# Le Mystere du Professeur Zacus

Zacus est en refonte vers un produit hybride unique:
- un jeu terrain fiable sur carte Freenove ESP32-S3,
- un studio auteur moderne en React + Blockly,
- un runtime portable "Zacus Runtime 3" compile depuis le YAML canonique.

## Canon actuel
- Source narrative: `game/scenarios/zacus_v3_complete.yaml`
- Studio auteur: `frontend-v3/apps/atelier` (monorepo pnpm + turbo ; `frontend-scratch-v2/` est abandonné depuis le hard cutover du 2026-05)
- Hub game-master: `apps/zacus-hub` (app SwiftUI native)
- Gateway d'orchestration: `tools/zacus-gateway` (FastAPI, port 8400) — compile le YAML → Runtime 3 IR et pousse aux cartes
- Runtime portable: `tools/scenario/compile_runtime3.py` + `tools/scenario/simulate_runtime3.py`
- Cible hardware principale: `ESP32_ZACUS/idf_zacus` (ESP-IDF, Freenove ESP32-S3) — submodule sur Gitea ; `hardware/firmware` (ancien build Arduino) est legacy
- Plans et memoire: `memory/`, `plans/`, `todos/`
- Architecture et cartes Mermaid: `docs/architecture/`

## Démarrage rapide

### 1. Bootstrap validation
```bash
bash tools/setup/install_validators.sh
bash tools/test/run_content_checks.sh
```

### 2. Compiler et simuler Runtime 3
```bash
python3 tools/scenario/compile_runtime3.py game/scenarios/zacus_v3_complete.yaml
python3 tools/scenario/simulate_runtime3.py game/scenarios/zacus_v3_complete.yaml
python3 tools/scenario/export_runtime3_firmware_bundle.py game/scenarios/zacus_v3_complete.yaml
```

### 3. Démarrer le studio React + Blockly
```bash
cd frontend-v3
pnpm install
pnpm test
# Bases de liaison : gateway (:8400), firmware (:80), hints (:8311), voice-bridge (:8200)
VITE_GATEWAY_BASE_URL=http://localhost:8400 \
VITE_ESP32_BASE_URL=http://zacus-master.local \
pnpm dev
```

### 4. Utiliser le shell canonique
```bash
./tools/dev/zacus.sh content-checks
./tools/dev/zacus.sh runtime3-compile
make runtime3-verify
make runtime3-test
./tools/dev/zacus.sh frontend-test
./tools/dev/zacus.sh frontend-build
./tools/dev/zacus.sh menu
```

## Cartographie du dépôt
- `game/`: scénarios YAML canoniques.
- `audio/`: manifestes audio et assets associés.
- `printables/`: manifestes et exports imprimables.
- `kit-maitre-du-jeu/`: matériel MJ et déroulé terrain.
- `frontend-v3/`: studio auteur (apps/atelier + apps/dashboard), monorepo pnpm + turbo. **Webapp courante.**
- `apps/zacus-hub/`: hub game-master (app SwiftUI native).
- `tools/zacus-gateway/`: gateway FastAPI (:8400) — orchestration studio/flash, compile YAML → Runtime 3 IR.
- `ESP32_ZACUS/`: firmware ESP-IDF (submodule Gitea), cible principale `idf_zacus`.
- `frontend-scratch-v2/`: studio auteur React + Blockly (legacy, abandonné).
- `hardware/firmware/`: ancien firmware Arduino freenove (legacy).
- `tools/`: validateurs, compilateur/simulateur Runtime 3, shells d'automatisation.
- `docs/`: quickstart, architecture, benchmark OSS et runbooks.
- `memory/`, `plans/`, `todos/`: pilotage de la refonte.

## AI Integration

Le projet intègre une couche IA pour enrichir l'expérience terrain :
- **Voice pipeline** : wake word (ESP-SR) → ASR → LLM → TTS (Piper / XTTS-v2) → speaker. Scaffold prêt, voir [`docs/voice/VOICE_PIPELINE_GUIDE.md`](docs/voice/VOICE_PIPELINE_GUIDE.md).
- **Vision** : détection d'objets via ESP-DL pour indices contextuels.
- **LLM hints** : le Professeur Zacus répond aux joueurs via mascarade.
- **TUI dev** : script interactif d'orchestration → `python3 tools/dev/zacus_tui.py`

Analyse complète : [`docs/AI_INTEGRATION_ANALYSIS.md`](docs/AI_INTEGRATION_ANALYSIS.md)

## Sécurité & Déploiement

- [`docs/SECURITY.md`](docs/SECURITY.md) — audit firmware, HMAC auth, rate limiting
- [`docs/DEPLOYMENT_RUNBOOK.md`](docs/DEPLOYMENT_RUNBOOK.md) — procédures de déploiement terrain

## Statut du projet

- Runtime 3 : compilateur + simulateur + export firmware bundle OK
- Studio auteur : React 19 + Blockly, 18 tests passing
- Firmware : sécurité P0 intégrée (HMAC, rate limit, safe OTA)
- Voice pipeline : scaffold ESP-SR prêt, TTS Docker validé
- Specs : `ZACUS_RUNTIME_3_SPEC.md`, `STORY_DESIGNER_SCRATCH_LIKE_SPEC.md`

## Documentation à lire
- `docs/QUICKSTART.md`
- `docs/architecture/index.md`
- `docs/AI_INTEGRATION_ANALYSIS.md`
- `specs/ZACUS_RUNTIME_3_SPEC.md`
- `specs/STORY_DESIGNER_SCRATCH_LIKE_SPEC.md`
- `docs/benchmark-oss.md`

## Notes de refonte
- Le YAML reste la source de vérité pendant la migration.
- Le Runtime 3 devient le contrat portable entre studio, simulateur et firmware.
- `hardware/firmware/esp32/` reste en lecture seule.
- Les chemins legacy ne doivent être supprimés qu'après preuve de remplacement.

## Licences
- Code: MIT (`LICENSE`)
- Contenu créatif: CC BY-NC 4.0 (`LICENSE-CONTENT.md`)