From dd6df1fa691767f9eb4b1a8a4befbccf611997cf Mon Sep 17 00:00:00 2001
From: Claude Worker claude2 <claude2@MacBookPro.lan>
Date: Thu, 11 Jun 2026 03:07:14 +0200
Subject: [PATCH] docs(ir): example IR + authoring gap note

---
 .../story/runtime3/EXAMPLE_LOCAL_PUZZLES.json | 60 +++++++++++++++++++
 specs/ZACUS_RUNTIME_3_SPEC.md                 | 26 ++++++++
 2 files changed, 86 insertions(+)
 create mode 100644 hardware/firmware/data/story/runtime3/EXAMPLE_LOCAL_PUZZLES.json

diff --git a/hardware/firmware/data/story/runtime3/EXAMPLE_LOCAL_PUZZLES.json b/hardware/firmware/data/story/runtime3/EXAMPLE_LOCAL_PUZZLES.json
new file mode 100644
index 0000000..593adef
--- /dev/null
+++ b/hardware/firmware/data/story/runtime3/EXAMPLE_LOCAL_PUZZLES.json
@@ -0,0 +1,60 @@
+{
+  "schema_version": "zacus.runtime3.v1",
+  "scenario": {
+    "id": "EXAMPLE_LOCAL_PUZZLES",
+    "version": 3,
+    "title": "Exemple — enigmes locales P1 son / P3 QR",
+    "entry_step_id": "STEP_QR"
+  },
+  "steps": [
+    {
+      "id": "STEP_QR",
+      "scene_id": "SCENE_QR_DETECTOR",
+      "scene": {
+        "title": "MISSION QR",
+        "subtitle": "scannez les codes dans l'ordre",
+        "symbol": "RUN",
+        "effect": "gyro"
+      },
+      "puzzle": {
+        "id": 3,
+        "type": "qr",
+        "codes": ["zacus-qr-1", "zacus-qr-2"],
+        "fragment": [5]
+      },
+      "transitions": [
+        { "event_type": "unlock", "target_step_id": "STEP_SOUND" }
+      ]
+    },
+    {
+      "id": "STEP_SOUND",
+      "scene_id": "SCENE_LA_DETECTOR",
+      "scene": {
+        "title": "U-SON",
+        "subtitle": "jouez la melodie do re mi fa",
+        "symbol": "440",
+        "effect": "glitch"
+      },
+      "puzzle": {
+        "id": 1,
+        "type": "sound",
+        "melody": [60, 62, 64, 65],
+        "tolerance": 2,
+        "fragment": [1, 2]
+      },
+      "transitions": [
+        { "event_type": "unlock", "target_step_id": "STEP_CALME" }
+      ]
+    },
+    {
+      "id": "STEP_CALME",
+      "scene_id": "SCENE_FIN",
+      "scene": {
+        "title": "CODE ASSEMBLE",
+        "subtitle": "125",
+        "effect": "pulse"
+      },
+      "transitions": []
+    }
+  ]
+}
diff --git a/specs/ZACUS_RUNTIME_3_SPEC.md b/specs/ZACUS_RUNTIME_3_SPEC.md
index 1e4fda7..29621c0 100644
--- a/specs/ZACUS_RUNTIME_3_SPEC.md
+++ b/specs/ZACUS_RUNTIME_3_SPEC.md
@@ -139,3 +139,29 @@ effect). All fields optional.
 
 - `title` <= 47 chars, `subtitle` <= 63, `symbol` <= 15.
 - `effect`: `pulse` (default) | `glitch` | `gyro` | `none`.
+
+### État de l'authoring et chaînon manquant
+
+Au stade actuel, les champs `puzzle`/`scene` sont **portés de bout en bout
+côté exécution** : le compilateur (`runtime3_common.py`) les transmet
+verbatim de l'IR au firmware, qui arme les énigmes locales (P1 son / P3 QR)
+et pilote l'écran. Un IR de référence exerçant ces champs est fourni :
+`hardware/firmware/data/story/runtime3/EXAMPLE_LOCAL_PUZZLES.json` (validé
+par `validate_runtime3_document`, testé en bout-à-bout via `POST /game/scenario`
+puis `POST /game/step`).
+
+**En revanche, l'authoring ne les génère pas encore.** Les scénarios
+canoniques (`game/scenarios/zacus_v2.yaml`, `zacus_v3.yaml`) décrivent les
+mêmes énigmes via un vocabulaire distinct — blocs `solution:`
+(`frequency_hz`, `qr_payload`, `sequence`) et `scene: SCENE_X` (référence
+d'ID d'écran, pas l'objet d'affichage) — qui **n'est pas traduit** vers les
+objets `puzzle`/`scene` de l'IR. L'IR embarqué `DEFAULT.json` ne contient
+donc aucun champ `puzzle`/`scene`.
+
+Chaînon à construire (tâche dédiée) : enseigner au compilateur la
+correspondance `solution:` → `puzzle:` (ex. `frequency_hz`+`tolerance_hz`
+→ `type:sound`/`melody`/`tolerance` ; `qr_payload`/`sequence`
+→ `type:qr`/`codes` ; allocation des `fragment` de code par énigme), et
+exposer un objet `scene` d'affichage dans l'authoring. En attendant,
+pousser directement un IR comme `EXAMPLE_LOCAL_PUZZLES.json` reste le moyen
+d'exercer les énigmes locales depuis la webUI/gateway.