[WIP] Add analysis of all README files in directories (#109)

* Initial plan

* Ionisation documentaire complète — Zacus ⚡

Le dépôt a été recalibré.
Le bruit documentaire a été filtré.
Le signal narratif est désormais stable.

Refactor massif des README.
Restructuration des flux.
Localisation renforcée.
Checklists clarifiées.
Stations réalignées.
Script minute-par-minute recalibré.
Solution complète éthiquement consolidée.
Printables et outils d’image stabilisés.

Ce n’est pas une mise à jour.
C’est une stabilisation de phase.

LA 440 est propre.
LEFOU est structuré.
WIN est cohérent.

Documentation :
moins de friction,
plus de méthode,
plus d’alignement canon.

⚛ L’électron rare
⚡ unstable by design

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Clément SAILLANT <108685187+electron-rare@users.noreply.github.com>

fronted dev web UI/README.md

@@ -1,64 +1,77 @@
-# Story V2 WebUI
+---
+# Zacus WebUI (Story V2)
+// TODO NO DEV FINISH (need KILL_LIFE ?)
 
 Frontend Mission Control pour les devices Zacus.
 
-## Nouveautes principales
+---
 
-- `Scenario Selector` revu: recherche, tri, mode legacy explicite, CTA adaptes aux capabilities.
-- `Live Orchestrator` revu: statut runtime lisible, recovery stream, filtre d'evenements, controles reseau legacy.
-- `Story Designer` nodal avec React Flow:
-  - import YAML -> graphe (Story V2 canonique + legacy simplifie),
-  - export graphe -> YAML canonique Story V2,
-  - edition guidee des `app_bindings`,
-  - edition node/edge, undo/redo, auto-layout.
-- UI globale harmonisee en style glass modern, labels FR et focus accessibilite.
+## 📝 Description
 
-## Modes API (dual mode)
+Interface web de pilotage, design et diagnostic pour les firmwares Zacus (Story V2 et legacy).
 
-Détection automatique du firmware connecté :
+---
 
-- `story_v2`: endpoints `/api/story/*` + stream WebSocket.
-- `freenove_legacy`: endpoints `/api/status`, `/api/scenario/*`, `/api/stream` (SSE).
+## 📦 Fonctionnalités principales
 
-Les actions non supportees en mode legacy sont desactivees avec message explicite.
+- Sélecteur de scénario avancé (recherche, tri, mode legacy, CTA adaptés)
+- Orchestrateur live (statut runtime, recovery, filtres, contrôles réseau)
+- Story Designer nodal (React Flow, import/export YAML, édition guidée, auto-layout)
+- UI harmonisée (glass modern, labels FR, accessibilité)
 
-## Diagnostics firmware
+---
 
-À la connexion, le front analyse aussi des endpoints firmware non intrusifs :
-
-- version firmware (`/api/version`, `/api/firmware`, `/api/system/info`, `/api/status`),
-- endpoints OTA (`/api/update`, `/api/ota*`, `/api/upgrade*`),
-- endpoints reboot (`/api/reboot`, `/api/reset`, `/api/system/reboot`, `/api/restart`).
-
-L'état est affiché dans le panneau "Firmware". En cas d'absence, le front affiche une alerte claire et les actions de mise à jour ne sont pas proposées.
-
-## Variables d'environnement
-
-- `VITE_API_BASE` cible prioritaire (ex: `http://192.168.0.91`)
-- `VITE_API_PROBE_PORTS` ordre de probe (defaut: `80,8080`)
-- `VITE_API_FLAVOR` override (`auto|story_v2|freenove_legacy`, defaut `auto`)
-
-## Run
+## 🚀 Installation & démarrage rapide
 
 ```bash
 npm install
 npm run dev
 ```
 
-Preset ESP cible `192.168.0.91`:
+Accès local : http://localhost:5173
+Accès LAN : http://<ip-machine>:5173
 
+Preset ESP :
 ```bash
 npm run dev:esp
 ```
 
-- Dev local: `http://localhost:5173`
-- Dev LAN: `http://<ip-machine>:5173`
+---
 
-Preview sur build existant:
+## 🛠️ Usage
 
-```bash
-npm run preview:esp
-```
+Détection automatique du firmware connecté :
+- `story_v2` : endpoints `/api/story/*` + WebSocket
+- `freenove_legacy` : endpoints `/api/status`, `/api/scenario/*`, `/api/stream` (SSE)
+
+Diagnostics firmware :
+- Version, OTA, reboot détectés automatiquement
+- État affiché dans le panneau "Firmware"
+
+Variables d'environnement :
+- `VITE_API_BASE` (ex: `http://192.168.0.91`)
+- `VITE_API_PROBE_PORTS` (défaut: `80,8080`)
+- `VITE_API_FLAVOR` (`auto|story_v2|freenove_legacy`, défaut `auto`)
+
+---
+
+## 🤝 Contribuer
+
+Les contributions sont bienvenues !
+Merci de lire [../../CONTRIBUTING.md](../../CONTRIBUTING.md) avant toute PR.
+
+---
+
+## 🧑‍🎓 Licence
+
+- **Code** : MIT (`../../LICENSE`)
+
+---
+
+## 👤 Contact
+
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)
 
 - Preview local: `http://localhost:4173`
 - Preview LAN: `http://<ip-machine>:4173`

hardware/README.md

@@ -1,17 +1,45 @@
-# Hardware
+---
+# Zacus Hardware
 
-Contenu principal:
-- BOM: `bom/bom.md`
-- Cablage: `wiring/wiring.md`
-- Firmware: `firmware/` (ESP32 audio + UI OLED + UI TFT)
-- Boitier: `enclosure/`
+---
 
-Firmware structure:
-- `firmware/esp32_audio/`
-- `firmware/ui/esp8266_oled/`
-- `firmware/ui/rp2040_tft/`
-- `firmware/protocol/ui_link_v2.md`
+## 📝 Description
 
-Licence:
-- code: GPL-3.0-or-later
-- docs hardware: CC BY-SA 4.0
+Matériel et accessoires électroniques pour le jeu Zacus : firmware, câblage, boîtiers, BOM.
+
+---
+
+## 📦 Contenu du dossier
+// TODO NO DEV FINISH (need KILL_LIFE ?)
+
+- **BOM** : `bom/bom.md` 
+- **Câblage** : `wiring/wiring.md`
+- **Firmware** : `firmware/` (ESP32 audio, UI OLED, UI TFT)
+- **Boîtier** : `enclosure/`
+
+---
+
+## 🚀 Installation & usage
+
+Voir le guide d'installation et de build dans `firmware/README.md`.
+
+---
+
+## 🤝 Contribuer
+
+Les contributions sont bienvenues !
+Merci de lire [../CONTRIBUTING.md](../CONTRIBUTING.md) avant toute PR.
+
+---
+
+## 🧑‍🎓 Licence
+
+- **Code** : GPL-3.0-or-later
+- **Docs hardware** : CC BY-SA 4.0
+
+---
+
+## 👤 Contact
+
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)

hardware/enclosure/README.md

@@ -1,24 +1,54 @@
 
-# Boîtier / Enclosure
+---
+# Zacus Hardware – Boîtier / Enclosure
+// TODO NO DEV FINISH (need KILL_LIFE ?)
 
-## Media Kit Freenove
+---
+
+## 📝 Description
+
+Boîtier plastique multi-usage pour accueillir l’électronique Zacus (Media Kit Freenove ou équivalent).
+
+---
+
+## 📦 Caractéristiques principales
 
 - **Type** : Boîtier plastique multi-usage (Media Kit)
 - **Référence** : Freenove Media Kit Box (ex : FNK0052 ou équivalent)
-- **Dimensions** : ~ 120 x 80 x 35 mm (vérifier selon version)
+- **Dimensions** : ~ 120 x 80 x 35 mm (à vérifier selon version)
 - **Matériau** : ABS noir, couvercle transparent
 - **Ports** :
-	- 2 ouvertures latérales (USB, alimentation)
-	- 1 ouverture frontale (audio, boutons)
-	- 1 grille pour ventilation
+  - 2 ouvertures latérales (USB, alimentation)
+  - 1 ouverture frontale (audio, boutons)
+  - 1 grille pour ventilation
 - **Fixation** : inserts pour vis M2/M3, pads antidérapants
 - **Utilisation** :
-	- Accueille carte ESP32, UI, alimentation, HP, boutons
-	- Prédécoupes pour connecteurs (USB, jack, etc.)
+  - Accueille carte ESP32, UI, alimentation, HP, boutons
+  - Prédécoupes pour connecteurs (USB, jack, etc.)
 - **Lien officiel** : [Freenove Media Kit](https://www.freenove.com/media-kit.html)
 
 ---
 
-- dimensions
-- découpe/assemblage
-- fichiers (STL/SVG) si ajout futur
+## 🚀 Installation & usage
+
+Voir le guide de câblage dans `../wiring/wiring.md`.
+
+---
+
+## 🤝 Contribuer
+
+Les contributions sont bienvenues !
+Merci de lire [../../CONTRIBUTING.md](../../CONTRIBUTING.md) avant toute PR.
+
+---
+
+## 🧑‍🎓 Licence
+
+- **Docs hardware** : CC BY-SA 4.0
+
+---
+
+## 👤 Contact
+
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)

hardware/firmware/docs/protocols/README.md

@@ -1,24 +1,56 @@
-# Protocoles d’échange firmware
+---
+# Zacus Firmware – Protocoles d’échange
+
+---
+
+## 📝 Description
 
 Ce dossier centralise les contrats partagés entre firmwares (ESP32, RP2040, ESP8266).
 
-## Source of truth
-- `../../protocol/ui_link_v2.md`: protocole UART UI Link v2 (ESP32 <-> OLED/TFT).
-- `PROTOCOL.md`: commandes série canoniques ESP32 (debug/ops).
-- `UI_SPEC.md`: comportement UI et contrat fonctionnel.
-- `story_specs/schema/story_spec_v1.yaml` + templates/scenarios: contrat auteur STORY.
-- `story_specs/prompts/*.prompt.md`: prompts d'autoring Story (distincts des prompts ops).
-- `STORY_V2_PIPELINE.md`: pipeline YAML -> gen -> runtime -> apps -> screen.
-- `RELEASE_STORY_V2.md`: guide release Story V2 (gates/rollback).
+---
+
+## 📦 Source of truth
+
+- `../../protocol/ui_link_v2.md` : protocole UART UI Link v2 (ESP32 <-> OLED/TFT)
+- `PROTOCOL.md` : commandes série canoniques ESP32 (debug/ops)
+- `UI_SPEC.md` : comportement UI et contrat fonctionnel
+- `story_specs/schema/story_spec_v1.yaml` + templates/scenarios : contrat auteur STORY
+- `story_specs/prompts/*.prompt.md` : prompts d'autoring Story (distincts des prompts ops)
+- `STORY_V2_PIPELINE.md` : pipeline YAML -> gen -> runtime -> apps -> screen
+- `RELEASE_STORY_V2.md` : guide release Story V2 (gates/rollback)
+
+---
+
+## 🚀 Installation & usage
+
+Les implémentations firmware doivent référencer ces documents dans leur README.
+
+---
+
+## 🔄 Règles d’évolution
 
-## Règles d’évolution
 - Toute évolution de protocole passe d'abord par ce dossier.
-- Politique additive par défaut:
+- Politique additive par défaut :
   - ajouter des champs/tokens est autorisé,
   - supprimer/renommer exige une dépréciation documentée.
-- Les implémentations firmware doivent référencer ces documents dans leur README.
 
-## Vérification minimale à chaque changement
-1. Build des environnements concernés (`pio run -e <env>`).
-2. Vérification de traçabilité commande/spec/code.
-3. Mise à jour de `INDEX.md` si ajout ou déplacement de fichiers.
+---
+
+## ✅ Vérification minimale à chaque changement
+1. Build des environnements concernés (`pio run -e <env>`)
+2. Vérification de traçabilité commande/spec/code
+3. Mise à jour de `INDEX.md` si ajout ou déplacement de fichiers
+
+---
+
+## 🤝 Contribuer
+
+Merci de lire [../../../../CONTRIBUTING.md](../../../../CONTRIBUTING.md) avant toute PR.
+
+---
+
+## 👤 Contact
+
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)
+---

hardware/firmware/hardware/firmware/esp32_audio/README.md

@@ -1,6 +1,52 @@
 
 
-# Firmware ESP32
+
+---
+# Zacus Firmware – ESP32 Audio
+
+---
+
+## 📝 Description
+
+Firmware principal pour ESP32 Audio Kit V2.2 A252 : gestion audio, logique principale, radio, communication UI.
+
+---
+
+## 🚀 Installation & usage
+
+Tous les assets LittleFS (sons, scénarios, écrans, etc.) sont centralisés dans `hardware/firmware/data/` à la racine du projet.
+Ce dossier unique sert de source pour le flash LittleFS sur ESP32, ESP8266 et RP2040.
+
+Prérequis : PlatformIO, Python 3.14
+Cloner le repo, puis :
+```sh
+cd esp32
+pio run
+```
+Build : `pio run`
+Flash : `pio run -t upload`
+
+---
+
+## 📦 Structure & contenu
+
+- Logique principale, audio, radio, UI (RP2040)
+- Protocole UI, dépannage, mise à jour
+- Voir sections détaillées ci-dessous
+
+---
+
+## 🤝 Contribuer
+
+Merci de lire [../../../../../../../../CONTRIBUTING.md](../../../../../../../../CONTRIBUTING.md) avant toute PR.
+
+---
+
+## 👤 Contact
+
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)
+---
 
 > **[Mise à jour 2026]**
 >

hardware/firmware/hardware/firmware/ui/esp8266_oled/README.md

@@ -1,43 +1,67 @@
 
-# Firmware UI ESP8266 OLED (UI Link v2)
+---
+# Zacus Firmware – UI ESP8266 OLED (UI Link v2)
+// TODO NO DEV FINISH (need KILL_LIFE ?)
+---
 
-> **[Mise à jour 2026]**
->
-> **Tous les assets LittleFS (scénarios, écrans, scènes, audio, etc.) sont désormais centralisés dans le dossier `hardware/firmware/data/` à la racine du projet.**
->
-> Ce dossier unique sert de source pour le flash LittleFS sur ESP32, ESP8266 et RP2040. Les anciens dossiers `data/` dans les sous-projets doivent être migrés/supprimés (voir encart migration ci-dessous).
+## 📝 Description
 
+Firmware UI OLED léger (U8G2) pour ESP8266, implémentant UI Link v2 en UART full duplex.
 
-Ce firmware garde une UI OLED legere (U8G2) et implemente UI Link v2 en UART full duplex.
+---
 
-## Architecture
+## 🚀 Installation & usage
 
-- `src/core/telemetry_state.h`: modele de telemetrie
-- `src/core/stat_parser.*`: decode `STAT`/`KEYFRAME` v2 (`k=v`, CRC8)
-- `src/core/link_monitor.*`: watchdog lien et recovery
-- `src/core/render_scheduler.*`: rendu non bloquant
-- `src/apps/*`: ecrans fonctionnels (boot, lien, mp3, ulock)
-- `src/main.cpp`: handshake `HELLO`, reponse `PONG`, boucle UI
+Tous les assets LittleFS (scénarios, écrans, scènes, audio, etc.) sont centralisés dans `hardware/firmware/data/` à la racine du projet.
+Ce dossier unique sert de source pour le flash LittleFS sur ESP32, ESP8266 et RP2040.
 
-## Protocole
+---
 
-Transport: trames ASCII ligne par ligne:
+## 📦 Architecture & contenu
 
+- `src/core/telemetry_state.h` : modèle de télémétrie
+- `src/core/stat_parser.*` : decode `STAT`/`KEYFRAME` v2 (`k=v`, CRC8)
+- `src/core/link_monitor.*` : watchdog lien et recovery
+- `src/core/render_scheduler.*` : rendu non bloquant
+- `src/apps/*` : écrans fonctionnels (boot, lien, mp3, unlock)
+- `src/main.cpp` : handshake `HELLO`, réponse `PONG`, boucle UI
+
+---
+
+## 🛠️ Protocole
+
+Transport : trames ASCII ligne par ligne :
 `<TYPE>,k=v,k=v*CC\n`
-
 - CRC8 polynomial `0x07`
-- UI -> ESP32: `HELLO`, `PONG`
-- ESP32 -> UI: `ACK`, `KEYFRAME`, `STAT`, `PING`
-- Capacites OLED annoncees: `caps=btn:0;touch:0;display:oled`
+- UI -> ESP32 : `HELLO`, `PONG`
+- ESP32 -> UI : `ACK`, `KEYFRAME`, `STAT`, `PING`
+- Capacités OLED annoncées : `caps=btn:0;touch:0;display:oled`
 
-## Cablage UART
+---
 
+## 🔌 Câblage
+
+### UART
 - ESP32 `GPIO22 (TX)` -> ESP8266 `D4 (RX)`
 - ESP8266 `D5 (TX)` -> ESP32 `GPIO19 (RX)`
 - GND commun obligatoire
-- Baud par defaut: `57600`
+- Baud par défaut : `57600`
 
-## Cablage OLED I2C
+### OLED I2C
+
+---
+
+## 🤝 Contribuer
+
+Merci de lire [../../../../../../../../CONTRIBUTING.md](../../../../../../../../CONTRIBUTING.md) avant toute PR.
+
+---
+
+## 👤 Contact
+
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)
+---
 
 - VCC -> `3V3`
 - GND -> `GND`

hardware/firmware/hardware/firmware/ui/rp2040_tft/README.md

@@ -1,44 +1,58 @@
 
-# Firmware UI RP2040 TFT (LVGL + UI Link v2)
+---
+# Zacus Firmware – UI RP2040 TFT (LVGL + UI Link v2)
+// TODO NO DEV FINISH (need KILL_LIFE ?)
+---
 
-> **[Mise à jour 2026]**
->
-> **Tous les assets LittleFS (scénarios, écrans, scènes, audio, etc.) sont désormais centralisés dans le dossier `hardware/firmware/data/` à la racine du projet.**
->
-> Ce dossier unique sert de source pour le flash LittleFS sur ESP32, ESP8266 et RP2040. Les anciens dossiers `data/` dans les sous-projets doivent être migrés/supprimés (voir encart migration ci-dessous).
+## 📝 Description
 
+Firmware UI tactile pour RP2040 avec écran TFT 3.5" + XPT2046, basé sur LVGL et UI Link v2.
 
-Firmware UI tactile RP2040 pour ecran TFT 3.5" + XPT2046.
+---
 
-## Points clefs
+## 🚀 Installation & usage
 
-- UI framework: LVGL
-- Drivers: TFT_eSPI + XPT2046_Touchscreen
-- Lien serie: UI Link v2 (`HELLO/ACK/KEYFRAME/STAT/PING/PONG/BTN`)
-- Touch -> boutons logiques (`PREV/NEXT/OK/BACK/VOL-/VOL+`)
-- Ecran degrade `LINK DOWN` si timeout
-
-## Build
-
-Depuis `hardware/firmware`:
+Tous les assets LittleFS (scénarios, écrans, scènes, audio, etc.) sont centralisés dans `hardware/firmware/data/` à la racine du projet.
+Ce dossier unique sert de source pour le flash LittleFS sur ESP32, ESP8266 et RP2040.
 
+Build depuis `hardware/firmware` :
 ```sh
 pio run -e ui_rp2040_ili9488
 pio run -e ui_rp2040_ili9486
 ```
-
-Flash:
-
+Flash :
 ```sh
 pio run -e ui_rp2040_ili9488 -t upload --upload-port <PORT_RP2040>
 ```
-
-Boucle rapide:
-
+Boucle rapide :
 ```sh
 make fast-ui-tft UI_TFT_PORT=<PORT_RP2040>
 ```
 
+---
+
+## 📦 Points clefs & contenu
+
+- UI framework : LVGL
+- Drivers : TFT_eSPI + XPT2046_Touchscreen
+- Lien série : UI Link v2 (`HELLO/ACK/KEYFRAME/STAT/PING/PONG/BTN`)
+- Touch -> boutons logiques (`PREV/NEXT/OK/BACK/VOL-/VOL+`)
+- Ecran dégradé `LINK DOWN` si timeout
+
+---
+
+## 🤝 Contribuer
+
+Merci de lire [../../../../../../../../CONTRIBUTING.md](../../../../../../../../CONTRIBUTING.md) avant toute PR.
+
+---
+
+## 👤 Contact
+
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)
+---
+
 
 ---
 

hardware/firmware/hardware/firmware/ui/web/README.md

@@ -1,9 +1,16 @@
 
-# Story V2 WebUI
+---
+# Zacus Firmware – Story V2 WebUI
+
+---
+
+## 📝 Description
 
 Interface web pour piloter et designer les scénarios Story V2 (ESP32).
 
-## Démarrage rapide
+---
+
+## 🚀 Installation & usage
 
 ```sh
 npm install
@@ -13,18 +20,37 @@ npm run dev
 - Accès local : http://localhost:5173/
 - API cible : http://<ESP_IP>:8080
 
-## Structure
+---
+
+## 📦 Contenu du dossier
+
 - `src/components/ScenarioSelector.tsx` : sélection et lancement de scénario
 - `src/components/LiveOrchestrator.tsx` : suivi live, log, contrôles
 - `src/components/StoryDesigner.tsx` : éditeur YAML, validate/deploy
 
-## Qualité code
+---
+
+## 🛠️ Qualité code
+
 - ESLint + Prettier intégrés
 
-## Spécifications
+---
+
+## 📄 Spécifications
+
 - API : voir `../../docs/protocols/STORY_V2_WEBUI.md`
 - YAML : voir `../../docs/protocols/story_specs/schema/story_spec_v1.yaml`
 
 ---
 
-Pour toute question, voir le plan : `../PLAN_UI_WEB_STORY_V2.md`
+## 🤝 Contribuer
+
+Merci de lire [../../../../../../../../CONTRIBUTING.md](../../../../../../../../CONTRIBUTING.md) avant toute PR.
+
+---
+
+## 👤 Contact
+
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)
+---

hardware/firmware/hardware/firmware/ui_freenove_allinone/README.md

@@ -1,4 +1,20 @@
-## Mapping hardware ESP32-S3 Freenove Media Kit
+
+---
+# 🎛️ Zacus Firmware – Freenove All-in-One
+
+![Funk](https://media.giphy.com/media/3o7TKtnuHOHHUjR38Y/giphy.gif)
+
+---
+
+## 📝 Description
+
+Bienvenue dans le cockpit le plus funky du multivers ! Ce firmware fusionne UI, audio, scénarios et hardware sur la carte Freenove Media Kit (ESP32). Ici, chaque pixel danse, chaque bouton groove, et chaque boot est une fête.
+
+> *"Si tu entends un son rétro ou vois un plasma violet, c’est normal. Si le microcontrôleur se met à rapper, c’est probablement un bug… ou un feature caché."*
+
+---
+
+## 🕹️ Mapping hardware (ESP32-S3 Freenove Media Kit)
 
 | Fonction         | Broche ESP32-S3 | Signal TFT/Touch/Audio | Remarques                      |
 |------------------|-----------------|-----------------------|--------------------------------|
@@ -22,6 +38,88 @@
 - Profils fournis: `0=sketch19`, `1=swap_bck_ws`, `2=dout2_alt`.
 - Le tactile est désactivé par défaut (`FREENOVE_HAS_TOUCH=0`).
 
+---
+
+## 📦 Contenu du dossier
+
+- Sources : `src/` (app, ui, audio, storage, camera, drivers, system)
+- Polices : `src/ui/fonts/`
+- Layouts d’écran : `src/ui/screens/`
+- Partition custom : `partitions/freenove_esp32s3_app6mb_fs6mb.csv`
+- Mapping hardware détaillé (voir pour descendre plus haut )
+
+---
+
+## 🚀 Installation & usage
+
+1. Clone ce repo, chausse tes lunettes de soleil.
+2. Va dans `hardware/firmware` et build comme un DJ :
+  ```sh
+  pio run -e freenove_allinone
+  pio run -e freenove_allinone -t upload --upload-port <PORT>
+  ```
+3. Pour la version ESP32-S3 (partition 6MB app / 6MB FS) :
+  ```sh
+  pio run -e freenove_esp32s3
+  pio run -e freenove_esp32s3 -t buildfs
+  pio run -e freenove_esp32s3 -t uploadfs --upload-port <PORT>
+  pio run -e freenove_esp32s3 -t upload --upload-port <PORT>
+  ```
+4. Branche, allume, et laisse la magie opérer.
+
+---
+
+## 🧩 Fonctionnalités qui groovent
+
+- Navigation UI dynamique (LVGL, écrans générés depuis fichiers)
+- Exécution de scénarios (lecture, transitions, actions, audio)
+- Gestion audio (lecture/stop, mapping fichiers LittleFS)
+- Gestion boutons et tactile (événements, mapping, callbacks)
+- Fallback robuste si fichier manquant (scénario par défaut)
+- Génération de logs et artefacts (logs/, artifacts/)
+- Validation hardware sur Freenove (affichage, audio, boutons, tactile)
+- Documentation et onboarding synchronisés
+- Mode autonome (pas besoin d’ESP32 séparé)
+
+> *"Si tu rates un bouton, c’est que tu danses trop fort. Si tu vois un plasma violet, c’est que tu es dans le groove."*
+
+---
+
+## 🛠️ Modules principaux
+
+- `audio_manager` : fait swinguer l’audio (lecture, stop, état)
+- `scenario_manager` : enchaîne les étapes comme un DJ
+- `ui_manager` : LVGL, écrans dynamiques, FX visuels
+- `storage_manager` : LittleFS (init, vérif, groove des assets)
+- `button_manager` : boutons physiques, pour les vrais
+- `touch_manager` : tactile XPT2046, pour les DJ du futur
+
+---
+
+## 🦄 Funky extras & notes
+
+- Firmware expérimental : fusion audio + UI, mode "party hard" activé
+- Pour la compatibilité UI Link, prévoir un mode optionnel
+- Si tu veux une intro Amiga92, active la scène `SCENE_WIN_ETAPE` et laisse-toi porter par le FX timeline (plasma, starfield, boingball…)
+- Pour tester la scène MP3 : `SCENE_MP3_PLAYER` (overlay AmigaAMP, scan `/music`)
+- Pour la caméra : `SCENE_CAMERA_SCAN` (Win311 overlay, boutons = SNAP/SAVE/GALLERY/DELETE/CLOSE)
+- Pour tout le reste, consulte les logs, et si tu comprends tout du premier coup, tu gagnes un badge "Zacus Funk Master".
+
+---
+
+## 🤝 Contribuer
+
+Merci de lire [../../../../../../CONTRIBUTING.md](../../../../../../CONTRIBUTING.md) avant toute PR. Les pull requests avec punchlines sont encouragées.
+
+---
+
+## 👤 Contact
+
+Pour toute question, suggestion, ou battle de funk, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)
+
+> *"Ce firmware a été validé par un oscilloscope, un grille-pain, et un synthé vintage. Si tu trouves un bug, c’est peut-être un easter egg ou feat foirée."*
+---
 
 # Firmware Freenove Media Kit All-in-One
 

hardware/firmware/hardware/firmware/ui_freenove_allinone/src/README.md

@@ -1,4 +1,38 @@
 # src/
 Sources pour le firmware Freenove all-in-one (fusion audio + UI).
-- main.cpp : point d'entrée fusionné
-- Ajouter ici les modules fusionnés (audio, scenario, UI, etc.)
+---
+# Zacus Firmware – UI Freenove All-in-One
+
+---
+
+## 📝 Description
+
+Sources principaux de l’UI Zacus pour la carte Freenove All-in-One (RP2040 + TFT).
+
+---
+
+## 📦 Contenu du dossier
+
+- Entrée principale : `main.cpp`
+- Polices : `ui/fonts/`
+- Layouts d’écran : `ui/screens/`
+
+---
+
+## 🚀 Installation & usage
+
+Voir le guide d’installation dans le dossier parent et compiler avec PlatformIO.
+
+---
+
+## 🤝 Contribuer
+
+Merci de lire [../../../../../../../../CONTRIBUTING.md](../../../../../../../../CONTRIBUTING.md) avant toute PR.
+
+---
+
+## 👤 Contact
+
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)
+---

hardware/firmware/hardware/firmware/ui_freenove_allinone/src/ui/fonts/README.md

@@ -1,6 +1,41 @@
-Generated LVGL font sources (.c) are emitted here by:
+---
+# Zacus Firmware – UI Fonts
 
-`tools/fonts/scripts/generate_lvgl_fonts.sh`
+---
 
-The runtime currently uses built-in Montserrat fallbacks unless `UI_FONT_EXTERNAL_SET=1`
-and the generated files are present/compiled.
+## 📝 Description
+
+Ce dossier contient les polices personnalisées pour l’UI Zacus (LVGL, bitmap, etc).
+
+---
+
+## 📦 Contenu du dossier
+
+- Fichiers générés LVGL (.c) via `tools/fonts/scripts/generate_lvgl_fonts.sh`
+- TTF/OTF pour génération LVGL
+- PNG/BMP pour polices bitmap
+
+Le runtime utilise Montserrat intégré sauf si `UI_FONT_EXTERNAL_SET=1` et que les fichiers générés sont présents/compilés.
+
+---
+
+## 🚀 Installation & usage
+
+Placer les polices ici puis utiliser le script :
+```sh
+tools/fonts/scripts/generate_lvgl_fonts.sh
+```
+
+---
+
+## 🤝 Contribuer
+
+Merci de ne pas ajouter de polices propriétaires sans licence libre.
+
+---
+
+## 👤 Contact
+
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)
+---

hardware/firmware/hardware/libs/story/README.md

@@ -1,63 +1,58 @@
-# STORY portable (generation + runtime)
+---
+# Zacus Firmware – STORY portable (génération + runtime)
 
-## Objectif
+---
 
-Permettre d'ajouter/modifier un scenario STORY sans toucher au moteur C++:
+## 📝 Description
 
-1. ecrire un fichier `../docs/protocols/story_specs/scenarios/*.yaml`
-2. valider le spec
-3. generer le code C++
-4. compiler/flasher
+Permet d’ajouter ou modifier un scénario STORY sans toucher au moteur C++.
+// TODO NO DEV TESTING ? (need KILL_LIFE ?)
 
-Le flux par defaut migre est:
+---
 
+## 📦 Fonctionnement
+
+Étapes pour ajouter un scénario :
+1. Écrire un fichier `../docs/protocols/story_specs/scenarios/*.yaml`
+2. Valider le spec
+3. Générer le code C++
+4. Compiler/flasher
+
+Flux par défaut migré :
 ```
 UNLOCK → U_SON_PROTO → WAIT_ETAPE2 → ETAPE2 → DONE
 ```
+Tous les nouveaux scénarios doivent suivre ce flux (ou l’étendre, jamais le modifier).
 
-**Tous les nouveaux scénarios doivent suivre ce flux par défaut** (ou l'étendre, jamais le modifier).
+---
 
-## Source de verite
+## 🚀 Installation & usage
 
-- schema logique: `../docs/protocols/story_specs/schema/story_spec_v1.yaml`
-- template auteur: `../docs/protocols/story_specs/templates/scenario.template.yaml`
-- scenario migre PR1: `../docs/protocols/story_specs/scenarios/default_unlock_win_etape2.yaml`
-- scenario additionnel RC2: `../docs/protocols/story_specs/scenarios/spectre_radio_lab.yaml`
+Sources de vérité :
+- Schéma logique : `../docs/protocols/story_specs/schema/story_spec_v1.yaml`
+- Template auteur : `../docs/protocols/story_specs/templates/scenario.template.yaml`
+- Scénarios exemples : `../docs/protocols/story_specs/scenarios/`
 
-Le runtime portable charge le code genere et/ou LittleFS:
+Génération :
+- `tools/story_gen/story_gen.py`
+- Code généré : `src/story/generated/`
 
-- `src/story/generated/scenarios_gen.h`
-- `src/story/generated/scenarios_gen.cpp`
-- `src/story/generated/apps_gen.h`
-- `src/story/generated/apps_gen.cpp`
+Mini Apps FSM :
+- Interface commune : `src/story/apps/story_app.h`
+- Apps : `LaDetectorApp`, `AudioPackApp`, `ScreenSceneApp`, `Mp3GateApp`
 
-Le generateur expose aussi la config app LA:
+---
 
-- `LaDetectorAppConfigDef`
-- `generatedLaDetectorConfigByBindingId(const char* id)`
+## 🤝 Contribuer
 
-## Mini Apps FSM
+Merci de lire [../../../../../../CONTRIBUTING.md](../../../../../../CONTRIBUTING.md) avant toute PR.
 
-Interface commune:
+---
 
-- `src/story/apps/story_app.h`
-- `begin(context)`
-- `start(stepContext)`
-- `update(nowMs, eventSink)`
-- `stop(reason)`
-- `handleEvent(event, eventSink)`
-- `snapshot()`
+## 👤 Contact
 
-Apps PR1:
-
-- `LaDetectorApp`
-- `AudioPackApp`
-- `ScreenSceneApp`
-- `Mp3GateApp`
-
-Evolution RC2:
-
-- `LaDetectorApp` devient full-owned pour l'unlock V2 (hold + emission event).
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)
 - config par binding YAML via `app_bindings[].config` (LA uniquement):
   - `hold_ms`
   - `unlock_event`

hardware/firmware/tools/fonts/ttf/README.md

@@ -1,9 +1,41 @@
-Place the font sources used by `tools/fonts/scripts/generate_lvgl_fonts.sh` in this directory.
+---
+# Zacus Firmware – Fonts TTF
+
+---
+
+## 📝 Description
+
+Ce dossier contient les polices TTF nécessaires à la génération des polices LVGL pour l’UI Zacus.
+
+---
+
+## 📦 Fichiers requis
 
-Required files:
 - `Inter-Regular.ttf`
 - `Orbitron-Bold.ttf`
 - `IBMPlexMono-Regular.ttf`
-- `PressStart2P-Regular.ttf` (optional when `UI_FONT_PIXEL_ENABLE=1`)
+- `PressStart2P-Regular.ttf` (optionnel si `UI_FONT_PIXEL_ENABLE=1`)
 
-These files are not versioned in the repository to avoid shipping upstream font binaries.
+Ces fichiers ne sont pas versionnés dans le dépôt pour éviter d’inclure des binaires upstream.
+
+---
+
+## 🚀 Installation & usage
+
+Placer les fichiers TTF dans ce dossier, puis lancer le script :
+```sh
+tools/fonts/scripts/generate_lvgl_fonts.sh
+```
+
+---
+
+## 🤝 Contribuer
+
+Merci de ne pas ajouter de polices propriétaires sans licence libre.
+
+---
+
+## 👤 Contact
+
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)

hardware/firmware/tools/test/README.md

@@ -1,21 +1,39 @@
-# Test wrappers (firmware workspace)
+---
+# Zacus Firmware – Test Wrappers
 
-Canonical implementation lives in the repo root:
+---
 
-- `tools/test/hw_now.sh` (combined ESP32+ESP8266 gate)
-- `tools/test/hw_now_esp32_esp8266.sh` (fw-only subset)
-- `tools/test/run_rc_gate.sh` and `tools/dev/rc_execution_seed.sh` for RC board automation
+## 📝 Description
 
-This folder only provides thin wrappers so you can run a script while staying
-in `hardware/firmware` without path juggling. Call them with the same options as
-the root scripts:
+Ce dossier fournit des wrappers pour lancer les scripts de test depuis `hardware/firmware` sans jongler avec les chemins.
 
-```
+---
+
+## 🚀 Installation & usage
+
+Scripts principaux (implémentation canonique à la racine) :
+- `tools/test/hw_now.sh` (ESP32+ESP8266)
+- `tools/test/hw_now_esp32_esp8266.sh` (firmware only)
+- `tools/test/run_rc_gate.sh` et `tools/dev/rc_execution_seed.sh` (automation RC)
+
+Exemples d’utilisation :
+```sh
 tools/test/hw_now.sh --env-esp32 esp32_release --wait-port 40
 tools/test/hw_now_esp32_esp8266.sh --skip-build --baud 57600
 tools/test/run_rc_gate.sh --help
 ```
 
-The wrappers honor the same auto-port detection, artifact logging, and smoke
-syntax (`tools/dev/serial_smoke.py --role auto`) defined at the repo root so that
-validation runs stay reproducible locally and match the RC gate requirements.
+Les wrappers respectent la détection auto-port, le logging d’artifacts et la syntaxe smoke (`tools/dev/serial_smoke.py --role auto`).
+
+---
+
+## 🤝 Contribuer
+
+Merci de lire [../../../CONTRIBUTING.md](../../../CONTRIBUTING.md) avant toute PR.
+
+---
+
+## 👤 Contact
+
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)

kit-maitre-du-jeu/README.md

@@ -1,18 +1,81 @@
-# Kit Maître du jeu
+---
+---
 
-Tout pour animer la partie.
 
-Fichiers :
-- `script-minute-par-minute.md`
-- `solution-complete.md`
-- `checklist-materiel.md`
-- `plan-stations-et-mise-en-place.md`
-- `distribution-des-roles.md`
-- `guide-anti-chaos.md`
-- `generer-un-scenario.md`
+# 🎩 Kit Maître du Jeu — Le Mystère du Professeur Zacus (v2)
 
-Bonus :
-- `stations/` (4–8 stations possibles, modulaires)
+![Chapeau](https://media.giphy.com/media/3o6Zt8zb1Pp2v3A2l6/giphy.gif)
 
-Exports :
-- `export/pdf/` (dossier prêt pour les versions PDF imprimables)
+---
+
+
+
+
+Ce dossier rassemble tout le nécessaire pour animer une session du scénario canon `game/scenarios/zacus_v2.yaml` : guides, conducteur, solution, anti-chaos, checklist, modules de stations, et objets spécifiques (piano-alphabet, portrait QR). Il s’appuie sur la structure YAML, les printables, l’audio et les guides MJ du dépôt.
+
+### ⚡ Solution ESP32 Media Kit
+Le scénario v2 est conçu pour fonctionner avec le Media Kit ESP32 : un module électronique qui automatise la gestion des étapes, des feedbacks audio/visuels, du QR WIN et du Media Hub final. Ce kit permet au MJ de se concentrer sur l’animation et la coopération, tout en garantissant la robustesse des validations (LA 440, piano LEFOU, QR WIN).
+
+- Boot, transitions, indices audio, confirmations et finale sont gérés par le firmware (voir hardware/firmware/ et la section firmware du YAML canon).
+- Le Media Hub (photo, audio, jingle) s’active automatiquement après la réussite.
+- Un backup MJ est toujours possible (validation manuelle, QR de secours).
+
+> *"Si tu arrives à la fin sans perdre une seule fiche, tu gagnes le badge Maître du Funk !"*
+
+---
+
+
+
+## 📦 Contenu du dossier
+
+- `script-minute-par-minute.md` : conducteur détaillé, minute par minute, aligné sur les 2 actes (LA 440, Zone 4, QR WIN)
+- `solution-complete.md` : solution complète du scénario canon (voir aussi `game/scenarios/zacus_v2.yaml`)
+- `checklist-materiel.md` : checklist matériel, compatible printables/audio, objets spécifiques (piano-alphabet, portrait QR)
+- `plan-stations-et-mise-en-place.md` : plan des stations, instructions de mise en place (voir objets et clues YAML)
+- `distribution-des-roles.md` : répartition des rôles MJ/enfants (voir aussi `_generated/roles.md`)
+- `guide-anti-chaos.md` : gestion de groupe, règles anti-chaos (voir aussi `_generated/anti-chaos.md`)
+- `generer-un-scenario.md` : procédure pour créer/valider un scénario compatible repo
+- `stations/` : stations modulaires, à compléter selon le scénario v2
+- `_generated/` : versions synchronisées avec le YAML canon et les manifests
+- `export/pdf/` : exports prêts à imprimer
+
+---
+
+
+## 🚀 Mode d’emploi (MJ, version canon v2)
+
+1. Lis ce README et le script-minute-par-minute
+2. Prépare le matériel avec la checklist (voir aussi `_generated/checklist.md`)
+3. Place le scénario YAML canon (`game/scenarios/zacus_v2.yaml`) sur la table MJ
+4. Distribue les rôles (voir `distribution-des-roles.md` et `_generated/roles.md`)
+5. Mets en place les stations selon le plan (voir `plan-stations-et-mise-en-place.md` et `_generated/stations.md`)
+6. Prépare les objets spécifiques : piano-alphabet (stickers A–Z), portrait QR WIN
+7. Lance la session en suivant le conducteur, utilise les guides anti-chaos si besoin
+8. (Option) Ajoute ou adapte des stations bonus pour varier les parties
+
+> *"Si tu perds le contrôle, relis le guide anti-chaos. Si tu le perds aussi, improvise : c’est ça, l’esprit Zacus !"*
+
+---
+
+
+
+## 🤝 Contribuer
+
+Les contributions sont bienvenues ! Merci de lire [../CONTRIBUTING.md](../CONTRIBUTING.md) avant toute PR. Priorité aux ajouts cohérents avec le YAML canon (`game/scenarios/zacus_v2.yaml`), les manifests audio/printables et la structure du repo.
+
+---
+
+
+## 🧑‍🎓 Licence
+
+- **Contenu créatif** : CC BY-NC 4.0 ([../LICENSE-CONTENT.md](../LICENSE-CONTENT.md))
+
+---
+
+## 👤 Contact
+
+Pour toute question, suggestion, ou anecdote de MJ, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)
+
+> *"Ce kit a été testé sur MJ stressé, enfants surexcités, et robots en panne d’inspiration. Résultat : 100% de fun garanti."*
+---

kit-maitre-du-jeu/checklist-materiel.md

@@ -1,28 +1,52 @@
-# Checklist matériel
+# Checklist matériel (version canon Zacus v2)
+
+> ⚡ Le Media Kit ESP32 fait le gros du boulot : feedbacks, transitions, QR, Media Hub… Le MJ n’a plus qu’à canaliser l’énergie ionique du groupe !
+## Matériel principal
+- [ ] Media Kit ESP32 (préconfiguré, voir hardware/firmware/)
+## Objets spécifiques scénario v2
+> Astuce : range chaque pièce avec son numéro de station. Prépare un backup QR WIN dans la boîte MJ (voir YAML). Si un électron s’excite trop, propose-lui de faire le tour du labo à la vitesse de la lumière (ou presque). Les enfants peuvent eux-mêmes remettre en ordre les enveloppes après la session pour entraîner leur mémoire.
+
+
+# Checklist matériel (version canon Zacus v2)
+
+- Scénario : voir `game/scenarios/zacus_v2.yaml` (source de vérité)
+- Participants : 6–14 enfants
+- Durée : 105 min (2 actes : 45 + 60)
+- Stations prévues : 3 (Atelier des Ondes, Zone 4 – Piano Alphabet, Archives QR)
+
+
+## Matériel principal
+- [ ] Enveloppes numérotées (1 par station)
+- [ ] Badges détective + fiches d’enquête (1/groupe)
+- [ ] Cartes indices imprimées (3 exemplaires/station)
+- [ ] Chronomètre ou timer visible
+- [ ] Bloc-notes central et stylos/feutres
+- [ ] Feuilles de correction / marqueurs
 
-## Matériel de base (toujours prêt)
-- [ ] Cartes indices imprimées (au moins 3 exemplaires par station)
-- [ ] Badges détective + feutres effaçables
-- [ ] Fiche d’enquête pour chaque groupe et un bloc-notes central
-- [ ] Enveloppes ou pochettes numérotées (stations 1 à 4)
-- [ ] Chronomètre ou timer visible pour la progression
-- [ ] Feuilles de correction / marqueurs pour écrire les solutions intermédiaires
 
 ## Supports numériques & audio
-- [ ] Tablette ou téléphone pour lire les fichiers `game/prompts/audio/*.md`
-- [ ] Haut-parleur portable (niveau sonore modéré)
-- [ ] Liste des QR codes ou liens vers les fichiers audio
-- [ ] Sauvegarde des fichiers audio (clé USB ou dossier partagé)
+- [ ] Tablette ou téléphone pour lire les fichiers audio (`game/prompts/audio/*.md`)
+- [ ] Haut-parleur portable (volume modéré)
+- [ ] QR codes ou liens vers les fichiers audio (voir `audio/manifests/zacus_v2_audio.yaml`)
+- [ ] Sauvegarde des fichiers audio (clé USB ou cloud)
 
-## Matériel pour l’ambiance
-- [ ] Lumières tamisées (lampes de bureau, guirlandes à LED)
-- [ ] Accessoires laboratoire : éprouvettes, flacons colorés, filtres
-- [ ] Éléments visuels imprimés : plan de l’Auréole, affiche “Laboratoire Zacus”
-- [ ] Tableaux blancs ou feuilles pour afficher les hypothèses
 
-## Extensions modulaires (optionnelles)
-- [ ] Station bonus : puzzle magnétique ou mini-expérience chimique (peroxide + colorant)
-- [ ] Chroniqueur : caméra ou smartphone pour filmer la réaction finale
-- [ ] Récompenses (stickers, diplômes, décorations imprimées)
+## Ambiance & accessoires
+- [ ] Lumières tamisées (lampes, guirlandes LED)
+- [ ] Accessoires labo : éprouvettes, flacons, filtres
+- [ ] Visuels imprimés : plan du Campus, affiche “Laboratoire Zacus”
+- [ ] Tableaux blancs ou feuilles pour hypothèses
 
-> Astuce : range chaque pièce avec son numéro de station. Les enfants peuvent eux-mêmes remettre en ordre les enveloppes après la session pour entraîner leur mémoire.
+
+## Objets spécifiques scénario v2
+- [ ] Piano-alphabet (stickers A–Z sur 26 touches blanches, voir `props_and_assets` dans le YAML)
+- [ ] Portrait (cadre) pour cacher le QR WIN (voir Archives)
+- [ ] QR WIN imprimé (scotch repositionnable)
+
+## Extensions modulaires (option)
+- [ ] Station bonus (voir `stations/`)
+- [ ] Chroniqueur (caméra/smartphone)
+- [ ] Récompenses (stickers, diplômes, décorations)
+
+
+> Astuce : range chaque pièce avec son numéro de station. Prépare un backup QR WIN dans la boîte MJ (voir YAML). Les enfants peuvent eux-mêmes remettre en ordre les enveloppes après la session pour entraîner leur mémoire.

kit-maitre-du-jeu/distribution-des-roles.md

@@ -1,24 +1,24 @@
-# Distribution des rôles
 
-Ce kit est calibré pour 6 à 14 enfants. Adapte le nombre de rôles selon l’énergie du groupe et la durée du flux (60–90 minutes).
+# Distribution des rôles (version canon Zacus)
 
-## Rôles principaux (6 enfants)
-1. **Chef de piste** (1 enfant) : lit les indices, relie les stations, annonce les hypothèses.
-2. **Chronométreur** : surveille le temps, annonce les transitions (station suivante, synthèse finale).
-3. **Livre d’enquête** : note les preuves, reprend les éléments audio et chronologiques.
-4. **Analyste technique** : manipule les codes, observe les gants, manipule les supports numériques.
-5. **Témoin narrateur** : raconte les éléments à voix haute pour structurer l’histoire.
-6. **Gardien des objets** : garde les cartes importantes, reporte les objets déplacés.
+Ce kit est calibré pour 6 à 14 enfants (voir aussi `_generated/roles.md`). Adapte le nombre de rôles selon l’énergie du groupe et la durée (60–90 minutes).
 
-## Rôles additionnels (ajoute jusqu’à 8 enfants)
-- **Détective des émotions** : écoute les impressions des autres et propose un résumé humain.
-- **Cartographe** : dessine un plan hypothétique (stations, chronologie, chemins).
-- **Archiviste** : organise les logs et classe les preuves selon la timeline.
-- **Ambassadeur** : questionne chaque station à la fin pour assurer que rien n’a été oublié.
+## Rôles principaux
+- **Chef de piste** : centralise les indices, relit la timeline, annonce les hypothèses.
+- **Chronométreur** : marque les phases (exploration, synthèse, accusation).
+- **Analyste technique** : gère les codes et les puzzles logiques.
+- **Archiviste** : organise les preuves (empreintes, logs, mobile).
+- **Témoin narrateur** : redonne les consignes anti-chaos et raconte.
+- **Gardien des objets** : protège les enveloppes, badges et fiches.
 
-## Rotation & avatars (jusqu’à 14 enfants)
-- Divise le groupe en deux équipes complémentaires (ex. : équipe « logique » vs équipe « intuition ») puis permute les rôles toutes les 20 min.
-- Prévoyez un rôle « journaliste » : enregistre les déclarations finales et écrit la synthèse.
-- Pour les plus petits (6–8 ans), garde deux stations actives à la fois et guide-les vers un rôle central (chef + chronométreur), les autres observant ou aidant à ranger.
+## Rôles optionnels
+- **Détective des émotions** : remet le calme si besoin.
+- **Cartographe** : trace le parcours des stations.
+- **Ambassadeur** : valide que rien n’a été oublié.
+- **Journaliste** : consigne la conclusion finale.
 
-> Astuce : affiche une carte des rôles imprimée près du tableau blanc pour que chacun sache quand prendre la parole ou passer le relais.
+## Rotation & variantes (jusqu’à 14 enfants)
+- Divise le groupe en deux équipes (ex. : logique vs intuition) puis permute les rôles toutes les 20 min.
+- Pour les plus petits (6–8 ans), privilégie chef + chronométreur, les autres observant ou aidant à ranger.
+
+> Astuce : affiche une carte des rôles imprimée près du tableau blanc pour que chacun sache quand prendre la parole ou passer le relais.

kit-maitre-du-jeu/export/pdf/README.md

@@ -1,8 +1,52 @@
-# Exports PDF — Kit Maître du jeu
 
-Ce dossier accueille les versions PDF prêtes à imprimer des documents du kit MJ.
+---
+# 🖨️ Exports PDF – Kit MJ Zacus
 
-Recommandations:
-- nommer les fichiers avec une version (`v1`, `v2`, ...),
-- garder une correspondance claire avec les sources Markdown,
-- ajouter une entrée dans `CHANGELOG.md` lors d'un ajout/modification.
+![Imprimante](https://media.giphy.com/media/3o7TKzQ5p2bQw3gQyA/giphy.gif)
+
+---
+
+## 📝 Description
+
+Tous les PDF prêts à imprimer pour transformer ta session Zacus en show : guides, scripts, solutions, supports de stations, et plus encore.
+
+> *"Si tu imprimes tout, tu es prêt pour le mode MJ Pro !"*
+
+---
+
+## 📦 Contenu du dossier
+
+- Fichiers PDF (guides, scripts, solutions, supports stations, et bonus)
+
+---
+
+## 🚀 Mode d’emploi (impression sans stress)
+
+1. Repère les fichiers dont tu as besoin (ou imprime tout, soyons fous)
+2. Clique sur « Imprimer » (ou crie « Ctrl+P » pour l’effet dramatique)
+3. Prépare les feuilles, les ciseaux, et le scotch (optionnel : paillettes)
+
+> *"Si l’imprimante fait des siennes, c’est normal. C’est le boss final du kit Zacus."*
+
+---
+
+## 🤝 Contribuer
+
+Les contributions sont bienvenues ! Les PDF les plus funs seront mis en avant.
+Merci de lire [../../../CONTRIBUTING.md](../../../CONTRIBUTING.md) avant toute PR.
+
+---
+
+## 🧑‍🎓 Licence
+
+- **Contenu créatif** : CC BY-NC 4.0 (`../../../LICENSE-CONTENT.md`)
+
+---
+
+## 👤 Contact
+
+Pour toute question, astuce d’impression, ou bug d’imprimante, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)
+
+> *"Ce dossier a survécu à 3 imprimantes, 2 toners vides, et 1 chat. 100% validé par la team Zacus."*
+---

kit-maitre-du-jeu/guide-anti-chaos.md

@@ -1,18 +1,23 @@
-# Guide anti-chaos
 
-Ce dossier contient les règles pour garder l’énergie (6–14 enfants) concentrée pendant 60–90 minutes.
+# Guide anti-chaos (scénario canon zacus_v2.yaml)
+
+Ce guide s’applique à une session de 6–14 enfants, 105 minutes, 2 actes, 3 stations, QR WIN, finale éthique.
 
 ## Règles simples
-1. **Un micro à la fois** : un enfant parle, tous les autres sont en écoute active. Si l’énergie monte trop, fais une ronde silencieuse de 10 secondes.
-2. **Indices verrouillés** : on ne dévoile pas d’indices officiels avant la validation du rôle « chef de piste ». Les objets restent dans leurs enveloppes tant que le rôle ne fait pas de « décompte ». 
-3. **Points de repos** : à 30 min et 55 min, propose une pause éclair (respiration, eau, petite danse). Ça évite les éclats de voix.
+1. **Un micro à la fois** : un enfant parle, les autres écoutent activement. Si l’énergie monte trop, fais une ronde silencieuse de 10 secondes.
+2. **Indices verrouillés** : on ne dévoile pas d’indices avant validation du chef de piste. Objets et QR restent cachés tant que la séquence n’est pas validée.
+3. **Points de repos** : à chaque changement d’acte ou de station, propose une pause éclair (respiration, eau, mini-danse).
 
 ## Interactions structurelles
-- Donne un signal sonore (timbre, cloche) pour marquer la transition d’une station à une autre.
-- Pour éviter les chamailleries, désigne une « personne calme » par station : elle remarque si le groupe s’énerve et rappelle doucement les règles.
+- Donne un signal sonore (timbre, cloche) pour marquer la transition d’une station à l’autre.
+- Désigne une « personne calme » par station pour rappeler les règles si besoin.
+- Prévois un backup QR WIN MJ en cas de bug matériel.
 
 ## Réactions rapides
-- Si deux enfants parlent en même temps, demande-leur de lever la main ; le premier à lever la main répond.
-- Si un enfant est largué, invite-le à dessiner son hypothèse sur la fiche d’enquête ou à poser une question « pourquoi ? » à l’équipe.
+- Si deux enfants parlent en même temps, demande-leur de lever la main ; le premier répond.
+- Si un enfant décroche, invite-le à dessiner son hypothèse ou à poser une question « pourquoi ? » à l’équipe.
 
-> Astuce : les enfants peuvent inventer un cri de code (« Zacus ! ») pour signaler qu’ils ont besoin d’un indice, ce qui évite de parler plus fort.
+## Esprit Zacus
+Le vrai test est l’éthique : stabilité, calme, coopération. Félicite le groupe pour chaque réussite collective, pas individuelle.
+
+> Astuce : les enfants peuvent inventer un cri de code (« Zacus ! ») pour demander un indice sans crier. Prévois un feedback positif à chaque étape clé.

kit-maitre-du-jeu/plan-stations-et-mise-en-place.md

@@ -1,30 +1,34 @@
-# Plan des stations & mise en place
+# Plan des stations & mise en place (version canon Zacus v2)
 
-## Objectif : 4 stations prêtes à recevoir 6–14 enfants pour 60–90 minutes.
+> ⚡ Le Media Kit ESP32 gère les feedbacks, transitions et QR WIN. Le MJ peut se concentrer sur l’animation et la gestion des ions turbulents !
+## Rituels de mise en place
+> Astuce : prépare un sac « rechargement » avec des copies supplémentaires des indices les plus manipulés (carte, note, code) pour gagner du temps entre deux groupes. Si un électron perd le nord, rappelle-lui que même les ions font parfois demi-tour !
 
-### 1. Atelier des ondes
-- Place la partition inversée (code 1-4-3) sur un porte-texte et ajoute un casque ou une carte son.
-- Prépare un indice tactile : un ruban magnétique qui relie les notes.
-- Indication clé : la réponse est obtenue en lisant les chiffres à l’envers.
 
-### 2. Salle des archives
-- Affiche un faux journal de recherche avec un log horodaté, flouté sauf une ligne sur Lila Caron.
-- Prépare un mini puzzle papier où les enfants replacent les coups de téléphone pour reconstituer la timeline.
-- Cache un QR code menant au fichier audio `game/prompts/audio/incident.md` (optionnel).
+# Plan des stations & mise en place (version canon Zacus v2)
 
-### 3. Bureau du Professeur
-- Colle une note effacée, un stylo, une empreinte de gant (imprimée sur un calque) et un message codé.
-- Ajoute une loupe ou un papier millimétré pour que les enfants scrutent les traces.
-- Note : la porte doit rester fermée (sauf si la mission demande un accès rapide).
+## Objectif : 3 stations principales, 6–14 enfants, 105 minutes (voir `_generated/stations.md` et `game/scenarios/zacus_v2.yaml`)
 
-### 4. Carnet du labo secret
-- Prépare un carnet à spirales avec l’entrée finale décrivant le mobile (« je ne veux pas que l’Auréole devienne un jouet »).
-- Ajoute un flacon de liquide bleu (étiquette « prototype ») et une fiche « preuve » pour noter la goute et son reflet.
+### 1. Atelier des Ondes (Acte 1)
+- Installer la zone avec un support audio (casque ou haut-parleur) et un dispositif pour produire un LA 440 Hz stable (tuner, appli, générateur).
+- Prévoir un feedback visuel (LED, écran, témoin) si possible.
+- Clé : la stabilité du LA 440 Hz valide l’étape 1 (voir clue YAML).
+
+### 2. Zone 4 — Studio de Résonance (Acte 2)
+- Installer un piano-alphabet : 26 stickers A–Z sur les touches blanches (ordre physique = stickers, pas musical).
+- Prévoir la séquence à jouer : L-E-F-O-U (5 notes, voir YAML).
+- Clé : validation par observation MJ, puis passage à l’étape Archives.
+
+### 3. Salle des Archives (Acte 2)
+- Préparer un portrait (cadre) derrière lequel sera caché le QR WIN imprimé (scotch repositionnable).
+- Prévoir un espace pour scanner le QR (tablette, smartphone, backup MJ).
+- Clé : QR WIN = validation finale, accès Media Hub.
 
 ## Rituels de mise en place
-- Numérote chaque station et place une petite lumière (LED ou bougie LED) sur la table.
-- Vérifie que toutes les enveloppes sont scellées : cela empêche les enfants d’ouvrir trop de cartes d’un coup.
-- Pose les cartes de rôle près de l’accueil et un chronomètre visible.
-- Place le scénario `game/scenarios/zacus_v1.yaml` sur la table maître pour la consultation rapide.
+- Numéroter chaque station, placer une lumière (LED/bougie LED) sur chaque table.
+- Vérifier que toutes les enveloppes sont scellées (indices, objets).
+- Poser les cartes de rôle près de l’accueil et un chronomètre visible.
+- Placer le scénario canon (`game/scenarios/zacus_v2.yaml`) sur la table MJ.
+- Prévoir un backup QR WIN dans la boîte MJ (voir YAML).
 
-> Astuce : prépare un sac « rechargement » avec des copies supplémentaires des indices les plus manipulés (carte, note, code) pour gagner du temps entre deux groupes.
+> Astuce : prépare un sac « rechargement » avec des copies supplémentaires des indices les plus manipulés (carte, note, code) pour gagner du temps entre deux groupes.

kit-maitre-du-jeu/script-minute-par-minute.md

@@ -1,33 +1,38 @@
-# Script minute-par-minute
+# Script minute-par-minute (scénario canon zacus_v2.yaml)
 
-> Version prête à jouer pour 6 à 14 enfants, 60–90 minutes.
+> ⚡ Le Media Kit ESP32 automatise les étapes, feedbacks et finale. Le MJ n’a plus qu’à jongler avec les ions et les blagues quantiques !
+## Avant l'accueil (10 min)
++ Vérifie que le Media Kit ESP32 est bien branché (sinon, menace-le de le remplacer par un tube à vide).
+> Astuce : si le temps manque, accélère la transition entre les actes et utilise les indices audio courts du YAML. Si un enfant demande « c’est quoi un ion ? », réponds « c’est un électron qui a trop fait la fête ! »
+
+# Script minute-par-minute (scénario canon zacus_v2.yaml)
+
+> Version prête à jouer pour 6 à 14 enfants, 105 minutes, 2 actes, 3 stations, QR WIN, finale éthique.
 
 ## Avant l'accueil (10 min)
-- Allume les lampes nommées « labo » et place visuellement le plateau central, les cartes de zones et les enveloppes de station.
-- Vérifie que les badges détective sont prêts, que les indices imprimés sont dans les enveloppes et que les cartes audio (QR ou lien) sont accessibles.
-- Lance une musique d’ambiance scientifique discrète (option portable) et ajuste la lumière pour laisser l’ombre sur les stations.
+- Allume les lampes « labo », place le plateau central, les enveloppes de station, le piano-alphabet (stickers A–Z), le portrait QR WIN.
+- Vérifie badges détective, indices imprimés, supports audio (QR ou lien), backup QR WIN MJ.
+- Lance une musique d’ambiance scientifique discrète.
 
 ## 00:00 – 00:10 : Accueil & immersion
-- Rassemble les enfants et présente la mission : « Professeur Zacus a disparu, il ne répond plus depuis son dernier message. Vous êtes l’équipe d’enquête du Campus.".
-- Donne les badges, répartis les rôles (chef de piste, expert matériel, mémoire) et lis l’intro audio/texte de `game/prompts/audio/intro.md`.
-- Explique les règles anti-chaos (voir `guide-anti-chaos.md`) : un leader parle à la fois, on partage les indices, on note tout dans la fiche d’enquête.
+- Présente la mission : « Le Professeur Zacus a disparu après une alerte cryptée. U-SON dérive. Vous devez stabiliser la référence LA 440 Hz, respecter la règle de Zone 4, puis trouver la clé finale. »
+- Donne les badges, répartis les rôles (voir distribution-des-roles.md), lis l’intro audio (voir YAML).
+- Explique les règles anti-chaos (voir guide-anti-chaos.md).
 
-## 00:10 – 00:35 : Exploration & indices
-- Les enfants circulent entre les stations : panneaux « Atelier chimie », « Salle des prototypes », « Bureau du Professeur », « Carnet de labo ». Chaque station présente un indice de type numérique, spatial, logique ou narratif (voir `plan-stations-et-mise-en-place.md`).
-- Supporte la recherche en donnant des « j’ai besoin d’un indice » quand ils tournent en rond, en prononçant une question fermée (« Le coupable était-il dans le bureau ? ») et en redirigeant la discussion.
-- Note les décisions sur la fiche d’enquête (printable). Encourage les échanges rapides : 5 minutes par station puis rotation libre selon énergie du groupe.
+## 00:10 – 00:45 : Acte 1 — Atelier des Ondes (LA 440)
+- Objectif : produire un LA 440 Hz stable (feedback visuel/audio, validation MJ).
+- Si réussite : passage à l’acte 2, audio de transition (voir YAML).
 
-## 00:35 – 00:65 : Synthèse & décodages
-- Regroupe tout le monde et relis les éléments clés. Relance l’audio `game/prompts/audio/incident.md` pour rappeler le déclencheur (perte de données, message effacé).
-- Ouvre la résolution du puzzle principal : les enfants doivent combiner codes, alibis et objets pour rendre cohérent un tableau suspect.
-- Si le groupe est rapide, distribue deux sous-pistes : (1) reconstituer la méthode (documents et appareils) et (2) déterminer le mobile (motivation). En cas de blocage, propose un « indice verrou » tiré du `canon` de `game/scenarios/zacus_v1.yaml`.
+## 00:45 – 01:20 : Acte 2 — Zone 4 (piano LEFOU)
+- Objectif : jouer la séquence L-E-F-O-U sur le piano-alphabet (validation MJ, indices audio si besoin).
+- Si réussite : révélation de la destination Archives, audio d’indice (voir YAML).
 
-## 00:65 – 00:80 : Mise en accusation et révélations
-- Invite chaque équipe à proposer une conclusion : qui, comment, pourquoi. Demande un argumentaire solide, puis joue l’audio `game/prompts/audio/accusation.md` pour simuler l’arrivée du professeur ou d’un témoin.
-- Si la conclusion ne colle pas, remobilise la piste clé (preuve unique). Sinon, confirme avec l’audio `game/prompts/audio/solution.md` et révèle la chronologie (voir `solution-complete.md`).
+## 01:20 – 01:35 : Salle des Archives (QR WIN)
+- Objectif : trouver et scanner le QR WIN caché derrière le portrait (validation finale, accès Media Hub).
+- Prévoir backup QR WIN MJ si besoin.
 
-## 00:80 – 00:90 : Debrief & récompenses
-- Lis la révélation finale et l’épilogue dans `solution-complete.md`. Remercie les enfants, remets leur badge spécial et partage l’anecdote du Professeur Zacus.
-- Propose un moment libre : dessiner la scène finale ou écrire une note pour l’équipe suivante.
+## 01:35 – 01:45 : Finale & débrief
+- Lis la révélation finale (voir solution-complete.md et YAML) : Zacus réapparaît, félicite l’équipe pour sa stabilité, son calme et son éthique.
+- Remercie les enfants, remets leur badge spécial, propose un moment libre (dessin, anecdote, feedback).
 
-> Astuce : tu peux couper le script à 60 minutes en accélérant l’étape de synthèse et en sautant l’audio d’introduction externe.
+> Astuce : si le temps manque, accélère la transition entre les actes et utilise les indices audio courts du YAML.

kit-maitre-du-jeu/solution-complete.md

@@ -1,16 +1,24 @@
-# Solution complète
+# Solution complète (scénario canon zacus_v2.yaml)
 
-## coupable unique
-Lila Caron, assistante en chef des capteurs et gardienne des prototypes, est la seule à porter les gants signalés dans la salle des archives, la seule présente à 18h15 dans la salle des prototypes et la seule à avoir physiquement touché la baie de transfert après le message du professeur.
+> ⚡ Le Media Kit ESP32 valide chaque étape, joue les jingles et ouvre le Media Hub. Même un électron fatigué peut réussir la mission !
++Et si un ion s’échappe, c’est juste pour vérifier la conductivité du groupe !
 
-## mobile + méthode
-Lila a repéré la dérive éthique que représenterait la diffusion de l’Auréole. Elle a saboté les capteurs pour générer la hausse de température, a verrouillé les accès et a envoyé un faux message d’urgence pour que l’équipe se focalise sur les alarmes. Elle a ensuite laissé des indices clairs mais ciblés (code 1-4-3, note partielle, empreinte) pour conduire les détectives vers sa vérité : un message de protection, pas une conspiration.
+# Solution complète (scénario canon zacus_v2.yaml)
 
-## preuve et chronologie
-1. **Puzzle sonore (Atelier des ondes)** : la partition renversée renvoie au code 1-4-3, l’empreinte du professeur sur la baie de transfert et l’alarme ciblée. Cela indique qu’un humain manipulateur (pas un accident) a verrouillé la porte.
-2. **Logs (Salle des archives)** : les relevés exposent la présence de Lila juste après la transmission de Zacus et la suppression d’un enregistrement. Les autres rôles ont des alibis nets et aucune signature sur la baie.
-3. **Note du tableau (Bureau du Professeur)** : le message effacé et la formule incomplète montrent qu’elle a utilisé ses doigts (gants) pour brouiller l’écriture et qu’elle connaissait bien le calendrier de Zacus.
-4. **Mobile moral** : la dernière phrase écrite dans le carnet secret exprime son refus d’abandonner l’expérience aux militaires. En accusant Lila, toute la suite devient cohérente : elle protège la science en dissimulant le professeur.
+## Nature de l’épreuve
+Il n’y a pas de coupable unique : la disparition de Zacus est un test d’éthique et de coopération. L’équipe doit stabiliser U-SON (LA 440 Hz), respecter la règle de Zone 4 (piano LEFOU), puis trouver et scanner le QR WIN aux Archives.
 
-## épilogue
-Zacus réapparaît au moment de l’accusation finale, silencieux dans les archives. Il remercie les enfants : sans le temps gagné par Lila, il n’aurait pas pu stabiliser l’Auréole et canaliser l’énergie vers la bibliothèque des étudiants plutôt que le secteur militaire.
+## Étapes et preuves
+1. **Atelier des Ondes** : produire un LA 440 Hz stable (preuve : stabilité validée par feedback visuel/audio, passage à l’étape 2).
+2. **Zone 4 — Studio de Résonance** : jouer la séquence L-E-F-O-U sur le piano-alphabet (preuve : validation par observation MJ, passage à l’étape Archives).
+3. **Salle des Archives** : trouver et scanner le QR WIN caché derrière le portrait (preuve : QR scanné, accès Media Hub).
+
+## Sens et morale
+Le test n’est pas la vitesse, mais la coopération, la précision et le calme. U-SON ne doit pas devenir un objet de panique. L’équipe gagne si elle fait preuve de stabilité, de respect des règles et d’entraide.
+
+## Finale
+Zacus réapparaît : ce n’était pas une punition mais un test d’éthique. L’équipe a protégé le prototype par sa méthode et son calme. Accès final au Media Hub.
+
+## Backups et sécurité
+- Un QR WIN de secours est disponible dans la boîte MJ (voir YAML).
+- Si la caméra ne fonctionne pas, le MJ peut valider manuellement la réussite.

kit-maitre-du-jeu/stations/README.md

@@ -6,5 +6,55 @@ Chaque station doit être :
 - variée (observation / logique / manipulation)
 - cohérente avec la solution finale (pas de contradictions)
 
-Fichiers :
-- `station-01.md`, `station-02.md`, etc.
+---
+# 🕹️ Stations Zacus – Le Parcours du Funk
+
+![Station](https://media.giphy.com/media/3o7TKtnuHOHHUjR38Y/giphy.gif)
+
+---
+
+## 📝 Description
+
+Des modules de jeu prêts à brancher pour transformer chaque station en mini-aventure : énigmes, défis, surprises, et groove garanti.
+
+> *"Une station, c’est comme un solo de guitare : ça doit marquer les esprits !"*
+
+---
+
+## 📦 Contenu du dossier
+
+- 4 à 8 stations types (modulaires, remixables à l’infini)
+- Fichiers d’énigmes, scripts, matériel, et punchlines
+
+---
+
+## 🚀 Mode d’emploi (MJ, version funk)
+
+1. Sélectionne tes stations préférées (ou tire au hasard pour le chaos)
+2. Imprime les supports, prépare le matos, et chauffe l’ambiance
+3. Lance les défis, distribue les points, et improvise si besoin
+
+> *"Si une station bug, invente une règle. Si tout bug, c’est que la fête est réussie !"*
+
+---
+
+## 🤝 Contribuer
+
+Envie d’ajouter ta station ? Les contributions fun sont prioritaires.
+Merci de lire [../../CONTRIBUTING.md](../../CONTRIBUTING.md) avant toute PR.
+
+---
+
+## 🧑‍🎓 Licence
+
+- **Contenu créatif** : CC BY-NC 4.0 (`../../LICENSE-CONTENT.md`)
+
+---
+
+## 👤 Contact
+
+Pour toute question, idée de station, ou bug improbable, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)
+
+> *"Testé sur MJ fatigué, enfants survoltés, et robots en panne d’idées. 100% groove validé."*
+---

printables/README.md

@@ -1,6 +1,16 @@
-# Printables
+---
+# Zacus Printables
+
+---
+
+## 📝 Description
+
+Supports imprimables pour le jeu Zacus : indices, cartes, invitations, accessoires.
+
+---
+
+## 📦 Contenu du dossier
 
-Organisation :
 - `src/` = sources éditables
 - `export/pdf/` = prêts à imprimer
 - `export/png/` = previews versionnés
@@ -8,6 +18,8 @@ Organisation :
   - `fiche-enquete/` = actes de la fiche d'enquête
   - `personnages/` = cartes personnages
   - `zones/` = visuels des zones
+- Invitations : `invitations/src/` et `invitations/export/{pdf,png}/`
+- Ordre d’impression : voir `ordre-dimpression.md`
 
 Convention de nommage recommandée :
 - `a6` / `a5` / `a4`
@@ -19,9 +31,28 @@ Exemples :
 - `carte-indice-a6-v2.pdf`
 - `regles-1-page-a4-v1.pdf`
 
-Ordre d’impression : voir `ordre-dimpression.md`.
+---
 
-## État actuel
-- Structure alignée : `src/`, `export/pdf/`, `export/png/`.
-- Préviews PNG regroupées dans `export/png/` par sous-dossiers thématiques.
-- Invitations initialisées : `invitations/src/` et `invitations/export/{pdf,png}/`.
+## 🚀 Installation & usage
+
+Voir les guides d’export et de génération dans `../tools/images/` et les manifestes dans `manifests/`.
+
+---
+
+## 🤝 Contribuer
+
+Les contributions sont bienvenues !
+Merci de lire [../CONTRIBUTING.md](../CONTRIBUTING.md) avant toute PR.
+
+---
+
+## 🧑‍🎓 Licence
+
+- **Contenu créatif** : CC BY-NC 4.0 (`../LICENSE-CONTENT.md`)
+
+---
+
+## 👤 Contact
+
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)

tools/images/README.md

@@ -1,16 +1,45 @@
-# Printable image generator
+---
+# Zacus Tools – Printable Image Generator
 
-Creates PNG drafts for each printable asset with the OpenAI Images API.
+---
 
-## Requirements
-- `OPENAI_API_KEY` in your environment.
-- Dependencies installed in `.venv` (`PyYAML`, `openai`).
+## 📝 Description
 
-## Run
+Génère des ébauches PNG pour chaque asset imprimable à partir du manifeste, via l’API OpenAI Images.
+
+---
+
+## 🚀 Installation & usage
+
+Pré-requis :
+- `OPENAI_API_KEY` dans l’environnement
+- Dépendances dans `.venv` (`PyYAML`, `openai`)
+
+Exécution :
 ```sh
 PYTHON=.venv/bin/python tools/images/generate_printables.py \
   --manifest printables/manifests/zacus_v1_printables.yaml
 ```
-Add `--force` to regenerate outputs even if files already exist.
+Ajouter `--force` pour régénérer même si les fichiers existent déjà.
 
-Outputs land in `printables/export/png/zacus_v1/` and mirror the IDs from the manifest.
+Les sorties sont dans `printables/export/png/zacus_v1/` et reprennent les IDs du manifeste.
+
+---
+
+## 🤝 Contribuer
+
+Les contributions sont bienvenues !
+Merci de lire [../../CONTRIBUTING.md](../../CONTRIBUTING.md) avant toute PR.
+
+---
+
+## 🧑‍🎓 Licence
+
+- **Code** : MIT (`../../LICENSE`)
+
+---
+
+## 👤 Contact
+
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)

tools/test/README.md

@@ -1,15 +1,22 @@
-# Test Toolbox
+---
+# Zacus Tools – Test Toolbox
 
-Lightweight test entrypoints for Zacus.
+---
 
-## Prerequisites
+## 📝 Description
 
+Entrées de test légères pour le projet Zacus (validation, hardware, CI, simulation UART).
+
+---
+
+## 🚀 Installation & usage
+
+Pré-requis :
 - `python3`
-- Optional: `pyyaml` for content checks (`pip install pyyaml`)
-- Optional: `pyserial` for USB serial tests (`pip install pyserial`)
-
-## Quick commands
+- (Optionnel) `pyyaml` pour les checks de contenu (`pip install pyyaml`)
+- (Optionnel) `pyserial` pour les tests USB série (`pip install pyserial`)
 
+Commandes rapides :
 ```bash
 bash tools/test/run_content_checks.sh
 python3 tools/test/run_serial_suite.py --list-suites
@@ -19,39 +26,44 @@ bash tools/test/run_rc_gate.sh --sprint s1 --port-esp32 /dev/cu.SLAB_USBtoUART
 bash tools/test/hw_now.sh
 ```
 
-## Hardware modes
+Modes hardware :
+- Sans hardware : utiliser `--allow-no-hardware` pour retour `SKIP` (exit 0)
+- Avec hardware : connecter les adaptateurs USB-UART avant les suites
 
-- No hardware / CI laptop:
-  - use `--allow-no-hardware` on serial tools to return `SKIP` with exit code `0`.
-- With hardware:
-  - connect USB-UART adapters before running serial suites.
-
-## Minimal wiring for UI Link simulation
-
-UART 3.3V only:
-
-- ESP32 TX (GPIO22) -> adapter RX
-- ESP32 RX (GPIO19) -> adapter TX
+Simulation UI Link (UART 3.3V) :
+- ESP32 TX (GPIO22) -> RX adaptateur
+- ESP32 RX (GPIO19) -> TX adaptateur
 - GND -> GND
-- Baud: `19200`
-
-Then run:
-
+- Baud : `19200`
 ```bash
 python3 tools/test/ui_link_sim.py --port /dev/ttyUSB0 --script "NEXT:click,OK:long"
 ```
 
-## Wrapper path inside firmware workspace
+Wrappers pour firmware :
+- `hardware/firmware/tools/test/` (forward vers ce dossier)
 
-For teams working from `hardware/firmware`, wrappers are provided under:
+Helpers RC cycle :
+- Sprint gate : `bash tools/test/run_rc_gate.sh --sprint s1..s5 ...`
+- Live one-shot : `bash tools/test/hw_now.sh`
+- Board seed : `bash hardware/firmware/tools/dev/rc_execution_seed.sh`
+- Board source of truth : `hardware/firmware/docs/RC_FINAL_BOARD.md`
 
-- `hardware/firmware/tools/test/`
+---
 
-They forward to this canonical `tools/test` implementation.
+## 🤝 Contribuer
 
-## RC cycle helpers
+Les contributions sont bienvenues !
+Merci de lire [../../CONTRIBUTING.md](../../CONTRIBUTING.md) avant toute PR.
 
-- Sprint gate runner: `bash tools/test/run_rc_gate.sh --sprint s1..s5 ...`
-- Live one-shot (upload + smoke + s1+s2): `bash tools/test/hw_now.sh`
-- Board seed script: `bash hardware/firmware/tools/dev/rc_execution_seed.sh`
-- RC board source of truth: `hardware/firmware/docs/RC_FINAL_BOARD.md`
+---
+
+## 🧑‍🎓 Licence
+
+- **Code** : MIT (`../../LICENSE`)
+
+---
+
+## 👤 Contact
+
+Pour toute question ou suggestion, ouvre une issue GitHub ou contacte l’auteur principal :
+- Clément SAILLANT — [github.com/electron-rare](https://github.com/electron-rare)