electron-rare/le-mystere-professeur-zacus

Files

T

L'électron rare 0ec3da620f docs: CLAUDE.md + README align with P1 stack

Project root CLAUDE.md: architecture diagram now shows MacStudio voice-bridge (cache → F5 → safe wav), hints engine LLM rewrite via LiteLLM hints-deep (MLX 32B Q4), and MLX-LM inference tier. Infrastructure section adds MacStudio (live stack) and demotes Tower to legacy. tools/macstudio/README.md gets full stack table, aliases, persistence (crontab @reboot + */2 watchdog), resilience (cache, service_down.wav), pool pre-render command, known issues. Home ~/CLAUDE.md edits applied separately (six-node, MacStudio added, Tower line trimmed).

2026-05-03 21:19:24 +02:00

5.3 KiB

Raw Permalink Blame History

CLAUDE.md

Guidance for Claude Code working in this repository.

Overview

Le Mystère du Professeur Zacus — hybrid educational escape room game with ESP32-S3 hardware, React authoring studios, and a portable Runtime 3 scenario engine. Scenarios are authored in YAML, compiled to a portable IR, and executed on both web and ESP32 targets.

Build & Test

make all-validate                                # Full pipeline (scenario + audio + printables + runtime3)
make content-checks                              # Schema validation only

# Runtime 3
make runtime3-compile                            # YAML → IR
make runtime3-simulate                           # Execute IR
make runtime3-verify                             # Verify pivots
make runtime3-test                               # Python unittest

# Compile a specific scenario
python3 tools/scenario/compile_runtime3.py game/scenarios/zacus_v2.yaml

# Dev CLI (12 actions)
./tools/dev/zacus.sh content-checks
./tools/dev/zacus.sh voice-bridge start|stop|status|test

Frontend, desktop, and tooling commands live in their nested CLAUDE.md.

Architecture

YAML scenario → compile_runtime3.py → Runtime 3 IR → ESP32 / Web player
                                                    ↓
                                              Voice bridge :8200 (MacStudio)
                                                ↳ /tts → F5-TTS-MLX (cache → F5 → safe wav)
                                                ↳ /voice/intent → LiteLLM npc-fast (MLX 7B Q4)
                                                ↳ /voice/transcribe → whisper.cpp :8300
                                                    ↓
                                              Hints engine → /hints/ask (LLM rewrite via hints-deep MLX 32B Q4)

Key surfaces:

Scenario IR: game/scenarios/zacus_v2.yaml → tools/scenario/compile_runtime3.py → portable Runtime 3 IR. Contract: specs/ZACUS_RUNTIME_3_SPEC.md.
Authoring: frontend-v3/ (pnpm monorepo: apps/atelier/ Scratch-like studio + apps/dashboard/ game-master live view).
Firmware:
- ESP32_ZACUS/ submodule — Freenove ESP32-S3 master (NPC engine, voice pipeline, vision/QR, media manager). Branche feat/idf-migration en cours (port Arduino → ESP-IDF 5.4).
- PLIP_FIRMWARE/ — retro telephone annex (ES8388 dev kit bringup, Si3210 PCB target). REST endpoint consumed by the master ESP32.
Voice / NPC: F5-TTS-MLX in-process sur MacStudio (studio:8200), voix Zacus clonée via ~/zacus_reference.wav. Pré-rendu via tools/tts/generate_npc_pool.py --backend f5. Service down WAV hardcoded en graceful degradation. NPC phrases : game/scenarios/npc_phrases.yaml.
Hints engine: tools/hints/server.py FastAPI (LLM rewrite via LiteLLM hints-deep, anti-cheat, adaptive level, safety filter game/scenarios/hints_safety.yaml).
Inference stack: voir tools/macstudio/README.md — MLX-LM (npc + hints), whisper.cpp, F5-TTS, LiteLLM proxy :4000. Configs versionnées dans tools/macstudio/.
MCP hardware: tools/dev/mcp_hardware_server.py (stdio, 6 tools).
Desktop hub: desktop/ (Electron, macOS, bundles V3 frontends, talks USB serial).

Where to Look

Task	Location
Edit scenarios, NPC phrases, prompts	`game/`
Modify Runtime 3 compiler / validators / TTS pool / dev CLI	`tools/`
Authoring UI / dashboard / simulation	`frontend-v3/`
Zacus Studio macOS app	`desktop/`
Add or change a contract spec	`specs/`
Python tests (Runtime 3, NPC)	`tests/`
Firmware code (Zacus master)	`ESP32_ZACUS/` submodule (own repo)
Firmware code (PLIP retro phone)	`PLIP_FIRMWARE/` (inlined; see README for submodule conversion)

Canonical Files

File	Role
`game/scenarios/zacus_v2.yaml`	Scenario source of truth
`game/scenarios/npc_phrases.yaml`	NPC phrase bank (FR)
`specs/ZACUS_RUNTIME_3_SPEC.md`	Runtime contract
`specs/AI_INTEGRATION_SPEC.md`	AI layer architecture
`Makefile`	Top-level automation
`docs/QUICKSTART.md`	Getting started
`docs/DEPLOYMENT_RUNBOOK.md`	Field deployment
`docs/debt/codex-firmware-fixes-to-apply.md`	Pending firmware fixes

Infrastructure

MacStudio (ssh studio, M3 Ultra 512 GB) : stack inférence Zacus complète — MLX-LM (npc-fast 7B Q4 :8501, hints-deep 32B Q4 :8500), whisper.cpp large-v3-turbo-q5_0 :8300, F5-TTS-MLX in-process via voice-bridge :8200 (cache disque + watchdog */2 + service_down.wav graceful), LiteLLM proxy :4000. Voir tools/macstudio/README.md.
Tower (clems@192.168.0.120) : Suite Numérique, n8n, LiteLLM Tower (legacy). Plus dans la chaîne live Zacus ; container Docker zacus-tts-piper survit pour batch historique uniquement (voix EN-only, FR à déployer si besoin).
KXKM-AI (kxkm@kxkm-ai via Tailscale) : RTX 4090, GPU inference (fine-tuning, plus utilisé en runtime).
SSH is key-based only — never sshpass.

Language

User speaks French → respond in French. Code, comments, commits, docs → English. Full diacritics required in French.

Nested Guidance

Domain-specific rules live in nested CLAUDE.md files and load automatically when you read files in those directories. Closest file wins. Current nested:

game/, tools/, tests/, specs/
frontend-v3/, desktop/

5.3 KiB Raw Permalink Blame History