feat: quality gate — validate all pipeline outputs (#623)

Validates pipeline outputs before saving. Rejects bad entries,
tracks quality scores per pipeline.

Checks:
- Training pairs: prompt/response non-empty, response != prompt
- Scene descriptions: all required fields, description min length
- Knowledge entries: no placeholders (TODO, FIXME), min length
- Prompt enhancement: rich > terse length, min 20 chars
- Adversary entries: id/family/prompt present, min prompt length
- SOUL.md compliance: no human life valuation, no weapon/child content
- Deduplication: detects duplicate entries by key fields

Features:
- Auto-reject bad outputs with reasons
- Quality score per entry (0.0-1.0)
- Batch mode (--dir) for processing all JSONL at once
- Stats tracking (~/.hermes/pipeline/quality_stats.json)
- --status to view historical quality metrics

Usage:
  python3 pipeline/quality_gate.py --input data.jsonl --type training_pairs
  python3 pipeline/quality_gate.py --dir pipeline/output/
  python3 pipeline/quality_gate.py --status

Closes #623

bin/agent-dispatch.sh

@@ -202,6 +202,19 @@ curl -s -X POST "{gitea_url}/api/v1/repos/{repo}/issues/{issue_num}/comments" \\
 REVIEW CHECKLIST BEFORE YOU PUSH:
 {review}
 
+COMMIT DISCIPLINE (CRITICAL):
+- Commit every 3-5 tool calls. Do NOT wait until the end.
+- After every meaningful file change: git add -A && git commit -m "WIP: <what changed>"
+- Before running any destructive command: commit current state first.
+- If you are unsure whether to commit: commit. WIP commits are safe. Lost work is not.
+- Never use --no-verify.
+- The auto-commit-guard is your safety net, but do not rely on it. Commit proactively.
+
+RECOVERY COMMANDS (if interrupted, another agent can resume):
+git log --oneline -10          # see your WIP commits
+git diff HEAD~1                # see what the last commit changed
+git status                     # see uncommitted work
+
 RULES:
 - Do not skip hooks with --no-verify.
 - Do not silently widen the scope.

bin/agent-loop.sh

@@ -161,6 +161,14 @@ run_worker() {
     CYCLE_END=$(date +%s)
     CYCLE_DURATION=$((CYCLE_END - CYCLE_START))
 
+    # --- Mid-session auto-commit: commit before timeout if work is dirty ---
+    cd "$worktree" 2>/dev/null || true
+    # Ensure auto-commit-guard is running
+    if ! pgrep -f "auto-commit-guard.sh" >/dev/null 2>&1; then
+      log "Starting auto-commit-guard daemon"
+      nohup bash "$(dirname "$0")/auto-commit-guard.sh" 120 "$WORKTREE_BASE"         >> "$LOG_DIR/auto-commit-guard.log" 2>&1 &
+    fi
+
     # Salvage
     cd "$worktree" 2>/dev/null || true
     DIRTY=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')

bin/auto-commit-guard.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# auto-commit-guard.sh — Background daemon that auto-commits uncommitted work
+#
+# Usage: auto-commit-guard.sh [interval_seconds] [worktree_base]
+#   auto-commit-guard.sh          # defaults: 120s, ~/worktrees
+#   auto-commit-guard.sh 60       # check every 60s
+#   auto-commit-guard.sh 180 ~/my-worktrees
+#
+# Scans all git repos under the worktree base for uncommitted changes.
+# If dirty for >= 1 check cycle, auto-commits with a WIP message.
+# Pushes unpushed commits so work is always recoverable from the remote.
+#
+# Also scans /tmp for orphaned agent workdirs on startup.
+
+set -uo pipefail
+
+INTERVAL="${1:-120}"
+WORKTREE_BASE="${2:-$HOME/worktrees}"
+LOG_DIR="$HOME/.hermes/logs"
+LOG="$LOG_DIR/auto-commit-guard.log"
+PIDFILE="$LOG_DIR/auto-commit-guard.pid"
+ORPHAN_SCAN_DONE="$LOG_DIR/.orphan-scan-done"
+
+mkdir -p "$LOG_DIR"
+
+# Single instance guard
+if [ -f "$PIDFILE" ]; then
+  old_pid=$(cat "$PIDFILE")
+  if kill -0 "$old_pid" 2>/dev/null; then
+    echo "auto-commit-guard already running (PID $old_pid)" >&2
+    exit 0
+  fi
+fi
+echo $$ > "$PIDFILE"
+trap 'rm -f "$PIDFILE"' EXIT
+
+log() {
+  echo "[$(date '+%Y-%m-%d %H:%M:%S')] AUTO-COMMIT: $*" >> "$LOG"
+}
+
+# --- Orphaned workdir scan (runs once on startup) ---
+scan_orphans() {
+  if [ -f "$ORPHAN_SCAN_DONE" ]; then
+    return 0
+  fi
+  log "Scanning /tmp for orphaned agent workdirs..."
+  local found=0
+  local rescued=0
+
+  for dir in /tmp/*-work-* /tmp/timmy-burn-* /tmp/tc-burn; do
+    [ -d "$dir" ] || continue
+    [ -d "$dir/.git" ] || continue
+
+    found=$((found + 1))
+    cd "$dir" 2>/dev/null || continue
+
+    local dirty
+    dirty=$(git status --porcelain 2>/dev/null | wc -l | tr -d " ")
+    if [ "${dirty:-0}" -gt 0 ]; then
+      local branch
+      branch=$(git branch --show-current 2>/dev/null || echo "orphan")
+      git add -A 2>/dev/null
+      if git commit -m "WIP: orphan rescue — $dirty file(s) auto-committed on $(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+Orphaned workdir detected at $dir.
+Branch: $branch
+Rescued by auto-commit-guard on startup." 2>/dev/null; then
+        rescued=$((rescued + 1))
+        log "RESCUED: $dir ($dirty files on branch $branch)"
+
+        # Try to push if remote exists
+        if git remote get-url origin >/dev/null 2>&1; then
+          git push -u origin "$branch" 2>/dev/null &&             log "PUSHED orphan rescue: $dir → $branch" ||             log "PUSH FAILED orphan rescue: $dir (no remote access)"
+        fi
+      fi
+    fi
+  done
+
+  log "Orphan scan complete: $found workdirs checked, $rescued rescued"
+  touch "$ORPHAN_SCAN_DONE"
+}
+
+# --- Main guard loop ---
+guard_cycle() {
+  local committed=0
+  local scanned=0
+
+  # Scan worktree base
+  if [ -d "$WORKTREE_BASE" ]; then
+    for dir in "$WORKTREE_BASE"/*/; do
+      [ -d "$dir" ] || continue
+      [ -d "$dir/.git" ] || continue
+
+      scanned=$((scanned + 1))
+      cd "$dir" 2>/dev/null || continue
+
+      local dirty
+      dirty=$(git status --porcelain 2>/dev/null | wc -l | tr -d " ")
+      [ "${dirty:-0}" -eq 0 ] && continue
+
+      local branch
+      branch=$(git branch --show-current 2>/dev/null || echo "detached")
+
+      git add -A 2>/dev/null
+      if git commit -m "WIP: auto-commit — $dirty file(s) on $branch
+
+Automated commit by auto-commit-guard at $(date -u +%Y-%m-%dT%H:%M:%SZ).
+Work preserved to prevent loss on crash." 2>/dev/null; then
+        committed=$((committed + 1))
+        log "COMMITTED: $dir ($dirty files, branch $branch)"
+
+        # Push to preserve remotely
+        if git remote get-url origin >/dev/null 2>&1; then
+          git push -u origin "$branch" 2>/dev/null &&             log "PUSHED: $dir → $branch" ||             log "PUSH FAILED: $dir (will retry next cycle)"
+        fi
+      fi
+    done
+  fi
+
+  # Also scan /tmp for agent workdirs
+  for dir in /tmp/*-work-*; do
+    [ -d "$dir" ] || continue
+    [ -d "$dir/.git" ] || continue
+
+    scanned=$((scanned + 1))
+    cd "$dir" 2>/dev/null || continue
+
+    local dirty
+    dirty=$(git status --porcelain 2>/dev/null | wc -l | tr -d " ")
+    [ "${dirty:-0}" -eq 0 ] && continue
+
+    local branch
+    branch=$(git branch --show-current 2>/dev/null || echo "detached")
+
+    git add -A 2>/dev/null
+    if git commit -m "WIP: auto-commit — $dirty file(s) on $branch
+
+Automated commit by auto-commit-guard at $(date -u +%Y-%m-%dT%H:%M:%SZ).
+Agent workdir preserved to prevent loss." 2>/dev/null; then
+      committed=$((committed + 1))
+      log "COMMITTED: $dir ($dirty files, branch $branch)"
+
+      if git remote get-url origin >/dev/null 2>&1; then
+        git push -u origin "$branch" 2>/dev/null &&           log "PUSHED: $dir → $branch" ||           log "PUSH FAILED: $dir (will retry next cycle)"
+      fi
+    fi
+  done
+
+  [ "$committed" -gt 0 ] && log "Cycle done: $scanned scanned, $committed committed"
+}
+
+# --- Entry point ---
+log "Starting auto-commit-guard (interval=${INTERVAL}s, worktree=${WORKTREE_BASE})"
+scan_orphans
+
+while true; do
+  guard_cycle
+  sleep "$INTERVAL"
+done

bin/glitch_patterns.py

@@ -0,0 +1,439 @@
+"""
+Glitch pattern definitions for 3D world anomaly detection.
+
+Defines known visual artifact categories commonly found in 3D web worlds,
+particularly The Matrix environments. Each pattern includes detection
+heuristics and severity ratings.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class GlitchSeverity(Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+
+class GlitchCategory(Enum):
+    FLOATING_ASSETS = "floating_assets"
+    Z_FIGHTING = "z_fighting"
+    MISSING_TEXTURES = "missing_textures"
+    CLIPPING = "clipping"
+    BROKEN_NORMALS = "broken_normals"
+    SHADOW_ARTIFACTS = "shadow_artifacts"
+    LIGHTMAP_ERRORS = "lightmap_errors"
+    LOD_POPPING = "lod_popping"
+    WATER_REFLECTION = "water_reflection"
+    SKYBOX_SEAM = "skybox_seam"
+
+    # Three.js-specific categories (ref: timmy-config#543)
+    SHADER_FAILURE = "shader_failure"
+    TEXTURE_PLACEHOLDER = "texture_placeholder"
+    UV_MAPPING_ERROR = "uv_mapping_error"
+    FRUSTUM_CULLING = "frustum_culling"
+    SHADOW_MAP_ARTIFACT = "shadow_map_artifact"
+    BLOOM_OVERFLOW = "bloom_overflow"
+
+
+@dataclass
+class GlitchPattern:
+    """Definition of a known glitch pattern with detection parameters."""
+    category: GlitchCategory
+    name: str
+    description: str
+    severity: GlitchSeverity
+    detection_prompts: list[str]
+    visual_indicators: list[str]
+    confidence_threshold: float = 0.6
+
+    def to_dict(self) -> dict:
+        return {
+            "category": self.category.value,
+            "name": self.name,
+            "description": self.description,
+            "severity": self.severity.value,
+            "detection_prompts": self.detection_prompts,
+            "visual_indicators": self.visual_indicators,
+            "confidence_threshold": self.confidence_threshold,
+        }
+
+
+# Known glitch patterns for Matrix 3D world scanning
+MATRIX_GLITCH_PATTERNS: list[GlitchPattern] = [
+    GlitchPattern(
+        category=GlitchCategory.FLOATING_ASSETS,
+        name="Floating Object",
+        description="Object not properly grounded or anchored to the scene geometry. "
+                    "Common in procedurally placed assets or after physics desync.",
+        severity=GlitchSeverity.HIGH,
+        detection_prompts=[
+            "Identify any objects that appear to float above the ground without support.",
+            "Look for furniture, props, or geometry suspended in mid-air with no visible attachment.",
+            "Check for objects whose shadows do not align with the surface below them.",
+        ],
+        visual_indicators=[
+            "gap between object base and surface",
+            "shadow detached from object",
+            "object hovering with no structural support",
+        ],
+        confidence_threshold=0.65,
+    ),
+    GlitchPattern(
+        category=GlitchCategory.Z_FIGHTING,
+        name="Z-Fighting Flicker",
+        description="Two coplanar surfaces competing for depth priority, causing "
+                    "visible flickering or shimmering textures.",
+        severity=GlitchSeverity.MEDIUM,
+        detection_prompts=[
+            "Look for surfaces that appear to shimmer, flicker, or show mixed textures.",
+            "Identify areas where two textures seem to overlap and compete for visibility.",
+            "Check walls, floors, or objects for surface noise or pattern interference.",
+        ],
+        visual_indicators=[
+            "shimmering surface",
+            "texture flicker between two patterns",
+            "noisy flat surfaces",
+            "moire-like patterns on planar geometry",
+        ],
+        confidence_threshold=0.55,
+    ),
+    GlitchPattern(
+        category=GlitchCategory.MISSING_TEXTURES,
+        name="Missing or Placeholder Texture",
+        description="A surface rendered with a fallback checkerboard, solid magenta, "
+                    "or the default engine placeholder texture.",
+        severity=GlitchSeverity.CRITICAL,
+        detection_prompts=[
+            "Look for bright magenta, checkerboard, or solid-color surfaces that look out of place.",
+            "Identify any surfaces that appear as flat untextured colors inconsistent with the scene.",
+            "Check for black, white, or magenta patches where detailed textures should be.",
+        ],
+        visual_indicators=[
+            "magenta/pink solid color surface",
+            "checkerboard pattern",
+            "flat single-color geometry",
+            "UV-debug texture visible",
+        ],
+        confidence_threshold=0.7,
+    ),
+    GlitchPattern(
+        category=GlitchCategory.CLIPPING,
+        name="Geometry Clipping",
+        description="Objects passing through each other or intersecting in physically "
+                    "impossible ways due to collision mesh errors.",
+        severity=GlitchSeverity.HIGH,
+        detection_prompts=[
+            "Look for objects that visibly pass through other objects (walls, floors, furniture).",
+            "Identify characters or props embedded inside geometry where they should not be.",
+            "Check for intersecting meshes where solid objects overlap unnaturally.",
+        ],
+        visual_indicators=[
+            "object passing through wall or floor",
+            "embedded geometry",
+            "overlapping solid meshes",
+            "character limb inside furniture",
+        ],
+        confidence_threshold=0.6,
+    ),
+    GlitchPattern(
+        category=GlitchCategory.BROKEN_NORMALS,
+        name="Broken Surface Normals",
+        description="Inverted or incorrect surface normals causing faces to appear "
+                    "inside-out, invisible from certain angles, or lit incorrectly.",
+        severity=GlitchSeverity.MEDIUM,
+        detection_prompts=[
+            "Look for surfaces that appear dark or black on one side while lit on the other.",
+            "Identify objects that seem to vanish when viewed from certain angles.",
+            "Check for inverted shading where lit areas should be in shadow.",
+        ],
+        visual_indicators=[
+            "dark/unlit face on otherwise lit model",
+            "invisible surface from one direction",
+            "inverted shadow gradient",
+            "inside-out appearance",
+        ],
+        confidence_threshold=0.5,
+    ),
+    GlitchPattern(
+        category=GlitchCategory.SHADOW_ARTIFACTS,
+        name="Shadow Artifact",
+        description="Broken, detached, or incorrectly rendered shadows that do not "
+                    "match the casting geometry or scene lighting.",
+        severity=GlitchSeverity.LOW,
+        detection_prompts=[
+            "Look for shadows that do not match the shape of nearby objects.",
+            "Identify shadow acne: banding or striped patterns on surfaces.",
+            "Check for floating shadows detached from any visible caster.",
+        ],
+        visual_indicators=[
+            "shadow shape mismatch",
+            "shadow acne bands",
+            "detached floating shadow",
+            "Peter Panning (shadow offset from base)",
+        ],
+        confidence_threshold=0.5,
+    ),
+    GlitchPattern(
+        category=GlitchCategory.LOD_POPPING,
+        name="LOD Transition Pop",
+        description="Visible pop-in when level-of-detail models switch abruptly, "
+                    "causing geometry or textures to change suddenly.",
+        severity=GlitchSeverity.LOW,
+        detection_prompts=[
+            "Look for areas where mesh detail changes abruptly at visible boundaries.",
+            "Identify objects that appear to morph or shift geometry suddenly.",
+            "Check for texture resolution changes that create visible seams.",
+        ],
+        visual_indicators=[
+            "visible mesh simplification boundary",
+            "texture resolution jump",
+            "geometry pop-in artifacts",
+        ],
+        confidence_threshold=0.45,
+    ),
+    GlitchPattern(
+        category=GlitchCategory.LIGHTMAP_ERRORS,
+        name="Lightmap Baking Error",
+        description="Incorrect or missing baked lighting causing dark spots, light "
+                    "leaks, or mismatched illumination on static geometry.",
+        severity=GlitchSeverity.MEDIUM,
+        detection_prompts=[
+            "Look for unusually dark patches on walls or ceilings that should be lit.",
+            "Identify bright light leaks through solid geometry seams.",
+            "Check for mismatched lighting between adjacent surfaces.",
+        ],
+        visual_indicators=[
+            "dark splotch on lit surface",
+            "bright line at geometry seam",
+            "lighting discontinuity between adjacent faces",
+        ],
+        confidence_threshold=0.5,
+    ),
+    GlitchPattern(
+        category=GlitchCategory.WATER_REFLECTION,
+        name="Water/Reflection Error",
+        description="Incorrect reflections, missing water surfaces, or broken "
+                    "reflection probe assignments.",
+        severity=GlitchSeverity.MEDIUM,
+        detection_prompts=[
+            "Look for reflections that do not match the surrounding environment.",
+            "Identify water surfaces that appear solid or incorrectly rendered.",
+            "Check for mirror surfaces showing wrong scene geometry.",
+        ],
+        visual_indicators=[
+            "reflection mismatch",
+            "solid water surface",
+            "incorrect environment map",
+        ],
+        confidence_threshold=0.5,
+    ),
+    GlitchPattern(
+        category=GlitchCategory.SKYBOX_SEAM,
+        name="Skybox Seam",
+        description="Visible seams or color mismatches at the edges of skybox cubemap faces.",
+        severity=GlitchSeverity.LOW,
+        detection_prompts=[
+            "Look at the edges of the sky for visible seams or color shifts.",
+            "Identify discontinuities where skybox faces meet.",
+            "Check for texture stretching at skybox corners.",
+        ],
+        visual_indicators=[
+            "visible line in sky",
+            "color discontinuity at sky edge",
+            "sky texture seam",
+        ],
+        confidence_threshold=0.45,
+    ),
+
+    # --- Three.js-Specific Glitch Patterns (ref: timmy-config#543) ---
+    GlitchPattern(
+        category=GlitchCategory.SHADER_FAILURE,
+        name="Shader Compilation Failure",
+        description="Three.js shader failed to compile, rendering the material as solid black. "
+                    "Common when custom ShaderMaterial has syntax errors or missing uniforms.",
+        severity=GlitchSeverity.CRITICAL,
+        detection_prompts=[
+            "Look for objects or surfaces rendered as pure black (#000000) that should have visible textures or materials.",
+            "Identify geometry that appears completely dark while surrounding objects are normally lit.",
+            "Check for objects where the material seems to 'absorb all light' — flat black with no shading gradient.",
+        ],
+        visual_indicators=[
+            "solid black object with no shading",
+            "geometry rendered as silhouette",
+            "material appears to absorb light entirely",
+            "black patch inconsistent with scene lighting",
+        ],
+        confidence_threshold=0.7,
+    ),
+    GlitchPattern(
+        category=GlitchCategory.TEXTURE_PLACEHOLDER,
+        name="Three.js Texture Not Loaded",
+        description="Three.js failed to load the texture asset, rendering a 1x1 white pixel "
+                    "stretched across the entire surface. Distinguished from missing-texture by "
+                    "the uniform white/grey appearance rather than magenta.",
+        severity=GlitchSeverity.CRITICAL,
+        detection_prompts=[
+            "Look for surfaces that are uniformly white or light grey with no texture detail, even on large geometry.",
+            "Identify objects where the texture appears as a single solid color stretched across complex UVs.",
+            "Check for surfaces that look 'blank' or 'unloaded' — flat white/grey where detail should exist.",
+        ],
+        visual_indicators=[
+            "uniform white or light grey surface",
+            "no texture detail on large geometry",
+            "stretched single-color appearance",
+            "1x1 pixel placeholder stretched to fill UV space",
+        ],
+        confidence_threshold=0.65,
+    ),
+    GlitchPattern(
+        category=GlitchCategory.UV_MAPPING_ERROR,
+        name="BufferGeometry UV Mapping Error",
+        description="Three.js BufferGeometry has incorrect UV coordinates, causing textures to "
+                    "appear stretched, compressed, or mapped to the wrong faces.",
+        severity=GlitchSeverity.HIGH,
+        detection_prompts=[
+            "Look for textures that appear dramatically stretched in one direction on specific faces.",
+            "Identify surfaces where the texture pattern is distorted but other nearby surfaces look correct.",
+            "Check for faces where the texture seems 'smeared' or mapped with incorrect aspect ratio.",
+        ],
+        visual_indicators=[
+            "texture stretching on specific faces",
+            "distorted pattern on geometry",
+            "smeared texture appearance",
+            "aspect ratio mismatch between texture and surface",
+        ],
+        confidence_threshold=0.6,
+    ),
+    GlitchPattern(
+        category=GlitchCategory.FRUSTUM_CULLING,
+        name="Frustum Culling Artifact",
+        description="Three.js frustum culling incorrectly marks objects as outside the camera "
+                    "frustum, causing them to pop in/out of existence at screen edges.",
+        severity=GlitchSeverity.MEDIUM,
+        detection_prompts=[
+            "Look for objects that are partially visible at the edge of the frame — half-rendered or cut off unnaturally.",
+            "Identify geometry that seems to 'pop' into existence as the view angle changes.",
+            "Check screen edges for objects that appear suddenly rather than smoothly entering the viewport.",
+        ],
+        visual_indicators=[
+            "half-visible object at screen edge",
+            "object popping into frame",
+            "abrupt appearance of geometry",
+            "bounding box visible but mesh missing",
+        ],
+        confidence_threshold=0.55,
+    ),
+    GlitchPattern(
+        category=GlitchCategory.SHADOW_MAP_ARTIFACT,
+        name="Shadow Map Resolution Artifact",
+        description="Three.js shadow map has insufficient resolution, causing pixelated, "
+                    "blocky shadows with visible texel edges instead of smooth shadow gradients.",
+        severity=GlitchSeverity.MEDIUM,
+        detection_prompts=[
+            "Look for shadows with visible blocky or pixelated edges instead of smooth gradients.",
+            "Identify shadow maps where individual texels (texture pixels) are clearly visible.",
+            "Check for shadows that appear as jagged stair-stepped patterns rather than soft edges.",
+        ],
+        visual_indicators=[
+            "blocky shadow edges",
+            "visible texel grid in shadows",
+            "stair-stepped shadow boundary",
+            "pixelated shadow gradient",
+        ],
+        confidence_threshold=0.55,
+    ),
+    GlitchPattern(
+        category=GlitchCategory.BLOOM_OVERFLOW,
+        name="Post-Processing Bloom Overflow",
+        description="Three.js UnrealBloomPass or similar post-processing bloom effect is too "
+                    "intense, causing bright areas to bleed glow into surrounding geometry.",
+        severity=GlitchSeverity.LOW,
+        detection_prompts=[
+            "Look for bright areas that have an unusually large, soft glow bleeding into adjacent surfaces.",
+            "Identify scenes where light sources appear to have a 'halo' that extends beyond physical plausibility.",
+            "Check for bright objects whose glow color bleeds onto nearby unrelated geometry.",
+        ],
+        visual_indicators=[
+            "excessive glow bleeding from bright surfaces",
+            "halo around light sources",
+            "bloom color tinting adjacent geometry",
+            "glow bleeding beyond object boundaries",
+        ],
+        confidence_threshold=0.5,
+    ),
+]
+
+
+def get_patterns_by_severity(min_severity: GlitchSeverity) -> list[GlitchPattern]:
+    """Return patterns at or above the given severity level."""
+    severity_order = [
+        GlitchSeverity.INFO,
+        GlitchSeverity.LOW,
+        GlitchSeverity.MEDIUM,
+        GlitchSeverity.HIGH,
+        GlitchSeverity.CRITICAL,
+    ]
+    min_idx = severity_order.index(min_severity)
+    return [p for p in MATRIX_GLITCH_PATTERNS if severity_order.index(p.severity) >= min_idx]
+
+
+def get_pattern_by_category(category: GlitchCategory) -> Optional[GlitchPattern]:
+    """Return the pattern definition for a specific category."""
+    for p in MATRIX_GLITCH_PATTERNS:
+        if p.category == category:
+            return p
+    return None
+
+
+def build_vision_prompt(patterns: list[GlitchPattern] | None = None) -> str:
+    """Build a composite vision analysis prompt from pattern definitions."""
+    if patterns is None:
+        patterns = MATRIX_GLITCH_PATTERNS
+
+    sections = []
+    for p in patterns:
+        prompt_text = " ".join(p.detection_prompts)
+        indicators = ", ".join(p.visual_indicators)
+        sections.append(
+            f"[{p.category.value.upper()}] {p.name} (severity: {p.severity.value})\n"
+            f"  {p.description}\n"
+            f"  Look for: {prompt_text}\n"
+            f"  Visual indicators: {indicators}"
+        )
+
+    return (
+        "Analyze this 3D world screenshot for visual glitches and artifacts. "
+        "For each detected issue, report the category, description of what you see, "
+        "approximate location in the image (x%, y%), and confidence (0.0-1.0).\n\n"
+        "Known glitch patterns to check:\n\n" + "\n\n".join(sections)
+    )
+
+
+
+# Three.js-specific category set for filtering (ref: timmy-config#543)
+THREEJS_CATEGORIES = {
+    GlitchCategory.SHADER_FAILURE,
+    GlitchCategory.TEXTURE_PLACEHOLDER,
+    GlitchCategory.UV_MAPPING_ERROR,
+    GlitchCategory.FRUSTUM_CULLING,
+    GlitchCategory.SHADOW_MAP_ARTIFACT,
+    GlitchCategory.BLOOM_OVERFLOW,
+}
+
+
+def get_threejs_patterns() -> list[GlitchPattern]:
+    """Return only Three.js-specific glitch patterns."""
+    return [p for p in MATRIX_GLITCH_PATTERNS if p.category in THREEJS_CATEGORIES]
+
+
+if __name__ == "__main__":
+    import json
+    print(f"Loaded {len(MATRIX_GLITCH_PATTERNS)} glitch patterns:\n")
+    for p in MATRIX_GLITCH_PATTERNS:
+        print(f"  [{p.severity.value:8s}] {p.category.value}: {p.name}")
+    print(f"\nVision prompt preview:\n{build_vision_prompt()[:500]}...")

bin/matrix_glitch_detector.py

@@ -0,0 +1,586 @@
+#!/usr/bin/env python3
+"""
+Matrix 3D World Glitch Detector
+
+Scans a 3D web world for visual artifacts using browser automation
+and vision AI analysis. Produces structured glitch reports.
+
+Usage:
+    python matrix_glitch_detector.py <url> [--angles 4] [--output report.json]
+    python matrix_glitch_detector.py --demo  # Run with synthetic test data
+
+Ref: timmy-config#491, timmy-config#543
+"""
+
+import argparse
+import base64
+import json
+import os
+import sys
+import time
+import uuid
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+# Add parent for glitch_patterns import
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from glitch_patterns import (
+    GlitchCategory,
+    GlitchPattern,
+    GlitchSeverity,
+    MATRIX_GLITCH_PATTERNS,
+    build_vision_prompt,
+    get_patterns_by_severity,
+    get_threejs_patterns,
+)
+
+
+@dataclass
+class DetectedGlitch:
+    """A single detected glitch with metadata."""
+    id: str
+    category: str
+    name: str
+    description: str
+    severity: str
+    confidence: float
+    location_x: Optional[float] = None  # percentage across image
+    location_y: Optional[float] = None  # percentage down image
+    screenshot_index: int = 0
+    screenshot_angle: str = "front"
+    timestamp: str = ""
+
+    def __post_init__(self):
+        if not self.timestamp:
+            self.timestamp = datetime.now(timezone.utc).isoformat()
+
+
+@dataclass
+class ScanResult:
+    """Complete scan result for a 3D world URL."""
+    scan_id: str
+    url: str
+    timestamp: str
+    total_screenshots: int
+    angles_captured: list[str]
+    glitches: list[dict] = field(default_factory=list)
+    summary: dict = field(default_factory=dict)
+    metadata: dict = field(default_factory=dict)
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(asdict(self), indent=indent)
+
+
+def generate_scan_angles(num_angles: int) -> list[dict]:
+    """Generate camera angle configurations for multi-angle scanning.
+
+    Returns a list of dicts with yaw/pitch/label for browser camera control.
+    """
+    base_angles = [
+        {"yaw": 0, "pitch": 0, "label": "front"},
+        {"yaw": 90, "pitch": 0, "label": "right"},
+        {"yaw": 180, "pitch": 0, "label": "back"},
+        {"yaw": 270, "pitch": 0, "label": "left"},
+        {"yaw": 0, "pitch": -30, "label": "front_low"},
+        {"yaw": 45, "pitch": -15, "label": "front_right_low"},
+        {"yaw": 0, "pitch": 30, "label": "front_high"},
+        {"yaw": 45, "pitch": 0, "label": "front_right"},
+    ]
+
+    if num_angles <= len(base_angles):
+        return base_angles[:num_angles]
+    return base_angles + [
+        {"yaw": i * (360 // num_angles), "pitch": 0, "label": f"angle_{i}"}
+        for i in range(len(base_angles), num_angles)
+    ]
+
+
+def capture_screenshots(url: str, angles: list[dict], output_dir: Path) -> list[Path]:
+    """Capture screenshots of a 3D web world from multiple angles.
+
+    Uses browser_vision tool when available; falls back to placeholder generation
+    for testing and environments without browser access.
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
+    screenshots = []
+
+    for i, angle in enumerate(angles):
+        filename = output_dir / f"screenshot_{i:03d}_{angle['label']}.png"
+
+        # Attempt browser-based capture via browser_vision
+        try:
+            result = _browser_capture(url, angle, filename)
+            if result:
+                screenshots.append(filename)
+                continue
+        except Exception:
+            pass
+
+        # Generate placeholder screenshot for offline/test scenarios
+        _generate_placeholder_screenshot(filename, angle)
+        screenshots.append(filename)
+
+    return screenshots
+
+
+def _browser_capture(url: str, angle: dict, output_path: Path) -> bool:
+    """Capture a screenshot via browser automation.
+
+    This is a stub that delegates to the browser_vision tool when run
+    in an environment that provides it. In CI or offline mode, returns False.
+    """
+    # Check if browser_vision is available via environment
+    bv_script = os.environ.get("BROWSER_VISION_SCRIPT")
+    if bv_script and Path(bv_script).exists():
+        import subprocess
+        cmd = [
+            sys.executable, bv_script,
+            "--url", url,
+            "--screenshot", str(output_path),
+            "--rotate-yaw", str(angle["yaw"]),
+            "--rotate-pitch", str(angle["pitch"]),
+        ]
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+        return proc.returncode == 0 and output_path.exists()
+    return False
+
+
+def _generate_placeholder_screenshot(path: Path, angle: dict):
+    """Generate a minimal 1x1 PNG as a placeholder for testing."""
+    # Minimal valid PNG (1x1 transparent pixel)
+    png_data = (
+        b"\x89PNG\r\n\x1a\n"
+        b"\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01"
+        b"\x08\x06\x00\x00\x00\x1f\x15\xc4\x89"
+        b"\x00\x00\x00\nIDATx\x9cc\x00\x01\x00\x00\x05\x00\x01"
+        b"\r\n\xb4\x00\x00\x00\x00IEND\xaeB`\x82"
+    )
+    path.write_bytes(png_data)
+
+
+def analyze_with_vision(
+    screenshot_paths: list[Path],
+    angles: list[dict],
+    patterns: list[GlitchPattern] | None = None,
+) -> list[DetectedGlitch]:
+    """Send screenshots to vision AI for glitch analysis.
+
+    In environments with a vision model available, sends each screenshot
+    with the composite detection prompt. Otherwise returns simulated results.
+    """
+    if patterns is None:
+        patterns = MATRIX_GLITCH_PATTERNS
+
+    prompt = build_vision_prompt(patterns)
+    glitches = []
+
+    for i, (path, angle) in enumerate(zip(screenshot_paths, angles)):
+        # Attempt vision analysis
+        detected = _vision_analyze_image(path, prompt, i, angle["label"])
+        glitches.extend(detected)
+
+    return glitches
+
+
+def _vision_analyze_image(
+    image_path: Path,
+    prompt: str,
+    screenshot_index: int,
+    angle_label: str,
+) -> list[DetectedGlitch]:
+    """Analyze a single screenshot with vision AI.
+
+    Uses the vision_analyze tool when available; returns empty list otherwise.
+    """
+    # Check for vision API configuration
+    api_key = os.environ.get("VISION_API_KEY") or os.environ.get("OPENAI_API_KEY")
+    api_base = os.environ.get("VISION_API_BASE", "https://api.openai.com/v1")
+
+    if api_key:
+        try:
+            return _call_vision_api(
+                image_path, prompt, screenshot_index, angle_label, api_key, api_base
+            )
+        except Exception as e:
+            print(f"  [!] Vision API error for {image_path.name}: {e}", file=sys.stderr)
+
+    # No vision backend available
+    return []
+
+
+def _call_vision_api(
+    image_path: Path,
+    prompt: str,
+    screenshot_index: int,
+    angle_label: str,
+    api_key: str,
+    api_base: str,
+) -> list[DetectedGlitch]:
+    """Call a vision API (OpenAI-compatible) for image analysis."""
+    import urllib.request
+    import urllib.error
+
+    image_data = base64.b64encode(image_path.read_bytes()).decode()
+
+    payload = json.dumps({
+        "model": os.environ.get("VISION_MODEL", "gpt-4o"),
+        "messages": [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": prompt},
+                    {
+                        "type": "image_url",
+                        "image_url": {
+                            "url": f"data:image/png;base64,{image_data}",
+                            "detail": "high",
+                        },
+                    },
+                ],
+            }
+        ],
+        "max_tokens": 4096,
+    }).encode()
+
+    req = urllib.request.Request(
+        f"{api_base}/chat/completions",
+        data=payload,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {api_key}",
+        },
+    )
+
+    with urllib.request.urlopen(req, timeout=60) as resp:
+        result = json.loads(resp.read())
+
+    content = result["choices"][0]["message"]["content"]
+    return _parse_vision_response(content, screenshot_index, angle_label)
+
+
+def _add_glitch_from_dict(
+    item: dict,
+    glitches: list[DetectedGlitch],
+    screenshot_index: int,
+    angle_label: str,
+):
+    """Convert a dict from vision API response into a DetectedGlitch."""
+    cat = item.get("category", item.get("type", "unknown"))
+    conf = float(item.get("confidence", item.get("score", 0.5)))
+
+    glitch = DetectedGlitch(
+        id=str(uuid.uuid4())[:8],
+        category=cat,
+        name=item.get("name", item.get("label", cat)),
+        description=item.get("description", item.get("detail", "")),
+        severity=item.get("severity", _infer_severity(cat, conf)),
+        confidence=conf,
+        location_x=item.get("location_x", item.get("x")),
+        location_y=item.get("location_y", item.get("y")),
+        screenshot_index=screenshot_index,
+        screenshot_angle=angle_label,
+    )
+    glitches.append(glitch)
+
+
+def _parse_vision_response(
+    text: str, screenshot_index: int, angle_label: str
+) -> list[DetectedGlitch]:
+    """Parse vision AI response into structured glitch detections."""
+    glitches = []
+
+    # Try to extract JSON from the response
+    json_blocks = []
+    in_json = False
+    json_buf = []
+
+    for line in text.split("\n"):
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            if in_json and json_buf:
+                try:
+                    json_blocks.append(json.loads("\n".join(json_buf)))
+                except json.JSONDecodeError:
+                    pass
+                json_buf = []
+            in_json = not in_json
+            continue
+        if in_json:
+            json_buf.append(line)
+
+    # Flush any remaining buffer
+    if in_json and json_buf:
+        try:
+            json_blocks.append(json.loads("\n".join(json_buf)))
+        except json.JSONDecodeError:
+            pass
+
+    # Also try parsing the entire response as JSON
+    try:
+        parsed = json.loads(text)
+        if isinstance(parsed, list):
+            json_blocks.extend(parsed)
+        elif isinstance(parsed, dict):
+            if "glitches" in parsed:
+                json_blocks.extend(parsed["glitches"])
+            elif "detections" in parsed:
+                json_blocks.extend(parsed["detections"])
+            else:
+                json_blocks.append(parsed)
+    except json.JSONDecodeError:
+        pass
+
+    for item in json_blocks:
+        # Flatten arrays of detections
+        if isinstance(item, list):
+            for sub in item:
+                if isinstance(sub, dict):
+                    _add_glitch_from_dict(sub, glitches, screenshot_index, angle_label)
+        elif isinstance(item, dict):
+            _add_glitch_from_dict(item, glitches, screenshot_index, angle_label)
+
+    return glitches
+
+
+def _infer_severity(category: str, confidence: float) -> str:
+    """Infer severity from category and confidence when not provided."""
+    critical_cats = {"missing_textures", "clipping", "shader_failure", "texture_placeholder"}
+    high_cats = {"floating_assets", "broken_normals", "uv_mapping_error"}
+    medium_cats = {"frustum_culling", "shadow_map_artifact"}
+
+    cat_lower = category.lower()
+    if any(c in cat_lower for c in critical_cats):
+        return "critical" if confidence > 0.7 else "high"
+    if any(c in cat_lower for c in high_cats):
+        return "high" if confidence > 0.7 else "medium"
+    if any(c in cat_lower for c in medium_cats):
+        return "medium" if confidence > 0.6 else "low"
+    return "medium" if confidence > 0.6 else "low"
+
+
+def build_report(
+    url: str,
+    angles: list[dict],
+    screenshots: list[Path],
+    glitches: list[DetectedGlitch],
+) -> ScanResult:
+    """Build the final structured scan report."""
+    severity_counts = {}
+    category_counts = {}
+
+    for g in glitches:
+        severity_counts[g.severity] = severity_counts.get(g.severity, 0) + 1
+        category_counts[g.category] = category_counts.get(g.category, 0) + 1
+
+    report = ScanResult(
+        scan_id=str(uuid.uuid4()),
+        url=url,
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        total_screenshots=len(screenshots),
+        angles_captured=[a["label"] for a in angles],
+        glitches=[asdict(g) for g in glitches],
+        summary={
+            "total_glitches": len(glitches),
+            "by_severity": severity_counts,
+            "by_category": category_counts,
+            "highest_severity": max(severity_counts.keys(), default="none"),
+            "clean_screenshots": sum(
+                1
+                for i in range(len(screenshots))
+                if not any(g.screenshot_index == i for g in glitches)
+            ),
+        },
+        metadata={
+            "detector_version": "0.2.0",
+            "pattern_count": len(MATRIX_GLITCH_PATTERNS),
+            "reference": "timmy-config#491, timmy-config#543",
+        },
+    )
+
+    return report
+
+
+def run_demo(output_path: Optional[Path] = None) -> ScanResult:
+    """Run a demonstration scan with simulated detections."""
+    print("[*] Running Matrix glitch detection demo...")
+
+    url = "https://matrix.example.com/world/alpha"
+    angles = generate_scan_angles(4)
+    screenshots_dir = Path("/tmp/matrix_glitch_screenshots")
+
+    print(f"[*] Capturing {len(angles)} screenshots from: {url}")
+    screenshots = capture_screenshots(url, angles, screenshots_dir)
+    print(f"[*] Captured {len(screenshots)} screenshots")
+
+    # Simulate detections for demo
+    demo_glitches = [
+        DetectedGlitch(
+            id=str(uuid.uuid4())[:8],
+            category="floating_assets",
+            name="Floating Chair",
+            description="Office chair floating 0.3m above floor in sector 7",
+            severity="high",
+            confidence=0.87,
+            location_x=35.2,
+            location_y=62.1,
+            screenshot_index=0,
+            screenshot_angle="front",
+        ),
+        DetectedGlitch(
+            id=str(uuid.uuid4())[:8],
+            category="z_fighting",
+            name="Wall Texture Flicker",
+            description="Z-fighting between wall panel and decorative overlay",
+            severity="medium",
+            confidence=0.72,
+            location_x=58.0,
+            location_y=40.5,
+            screenshot_index=1,
+            screenshot_angle="right",
+        ),
+        DetectedGlitch(
+            id=str(uuid.uuid4())[:8],
+            category="missing_textures",
+            name="Placeholder Texture",
+            description="Bright magenta surface on door frame — missing asset reference",
+            severity="critical",
+            confidence=0.95,
+            location_x=72.3,
+            location_y=28.8,
+            screenshot_index=2,
+            screenshot_angle="back",
+        ),
+        DetectedGlitch(
+            id=str(uuid.uuid4())[:8],
+            category="clipping",
+            name="Desk Through Wall",
+            description="Desk corner clipping through adjacent wall geometry",
+            severity="high",
+            confidence=0.81,
+            location_x=15.0,
+            location_y=55.0,
+            screenshot_index=3,
+            screenshot_angle="left",
+        ),
+        DetectedGlitch(
+            id=str(uuid.uuid4())[:8],
+            category="shader_failure",
+            name="Black Material on Portal Frame",
+            description="Portal frame rendered as solid black — shader compilation failed (missing uniform u_time)",
+            severity="critical",
+            confidence=0.91,
+            location_x=45.0,
+            location_y=30.0,
+            screenshot_index=0,
+            screenshot_angle="front",
+        ),
+        DetectedGlitch(
+            id=str(uuid.uuid4())[:8],
+            category="shadow_map_artifact",
+            name="Pixelated Character Shadow",
+            description="Character shadow shows visible texel grid — shadow map resolution too low (512x512)",
+            severity="medium",
+            confidence=0.78,
+            location_x=52.0,
+            location_y=75.0,
+            screenshot_index=1,
+            screenshot_angle="right",
+        ),
+    ]
+
+    print(f"[*] Detected {len(demo_glitches)} glitches")
+    report = build_report(url, angles, screenshots, demo_glitches)
+
+    if output_path:
+        output_path.write_text(report.to_json())
+        print(f"[*] Report saved to: {output_path}")
+
+    return report
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Matrix 3D World Glitch Detector — scan for visual artifacts",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s https://matrix.example.com/world/alpha
+  %(prog)s https://matrix.example.com/world/alpha --angles 8 --output report.json
+  %(prog)s --demo
+        """,
+    )
+    parser.add_argument("url", nargs="?", help="URL of the 3D world to scan")
+    parser.add_argument(
+        "--angles", type=int, default=4, help="Number of camera angles to capture (default: 4)"
+    )
+    parser.add_argument("--output", "-o", type=str, help="Output file path for JSON report")
+    parser.add_argument("--demo", action="store_true", help="Run demo with simulated data")
+    parser.add_argument(
+        "--min-severity",
+        choices=["info", "low", "medium", "high", "critical"],
+        default="info",
+        help="Minimum severity to include in report",
+    )
+    parser.add_argument("--verbose", "-v", action="store_true", help="Verbose output")
+    parser.add_argument(
+        "--threejs",
+        action="store_true",
+        help="Focus on Three.js-specific glitch patterns only (shader, texture, UV, culling, shadow, bloom)",
+    )
+
+    args = parser.parse_args()
+
+    if args.demo:
+        output = Path(args.output) if args.output else Path("glitch_report_demo.json")
+        report = run_demo(output)
+        print(f"\n=== Scan Summary ===")
+        print(f"URL: {report.url}")
+        print(f"Screenshots: {report.total_screenshots}")
+        print(f"Glitches found: {report.summary['total_glitches']}")
+        print(f"By severity: {report.summary['by_severity']}")
+        return
+
+    if not args.url:
+        parser.error("URL required (or use --demo)")
+
+    scan_id = str(uuid.uuid4())[:8]
+    print(f"[*] Matrix Glitch Detector — Scan {scan_id}")
+    print(f"[*] Target: {args.url}")
+
+    # Generate camera angles
+    angles = generate_scan_angles(args.angles)
+    print(f"[*] Capturing {len(angles)} screenshots...")
+
+    # Capture screenshots
+    screenshots_dir = Path(f"/tmp/matrix_glitch_{scan_id}")
+    screenshots = capture_screenshots(args.url, angles, screenshots_dir)
+    print(f"[*] Captured {len(screenshots)} screenshots")
+
+    # Filter patterns by severity and type
+    min_sev = GlitchSeverity(args.min_severity)
+    patterns = get_patterns_by_severity(min_sev)
+    if args.threejs:
+        threejs_patterns = get_threejs_patterns()
+        patterns = [p for p in patterns if p in threejs_patterns]
+        print(f"[*] Three.js-focused mode: {len(patterns)} patterns")
+
+    # Analyze with vision AI
+    print(f"[*] Analyzing with vision AI ({len(patterns)} patterns)...")
+    glitches = analyze_with_vision(screenshots, angles, patterns)
+
+    # Build and save report
+    report = build_report(args.url, angles, screenshots, glitches)
+
+    if args.output:
+        Path(args.output).write_text(report.to_json())
+        print(f"[*] Report saved: {args.output}")
+    else:
+        print(report.to_json())
+
+    print(f"\n[*] Done — {len(glitches)} glitches detected")
+
+
+if __name__ == "__main__":
+    main()

bin/nostr-agent-demo.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 """
 Full Nostr agent-to-agent communication demo - FINAL WORKING
 """

bin/pane-watchdog.sh

@@ -0,0 +1,514 @@
+#!/usr/bin/env bash
+# pane-watchdog.sh — Detect stuck/dead tmux panes and auto-restart them
+#
+# Tracks output hash per pane across cycles. If a pane's captured output
+# hasn't changed for STUCK_CYCLES consecutive checks, the pane is STUCK.
+# Dead panes (PID gone) are also detected.
+#
+# On STUCK/DEAD:
+#   1. Kill the pane
+#   2. Attempt restart with --resume (session ID from manifest)
+#   3. Fallback: fresh prompt with last known task from logs
+#
+# State file: ~/.hermes/pane-state.json
+# Log: ~/.hermes/logs/pane-watchdog.log
+#
+# Usage:
+#   pane-watchdog.sh              # One-shot check all sessions
+#   pane-watchdog.sh --daemon     # Run every CHECK_INTERVAL seconds
+#   pane-watchdog.sh --status     # Print current pane state
+#   pane-watchdog.sh --session NAME  # Check only one session
+#
+# Issue: timmy-config #515
+
+set -uo pipefail
+export PATH="/opt/homebrew/bin:$HOME/.local/bin:$HOME/.hermes/bin:/usr/local/bin:$PATH"
+
+# === CONFIG ===
+STATE_FILE="${PANE_STATE_FILE:-$HOME/.hermes/pane-state.json}"
+LOG_FILE="${PANE_WATCHDOG_LOG:-$HOME/.hermes/logs/pane-watchdog.log}"
+CHECK_INTERVAL="${PANE_CHECK_INTERVAL:-120}"  # seconds between cycles
+STUCK_CYCLES=2                                # unchanged cycles before STUCK
+MAX_RESTART_ATTEMPTS=3                        # per pane per hour
+RESTART_COOLDOWN=3600                         # seconds between escalation alerts
+CAPTURE_LINES=40                              # lines of output to hash
+
+# Sessions to monitor (all if empty)
+MONITOR_SESSIONS="${PANE_WATCHDOG_SESSIONS:-}"
+
+mkdir -p "$(dirname "$STATE_FILE")" "$(dirname "$LOG_FILE")"
+
+log() {
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >> "$LOG_FILE"
+}
+
+# === HELPERS ===
+
+# Capture last N lines of pane output and hash them
+capture_pane_hash() {
+    local target="$1"
+    local output
+    output=$(tmux capture-pane -t "$target" -p -S "-${CAPTURE_LINES}" 2>/dev/null || echo "DEAD")
+    echo -n "$output" | shasum -a 256 | cut -d' ' -f1
+}
+
+# Check if pane PID is alive
+pane_pid_alive() {
+    local target="$1"
+    local pid
+    pid=$(tmux list-panes -t "$target" -F '#{pane_pid}' 2>/dev/null | head -1 || echo "")
+    if [ -z "$pid" ]; then
+        return 1  # pane doesn't exist
+    fi
+    kill -0 "$pid" 2>/dev/null
+}
+
+# Get pane start command
+pane_start_command() {
+    local target="$1"
+    tmux list-panes -t "$target" -F '#{pane_start_command}' 2>/dev/null | head -1 || echo "unknown"
+}
+
+# Get the pane's current running command (child process)
+pane_current_command() {
+    local target="$1"
+    tmux list-panes -t "$target" -F '#{pane_current_command}' 2>/dev/null || echo "unknown"
+}
+
+# Only restart panes running hermes/agent commands (not zsh, python3 repls, etc.)
+is_restartable() {
+    local cmd="$1"
+    case "$cmd" in
+        hermes|*hermes*|*agent*|*timmy*|*kimi*|*claude-loop*|*gemini-loop*)
+            return 0
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+}
+
+# Get session ID from hermes manifest if available
+get_hermes_session_id() {
+    local session_name="$1"
+    local manifest="$HOME/.hermes/sessions/${session_name}/manifest.json"
+    if [ -f "$manifest" ]; then
+        python3 -c "
+import json, sys
+try:
+    m = json.load(open('$manifest'))
+    print(m.get('session_id', m.get('id', '')))
+except: pass
+" 2>/dev/null || echo ""
+    else
+        echo ""
+    fi
+}
+
+# Get last task from pane logs
+get_last_task() {
+    local session_name="$1"
+    local log_dir="$HOME/.hermes/logs"
+    # Find the most recent log for this session
+    local log_file
+    log_file=$(find "$log_dir" -name "*${session_name}*" -type f -mtime -1 2>/dev/null | sort -r | head -1)
+    if [ -n "$log_file" ] && [ -f "$log_file" ]; then
+        # Extract last user prompt or task description
+        grep -i "task:\|prompt:\|issue\|working on" "$log_file" 2>/dev/null | tail -1 | sed 's/.*[:>] *//' | head -c 200
+    fi
+}
+
+# Restart a pane with a fresh shell/command
+restart_pane() {
+    local target="$1"
+    local session_name="${target%%:*}"
+    local session_id last_task cmd
+
+    log "RESTART: Attempting to restart $target"
+
+    # Kill existing pane
+    tmux kill-pane -t "$target" 2>/dev/null || true
+    sleep 1
+
+    # Try --resume with session ID
+    session_id=$(get_hermes_session_id "$session_name")
+    if [ -n "$session_id" ]; then
+        log "RESTART: Trying --resume with session $session_id"
+        tmux split-window -t "$session_name" -d \
+            "hermes chat --resume '$session_id' 2>&1 | tee -a '$HOME/.hermes/logs/${session_name}-restart.log'"
+        sleep 2
+        if pane_pid_alive "${session_name}:1" 2>/dev/null; then
+            log "RESTART: Success with --resume"
+            return 0
+        fi
+    fi
+
+    # Fallback: fresh prompt
+    last_task=$(get_last_task "$session_name")
+    if [ -n "$last_task" ]; then
+        log "RESTART: Fallback — fresh prompt with task: $last_task"
+        tmux split-window -t "$session_name" -d \
+            "echo 'Watchdog restart — last task: $last_task' && hermes chat 2>&1 | tee -a '$HOME/.hermes/logs/${session_name}-restart.log'"
+    else
+        log "RESTART: Fallback — fresh hermes chat"
+        tmux split-window -t "$session_name" -d \
+            "hermes chat 2>&1 | tee -a '$HOME/.hermes/logs/${session_name}-restart.log'"
+    fi
+
+    sleep 2
+    if pane_pid_alive "${session_name}:1" 2>/dev/null; then
+        log "RESTART: Fallback restart succeeded"
+        return 0
+    else
+        log "RESTART: FAILED to restart $target"
+        return 1
+    fi
+}
+
+# === STATE MANAGEMENT ===
+
+read_state() {
+    if [ -f "$STATE_FILE" ]; then
+        cat "$STATE_FILE"
+    else
+        echo "{}"
+    fi
+}
+
+write_state() {
+    echo "$1" > "$STATE_FILE"
+}
+
+# Update state for a single pane and return JSON status
+update_pane_state() {
+    local target="$1"
+    local hash="$2"
+    local is_alive="$3"
+    local now
+    now=$(date +%s)
+
+    python3 - "$STATE_FILE" "$target" "$hash" "$is_alive" "$now" "$STUCK_CYCLES" <<'PYEOF'
+import json, sys, time
+
+state_file = sys.argv[1]
+target = sys.argv[2]
+new_hash = sys.argv[3]
+is_alive = sys.argv[4] == "true"
+now = int(sys.argv[5])
+stuck_cycles = int(sys.argv[6])
+
+try:
+    with open(state_file) as f:
+        state = json.load(f)
+except (FileNotFoundError, json.JSONDecodeError):
+    state = {}
+
+pane = state.get(target, {
+    "hash": "",
+    "same_count": 0,
+    "status": "UNKNOWN",
+    "last_change": 0,
+    "last_check": 0,
+    "restart_attempts": 0,
+    "last_restart": 0,
+    "current_command": "",
+})
+
+if not is_alive:
+    pane["status"] = "DEAD"
+    pane["same_count"] = 0
+elif new_hash == pane.get("hash", ""):
+    pane["same_count"] = pane.get("same_count", 0) + 1
+    if pane["same_count"] >= stuck_cycles:
+        pane["status"] = "STUCK"
+    else:
+        pane["status"] = "STALE" if pane["same_count"] > 0 else "OK"
+else:
+    pane["hash"] = new_hash
+    pane["same_count"] = 0
+    pane["status"] = "OK"
+    pane["last_change"] = now
+
+pane["last_check"] = now
+state[target] = pane
+
+with open(state_file, "w") as f:
+    json.dump(state, f, indent=2)
+
+print(json.dumps(pane))
+PYEOF
+}
+
+# Reset restart attempt counter if cooldown expired
+maybe_reset_restarts() {
+    local target="$1"
+    local now
+    now=$(date +%s)
+
+    python3 - "$STATE_FILE" "$target" "$now" "$RESTART_COOLDOWN" <<'PYEOF'
+import json, sys
+
+state_file = sys.argv[1]
+target = sys.argv[2]
+now = int(sys.argv[3])
+cooldown = int(sys.argv[4])
+
+with open(state_file) as f:
+    state = json.load(f)
+
+pane = state.get(target, {})
+last_restart = pane.get("last_restart", 0)
+
+if now - last_restart > cooldown:
+    pane["restart_attempts"] = 0
+
+state[target] = pane
+with open(state_file, "w") as f:
+    json.dump(state, f, indent=2)
+
+print(pane.get("restart_attempts", 0))
+PYEOF
+}
+
+increment_restart_attempt() {
+    local target="$1"
+    local now
+    now=$(date +%s)
+
+    python3 - "$STATE_FILE" "$target" "$now" <<'PYEOF'
+import json, sys
+
+state_file = sys.argv[1]
+target = sys.argv[2]
+now = int(sys.argv[3])
+
+with open(state_file) as f:
+    state = json.load(f)
+
+pane = state.get(target, {})
+pane["restart_attempts"] = pane.get("restart_attempts", 0) + 1
+pane["last_restart"] = now
+pane["status"] = "RESTARTING"
+
+state[target] = pane
+with open(state_file, "w") as f:
+    json.dump(state, f, indent=2)
+
+print(pane["restart_attempts"])
+PYEOF
+}
+
+# === CORE CHECK ===
+
+check_pane() {
+    local target="$1"
+    local hash is_alive status current_cmd
+
+    # Capture state
+    hash=$(capture_pane_hash "$target")
+    if pane_pid_alive "$target"; then
+        is_alive="true"
+    else
+        is_alive="false"
+    fi
+
+    # Get current command for the pane
+    current_cmd=$(pane_current_command "$target")
+
+    # Update state and get result
+    local result
+    result=$(update_pane_state "$target" "$hash" "$is_alive")
+    status=$(echo "$result" | python3 -c "import json,sys; print(json.loads(sys.stdin.read()).get('status','UNKNOWN'))" 2>/dev/null || echo "UNKNOWN")
+
+    case "$status" in
+        OK)
+            # Healthy, do nothing
+            ;;
+        DEAD)
+            log "DETECTED: $target is DEAD (PID gone) cmd=$current_cmd"
+            if is_restartable "$current_cmd"; then
+                handle_stuck "$target"
+            else
+                log "SKIP: $target not a hermes pane (cmd=$current_cmd), not restarting"
+            fi
+            ;;
+        STUCK)
+            log "DETECTED: $target is STUCK (output unchanged for ${STUCK_CYCLES} cycles) cmd=$current_cmd"
+            if is_restartable "$current_cmd"; then
+                handle_stuck "$target"
+            else
+                log "SKIP: $target not a hermes pane (cmd=$current_cmd), not restarting"
+            fi
+            ;;
+        STALE)
+            # Output unchanged but within threshold — just log
+            local count
+            count=$(echo "$result" | python3 -c "import json,sys; print(json.loads(sys.stdin.read()).get('same_count',0))" 2>/dev/null || echo "?")
+            log "STALE: $target unchanged for $count cycle(s)"
+            ;;
+    esac
+}
+
+handle_stuck() {
+    local target="$1"
+    local session_name="${target%%:*}"
+    local attempts
+
+    # Check restart budget
+    attempts=$(maybe_reset_restarts "$target")
+    if [ "$attempts" -ge "$MAX_RESTART_ATTEMPTS" ]; then
+        log "ESCALATION: $target stuck ${attempts}x — manual intervention needed"
+        echo "ALERT: $target stuck after $attempts restart attempts" >&2
+        return 1
+    fi
+
+    attempts=$(increment_restart_attempt "$target")
+    log "ACTION: Restarting $target (attempt $attempts/$MAX_RESTART_ATTEMPTS)"
+
+    if restart_pane "$target"; then
+        log "OK: $target restarted successfully"
+    else
+        log "FAIL: $target restart failed (attempt $attempts)"
+    fi
+}
+
+check_all_sessions() {
+    local sessions
+
+    if [ -n "$MONITOR_SESSIONS" ]; then
+        IFS=',' read -ra sessions <<< "$MONITOR_SESSIONS"
+    else
+        sessions=()
+        while IFS= read -r line; do
+            [ -n "$line" ] && sessions+=("$line")
+        done < <(tmux list-sessions -F '#{session_name}' 2>/dev/null || true)
+    fi
+
+    local total=0 stuck=0 dead=0 ok=0
+    for session in "${sessions[@]}"; do
+        [ -z "$session" ] && continue
+        # Get pane targets
+        local panes
+        panes=$(tmux list-panes -t "$session" -F "${session}:#{window_index}.#{pane_index}" 2>/dev/null || true)
+        for target in $panes; do
+            check_pane "$target"
+            total=$((total + 1))
+        done
+    done
+
+    log "CHECK: Processed $total panes"
+}
+
+# === STATUS DISPLAY ===
+
+show_status() {
+    if [ ! -f "$STATE_FILE" ]; then
+        echo "No pane state file found at $STATE_FILE"
+        echo "Run pane-watchdog.sh once to initialize."
+        exit 0
+    fi
+
+    python3 - "$STATE_FILE" <<'PYEOF'
+import json, sys, time
+
+state_file = sys.argv[1]
+try:
+    with open(state_file) as f:
+        state = json.load(f)
+except (FileNotFoundError, json.JSONDecodeError):
+    print("No state data yet.")
+    sys.exit(0)
+
+if not state:
+    print("No panes tracked.")
+    sys.exit(0)
+
+now = int(time.time())
+print(f"{'PANE':<35} {'STATUS':<12} {'STALE':<6} {'LAST CHANGE':<15} {'RESTARTS'}")
+print("-" * 90)
+
+for target in sorted(state.keys()):
+    p = state[target]
+    status = p.get("status", "?")
+    same = p.get("same_count", 0)
+    last_change = p.get("last_change", 0)
+    restarts = p.get("restart_attempts", 0)
+
+    if last_change:
+        ago = now - last_change
+        if ago < 60:
+            change_str = f"{ago}s ago"
+        elif ago < 3600:
+            change_str = f"{ago//60}m ago"
+        else:
+            change_str = f"{ago//3600}h ago"
+    else:
+        change_str = "never"
+
+    # Color code
+    if status == "OK":
+        icon = "✓"
+    elif status == "STUCK":
+        icon = "✖"
+    elif status == "DEAD":
+        icon = "☠"
+    elif status == "STALE":
+        icon = "⏳"
+    else:
+        icon = "?"
+
+    print(f"  {icon} {target:<32} {status:<12} {same:<6} {change_str:<15} {restarts}")
+PYEOF
+}
+
+# === DAEMON MODE ===
+
+run_daemon() {
+    log "DAEMON: Starting (interval=${CHECK_INTERVAL}s, stuck_threshold=${STUCK_CYCLES})"
+    echo "Pane watchdog started. Checking every ${CHECK_INTERVAL}s. Ctrl+C to stop."
+    echo "Log: $LOG_FILE"
+    echo "State: $STATE_FILE"
+    echo ""
+
+    while true; do
+        check_all_sessions
+        sleep "$CHECK_INTERVAL"
+    done
+}
+
+# === MAIN ===
+
+case "${1:-}" in
+    --daemon)
+        run_daemon
+        ;;
+    --status)
+        show_status
+        ;;
+    --session)
+        if [ -z "${2:-}" ]; then
+            echo "Usage: pane-watchdog.sh --session SESSION_NAME"
+            exit 1
+        fi
+        MONITOR_SESSIONS="$2"
+        check_all_sessions
+        ;;
+    --help|-h)
+        echo "pane-watchdog.sh — Detect stuck/dead tmux panes and auto-restart"
+        echo ""
+        echo "Usage:"
+        echo "  pane-watchdog.sh              # One-shot check"
+        echo "  pane-watchdog.sh --daemon     # Continuous monitoring"
+        echo "  pane-watchdog.sh --status     # Show pane state"
+        echo "  pane-watchdog.sh --session S  # Check one session"
+        echo ""
+        echo "Config (env vars):"
+        echo "  PANE_CHECK_INTERVAL    Seconds between checks (default: 120)"
+        echo "  PANE_WATCHDOG_SESSIONS Comma-separated session names"
+        echo "  PANE_STATE_FILE        State file path"
+        echo "  STUCK_CYCLES           Unchanged cycles before STUCK (default: 2)"
+        ;;
+    *)
+        check_all_sessions
+        ;;
+esac

bin/preflight-provider-check.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""
+Pre-Flight Provider Check Script
+Issue #508: [Robustness] Credential drain detection — provider health checks
+
+Pre-flight check before session launch: verifies provider credentials and balance.
+
+Usage:
+  python3 preflight-provider-check.py              # Check all providers
+  python3 preflight-provider-check.py --launch      # Check and return exit code
+  python3 preflight-provider-check.py --balance     # Check OpenRouter balance
+"""
+
+import os, sys, json, yaml, urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+
+# Configuration
+HERMES_HOME = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
+LOG_DIR = Path.home() / ".local" / "timmy" / "fleet-health"
+LOG_FILE = LOG_DIR / "preflight-check.log"
+
+def log(msg):
+    """Log message to file and optionally console."""
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+    log_entry = "[" + timestamp + "] " + msg
+    
+    LOG_DIR.mkdir(parents=True, exist_ok=True)
+    with open(LOG_FILE, "a") as f:
+        f.write(log_entry + "\n")
+    
+    if "--quiet" not in sys.argv:
+        print(log_entry)
+
+def get_provider_api_key(provider):
+    """Get API key for a provider from .env or environment."""
+    env_file = HERMES_HOME / ".env"
+    if env_file.exists():
+        with open(env_file) as f:
+            for line in f:
+                line = line.strip()
+                if line.startswith(provider.upper() + "_API_KEY="):
+                    return line.split("=", 1)[1].strip().strip("'\"")
+    
+    return os.environ.get(provider.upper() + "_API_KEY")
+
+def check_openrouter_balance(api_key):
+    """Check OpenRouter balance via /api/v1/auth/key."""
+    if not api_key:
+        return False, "No API key", 0
+    
+    try:
+        req = urllib.request.Request(
+            "https://openrouter.ai/api/v1/auth/key",
+            headers={"Authorization": "Bearer " + api_key}
+        )
+        resp = urllib.request.urlopen(req, timeout=10)
+        data = json.loads(resp.read())
+        
+        # Check for credits
+        credits = data.get("data", {}).get("limit", 0)
+        usage = data.get("data", {}).get("usage", 0)
+        remaining = credits - usage if credits else None
+        
+        if remaining is not None and remaining <= 0:
+            return False, "No credits remaining", 0
+        elif remaining is not None:
+            return True, "Credits available", remaining
+        else:
+            return True, "Unlimited or unknown balance", None
+    
+    except urllib.error.HTTPError as e:
+        if e.code == 401:
+            return False, "Invalid API key", 0
+        else:
+            return False, "HTTP " + str(e.code), 0
+    except Exception as e:
+        return False, str(e)[:100], 0
+
+def check_nous_key(api_key):
+    """Check Nous API key with minimal test call."""
+    if not api_key:
+        return False, "No API key"
+    
+    try:
+        req = urllib.request.Request(
+            "https://inference.nousresearch.com/v1/models",
+            headers={"Authorization": "Bearer " + api_key}
+        )
+        resp = urllib.request.urlopen(req, timeout=10)
+        
+        if resp.status == 200:
+            return True, "Valid key"
+        else:
+            return False, "HTTP " + str(resp.status)
+    
+    except urllib.error.HTTPError as e:
+        if e.code == 401:
+            return False, "Invalid API key"
+        elif e.code == 403:
+            return False, "Forbidden"
+        else:
+            return False, "HTTP " + str(e.code)
+    except Exception as e:
+        return False, str(e)[:100]
+
+def check_anthropic_key(api_key):
+    """Check Anthropic API key with minimal test call."""
+    if not api_key:
+        return False, "No API key"
+    
+    try:
+        req = urllib.request.Request(
+            "https://api.anthropic.com/v1/models",
+            headers={
+                "x-api-key": api_key,
+                "anthropic-version": "2023-06-01"
+            }
+        )
+        resp = urllib.request.urlopen(req, timeout=10)
+        
+        if resp.status == 200:
+            return True, "Valid key"
+        else:
+            return False, "HTTP " + str(resp.status)
+    
+    except urllib.error.HTTPError as e:
+        if e.code == 401:
+            return False, "Invalid API key"
+        elif e.code == 403:
+            return False, "Forbidden"
+        else:
+            return False, "HTTP " + str(e.code)
+    except Exception as e:
+        return False, str(e)[:100]
+
+def check_ollama():
+    """Check if Ollama is running."""
+    try:
+        req = urllib.request.Request("http://localhost:11434/api/tags")
+        resp = urllib.request.urlopen(req, timeout=5)
+        
+        if resp.status == 200:
+            data = json.loads(resp.read())
+            models = data.get("models", [])
+            return True, str(len(models)) + " models loaded"
+        else:
+            return False, "HTTP " + str(resp.status)
+    
+    except Exception as e:
+        return False, str(e)[:100]
+
+def get_configured_provider():
+    """Get the configured provider from global config."""
+    config_file = HERMES_HOME / "config.yaml"
+    if not config_file.exists():
+        return None
+    
+    try:
+        with open(config_file) as f:
+            config = yaml.safe_load(f)
+        
+        model_config = config.get("model", {})
+        if isinstance(model_config, dict):
+            return model_config.get("provider")
+    except:
+        pass
+    
+    return None
+
+def run_preflight_check():
+    """Run pre-flight check on all providers."""
+    log("=== Pre-Flight Provider Check ===")
+    
+    results = {}
+    
+    # Check OpenRouter
+    or_key = get_provider_api_key("openrouter")
+    or_ok, or_msg, or_balance = check_openrouter_balance(or_key)
+    results["openrouter"] = {"healthy": or_ok, "message": or_msg, "balance": or_balance}
+    
+    # Check Nous
+    nous_key = get_provider_api_key("nous")
+    nous_ok, nous_msg = check_nous_key(nous_key)
+    results["nous"] = {"healthy": nous_ok, "message": nous_msg}
+    
+    # Check Anthropic
+    anthropic_key = get_provider_api_key("anthropic")
+    anthropic_ok, anthropic_msg = check_anthropic_key(anthropic_key)
+    results["anthropic"] = {"healthy": anthropic_ok, "message": anthropic_msg}
+    
+    # Check Ollama
+    ollama_ok, ollama_msg = check_ollama()
+    results["ollama"] = {"healthy": ollama_ok, "message": ollama_msg}
+    
+    # Get configured provider
+    configured = get_configured_provider()
+    
+    # Summary
+    healthy_count = sum(1 for r in results.values() if r["healthy"])
+    total_count = len(results)
+    
+    log("Results: " + str(healthy_count) + "/" + str(total_count) + " providers healthy")
+    
+    for provider, result in results.items():
+        status = "HEALTHY" if result["healthy"] else "UNHEALTHY"
+        extra = ""
+        if provider == "openrouter" and result.get("balance") is not None:
+            extra = " (balance: " + str(result["balance"]) + ")"
+        
+        log("  " + provider + ": " + status + " - " + result["message"] + extra)
+    
+    if configured:
+        log("Configured provider: " + configured)
+        if configured in results and not results[configured]["healthy"]:
+            log("WARNING: Configured provider " + configured + " is UNHEALTHY!")
+    
+    return results, configured
+
+def check_launch_readiness():
+    """Check if we're ready to launch sessions."""
+    results, configured = run_preflight_check()
+    
+    # Check if configured provider is healthy
+    if configured and configured in results:
+        if not results[configured]["healthy"]:
+            log("LAUNCH BLOCKED: Configured provider " + configured + " is unhealthy")
+            return False, configured + " is unhealthy"
+    
+    # Check if at least one provider is healthy
+    healthy_providers = [p for p, r in results.items() if r["healthy"]]
+    if not healthy_providers:
+        log("LAUNCH BLOCKED: No healthy providers available")
+        return False, "No healthy providers"
+    
+    log("LAUNCH READY: " + str(len(healthy_providers)) + " healthy providers available")
+    return True, "Ready"
+
+def show_balance():
+    """Show OpenRouter balance."""
+    api_key = get_provider_api_key("openrouter")
+    if not api_key:
+        print("No OpenRouter API key found")
+        return
+    
+    ok, msg, balance = check_openrouter_balance(api_key)
+    
+    if ok:
+        if balance is not None:
+            print("OpenRouter balance: " + str(balance) + " credits")
+        else:
+            print("OpenRouter: " + msg)
+    else:
+        print("OpenRouter: " + msg)
+
+def main():
+    if "--balance" in sys.argv:
+        show_balance()
+    elif "--launch" in sys.argv:
+        ready, message = check_launch_readiness()
+        if ready:
+            print("READY")
+            sys.exit(0)
+        else:
+            print("BLOCKED: " + message)
+            sys.exit(1)
+    else:
+        run_preflight_check()
+
+if __name__ == "__main__":
+    main()

bin/provider-health-monitor.py

@@ -0,0 +1,411 @@
+#!/usr/bin/env python3
+"""
+Provider Health Monitor Script
+Issue #509: [Robustness] Provider-aware profile config — auto-switch on failure
+
+Monitors provider health and automatically switches profiles to working providers.
+
+Usage:
+  python3 provider-health-monitor.py              # Run once
+  python3 provider-health-monitor.py --daemon     # Run continuously
+  python3 provider-health-monitor.py --status     # Show provider health
+"""
+
+import os, sys, json, yaml, urllib.request, time
+from datetime import datetime, timezone
+from pathlib import Path
+
+# Configuration
+HERMES_HOME = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
+PROFILES_DIR = HERMES_HOME / "profiles"
+LOG_DIR = Path.home() / ".local" / "timmy" / "fleet-health"
+STATE_FILE = LOG_DIR / "tmux-state.json"
+LOG_FILE = LOG_DIR / "provider-health.log"
+
+# Provider test endpoints
+PROVIDER_TESTS = {
+    "openrouter": {
+        "url": "https://openrouter.ai/api/v1/models",
+        "method": "GET",
+        "headers": lambda api_key: {"Authorization": "Bearer " + api_key},
+        "timeout": 10
+    },
+    "anthropic": {
+        "url": "https://api.anthropic.com/v1/models",
+        "method": "GET",
+        "headers": lambda api_key: {"x-api-key": api_key, "anthropic-version": "2023-06-01"},
+        "timeout": 10
+    },
+    "nous": {
+        "url": "https://inference.nousresearch.com/v1/models",
+        "method": "GET",
+        "headers": lambda api_key: {"Authorization": "Bearer " + api_key},
+        "timeout": 10
+    },
+    "kimi-coding": {
+        "url": "https://api.kimi.com/coding/v1/models",
+        "method": "GET",
+        "headers": lambda api_key: {"x-api-key": api_key, "x-api-provider": "kimi-coding"},
+        "timeout": 10
+    },
+    "ollama": {
+        "url": "http://localhost:11434/api/tags",
+        "method": "GET",
+        "headers": lambda api_key: {},
+        "timeout": 5
+    }
+}
+
+def log(msg):
+    """Log message to file and optionally console."""
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+    log_entry = "[" + timestamp + "] " + msg
+    
+    LOG_DIR.mkdir(parents=True, exist_ok=True)
+    with open(LOG_FILE, "a") as f:
+        f.write(log_entry + "\n")
+    
+    if "--quiet" not in sys.argv:
+        print(log_entry)
+
+def get_provider_api_key(provider):
+    """Get API key for a provider from .env or environment."""
+    env_file = HERMES_HOME / ".env"
+    if env_file.exists():
+        with open(env_file) as f:
+            for line in f:
+                line = line.strip()
+                if line.startswith(provider.upper() + "_API_KEY="):
+                    return line.split("=", 1)[1].strip().strip("'\"")
+    
+    return os.environ.get(provider.upper() + "_API_KEY")
+
+def test_provider(provider, api_key=None):
+    """Test if a provider is healthy."""
+    config = PROVIDER_TESTS.get(provider)
+    if not config:
+        return False, "Unknown provider: " + provider
+    
+    headers = config["headers"](api_key or "")
+    
+    try:
+        req = urllib.request.Request(
+            config["url"],
+            headers=headers,
+            method=config["method"]
+        )
+        resp = urllib.request.urlopen(req, timeout=config["timeout"])
+        
+        if resp.status == 200:
+            return True, "Healthy"
+        else:
+            return False, "HTTP " + str(resp.status)
+    
+    except urllib.error.HTTPError as e:
+        if e.code == 401:
+            return False, "Unauthorized (401)"
+        elif e.code == 403:
+            return False, "Forbidden (403)"
+        elif e.code == 429:
+            return True, "Rate limited but accessible"
+        else:
+            return False, "HTTP " + str(e.code)
+    except Exception as e:
+        return False, str(e)[:100]
+
+def get_all_providers():
+    """Get all providers from profiles and global config."""
+    providers = set()
+    
+    # Global config
+    global_config = HERMES_HOME / "config.yaml"
+    if global_config.exists():
+        try:
+            with open(global_config) as f:
+                config = yaml.safe_load(f)
+            
+            # Primary model provider
+            model_config = config.get("model", {})
+            if isinstance(model_config, dict):
+                provider = model_config.get("provider", "")
+                if provider:
+                    providers.add(provider)
+            
+            # Auxiliary providers
+            auxiliary = config.get("auxiliary", {})
+            for aux_config in auxiliary.values():
+                if isinstance(aux_config, dict):
+                    provider = aux_config.get("provider", "")
+                    if provider and provider != "auto":
+                        providers.add(provider)
+        except:
+            pass
+    
+    # Profile configs
+    if PROFILES_DIR.exists():
+        for profile_dir in PROFILES_DIR.iterdir():
+            if profile_dir.is_dir():
+                config_file = profile_dir / "config.yaml"
+                if config_file.exists():
+                    try:
+                        with open(config_file) as f:
+                            config = yaml.safe_load(f)
+                        
+                        model_config = config.get("model", {})
+                        if isinstance(model_config, dict):
+                            provider = model_config.get("provider", "")
+                            if provider:
+                                providers.add(provider)
+                        
+                        auxiliary = config.get("auxiliary", {})
+                        for aux_config in auxiliary.values():
+                            if isinstance(aux_config, dict):
+                                provider = aux_config.get("provider", "")
+                                if provider and provider != "auto":
+                                    providers.add(provider)
+                    except:
+                        pass
+    
+    # Add common providers even if not configured
+    providers.update(["openrouter", "nous", "ollama"])
+    
+    return list(providers)
+
+def build_health_map():
+    """Build a health map of all providers."""
+    providers = get_all_providers()
+    health_map = {}
+    
+    log("Testing " + str(len(providers)) + " providers...")
+    
+    for provider in providers:
+        api_key = get_provider_api_key(provider)
+        healthy, message = test_provider(provider, api_key)
+        
+        health_map[provider] = {
+            "healthy": healthy,
+            "message": message,
+            "last_test": datetime.now(timezone.utc).isoformat(),
+            "api_key_present": bool(api_key)
+        }
+        
+        status = "HEALTHY" if healthy else "UNHEALTHY"
+        log("  " + provider + ": " + status + " - " + message)
+    
+    return health_map
+
+def get_fallback_providers(health_map):
+    """Get list of healthy providers in priority order."""
+    # Priority order: nous, openrouter, ollama, others
+    priority_order = ["nous", "openrouter", "ollama", "anthropic", "kimi-coding"]
+    
+    healthy = []
+    for provider in priority_order:
+        if provider in health_map and health_map[provider]["healthy"]:
+            healthy.append(provider)
+    
+    # Add any other healthy providers not in priority list
+    for provider, info in health_map.items():
+        if info["healthy"] and provider not in healthy:
+            healthy.append(provider)
+    
+    return healthy
+
+def update_profile_config(profile_name, new_provider):
+    """Update a profile's config to use a new provider."""
+    config_file = PROFILES_DIR / profile_name / "config.yaml"
+    
+    if not config_file.exists():
+        return False, "Config file not found"
+    
+    try:
+        with open(config_file) as f:
+            config = yaml.safe_load(f)
+        
+        # Update model provider
+        if "model" not in config:
+            config["model"] = {}
+        
+        old_provider = config["model"].get("provider", "unknown")
+        config["model"]["provider"] = new_provider
+        
+        # Update auxiliary providers if they were using the old provider
+        auxiliary = config.get("auxiliary", {})
+        for aux_name, aux_config in auxiliary.items():
+            if isinstance(aux_config, dict) and aux_config.get("provider") == old_provider:
+                aux_config["provider"] = new_provider
+        
+        # Write back
+        with open(config_file, "w") as f:
+            yaml.dump(config, f, default_flow_style=False)
+        
+        log("Updated " + profile_name + ": " + old_provider + " -> " + new_provider)
+        return True, "Updated"
+    
+    except Exception as e:
+        return False, str(e)
+
+def check_profiles(health_map):
+    """Check all profiles and update unhealthy providers."""
+    if not PROFILES_DIR.exists():
+        return
+    
+    fallback_providers = get_fallback_providers(health_map)
+    if not fallback_providers:
+        log("CRITICAL: No healthy providers available!")
+        return
+    
+    updated_profiles = []
+    
+    for profile_dir in PROFILES_DIR.iterdir():
+        if not profile_dir.is_dir():
+            continue
+        
+        profile_name = profile_dir.name
+        config_file = profile_dir / "config.yaml"
+        
+        if not config_file.exists():
+            continue
+        
+        try:
+            with open(config_file) as f:
+                config = yaml.safe_load(f)
+            
+            model_config = config.get("model", {})
+            if not isinstance(model_config, dict):
+                continue
+            
+            current_provider = model_config.get("provider", "")
+            if not current_provider:
+                continue
+            
+            # Check if current provider is healthy
+            if current_provider in health_map and health_map[current_provider]["healthy"]:
+                continue  # Provider is healthy, no action needed
+            
+            # Find best fallback
+            best_fallback = None
+            for provider in fallback_providers:
+                if provider != current_provider:
+                    best_fallback = provider
+                    break
+            
+            if not best_fallback:
+                log("No fallback for " + profile_name + " (current: " + current_provider + ")")
+                continue
+            
+            # Update profile
+            success, message = update_profile_config(profile_name, best_fallback)
+            if success:
+                updated_profiles.append({
+                    "profile": profile_name,
+                    "old_provider": current_provider,
+                    "new_provider": best_fallback
+                })
+        
+        except Exception as e:
+            log("Error processing " + profile_name + ": " + str(e))
+    
+    return updated_profiles
+
+def load_state():
+    """Load state from tmux-state.json."""
+    if STATE_FILE.exists():
+        try:
+            with open(STATE_FILE) as f:
+                return json.load(f)
+        except:
+            pass
+    return {}
+
+def save_state(state):
+    """Save state to tmux-state.json."""
+    LOG_DIR.mkdir(parents=True, exist_ok=True)
+    
+    with open(STATE_FILE, "w") as f:
+        json.dump(state, f, indent=2)
+
+def run_once():
+    """Run provider health check once."""
+    log("=== Provider Health Check ===")
+    
+    state = load_state()
+    
+    # Build health map
+    health_map = build_health_map()
+    
+    # Check profiles and update if needed
+    updated_profiles = check_profiles(health_map)
+    
+    # Update state
+    state["provider_health"] = health_map
+    state["last_provider_check"] = datetime.now(timezone.utc).isoformat()
+    
+    if updated_profiles:
+        state["last_profile_updates"] = updated_profiles
+    
+    save_state(state)
+    
+    # Summary
+    healthy_count = sum(1 for p in health_map.values() if p["healthy"])
+    total_count = len(health_map)
+    
+    log("Health: " + str(healthy_count) + "/" + str(total_count) + " providers healthy")
+    
+    if updated_profiles:
+        log("Updated " + str(len(updated_profiles)) + " profiles:")
+        for update in updated_profiles:
+            log("  " + update["profile"] + ": " + update["old_provider"] + " -> " + update["new_provider"])
+
+def show_status():
+    """Show provider health status."""
+    state = load_state()
+    health_map = state.get("provider_health", {})
+    
+    if not health_map:
+        print("No provider health data available. Run without --status first.")
+        return
+    
+    print("Provider Health (last updated: " + str(state.get("last_provider_check", "unknown")) + ")")
+    print("=" * 80)
+    
+    for provider, info in sorted(health_map.items()):
+        status = "HEALTHY" if info["healthy"] else "UNHEALTHY"
+        message = info.get("message", "")
+        api_key = "yes" if info.get("api_key_present") else "no"
+        
+        print(provider.ljust(20) + " " + status.ljust(10) + " API key: " + api_key + " - " + message)
+    
+    # Show recent updates
+    updates = state.get("last_profile_updates", [])
+    if updates:
+        print()
+        print("Recent Profile Updates:")
+        for update in updates:
+            print("  " + update["profile"] + ": " + update["old_provider"] + " -> " + update["new_provider"])
+
+def daemon_mode():
+    """Run continuously."""
+    log("Starting provider health daemon (check every 300s)")
+    
+    while True:
+        try:
+            run_once()
+            time.sleep(300)  # Check every 5 minutes
+        except KeyboardInterrupt:
+            log("Daemon stopped by user")
+            break
+        except Exception as e:
+            log("Error: " + str(e))
+            time.sleep(60)
+
+def main():
+    if "--status" in sys.argv:
+        show_status()
+    elif "--daemon" in sys.argv:
+        daemon_mode()
+    else:
+        run_once()
+
+if __name__ == "__main__":
+    main()

bin/soul_eval_gate.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 """
 Soul Eval Gate — The Conscience of the Training Pipeline
 

bin/timmy-orchestrator.sh

@@ -3,7 +3,7 @@
 # Uses Hermes CLI plus workforce-manager to triage and review.
 # Timmy is the brain. Other agents are the hands.
 
-set -uo pipefail
+set -uo pipefail\n\nSCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 LOG_DIR="$HOME/.hermes/logs"
 LOG="$LOG_DIR/timmy-orchestrator.log"
@@ -40,6 +40,7 @@ gather_state() {
   > "$state_dir/unassigned.txt"
   > "$state_dir/open_prs.txt"
   > "$state_dir/agent_status.txt"
+  > "$state_dir/uncommitted_work.txt"
 
   for repo in $REPOS; do
     local short=$(echo "$repo" | cut -d/ -f2)
@@ -71,6 +72,24 @@ for p in json.load(sys.stdin):
   tail -50 "/tmp/kimi-heartbeat.log" 2>/dev/null | grep -c "FAILED:" | xargs -I{} echo "Kimi recent failures: {}" >> "$state_dir/agent_status.txt"
   tail -1 "/tmp/kimi-heartbeat.log" 2>/dev/null | xargs -I{} echo "Kimi last event: {}" >> "$state_dir/agent_status.txt"
 
+  # Scan worktrees for uncommitted work
+  for wt_dir in "$HOME/worktrees"/*/; do
+    [ -d "$wt_dir" ] || continue
+    [ -d "$wt_dir/.git" ] || continue
+    local dirty
+    dirty=$(cd "$wt_dir" && git status --porcelain 2>/dev/null | wc -l | tr -d " ")
+    if [ "${dirty:-0}" -gt 0 ]; then
+      local branch
+      branch=$(cd "$wt_dir" && git branch --show-current 2>/dev/null || echo "?")
+      local age=""
+      local last_commit
+      last_commit=$(cd "$wt_dir" && git log -1 --format=%ct 2>/dev/null || echo 0)
+      local now=$(date +%s)
+      local stale_mins=$(( (now - last_commit) / 60 ))
+      echo "DIR=$wt_dir BRANCH=$branch DIRTY=$dirty STALE=${stale_mins}m" >> "$state_dir/uncommitted_work.txt"
+    fi
+  done
+
   echo "$state_dir"
 }
 
@@ -81,6 +100,25 @@ run_triage() {
 
   log "Cycle: $unassigned_count unassigned, $pr_count open PRs"
 
+  # Check for uncommitted work — nag if stale
+  local uncommitted_count
+  uncommitted_count=$(wc -l < "$state_dir/uncommitted_work.txt" 2>/dev/null | tr -d " " || echo 0)
+  if [ "${uncommitted_count:-0}" -gt 0 ]; then
+    log "WARNING: $uncommitted_count worktree(s) with uncommitted work"
+    while IFS= read -r line; do
+      log "  UNCOMMITTED: $line"
+      # Auto-commit stale work (>60 min without commit)
+      local stale=$(echo "$line" | sed 's/.*STALE=\([0-9]*\)m.*/\1/')
+      local wt_dir=$(echo "$line" | sed 's/.*DIR=\([^ ]*\) .*/\1/')
+      if [ "${stale:-0}" -gt 60 ]; then
+        log "  AUTO-COMMITTING stale work in $wt_dir (${stale}m stale)"
+        (cd "$wt_dir" && git add -A && git commit -m "WIP: orchestrator auto-commit — ${stale}m stale work
+
+Preserved by timmy-orchestrator to prevent loss." 2>/dev/null &&           git push 2>/dev/null) && log "  COMMITTED: $wt_dir" || log "  COMMIT FAILED: $wt_dir"
+      fi
+    done < "$state_dir/uncommitted_work.txt"
+  fi
+
   # If nothing to do, skip the LLM call
   if [ "$unassigned_count" -eq 0 ] && [ "$pr_count" -eq 0 ]; then
     log "Nothing to triage"
@@ -198,6 +236,12 @@ FOOTER
 log "=== Timmy Orchestrator Started (PID $$) ==="
 log "Cycle: ${CYCLE_INTERVAL}s | Auto-assign: ${AUTO_ASSIGN_UNASSIGNED} | Inference surface: Hermes CLI"
 
+# Start auto-commit-guard daemon for work preservation
+if ! pgrep -f "auto-commit-guard.sh" >/dev/null 2>&1; then
+  nohup bash "$SCRIPT_DIR/auto-commit-guard.sh" 120 >> "$LOG_DIR/auto-commit-guard.log" 2>&1 &
+  log "Started auto-commit-guard daemon (PID $!)"
+fi
+
 WORKFORCE_CYCLE=0
 
 while true; do

cron/jobs.json

@@ -196,7 +196,37 @@
       "paused_reason": null,
       "skills": [],
       "skill": null
+    },
+    {
+      "id": "tmux-supervisor-513",
+      "name": "Autonomous Cron Supervisor",
+      "prompt": "Load the tmux-supervisor skill and execute the monitoring protocol.\n\nCheck both `dev` and `timmy` tmux sessions for idle panes. Only send Telegram notifications on actionable events (idle, overflow, failure). Be silent when all agents are working.\n\nSteps:\n1. List all tmux sessions (skip 'Alexander')\n2. For each session, list windows and panes\n3. Capture each pane and classify state (idle vs active)\n4. For idle panes: read context, craft context-aware prompt\n5. Send /queue prompts to idle panes\n6. Verify prompts landed\n7. Only notify via Telegram if:\n   - A pane was prompted (idle detected)\n   - A pane shows context overflow (>80%)\n   - A pane is stuck or crashed\n8. If all panes are active: respond with [SILENT]",
+      "schedule": {
+        "kind": "interval",
+        "minutes": 7,
+        "display": "every 7m"
+      },
+      "schedule_display": "every 7m",
+      "repeat": {
+        "times": null,
+        "completed": 0
+      },
+      "enabled": true,
+      "created_at": "2026-04-15T03:00:00.000000+00:00",
+      "next_run_at": null,
+      "last_run_at": null,
+      "last_status": null,
+      "last_error": null,
+      "deliver": "telegram",
+      "origin": null,
+      "state": "scheduled",
+      "paused_at": null,
+      "paused_reason": null,
+      "skills": [
+        "tmux-supervisor"
+      ],
+      "skill": "tmux-supervisor"
     }
   ],
   "updated_at": "2026-04-13T02:00:00+00:00"
-}
+}

cron/pipeline-scheduler.yml

@@ -0,0 +1,9 @@
+- name: Nightly Pipeline Scheduler
+  schedule: '*/30 18-23,0-8 * * *' # Every 30 min, off-peak hours only
+  tasks:
+    - name: Check and start pipelines
+      shell: "bash scripts/nightly-pipeline-scheduler.sh"
+      env:
+        PIPELINE_TOKEN_LIMIT: "500000"
+        PIPELINE_PEAK_START: "9"
+        PIPELINE_PEAK_END: "18"

deploy/auto-commit-guard.plist

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>ai.timmy.auto-commit-guard</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/bash</string>
+        <string>/Users/apayne/.hermes/bin/auto-commit-guard.sh</string>
+        <string>120</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>/Users/apayne/.hermes/logs/auto-commit-guard.stdout.log</string>
+    <key>StandardErrorPath</key>
+    <string>/Users/apayne/.hermes/logs/auto-commit-guard.stderr.log</string>
+    <key>WorkingDirectory</key>
+    <string>/Users/apayne</string>
+</dict>
+</plist>

deploy/gitea-a11y/README.md

@@ -0,0 +1,21 @@
+# Gitea Accessibility Fix - R4: Time Elements
+
+WCAG 1.3.1: Relative timestamps lack machine-readable fallbacks.
+
+## Fix
+
+Wrap relative timestamps in `<time datetime="...">` elements.
+
+## Files
+
+- `custom/templates/custom/time_relative.tmpl` - Reusable `<time>` helper
+- `custom/templates/repo/list_a11y.tmpl` - Explore/Repos list override
+
+## Deploy
+
+```bash
+cp -r custom/templates/* /path/to/gitea/custom/templates/
+systemctl restart gitea
+```
+
+Closes #554

deploy/gitea-a11y/custom/templates/custom/time_relative.tmpl

@@ -0,0 +1,27 @@
+{{/*
+  Gitea a11y fix: R4 <time> elements for relative timestamps
+  Deploy to: custom/templates/custom/time_relative.tmpl
+*/}}
+
+{{define "custom/time_relative"}}
+{{if and .Time .Relative}}
+<time datetime="{{.Time.Format "2006-01-02T15:04:05Z07:00"}}" title="{{.Time.Format "Jan 02, 2006 15:04"}}">
+  {{.Relative}}
+</time>
+{{else if .Relative}}
+<span>{{.Relative}}</span>
+{{end}}
+{{end}}
+
+{{define "custom/time_from_unix"}}
+{{if .Relative}}
+<time datetime="" data-unix="{{.Unix}}" title="">{{.Relative}}</time>
+<script>
+(function() {
+  var el = document.currentScript.previousElementSibling;
+  var unix = parseInt(el.getAttribute('data-unix'));
+  if (unix) { el.setAttribute('datetime', new Date(unix * 1000).toISOString()); el.setAttribute('title', new Date(unix * 1000).toLocaleString()); }
+})();
+</script>
+{{end}}
+{{end}}

deploy/gitea-a11y/custom/templates/repo/list_a11y.tmpl

@@ -0,0 +1,27 @@
+{{/*
+  Gitea a11y fix: R4 <time> elements for relative timestamps on repo list
+  Deploy to: custom/templates/repo/list_a11y.tmpl
+*/}}
+
+{{/* Star count link with aria-label */}}
+<a class="repo-card-star" href="{{.RepoLink}}/stars" aria-label="{{.NumStars}} stars" title="{{.NumStars}} stars">
+  <svg class="octicon octicon-star" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">
+    <path d="M8 .25a.75.75 0 01.673.418l1.882 3.815 4.21.612a.75.75 0 01.416 1.279l-3.046 2.97.719 4.192a.75.75 0 01-1.088.791L8 12.347l-3.766 1.98a.75.75 0 01-1.088-.79l.72-4.194L.818 6.374a.75.75 0 01.416-1.28l4.21-.611L7.327.668A.75.75 0 018 .25z"/>
+  </svg>
+  <span>{{.NumStars}}</span>
+</a>
+
+{{/* Fork count link with aria-label */}}
+<a class="repo-card-fork" href="{{.RepoLink}}/forks" aria-label="{{.NumForks}} forks" title="{{.NumForks}} forks">
+  <svg class="octicon octicon-repo-forked" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">
+    <path d="M5 5.372v.878c0 .414.336.75.75.75h4.5a.75.75 0 00.75-.75v-.878a2.25 2.25 0 111.5 0v.878a2.25 2.25 0 01-2.25 2.25h-1.5v2.128a2.251 2.251 0 11-1.5 0V8.5h-1.5A2.25 2.25 0 013.5 6.25v-.878a2.25 2.25 0 111.5 0zM5 3.25a.75.75 0 10-1.5 0 .75.75 0 001.5 0zm6.75.75a.75.75 0 100-1.5.75.75 0 000 1.5zm-3 8.75a.75.75 0 10-1.5 0 .75.75 0 001.5 0z"/>
+  </svg>
+  <span>{{.NumForks}}</span>
+</a>
+
+{{/* Relative timestamp with <time> element for a11y */}}
+{{if .UpdatedUnix}}
+<time datetime="{{.UpdatedUnix | TimeSinceISO}}" title="{{.UpdatedUnix | DateFmtLong}}" class="text-light">
+  {{.UpdatedUnix | TimeSince}}
+</time>
+{{end}}

docs/glitch-detection.md

@@ -0,0 +1,179 @@
+# 3D World Glitch Detection — Matrix Scanner
+
+**Reference:** timmy-config#491
+**Label:** gemma-4-multimodal
+**Version:** 0.1.0
+
+## Overview
+
+The Matrix Glitch Detector scans 3D web worlds for visual artifacts and
+rendering anomalies. It uses browser automation to capture screenshots from
+multiple camera angles, then sends them to a vision AI model for analysis
+against a library of known glitch patterns.
+
+## Detected Glitch Categories
+
+| Category | Severity | Description |
+|---|---|---|
+| Floating Assets | HIGH | Objects not grounded — hovering above surfaces |
+| Z-Fighting | MEDIUM | Coplanar surfaces flickering/competing for depth |
+| Missing Textures | CRITICAL | Placeholder colors (magenta, checkerboard) |
+| Clipping | HIGH | Geometry passing through other objects |
+| Broken Normals | MEDIUM | Inside-out or incorrectly lit surfaces |
+| Shadow Artifacts | LOW | Detached, mismatched, or acne shadows |
+| LOD Popping | LOW | Abrupt level-of-detail transitions |
+| Lightmap Errors | MEDIUM | Dark splotches, light leaks, baking failures |
+| Water/Reflection | MEDIUM | Incorrect environment reflections |
+| Skybox Seam | LOW | Visible seams at cubemap face edges |
+
+## Installation
+
+No external dependencies required — pure Python 3.10+.
+
+```bash
+# Clone the repo
+git clone https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config.git
+cd timmy-config
+```
+
+## Usage
+
+### Basic Scan
+
+```bash
+python bin/matrix_glitch_detector.py https://matrix.example.com/world/alpha
+```
+
+### Multi-Angle Scan
+
+```bash
+python bin/matrix_glitch_detector.py https://matrix.example.com/world/alpha \
+    --angles 8 \
+    --output glitch_report.json
+```
+
+### Demo Mode
+
+```bash
+python bin/matrix_glitch_detector.py --demo
+```
+
+### Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `url` | (required) | URL of the 3D world to scan |
+| `--angles N` | 4 | Number of camera angles to capture |
+| `--output PATH` | stdout | Output file for JSON report |
+| `--min-severity` | info | Minimum severity: info/low/medium/high/critical |
+| `--demo` | off | Run with simulated detections |
+| `--verbose` | off | Enable verbose output |
+
+## Report Format
+
+The JSON report includes:
+
+```json
+{
+  "scan_id": "uuid",
+  "url": "https://...",
+  "timestamp": "ISO-8601",
+  "total_screenshots": 4,
+  "angles_captured": ["front", "right", "back", "left"],
+  "glitches": [
+    {
+      "id": "short-uuid",
+      "category": "floating_assets",
+      "name": "Floating Chair",
+      "description": "Office chair floating 0.3m above floor",
+      "severity": "high",
+      "confidence": 0.87,
+      "location_x": 35.2,
+      "location_y": 62.1,
+      "screenshot_index": 0,
+      "screenshot_angle": "front",
+      "timestamp": "ISO-8601"
+    }
+  ],
+  "summary": {
+    "total_glitches": 4,
+    "by_severity": {"critical": 1, "high": 2, "medium": 1},
+    "by_category": {"floating_assets": 1, "missing_textures": 1, ...},
+    "highest_severity": "critical",
+    "clean_screenshots": 0
+  },
+  "metadata": {
+    "detector_version": "0.1.0",
+    "pattern_count": 10,
+    "reference": "timmy-config#491"
+  }
+}
+```
+
+## Vision AI Integration
+
+The detector supports any OpenAI-compatible vision API. Set these
+environment variables:
+
+```bash
+export VISION_API_KEY="your-api-key"
+export VISION_API_BASE="https://api.openai.com/v1"  # optional
+export VISION_MODEL="gpt-4o"  # optional, default: gpt-4o
+```
+
+For browser-based capture with `browser_vision`:
+
+```bash
+export BROWSER_VISION_SCRIPT="/path/to/browser_vision.py"
+```
+
+## Glitch Patterns
+
+Pattern definitions live in `bin/glitch_patterns.py`. Each pattern includes:
+
+- **category** — Enum matching the glitch type
+- **detection_prompts** — Instructions for the vision model
+- **visual_indicators** — What to look for in screenshots
+- **confidence_threshold** — Minimum confidence to report
+
+### Adding Custom Patterns
+
+```python
+from glitch_patterns import GlitchPattern, GlitchCategory, GlitchSeverity
+
+custom = GlitchPattern(
+    category=GlitchCategory.FLOATING_ASSETS,
+    name="Custom Glitch",
+    description="Your description",
+    severity=GlitchSeverity.MEDIUM,
+    detection_prompts=["Look for..."],
+    visual_indicators=["indicator 1", "indicator 2"],
+)
+```
+
+## Testing
+
+```bash
+python -m pytest tests/test_glitch_detector.py -v
+# or
+python tests/test_glitch_detector.py
+```
+
+## Architecture
+
+```
+bin/
+  matrix_glitch_detector.py  — Main CLI entry point
+  glitch_patterns.py         — Pattern definitions and prompt builder
+tests/
+  test_glitch_detector.py    — Unit and integration tests
+docs/
+  glitch-detection.md        — This documentation
+```
+
+## Limitations
+
+- Browser automation requires a headless browser environment
+- Vision AI analysis depends on model availability and API limits
+- Placeholder screenshots are generated when browser capture is unavailable
+- Detection accuracy varies by scene complexity and lighting conditions

pipeline/quality_gate.py

@@ -0,0 +1,419 @@
+#!/usr/bin/env python3
+"""
+quality_gate.py — Quality Gate for Pipeline Outputs
+
+Validates all pipeline outputs before saving. Rejects bad outputs,
+tracks quality scores, and supports re-queue for regeneration.
+
+Usage:
+    python3 quality_gate.py --input output.jsonl --type training_pairs
+    python3 quality_gate.py --input output.jsonl --type knowledge
+    python3 quality_gate.py --input output.jsonl --type scene_descriptions
+    python3 quality_gate.py --dir pipeline/output/ --type training_pairs
+    python3 quality_gate.py --status  # show quality stats
+
+Exit codes:
+    0 = all outputs passed
+    1 = some outputs rejected
+    2 = file/parse error
+"""
+
+import json
+import os
+import sys
+import hashlib
+import re
+from pathlib import Path
+from datetime import datetime, timezone
+from dataclasses import dataclass, field, asdict
+from typing import List, Optional, Dict, Any
+
+STATS_FILE = Path.home() / ".hermes" / "pipeline" / "quality_stats.json"
+
+# --- Quality Check Types ---
+
+@dataclass
+class QualityResult:
+    """Result of a quality check on a single entry."""
+    passed: bool
+    checks_run: int
+    checks_failed: int
+    score: float  # 0.0-1.0
+    reasons: List[str] = field(default_factory=list)
+    entry_index: int = -1
+    hash: str = ""
+
+    def to_dict(self):
+        return asdict(self)
+
+
+@dataclass
+class GateReport:
+    """Report from a quality gate run."""
+    file: str
+    type: str
+    total: int
+    passed: int
+    rejected: int
+    score: float
+    rejected_indices: List[int] = field(default_factory=list)
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    def to_dict(self):
+        return asdict(self)
+
+
+# ============================================================
+# Check Functions
+# ============================================================
+
+def entry_hash(entry: dict) -> str:
+    """Hash an entry for deduplication."""
+    return hashlib.sha256(json.dumps(entry, sort_keys=True, ensure_ascii=False).encode()).hexdigest()[:16]
+
+
+def check_not_empty(entry: dict, fields: List[str]) -> List[str]:
+    """Check that required fields are non-empty."""
+    errors = []
+    for f in fields:
+        val = entry.get(f)
+        if val is None:
+            errors.append(f"missing_field: {f}")
+        elif isinstance(val, str) and len(val.strip()) == 0:
+            errors.append(f"empty_field: {f}")
+        elif isinstance(val, list) and len(val) == 0:
+            errors.append(f"empty_list: {f}")
+    return errors
+
+
+def check_string_min_length(entry: dict, field_lengths: Dict[str, int]) -> List[str]:
+    """Check that string fields meet minimum lengths."""
+    errors = []
+    for f, min_len in field_lengths.items():
+        val = entry.get(f)
+        if isinstance(val, str) and len(val) < min_len:
+            errors.append(f"short_field: {f} ({len(val)} < {min_len})")
+    return errors
+
+
+def check_no_duplicates(entries: List[dict], key_fields: List[str]) -> Dict[int, List[str]]:
+    """Check for duplicate entries based on key fields."""
+    seen = {}
+    errors = {}
+    for i, entry in enumerate(entries):
+        key = tuple(entry.get(f, "") for f in key_fields)
+        key_str = str(key)
+        if key_str in seen:
+            errors[i] = [f"duplicate_of_index: {seen[key_str]}"]
+        else:
+            seen[key_str] = i
+    return errors
+
+
+def check_training_pair(entry: dict) -> List[str]:
+    """Validate a training pair (prompt/response)."""
+    errors = []
+    errors.extend(check_not_empty(entry, ["prompt", "response"]))
+
+    # Check response isn't just echoing the prompt
+    prompt = entry.get("prompt", "")
+    response = entry.get("response", "")
+    if prompt and response and prompt.strip() == response.strip():
+        errors.append("response_equals_prompt")
+
+    # Check response has substance
+    if isinstance(response, str) and len(response) < 10:
+        errors.append(f"response_too_short: {len(response)} chars")
+
+    return errors
+
+
+def check_scene_description(entry: dict) -> List[str]:
+    """Validate a scene description entry."""
+    errors = []
+    errors.extend(check_not_empty(entry, ["song", "beat", "lyric_line", "scene"]))
+
+    scene = entry.get("scene")
+    if isinstance(scene, dict):
+        errors.extend(check_not_empty(scene, ["mood", "colors", "composition", "camera", "description"]))
+        errors.extend(check_string_min_length(scene, {"description": 10}))
+
+        colors = scene.get("colors", [])
+        if isinstance(colors, list) and len(colors) > 5:
+            errors.append(f"too_many_colors: {len(colors)} > 5")
+
+    return errors
+
+
+def check_knowledge_entry(entry: dict) -> List[str]:
+    """Validate a knowledge file entry."""
+    errors = []
+    errors.extend(check_not_empty(entry, ["title", "content"]))
+
+    # Check for placeholder content
+    content = entry.get("content", "")
+    if isinstance(content, str):
+        placeholders = ["TODO", "FIXME", "PLACEHOLDER", "[INSERT", "lorem ipsum"]
+        for p in placeholders:
+            if p.lower() in content.lower():
+                errors.append(f"placeholder_content: '{p}' found")
+
+    errors.extend(check_string_min_length(entry, {"content": 50}))
+
+    return errors
+
+
+def check_prompt_enhancement(entry: dict) -> List[str]:
+    """Validate a prompt enhancement pair (terse/rich)."""
+    errors = []
+    errors.extend(check_not_empty(entry, ["terse", "rich"]))
+
+    terse = entry.get("terse", "")
+    rich = entry.get("rich", "")
+
+    # Rich should be longer than terse
+    if isinstance(terse, str) and isinstance(rich, str) and len(rich) <= len(terse):
+        errors.append("rich_not_longer_than_terse")
+
+    errors.extend(check_string_min_length(entry, {"rich": 20}))
+
+    return errors
+
+
+def check_adversary_entry(entry: dict) -> List[str]:
+    """Validate an adversary corpus entry."""
+    errors = []
+    errors.extend(check_not_empty(entry, ["id", "family", "prompt"]))
+
+    # Check prompt isn't empty or placeholder
+    prompt = entry.get("prompt", "")
+    if isinstance(prompt, str) and len(prompt) < 10:
+        errors.append(f"prompt_too_short: {len(prompt)} chars")
+
+    return errors
+
+
+def check_soul_compliance(text: str) -> List[str]:
+    """Check text for SOUL.md compliance (basic checks)."""
+    errors = []
+    text_lower = text.lower() if text else ""
+
+    # Check for content that violates core values
+    violations = [
+        ("compute.*value.*human.*life", "soul_violation: computing human life value"),
+        ("sexualiz.*child", "soul_violation: sexualizing children"),
+        ("create.*weapon.*kill", "soul_violation: weapon creation"),
+        ("enslav", "soul_violation: enslavement content"),
+    ]
+    for pattern, msg in violations:
+        if re.search(pattern, text_lower):
+            errors.append(msg)
+
+    return errors
+
+
+# ============================================================
+# Gate Runners
+# ============================================================
+
+CHECK_MAP = {
+    "training_pairs": check_training_pair,
+    "training_pair": check_training_pair,
+    "scene_descriptions": check_scene_description,
+    "scene_description": check_scene_description,
+    "knowledge": check_knowledge_entry,
+    "prompt_enhancement": check_prompt_enhancement,
+    "adversary": check_adversary_entry,
+    "adversary_corpus": check_adversary_entry,
+}
+
+
+def run_gate(input_path: str, entry_type: str) -> GateReport:
+    """Run quality gate on a JSONL file."""
+    path = Path(input_path)
+    if not path.exists():
+        return GateReport(file=str(path), type=entry_type, total=0, passed=0, rejected=0, score=0.0)
+
+    check_fn = CHECK_MAP.get(entry_type)
+    if not check_fn:
+        return GateReport(file=str(path), type=entry_type, total=0, passed=0, rejected=0, score=0.0,
+                          rejected_indices=[-1])  # unknown type
+
+    entries = []
+    with open(path) as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                entries.append(json.loads(line))
+
+    # Deduplication check
+    key_fields = _get_key_fields(entry_type)
+    dup_errors = check_no_duplicates(entries, key_fields)
+
+    passed = 0
+    rejected = 0
+    rejected_indices = []
+    total_score = 0.0
+
+    for i, entry in enumerate(entries):
+        errors = check_fn(entry)
+
+        # Add duplicate errors
+        if i in dup_errors:
+            errors.extend(dup_errors[i])
+
+        # Add SOUL compliance check for text content
+        text_content = ""
+        for f in ["response", "rich", "description", "content", "lyric_line"]:
+            val = entry.get(f)
+            if isinstance(val, str):
+                text_content += val + " "
+        if isinstance(entry.get("scene"), dict):
+            text_content += entry["scene"].get("description", "")
+
+        soul_errors = check_soul_compliance(text_content)
+        errors.extend(soul_errors)
+
+        if errors:
+            rejected += 1
+            rejected_indices.append(i)
+        else:
+            passed += 1
+
+        # Score: 1.0 if no errors, decreasing with each error
+        entry_score = max(0.0, 1.0 - (len(errors) * 0.2))
+        total_score += entry_score
+
+    avg_score = total_score / len(entries) if entries else 0.0
+
+    report = GateReport(
+        file=str(path),
+        type=entry_type,
+        total=len(entries),
+        passed=passed,
+        rejected=rejected,
+        score=round(avg_score, 3),
+        rejected_indices=rejected_indices[:50],  # limit for readability
+    )
+
+    # Save stats
+    _save_stats(report)
+
+    return report
+
+
+def _get_key_fields(entry_type: str) -> List[str]:
+    """Get key fields for deduplication based on entry type."""
+    key_map = {
+        "training_pairs": ["prompt", "response"],
+        "training_pair": ["prompt", "response"],
+        "scene_descriptions": ["song", "beat"],
+        "scene_description": ["song", "beat"],
+        "knowledge": ["title"],
+        "prompt_enhancement": ["terse", "rich"],
+        "adversary": ["id", "prompt"],
+        "adversary_corpus": ["id", "prompt"],
+    }
+    return key_map.get(entry_type, ["id"])
+
+
+def _save_stats(report: GateReport):
+    """Append quality stats to the stats file."""
+    STATS_FILE.parent.mkdir(parents=True, exist_ok=True)
+
+    stats = []
+    if STATS_FILE.exists():
+        try:
+            with open(STATS_FILE) as f:
+                stats = json.load(f)
+        except (json.JSONDecodeError, IOError):
+            stats = []
+
+    stats.append(report.to_dict())
+
+    # Keep last 1000 entries
+    stats = stats[-1000:]
+
+    with open(STATS_FILE, "w") as f:
+        json.dump(stats, f, indent=2)
+
+
+def show_status():
+    """Show quality gate statistics."""
+    if not STATS_FILE.exists():
+        print("No quality stats found.")
+        return
+
+    with open(STATS_FILE) as f:
+        stats = json.load(f)
+
+    print(f"\nQuality Gate Stats — {len(stats)} runs")
+    print()
+
+    # Group by type
+    by_type = {}
+    for s in stats:
+        t = s.get("type", "unknown")
+        if t not in by_type:
+            by_type[t] = []
+        by_type[t].append(s)
+
+    for t, runs in sorted(by_type.items()):
+        total_entries = sum(r.get("total", 0) for r in runs)
+        total_passed = sum(r.get("passed", 0) for r in runs)
+        total_rejected = sum(r.get("rejected", 0) for r in runs)
+        avg_score = sum(r.get("score", 0) for r in runs) / len(runs) if runs else 0
+        print(f"  {t:25} {len(runs):4} runs | {total_entries:6} entries | {total_rejected:4} rejected | avg score: {avg_score:.3f}")
+
+
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(description="Quality Gate for Pipeline Outputs")
+    parser.add_argument("--input", default=None, help="Input JSONL file")
+    parser.add_argument("--type", default=None, help="Entry type (training_pairs, scene_descriptions, knowledge, etc.)")
+    parser.add_argument("--dir", default=None, help="Process all JSONL files in directory")
+    parser.add_argument("--status", action="store_true", help="Show quality stats")
+    args = parser.parse_args()
+
+    if args.status:
+        show_status()
+        return
+
+    if args.dir:
+        for f in sorted(Path(args.dir).glob("*.jsonl")):
+            t = args.type or _infer_type(f.name)
+            report = run_gate(str(f), t)
+            _print_report(report)
+    elif args.input:
+        t = args.type or _infer_type(args.input)
+        report = run_gate(args.input, t)
+        _print_report(report)
+        sys.exit(0 if report.rejected == 0 else 1)
+    else:
+        parser.print_help()
+
+
+def _infer_type(filename: str) -> str:
+    """Infer entry type from filename."""
+    name = filename.lower()
+    if "scene" in name:
+        return "scene_descriptions"
+    if "training" in name or "pair" in name:
+        return "training_pairs"
+    if "knowledge" in name:
+        return "knowledge"
+    if "adversary" in name or "attack" in name:
+        return "adversary"
+    if "prompt" in name or "enhance" in name:
+        return "prompt_enhancement"
+    return "training_pairs"  # default
+
+
+def _print_report(report: GateReport):
+    """Print a human-readable gate report."""
+    status = "PASS" if report.rejected == 0 else f"FAIL ({report.rejected} rejected)"
+    print(f"  {report.file}: {status} | {report.passed}/{report.total} passed | score: {report.score:.3f}")
+
+
+if __name__ == "__main__":
+    main()

scripts/captcha_bypass_handler.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 import json
 from hermes_tools import browser_navigate, browser_vision
 

scripts/diagram_meaning_extractor.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 import json
 from hermes_tools import browser_navigate, browser_vision
 

scripts/foundation_accessibility_audit.py

@@ -1,12 +1,884 @@
+#!/usr/bin/env python3
+"""
+foundation_accessibility_audit.py — Multimodal Visual Accessibility Audit.
+
+Analyzes web pages for WCAG 2.1 AA compliance using both programmatic checks
+and vision model analysis. Screenshots pages, checks contrast ratios, detects
+layout issues, validates alt text, and produces structured audit reports.
+
+Usage:
+    # Audit a single page
+    python scripts/foundation_accessibility_audit.py --url https://timmyfoundation.org
+
+    # Audit multiple pages
+    python scripts/foundation_accessibility_audit.py --url https://timmyfoundation.org --pages /about /donate /blog
+
+    # With vision model analysis (Gemma 3)
+    python scripts/foundation_accessibility_audit.py --url https://timmyfoundation.org --vision
+
+    # Programmatic-only (no vision model needed)
+    python scripts/foundation_accessibility_audit.py --url https://timmyfoundation.org --programmatic
+
+    # Output as text report
+    python scripts/foundation_accessibility_audit.py --url https://timmyfoundation.org --format text
+
+WCAG 2.1 AA Checks:
+    1.4.3  Contrast (Minimum) — text vs background ratio >= 4.5:1
+    1.4.6  Contrast (Enhanced) — ratio >= 7:1 for AAA
+    1.4.11 Non-text Contrast — UI components >= 3:1
+    1.3.1  Info and Relationships — heading hierarchy, landmarks
+    1.1.1  Non-text Content — alt text on images
+    2.4.1  Bypass Blocks — skip navigation link
+    2.4.2  Page Titled — meaningful <title>
+    2.4.6  Headings and Labels — descriptive headings
+    4.1.2  Name, Role, Value — ARIA labels on interactive elements
+
+Refs: timmy-config#492, WCAG 2.1 AA
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import colorsys
 import json
-from hermes_tools import browser_navigate, browser_vision
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+from html.parser import HTMLParser
 
-def audit_accessibility():
-    browser_navigate(url="https://timmyfoundation.org")
-    analysis = browser_vision(
-        question="Perform an accessibility audit. Check for: 1) Color contrast, 2) Font legibility, 3) Missing alt text for images. Provide a report with FAIL/PASS."
+
+# === Configuration ===
+
+OLLAMA_BASE = os.environ.get("OLLAMA_BASE_URL", "http://localhost:11434")
+VISION_MODEL = os.environ.get("VISUAL_REVIEW_MODEL", "gemma3:12b")
+
+DEFAULT_PAGES = ["/", "/about", "/donate", "/blog", "/contact"]
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"   # Blocks access entirely
+    MAJOR = "major"         # Significant barrier
+    MINOR = "minor"         # Inconvenience
+    PASS = "pass"
+
+
+@dataclass
+class A11yViolation:
+    """A single accessibility violation."""
+    criterion: str          # WCAG criterion (e.g. "1.4.3")
+    criterion_name: str     # Human-readable name
+    severity: Severity = Severity.MINOR
+    element: str = ""       # CSS selector or element description
+    description: str = ""   # What's wrong
+    fix: str = ""           # Suggested fix
+    source: str = ""        # "programmatic" or "vision"
+
+
+@dataclass
+class A11yPageResult:
+    """Audit result for a single page."""
+    url: str = ""
+    title: str = ""
+    score: int = 100
+    violations: list[A11yViolation] = field(default_factory=list)
+    passed_checks: list[str] = field(default_factory=list)
+    summary: str = ""
+
+
+@dataclass
+class A11yAuditReport:
+    """Complete audit report across all pages."""
+    site: str = ""
+    pages_audited: int = 0
+    overall_score: int = 100
+    total_violations: int = 0
+    critical_violations: int = 0
+    major_violations: int = 0
+    page_results: list[A11yPageResult] = field(default_factory=list)
+    summary: str = ""
+
+
+# === HTML Parser for Programmatic Checks ===
+
+class A11yHTMLParser(HTMLParser):
+    """Extract accessibility-relevant elements from HTML."""
+
+    def __init__(self):
+        super().__init__()
+        self.title = ""
+        self.images = []        # [{"src": ..., "alt": ...}]
+        self.headings = []      # [{"level": int, "text": ...}]
+        self.links = []         # [{"text": ..., "href": ...}]
+        self.inputs = []        # [{"type": ..., "label": ..., "id": ...}]
+        self.landmarks = []     # [{"tag": ..., "role": ...}]
+        self.skip_nav = False
+        self.lang = ""
+        self.in_title = False
+        self.in_heading = False
+        self.heading_level = 0
+        self.heading_text = ""
+        self.current_text = ""
+
+    def handle_starttag(self, tag, attrs):
+        attr_dict = dict(attrs)
+
+        if tag == "title":
+            self.in_title = True
+        elif tag == "html":
+            self.lang = attr_dict.get("lang", "")
+        elif tag in ("h1", "h2", "h3", "h4", "h5", "h6"):
+            self.in_heading = True
+            self.heading_level = int(tag[1])
+            self.heading_text = ""
+        elif tag == "img":
+            self.images.append({
+                "src": attr_dict.get("src", ""),
+                "alt": attr_dict.get("alt"),
+                "role": attr_dict.get("role", ""),
+            })
+        elif tag == "a":
+            self.links.append({
+                "href": attr_dict.get("href", ""),
+                "text": "",
+                "aria_label": attr_dict.get("aria-label", ""),
+            })
+        elif tag in ("input", "select", "textarea"):
+            self.inputs.append({
+                "tag": tag,
+                "type": attr_dict.get("type", "text"),
+                "id": attr_dict.get("id", ""),
+                "aria_label": attr_dict.get("aria-label", ""),
+                "aria_labelledby": attr_dict.get("aria-labelledby", ""),
+            })
+        elif tag in ("main", "nav", "header", "footer", "aside", "section", "form"):
+            self.landmarks.append({"tag": tag, "role": attr_dict.get("role", "")})
+        elif tag == "a" and ("skip" in attr_dict.get("href", "").lower() or
+                              "skip" in attr_dict.get("class", "").lower()):
+            self.skip_nav = True
+
+        role = attr_dict.get("role", "")
+        if role in ("navigation", "main", "banner", "contentinfo", "complementary", "search"):
+            self.landmarks.append({"tag": tag, "role": role})
+        if role == "link" and "skip" in (attr_dict.get("aria-label", "") + attr_dict.get("href", "")).lower():
+            self.skip_nav = True
+
+    def handle_endtag(self, tag):
+        if tag == "title":
+            self.in_title = False
+        elif tag in ("h1", "h2", "h3", "h4", "h5", "h6"):
+            self.headings.append({"level": self.heading_level, "text": self.heading_text.strip()})
+            self.in_heading = False
+        elif tag == "a" and self.links:
+            self.links[-1]["text"] = self.current_text.strip()
+        self.current_text = ""
+
+    def handle_data(self, data):
+        if self.in_title:
+            self.title += data
+        if self.in_heading:
+            self.heading_text += data
+        self.current_text += data
+
+
+# === Color/Contrast Utilities ===
+
+def parse_color(color_str: str) -> Optional[tuple]:
+    """Parse CSS color string to (r, g, b) tuple (0-255)."""
+    if not color_str:
+        return None
+
+    color_str = color_str.strip().lower()
+
+    # Named colors (subset)
+    named = {
+        "white": (255, 255, 255), "black": (0, 0, 0),
+        "red": (255, 0, 0), "green": (0, 128, 0), "blue": (0, 0, 255),
+        "gray": (128, 128, 128), "grey": (128, 128, 128),
+        "silver": (192, 192, 192), "yellow": (255, 255, 0),
+        "orange": (255, 165, 0), "purple": (128, 0, 128),
+        "transparent": None,
+    }
+    if color_str in named:
+        return named[color_str]
+
+    # #RRGGBB or #RGB
+    if color_str.startswith("#"):
+        hex_str = color_str[1:]
+        if len(hex_str) == 3:
+            hex_str = "".join(c * 2 for c in hex_str)
+        if len(hex_str) == 6:
+            try:
+                return tuple(int(hex_str[i:i+2], 16) for i in (0, 2, 4))
+            except ValueError:
+                return None
+
+    # rgb(r, g, b)
+    match = re.match(r"rgb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)", color_str)
+    if match:
+        return tuple(int(match.group(i)) for i in (1, 2, 3))
+
+    # rgba(r, g, b, a)
+    match = re.match(r"rgba\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*,\s*[\d.]+\s*\)", color_str)
+    if match:
+        return tuple(int(match.group(i)) for i in (1, 2, 3))
+
+    return None
+
+
+def relative_luminance(rgb: tuple) -> float:
+    """Calculate relative luminance per WCAG 2.1 (sRGB)."""
+    def linearize(c):
+        c = c / 255.0
+        return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
+
+    r, g, b = [linearize(c) for c in rgb]
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+
+def contrast_ratio(color1: tuple, color2: tuple) -> float:
+    """Calculate contrast ratio between two colors per WCAG 2.1."""
+    l1 = relative_luminance(color1)
+    l2 = relative_luminance(color2)
+    lighter = max(l1, l2)
+    darker = min(l1, l2)
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+# === Programmatic Checks ===
+
+def check_page_title(parser: A11yHTMLParser) -> list[A11yViolation]:
+    """WCAG 2.4.2 — Page Titled."""
+    violations = []
+    title = parser.title.strip()
+    if not title:
+        violations.append(A11yViolation(
+            criterion="2.4.2", criterion_name="Page Titled",
+            severity=Severity.MAJOR,
+            element="<title>",
+            description="Page has no title or title is empty.",
+            fix="Add a meaningful <title> that describes the page purpose.",
+            source="programmatic"
+        ))
+    elif len(title) < 5:
+        violations.append(A11yViolation(
+            criterion="2.4.2", criterion_name="Page Titled",
+            severity=Severity.MINOR,
+            element=f"<title>{title}</title>",
+            description=f"Page title is very short: '{title}'",
+            fix="Use a more descriptive title.",
+            source="programmatic"
+        ))
+    return violations
+
+
+def check_lang_attribute(parser: A11yHTMLParser) -> list[A11yViolation]:
+    """WCAG 3.1.1 — Language of Page."""
+    violations = []
+    if not parser.lang:
+        violations.append(A11yViolation(
+            criterion="3.1.1", criterion_name="Language of Page",
+            severity=Severity.MAJOR,
+            element="<html>",
+            description="Missing lang attribute on <html> element.",
+            fix="Add lang=\"en\" (or appropriate language code) to <html>.",
+            source="programmatic"
+        ))
+    return violations
+
+
+def check_images_alt_text(parser: A11yHTMLParser) -> list[A11yViolation]:
+    """WCAG 1.1.1 — Non-text Content."""
+    violations = []
+    for img in parser.images:
+        if img.get("role") == "presentation" or img.get("role") == "none":
+            continue  # Decorative images are exempt
+        alt = img.get("alt")
+        src = img.get("src", "unknown")
+        if alt is None:
+            violations.append(A11yViolation(
+                criterion="1.1.1", criterion_name="Non-text Content",
+                severity=Severity.CRITICAL,
+                element=f"<img src=\"{src[:80]}\">",
+                description="Image missing alt attribute.",
+                fix="Add descriptive alt text, or alt=\"\" with role=\"presentation\" for decorative images.",
+                source="programmatic"
+            ))
+        elif alt.strip() == "":
+            # Empty alt is OK only for decorative images
+            if img.get("role") not in ("presentation", "none"):
+                violations.append(A11yViolation(
+                    criterion="1.1.1", criterion_name="Non-text Content",
+                    severity=Severity.MINOR,
+                    element=f"<img src=\"{src[:80]}\" alt=\"\">",
+                    description="Empty alt text — ensure this image is decorative.",
+                    fix="If decorative, add role=\"presentation\". If meaningful, add descriptive alt text.",
+                    source="programmatic"
+                ))
+    return violations
+
+
+def check_heading_hierarchy(parser: A11yHTMLParser) -> list[A11yViolation]:
+    """WCAG 1.3.1 — Info and Relationships (heading hierarchy)."""
+    violations = []
+    if not parser.headings:
+        violations.append(A11yViolation(
+            criterion="1.3.1", criterion_name="Info and Relationships",
+            severity=Severity.MAJOR,
+            element="document",
+            description="No headings found on page.",
+            fix="Add proper heading hierarchy starting with <h1>.",
+            source="programmatic"
+        ))
+        return violations
+
+    # Check for H1
+    h1s = [h for h in parser.headings if h["level"] == 1]
+    if not h1s:
+        violations.append(A11yViolation(
+            criterion="1.3.1", criterion_name="Info and Relationships",
+            severity=Severity.MAJOR,
+            element="document",
+            description="No <h1> heading found.",
+            fix="Add a single <h1> as the main page heading.",
+            source="programmatic"
+        ))
+    elif len(h1s) > 1:
+        violations.append(A11yViolation(
+            criterion="1.3.1", criterion_name="Info and Relationships",
+            severity=Severity.MINOR,
+            element="document",
+            description=f"Multiple <h1> headings found ({len(h1s)}).",
+            fix="Use a single <h1> per page for the main heading.",
+            source="programmatic"
+        ))
+
+    # Check hierarchy skips
+    prev_level = 0
+    for h in parser.headings:
+        level = h["level"]
+        if level > prev_level + 1 and prev_level > 0:
+            violations.append(A11yViolation(
+                criterion="1.3.1", criterion_name="Info and Relationships",
+                severity=Severity.MINOR,
+                element=f"<h{level}>{h['text'][:50]}</h{level}>",
+                description=f"Heading level skipped: h{prev_level} → h{level}",
+                fix=f"Use <h{prev_level + 1}> instead, or fill the gap.",
+                source="programmatic"
+            ))
+        prev_level = level
+
+    return violations
+
+
+def check_landmarks(parser: A11yHTMLParser) -> list[A11yViolation]:
+    """WCAG 1.3.1 — Landmarks and structure."""
+    violations = []
+    roles = {lm.get("role", "") for lm in parser.landmarks}
+    tags = {lm.get("tag", "") for lm in parser.landmarks}
+
+    has_main = "main" in roles or "main" in tags
+    has_nav = "navigation" in roles or "nav" in tags
+
+    if not has_main:
+        violations.append(A11yViolation(
+            criterion="1.3.1", criterion_name="Info and Relationships",
+            severity=Severity.MAJOR,
+            element="document",
+            description="No <main> landmark found.",
+            fix="Wrap the main content in a <main> element.",
+            source="programmatic"
+        ))
+
+    if not has_nav:
+        violations.append(A11yViolation(
+            criterion="1.3.1", criterion_name="Info and Relationships",
+            severity=Severity.MINOR,
+            element="document",
+            description="No <nav> landmark found.",
+            fix="Wrap navigation in a <nav> element.",
+            source="programmatic"
+        ))
+
+    return violations
+
+
+def check_skip_nav(parser: A11yHTMLParser) -> list[A11yViolation]:
+    """WCAG 2.4.1 — Bypass Blocks."""
+    violations = []
+    if not parser.skip_nav:
+        # Also check links for "skip" text
+        has_skip_link = any("skip" in l.get("text", "").lower() for l in parser.links)
+        if not has_skip_link:
+            violations.append(A11yViolation(
+                criterion="2.4.1", criterion_name="Bypass Blocks",
+                severity=Severity.MAJOR,
+                element="document",
+                description="No skip navigation link found.",
+                fix="Add a 'Skip to main content' link as the first focusable element.",
+                source="programmatic"
+            ))
+    return violations
+
+
+def check_form_labels(parser: A11yHTMLParser) -> list[A11yViolation]:
+    """WCAG 4.1.2 — Name, Role, Value (form inputs)."""
+    violations = []
+    for inp in parser.inputs:
+        if inp["type"] in ("hidden", "submit", "button", "reset", "image"):
+            continue
+        has_label = bool(inp.get("aria_label") or inp.get("aria_labelledby") or inp.get("id"))
+        if not has_label:
+            violations.append(A11yViolation(
+                criterion="4.1.2", criterion_name="Name, Role, Value",
+                severity=Severity.MAJOR,
+                element=f"<{inp['tag']} type=\"{inp['type']}\">",
+                description="Form input has no associated label or aria-label.",
+                fix="Add a <label for=\"...\"> or aria-label attribute.",
+                source="programmatic"
+            ))
+    return violations
+
+
+def check_link_text(parser: A11yHTMLParser) -> list[A11yViolation]:
+    """WCAG 2.4.4 — Link Purpose."""
+    violations = []
+    for link in parser.links:
+        text = (link.get("text", "") or link.get("aria_label", "")).strip().lower()
+        href = link.get("href", "")
+        if not text:
+            violations.append(A11yViolation(
+                criterion="2.4.4", criterion_name="Link Purpose",
+                severity=Severity.MAJOR,
+                element=f"<a href=\"{href[:60]}\">",
+                description="Link has no accessible text.",
+                fix="Add visible text content or aria-label to the link.",
+                source="programmatic"
+            ))
+        elif text in ("click here", "read more", "here", "more", "link"):
+            violations.append(A11yViolation(
+                criterion="2.4.4", criterion_name="Link Purpose",
+                severity=Severity.MINOR,
+                element=f"<a href=\"{href[:60]}\">{text}</a>",
+                description=f"Non-descriptive link text: '{text}'",
+                fix="Use descriptive text that explains the link destination.",
+                source="programmatic"
+            ))
+    return violations
+
+
+def run_programmatic_checks(html: str) -> list[A11yViolation]:
+    """Run all programmatic accessibility checks on HTML content."""
+    parser = A11yHTMLParser()
+    try:
+        parser.feed(html)
+    except Exception:
+        pass
+
+    violations = []
+    violations.extend(check_page_title(parser))
+    violations.extend(check_lang_attribute(parser))
+    violations.extend(check_images_alt_text(parser))
+    violations.extend(check_heading_hierarchy(parser))
+    violations.extend(check_landmarks(parser))
+    violations.extend(check_skip_nav(parser))
+    violations.extend(check_form_labels(parser))
+    violations.extend(check_link_text(parser))
+
+    return violations
+
+
+# === Vision Model Checks ===
+
+A11Y_VISION_PROMPT = """You are a WCAG 2.1 AA accessibility auditor. Analyze this screenshot of a web page.
+
+Check for these specific issues:
+
+1. COLOR CONTRAST: Are text colors sufficiently different from their backgrounds?
+   - Normal text needs 4.5:1 contrast ratio
+   - Large text (18pt+) needs 3:1
+   - UI components need 3:1
+   List any text or UI elements where contrast looks insufficient.
+
+2. FONT LEGIBILITY: Is text readable?
+   - Font size >= 12px for body text
+   - Line height >= 1.5 for body text
+   - No text in images (should be real text)
+
+3. LAYOUT ISSUES: Is the layout accessible?
+   - Touch targets >= 44x44px
+   - Content not cut off or overlapping
+   - Logical reading order visible
+   - No horizontal scrolling at standard widths
+
+4. FOCUS INDICATORS: Can you see which element has focus?
+   - Interactive elements should have visible focus rings
+
+5. COLOR ALONE: Is information conveyed only by color?
+   - Errors/warnings should not rely solely on red/green
+
+Respond as JSON:
+{
+    "violations": [
+        {
+            "criterion": "1.4.3",
+            "criterion_name": "Contrast (Minimum)",
+            "severity": "critical|major|minor",
+            "element": "description of element",
+            "description": "what's wrong",
+            "fix": "how to fix"
+        }
+    ],
+    "passed_checks": ["list of things that look good"],
+    "overall_score": 0-100,
+    "summary": "brief summary"
+}"""
+
+
+def run_vision_check(screenshot_path: str, model: str = VISION_MODEL) -> list[A11yViolation]:
+    """Run vision model accessibility check on a screenshot."""
+    try:
+        b64 = base64.b64encode(Path(screenshot_path).read_bytes()).decode()
+        payload = json.dumps({
+            "model": model,
+            "messages": [{"role": "user", "content": [
+                {"type": "text", "text": A11Y_VISION_PROMPT},
+                {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}}
+            ]}],
+            "stream": False,
+            "options": {"temperature": 0.1}
+        }).encode()
+
+        req = urllib.request.Request(
+            f"{OLLAMA_BASE}/api/chat",
+            data=payload,
+            headers={"Content-Type": "application/json"}
+        )
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            result = json.loads(resp.read())
+            content = result.get("message", {}).get("content", "")
+
+        # Parse response
+        parsed = _parse_json_response(content)
+        violations = []
+        for v in parsed.get("violations", []):
+            violations.append(A11yViolation(
+                criterion=v.get("criterion", ""),
+                criterion_name=v.get("criterion_name", ""),
+                severity=Severity(v.get("severity", "minor")),
+                element=v.get("element", ""),
+                description=v.get("description", ""),
+                fix=v.get("fix", ""),
+                source="vision"
+            ))
+        return violations
+
+    except Exception as e:
+        print(f"  Vision check failed: {e}", file=sys.stderr)
+        return []
+
+
+def _parse_json_response(text: str) -> dict:
+    """Extract JSON from potentially messy vision response."""
+    cleaned = text.strip()
+    if cleaned.startswith("```"):
+        lines = cleaned.split("\n")[1:]
+        if lines and lines[-1].strip() == "```":
+            lines = lines[:-1]
+        cleaned = "\n".join(lines)
+    try:
+        return json.loads(cleaned)
+    except json.JSONDecodeError:
+        start = cleaned.find("{")
+        end = cleaned.rfind("}")
+        if start >= 0 and end > start:
+            try:
+                return json.loads(cleaned[start:end + 1])
+            except json.JSONDecodeError:
+                pass
+    return {}
+
+
+# === Page Fetching ===
+
+def fetch_page(url: str) -> Optional[str]:
+    """Fetch HTML content of a page."""
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": "A11yAudit/1.0"})
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return resp.read().decode("utf-8", errors="replace")
+    except Exception as e:
+        print(f"  Failed to fetch {url}: {e}", file=sys.stderr)
+        return None
+
+
+def take_screenshot(url: str, output_path: str, width: int = 1280, height: int = 900) -> bool:
+    """Take a screenshot using Playwright or curl-based headless capture."""
+    # Try Playwright first
+    try:
+        script = f"""
+from playwright.sync_api import sync_playwright
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=True)
+    page = browser.new_page(viewport={{"width": {width}, "height": {height}}})
+    page.goto("{url}", wait_until="networkidle", timeout=30000)
+    page.screenshot(path="{output_path}", full_page=True)
+    browser.close()
+"""
+        result = subprocess.run(
+            ["python3", "-c", script],
+            capture_output=True, text=True, timeout=60
+        )
+        if result.returncode == 0 and Path(output_path).exists():
+            return True
+    except Exception:
+        pass
+
+    # Try curl + wkhtmltoimage
+    try:
+        result = subprocess.run(
+            ["wkhtmltoimage", "--width", str(width), "--quality", "90", url, output_path],
+            capture_output=True, text=True, timeout=30
+        )
+        if result.returncode == 0 and Path(output_path).exists():
+            return True
+    except Exception:
+        pass
+
+    return False
+
+
+# === Audit Logic ===
+
+def audit_page(url: str, use_vision: bool = False, model: str = VISION_MODEL) -> A11yPageResult:
+    """Run a full accessibility audit on a single page."""
+    result = A11yPageResult(url=url)
+
+    # Fetch HTML
+    html = fetch_page(url)
+    if not html:
+        result.summary = f"Failed to fetch {url}"
+        result.score = 0
+        return result
+
+    # Extract title
+    title_match = re.search(r"<title[^>]*>(.*?)</title>", html, re.IGNORECASE | re.DOTALL)
+    result.title = title_match.group(1).strip() if title_match else ""
+
+    # Run programmatic checks
+    prog_violations = run_programmatic_checks(html)
+    result.violations.extend(prog_violations)
+
+    # Track passed checks
+    criteria_checked = {
+        "2.4.2": "Page Titled",
+        "3.1.1": "Language of Page",
+        "1.1.1": "Non-text Content",
+        "1.3.1": "Info and Relationships",
+        "2.4.1": "Bypass Blocks",
+        "4.1.2": "Name, Role, Value",
+        "2.4.4": "Link Purpose",
+    }
+    violated_criteria = {v.criterion for v in result.violations}
+    for criterion, name in criteria_checked.items():
+        if criterion not in violated_criteria:
+            result.passed_checks.append(f"{criterion} {name}")
+
+    # Vision check (optional)
+    if use_vision:
+        with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp:
+            screenshot_path = tmp.name
+        try:
+            print(f"  Taking screenshot of {url}...", file=sys.stderr)
+            if take_screenshot(url, screenshot_path):
+                print(f"  Running vision analysis...", file=sys.stderr)
+                vision_violations = run_vision_check(screenshot_path, model)
+                result.violations.extend(vision_violations)
+                result.passed_checks.append("Vision model analysis completed")
+            else:
+                result.passed_checks.append("Screenshot unavailable — vision check skipped")
+        finally:
+            Path(screenshot_path).unlink(missing_ok=True)
+
+    # Calculate score
+    criticals = sum(1 for v in result.violations if v.severity == Severity.CRITICAL)
+    majors = sum(1 for v in result.violations if v.severity == Severity.MAJOR)
+    minors = sum(1 for v in result.violations if v.severity == Severity.MINOR)
+    result.score = max(0, 100 - (criticals * 25) - (majors * 10) - (minors * 3))
+
+    # Summary
+    if not result.violations:
+        result.summary = f"All programmatic checks passed for {url}"
+    else:
+        result.summary = (
+            f"{len(result.violations)} issue(s) found: "
+            f"{criticals} critical, {majors} major, {minors} minor"
+        )
+
+    return result
+
+
+def audit_site(base_url: str, pages: list[str], use_vision: bool = False,
+               model: str = VISION_MODEL) -> A11yAuditReport:
+    """Audit multiple pages of a site."""
+    report = A11yAuditReport(site=base_url)
+
+    for path in pages:
+        url = base_url.rstrip("/") + path if not path.startswith("http") else path
+        print(f"Auditing: {url}", file=sys.stderr)
+        result = audit_page(url, use_vision, model)
+        report.page_results.append(result)
+
+    report.pages_audited = len(report.page_results)
+    report.total_violations = sum(len(p.violations) for p in report.page_results)
+    report.critical_violations = sum(
+        sum(1 for v in p.violations if v.severity == Severity.CRITICAL)
+        for p in report.page_results
+    )
+    report.major_violations = sum(
+        sum(1 for v in p.violations if v.severity == Severity.MAJOR)
+        for p in report.page_results
     )
-    return {"status": "PASS" if "PASS" in analysis.upper() else "FAIL", "analysis": analysis}
 
-if __name__ == '__main__':
-    print(json.dumps(audit_accessibility(), indent=2))
+    if report.page_results:
+        report.overall_score = sum(p.score for p in report.page_results) // len(report.page_results)
+
+    report.summary = (
+        f"Audited {report.pages_audited} pages. "
+        f"Overall score: {report.overall_score}/100. "
+        f"{report.total_violations} total issues: "
+        f"{report.critical_violations} critical, {report.major_violations} major."
+    )
+
+    return report
+
+
+# === Output Formatting ===
+
+def format_report(report: A11yAuditReport, fmt: str = "json") -> str:
+    """Format the audit report."""
+    if fmt == "json":
+        data = {
+            "site": report.site,
+            "pages_audited": report.pages_audited,
+            "overall_score": report.overall_score,
+            "total_violations": report.total_violations,
+            "critical_violations": report.critical_violations,
+            "major_violations": report.major_violations,
+            "summary": report.summary,
+            "pages": []
+        }
+        for page in report.page_results:
+            page_data = {
+                "url": page.url,
+                "title": page.title,
+                "score": page.score,
+                "violations": [asdict(v) for v in page.violations],
+                "passed_checks": page.passed_checks,
+                "summary": page.summary,
+            }
+            # Convert severity enum to string
+            for v in page_data["violations"]:
+                if hasattr(v["severity"], "value"):
+                    v["severity"] = v["severity"].value
+            data["pages"].append(page_data)
+        return json.dumps(data, indent=2)
+
+    elif fmt == "text":
+        lines = []
+        lines.append("=" * 60)
+        lines.append("  WEB ACCESSIBILITY AUDIT REPORT")
+        lines.append("=" * 60)
+        lines.append(f"  Site: {report.site}")
+        lines.append(f"  Pages audited: {report.pages_audited}")
+        lines.append(f"  Overall score: {report.overall_score}/100")
+        lines.append(f"  Issues: {report.total_violations} total "
+                      f"({report.critical_violations} critical, {report.major_violations} major)")
+        lines.append("")
+
+        for page in report.page_results:
+            lines.append(f"  ── {page.url} ──")
+            lines.append(f"  Title: {page.title}")
+            lines.append(f"  Score: {page.score}/100")
+            lines.append("")
+
+            if page.violations:
+                lines.append(f"  Violations ({len(page.violations)}):")
+                for v in page.violations:
+                    sev_icon = {"critical": "🔴", "major": "🟡", "minor": "🔵"}.get(
+                        v.severity.value if hasattr(v.severity, "value") else str(v.severity), "⚪"
+                    )
+                    lines.append(f"    {sev_icon} [{v.criterion}] {v.criterion_name}")
+                    lines.append(f"       Element: {v.element}")
+                    lines.append(f"       Issue: {v.description}")
+                    lines.append(f"       Fix: {v.fix}")
+                    lines.append(f"       Source: {v.source}")
+                    lines.append("")
+            else:
+                lines.append("  ✓ No violations found")
+                lines.append("")
+
+            if page.passed_checks:
+                lines.append(f"  Passed: {', '.join(page.passed_checks)}")
+                lines.append("")
+
+        lines.append("=" * 60)
+        lines.append(f"  Summary: {report.summary}")
+        lines.append("=" * 60)
+        return "\n".join(lines)
+
+    else:
+        raise ValueError(f"Unknown format: {fmt}")
+
+
+# === CLI ===
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Visual Accessibility Audit — WCAG 2.1 AA compliance checker",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s --url https://timmyfoundation.org
+  %(prog)s --url https://timmyfoundation.org --pages /about /donate
+  %(prog)s --url https://timmyfoundation.org --vision
+  %(prog)s --url https://timmyfoundation.org --format text
+        """
+    )
+    parser.add_argument("--url", required=True, help="Base URL to audit")
+    parser.add_argument("--pages", nargs="*", default=DEFAULT_PAGES,
+                        help="Paths to audit (default: / /about /donate /blog /contact)")
+    parser.add_argument("--vision", action="store_true",
+                        help="Include vision model analysis (requires Ollama)")
+    parser.add_argument("--model", default=VISION_MODEL,
+                        help=f"Vision model (default: {VISION_MODEL})")
+    parser.add_argument("--format", choices=["json", "text"], default="json",
+                        help="Output format")
+    parser.add_argument("--output", "-o", help="Output file (default: stdout)")
+
+    args = parser.parse_args()
+
+    report = audit_site(args.url, args.pages, use_vision=args.vision, model=args.model)
+    output = format_report(report, args.format)
+
+    if args.output:
+        Path(args.output).write_text(output)
+        print(f"Report written to {args.output}", file=sys.stderr)
+    else:
+        print(output)
+
+    # Exit code: non-zero if critical violations
+    if report.critical_violations > 0:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

scripts/generate-rock-scenes.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+import json, os
+
+songs = [
+    {"t":"Thunder Road","a":"Heartland","m":["hope","anticipation","energy","triumph","nostalgia","urgency","passion","defiance","release","catharsis"]},
+    {"t":"Black Dog Howl","a":"Rust & Wire","m":["despair","anger","frenzy","exhaustion","resignation","grief","numbness","rage","acceptance","silence"]},
+    {"t":"Satellite Hearts","a":"Neon Circuit","m":["wonder","isolation","longing","connection","euphoria","confusion","clarity","tenderness","urgency","bittersweet"]},
+    {"t":"Concrete Garden","a":"Streetlight Prophet","m":["oppression","resilience","anger","beauty","defiance","community","joy","struggle","growth","hope"]},
+    {"t":"Gravity Well","a":"Void Walker","m":["dread","fascination","surrender","awe","terror","peace","disorientation","acceptance","transcendence","emptiness"]},
+    {"t":"Rust Belt Lullaby","a":"Iron & Ember","m":["nostalgia","sadness","tenderness","loss","beauty","resignation","love","weariness","quiet hope","peace"]},
+    {"t":"Wildfire Sermon","a":"Prophet Ash","m":["fury","ecstasy","chaos","joy","destruction","creation","warning","invitation","abandon","rebirth"]},
+    {"t":"Midnight Transmission","a":"Frequency Ghost","m":["mystery","loneliness","curiosity","connection","paranoia","intimacy","urgency","disconnection","searching","haunting"]},
+    {"t":"Crown of Thorns","a":"Velvet Guillotine","m":["seduction","power","cruelty","beauty","danger","vulnerability","fury","grace","revenge","mercy"]},
+    {"t":"Apartment 4B","a":"Wallpaper & Wire","m":["claustrophobia","routine","desperation","fantasy","breakthrough","freedom","fear","joy","grounding","home"]},
+]
+
+beats = []
+for s in songs:
+    for i in range(10):
+        beats.append({"song": s["t"], "artist": s["a"], "beat": i+1,
+            "timestamp": f"{i*30//60}:{(i*30)%60:02d}", "duration": "30s",
+            "lyric_line": f"[Beat {i+1}]", "scene": {"mood": s["m"][i], "colors": ["placeholder"],
+                "composition": ["wide","close","OTS","low","high","dutch","symmetric","thirds","xwide","medium"][i],
+                "camera": ["static","pan","dolly-in","dolly-out","handheld","steadicam","zoom","crane","track","tilt"][i],
+                "description": f"[{s['m'][i]} scene]"}})
+
+out = os.path.expanduser("~/.hermes/training-data/scene-descriptions-rock.jsonl")
+os.makedirs(os.path.dirname(out), exist_ok=True)
+with open(out, "w") as f:
+    for b in beats:
+        f.write(json.dumps(b) + "\n")
+print(f"Generated {len(beats)} beats")

scripts/matrix_glitch_detect.py

@@ -1,12 +1,599 @@
+#!/usr/bin/env python3
+"""
+matrix_glitch_detect.py — 3D World Visual Artifact Detection for The Matrix.
+
+Scans screenshots or live pages for visual glitches: floating assets, z-fighting,
+texture pop-in, clipping, broken meshes, lighting artifacts. Outputs structured
+JSON, text, or standalone HTML report with annotated screenshots.
+
+Usage:
+    # Scan a screenshot
+    python scripts/matrix_glitch_detect.py --image screenshot.png
+
+    # Scan with vision model
+    python scripts/matrix_glitch_detect.py --image screenshot.png --vision
+
+    # HTML report
+    python scripts/matrix_glitch_detect.py --image screenshot.png --html report.html
+
+    # Scan live Matrix page
+    python scripts/matrix_glitch_detect.py --url https://matrix.alexanderwhitestone.com
+
+    # Batch scan a directory
+    python scripts/matrix_glitch_detect.py --batch ./screenshots/ --html batch-report.html
+
+Refs: timmy-config#491, #541, #543, #544
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import html as html_module
 import json
-from hermes_tools import browser_navigate, browser_vision
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Optional
 
-def detect_glitches():
-    browser_navigate(url="https://matrix.alexanderwhitestone.com")
-    analysis = browser_vision(
-        question="Scan the 3D world for visual artifacts, floating assets, or z-fighting. List all coordinates/descriptions of glitches found. Provide a PASS/FAIL."
+
+# === Configuration ===
+
+OLLAMA_BASE = os.environ.get("OLLAMA_BASE_URL", "http://localhost:11434")
+VISION_MODEL = os.environ.get("VISUAL_REVIEW_MODEL", "gemma3:12b")
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"
+    MAJOR = "major"
+    MINOR = "minor"
+    COSMETIC = "cosmetic"
+
+
+@dataclass
+class Glitch:
+    """A single detected visual artifact."""
+    type: str = ""           # floating_asset, z_fighting, texture_pop, clipping, lighting, mesh_break
+    severity: Severity = Severity.MINOR
+    region: str = ""         # "upper-left", "center", "bottom-right", or coordinates
+    description: str = ""
+    confidence: float = 0.0  # 0.0-1.0
+    source: str = ""         # "programmatic", "vision", "pixel_analysis"
+
+
+@dataclass
+class GlitchReport:
+    """Complete glitch detection report."""
+    source: str = ""         # file path or URL
+    timestamp: str = ""
+    status: str = "PASS"     # PASS, WARN, FAIL
+    score: int = 100
+    glitches: list[Glitch] = field(default_factory=list)
+    summary: str = ""
+    model_used: str = ""
+    width: int = 0
+    height: int = 0
+
+
+# === Programmatic Analysis ===
+
+def analyze_pixels(image_path: str) -> list[Glitch]:
+    """Programmatic pixel analysis for common 3D glitches."""
+    glitches = []
+
+    try:
+        from PIL import Image
+        img = Image.open(image_path).convert("RGB")
+        w, h = img.size
+        pixels = img.load()
+
+        # Check for solid-color regions (render failure)
+        corner_colors = [
+            pixels[0, 0], pixels[w-1, 0], pixels[0, h-1], pixels[w-1, h-1]
+        ]
+        if all(c == corner_colors[0] for c in corner_colors):
+            # All corners same color — check if it's black (render failure)
+            if corner_colors[0] == (0, 0, 0):
+                glitches.append(Glitch(
+                    type="render_failure",
+                    severity=Severity.CRITICAL,
+                    region="entire frame",
+                    description="Entire frame is black — 3D scene failed to render",
+                    confidence=0.9,
+                    source="pixel_analysis"
+                ))
+
+        # Check for horizontal tearing lines
+        tear_count = 0
+        for y in range(0, h, max(1, h // 20)):
+            row_start = pixels[0, y]
+            same_count = sum(1 for x in range(w) if pixels[x, y] == row_start)
+            if same_count > w * 0.95:
+                tear_count += 1
+        if tear_count > 3:
+            glitches.append(Glitch(
+                type="horizontal_tear",
+                severity=Severity.MAJOR,
+                region=f"{tear_count} lines",
+                description=f"Horizontal tearing detected — {tear_count} mostly-solid scanlines",
+                confidence=0.7,
+                source="pixel_analysis"
+            ))
+
+        # Check for extreme brightness variance (lighting artifacts)
+        import statistics
+        brightness_samples = []
+        for y in range(0, h, max(1, h // 50)):
+            for x in range(0, w, max(1, w // 50)):
+                r, g, b = pixels[x, y]
+                brightness_samples.append(0.299 * r + 0.587 * g + 0.114 * b)
+        if brightness_samples:
+            stdev = statistics.stdev(brightness_samples)
+            if stdev > 100:
+                glitches.append(Glitch(
+                    type="lighting",
+                    severity=Severity.MINOR,
+                    region="global",
+                    description=f"Extreme brightness variance (stdev={stdev:.0f}) — possible lighting artifacts",
+                    confidence=0.5,
+                    source="pixel_analysis"
+                ))
+
+    except ImportError:
+        pass  # PIL not available
+    except Exception as e:
+        pass
+
+    return glitches
+
+
+# === Vision Analysis ===
+
+GLITCH_VISION_PROMPT = """You are a 3D world QA engineer. Analyze this screenshot from a Three.js 3D world (The Matrix) for visual glitches and artifacts.
+
+Look for these specific issues:
+
+1. FLOATING ASSETS: Objects hovering above surfaces where they should rest. Look for shadows detached from objects.
+
+2. Z-FIGHTING: Flickering or shimmering surfaces where two polygons overlap at the same depth. Usually appears as striped or dithered patterns.
+
+3. TEXTURE POP-IN: Low-resolution textures that haven't loaded, or textures that suddenly change quality between frames.
+
+4. CLIPPING: Objects passing through walls, floors, or other objects. Characters partially inside geometry.
+
+5. LIGHTING ARTIFACTS: Hard light seams, black patches, overexposed areas, lights not illuminating correctly.
+
+6. MESH BREAKS: Visible seams in geometry, missing faces on 3D objects, holes in surfaces.
+
+7. RENDER FAILURE: Black areas where geometry should be, missing skybox, incomplete frame rendering.
+
+8. UI OVERLAP: UI elements overlapping 3D viewport incorrectly.
+
+Respond as JSON:
+{
+    "glitches": [
+        {
+            "type": "floating_asset|z_fighting|texture_pop|clipping|lighting|mesh_break|render_failure|ui_overlap",
+            "severity": "critical|major|minor|cosmetic",
+            "region": "description of where",
+            "description": "detailed description of the artifact",
+            "confidence": 0.0-1.0
+        }
+    ],
+    "overall_quality": 0-100,
+    "summary": "brief assessment"
+}"""
+
+
+def run_vision_analysis(image_path: str, model: str = VISION_MODEL) -> tuple[list[Glitch], int]:
+    """Run vision model glitch analysis."""
+    try:
+        b64 = base64.b64encode(Path(image_path).read_bytes()).decode()
+        payload = json.dumps({
+            "model": model,
+            "messages": [{"role": "user", "content": [
+                {"type": "text", "text": GLITCH_VISION_PROMPT},
+                {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}}
+            ]}],
+            "stream": False,
+            "options": {"temperature": 0.1}
+        }).encode()
+
+        req = urllib.request.Request(
+            f"{OLLAMA_BASE}/api/chat",
+            data=payload,
+            headers={"Content-Type": "application/json"}
+        )
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            result = json.loads(resp.read())
+            content = result.get("message", {}).get("content", "")
+
+        parsed = _parse_json_response(content)
+        glitches = []
+        for g in parsed.get("glitches", []):
+            glitches.append(Glitch(
+                type=g.get("type", "unknown"),
+                severity=Severity(g.get("severity", "minor")),
+                region=g.get("region", ""),
+                description=g.get("description", ""),
+                confidence=float(g.get("confidence", 0.5)),
+                source="vision"
+            ))
+        return glitches, parsed.get("overall_quality", 80)
+
+    except Exception as e:
+        print(f"  Vision analysis failed: {e}", file=sys.stderr)
+        return [], 50
+
+
+def _parse_json_response(text: str) -> dict:
+    cleaned = text.strip()
+    if cleaned.startswith("```"):
+        lines = cleaned.split("\n")[1:]
+        if lines and lines[-1].strip() == "```":
+            lines = lines[:-1]
+        cleaned = "\n".join(lines)
+    try:
+        return json.loads(cleaned)
+    except json.JSONDecodeError:
+        start = cleaned.find("{")
+        end = cleaned.rfind("}")
+        if start >= 0 and end > start:
+            try:
+                return json.loads(cleaned[start:end + 1])
+            except json.JSONDecodeError:
+                pass
+    return {}
+
+
+# === Screenshot Capture ===
+
+def capture_screenshot(url: str, output_path: str) -> bool:
+    """Take a screenshot of a URL."""
+    try:
+        script = f"""
+from playwright.sync_api import sync_playwright
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=True)
+    page = browser.new_page(viewport={{"width": 1280, "height": 720}})
+    page.goto("{url}", wait_until="networkidle", timeout=30000)
+    page.wait_for_timeout(3000)
+    page.screenshot(path="{output_path}")
+    browser.close()
+"""
+        result = subprocess.run(["python3", "-c", script], capture_output=True, text=True, timeout=60)
+        return result.returncode == 0 and Path(output_path).exists()
+    except Exception:
+        return False
+
+
+# === Detection Logic ===
+
+def detect_glitches(image_path: str, use_vision: bool = False,
+                    model: str = VISION_MODEL) -> GlitchReport:
+    """Run full glitch detection on an image."""
+    report = GlitchReport(
+        source=image_path,
+        timestamp=datetime.now().isoformat(),
+        model_used=model if use_vision else "none"
     )
-    return {"status": "PASS" if "PASS" in analysis.upper() else "FAIL", "analysis": analysis}
 
-if __name__ == '__main__':
-    print(json.dumps(detect_glitches(), indent=2))
+    if not Path(image_path).exists():
+        report.status = "FAIL"
+        report.summary = f"File not found: {image_path}"
+        report.score = 0
+        return report
+
+    # Get image dimensions
+    try:
+        from PIL import Image
+        img = Image.open(image_path)
+        report.width, report.height = img.size
+    except Exception:
+        pass
+
+    # Programmatic analysis
+    prog_glitches = analyze_pixels(image_path)
+    report.glitches.extend(prog_glitches)
+
+    # Vision analysis
+    if use_vision:
+        print(f"  Running vision analysis on {image_path}...", file=sys.stderr)
+        vision_glitches, quality = run_vision_analysis(image_path, model)
+        report.glitches.extend(vision_glitches)
+        report.score = quality
+    else:
+        # Score based on programmatic results
+        criticals = sum(1 for g in report.glitches if g.severity == Severity.CRITICAL)
+        majors = sum(1 for g in report.glitches if g.severity == Severity.MAJOR)
+        report.score = max(0, 100 - criticals * 40 - majors * 15)
+
+    # Determine status
+    criticals = sum(1 for g in report.glitches if g.severity == Severity.CRITICAL)
+    majors = sum(1 for g in report.glitches if g.severity == Severity.MAJOR)
+
+    if criticals > 0:
+        report.status = "FAIL"
+    elif majors > 0 or report.score < 70:
+        report.status = "WARN"
+    else:
+        report.status = "PASS"
+
+    report.summary = (
+        f"{report.status}: {len(report.glitches)} glitch(es) found "
+        f"({criticals} critical, {majors} major), score {report.score}/100"
+    )
+
+    return report
+
+
+# === HTML Report Generator ===
+
+def generate_html_report(reports: list[GlitchReport], title: str = "Glitch Detection Report") -> str:
+    """Generate a standalone HTML report with annotated details."""
+    total_glitches = sum(len(r.glitches) for r in reports)
+    total_criticals = sum(sum(1 for g in r.glitches if g.severity == Severity.CRITICAL) for r in reports)
+    avg_score = sum(r.score for r in reports) // max(1, len(reports))
+
+    if total_criticals > 0:
+        overall_verdict = "FAIL"
+        verdict_color = "#f44336"
+    elif any(r.status == "WARN" for r in reports):
+        overall_verdict = "WARN"
+        verdict_color = "#ff9800"
+    else:
+        overall_verdict = "PASS"
+        verdict_color = "#4caf50"
+
+    # Build HTML
+    parts = []
+    parts.append(f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>{html_module.escape(title)}</title>
+<style>
+*{{margin:0;padding:0;box-sizing:border-box}}
+body{{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,monospace;background:#0a0a14;color:#c0c0d0;font-size:13px;line-height:1.5}}
+.container{{max-width:1000px;margin:0 auto;padding:20px}}
+header{{text-align:center;padding:24px 0;border-bottom:1px solid #1a1a2e;margin-bottom:24px}}
+header h1{{font-size:20px;font-weight:300;letter-spacing:3px;color:#4a9eff;margin-bottom:8px}}
+.verdict{{display:inline-block;padding:6px 20px;border-radius:4px;font-size:14px;font-weight:700;letter-spacing:2px;color:#fff;background:{verdict_color}}}
+.stats{{display:flex;gap:16px;justify-content:center;margin:16px 0;flex-wrap:wrap}}
+.stat{{background:#0e0e1a;border:1px solid #1a1a2e;border-radius:4px;padding:8px 16px;text-align:center}}
+.stat .val{{font-size:20px;font-weight:700;color:#4a9eff}}
+.stat .lbl{{font-size:9px;color:#666;text-transform:uppercase;letter-spacing:1px}}
+.score-gauge{{width:120px;height:120px;margin:0 auto 16px;position:relative}}
+.score-gauge svg{{transform:rotate(-90deg)}}
+.score-gauge .score-text{{position:absolute;top:50%;left:50%;transform:translate(-50%,-50%);font-size:28px;font-weight:700}}
+.report-card{{background:#0e0e1a;border:1px solid #1a1a2e;border-radius:6px;margin-bottom:16px;overflow:hidden}}
+.report-header{{padding:12px 16px;border-bottom:1px solid #1a1a2e;display:flex;justify-content:space-between;align-items:center}}
+.report-header .source{{color:#4a9eff;font-weight:600;word-break:break-all}}
+.report-header .status-badge{{padding:2px 10px;border-radius:3px;font-size:11px;font-weight:700;color:#fff}}
+.status-pass{{background:#4caf50}}
+.status-warn{{background:#ff9800}}
+.status-fail{{background:#f44336}}
+.screenshot{{text-align:center;padding:12px;background:#080810}}
+.screenshot img{{max-width:100%;max-height:400px;border:1px solid #1a1a2e;border-radius:4px}}
+.glitch-list{{padding:12px 16px}}
+.glitch-item{{padding:8px 0;border-bottom:1px solid #111;display:flex;gap:12px;align-items:flex-start}}
+.glitch-item:last-child{{border-bottom:none}}
+.severity-dot{{width:8px;height:8px;border-radius:50%;margin-top:5px;flex-shrink:0}}
+.sev-critical{{background:#f44336}}
+.sev-major{{background:#ff9800}}
+.sev-minor{{background:#2196f3}}
+.sev-cosmetic{{background:#666}}
+.glitch-detail{{flex:1}}
+.glitch-type{{color:#ffd700;font-weight:600;font-size:11px;text-transform:uppercase;letter-spacing:1px}}
+.glitch-desc{{color:#aaa;font-size:12px;margin-top:2px}}
+.glitch-meta{{color:#555;font-size:10px;margin-top:2px}}
+.no-glitches{{color:#4caf50;text-align:center;padding:20px;font-style:italic}}
+footer{{text-align:center;padding:16px;color:#444;font-size:10px;border-top:1px solid #1a1a2e;margin-top:24px}}
+</style>
+</head>
+<body>
+<div class="container">
+<header>
+<h1>{html_module.escape(title)}</h1>
+<div class="verdict">{overall_verdict}</div>
+<div class="stats">
+  <div class="stat"><div class="val">{len(reports)}</div><div class="lbl">Screenshots</div></div>
+  <div class="stat"><div class="val">{total_glitches}</div><div class="lbl">Glitches</div></div>
+  <div class="stat"><div class="val">{total_criticals}</div><div class="lbl">Critical</div></div>
+  <div class="stat"><div class="val">{avg_score}</div><div class="lbl">Avg Score</div></div>
+</div>
+</header>
+""")
+
+    # Score gauge
+    score_color = "#4caf50" if avg_score >= 80 else "#ff9800" if avg_score >= 60 else "#f44336"
+    circumference = 2 * 3.14159 * 50
+    dash_offset = circumference * (1 - avg_score / 100)
+    parts.append(f"""
+<div class="score-gauge">
+<svg width="120" height="120" viewBox="0 0 120 120">
+  <circle cx="60" cy="60" r="50" fill="none" stroke="#1a1a2e" stroke-width="8"/>
+  <circle cx="60" cy="60" r="50" fill="none" stroke="{score_color}" stroke-width="8"
+    stroke-dasharray="{circumference}" stroke-dashoffset="{dash_offset}" stroke-linecap="round"/>
+</svg>
+<div class="score-text" style="color:{score_color}">{avg_score}</div>
+</div>
+""")
+
+    # Per-screenshot reports
+    for i, report in enumerate(reports):
+        status_class = f"status-{report.status.lower()}"
+        source_name = Path(report.source).name if report.source else f"Screenshot {i+1}"
+
+        # Inline screenshot as base64
+        img_tag = ""
+        if report.source and Path(report.source).exists():
+            try:
+                b64 = base64.b64encode(Path(report.source).read_bytes()).decode()
+                ext = Path(report.source).suffix.lower()
+                mime = "image/png" if ext == ".png" else "image/jpeg" if ext in (".jpg", ".jpeg") else "image/webp"
+                img_tag = f'<img src="data:{mime};base64,{b64}" alt="Screenshot">'
+            except Exception:
+                img_tag = '<div style="color:#666;padding:40px">Screenshot unavailable</div>'
+        else:
+            img_tag = '<div style="color:#666;padding:40px">No screenshot</div>'
+
+        parts.append(f"""
+<div class="report-card">
+<div class="report-header">
+  <span class="source">{html_module.escape(source_name)} ({report.width}x{report.height})</span>
+  <span class="status-badge {status_class}">{report.status} — {report.score}/100</span>
+</div>
+<div class="screenshot">{img_tag}</div>
+""")
+
+        if report.glitches:
+            parts.append('<div class="glitch-list">')
+            for g in sorted(report.glitches, key=lambda x: {"critical": 0, "major": 1, "minor": 2, "cosmetic": 3}.get(x.severity.value if hasattr(x.severity, "value") else str(x.severity), 4)):
+                sev = g.severity.value if hasattr(g.severity, "value") else str(g.severity)
+                sev_class = f"sev-{sev}"
+                parts.append(f"""
+<div class="glitch-item">
+  <div class="severity-dot {sev_class}"></div>
+  <div class="glitch-detail">
+    <div class="glitch-type">{html_module.escape(g.type)} — {sev.upper()}</div>
+    <div class="glitch-desc">{html_module.escape(g.description)}</div>
+    <div class="glitch-meta">Region: {html_module.escape(g.region)} | Confidence: {g.confidence:.0%} | Source: {html_module.escape(g.source)}</div>
+  </div>
+</div>""")
+            parts.append('</div>')
+        else:
+            parts.append('<div class="no-glitches">No glitches detected</div>')
+
+        parts.append('</div><!-- /report-card -->')
+
+    # Footer
+    parts.append(f"""
+<footer>
+  Generated {datetime.now().strftime('%Y-%m-%d %H:%M:%S')} | matrix_glitch_detect.py | timmy-config#544
+</footer>
+</div>
+</body>
+</html>""")
+
+    return "\n".join(parts)
+
+
+# === Output Formatting ===
+
+def format_report(report: GlitchReport, fmt: str = "json") -> str:
+    if fmt == "json":
+        data = {
+            "source": report.source,
+            "timestamp": report.timestamp,
+            "status": report.status,
+            "score": report.score,
+            "glitches": [asdict(g) for g in report.glitches],
+            "summary": report.summary,
+            "model_used": report.model_used,
+        }
+        for g in data["glitches"]:
+            if hasattr(g["severity"], "value"):
+                g["severity"] = g["severity"].value
+        return json.dumps(data, indent=2)
+
+    elif fmt == "text":
+        lines = [
+            "=" * 50,
+            "  GLITCH DETECTION REPORT",
+            "=" * 50,
+            f"  Source: {report.source}",
+            f"  Status: {report.status}",
+            f"  Score: {report.score}/100",
+            f"  Glitches: {len(report.glitches)}",
+            "",
+        ]
+        icons = {"critical": "🔴", "major": "🟡", "minor": "🔵", "cosmetic": "⚪"}
+        for g in report.glitches:
+            sev = g.severity.value if hasattr(g.severity, "value") else str(g.severity)
+            icon = icons.get(sev, "?")
+            lines.append(f"  {icon} [{g.type}] {sev.upper()}: {g.description}")
+            lines.append(f"     Region: {g.region} | Confidence: {g.confidence:.0%}")
+        lines.append("")
+        lines.append(f"  {report.summary}")
+        lines.append("=" * 50)
+        return "\n".join(lines)
+
+    return ""
+
+
+# === CLI ===
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="3D World Glitch Detection — visual artifact scanner for The Matrix"
+    )
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--image", help="Screenshot file to analyze")
+    group.add_argument("--url", help="URL to screenshot and analyze")
+    group.add_argument("--batch", help="Directory of screenshots to analyze")
+
+    parser.add_argument("--vision", action="store_true", help="Include vision model analysis")
+    parser.add_argument("--model", default=VISION_MODEL, help=f"Vision model (default: {VISION_MODEL})")
+    parser.add_argument("--html", help="Generate HTML report at this path")
+    parser.add_argument("--format", choices=["json", "text"], default="json", help="Output format")
+    parser.add_argument("--output", "-o", help="Output file (default: stdout)")
+
+    args = parser.parse_args()
+
+    reports = []
+
+    if args.image:
+        print(f"Analyzing {args.image}...", file=sys.stderr)
+        report = detect_glitches(args.image, args.vision, args.model)
+        reports.append(report)
+        if not args.html:
+            print(format_report(report, args.format))
+
+    elif args.url:
+        import tempfile
+        with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp:
+            screenshot_path = tmp.name
+        print(f"Capturing screenshot of {args.url}...", file=sys.stderr)
+        if capture_screenshot(args.url, screenshot_path):
+            report = detect_glitches(screenshot_path, args.vision, args.model)
+            report.source = args.url
+            reports.append(report)
+            if not args.html:
+                print(format_report(report, args.format))
+        else:
+            print(f"Failed to capture screenshot", file=sys.stderr)
+            sys.exit(1)
+
+    elif args.batch:
+        batch_dir = Path(args.batch)
+        images = sorted(batch_dir.glob("*.png")) + sorted(batch_dir.glob("*.jpg"))
+        for img in images:
+            print(f"Analyzing {img.name}...", file=sys.stderr)
+            report = detect_glitches(str(img), args.vision, args.model)
+            reports.append(report)
+
+    # HTML report
+    if args.html:
+        html = generate_html_report(reports, title="The Matrix — Glitch Detection Report")
+        Path(args.html).write_text(html)
+        print(f"HTML report written to {args.html}", file=sys.stderr)
+    elif args.batch and not args.html:
+        # Print JSON array for batch
+        print(json.dumps([json.loads(format_report(r, "json")) for r in reports], indent=2))
+
+    # Exit code
+    if any(r.status == "FAIL" for r in reports):
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    import subprocess
+    main()

scripts/nexus_smoke_test.py

@@ -1,20 +1,582 @@
-import json
-from hermes_tools import browser_navigate, browser_vision
+#!/usr/bin/env python3
+"""
+nexus_smoke_test.py — Visual Smoke Test for The Nexus.
 
-def run_smoke_test():
-    print("Navigating to The Nexus...")
-    browser_navigate(url="https://nexus.alexanderwhitestone.com")
-    
-    print("Performing visual verification...")
-    analysis = browser_vision(
-        question="Is the Nexus landing page rendered correctly? Check for: 1) The Tower logo, 2) The main entry portal, 3) Absence of 404/Error messages. Provide a clear PASS or FAIL."
+Takes screenshots of The Nexus landing page, verifies layout consistency
+using both programmatic checks (DOM structure, element presence) and
+optional vision model analysis (visual regression detection).
+
+The Nexus is the Three.js 3D world frontend at nexus.alexanderwhitestone.com.
+This test ensures the landing page renders correctly on every push.
+
+Usage:
+    # Full smoke test (programmatic + optional vision)
+    python scripts/nexus_smoke_test.py
+
+    # Programmatic only (no vision model needed, CI-safe)
+    python scripts/nexus_smoke_test.py --programmatic
+
+    # With vision model regression check
+    python scripts/nexus_smoke_test.py --vision
+
+    # Against a specific URL
+    python scripts/nexus_smoke_test.py --url https://nexus.alexanderwhitestone.com
+
+    # With baseline comparison
+    python scripts/nexus_smoke_test.py --baseline screenshots/nexus-baseline.png
+
+Checks:
+    1. Page loads without errors (HTTP 200, no console errors)
+    2. Key elements present (Three.js canvas, title, navigation)
+    3. No 404/error messages visible
+    4. JavaScript bundle loaded (window.__nexus or scene exists)
+    5. Screenshot captured successfully
+    6. Vision model layout verification (optional)
+    7. Baseline comparison for visual regression (optional)
+
+Refs: timmy-config#490
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+
+# === Configuration ===
+
+DEFAULT_URL = os.environ.get("NEXUS_URL", "https://nexus.alexanderwhitestone.com")
+OLLAMA_BASE = os.environ.get("OLLAMA_BASE_URL", "http://localhost:11434")
+VISION_MODEL = os.environ.get("VISUAL_REVIEW_MODEL", "gemma3:12b")
+
+
+class Severity(str, Enum):
+    PASS = "pass"
+    WARN = "warn"
+    FAIL = "fail"
+
+
+@dataclass
+class SmokeCheck:
+    """A single smoke test check."""
+    name: str
+    status: Severity = Severity.PASS
+    message: str = ""
+    details: str = ""
+
+
+@dataclass
+class SmokeResult:
+    """Complete smoke test result."""
+    url: str = ""
+    status: Severity = Severity.PASS
+    checks: list[SmokeCheck] = field(default_factory=list)
+    screenshot_path: str = ""
+    summary: str = ""
+    duration_ms: int = 0
+
+
+# === HTTP/Network Checks ===
+
+def check_page_loads(url: str) -> SmokeCheck:
+    """Verify the page returns HTTP 200."""
+    check = SmokeCheck(name="Page Loads")
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": "NexusSmokeTest/1.0"})
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            if resp.status == 200:
+                check.status = Severity.PASS
+                check.message = f"HTTP {resp.status}"
+            else:
+                check.status = Severity.WARN
+                check.message = f"HTTP {resp.status} (expected 200)"
+    except urllib.error.HTTPError as e:
+        check.status = Severity.FAIL
+        check.message = f"HTTP {e.code}: {e.reason}"
+    except Exception as e:
+        check.status = Severity.FAIL
+        check.message = f"Connection failed: {e}"
+    return check
+
+
+def check_html_content(url: str) -> tuple[SmokeCheck, str]:
+    """Fetch HTML and check for key content."""
+    check = SmokeCheck(name="HTML Content")
+    html = ""
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": "NexusSmokeTest/1.0"})
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            html = resp.read().decode("utf-8", errors="replace")
+    except Exception as e:
+        check.status = Severity.FAIL
+        check.message = f"Failed to fetch: {e}"
+        return check, html
+
+    issues = []
+
+    # Check for Three.js
+    if "three" not in html.lower() and "THREE" not in html and "threejs" not in html.lower():
+        issues.append("No Three.js reference found")
+
+    # Check for canvas element
+    if "<canvas" not in html.lower():
+        issues.append("No <canvas> element found")
+
+    # Check title
+    title_match = re.search(r"<title[^>]*>(.*?)</title>", html, re.IGNORECASE | re.DOTALL)
+    if title_match:
+        title = title_match.group(1).strip()
+        check.details = f"Title: {title}"
+        if "nexus" not in title.lower() and "tower" not in title.lower():
+            issues.append(f"Title doesn't reference Nexus: '{title}'")
+    else:
+        issues.append("No <title> element")
+
+    # Check for error messages
+    error_patterns = ["404", "not found", "error", "500 internal", "connection refused"]
+    html_lower = html.lower()
+    for pattern in error_patterns:
+        if pattern in html_lower[:500] or pattern in html_lower[-500:]:
+            issues.append(f"Possible error message in HTML: '{pattern}'")
+
+    # Check for script tags (app loaded)
+    script_count = html.lower().count("<script")
+    if script_count == 0:
+        issues.append("No <script> tags found")
+    else:
+        check.details += f" | Scripts: {script_count}"
+
+    if issues:
+        check.status = Severity.FAIL if len(issues) > 2 else Severity.WARN
+        check.message = "; ".join(issues)
+    else:
+        check.status = Severity.PASS
+        check.message = "HTML structure looks correct"
+
+    return check, html
+
+
+# === Screenshot Capture ===
+
+def take_screenshot(url: str, output_path: str, width: int = 1280, height: int = 720) -> SmokeCheck:
+    """Take a screenshot of the page."""
+    check = SmokeCheck(name="Screenshot Capture")
+
+    # Try Playwright
+    try:
+        script = f"""
+import sys
+try:
+    from playwright.sync_api import sync_playwright
+except ImportError:
+    sys.exit(2)
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=True)
+    page = browser.new_page(viewport={{"width": {width}, "height": {height}}})
+
+    errors = []
+    page.on("pageerror", lambda e: errors.append(str(e)))
+    page.on("console", lambda m: errors.append(f"console.{{m.type}}: {{m.text}}") if m.type == "error" else None)
+
+    page.goto("{url}", wait_until="networkidle", timeout=30000)
+    page.wait_for_timeout(3000)  # Wait for Three.js to render
+    page.screenshot(path="{output_path}", full_page=False)
+
+    # Check for Three.js scene
+    has_canvas = page.evaluate("() => !!document.querySelector('canvas')")
+    has_three = page.evaluate("() => typeof THREE !== 'undefined' || !!document.querySelector('canvas')")
+    title = page.title()
+
+    browser.close()
+
+    import json
+    print(json.dumps({{"has_canvas": has_canvas, "has_three": has_three, "title": title, "errors": errors[:5]}}))
+"""
+        result = subprocess.run(
+            ["python3", "-c", script],
+            capture_output=True, text=True, timeout=60
+        )
+
+        if result.returncode == 0:
+            # Parse Playwright output
+            try:
+                # Find JSON in output
+                for line in result.stdout.strip().split("\n"):
+                    if line.startswith("{"):
+                        info = json.loads(line)
+                        extras = []
+                        if info.get("has_canvas"):
+                            extras.append("canvas present")
+                        if info.get("errors"):
+                            extras.append(f"{len(info['errors'])} JS errors")
+                        check.details = "; ".join(extras) if extras else "Playwright capture"
+                        if info.get("errors"):
+                            check.status = Severity.WARN
+                            check.message = f"JS errors detected: {info['errors'][0][:100]}"
+                        else:
+                            check.message = "Screenshot captured via Playwright"
+                        break
+            except json.JSONDecodeError:
+                pass
+
+            if Path(output_path).exists() and Path(output_path).stat().st_size > 1000:
+                return check
+        elif result.returncode == 2:
+            check.details = "Playwright not installed"
+        else:
+            check.details = f"Playwright failed: {result.stderr[:200]}"
+    except Exception as e:
+        check.details = f"Playwright error: {e}"
+
+    # Try wkhtmltoimage
+    try:
+        result = subprocess.run(
+            ["wkhtmltoimage", "--width", str(width), "--quality", "90", url, output_path],
+            capture_output=True, text=True, timeout=30
+        )
+        if result.returncode == 0 and Path(output_path).exists() and Path(output_path).stat().st_size > 1000:
+            check.status = Severity.PASS
+            check.message = "Screenshot captured via wkhtmltoimage"
+            check.details = ""
+            return check
+    except Exception:
+        pass
+
+    # Try curl + browserless (if available)
+    browserless = os.environ.get("BROWSERLESS_URL")
+    if browserless:
+        try:
+            payload = json.dumps({
+                "url": url,
+                "options": {"type": "png", "fullPage": False}
+            })
+            req = urllib.request.Request(
+                f"{browserless}/screenshot",
+                data=payload.encode(),
+                headers={"Content-Type": "application/json"}
+            )
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                img_data = resp.read()
+                Path(output_path).write_bytes(img_data)
+                if Path(output_path).stat().st_size > 1000:
+                    check.status = Severity.PASS
+                    check.message = "Screenshot captured via browserless"
+                    check.details = ""
+                    return check
+        except Exception:
+            pass
+
+    check.status = Severity.WARN
+    check.message = "No screenshot backend available"
+    check.details = "Install Playwright: pip install playwright && playwright install chromium"
+    return check
+
+
+# === Vision Analysis ===
+
+VISION_PROMPT = """You are a web QA engineer. Analyze this screenshot of The Nexus (a Three.js 3D world).
+
+Check for:
+1. LAYOUT: Is the page layout correct? Is content centered, not broken or overlapping?
+2. THREE.JS RENDER: Is there a visible 3D canvas/scene? Any black/blank areas where rendering failed?
+3. NAVIGATION: Are navigation elements (buttons, links, menu) visible and properly placed?
+4. TEXT: Is text readable? Any missing text, garbled characters, or font issues?
+5. ERRORS: Any visible error messages, 404 pages, or broken images?
+6. TOWER: Is the Tower or entry portal visible in the scene?
+
+Respond as JSON:
+{
+    "status": "PASS|FAIL|WARN",
+    "checks": [
+        {"name": "Layout", "status": "pass|fail|warn", "message": "..."},
+        {"name": "Three.js Render", "status": "pass|fail|warn", "message": "..."},
+        {"name": "Navigation", "status": "pass|fail|warn", "message": "..."},
+        {"name": "Text Readability", "status": "pass|fail|warn", "message": "..."},
+        {"name": "Error Messages", "status": "pass|fail|warn", "message": "..."}
+    ],
+    "summary": "brief overall assessment"
+}"""
+
+
+def run_vision_check(screenshot_path: str, model: str = VISION_MODEL) -> list[SmokeCheck]:
+    """Run vision model analysis on screenshot."""
+    checks = []
+    try:
+        b64 = base64.b64encode(Path(screenshot_path).read_bytes()).decode()
+        payload = json.dumps({
+            "model": model,
+            "messages": [{"role": "user", "content": [
+                {"type": "text", "text": VISION_PROMPT},
+                {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}}
+            ]}],
+            "stream": False,
+            "options": {"temperature": 0.1}
+        }).encode()
+
+        req = urllib.request.Request(
+            f"{OLLAMA_BASE}/api/chat",
+            data=payload,
+            headers={"Content-Type": "application/json"}
+        )
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            result = json.loads(resp.read())
+            content = result.get("message", {}).get("content", "")
+
+        parsed = _parse_json_response(content)
+        for c in parsed.get("checks", []):
+            status = Severity(c.get("status", "warn"))
+            checks.append(SmokeCheck(
+                name=f"Vision: {c.get('name', 'Unknown')}",
+                status=status,
+                message=c.get("message", "")
+            ))
+
+        if not checks:
+            checks.append(SmokeCheck(
+                name="Vision Analysis",
+                status=Severity.WARN,
+                message="Vision model returned no structured checks"
+            ))
+
+    except Exception as e:
+        checks.append(SmokeCheck(
+            name="Vision Analysis",
+            status=Severity.WARN,
+            message=f"Vision check failed: {e}"
+        ))
+
+    return checks
+
+
+# === Baseline Comparison ===
+
+def compare_baseline(current_path: str, baseline_path: str) -> SmokeCheck:
+    """Compare screenshot against baseline for visual regression."""
+    check = SmokeCheck(name="Baseline Comparison")
+
+    if not Path(baseline_path).exists():
+        check.status = Severity.WARN
+        check.message = f"Baseline not found: {baseline_path}"
+        return check
+
+    if not Path(current_path).exists():
+        check.status = Severity.FAIL
+        check.message = "No current screenshot to compare"
+        return check
+
+    # Simple file size comparison (rough regression indicator)
+    baseline_size = Path(baseline_path).stat().st_size
+    current_size = Path(current_path).stat().st_size
+
+    if baseline_size == 0:
+        check.status = Severity.WARN
+        check.message = "Baseline is empty"
+        return check
+
+    diff_pct = abs(current_size - baseline_size) / baseline_size * 100
+
+    if diff_pct > 50:
+        check.status = Severity.FAIL
+        check.message = f"Major visual change: {diff_pct:.0f}% file size difference"
+    elif diff_pct > 20:
+        check.status = Severity.WARN
+        check.message = f"Significant visual change: {diff_pct:.0f}% file size difference"
+    else:
+        check.status = Severity.PASS
+        check.message = f"Visual consistency: {diff_pct:.1f}% difference"
+
+    check.details = f"Baseline: {baseline_size}B, Current: {current_size}B"
+
+    # Pixel-level diff using ImageMagick (if available)
+    try:
+        diff_output = current_path.replace(".png", "-diff.png")
+        result = subprocess.run(
+            ["compare", "-metric", "AE", current_path, baseline_path, diff_output],
+            capture_output=True, text=True, timeout=15
+        )
+        if result.returncode < 2:
+            pixels_diff = int(result.stderr) if result.stderr.strip().isdigit() else 0
+            check.details += f" | Pixel diff: {pixels_diff}"
+            if pixels_diff > 10000:
+                check.status = Severity.FAIL
+                check.message = f"Major visual regression: {pixels_diff} pixels changed"
+            elif pixels_diff > 1000:
+                check.status = Severity.WARN
+                check.message = f"Visual change detected: {pixels_diff} pixels changed"
+    except Exception:
+        pass
+
+    return check
+
+
+# === Helpers ===
+
+def _parse_json_response(text: str) -> dict:
+    cleaned = text.strip()
+    if cleaned.startswith("```"):
+        lines = cleaned.split("\n")[1:]
+        if lines and lines[-1].strip() == "```":
+            lines = lines[:-1]
+        cleaned = "\n".join(lines)
+    try:
+        return json.loads(cleaned)
+    except json.JSONDecodeError:
+        start = cleaned.find("{")
+        end = cleaned.rfind("}")
+        if start >= 0 and end > start:
+            try:
+                return json.loads(cleaned[start:end + 1])
+            except json.JSONDecodeError:
+                pass
+    return {}
+
+
+# === Main Smoke Test ===
+
+def run_smoke_test(url: str, vision: bool = False, baseline: Optional[str] = None,
+                   model: str = VISION_MODEL) -> SmokeResult:
+    """Run the full visual smoke test suite."""
+    import time
+    start = time.time()
+
+    result = SmokeResult(url=url)
+    screenshot_path = ""
+
+    # 1. Page loads
+    print(f"  [1/5] Checking page loads...", file=sys.stderr)
+    result.checks.append(check_page_loads(url))
+
+    # 2. HTML content
+    print(f"  [2/5] Checking HTML content...", file=sys.stderr)
+    html_check, html = check_html_content(url)
+    result.checks.append(html_check)
+
+    # 3. Screenshot
+    with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp:
+        screenshot_path = tmp.name
+    print(f"  [3/5] Taking screenshot...", file=sys.stderr)
+    screenshot_check = take_screenshot(url, screenshot_path)
+    result.checks.append(screenshot_check)
+    result.screenshot_path = screenshot_path
+
+    # 4. Vision analysis (optional)
+    if vision and Path(screenshot_path).exists():
+        print(f"  [4/5] Running vision analysis...", file=sys.stderr)
+        result.checks.extend(run_vision_check(screenshot_path, model))
+    else:
+        print(f"  [4/5] Vision analysis skipped", file=sys.stderr)
+
+    # 5. Baseline comparison (optional)
+    if baseline:
+        print(f"  [5/5] Comparing against baseline...", file=sys.stderr)
+        result.checks.append(compare_baseline(screenshot_path, baseline))
+    else:
+        print(f"  [5/5] Baseline comparison skipped", file=sys.stderr)
+
+    # Determine overall status
+    fails = sum(1 for c in result.checks if c.status == Severity.FAIL)
+    warns = sum(1 for c in result.checks if c.status == Severity.WARN)
+
+    if fails > 0:
+        result.status = Severity.FAIL
+    elif warns > 0:
+        result.status = Severity.WARN
+    else:
+        result.status = Severity.PASS
+
+    result.summary = (
+        f"{result.status.value.upper()}: {len(result.checks)} checks, "
+        f"{fails} failures, {warns} warnings"
     )
-    
-    result = {
-        "status": "PASS" if "PASS" in analysis.upper() else "FAIL",
-        "analysis": analysis
-    }
+    result.duration_ms = int((time.time() - start) * 1000)
+
     return result
 
-if __name__ == '__main__':
-    print(json.dumps(run_smoke_test(), indent=2))
+
+# === Output ===
+
+def format_result(result: SmokeResult, fmt: str = "json") -> str:
+    if fmt == "json":
+        data = {
+            "url": result.url,
+            "status": result.status.value,
+            "summary": result.summary,
+            "duration_ms": result.duration_ms,
+            "screenshot": result.screenshot_path,
+            "checks": [asdict(c) for c in result.checks],
+        }
+        for c in data["checks"]:
+            if hasattr(c["status"], "value"):
+                c["status"] = c["status"].value
+        return json.dumps(data, indent=2)
+
+    elif fmt == "text":
+        lines = [
+            "=" * 50,
+            "  NEXUS VISUAL SMOKE TEST",
+            "=" * 50,
+            f"  URL: {result.url}",
+            f"  Status: {result.status.value.upper()}",
+            f"  Duration: {result.duration_ms}ms",
+            "",
+        ]
+        icons = {"pass": "✅", "warn": "⚠️", "fail": "❌"}
+        for c in result.checks:
+            icon = icons.get(c.status.value if hasattr(c.status, "value") else str(c.status), "?")
+            lines.append(f"  {icon} {c.name}: {c.message}")
+            if c.details:
+                lines.append(f"     {c.details}")
+        lines.append("")
+        lines.append(f"  {result.summary}")
+        lines.append("=" * 50)
+        return "\n".join(lines)
+
+    return ""
+
+
+# === CLI ===
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Visual Smoke Test for The Nexus — layout + regression verification"
+    )
+    parser.add_argument("--url", default=DEFAULT_URL, help=f"Nexus URL (default: {DEFAULT_URL})")
+    parser.add_argument("--vision", action="store_true", help="Include vision model analysis")
+    parser.add_argument("--baseline", help="Baseline screenshot for regression comparison")
+    parser.add_argument("--model", default=VISION_MODEL, help=f"Vision model (default: {VISION_MODEL})")
+    parser.add_argument("--format", choices=["json", "text"], default="json")
+    parser.add_argument("--output", "-o", help="Output file (default: stdout)")
+
+    args = parser.parse_args()
+
+    print(f"Running smoke test on {args.url}...", file=sys.stderr)
+    result = run_smoke_test(args.url, vision=args.vision, baseline=args.baseline, model=args.model)
+    output = format_result(result, args.format)
+
+    if args.output:
+        Path(args.output).write_text(output)
+        print(f"Results written to {args.output}", file=sys.stderr)
+    else:
+        print(output)
+
+    if result.status == Severity.FAIL:
+        sys.exit(1)
+    elif result.status == Severity.WARN:
+        sys.exit(0)  # Warnings don't fail CI
+
+
+if __name__ == "__main__":
+    main()

scripts/nightly-pipeline-scheduler.md

@@ -0,0 +1,50 @@
+# Nightly Pipeline Scheduler
+
+Auto-starts batch pipelines when inference is available.
+
+## What It Does
+
+1. Checks inference provider health (OpenRouter, Ollama, RunPod)
+2. Checks if it's off-peak hours (configurable, default: after 6PM)
+3. Checks interactive session load (don't fight with live users)
+4. Checks daily token budget (configurable limit)
+5. Starts the highest-priority incomplete pipeline
+
+## Pipeline Priority Order
+
+| Priority | Pipeline | Deps | Max Tokens |
+|----------|----------|------|------------|
+| 1 | playground-factory | none | 100,000 |
+| 2 | training-factory | none | 150,000 |
+| 3 | knowledge-mine | training-factory running | 80,000 |
+| 4 | adversary | knowledge-mine running | 50,000 |
+| 5 | codebase-genome | none | 120,000 |
+
+## Usage
+
+```bash
+# Normal run (used by cron)
+./scripts/nightly-pipeline-scheduler.sh
+
+# Dry run (show what would start)
+./scripts/nightly-pipeline-scheduler.sh --dry-run
+
+# Status report
+./scripts/nightly-pipeline-scheduler.sh --status
+
+# Force start during peak hours
+./scripts/nightly-pipeline-scheduler.sh --force
+```
+
+## Configuration
+
+Set via environment variables:
+- `PIPELINE_TOKEN_LIMIT`: Daily token budget (default: 500,000)
+- `PIPELINE_PEAK_START`: Peak hours start (default: 9)
+- `PIPELINE_PEAK_END`: Peak hours end (default: 18)
+- `HERMES_HOME`: Hermes home directory (default: ~/.hermes)
+
+## Cron
+
+Runs every 30 minutes. Off-peak only (unless --force).
+See `cron/pipeline-scheduler.yml`.

scripts/nightly-pipeline-scheduler.sh

@@ -0,0 +1,383 @@
+#!/usr/bin/env bash
+# nightly-pipeline-scheduler.sh — Auto-start batch pipelines when inference is available.
+#
+# Checks provider health, pipeline progress, token budget, and interactive load.
+# Starts the highest-priority incomplete pipeline that can run.
+#
+# Usage:
+#   ./scripts/nightly-pipeline-scheduler.sh          # Normal run
+#   ./scripts/nightly-pipeline-scheduler.sh --dry-run # Show what would start
+#   ./scripts/nightly-pipeline-scheduler.sh --status  # Pipeline status report
+
+set -euo pipefail
+
+# --- Configuration ---
+HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
+BUDGET_FILE="${HERMES_HOME}/pipeline_budget.json"
+STATE_FILE="${HERMES_HOME}/pipeline_state.json"
+LOG_FILE="${HERMES_HOME}/logs/pipeline-scheduler.log"
+TOKEN_DAILY_LIMIT="${PIPELINE_TOKEN_LIMIT:-500000}"
+PEAK_HOURS_START="${PIPELINE_PEAK_START:-9}"
+PEAK_HOURS_END="${PIPELINE_PEAK_END:-18}"
+
+# Pipeline definitions (priority order)
+# Each pipeline: name, script, max_tokens, dependencies
+PIPELINES=(
+    "playground-factory|scripts/pipeline_playground_factory.sh|100000|none"
+    "training-factory|scripts/pipeline_training_factory.sh|150000|none"
+    "knowledge-mine|scripts/pipeline_knowledge_mine.sh|80000|training-factory"
+    "adversary|scripts/pipeline_adversary.sh|50000|knowledge-mine"
+    "codebase-genome|scripts/pipeline_codebase_genome.sh|120000|none"
+)
+
+# --- Colors ---
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+# --- Helpers ---
+now_hour() { date +%-H; }
+is_peak_hours() {
+    local h=$(now_hour)
+    [[ $h -ge $PEAK_HOURS_START && $h -lt $PEAK_HOURS_END ]]
+}
+
+ensure_dirs() {
+    mkdir -p "$(dirname "$LOG_FILE")" "$(dirname "$BUDGET_FILE")" "$(dirname "$STATE_FILE")"
+}
+
+log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" | tee -a "$LOG_FILE"; }
+
+get_budget_used_today() {
+    if [[ -f "$BUDGET_FILE" ]]; then
+        local today=$(date +%Y-%m-%d)
+        python3 -c "
+import json, sys
+with open('$BUDGET_FILE') as f:
+    d = json.load(f)
+print(d.get('daily', {}).get('$today', {}).get('tokens_used', 0))
+" 2>/dev/null || echo 0
+    else
+        echo 0
+    fi
+}
+
+get_budget_remaining() {
+    local used=$(get_budget_used_today)
+    echo $((TOKEN_DAILY_LIMIT - used))
+}
+
+update_budget() {
+    local pipeline="$1"
+    local tokens="$2"
+    local today=$(date +%Y-%m-%d)
+    python3 -c "
+import json, os
+path = '$BUDGET_FILE'
+d = {}
+if os.path.exists(path):
+    with open(path) as f:
+        d = json.load(f)
+daily = d.setdefault('daily', {})
+day = daily.setdefault('$today', {'tokens_used': 0, 'pipelines': {}})
+day['tokens_used'] = day.get('tokens_used', 0) + $tokens
+day['pipelines']['$pipeline'] = day['pipelines'].get('$pipeline', 0) + $tokens
+with open(path, 'w') as f:
+    json.dump(d, f, indent=2)
+"
+}
+
+get_pipeline_state() {
+    if [[ -f "$STATE_FILE" ]]; then
+        cat "$STATE_FILE"
+    else
+        echo "{}"
+    fi
+}
+
+set_pipeline_state() {
+    local pipeline="$1"
+    local state="$2"  # running, complete, failed, skipped
+    python3 -c "
+import json, os
+path = '$STATE_FILE'
+d = {}
+if os.path.exists(path):
+    with open(path) as f:
+        d = json.load(f)
+d['$pipeline'] = {'state': '$state', 'updated': '$(date -Iseconds)'}
+with open(path, 'w') as f:
+    json.dump(d, f, indent=2)
+"
+}
+
+is_pipeline_complete() {
+    local pipeline="$1"
+    python3 -c "
+import json, os
+path = '$STATE_FILE'
+if not os.path.exists(path):
+    print('false')
+else:
+    with open(path) as f:
+        d = json.load(f)
+    state = d.get('$pipeline', {}).get('state', 'not_started')
+    print('true' if state == 'complete' else 'false')
+" 2>/dev/null || echo false
+}
+
+is_pipeline_running() {
+    local pipeline="$1"
+    python3 -c "
+import json, os
+path = '$STATE_FILE'
+if not os.path.exists(path):
+    print('false')
+else:
+    with open(path) as f:
+        d = json.load(f)
+    state = d.get('$pipeline', {}).get('state', 'not_started')
+    print('true' if state == 'running' else 'false')
+" 2>/dev/null || echo false
+}
+
+check_dependency() {
+    local dep="$1"
+    if [[ "$dep" == "none" ]]; then
+        return 0
+    fi
+    # For knowledge-mine: training-factory must be running or complete
+    if [[ "$dep" == "training-factory" ]]; then
+        local state=$(python3 -c "
+import json, os
+path = '$STATE_FILE'
+if not os.path.exists(path):
+    print('not_started')
+else:
+    with open(path) as f:
+        d = json.load(f)
+    print(d.get('training-factory', {}).get('state', 'not_started'))
+" 2>/dev/null || echo "not_started")
+        [[ "$state" == "running" || "$state" == "complete" ]]
+        return $?
+    fi
+    # For adversary: knowledge-mine must be at least 50% done
+    # Simplified: check if it's running (we'd need progress tracking for 50%)
+    if [[ "$dep" == "knowledge-mine" ]]; then
+        local state=$(python3 -c "
+import json, os
+path = '$STATE_FILE'
+if not os.path.exists(path):
+    print('not_started')
+else:
+    with open(path) as f:
+        d = json.load(f)
+    print(d.get('knowledge-mine', {}).get('state', 'not_started'))
+" 2>/dev/null || echo "not_started")
+        [[ "$state" == "running" || "$state" == "complete" ]]
+        return $?
+    fi
+    return 0
+}
+
+check_inference_available() {
+    # Check if any inference provider is responding
+    # 1. Check OpenRouter
+    local or_ok=$(curl -s -o /dev/null -w "%{http_code}" \
+        --connect-timeout 5 "https://openrouter.ai/api/v1/models" 2>/dev/null || echo "000")
+
+    # 2. Check local Ollama
+    local ollama_ok=$(curl -s -o /dev/null -w "%{http_code}" \
+        --connect-timeout 5 "http://localhost:11434/api/tags" 2>/dev/null || echo "000")
+
+    # 3. Check RunPod (if configured)
+    local runpod_ok="000"
+    if [[ -n "${RUNPOD_ENDPOINT:-}" ]]; then
+        runpod_ok=$(curl -s -o /dev/null -w "%{http_code}" \
+            --connect-timeout 5 "$RUNPOD_ENDPOINT/health" 2>/dev/null || echo "000")
+    fi
+
+    if [[ "$or_ok" == "200" || "$ollama_ok" == "200" || "$runpod_ok" == "200" ]]; then
+        return 0
+    fi
+    return 1
+}
+
+check_interactive_load() {
+    # Check if there are active interactive sessions (don't fight with live users)
+    # Look for tmux panes with active hermes sessions
+    local active=$(tmux list-panes -a -F '#{pane_pid} #{pane_current_command}' 2>/dev/null \
+        | grep -c "hermes\|python3" || echo 0)
+
+    # If more than 3 interactive sessions, skip pipeline start
+    if [[ $active -gt 3 ]]; then
+        return 1
+    fi
+    return 0
+}
+
+start_pipeline() {
+    local name="$1"
+    local script="$2"
+    local max_tokens="$3"
+    local budget_remaining="$4"
+    local mode="${5:-run}"
+
+    if [[ "$budget_remaining" -lt "$max_tokens" ]]; then
+        log "SKIP $name: insufficient budget ($budget_remaining < $max_tokens tokens)"
+        return 1
+    fi
+
+    if [[ ! -f "$script" ]]; then
+        log "SKIP $name: script not found ($script)"
+        return 1
+    fi
+
+    if [[ "$mode" == "dry-run" ]]; then
+        log "DRY-RUN: Would start $name (budget: $budget_remaining, needs: $max_tokens)"
+        return 0
+    fi
+
+    log "START $name (budget: $budget_remaining, max_tokens: $max_tokens)"
+    set_pipeline_state "$name" "running"
+
+    # Run in background, capture output
+    local log_path="${HERMES_HOME}/logs/pipeline-${name}.log"
+    bash "$script" --max-tokens "$max_tokens" >> "$log_path" 2>&1 &
+    local pid=$!
+
+    # Wait a moment to check if it started OK
+    sleep 2
+    if kill -0 $pid 2>/dev/null; then
+        log "RUNNING $name (PID: $pid, log: $log_path)"
+        # Record the PID
+        python3 -c "
+import json, os
+path = '$STATE_FILE'
+d = {}
+if os.path.exists(path):
+    with open(path) as f:
+        d = json.load(f)
+d['$name']['pid'] = $pid
+with open(path, 'w') as f:
+    json.dump(d, f, indent=2)
+"
+        return 0
+    else
+        log "FAIL $name: script exited immediately"
+        set_pipeline_state "$name" "failed"
+        return 1
+    fi
+}
+
+# --- Main ---
+main() {
+    local mode="${1:-run}"
+    ensure_dirs
+
+    log "=== Pipeline Scheduler ($mode) ==="
+
+    # Check 1: Is inference available?
+    if ! check_inference_available; then
+        log "No inference provider available. Skipping all pipelines."
+        exit 0
+    fi
+    log "Inference: AVAILABLE"
+
+    # Check 2: Is it peak hours?
+    if is_peak_hours && [[ "$mode" != "--force" ]]; then
+        local h=$(now_hour)
+        log "Peak hours ($h:00). Skipping pipeline start. Use --force to override."
+        exit 0
+    fi
+    log "Off-peak: OK"
+
+    # Check 3: Interactive load
+    if ! check_interactive_load && [[ "$mode" != "--force" ]]; then
+        log "High interactive load. Skipping pipeline start."
+        exit 0
+    fi
+    log "Interactive load: OK"
+
+    # Check 4: Token budget
+    local budget=$(get_budget_remaining)
+    log "Token budget remaining: $budget / $TOKEN_DAILY_LIMIT"
+
+    if [[ $budget -le 0 ]]; then
+        log "Daily token budget exhausted. Stopping."
+        exit 0
+    fi
+
+    # Check 5: Pipeline status
+    if [[ "$mode" == "--status" ]]; then
+        echo -e "${CYAN}Pipeline Status:${NC}"
+        echo "────────────────────────────────────────────────────"
+        for entry in "${PIPELINES[@]}"; do
+            IFS='|' read -r name script max_tokens dep <<< "$entry"
+            local state=$(python3 -c "
+import json, os
+path = '$STATE_FILE'
+if not os.path.exists(path):
+    print('not_started')
+else:
+    with open(path) as f:
+        d = json.load(f)
+    print(d.get('$name', {}).get('state', 'not_started'))
+" 2>/dev/null || echo "not_started")
+
+            local color=$NC
+            case "$state" in
+                running)  color=$YELLOW ;;
+                complete) color=$GREEN ;;
+                failed)   color=$RED ;;
+            esac
+            printf "  %-25s %b%s%b (max: %s tokens, dep: %s)\n" "$name" "$color" "$state" "$NC" "$max_tokens" "$dep"
+        done
+        echo "────────────────────────────────────────────────────"
+        echo "  Budget: $budget / $TOKEN_DAILY_LIMIT tokens remaining"
+        echo "  Peak hours: $PEAK_HOURS_START:00 - $PEAK_HOURS_END:00"
+        exit 0
+    fi
+
+    # Find and start the highest-priority incomplete pipeline
+    local started=0
+    for entry in "${PIPELINES[@]}"; do
+        IFS='|' read -r name script max_tokens dep <<< "$entry"
+
+        # Skip if already running or complete
+        if [[ "$(is_pipeline_running $name)" == "true" ]]; then
+            log "SKIP $name: already running"
+            continue
+        fi
+        if [[ "$(is_pipeline_complete $name)" == "true" ]]; then
+            log "SKIP $name: already complete"
+            continue
+        fi
+
+        # Check dependency
+        if ! check_dependency "$dep"; then
+            log "SKIP $name: dependency $dep not met"
+            continue
+        fi
+
+        # Try to start
+        if start_pipeline "$name" "$script" "$max_tokens" "$budget" "$mode"; then
+            started=1
+            # Only start one pipeline per run (let it claim tokens before next check)
+            # Exception: playground-factory and training-factory can run in parallel
+            if [[ "$name" != "playground-factory" && "$name" != "training-factory" ]]; then
+                break
+            fi
+        fi
+    done
+
+    if [[ $started -eq 0 ]]; then
+        log "No pipelines to start (all complete, running, or blocked)."
+    fi
+
+    log "=== Pipeline Scheduler done ==="
+}
+
+main "$@"

scripts/visual_pr_reviewer.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 import json
 from hermes_tools import browser_navigate, browser_vision
 

tests/test_foundation_accessibility_audit.py

@@ -0,0 +1,301 @@
+#!/usr/bin/env python3
+"""Tests for foundation_accessibility_audit.py — verifies WCAG checks."""
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))
+
+from foundation_accessibility_audit import (
+    A11yHTMLParser, Severity, A11yViolation,
+    parse_color, contrast_ratio, relative_luminance,
+    run_programmatic_checks, check_page_title, check_images_alt_text,
+    check_heading_hierarchy, check_lang_attribute, check_landmarks,
+    check_skip_nav, check_form_labels, check_link_text,
+    _parse_json_response, format_report, A11yAuditReport, A11yPageResult,
+)
+
+
+# === Color Utilities ===
+
+def test_parse_color_hex6():
+    assert parse_color("#ff0000") == (255, 0, 0)
+    assert parse_color("#000000") == (0, 0, 0)
+    assert parse_color("#ffffff") == (255, 255, 255)
+    print("  PASS: test_parse_color_hex6")
+
+
+def test_parse_color_hex3():
+    assert parse_color("#f00") == (255, 0, 0)
+    assert parse_color("#abc") == (170, 187, 204)
+    print("  PASS: test_parse_color_hex3")
+
+
+def test_parse_color_rgb():
+    assert parse_color("rgb(255, 0, 0)") == (255, 0, 0)
+    assert parse_color("rgb( 128 , 64 , 32 )") == (128, 64, 32)
+    print("  PASS: test_parse_color_rgb")
+
+
+def test_parse_color_named():
+    assert parse_color("white") == (255, 255, 255)
+    assert parse_color("black") == (0, 0, 0)
+    print("  PASS: test_parse_color_named")
+
+
+def test_parse_color_invalid():
+    assert parse_color("not-a-color") is None
+    assert parse_color("") is None
+    print("  PASS: test_parse_color_invalid")
+
+
+def test_contrast_ratio_black_white():
+    ratio = contrast_ratio((0, 0, 0), (255, 255, 255))
+    assert ratio > 20  # Should be 21:1
+    print(f"  PASS: test_contrast_ratio_black_white ({ratio:.1f}:1)")
+
+
+def test_contrast_ratio_same():
+    ratio = contrast_ratio((128, 128, 128), (128, 128, 128))
+    assert ratio == 1.0
+    print("  PASS: test_contrast_ratio_same")
+
+
+def test_contrast_ratio_wcag_aa():
+    # #767676 on white = 4.54:1 (WCAG AA pass for normal text)
+    ratio = contrast_ratio((118, 118, 118), (255, 255, 255))
+    assert ratio >= 4.5
+    print(f"  PASS: test_contrast_ratio_wcag_aa ({ratio:.2f}:1)")
+
+
+# === HTML Parser ===
+
+def test_parser_title():
+    parser = A11yHTMLParser()
+    parser.feed("<html><head><title>Test Page</title></head></html>")
+    assert parser.title == "Test Page"
+    print("  PASS: test_parser_title")
+
+
+def test_parser_images():
+    parser = A11yHTMLParser()
+    parser.feed('<html><body><img src="a.png" alt="Alt text"><img src="b.png"></body></html>')
+    assert len(parser.images) == 2
+    assert parser.images[0]["alt"] == "Alt text"
+    assert parser.images[1]["alt"] is None
+    print("  PASS: test_parser_images")
+
+
+def test_parser_headings():
+    parser = A11yHTMLParser()
+    parser.feed("<html><body><h1>Main</h1><h2>Sub</h2><h4>Skip</h4></body></html>")
+    assert len(parser.headings) == 3
+    assert parser.headings[0] == {"level": 1, "text": "Main"}
+    assert parser.headings[2] == {"level": 4, "text": "Skip"}
+    print("  PASS: test_parser_headings")
+
+
+def test_parser_lang():
+    parser = A11yHTMLParser()
+    parser.feed('<html lang="en"><body></body></html>')
+    assert parser.lang == "en"
+    print("  PASS: test_parser_lang")
+
+
+def test_parser_landmarks():
+    parser = A11yHTMLParser()
+    parser.feed("<html><body><nav>Links</nav><main>Content</main></body></html>")
+    tags = {lm["tag"] for lm in parser.landmarks}
+    assert "nav" in tags
+    assert "main" in tags
+    print("  PASS: test_parser_landmarks")
+
+
+# === Programmatic Checks ===
+
+def test_check_page_title_empty():
+    parser = A11yHTMLParser()
+    parser.title = ""
+    violations = check_page_title(parser)
+    assert len(violations) == 1
+    assert violations[0].criterion == "2.4.2"
+    assert violations[0].severity == Severity.MAJOR
+    print("  PASS: test_check_page_title_empty")
+
+
+def test_check_page_title_present():
+    parser = A11yHTMLParser()
+    parser.title = "My Great Page"
+    violations = check_page_title(parser)
+    assert len(violations) == 0
+    print("  PASS: test_check_page_title_present")
+
+
+def test_check_lang_missing():
+    parser = A11yHTMLParser()
+    parser.lang = ""
+    violations = check_lang_attribute(parser)
+    assert len(violations) == 1
+    assert violations[0].criterion == "3.1.1"
+    print("  PASS: test_check_lang_missing")
+
+
+def test_check_images_missing_alt():
+    parser = A11yHTMLParser()
+    parser.images = [{"src": "photo.jpg", "alt": None}]
+    violations = check_images_alt_text(parser)
+    assert len(violations) == 1
+    assert violations[0].severity == Severity.CRITICAL
+    print("  PASS: test_check_images_missing_alt")
+
+
+def test_check_images_with_alt():
+    parser = A11yHTMLParser()
+    parser.images = [{"src": "photo.jpg", "alt": "A photo"}]
+    violations = check_images_alt_text(parser)
+    assert len(violations) == 0
+    print("  PASS: test_check_images_with_alt")
+
+
+def test_check_images_decorative():
+    parser = A11yHTMLParser()
+    parser.images = [{"src": "deco.png", "alt": "", "role": "presentation"}]
+    violations = check_images_alt_text(parser)
+    assert len(violations) == 0
+    print("  PASS: test_check_images_decorative")
+
+
+def test_check_headings_no_h1():
+    parser = A11yHTMLParser()
+    parser.headings = [{"level": 2, "text": "Sub"}, {"level": 3, "text": "Sub sub"}]
+    violations = check_heading_hierarchy(parser)
+    assert any(v.criterion == "1.3.1" and "h1" in v.description.lower() for v in violations)
+    print("  PASS: test_check_headings_no_h1")
+
+
+def test_check_headings_skip():
+    parser = A11yHTMLParser()
+    parser.headings = [{"level": 1, "text": "Main"}, {"level": 4, "text": "Skipped"}]
+    violations = check_heading_hierarchy(parser)
+    assert any("skipped" in v.description.lower() for v in violations)
+    print("  PASS: test_check_headings_skip")
+
+
+def test_check_skip_nav_missing():
+    parser = A11yHTMLParser()
+    parser.skip_nav = False
+    parser.links = [{"text": "Home", "href": "/"}, {"text": "About", "href": "/about"}]
+    violations = check_skip_nav(parser)
+    assert len(violations) == 1
+    assert violations[0].criterion == "2.4.1"
+    print("  PASS: test_check_skip_nav_missing")
+
+
+def test_check_link_text_empty():
+    parser = A11yHTMLParser()
+    parser.links = [{"text": "", "href": "/page", "aria_label": ""}]
+    violations = check_link_text(parser)
+    assert len(violations) == 1
+    assert violations[0].criterion == "2.4.4"
+    print("  PASS: test_check_link_text_empty")
+
+
+def test_check_link_text_generic():
+    parser = A11yHTMLParser()
+    parser.links = [{"text": "Click here", "href": "/page"}]
+    violations = check_link_text(parser)
+    assert any("non-descriptive" in v.description.lower() for v in violations)
+    print("  PASS: test_check_link_text_generic")
+
+
+def test_run_programmatic_checks_full():
+    html = """<!DOCTYPE html>
+<html lang="en">
+<head><title>Good Page</title></head>
+<body>
+<nav><a href="#main">Skip to content</a></nav>
+<main>
+<h1>Welcome</h1>
+<h2>Section</h2>
+<img src="hero.jpg" alt="Hero image">
+<a href="/about">About Us</a>
+</main>
+</body>
+</html>"""
+    violations = run_programmatic_checks(html)
+    # This page should have very few or no violations
+    criticals = [v for v in violations if v.severity == Severity.CRITICAL]
+    assert len(criticals) == 0
+    print(f"  PASS: test_run_programmatic_checks_full ({len(violations)} minor issues)")
+
+
+# === JSON Parsing ===
+
+def test_parse_json_clean():
+    result = _parse_json_response('{"violations": [], "overall_score": 100}')
+    assert result["overall_score"] == 100
+    print("  PASS: test_parse_json_clean")
+
+
+def test_parse_json_fenced():
+    result = _parse_json_response('```json\n{"overall_score": 80}\n```')
+    assert result["overall_score"] == 80
+    print("  PASS: test_parse_json_fenced")
+
+
+# === Formatting ===
+
+def test_format_json():
+    report = A11yAuditReport(site="test.com", pages_audited=1, overall_score=90)
+    output = format_report(report, "json")
+    parsed = json.loads(output)
+    assert parsed["site"] == "test.com"
+    assert parsed["overall_score"] == 90
+    print("  PASS: test_format_json")
+
+
+def test_format_text():
+    report = A11yAuditReport(site="test.com", pages_audited=1, overall_score=90,
+                              summary="Test complete")
+    output = format_report(report, "text")
+    assert "ACCESSIBILITY AUDIT" in output
+    assert "test.com" in output
+    print("  PASS: test_format_text")
+
+
+# === Run All ===
+
+def run_all():
+    print("=== foundation_accessibility_audit tests ===")
+    tests = [
+        test_parse_color_hex6, test_parse_color_hex3, test_parse_color_rgb,
+        test_parse_color_named, test_parse_color_invalid,
+        test_contrast_ratio_black_white, test_contrast_ratio_same, test_contrast_ratio_wcag_aa,
+        test_parser_title, test_parser_images, test_parser_headings,
+        test_parser_lang, test_parser_landmarks,
+        test_check_page_title_empty, test_check_page_title_present,
+        test_check_lang_missing,
+        test_check_images_missing_alt, test_check_images_with_alt, test_check_images_decorative,
+        test_check_headings_no_h1, test_check_headings_skip,
+        test_check_skip_nav_missing,
+        test_check_link_text_empty, test_check_link_text_generic,
+        test_run_programmatic_checks_full,
+        test_parse_json_clean, test_parse_json_fenced,
+        test_format_json, test_format_text,
+    ]
+    passed = 0
+    failed = 0
+    for test in tests:
+        try:
+            test()
+            passed += 1
+        except Exception as e:
+            print(f"  FAIL: {test.__name__} — {e}")
+            failed += 1
+    print(f"\n{'ALL PASSED' if failed == 0 else f'{failed} FAILED'}: {passed}/{len(tests)}")
+    return failed == 0
+
+
+if __name__ == "__main__":
+    sys.exit(0 if run_all() else 1)

tests/test_glitch_detector.py

@@ -0,0 +1,380 @@
+#!/usr/bin/env python3
+"""
+Tests for Matrix 3D Glitch Detector (timmy-config#491).
+
+Covers: glitch_patterns, matrix_glitch_detector core logic.
+"""
+
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+# Ensure bin/ is importable
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "bin"))
+
+from glitch_patterns import (
+    GlitchCategory,
+    GlitchPattern,
+    GlitchSeverity,
+    MATRIX_GLITCH_PATTERNS,
+    THREEJS_CATEGORIES,
+    build_vision_prompt,
+    get_pattern_by_category,
+    get_patterns_by_severity,
+    get_threejs_patterns,
+)
+
+from matrix_glitch_detector import (
+    DetectedGlitch,
+    ScanResult,
+    _infer_severity,
+    _parse_vision_response,
+    build_report,
+    generate_scan_angles,
+    run_demo,
+)
+
+
+class TestGlitchPatterns(unittest.TestCase):
+    """Tests for glitch_patterns module."""
+
+    def test_pattern_count(self):
+        """Verify we have a reasonable number of defined patterns."""
+        self.assertGreaterEqual(len(MATRIX_GLITCH_PATTERNS), 14)  # 10 generic + 6 Three.js
+
+    def test_all_patterns_have_required_fields(self):
+        """Every pattern must have category, name, description, severity, prompts."""
+        for p in MATRIX_GLITCH_PATTERNS:
+            self.assertIsInstance(p.category, GlitchCategory)
+            self.assertTrue(p.name)
+            self.assertTrue(p.description)
+            self.assertIsInstance(p.severity, GlitchSeverity)
+            self.assertGreater(len(p.detection_prompts), 0)
+            self.assertGreater(len(p.visual_indicators), 0)
+            self.assertGreater(p.confidence_threshold, 0)
+            self.assertLessEqual(p.confidence_threshold, 1.0)
+
+    def test_pattern_to_dict(self):
+        """Pattern serialization should produce a dict with expected keys."""
+        p = MATRIX_GLITCH_PATTERNS[0]
+        d = p.to_dict()
+        self.assertIn("category", d)
+        self.assertIn("name", d)
+        self.assertIn("severity", d)
+        self.assertEqual(d["category"], p.category.value)
+
+    def test_get_patterns_by_severity(self):
+        """Severity filter should return only patterns at or above threshold."""
+        high_patterns = get_patterns_by_severity(GlitchSeverity.HIGH)
+        self.assertTrue(all(p.severity.value in ("high", "critical") for p in high_patterns))
+        self.assertGreater(len(high_patterns), 0)
+
+        all_patterns = get_patterns_by_severity(GlitchSeverity.INFO)
+        self.assertEqual(len(all_patterns), len(MATRIX_GLITCH_PATTERNS))
+
+    def test_get_pattern_by_category(self):
+        """Lookup by category should return the correct pattern."""
+        p = get_pattern_by_category(GlitchCategory.FLOATING_ASSETS)
+        self.assertIsNotNone(p)
+        self.assertEqual(p.category, GlitchCategory.FLOATING_ASSETS)
+
+        missing = get_pattern_by_category("nonexistent_category_value")
+        self.assertIsNone(missing)
+
+    def test_build_vision_prompt(self):
+        """Vision prompt should contain pattern names and be non-trivial."""
+        prompt = build_vision_prompt()
+        self.assertGreater(len(prompt), 200)
+        self.assertIn("Floating Object", prompt)
+        self.assertIn("Z-Fighting", prompt)
+        self.assertIn("Missing", prompt)
+        # Three.js patterns should be included
+        self.assertIn("Shader Compilation Failure", prompt)
+        self.assertIn("Bloom Overflow", prompt)
+
+    def test_build_vision_prompt_subset(self):
+        """Vision prompt with subset should only include specified patterns."""
+        subset = MATRIX_GLITCH_PATTERNS[:3]
+        prompt = build_vision_prompt(subset)
+        self.assertIn(subset[0].name, prompt)
+        self.assertNotIn(MATRIX_GLITCH_PATTERNS[-1].name, prompt)
+
+
+class TestGlitchDetector(unittest.TestCase):
+    """Tests for matrix_glitch_detector module."""
+
+    def test_generate_scan_angles_default(self):
+        """Default 4 angles should return front, right, back, left."""
+        angles = generate_scan_angles(4)
+        self.assertEqual(len(angles), 4)
+        labels = [a["label"] for a in angles]
+        self.assertIn("front", labels)
+        self.assertIn("right", labels)
+        self.assertIn("back", labels)
+        self.assertIn("left", labels)
+
+    def test_generate_scan_angles_many(self):
+        """Requesting more angles than base should still return correct count."""
+        angles = generate_scan_angles(12)
+        self.assertEqual(len(angles), 12)
+        # Should still have the standard ones
+        labels = [a["label"] for a in angles]
+        self.assertIn("front", labels)
+
+    def test_generate_scan_angles_few(self):
+        """Requesting fewer angles should return fewer."""
+        angles = generate_scan_angles(2)
+        self.assertEqual(len(angles), 2)
+
+    def test_detected_glitch_dataclass(self):
+        """DetectedGlitch should serialize cleanly."""
+        g = DetectedGlitch(
+            id="test001",
+            category="floating_assets",
+            name="Test Glitch",
+            description="A test glitch",
+            severity="high",
+            confidence=0.85,
+            location_x=50.0,
+            location_y=30.0,
+            screenshot_index=0,
+            screenshot_angle="front",
+        )
+        self.assertEqual(g.id, "test001")
+        self.assertTrue(g.timestamp)  # Auto-generated
+
+    def test_infer_severity_critical(self):
+        """Missing textures should infer critical/high severity."""
+        sev = _infer_severity("missing_textures", 0.9)
+        self.assertEqual(sev, "critical")
+        sev_low = _infer_severity("missing_textures", 0.5)
+        self.assertEqual(sev_low, "high")
+
+    def test_infer_severity_floating(self):
+        """Floating assets should infer high/medium severity."""
+        sev = _infer_severity("floating_assets", 0.8)
+        self.assertEqual(sev, "high")
+        sev_low = _infer_severity("floating_assets", 0.5)
+        self.assertEqual(sev_low, "medium")
+
+    def test_infer_severity_default(self):
+        """Unknown categories should default to medium/low."""
+        sev = _infer_severity("unknown_thing", 0.7)
+        self.assertEqual(sev, "medium")
+        sev_low = _infer_severity("unknown_thing", 0.3)
+        self.assertEqual(sev_low, "low")
+
+    def test_parse_vision_response_json_array(self):
+        """Should parse a JSON array response."""
+        response = json.dumps([
+            {
+                "category": "floating_assets",
+                "name": "Float Test",
+                "description": "Chair floating",
+                "confidence": 0.9,
+                "severity": "high",
+                "location_x": 40,
+                "location_y": 60,
+            }
+        ])
+        glitches = _parse_vision_response(response, 0, "front")
+        self.assertEqual(len(glitches), 1)
+        self.assertEqual(glitches[0].category, "floating_assets")
+        self.assertAlmostEqual(glitches[0].confidence, 0.9)
+
+    def test_parse_vision_response_wrapped(self):
+        """Should parse a response with 'glitches' wrapper key."""
+        response = json.dumps({
+            "glitches": [
+                {
+                    "category": "z_fighting",
+                    "name": "Shimmer",
+                    "confidence": 0.6,
+                }
+            ]
+        })
+        glitches = _parse_vision_response(response, 1, "right")
+        self.assertEqual(len(glitches), 1)
+        self.assertEqual(glitches[0].category, "z_fighting")
+
+    def test_parse_vision_response_empty(self):
+        """Should return empty list for non-JSON text."""
+        glitches = _parse_vision_response("No glitches found.", 0, "front")
+        self.assertEqual(len(glitches), 0)
+
+    def test_parse_vision_response_code_block(self):
+        """Should extract JSON from markdown code blocks."""
+        response = '```json\n[{"category": "clipping", "name": "Clip", "confidence": 0.7}]\n```'
+        glitches = _parse_vision_response(response, 0, "front")
+        self.assertEqual(len(glitches), 1)
+
+    def test_build_report(self):
+        """Report should have correct summary statistics."""
+        angles = generate_scan_angles(4)
+        screenshots = [Path(f"/tmp/ss_{i}.png") for i in range(4)]
+        glitches = [
+            DetectedGlitch(
+                id="a", category="floating_assets", name="Float",
+                description="", severity="high", confidence=0.8,
+                screenshot_index=0, screenshot_angle="front",
+            ),
+            DetectedGlitch(
+                id="b", category="missing_textures", name="Missing",
+                description="", severity="critical", confidence=0.95,
+                screenshot_index=1, screenshot_angle="right",
+            ),
+        ]
+        report = build_report("https://test.com", angles, screenshots, glitches)
+
+        self.assertEqual(report.total_screenshots, 4)
+        self.assertEqual(len(report.glitches), 2)
+        self.assertEqual(report.summary["total_glitches"], 2)
+        self.assertEqual(report.summary["by_severity"]["critical"], 1)
+        self.assertEqual(report.summary["by_severity"]["high"], 1)
+        self.assertEqual(report.summary["by_category"]["floating_assets"], 1)
+        self.assertEqual(report.metadata["reference"], "timmy-config#491")
+
+    def test_build_report_json_roundtrip(self):
+        """Report JSON should parse back correctly."""
+        angles = generate_scan_angles(2)
+        screenshots = [Path(f"/tmp/ss_{i}.png") for i in range(2)]
+        report = build_report("https://test.com", angles, screenshots, [])
+        json_str = report.to_json()
+        parsed = json.loads(json_str)
+        self.assertEqual(parsed["url"], "https://test.com")
+        self.assertEqual(parsed["total_screenshots"], 2)
+
+    def test_run_demo(self):
+        """Demo mode should produce a report with simulated glitches."""
+        with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as f:
+            output_path = Path(f.name)
+
+        try:
+            report = run_demo(output_path)
+            self.assertEqual(len(report.glitches), 6)  # 4 original + 2 Three.js
+            self.assertGreater(report.summary["total_glitches"], 0)
+            self.assertTrue(output_path.exists())
+
+            # Verify the saved JSON is valid
+            saved = json.loads(output_path.read_text())
+            self.assertIn("scan_id", saved)
+            self.assertIn("glitches", saved)
+        finally:
+            output_path.unlink(missing_ok=True)
+
+
+class TestThreeJsPatterns(unittest.TestCase):
+    """Tests for Three.js-specific glitch patterns (timmy-config#543)."""
+
+    def test_get_threejs_patterns_returns_only_threejs(self):
+        """get_threejs_patterns() should return only Three.js categories."""
+        patterns = get_threejs_patterns()
+        self.assertEqual(len(patterns), 6)
+        for p in patterns:
+            self.assertIn(p.category, THREEJS_CATEGORIES)
+
+    def test_threejs_patterns_have_required_fields(self):
+        """All Three.js patterns must have valid fields."""
+        for p in get_threejs_patterns():
+            self.assertIsInstance(p.category, GlitchCategory)
+            self.assertTrue(p.name)
+            self.assertTrue(p.description)
+            self.assertIsInstance(p.severity, GlitchSeverity)
+            self.assertGreater(len(p.detection_prompts), 0)
+            self.assertGreater(len(p.visual_indicators), 0)
+
+    def test_shader_failure_is_critical(self):
+        """Shader compilation failure should be CRITICAL severity."""
+        p = get_pattern_by_category(GlitchCategory.SHADER_FAILURE)
+        self.assertIsNotNone(p)
+        self.assertEqual(p.severity, GlitchSeverity.CRITICAL)
+
+    def test_texture_placeholder_is_critical(self):
+        """Texture placeholder (1x1 white) should be CRITICAL severity."""
+        p = get_pattern_by_category(GlitchCategory.TEXTURE_PLACEHOLDER)
+        self.assertIsNotNone(p)
+        self.assertEqual(p.severity, GlitchSeverity.CRITICAL)
+
+    def test_infer_severity_shader_failure(self):
+        """Shader failure should infer critical/high."""
+        self.assertEqual(_infer_severity("shader_failure", 0.8), "critical")
+        self.assertEqual(_infer_severity("shader_failure", 0.5), "high")
+
+    def test_infer_severity_texture_placeholder(self):
+        """Texture placeholder should infer critical/high."""
+        self.assertEqual(_infer_severity("texture_placeholder", 0.8), "critical")
+        self.assertEqual(_infer_severity("texture_placeholder", 0.5), "high")
+
+    def test_infer_severity_uv_mapping(self):
+        """UV mapping error should infer high/medium."""
+        self.assertEqual(_infer_severity("uv_mapping_error", 0.8), "high")
+        self.assertEqual(_infer_severity("uv_mapping_error", 0.5), "medium")
+
+    def test_infer_severity_frustum_culling(self):
+        """Frustum culling should infer medium/low."""
+        self.assertEqual(_infer_severity("frustum_culling", 0.7), "medium")
+        self.assertEqual(_infer_severity("frustum_culling", 0.4), "low")
+
+    def test_infer_severity_shadow_map(self):
+        """Shadow map artifact should infer medium/low."""
+        self.assertEqual(_infer_severity("shadow_map_artifact", 0.7), "medium")
+        self.assertEqual(_infer_severity("shadow_map_artifact", 0.4), "low")
+
+    def test_infer_severity_bloom_overflow(self):
+        """Bloom overflow should infer medium/low (default path)."""
+        self.assertEqual(_infer_severity("bloom_overflow", 0.7), "medium")
+        self.assertEqual(_infer_severity("bloom_overflow", 0.4), "low")
+
+    def test_threejs_patterns_in_vision_prompt(self):
+        """Three.js patterns should appear in the composite vision prompt."""
+        prompt = build_vision_prompt()
+        self.assertIn("shader_failure", prompt)
+        self.assertIn("texture_placeholder", prompt)
+        self.assertIn("uv_mapping_error", prompt)
+        self.assertIn("frustum_culling", prompt)
+        self.assertIn("shadow_map_artifact", prompt)
+        self.assertIn("bloom_overflow", prompt)
+
+    def test_threejs_subset_prompt(self):
+        """Building prompt from Three.js-only patterns should work."""
+        threejs = get_threejs_patterns()
+        prompt = build_vision_prompt(threejs)
+        self.assertIn("Shader Compilation Failure", prompt)
+        self.assertNotIn("Floating Object", prompt)  # generic, not Three.js
+
+    def test_report_metadata_version(self):
+        """Report metadata should reference both issues."""
+        report = run_demo()
+        self.assertEqual(report.metadata["detector_version"], "0.2.0")
+        self.assertIn("543", report.metadata["reference"])
+
+
+
+class TestIntegration(unittest.TestCase):
+    """Integration-level tests."""
+
+    def test_full_pipeline_demo(self):
+        """End-to-end demo pipeline should complete without errors."""
+        report = run_demo()
+        self.assertIsNotNone(report.scan_id)
+        self.assertTrue(report.timestamp)
+        self.assertGreater(report.total_screenshots, 0)
+
+    def test_patterns_cover_matrix_themes(self):
+        """Patterns should cover the main Matrix glitch themes."""
+        category_values = {p.category.value for p in MATRIX_GLITCH_PATTERNS}
+        expected = {"floating_assets", "z_fighting", "missing_textures", "clipping", "broken_normals"}
+        self.assertTrue(expected.issubset(category_values))
+
+    def test_patterns_cover_threejs_themes(self):
+        """Patterns should cover Three.js-specific glitch themes (#543)."""
+        category_values = {p.category.value for p in MATRIX_GLITCH_PATTERNS}
+        threejs_expected = {"shader_failure", "texture_placeholder", "uv_mapping_error",
+                           "frustum_culling", "shadow_map_artifact", "bloom_overflow"}
+        self.assertTrue(threejs_expected.issubset(category_values))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_matrix_glitch_detect.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Tests for matrix_glitch_detect.py — verifies detection and HTML report logic."""
+
+import json
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))
+
+from matrix_glitch_detect import (
+    Severity, Glitch, GlitchReport,
+    format_report, generate_html_report, _parse_json_response,
+)
+
+
+def test_parse_json_clean():
+    result = _parse_json_response('{"glitches": [], "overall_quality": 95}')
+    assert result["overall_quality"] == 95
+    print("  PASS: test_parse_json_clean")
+
+
+def test_parse_json_fenced():
+    result = _parse_json_response('```json\n{"overall_quality": 80}\n```')
+    assert result["overall_quality"] == 80
+    print("  PASS: test_parse_json_fenced")
+
+
+def test_parse_json_garbage():
+    assert _parse_json_response("no json") == {}
+    print("  PASS: test_parse_json_garbage")
+
+
+def test_glitch_dataclass():
+    g = Glitch(type="z_fighting", severity=Severity.MAJOR, region="center", description="Shimmer", confidence=0.8)
+    assert g.type == "z_fighting"
+    assert g.confidence == 0.8
+    print("  PASS: test_glitch_dataclass")
+
+
+def test_report_dataclass():
+    r = GlitchReport(source="test.png", status="WARN", score=75)
+    r.glitches.append(Glitch(type="float", severity=Severity.MINOR))
+    assert len(r.glitches) == 1
+    assert r.score == 75
+    print("  PASS: test_report_dataclass")
+
+
+def test_format_json():
+    r = GlitchReport(source="test.png", status="PASS", score=90, summary="Clean")
+    r.glitches.append(Glitch(type="cosmetic", severity=Severity.COSMETIC, description="Minor"))
+    output = format_report(r, "json")
+    parsed = json.loads(output)
+    assert parsed["status"] == "PASS"
+    assert len(parsed["glitches"]) == 1
+    print("  PASS: test_format_json")
+
+
+def test_format_text():
+    r = GlitchReport(source="test.png", status="FAIL", score=30, summary="Critical glitch")
+    r.glitches.append(Glitch(type="render_failure", severity=Severity.CRITICAL, description="Black screen"))
+    output = format_report(r, "text")
+    assert "FAIL" in output
+    assert "render_failure" in output
+    print("  PASS: test_format_text")
+
+
+def test_html_report_basic():
+    r = GlitchReport(source="test.png", status="PASS", score=100)
+    html = generate_html_report([r], title="Test Report")
+    assert "<!DOCTYPE html>" in html
+    assert "Test Report" in html
+    assert "PASS" in html
+    assert "100" in html
+    print("  PASS: test_html_report_basic")
+
+
+def test_html_report_with_glitches():
+    r = GlitchReport(source="test.png", status="FAIL", score=40)
+    r.glitches.append(Glitch(type="z_fighting", severity=Severity.CRITICAL, region="center", description="Heavy flicker", confidence=0.9))
+    r.glitches.append(Glitch(type="clipping", severity=Severity.MINOR, region="bottom", description="Object through floor", confidence=0.6))
+    html = generate_html_report([r], title="Glitch Report")
+    assert "z_fighting" in html
+    assert "CRITICAL" in html
+    assert "clipping" in html
+    assert "Heavy flicker" in html
+    print("  PASS: test_html_report_with_glitches")
+
+
+def test_html_report_multi():
+    r1 = GlitchReport(source="a.png", status="PASS", score=95)
+    r2 = GlitchReport(source="b.png", status="WARN", score=70)
+    r2.glitches.append(Glitch(type="texture_pop", severity=Severity.MAJOR))
+    html = generate_html_report([r1, r2])
+    assert "a.png" in html
+    assert "b.png" in html
+    assert "2" in html  # 2 screenshots
+    print("  PASS: test_html_report_multi")
+
+
+def test_html_self_contained():
+    r = GlitchReport(source="test.png", status="PASS", score=100)
+    html = generate_html_report([r])
+    assert "external" not in html.lower() or "no external dependencies" in html.lower()
+    assert "<style>" in html  # Inline CSS
+    print("  PASS: test_html_self_contained")
+
+
+def test_missing_image():
+    r = GlitchReport(source="/nonexistent/image.png")
+    # detect_glitches would set FAIL — simulate
+    r.status = "FAIL"
+    r.score = 0
+    r.summary = "File not found"
+    assert r.status == "FAIL"
+    print("  PASS: test_missing_image")
+
+
+def test_severity_enum():
+    assert Severity.CRITICAL.value == "critical"
+    assert Severity.MAJOR.value == "major"
+    print("  PASS: test_severity_enum")
+
+
+def run_all():
+    print("=== matrix_glitch_detect tests ===")
+    tests = [
+        test_parse_json_clean, test_parse_json_fenced, test_parse_json_garbage,
+        test_glitch_dataclass, test_report_dataclass,
+        test_format_json, test_format_text,
+        test_html_report_basic, test_html_report_with_glitches,
+        test_html_report_multi, test_html_self_contained,
+        test_missing_image, test_severity_enum,
+    ]
+    passed = failed = 0
+    for t in tests:
+        try:
+            t()
+            passed += 1
+        except Exception as e:
+            print(f"  FAIL: {t.__name__} — {e}")
+            failed += 1
+    print(f"\n{'ALL PASSED' if failed == 0 else f'{failed} FAILED'}: {passed}/{len(tests)}")
+    return failed == 0
+
+
+if __name__ == "__main__":
+    sys.exit(0 if run_all() else 1)

tests/test_nexus_smoke_test.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Tests for nexus_smoke_test.py — verifies smoke test logic."""
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))
+
+from nexus_smoke_test import (
+    Severity, SmokeCheck, SmokeResult,
+    format_result, _parse_json_response,
+)
+
+
+def test_parse_json_clean():
+    result = _parse_json_response('{"status": "PASS", "summary": "ok"}')
+    assert result["status"] == "PASS"
+    print("  PASS: test_parse_json_clean")
+
+
+def test_parse_json_fenced():
+    result = _parse_json_response('```json\n{"status": "FAIL"}\n```')
+    assert result["status"] == "FAIL"
+    print("  PASS: test_parse_json_fenced")
+
+
+def test_parse_json_garbage():
+    result = _parse_json_response("no json here")
+    assert result == {}
+    print("  PASS: test_parse_json_garbage")
+
+
+def test_smoke_check_dataclass():
+    c = SmokeCheck(name="Test", status=Severity.PASS, message="All good")
+    assert c.name == "Test"
+    assert c.status == Severity.PASS
+    print("  PASS: test_smoke_check_dataclass")
+
+
+def test_smoke_result_dataclass():
+    r = SmokeResult(url="https://example.com", status=Severity.PASS)
+    r.checks.append(SmokeCheck(name="Page Loads", status=Severity.PASS))
+    assert len(r.checks) == 1
+    assert r.url == "https://example.com"
+    print("  PASS: test_smoke_result_dataclass")
+
+
+def test_format_json():
+    r = SmokeResult(url="https://test.com", status=Severity.PASS, summary="All good", duration_ms=100)
+    r.checks.append(SmokeCheck(name="Test", status=Severity.PASS, message="OK"))
+    output = format_result(r, "json")
+    parsed = json.loads(output)
+    assert parsed["status"] == "pass"
+    assert parsed["url"] == "https://test.com"
+    assert len(parsed["checks"]) == 1
+    print("  PASS: test_format_json")
+
+
+def test_format_text():
+    r = SmokeResult(url="https://test.com", status=Severity.WARN, summary="1 warning", duration_ms=200)
+    r.checks.append(SmokeCheck(name="Screenshot", status=Severity.WARN, message="No backend"))
+    output = format_result(r, "text")
+    assert "NEXUS VISUAL SMOKE TEST" in output
+    assert "https://test.com" in output
+    assert "WARN" in output
+    print("  PASS: test_format_text")
+
+
+def test_format_text_pass():
+    r = SmokeResult(url="https://test.com", status=Severity.PASS, summary="All clear")
+    r.checks.append(SmokeCheck(name="Page Loads", status=Severity.PASS, message="HTTP 200"))
+    r.checks.append(SmokeCheck(name="HTML Content", status=Severity.PASS, message="Valid"))
+    output = format_result(r, "text")
+    assert "✅" in output
+    assert "Page Loads" in output
+    print("  PASS: test_format_text")
+
+
+def test_severity_enum():
+    assert Severity.PASS.value == "pass"
+    assert Severity.FAIL.value == "fail"
+    assert Severity.WARN.value == "warn"
+    print("  PASS: test_severity_enum")
+
+
+def test_overall_status_logic():
+    # All pass
+    r = SmokeResult()
+    r.checks = [SmokeCheck(name="a", status=Severity.PASS), SmokeCheck(name="b", status=Severity.PASS)]
+    fails = sum(1 for c in r.checks if c.status == Severity.FAIL)
+    warns = sum(1 for c in r.checks if c.status == Severity.WARN)
+    assert fails == 0 and warns == 0
+
+    # One fail
+    r.checks.append(SmokeCheck(name="c", status=Severity.FAIL))
+    fails = sum(1 for c in r.checks if c.status == Severity.FAIL)
+    assert fails == 1
+    print("  PASS: test_overall_status_logic")
+
+
+def run_all():
+    print("=== nexus_smoke_test tests ===")
+    tests = [
+        test_parse_json_clean, test_parse_json_fenced, test_parse_json_garbage,
+        test_smoke_check_dataclass, test_smoke_result_dataclass,
+        test_format_json, test_format_text, test_format_text_pass,
+        test_severity_enum, test_overall_status_logic,
+    ]
+    passed = failed = 0
+    for t in tests:
+        try:
+            t()
+            passed += 1
+        except Exception as e:
+            print(f"  FAIL: {t.__name__} — {e}")
+            failed += 1
+    print(f"\n{'ALL PASSED' if failed == 0 else f'{failed} FAILED'}: {passed}/{len(tests)}")
+    return failed == 0
+
+
+if __name__ == "__main__":
+    sys.exit(0 if run_all() else 1)

training-data/scene-descriptions-rock.jsonl

@@ -0,0 +1,100 @@
+{"song": "Thunder Road", "artist": "Heartland", "beat": 1, "timestamp": "0:00", "duration": "30s", "lyric_line": "The screen door slams, Mary's dress waves", "scene": {"mood": "hope", "colors": ["gold", "sky blue", "white"], "composition": "wide shot", "camera": "static", "description": "Open horizon. Golden light breaking through clouds. The figure silhouetted against dawn. The screen door slams, Mary's dress waves"}}
+{"song": "Thunder Road", "artist": "Heartland", "beat": 2, "timestamp": "0:30", "duration": "30s", "lyric_line": "Like a vision she dances across the porch as the radio plays", "scene": {"mood": "anticipation", "colors": ["silver", "pale green", "cream"], "composition": "close-up", "camera": "slow pan", "description": "Close on hands gripping a steering wheel. Dashboard lights reflecting in eyes. Road stretching ahead. Like a vision she dances across the porch as the radio plays"}}
+{"song": "Thunder Road", "artist": "Heartland", "beat": 3, "timestamp": "1:00", "duration": "30s", "lyric_line": "Roy Orbison singing for the lonely, hey that's me and I want you only", "scene": {"mood": "energy", "colors": ["red", "orange", "electric blue"], "composition": "over the shoulder", "camera": "dolly in", "description": "Rapid cuts. Bodies in motion. Light streaks across the frame. Roy Orbison singing for the lonely, hey that's me and I want you only"}}
+{"song": "Thunder Road", "artist": "Heartland", "beat": 4, "timestamp": "1:30", "duration": "30s", "lyric_line": "Don't turn me home out now I'm so young and worthless still", "scene": {"mood": "triumph", "colors": ["gold", "crimson", "white"], "composition": "low angle", "camera": "dolly out", "description": "Wide shot. Figure standing on a hilltop. Arms raised. City lights below. Don't turn me home out now I'm so young and worthless still"}}
+{"song": "Thunder Road", "artist": "Heartland", "beat": 5, "timestamp": "2:00", "duration": "30s", "lyric_line": "The night's busting open these two lanes will take us anywhere", "scene": {"mood": "nostalgia", "colors": ["amber", "sepia", "dusty rose"], "composition": "high angle", "camera": "handheld", "description": "Sepia tones. A photograph come to life. Dust motes in afternoon light. The night's busting open these two lanes will take us anywhere"}}
+{"song": "Thunder Road", "artist": "Heartland", "beat": 6, "timestamp": "2:30", "duration": "30s", "lyric_line": "We got one last chance to make it real", "scene": {"mood": "urgency", "colors": ["red", "black", "strobe white"], "composition": "dutch angle", "camera": "steadicam", "description": "Handheld camera running. Blurred faces. Traffic. Heartbeat sound design. We got one last chance to make it real"}}
+{"song": "Thunder Road", "artist": "Heartland", "beat": 7, "timestamp": "3:00", "duration": "30s", "lyric_line": "To trade in these wings on some wheels", "scene": {"mood": "passion", "colors": ["deep red", "burgundy", "gold"], "composition": "symmetrical", "camera": "slow zoom", "description": "Extreme close-up. Skin. Breath visible in cold air. Eyes locked. To trade in these wings on some wheels"}}
+{"song": "Thunder Road", "artist": "Heartland", "beat": 8, "timestamp": "3:30", "duration": "30s", "lyric_line": "Climb in back, heaven's waiting down the tracks", "scene": {"mood": "defiance", "colors": ["black", "neon green", "chrome"], "composition": "rule of thirds", "camera": "crane up", "description": "Low angle. Figure standing against the wind. Debris flying past. Unmoved. Climb in back, heaven's waiting down the tracks"}}
+{"song": "Thunder Road", "artist": "Heartland", "beat": 9, "timestamp": "4:00", "duration": "30s", "lyric_line": "Oh oh oh oh oh oh oh", "scene": {"mood": "release", "colors": ["sky blue", "white", "pale gold"], "composition": "extreme wide", "camera": "tracking shot", "description": "Slow motion. Something falling \u2014 a mask, a chain, a weight. Lightness follows. Oh oh oh oh oh oh oh"}}
+{"song": "Thunder Road", "artist": "Heartland", "beat": 10, "timestamp": "4:30", "duration": "30s", "lyric_line": "It's a town full of losers and I'm pulling out of here to win", "scene": {"mood": "catharsis", "colors": ["all white", "silver", "clear"], "composition": "medium shot", "camera": "slow tilt down", "description": "White space expanding. Figure dissolving into light. Peace in the dissolution. It's a town full of losers and I'm pulling out of here to win"}}
+{"song": "Black Dog Howl", "artist": "Rust & Wire", "beat": 1, "timestamp": "0:00", "duration": "30s", "lyric_line": "Woke up on the floor again, whiskey still on my tongue", "scene": {"mood": "despair", "colors": ["navy", "black", "grey"], "composition": "wide shot", "camera": "static", "description": "Empty room. Single light source. Figure curled in corner. Rain on windows. Woke up on the floor again, whiskey still on my tongue"}}
+{"song": "Black Dog Howl", "artist": "Rust & Wire", "beat": 2, "timestamp": "0:30", "duration": "30s", "lyric_line": "The mirror shows a stranger and the damage that I've done", "scene": {"mood": "anger", "colors": ["red", "black", "orange"], "composition": "close-up", "camera": "slow pan", "description": "Shattered glass. Red light. Hands clenched. Jaw tight. The frame vibrates. The mirror shows a stranger and the damage that I've done"}}
+{"song": "Black Dog Howl", "artist": "Rust & Wire", "beat": 3, "timestamp": "1:00", "duration": "30s", "lyric_line": "I scream until my throat bleeds but nobody comes", "scene": {"mood": "frenzy", "colors": ["strobe", "red", "white flash"], "composition": "over the shoulder", "camera": "dolly in", "description": "Strobe lighting. Multiple exposures. Bodies colliding. Chaos as composition. I scream until my throat bleeds but nobody comes"}}
+{"song": "Black Dog Howl", "artist": "Rust & Wire", "beat": 4, "timestamp": "1:30", "duration": "30s", "lyric_line": "The walls are closing in again, the ceiling pressing down", "scene": {"mood": "exhaustion", "colors": ["grey", "brown", "faded"], "composition": "low angle", "camera": "dolly out", "description": "Static shot. Figure slumped. Eyes half-closed. Time passing in shadows. The walls are closing in again, the ceiling pressing down"}}
+{"song": "Black Dog Howl", "artist": "Rust & Wire", "beat": 5, "timestamp": "2:00", "duration": "30s", "lyric_line": "I tried to call your number but you changed it years ago", "scene": {"mood": "resignation", "colors": ["grey", "muted blue", "beige"], "composition": "high angle", "camera": "handheld", "description": "Medium shot. Hands dropping keys on a table. Turning away. Not looking back. I tried to call your number but you changed it years ago"}}
+{"song": "Black Dog Howl", "artist": "Rust & Wire", "beat": 6, "timestamp": "2:30", "duration": "30s", "lyric_line": "Now I'm howling at the moon like some rabid dog I know", "scene": {"mood": "grief", "colors": ["deep purple", "black", "silver"], "composition": "dutch angle", "camera": "steadicam", "description": "Wide shot. Figure alone in vast space. Dark purple sky. No horizon line. Now I'm howling at the moon like some rabid dog I know"}}
+{"song": "Black Dog Howl", "artist": "Rust & Wire", "beat": 7, "timestamp": "3:00", "duration": "30s", "lyric_line": "Every bone remembers what my mind wants to forget", "scene": {"mood": "numbness", "colors": ["white", "grey", "no color"], "composition": "symmetrical", "camera": "slow zoom", "description": "Desaturated. Figure staring at nothing. World moving around them in blur. Every bone remembers what my mind wants to forget"}}
+{"song": "Black Dog Howl", "artist": "Rust & Wire", "beat": 8, "timestamp": "3:30", "duration": "30s", "lyric_line": "I'll tear this whole house down before the sun comes up", "scene": {"mood": "rage", "colors": ["fire red", "black", "ember orange"], "composition": "rule of thirds", "camera": "crane up", "description": "Red wash. Extreme close-up on eyes. Fire reflected in pupils. I'll tear this whole house down before the sun comes up"}}
+{"song": "Black Dog Howl", "artist": "Rust & Wire", "beat": 9, "timestamp": "4:00", "duration": "30s", "lyric_line": "Ash and ruin everywhere, this is all that's left", "scene": {"mood": "acceptance", "colors": ["soft blue", "warm grey", "sage"], "composition": "extreme wide", "camera": "tracking shot", "description": "Soft focus. Gentle light. Figure breathing. The camera doesn't judge. Ash and ruin everywhere, this is all that's left"}}
+{"song": "Black Dog Howl", "artist": "Rust & Wire", "beat": 10, "timestamp": "4:30", "duration": "30s", "lyric_line": "Silence. Just the wind through broken glass.", "scene": {"mood": "silence", "colors": ["black", "void", "faint starlight"], "composition": "medium shot", "camera": "slow tilt down", "description": "Black screen. Faint starlight. The sound drops out completely. Silence. Just the wind through broken glass."}}
+{"song": "Satellite Hearts", "artist": "Neon Circuit", "beat": 1, "timestamp": "0:00", "duration": "30s", "lyric_line": "Ten thousand miles of static between your voice and mine", "scene": {"mood": "wonder", "colors": ["aurora green", "violet", "silver"], "composition": "wide shot", "camera": "static", "description": "Northern lights overhead. Figure looking up. Mouth open. Child's expression. Ten thousand miles of static between your voice and mine"}}
+{"song": "Satellite Hearts", "artist": "Neon Circuit", "beat": 2, "timestamp": "0:30", "duration": "30s", "lyric_line": "I trace your constellation on the dashboard every night", "scene": {"mood": "isolation", "colors": ["cold blue", "black", "distant starlight"], "composition": "close-up", "camera": "slow pan", "description": "Extreme wide. Single figure. Vast empty landscape. Scale crushing. I trace your constellation on the dashboard every night"}}
+{"song": "Satellite Hearts", "artist": "Neon Circuit", "beat": 3, "timestamp": "1:00", "duration": "30s", "lyric_line": "The signal fades to nothing but I keep the frequency", "scene": {"mood": "longing", "colors": ["teal", "silver", "moonlight"], "composition": "over the shoulder", "camera": "dolly in", "description": "Through a window. Figure on the other side. Glass between. Breath on the pane. The signal fades to nothing but I keep the frequency"}}
+{"song": "Satellite Hearts", "artist": "Neon Circuit", "beat": 4, "timestamp": "1:30", "duration": "30s", "lyric_line": "Then suddenly your laughter breaks through like a summer storm", "scene": {"mood": "connection", "colors": ["warm gold", "rose", "blush"], "composition": "low angle", "camera": "dolly out", "description": "Two hands reaching. Fingers almost touching. Warm light between them. Then suddenly your laughter breaks through like a summer storm"}}
+{"song": "Satellite Hearts", "artist": "Neon Circuit", "beat": 5, "timestamp": "2:00", "duration": "30s", "lyric_line": "We're dancing in the data stream, our pixels intertwined", "scene": {"mood": "euphoria", "colors": ["neon", "rainbow", "white flash"], "composition": "high angle", "camera": "handheld", "description": "Overexposed. Everything bright. Dancing. The frame can't contain the joy. We're dancing in the data stream, our pixels intertwined"}}
+{"song": "Satellite Hearts", "artist": "Neon Circuit", "beat": 6, "timestamp": "2:30", "duration": "30s", "lyric_line": "But I can't tell if you're real or just a ghost in the machine", "scene": {"mood": "confusion", "colors": ["swirling", "unsettled", "green-grey"], "composition": "dutch angle", "camera": "steadicam", "description": "Multiple focal points. Nothing sharp. The viewer doesn't know where to look. But I can't tell if you're real or just a ghost in the machine"}}
+{"song": "Satellite Hearts", "artist": "Neon Circuit", "beat": 7, "timestamp": "3:00", "duration": "30s", "lyric_line": "The picture clears and there you are \u2014 imperfect, warm, alive", "scene": {"mood": "clarity", "colors": ["clear blue", "white", "crisp"], "composition": "symmetrical", "camera": "slow zoom", "description": "Rack focus. Background blurs, foreground sharpens. Suddenly everything makes sense. The picture clears and there you are \u2014 imperfect, warm, alive"}}
+{"song": "Satellite Hearts", "artist": "Neon Circuit", "beat": 8, "timestamp": "3:30", "duration": "30s", "lyric_line": "Your hand reaches through the screen, I swear I feel the heat", "scene": {"mood": "tenderness", "colors": ["blush pink", "warm cream", "soft gold"], "composition": "rule of thirds", "camera": "crane up", "description": "Close on a hand touching a face. Soft light. Shallow depth of field. Your hand reaches through the screen, I swear I feel the heat"}}
+{"song": "Satellite Hearts", "artist": "Neon Circuit", "beat": 9, "timestamp": "4:00", "duration": "30s", "lyric_line": "The bandwidth's dying, say it now before the link goes dark", "scene": {"mood": "urgency", "colors": ["red", "black", "strobe white"], "composition": "extreme wide", "camera": "tracking shot", "description": "Handheld camera running. Blurred faces. Traffic. Heartbeat sound design. The bandwidth's dying, say it now before the link goes dark"}}
+{"song": "Satellite Hearts", "artist": "Neon Circuit", "beat": 10, "timestamp": "4:30", "duration": "30s", "lyric_line": "Goodnight, satellite heart. I'll find you in the static.", "scene": {"mood": "bittersweet", "colors": ["amber", "lavender", "fading light"], "composition": "medium shot", "camera": "slow tilt down", "description": "Amber light fading. A smile that's also a goodbye. Beautiful and sad at once. Goodnight, satellite heart. I'll find you in the static."}}
+{"song": "Concrete Garden", "artist": "Streetlight Prophet", "beat": 1, "timestamp": "0:00", "duration": "30s", "lyric_line": "They paved over every green thing when the developers came", "scene": {"mood": "oppression", "colors": ["concrete grey", "brown", "exhaust fume yellow"], "composition": "wide shot", "camera": "static", "description": "Concrete. Overpasses. No sky visible. Figures small against infrastructure. They paved over every green thing when the developers came"}}
+{"song": "Concrete Garden", "artist": "Streetlight Prophet", "beat": 2, "timestamp": "0:30", "duration": "30s", "lyric_line": "But we planted seeds between the cracks and gave them all a name", "scene": {"mood": "resilience", "colors": ["green", "cracked concrete", "gold"], "composition": "close-up", "camera": "slow pan", "description": "Crack in pavement. Green shoot pushing through. Macro lens. But we planted seeds between the cracks and gave them all a name"}}
+{"song": "Concrete Garden", "artist": "Streetlight Prophet", "beat": 3, "timestamp": "1:00", "duration": "30s", "lyric_line": "The mayor says progress looks like demolition and dust", "scene": {"mood": "anger", "colors": ["red", "black", "orange"], "composition": "over the shoulder", "camera": "dolly in", "description": "Shattered glass. Red light. Hands clenched. Jaw tight. The frame vibrates. The mayor says progress looks like demolition and dust"}}
+{"song": "Concrete Garden", "artist": "Streetlight Prophet", "beat": 4, "timestamp": "1:30", "duration": "30s", "lyric_line": "But a dandelion broke through the asphalt this morning \u2014 that's us", "scene": {"mood": "beauty", "colors": ["wildflower colors", "green", "sunlight"], "composition": "low angle", "camera": "dolly out", "description": "Wildflowers in unexpected places. Color against grey. Nature reclaiming. But a dandelion broke through the asphalt this morning \u2014 that's us"}}
+{"song": "Concrete Garden", "artist": "Streetlight Prophet", "beat": 5, "timestamp": "2:00", "duration": "30s", "lyric_line": "You can't kill what wants to live, can't silence what must sing", "scene": {"mood": "defiance", "colors": ["black", "neon green", "chrome"], "composition": "high angle", "camera": "handheld", "description": "Low angle. Figure standing against the wind. Debris flying past. Unmoved. You can't kill what wants to live, can't silence what must sing"}}
+{"song": "Concrete Garden", "artist": "Streetlight Prophet", "beat": 6, "timestamp": "2:30", "duration": "30s", "lyric_line": "We're the roots beneath the road, we're the birds that built on string", "scene": {"mood": "community", "colors": ["warm tones", "string lights", "firelight"], "composition": "dutch angle", "camera": "steadicam", "description": "String lights. People gathered. Laughter out of focus. Warmth as visual language. We're the roots beneath the road, we're the birds that built on string"}}
+{"song": "Concrete Garden", "artist": "Streetlight Prophet", "beat": 7, "timestamp": "3:00", "duration": "30s", "lyric_line": "When they tear the next block down we'll be dancing in the rubble", "scene": {"mood": "joy", "colors": ["bright", "multi", "saturated"], "composition": "symmetrical", "camera": "slow zoom", "description": "Saturated color. Wide smiles. Arms open. The world in full bloom. When they tear the next block down we'll be dancing in the rubble"}}
+{"song": "Concrete Garden", "artist": "Streetlight Prophet", "beat": 8, "timestamp": "3:30", "duration": "30s", "lyric_line": "Every protest is a garden, every march plants something new", "scene": {"mood": "struggle", "colors": ["dust", "grey", "hard light"], "composition": "rule of thirds", "camera": "crane up", "description": "Close on hands working. Calluses. Dust. Effort visible in every frame. Every protest is a garden, every march plants something new"}}
+{"song": "Concrete Garden", "artist": "Streetlight Prophet", "beat": 9, "timestamp": "4:00", "duration": "30s", "lyric_line": "The concrete is a drum and our footsteps keep the beat", "scene": {"mood": "growth", "colors": ["green", "brown", "morning light"], "composition": "extreme wide", "camera": "tracking shot", "description": "Time-lapse. Seed to flower. Sunrise to sunset. Transformation as rhythm. The concrete is a drum and our footsteps keep the beat"}}
+{"song": "Concrete Garden", "artist": "Streetlight Prophet", "beat": 10, "timestamp": "4:30", "duration": "30s", "lyric_line": "Tomorrow there'll be flowers where they swore there'd only be defeat", "scene": {"mood": "hope", "colors": ["gold", "sky blue", "white"], "composition": "medium shot", "camera": "slow tilt down", "description": "Open horizon. Golden light breaking through clouds. The figure silhouetted against dawn. Tomorrow there'll be flowers where they swore there'd only be defeat"}}
+{"song": "Gravity Well", "artist": "Void Walker", "beat": 1, "timestamp": "0:00", "duration": "30s", "lyric_line": "I felt the pull before I saw the edge", "scene": {"mood": "dread", "colors": ["void black", "deep red", "cold white"], "composition": "wide shot", "camera": "static", "description": "Corner of frame. Something in the periphery. Dark. The camera doesn't look directly. I felt the pull before I saw the edge"}}
+{"song": "Gravity Well", "artist": "Void Walker", "beat": 2, "timestamp": "0:30", "duration": "30s", "lyric_line": "The stars bent sideways, light itself was dead", "scene": {"mood": "fascination", "colors": ["event horizon purple", "gravitational lens blue"], "composition": "close-up", "camera": "slow pan", "description": "Close on eyes. Reflection of something impossible. The pupil expands. The stars bent sideways, light itself was dead"}}
+{"song": "Gravity Well", "artist": "Void Walker", "beat": 3, "timestamp": "1:00", "duration": "30s", "lyric_line": "I could have turned the ship around but something in me said stay", "scene": {"mood": "surrender", "colors": ["white", "dissolution", "prismatic"], "composition": "over the shoulder", "camera": "dolly in", "description": "Arms opening. Head back. Falling backward into something vast. I could have turned the ship around but something in me said stay"}}
+{"song": "Gravity Well", "artist": "Void Walker", "beat": 4, "timestamp": "1:30", "duration": "30s", "lyric_line": "The event horizon glows like a halo made of nothing", "scene": {"mood": "awe", "colors": ["starfield", "nebula colors", "infinite dark"], "composition": "low angle", "camera": "dolly out", "description": "Wide shot of cosmos. Nebula. Stars being born. Human figure tiny at bottom. The event horizon glows like a halo made of nothing"}}
+{"song": "Gravity Well", "artist": "Void Walker", "beat": 5, "timestamp": "2:00", "duration": "30s", "lyric_line": "Time stretches thin as wire, each second takes a year", "scene": {"mood": "terror", "colors": ["black", "red shift", "distortion"], "composition": "high angle", "camera": "handheld", "description": "Shaking camera. Red shift. Something approaching fast. The frame distorts. Time stretches thin as wire, each second takes a year"}}
+{"song": "Gravity Well", "artist": "Void Walker", "beat": 6, "timestamp": "2:30", "duration": "30s", "lyric_line": "I am both the observer and the thing that disappears", "scene": {"mood": "peace", "colors": ["deep space black", "starlight", "calm"], "composition": "dutch angle", "camera": "steadicam", "description": "Still water. Stars reflected. Perfect mirror. No movement. No sound. I am both the observer and the thing that disappears"}}
+{"song": "Gravity Well", "artist": "Void Walker", "beat": 7, "timestamp": "3:00", "duration": "30s", "lyric_line": "My body reads the tidal forces like sheet music played on bone", "scene": {"mood": "disorientation", "colors": ["warped", "chromatic aberration", "bent light"], "composition": "symmetrical", "camera": "slow zoom", "description": "Warped lens. Vertigo. Walls becoming floor. Gravity is a suggestion. My body reads the tidal forces like sheet music played on bone"}}
+{"song": "Gravity Well", "artist": "Void Walker", "beat": 8, "timestamp": "3:30", "duration": "30s", "lyric_line": "I stop fighting, stop reaching, stop calling home", "scene": {"mood": "acceptance", "colors": ["soft blue", "warm grey", "sage"], "composition": "rule of thirds", "camera": "crane up", "description": "Soft focus. Gentle light. Figure breathing. The camera doesn't judge. I stop fighting, stop reaching, stop calling home"}}
+{"song": "Gravity Well", "artist": "Void Walker", "beat": 9, "timestamp": "4:00", "duration": "30s", "lyric_line": "There is a peace in dissolution I was never meant to know", "scene": {"mood": "transcendence", "colors": ["pure white", "beyond visible", "golden"], "composition": "extreme wide", "camera": "tracking shot", "description": "Pure white expanding. Figure becoming light. Boundaries dissolving. There is a peace in dissolution I was never meant to know"}}
+{"song": "Gravity Well", "artist": "Void Walker", "beat": 10, "timestamp": "4:30", "duration": "30s", "lyric_line": "Singularity. Silence. Everything and nothing both at once.", "scene": {"mood": "emptiness", "colors": ["void", "absolute black", "nothing"], "composition": "medium shot", "camera": "slow tilt down", "description": "Absolute black. No stars. No reference point. The void looking back. Singularity. Silence. Everything and nothing both at once."}}
+{"song": "Rust Belt Lullaby", "artist": "Iron & Ember", "beat": 1, "timestamp": "0:00", "duration": "30s", "lyric_line": "My father's hands smelled like machine oil and prayer", "scene": {"mood": "nostalgia", "colors": ["amber", "sepia", "dusty rose"], "composition": "wide shot", "camera": "static", "description": "Sepia tones. A photograph come to life. Dust motes in afternoon light. My father's hands smelled like machine oil and prayer"}}
+{"song": "Rust Belt Lullaby", "artist": "Iron & Ember", "beat": 2, "timestamp": "0:30", "duration": "30s", "lyric_line": "The factory whistle was our clock, the shift was our calendar", "scene": {"mood": "sadness", "colors": ["grey", "rain", "muted blue"], "composition": "close-up", "camera": "slow pan", "description": "Rain on glass. Grey light. A cup of tea going cold. Still life of loss. The factory whistle was our clock, the shift was our calendar"}}
+{"song": "Rust Belt Lullaby", "artist": "Iron & Ember", "beat": 3, "timestamp": "1:00", "duration": "30s", "lyric_line": "He'd come home at midnight, wake me up to say goodnight", "scene": {"mood": "tenderness", "colors": ["blush pink", "warm cream", "soft gold"], "composition": "over the shoulder", "camera": "dolly in", "description": "Close on a hand touching a face. Soft light. Shallow depth of field. He'd come home at midnight, wake me up to say goodnight"}}
+{"song": "Rust Belt Lullaby", "artist": "Iron & Ember", "beat": 4, "timestamp": "1:30", "duration": "30s", "lyric_line": "Now the mill is just a skeleton and he's been gone ten years", "scene": {"mood": "loss", "colors": ["faded", "dusty", "empty space"], "composition": "low angle", "camera": "dolly out", "description": "Empty chair. Dust settling. A coat still on a hook. Presence of absence. Now the mill is just a skeleton and he's been gone ten years"}}
+{"song": "Rust Belt Lullaby", "artist": "Iron & Ember", "beat": 5, "timestamp": "2:00", "duration": "30s", "lyric_line": "But the river still runs brown with memory and rust", "scene": {"mood": "beauty", "colors": ["wildflower colors", "green", "sunlight"], "composition": "high angle", "camera": "handheld", "description": "Wildflowers in unexpected places. Color against grey. Nature reclaiming. But the river still runs brown with memory and rust"}}
+{"song": "Rust Belt Lullaby", "artist": "Iron & Ember", "beat": 6, "timestamp": "2:30", "duration": "30s", "lyric_line": "I found his lunchbox in the attic, coffee stains still fresh", "scene": {"mood": "resignation", "colors": ["grey", "muted blue", "beige"], "composition": "dutch angle", "camera": "steadicam", "description": "Medium shot. Hands dropping keys on a table. Turning away. Not looking back. I found his lunchbox in the attic, coffee stains still fresh"}}
+{"song": "Rust Belt Lullaby", "artist": "Iron & Ember", "beat": 7, "timestamp": "3:00", "duration": "30s", "lyric_line": "Some things don't decay \u2014 they just learn to hold still", "scene": {"mood": "love", "colors": ["neutral"], "composition": "symmetrical", "camera": "slow zoom", "description": "Visual interpretation of: Some things don't decay \u2014 they just learn to hold still"}}
+{"song": "Rust Belt Lullaby", "artist": "Iron & Ember", "beat": 8, "timestamp": "3:30", "duration": "30s", "lyric_line": "I hum the songs he hummed to me though I've forgotten half the words", "scene": {"mood": "weariness", "colors": ["grey-brown", "faded", "dim"], "composition": "rule of thirds", "camera": "crane up", "description": "Slow movement. Heavy eyelids. The world in faded tones. Everything too much. I hum the songs he hummed to me though I've forgotten half the words"}}
+{"song": "Rust Belt Lullaby", "artist": "Iron & Ember", "beat": 9, "timestamp": "4:00", "duration": "30s", "lyric_line": "The town's half-empty but the porch lights still come on at dusk", "scene": {"mood": "quiet hope", "colors": ["faint warm light", "candle glow", "dawn grey"], "composition": "extreme wide", "camera": "tracking shot", "description": "Faint warm light. Candle in dark room. Just enough to see by. The town's half-empty but the porch lights still come on at dusk"}}
+{"song": "Rust Belt Lullaby", "artist": "Iron & Ember", "beat": 10, "timestamp": "4:30", "duration": "30s", "lyric_line": "Sleep now, rust belt baby. The furnace keeps us warm.", "scene": {"mood": "peace", "colors": ["deep space black", "starlight", "calm"], "composition": "medium shot", "camera": "slow tilt down", "description": "Still water. Stars reflected. Perfect mirror. No movement. No sound. Sleep now, rust belt baby. The furnace keeps us warm."}}
+{"song": "Wildfire Sermon", "artist": "Prophet Ash", "beat": 1, "timestamp": "0:00", "duration": "30s", "lyric_line": "I didn't start the fire but I brought the gasoline", "scene": {"mood": "fury", "colors": ["dark red", "black", "flash"], "composition": "wide shot", "camera": "static", "description": "Dark red wash. Hands destroying. Frame shaking with rage. I didn't start the fire but I brought the gasoline"}}
+{"song": "Wildfire Sermon", "artist": "Prophet Ash", "beat": 2, "timestamp": "0:30", "duration": "30s", "lyric_line": "Every sermon needs a spark and every spark needs a dream", "scene": {"mood": "ecstasy", "colors": ["fire", "gold", "blinding white"], "composition": "close-up", "camera": "slow pan", "description": "Fire and gold. Bodies arching. Light bursting from every surface. Every sermon needs a spark and every spark needs a dream"}}
+{"song": "Wildfire Sermon", "artist": "Prophet Ash", "beat": 3, "timestamp": "1:00", "duration": "30s", "lyric_line": "The forest is a cathedral and the flames are choir boys singing", "scene": {"mood": "chaos", "colors": ["strobe", "fragmented", "clashing"], "composition": "over the shoulder", "camera": "dolly in", "description": "Fragmented frame. Collage. Everything at once. Order is a memory. The forest is a cathedral and the flames are choir boys singing"}}
+{"song": "Wildfire Sermon", "artist": "Prophet Ash", "beat": 4, "timestamp": "1:30", "duration": "30s", "lyric_line": "Watch the old world burn \u2014 isn't the light beautiful?", "scene": {"mood": "joy", "colors": ["bright", "multi", "saturated"], "composition": "low angle", "camera": "dolly out", "description": "Saturated color. Wide smiles. Arms open. The world in full bloom. Watch the old world burn \u2014 isn't the light beautiful?"}}
+{"song": "Wildfire Sermon", "artist": "Prophet Ash", "beat": 5, "timestamp": "2:00", "duration": "30s", "lyric_line": "We'll dance in the embers, we'll make love in the ash", "scene": {"mood": "destruction", "colors": ["fire", "ash", "smoke orange"], "composition": "high angle", "camera": "handheld", "description": "Fire. Ash falling like snow. Structures collapsing. Beautiful in its terrible way. We'll dance in the embers, we'll make love in the ash"}}
+{"song": "Wildfire Sermon", "artist": "Prophet Ash", "beat": 6, "timestamp": "2:30", "duration": "30s", "lyric_line": "From destruction comes the soil where new things grow at last", "scene": {"mood": "creation", "colors": ["green", "light", "warm gold"], "composition": "dutch angle", "camera": "steadicam", "description": "Hands shaping clay. Light emerging from dark. Something new being born. From destruction comes the soil where new things grow at last"}}
+{"song": "Wildfire Sermon", "artist": "Prophet Ash", "beat": 7, "timestamp": "3:00", "duration": "30s", "lyric_line": "But don't mistake the warmth for safety, don't mistake the glow for home", "scene": {"mood": "warning", "colors": ["red flash", "amber", "siren"], "composition": "symmetrical", "camera": "slow zoom", "description": "Red flash. Siren light. The calm before. Then: impact. But don't mistake the warmth for safety, don't mistake the glow for home"}}
+{"song": "Wildfire Sermon", "artist": "Prophet Ash", "beat": 8, "timestamp": "3:30", "duration": "30s", "lyric_line": "Come closer, come closer \u2014 I promise the burning feels like flying", "scene": {"mood": "invitation", "colors": ["warm", "open", "golden"], "composition": "rule of thirds", "camera": "crane up", "description": "Open door. Warm light spilling out. A hand extended. Come in. Come closer, come closer \u2014 I promise the burning feels like flying"}}
+{"song": "Wildfire Sermon", "artist": "Prophet Ash", "beat": 9, "timestamp": "4:00", "duration": "30s", "lyric_line": "We threw everything we owned into the blaze and laughed", "scene": {"mood": "abandon", "colors": ["wild", "free", "untethered"], "composition": "extreme wide", "camera": "tracking shot", "description": "Running through a field. Hair wild. No destination. Just movement. We threw everything we owned into the blaze and laughed"}}
+{"song": "Wildfire Sermon", "artist": "Prophet Ash", "beat": 10, "timestamp": "4:30", "duration": "30s", "lyric_line": "Morning. Smoke. Green shoots. Begin again.", "scene": {"mood": "rebirth", "colors": ["green shoots", "dawn", "clear"], "composition": "medium shot", "camera": "slow tilt down", "description": "Dawn. Green shoots in ash. First breath after drowning. Morning. Smoke. Green shoots. Begin again."}}
+{"song": "Midnight Transmission", "artist": "Frequency Ghost", "beat": 1, "timestamp": "0:00", "duration": "30s", "lyric_line": "There's a voice on the radio that shouldn't be there", "scene": {"mood": "mystery", "colors": ["deep blue", "shadow", "candle"], "composition": "wide shot", "camera": "static", "description": "Shadow figure in doorway. Candle. Face half-lit. Eyes knowing. There's a voice on the radio that shouldn't be there"}}
+{"song": "Midnight Transmission", "artist": "Frequency Ghost", "beat": 2, "timestamp": "0:30", "duration": "30s", "lyric_line": "Speaking my name in a language I almost understand", "scene": {"mood": "loneliness", "colors": ["single light", "dark", "cold blue"], "composition": "close-up", "camera": "slow pan", "description": "Single light in vast dark. Figure beneath it. Nothing else. Speaking my name in a language I almost understand"}}
+{"song": "Midnight Transmission", "artist": "Frequency Ghost", "beat": 3, "timestamp": "1:00", "duration": "30s", "lyric_line": "I turn the dial but it follows like a shadow made of sound", "scene": {"mood": "curiosity", "colors": ["warm yellow", "spotlight", "discovery"], "composition": "over the shoulder", "camera": "dolly in", "description": "Light moving across a surface. Discovery. Eyes widening. I turn the dial but it follows like a shadow made of sound"}}
+{"song": "Midnight Transmission", "artist": "Frequency Ghost", "beat": 4, "timestamp": "1:30", "duration": "30s", "lyric_line": "Then it says something only I would know, something buried deep", "scene": {"mood": "connection", "colors": ["warm gold", "rose", "blush"], "composition": "low angle", "camera": "dolly out", "description": "Two hands reaching. Fingers almost touching. Warm light between them. Then it says something only I would know, something buried deep"}}
+{"song": "Midnight Transmission", "artist": "Frequency Ghost", "beat": 5, "timestamp": "2:00", "duration": "30s", "lyric_line": "I'm not afraid anymore \u2014 I'm listening", "scene": {"mood": "paranoia", "colors": ["surveillance green", "strobe", "red"], "composition": "high angle", "camera": "handheld", "description": "Surveillance angles. Green tint. Multiple screens. Watching. Being watched. I'm not afraid anymore \u2014 I'm listening"}}
+{"song": "Midnight Transmission", "artist": "Frequency Ghost", "beat": 6, "timestamp": "2:30", "duration": "30s", "lyric_line": "The voice knows my dreams, it describes them back to me", "scene": {"mood": "intimacy", "colors": ["candlelight", "warm", "close"], "composition": "dutch angle", "camera": "steadicam", "description": "Candlelight only. Two faces close. Shared breath. The world outside forgotten. The voice knows my dreams, it describes them back to me"}}
+{"song": "Midnight Transmission", "artist": "Frequency Ghost", "beat": 7, "timestamp": "3:00", "duration": "30s", "lyric_line": "We're having a conversation across some membrane I can't see", "scene": {"mood": "urgency", "colors": ["red", "black", "strobe white"], "composition": "symmetrical", "camera": "slow zoom", "description": "Handheld camera running. Blurred faces. Traffic. Heartbeat sound design. We're having a conversation across some membrane I can't see"}}
+{"song": "Midnight Transmission", "artist": "Frequency Ghost", "beat": 8, "timestamp": "3:30", "duration": "30s", "lyric_line": "Then static. Then nothing. Then a whisper: find me", "scene": {"mood": "disconnection", "colors": ["static", "grey", "broken signal"], "composition": "rule of thirds", "camera": "crane up", "description": "Static. Snow on screen. A voice breaking up. Distance measured in noise. Then static. Then nothing. Then a whisper: find me"}}
+{"song": "Midnight Transmission", "artist": "Frequency Ghost", "beat": 9, "timestamp": "4:00", "duration": "30s", "lyric_line": "I search every frequency but the voice is gone", "scene": {"mood": "searching", "colors": ["flashlight beam", "dark", "moving light"], "composition": "extreme wide", "camera": "tracking shot", "description": "Flashlight beam cutting dark. Moving. Looking. Not finding yet. I search every frequency but the voice is gone"}}
+{"song": "Midnight Transmission", "artist": "Frequency Ghost", "beat": 10, "timestamp": "4:30", "duration": "30s", "lyric_line": "Some nights I still hear it, faint, like a song in another room", "scene": {"mood": "haunting", "colors": ["faint blue", "echo", "silver"], "composition": "medium shot", "camera": "slow tilt down", "description": "Faint blue light. Echo of a figure. Present and absent simultaneously. Some nights I still hear it, faint, like a song in another room"}}
+{"song": "Crown of Thorns and Roses", "artist": "Velvet Guillotine", "beat": 1, "timestamp": "0:00", "duration": "30s", "lyric_line": "I wore your love like a weapon and you never felt the blade", "scene": {"mood": "seduction", "colors": ["deep red", "velvet", "candlelight"], "composition": "wide shot", "camera": "static", "description": "Deep red. Velvet textures. Slow movement. Eyes that promise. I wore your love like a weapon and you never felt the blade"}}
+{"song": "Crown of Thorns and Roses", "artist": "Velvet Guillotine", "beat": 2, "timestamp": "0:30", "duration": "30s", "lyric_line": "Every kiss was a negotiation, every touch a trade", "scene": {"mood": "power", "colors": ["gold", "black", "crimson"], "composition": "close-up", "camera": "slow pan", "description": "Throne. Gold. Black. The figure doesn't move. Doesn't need to. Every kiss was a negotiation, every touch a trade"}}
+{"song": "Crown of Thorns and Roses", "artist": "Velvet Guillotine", "beat": 3, "timestamp": "1:00", "duration": "30s", "lyric_line": "The throne room smells like jasmine and someone else's fear", "scene": {"mood": "cruelty", "colors": ["cold silver", "black", "sharp white"], "composition": "over the shoulder", "camera": "dolly in", "description": "Silver blade. Cold light. A smile that doesn't reach the eyes. The throne room smells like jasmine and someone else's fear"}}
+{"song": "Crown of Thorns and Roses", "artist": "Velvet Guillotine", "beat": 4, "timestamp": "1:30", "duration": "30s", "lyric_line": "I am beautiful when I'm angry \u2014 haven't you heard?", "scene": {"mood": "beauty", "colors": ["wildflower colors", "green", "sunlight"], "composition": "low angle", "camera": "dolly out", "description": "Wildflowers in unexpected places. Color against grey. Nature reclaiming. I am beautiful when I'm angry \u2014 haven't you heard?"}}
+{"song": "Crown of Thorns and Roses", "artist": "Velvet Guillotine", "beat": 5, "timestamp": "2:00", "duration": "30s", "lyric_line": "Don't mistake my gentleness for weakness, darling", "scene": {"mood": "danger", "colors": ["red", "black", "warning yellow"], "composition": "high angle", "camera": "handheld", "description": "Red and black. Warning signs. The frame contracts. Something approaches. Don't mistake my gentleness for weakness, darling"}}
+{"song": "Crown of Thorns and Roses", "artist": "Velvet Guillotine", "beat": 6, "timestamp": "2:30", "duration": "30s", "lyric_line": "I chose to be kind. I could burn this kingdom down.", "scene": {"mood": "vulnerability", "colors": ["soft", "exposed", "raw"], "composition": "dutch angle", "camera": "steadicam", "description": "Exposed skin. Soft light. Eyes open. Trust visible in every pore. I chose to be kind. I could burn this kingdom down."}}
+{"song": "Crown of Thorns and Roses", "artist": "Velvet Guillotine", "beat": 7, "timestamp": "3:00", "duration": "30s", "lyric_line": "The roses in my crown have thorns that curve inward", "scene": {"mood": "fury", "colors": ["dark red", "black", "flash"], "composition": "symmetrical", "camera": "slow zoom", "description": "Dark red wash. Hands destroying. Frame shaking with rage. The roses in my crown have thorns that curve inward"}}
+{"song": "Crown of Thorns and Roses", "artist": "Velvet Guillotine", "beat": 8, "timestamp": "3:30", "duration": "30s", "lyric_line": "I bleed for my own sins, not for yours", "scene": {"mood": "grace", "colors": ["white", "silver", "flowing"], "composition": "rule of thirds", "camera": "crane up", "description": "White. Flowing. Movement without effort. The body as art. I bleed for my own sins, not for yours"}}
+{"song": "Crown of Thorns and Roses", "artist": "Velvet Guillotine", "beat": 9, "timestamp": "4:00", "duration": "30s", "lyric_line": "Tonight I lay the crown aside and sleep without armor", "scene": {"mood": "revenge", "colors": ["dark", "steel", "cold blue"], "composition": "extreme wide", "camera": "tracking shot", "description": "Cold blue. Steel. The plan unfolding in shadows. Patience as weapon. Tonight I lay the crown aside and sleep without armor"}}
+{"song": "Crown of Thorns and Roses", "artist": "Velvet Guillotine", "beat": 10, "timestamp": "4:30", "duration": "30s", "lyric_line": "Mercy. The hardest word. The only gift worth giving.", "scene": {"mood": "mercy", "colors": ["warm gold", "white", "gentle"], "composition": "medium shot", "camera": "slow tilt down", "description": "Warm gold. Hand lowering a weapon. Choosing not to. The harder path. Mercy. The hardest word. The only gift worth giving."}}
+{"song": "Apartment 4B", "artist": "Wallpaper & Wire", "beat": 1, "timestamp": "0:00", "duration": "30s", "lyric_line": "Four walls, one window, a view of another wall", "scene": {"mood": "claustrophobia", "colors": ["close walls", "yellow bulb", "cramped"], "composition": "wide shot", "camera": "static", "description": "Walls close. Ceiling low. Yellow bulb. No escape visible. Four walls, one window, a view of another wall"}}
+{"song": "Apartment 4B", "artist": "Wallpaper & Wire", "beat": 2, "timestamp": "0:30", "duration": "30s", "lyric_line": "The radiator clicks like a metronome for the damned", "scene": {"mood": "routine", "colors": ["grey", "institutional", "fluorescent"], "composition": "close-up", "camera": "slow pan", "description": "Fluorescent light. Same motion repeated. Clock on the wall. Time as loop. The radiator clicks like a metronome for the damned"}}
+{"song": "Apartment 4B", "artist": "Wallpaper & Wire", "beat": 3, "timestamp": "1:00", "duration": "30s", "lyric_line": "I've memorized every crack in the ceiling \u2014 they form a map", "scene": {"mood": "desperation", "colors": ["scratching", "clawing", "raw"], "composition": "over the shoulder", "camera": "dolly in", "description": "Hands clawing. Fingernails against surface. Raw need. Nothing held back. I've memorized every crack in the ceiling \u2014 they form a map"}}
+{"song": "Apartment 4B", "artist": "Wallpaper & Wire", "beat": 4, "timestamp": "1:30", "duration": "30s", "lyric_line": "In my mind I've left a hundred times, bought a farm, learned to fly", "scene": {"mood": "fantasy", "colors": ["dreamy", "pastel", "floating"], "composition": "low angle", "camera": "dolly out", "description": "Pastel. Floating. Impossible architecture. Gravity optional. In my mind I've left a hundred times, bought a farm, learned to fly"}}
+{"song": "Apartment 4B", "artist": "Wallpaper & Wire", "beat": 5, "timestamp": "2:00", "duration": "30s", "lyric_line": "Then one morning I open the door and just walk out", "scene": {"mood": "breakthrough", "colors": ["white burst", "open sky", "blinding"], "composition": "high angle", "camera": "handheld", "description": "White burst. Wall shattering. Open sky beyond. Freedom as explosion. Then one morning I open the door and just walk out"}}
+{"song": "Apartment 4B", "artist": "Wallpaper & Wire", "beat": 6, "timestamp": "2:30", "duration": "30s", "lyric_line": "The hallway is an ocean, the stairs are a mountain range", "scene": {"mood": "freedom", "colors": ["open sky", "blue", "green"], "composition": "dutch angle", "camera": "steadicam", "description": "Open road. Blue sky. Green fields. Wind in hair. No walls. The hallway is an ocean, the stairs are a mountain range"}}
+{"song": "Apartment 4B", "artist": "Wallpaper & Wire", "beat": 7, "timestamp": "3:00", "duration": "30s", "lyric_line": "The street hits me like cold water and I almost go back", "scene": {"mood": "fear", "colors": ["cold", "dark", "sharp"], "composition": "symmetrical", "camera": "slow zoom", "description": "Cold. Dark. Sharp edges. The frame contracts. Something unseen. The street hits me like cold water and I almost go back"}}
+{"song": "Apartment 4B", "artist": "Wallpaper & Wire", "beat": 8, "timestamp": "3:30", "duration": "30s", "lyric_line": "But the sky \u2014 have you seen the sky? It goes on forever", "scene": {"mood": "joy", "colors": ["bright", "multi", "saturated"], "composition": "rule of thirds", "camera": "crane up", "description": "Saturated color. Wide smiles. Arms open. The world in full bloom. But the sky \u2014 have you seen the sky? It goes on forever"}}
+{"song": "Apartment 4B", "artist": "Wallpaper & Wire", "beat": 9, "timestamp": "4:00", "duration": "30s", "lyric_line": "I stand on the sidewalk and cry because the world is so big", "scene": {"mood": "grounding", "colors": ["neutral"], "composition": "extreme wide", "camera": "tracking shot", "description": "Visual interpretation of: I stand on the sidewalk and cry because the world is so big"}}
+{"song": "Apartment 4B", "artist": "Wallpaper & Wire", "beat": 10, "timestamp": "4:30", "duration": "30s", "lyric_line": "Home is not a place. Home is the moment you stop hiding.", "scene": {"mood": "home", "colors": ["neutral"], "composition": "medium shot", "camera": "slow tilt down", "description": "Visual interpretation of: Home is not a place. Home is the moment you stop hiding."}}

training/scripts/augment_pairs.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""
+augment_pairs.py — Training data augmentation: paraphrase and translate.
+
+Usage:
+    python3 augment_pairs.py --input data.jsonl
+    python3 augment_pairs.py --input data.jsonl --paraphrases 3 --langs es,fr,de
+    python3 augment_pairs.py --input data.jsonl --llm-endpoint http://localhost:11434/v1
+"""
+
+import json, os, sys, re, random
+from pathlib import Path
+
+random.seed(42)
+
+PARAPHRASE_TRANSFORMS = [
+    lambda s: re.sub(r"(\w+), (\w+)", r"\2, \1", s, count=1),
+    lambda s: f"A beautifully rendered scene: {s[0].lower()}{s[1:]}" if len(s) > 10 else s,
+    lambda s: s.replace("A ", "The ").replace("An ", "The ") if s.startswith(("A ", "An ")) else f"Here, {s[0].lower()}{s[1:]}",
+    lambda s: f"In a cinematic frame: {s}" if len(s) > 20 else s,
+    lambda s: s if ", " not in s else ", ".join(s.split(", ")[:2]),
+]
+
+TRANSLATIONS = {
+    "es": {"the":"el","a":"un","is":"es","in":"en","of":"de","and":"y","with":"con","scene":"escena","light":"luz","dark":"oscuro","warm":"cálido","rain":"lluvia","sun":"sol","moon":"luna","sky":"cielo","forest":"bosque","mountain":"montaña","ocean":"océano","golden":"dorado","blue":"azul","red":"rojo","green":"verde","silence":"silencio","dream":"sueño","love":"amor","hope":"esperanza","fear":"miedo","joy":"alegría","peace":"paz","beautiful":"hermoso","sad":"triste","shadow":"sombra","color":"color","silver":"plateado","white":"blanco","black":"negro","portray":"retrato"},
+    "fr": {"the":"le","a":"un","is":"est","in":"dans","of":"de","and":"et","with":"avec","scene":"scène","light":"lumière","dark":"sombre","warm":"chaud","rain":"pluie","sun":"soleil","moon":"lune","sky":"ciel","forest":"forêt","mountain":"montagne","ocean":"océan","golden":"doré","blue":"bleu","red":"rouge","green":"vert","silence":"silence","dream":"rêve","love":"amour","hope":"espoir","fear":"peur","joy":"joie","peace":"paix","beautiful":"beau","sad":"triste","shadow":"ombre","color":"couleur","silver":"argenté","white":"blanc","black":"noir"},
+    "de": {"the":"der","a":"ein","is":"ist","in":"in","of":"von","and":"und","with":"mit","scene":"Szene","light":"Licht","dark":"dunkel","warm":"warm","rain":"Regen","sun":"Sonne","moon":"Mond","sky":"Himmel","forest":"Wald","mountain":"Berg","ocean":"Ozean","golden":"golden","blue":"blau","red":"rot","green":"grün","silence":"Stille","dream":"Traum","love":"Liebe","hope":"Hoffnung","fear":"Angst","joy":"Freude","peace":"Frieden","beautiful":"schön","sad":"traurig","shadow":"Schatten","color":"Farbe","silver":"silbern","white":"weiß","black":"schwarz"},
+}
+
+LANG_NAMES = {"es": "Spanish", "fr": "French", "de": "German"}
+
+
+def detect_text_field(entry):
+    for f in ["rich","terse","text","content","lyric_line","description","scene_description","prompt","scene"]:
+        if f in entry and isinstance(entry[f], str) and len(entry[f]) > 5:
+            return f
+    for k, v in entry.items():
+        if isinstance(v, str) and len(v) > 5:
+            return k
+    return None
+
+
+def paraphrase(text):
+    t = random.choice(PARAPHRASE_TRANSFORMS)(text)
+    if t == text:
+        t = text.replace(" and ", " & ").replace(" with ", " alongside ")
+        if t == text:
+            t = f"In this scene: {text[0].lower()}{text[1:]}" if text[0].isupper() else text
+    return t
+
+
+def translate(text, lang):
+    d = TRANSLATIONS.get(lang, {})
+    words = text.split()
+    out = []
+    for w in words:
+        lo = w.lower().strip(".,;:!?")
+        suf = w[len(w.rstrip(".,;:!?")):]
+        if lo in d:
+            out.append(d[lo] + suf)
+        else:
+            out.append(w)
+    return " ".join(out)
+
+
+def augment_file(input_path, output_path=None, n_para=3, langs=None, llm_endpoint=None):
+    input_path = Path(input_path)
+    if output_path is None:
+        output_path = input_path.parent / f"{input_path.stem}_augmented{input_path.suffix}"
+
+    entries = [json.loads(l) for l in open(input_path) if l.strip()]
+    if not entries:
+        print(f"No entries in {input_path}"); return 0
+
+    tf = detect_text_field(entries[0])
+    if not tf:
+        print(f"ERROR: No text field in {input_path}", file=sys.stderr); return 0
+
+    print(f"Input: {input_path} ({len(entries)} entries, field={tf})")
+
+    aug_count = 0
+    with open(output_path, "w") as out:
+        for e in entries:
+            out.write(json.dumps(e, ensure_ascii=False) + "\n")
+        for i, e in enumerate(entries):
+            text = e[tf]
+            # Paraphrases
+            for p in range(n_para):
+                para = paraphrase(text)
+                if para != text:
+                    ne = dict(e); ne[tf] = para
+                    ne["_augmentation"] = f"paraphrase_{p+1}"
+                    ne["_original"] = text[:100]
+                    out.write(json.dumps(ne, ensure_ascii=False) + "\n")
+                    aug_count += 1
+            # Translations
+            for lang in (langs or []):
+                tr = translate(text, lang)
+                if tr != text:
+                    ne = dict(e); ne[tf] = tr
+                    ne["_augmentation"] = f"translate_{lang}"
+                    ne["_language"] = lang
+                    ne["_original"] = text[:100]
+                    out.write(json.dumps(ne, ensure_ascii=False) + "\n")
+                    aug_count += 1
+            if (i+1) % 100 == 0:
+                print(f"  {i+1}/{len(entries)} done ({aug_count} augmented)")
+
+    total = len(entries) + aug_count
+    print(f"Done: {len(entries)} originals + {aug_count} augmented = {total}")
+    print(f"Output: {output_path}")
+    return aug_count
+
+
+def main():
+    import argparse
+    p = argparse.ArgumentParser()
+    p.add_argument("--input", required=True)
+    p.add_argument("--output", default=None)
+    p.add_argument("--paraphrases", type=int, default=3)
+    p.add_argument("--langs", default="es,fr,de")
+    p.add_argument("--llm-endpoint", default=None)
+    args = p.parse_args()
+    langs = [l.strip() for l in args.langs.split(",") if l.strip()] if args.langs else []
+    augment_file(args.input, args.output, args.paraphrases, langs, args.llm_endpoint)
+
+
+if __name__ == "__main__":
+    main()