feat: AI integration — voice pipeline, hints engine, MCP server, analytics, security

- Voice pipeline: ESP32 WebSocket client → voice bridge → LLM → Piper TTS (Tower :8001)
- Hints engine: 3 puzzles (LA_440, LEFOU_PIANO, QR_FINALE), anti-cheat, 3 hint levels
- MCP hardware server: 6 tools (puzzle, audio, LED, camera, scenario, status), stdio transport
- Analytics: ESP32 module + 6 web endpoints + Dashboard UI with chat interface
- Security: auth middleware (Bearer NVS), rate limiting, input validation on 30 endpoints
- Frontend: code-split (1.1MB → 210KB initial), ErrorBoundary, API timeout, WS reconnect
- Tests: 24 Python + 38 TypeScript + 18 MCP = 80 project tests (+ 19 mascarade)
- Specs: AI_INTEGRATION_SPEC, MCP_HARDWARE_SERVER_SPEC, QA_TEST_MATRIX_SPEC
- Docs: SECURITY, DEPLOYMENT_RUNBOOK, voice pipeline guide, AI architecture map
- 6 AI agent definitions (.github/agents/ai_*.md)
- TUI orchestration script (tools/dev/zacus_tui.py)
- Docker compose TTS for Tower + KXKM-AI
- CHANGELOG, README, mkdocs.yml updated
- Cycle detection (DFS) in runtime3 validator
- Sprint plan: plans/SPRINT_AI_INTEGRATION.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

game/scenarios/zacus_v2.yaml

@@ -47,17 +47,111 @@ firmware:
       - "SCENE_MP3_PLAYER"
       - "SCENE_READY"
 
-  steps_reference_order:
-    - STEP_U_SON_PROTO
-    - STEP_LA_DETECTOR
-    - STEP_RTC_ESP_ETAPE1
-    - STEP_WIN_ETAPE1
-    - STEP_WARNING
-    - STEP_LEFOU_DETECTOR
-    - STEP_RTC_ESP_ETAPE2
-    - STEP_QR_DETECTOR
-    - STEP_FINAL_WIN
+  initial_step: STEP_U_SON_PROTO
 
+  steps:
+    - step_id: STEP_U_SON_PROTO
+      screen_scene_id: SCENE_U_SON_PROTO
+      audio_pack_id: ""
+      actions: []
+      apps: []
+      transitions:
+        - event_type: serial
+          event_name: BTN_NEXT
+          target_step_id: STEP_LA_DETECTOR
+          priority: 100
+          after_ms: 0
+
+    - step_id: STEP_LA_DETECTOR
+      screen_scene_id: SCENE_LA_DETECTOR
+      audio_pack_id: ""
+      actions: []
+      apps: []
+      transitions:
+        - event_type: unlock
+          event_name: UNLOCK_LA_440
+          target_step_id: STEP_RTC_ESP_ETAPE1
+          priority: 120
+          after_ms: 0
+
+    - step_id: STEP_RTC_ESP_ETAPE1
+      screen_scene_id: SCENE_WIN_ETAPE1
+      audio_pack_id: ""
+      actions: []
+      apps: []
+      transitions:
+        - event_type: espnow
+          event_name: ACK_WIN1
+          target_step_id: STEP_WIN_ETAPE1
+          priority: 130
+          after_ms: 0
+
+    - step_id: STEP_WIN_ETAPE1
+      screen_scene_id: SCENE_WIN_ETAPE1
+      audio_pack_id: ""
+      actions: []
+      apps: []
+      transitions:
+        - event_type: audio_done
+          event_name: AUDIO_DONE
+          target_step_id: STEP_WARNING
+          priority: 110
+          after_ms: 0
+
+    - step_id: STEP_WARNING
+      screen_scene_id: SCENE_WARNING
+      audio_pack_id: ""
+      actions: []
+      apps: []
+      transitions:
+        - event_type: serial
+          event_name: BTN_NEXT
+          target_step_id: STEP_LEFOU_DETECTOR
+          priority: 100
+          after_ms: 0
+
+    - step_id: STEP_LEFOU_DETECTOR
+      screen_scene_id: SCENE_LEFOU_DETECTOR
+      audio_pack_id: ""
+      actions: []
+      apps: []
+      transitions:
+        - event_type: unlock
+          event_name: UNLOCK_PIANO_LEFOU
+          target_step_id: STEP_RTC_ESP_ETAPE2
+          priority: 120
+          after_ms: 0
+
+    - step_id: STEP_RTC_ESP_ETAPE2
+      screen_scene_id: SCENE_WIN_ETAPE2
+      audio_pack_id: ""
+      actions: []
+      apps: []
+      transitions:
+        - event_type: espnow
+          event_name: ACK_WIN2
+          target_step_id: STEP_QR_DETECTOR
+          priority: 130
+          after_ms: 0
+
+    - step_id: STEP_QR_DETECTOR
+      screen_scene_id: SCENE_QR_DETECTOR
+      audio_pack_id: ""
+      actions: []
+      apps: []
+      transitions:
+        - event_type: unlock
+          event_name: UNLOCK_QR
+          target_step_id: STEP_FINAL_WIN
+          priority: 140
+          after_ms: 0
+
+    - step_id: STEP_FINAL_WIN
+      screen_scene_id: SCENE_FINAL_WIN
+      audio_pack_id: ""
+      actions: []
+      apps: []
+      transitions: []
 # ============================================================
 # CANON NARRATIF (réalité terrain)
 # ============================================================
@@ -390,4 +484,4 @@ props_and_assets:
 notes: >
   Cette version est 100% alignée avec la réalité “2 étapes + QR + Media Hub”.
   Si tu veux, je peux aussi te générer la fiche MJ (indices soft/hard, cadence, placements)
-  et une version “short 90 min” sans casser le runtime.
+  et une version “short 90 min” sans casser le runtime.