chore(firmware): root live runner wrapper alignment and docs sync

hardware/firmware/README.md

@@ -63,10 +63,14 @@ USB console monitoring uses `115200`. ESP8266 internal UI link SoftwareSerial st
 
 ```sh
 ./tools/dev/run_matrix_and_smoke.sh
+# or from repo root:
+./hw_now.sh
 ```
 
 `run_matrix_and_smoke.sh` ensures PlatformIO caches land under `$HOME/.platformio` (via `PLATFORMIO_CORE_DIR`) rather than inside the repo.
 Before smoke it shows `⚠️ BRANCHE L’USB MAINTENANT ⚠️` three times, then waits for Enter while listing ports every 15s.
+Each run writes deterministic artifacts under `artifacts/rc_live/<timestamp>/` (`summary.json`, `summary.md`, `ports_resolve.json`, `ui_link.log`, per-step logs).
+The runner resolves macOS CP2102 by LOCATION (`20-6.1.1` ESP32, `20-6.1.2` ESP8266 USB), then enforces a dedicated `UI_LINK_STATUS connected=1` gate on ESP32.
 
 Environment overrides:
 

hardware/firmware/docs/HW_NOW.md

@@ -1,54 +1,36 @@
 Run now
 =======
 
-1. Vérifiez que les deux boards sont câblées : ESP32 Audio Kit A252 et ESP8266 OLED (NodeMCU).
-2. Lancez le script de validation canonique :  
-   `bash tools/test/hw_now.sh` ou `bash tools/test/hw_now_esp32_esp8266.sh` si vous êtes déjà dans `hardware/firmware`.  
-   Le script :
-   - détecte automatiquement les ports série (avec `tools/dev/serial_smoke.py` pour la reconnaissance)
-   - compile et upload les firmwares PlatformIO (`esp32dev` + `esp8266_oled`)
-   - exécute des smokes `serial_smoke.py --role auto` puis AP fallback et collecte le verdict
-   - stocke les traces dans `artifacts/rc_live/<TIMESTAMP>/` (avec `steps.tsv`) et `logs/hw_now_<TIMESTAMP>.log`.
-3. À la fin, lisez les derniers blocs `[PASS]` / `[SKIP]` / `[fail]` dans le log pour détecter les échecs, puis consultez `steps.tsv` si nécessaire.
-4. Si quelque chose échoue, relancez `pio device monitor -e <env>` sur le port correspondant (ESP32 ou ESP8266) pour récupérer les consoles : `pio device monitor -e <env> --port <PORT> --monitor-speed 19200`.
+1. Depuis la racine du repo, lancez `./hw_now.sh`.
+   - équivalent depuis `hardware/firmware`: `./tools/test/hw_now.sh`
+2. Le runner canonique est `tools/dev/run_matrix_and_smoke.sh`:
+   - build matrix PlatformIO (ou skip si artefacts déjà présents)
+   - gate USB locale: `⚠️ BRANCHE L’USB MAINTENANT ⚠️` x3 + attente Enter + listing ports toutes les 15s
+   - résolution de ports via `tools/test/resolve_ports.py` (macOS CP2102: `20-6.1.1=esp32`, `20-6.1.2=esp8266_usb`)
+   - smoke strict USB à `115200` (ESP32 + ESP8266 monitor-only)
+   - gate UI link dédiée: commande ESP32 `UI_LINK_STATUS`, attendu `connected=1`
+3. Les logs/artifacts sont toujours produits, même en FAIL:
+   - `artifacts/rc_live/<TIMESTAMP>/summary.json`
+   - `artifacts/rc_live/<TIMESTAMP>/summary.md`
+   - `artifacts/rc_live/<TIMESTAMP>/ports_resolve.json`
+   - `artifacts/rc_live/<TIMESTAMP>/ui_link.log`
+   - `logs/run_matrix_and_smoke_<TIMESTAMP>.log`
+4. Politique de verdict:
+   - `PASS`: toutes les étapes critiques passent
+   - `FAIL`: port unresolved, panic/reboot/binary junk, smoke fail, ou `UI_LINK_STATUS connected=0`
+   - `SKIP`: aucune carte détectée et mode non strict (pas de faux PASS)
 
-Câblage minimal
-----------------
+Rappels baud
+------------
 
-- Reliez les GND ensembles (ESP32 + ESP8266 + PC). Sans masse commune, les UARTs ne fonctionnent pas.
-- Pour les UARTs de debug, utilisez la paire GPIO1 (TX0) / GPIO3 (RX0) de l’ESP32 et connectez-la au RX/TX du NodeMCU (cross TX/RX).
-- Si vous préférez monitorer le lien UI avec GPIO22/19, gardez les fils séparés du bus de l’écran et connectez-les à un adaptateur USB-TTL.
-- Une seule connexion par board suffit, le script n’a besoin que des port `/dev/cu.*` affectés automatiquement.
+- Console USB PlatformIO/monitor: `115200`
+- Lien interne ESP8266 SoftwareSerial vers ESP32: `19200` (non utilisé pour le monitor USB)
 
-Commandes sans script
-----------------------
+Diagnostic rapide
+-----------------
 
-1. Build + upload manuel :
-   ```
-   pio run -e esp32dev
-   pio run -e esp8266_oled
-   pio run -e esp32dev -t upload --upload-port <PORT_ESP32>
-   pio run -e esp8266_oled -t upload --upload-port <PORT_ESP8266>
-   ```
-2. Smokes série :
-   ```
-   python3 tools/dev/serial_smoke.py --role esp32 --port <PORT_ESP32> --baud 19200 --wait-port 20
-   python3 tools/dev/serial_smoke.py --role esp8266 --port <PORT_ESP8266> --baud 19200 --wait-port 20
-   python3 tools/dev/serial_smoke.py --role auto --baud 19200 --wait-port 20
-   ```
-3. Indicateur UI link : ouvrez `pio device monitor` sur l’ESP32 et cherchez une ligne `UI_LINK` ou `connected=1`.
-4. Status AP fallback : `curl --max-time 5 -sS http://192.168.4.1/api/status` (timeout court pour ne pas bloquer l’exécution).
-
-Logs et artefacts
-------------------
-
-- Les runs `tools/test/hw_now.sh` et `hw_now_esp32_esp8266.sh` déposent les sorties dans `logs/hw_now_<TIMESTAMP>.log`.
-- Le dossier `artifacts/rc_live/<TIMESTAMP>/` contient un `steps.tsv` et un `ports_resolve.json` détaillant les ports détectés.
-- Conservez ces fichiers pour la traçabilité ou pour transmettre des logs à la QA / au RC gate.
-
-Interpréter PASS / FAIL / SKIP
--------------------------------
-
-- **PASS** : chaque étape attendue s’est terminée avec un `[ok]` dans `artifacts/hw_now/<TIMESTAMP>/hw_now.log`, la board répond au `PING`, l’AP fallback répond.
-- **FAIL** : un `pio run`, un `upload`, ou l’un des `serial_smoke` retourne `[fail]`; l’étape correspondant remonte la ligne d’erreur dans le log.
-- **SKIP** : seules les vérifications non critiques (ex. AP fallback absent) émettent un `SKIP`; cela ne bloque pas mais indique que la vérif n’a pas pu être faite. Toutes les étapes critiques échouent avec `FAIL`.
+- Vérifier les consoles USB:
+  - `pio device monitor -e esp32dev --port <PORT_ESP32> --monitor-speed 115200`
+  - `pio device monitor -e esp8266_oled --port <PORT_ESP8266> --monitor-speed 115200`
+- Forcer l'échec sans hardware (QA stricte):
+  - `ZACUS_REQUIRE_HW=1 ./tools/dev/run_matrix_and_smoke.sh`

hardware/firmware/docs/QUICKSTART.md

@@ -40,6 +40,8 @@ Attendu:
 ```sh
 ./tools/dev/bootstrap_local.sh
 ./tools/dev/run_matrix_and_smoke.sh
+# depuis la racine du repo:
+./hw_now.sh
 make fast-esp32 ESP32_PORT=<PORT_ESP32>
 make fast-ui-oled UI_OLED_PORT=<PORT_ESP8266>
 make fast-ui-tft UI_TFT_PORT=<PORT_RP2040>
@@ -60,6 +62,8 @@ Baud separation a retenir:
 
 Le script force `PLATFORMIO_CORE_DIR=$HOME/.platformio` pour que les caches PlatformIO restent en dehors du repo.
 Avant le smoke, il affiche `⚠️ BRANCHE L’USB MAINTENANT ⚠️` 3 fois, puis attend Enter en listant les ports toutes les 15s.
+Chaque run dépose `summary.json`, `summary.md`, `ports_resolve.json` et `ui_link.log` dans `artifacts/rc_live/<timestamp>/`.
+Le verdict UI link est strict: `UI_LINK_STATUS connected=1` attendu sur l'ESP32.
 
 Par défaut, la séquence smoke tolère l’absence de matériel et termine avec un code 0 quand rien n’est détecté.
 
@@ -73,7 +77,7 @@ Variantes d'environnement :
 - `ZACUS_ENV="esp32dev esp8266_oled" ./tools/dev/run_matrix_and_smoke.sh` — cible un sous-ensemble d’environnements.
 - `ZACUS_FORCE_BUILD=1 ./tools/dev/run_matrix_and_smoke.sh` — force la rebuild même si les artefacts existent déjà.
 
-Le script affiche un résumé final : `Build status` (OK ou SKIPPED) et `Smoke status` (OK/SKIP) avec la commande exacte.
+Le script affiche un résumé final (`Build/Port/Smoke/UI link`) et écrit le même verdict dans `artifacts/rc_live/<timestamp>/summary.json`.
 
 ## 4.6) Local dev cockpit
 

hardware/firmware/tools/dev/run_matrix_and_smoke.sh

@@ -263,7 +263,7 @@ resolve_live_ports() {
   printf '[step] %s\n' "${resolver_cmd[*]}" | tee -a "$RUN_LOG" "$resolve_log"
   set +e
   local resolve_json
-  resolve_json="$(${resolver_cmd[@]} 2>>"$resolve_log")"
+  resolve_json="$("${resolver_cmd[@]}" 2>>"$resolve_log")"
   local rc=$?
   set -e
   printf '%s\n' "$resolve_json" >> "$resolve_log"

hardware/firmware/tools/test/hw_now.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+FW_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$FW_ROOT"
+
+exec bash "./tools/dev/run_matrix_and_smoke.sh" "$@"

hw_now.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$ROOT/hardware/firmware"
+
+exec bash "./tools/dev/run_matrix_and_smoke.sh" "$@"