feat(plip): stage files onto SD via /game/file

/game/file only wrote SPIFFS (960 KB, too small for a voice pack). A
path prefixed sd/ (or /sdcard/) now routes to the microSD: the card is
mounted on demand (audio_ensure_sd, independent of hook state) and the
parent dir is created. MAX_BODY 256->512 KB so full say() hints fit
(streamed in 2 KB chunks, RAM-safe). Enable FATFS LFN_HEAP so >8.3
filenames work (greet_0142738200.wav etc). Validated: 40-sample FR
voice pack staged to /sdcard/voice on the bench PLIP (960 MB card).

idf_zacus/components/game_endpoint/CMakeLists.txt

@@ -22,4 +22,5 @@ idf_component_register(
         p7_coffre
         p5_morse
         p6_nfc
+        npc_engine
 )

idf_zacus/components/game_endpoint/game_endpoint.c

@@ -27,6 +27,7 @@
 #include "nvs_flash.h"
 
 #include "hints_client.h"
+#include "npc_engine.h"
 #include "scenario_mesh.h"
 #include "puzzle_binding.h"
 #include "local_puzzles.h"
@@ -807,6 +808,16 @@ esp_err_t game_endpoint_apply_step(const char *step_id,
     strncpy(s_current_step_id, step_id, sizeof(s_current_step_id) - 1);
     s_current_step_id[sizeof(s_current_step_id) - 1] = '\0';
 
+    // Sync the NPC/hints engine (and, through it, the voice gateway) with the
+    // scene this step enters. This is what makes the phone NPCs hint on — and
+    // scripted calls auto-ring for — the current scene, regardless of whether
+    // the step was driven by the local game loop or an external POST /game/step.
+    // Best-effort: notify is async + server-side idempotent and never blocks
+    // the step change. Steps with no scene_id (or an unknown one) are skipped.
+    if (s_current_scene.scene_id[0] != '\0') {
+        (void) npc_engine_set_scene_by_id(s_current_scene.scene_id, 0);
+    }
+
     // P7 coffre: fire the actuator when the final win step is reached.
     // p7_coffre_unlock() is a no-op stub when CONFIG_ZACUS_P7_COFFRE_ENABLE=n.
     if (strcmp(step_id, "STEP_FINAL_WIN") == 0) {

idf_zacus/components/game_endpoint/include/puzzle_binding.h

@@ -55,6 +55,7 @@ esp_err_t puzzle_binding_from_ir(const char *ir_json, const char *step_id,
 #define SB_MAX_TITLE    48
 #define SB_MAX_SUBTITLE 64
 #define SB_MAX_SYMBOL   16
+#define SB_MAX_SCENE_ID 40
 
 typedef enum {
     SB_FX_PULSE = 0,   // default (original SceneEffect::kPulse)
@@ -65,6 +66,8 @@ typedef enum {
 
 typedef struct {
     bool present;                     // step has a scene object
+    char scene_id[SB_MAX_SCENE_ID];   // canonical SCENE_* id (sibling of step id;
+                                      // set even when no display scene object)
     char title[SB_MAX_TITLE];
     char subtitle[SB_MAX_SUBTITLE];
     char symbol[SB_MAX_SYMBOL];

idf_zacus/components/game_endpoint/puzzle_binding.c

@@ -239,9 +239,15 @@ esp_err_t scene_binding_from_ir(const char *ir_json, const char *step_id,
     }
     if (!step) { cJSON_Delete(root); return ESP_ERR_NOT_FOUND; }
 
+    // Canonical scene id (SCENE_*), sibling of the step "id". Captured
+    // unconditionally so npc_engine / the voice gateway can be synced even
+    // on steps that carry no display "scene" object.
+    copy_scene_str(out->scene_id, sizeof(out->scene_id),
+                   cJSON_GetObjectItemCaseSensitive(step, "scene_id"));
+
     const cJSON *scene = cJSON_GetObjectItemCaseSensitive(step, "scene");
     if (!scene || !cJSON_IsObject(scene)) {
-        // No scene — present stays false, ESP_OK.
+        // No scene object — present stays false, ESP_OK (scene_id may be set).
         cJSON_Delete(root);
         return ESP_OK;
     }

idf_zacus/components/npc_engine/CMakeLists.txt

@@ -22,6 +22,7 @@ idf_component_register(
     REQUIRES
         media_manager
         hints_client
+        esp_http_client
         esp_timer
         esp_system
         nvs_flash

idf_zacus/components/npc_engine/include/npc_engine.h

@@ -169,6 +169,16 @@ esp_err_t npc_engine_trigger_cue(const char *cue_id);
 // and primes the stuck timer.
 esp_err_t npc_engine_set_step(uint8_t step_id, uint32_t expected_duration_ms);
 
+// Same bridge as npc_engine_set_step(), but keyed by the canonical scene
+// string id (e.g. "SCENE_WARNING") rather than its numeric index. Resolves
+// the id against the engine's internal scene table and forwards to
+// npc_engine_set_step(). Lets the game endpoint sync the NPC/hints engine
+// (and the voice gateway) straight from the scenario IR's `scene_id`.
+// Returns ESP_ERR_NOT_FOUND when the id matches no known scene (no notify
+// is sent in that case), ESP_ERR_INVALID_ARG on a NULL/empty id.
+esp_err_t npc_engine_set_scene_by_id(const char *scene_id,
+                                     uint32_t expected_duration_ms);
+
 // Request a hint for `puzzle_id` at escalation `level` (0..3). The engine
 // invokes `cb` with the resulting text. The current implementation is a
 // LOCAL STUB: it returns a hardcoded French placeholder synchronously.
@@ -184,6 +194,12 @@ const npc_state_t *npc_engine_state(void);
 // Thin wrapper kept here to give callers a single npc_engine_* surface.
 esp_err_t npc_engine_set_group_profile(const char *profile);
 
+// Point the engine at the voice gateway (tools/zacus-gateway). On each scene
+// change the engine POSTs the active SCENE_* to {base_url}/game/step?scene=… so
+// the phone NPCs disguise that scene's hint. Best-effort; pass NULL/"" to
+// disable. `token` is sent as a Bearer header (gateway require_token).
+void npc_engine_set_gateway(const char *base_url, const char *token);
+
 // Write the active puzzle id (e.g. "SCENE_LA_DETECTOR") into `out`,
 // truncated to `cap` bytes (NUL-terminated). Falls back to "SCENE_NPC"
 // when no scene is active or the engine is not initialised so callers

idf_zacus/components/npc_engine/npc_engine.c

@@ -17,16 +17,78 @@
 #include "npc_engine.h"
 
 #include <stdio.h>
+#include <stdlib.h>
 #include <string.h>
 
 #include "esp_err.h"
+#include "esp_http_client.h"
 #include "esp_log.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
 
 #include "media_manager.h"
 #include "hints_client.h"
 
 static const char *TAG = "npc_engine";
 
+// Voice gateway (tools/zacus-gateway) — we push the active SCENE_* to it at each
+// scene change so the phone NPCs disguise THIS scene's hint. Best-effort, set by
+// npc_engine_set_gateway(); empty = disabled (no-op, e.g. CI / dry runs).
+static char s_gw_url[128]   = {0};
+static char s_gw_token[80]  = {0};
+
+void npc_engine_set_gateway(const char *base_url, const char *token) {
+    if (base_url) snprintf(s_gw_url, sizeof(s_gw_url), "%s", base_url);
+    if (token)    snprintf(s_gw_token, sizeof(s_gw_token), "%s", token);
+}
+
+// One-shot worker: POST {gateway}/game/step?scene=<scene> then self-delete.
+// Runs on its own task so a slow/unreachable gateway NEVER stalls the scene
+// transition (the game must not lag 2 s on every scene change if the gateway is
+// offline). `arg` is a heap copy of the scene, freed here. Best-effort.
+static void gw_notify_task(void *arg) {
+    char *scene = (char *) arg;
+    char url[256];
+    snprintf(url, sizeof(url), "%s/game/step?scene=%s", s_gw_url, scene);
+    esp_http_client_config_t cfg = {
+        .url = url,
+        .method = HTTP_METHOD_POST,
+        .timeout_ms = 2000,
+    };
+    esp_http_client_handle_t cli = esp_http_client_init(&cfg);
+    if (cli) {
+        if (s_gw_token[0]) {
+            char auth[112];
+            snprintf(auth, sizeof(auth), "Bearer %s", s_gw_token);
+            esp_http_client_set_header(cli, "Authorization", auth);
+        }
+        esp_err_t err = esp_http_client_perform(cli);
+        if (err != ESP_OK) {
+            ESP_LOGW(TAG, "gateway /game/step notify failed: %s", esp_err_to_name(err));
+        } else {
+            ESP_LOGI(TAG, "gateway scene -> %s (HTTP %d)", scene,
+                     esp_http_client_get_status_code(cli));
+        }
+        esp_http_client_cleanup(cli);
+    }
+    free(scene);
+    vTaskDelete(NULL);
+}
+
+// Fire-and-forget the gateway scene notification on a detached task so a scene
+// change is never blocked by the network. No-op if no gateway configured.
+static void notify_gateway_scene(const char *scene) {
+    if (!s_gw_url[0] || !scene || !scene[0]) return;
+    size_t n = strlen(scene) + 1;
+    char *copy = malloc(n);
+    if (!copy) return;
+    memcpy(copy, scene, n);
+    if (xTaskCreate(gw_notify_task, "gw_notify", 4096, copy, 3, NULL) != pdPASS) {
+        ESP_LOGW(TAG, "gw_notify task spawn failed");
+        free(copy);
+    }
+}
+
 // ─── Core: scene/trigger/mood lookup tables (verbatim Arduino) ──────────────
 
 static const char *const kSceneIds[] = {
@@ -372,10 +434,25 @@ esp_err_t npc_engine_set_step(uint8_t step_id, uint32_t expected_duration_ms) {
                      (unsigned) prev_scene, (unsigned) step_id);
         }
         (void) hints_client_puzzle_start(puzzle_id);
+        // Keep the voice gateway in sync so the phone NPCs hint on THIS scene.
+        notify_gateway_scene(puzzle_id);
     }
     return ESP_OK;
 }
 
+esp_err_t npc_engine_set_scene_by_id(const char *scene_id,
+                                     uint32_t expected_duration_ms) {
+    if (scene_id == NULL || scene_id[0] == '\0') return ESP_ERR_INVALID_ARG;
+    for (uint8_t i = 0; i < kSceneCount; i++) {
+        if (strcmp(scene_id, kSceneIds[i]) == 0) {
+            return npc_engine_set_step(i, expected_duration_ms);
+        }
+    }
+    ESP_LOGW(TAG, "set_scene_by_id: unknown scene \"%s\" (no kSceneIds match)",
+             scene_id);
+    return ESP_ERR_NOT_FOUND;
+}
+
 esp_err_t npc_engine_set_group_profile(const char *profile) {
     // Thin pass-through. hints_client validates the value and logs the
     // outcome. Kept on npc_engine so the rest of the firmware doesn't

idf_zacus/main/main.c

@@ -63,6 +63,12 @@
 // this to NVS so the field operator can repoint the firmware without a flash.
 #define ZACUS_HINTS_BASE_URL  "http://192.168.0.150:8302"
 
+// Voice gateway (tools/zacus-gateway) — the engine POSTs each scene change to
+// {URL}/game/step?scene=SCENE_* so the phone NPCs disguise that scene's hint.
+// Hardcoded for now like the URLs above — moves to NVS in the same follow-up.
+#define ZACUS_GATEWAY_BASE_URL  "http://192.168.0.175:8401"
+#define ZACUS_GATEWAY_TOKEN     "testtoken"
+
 // Slice 7: voice-bridge WebSocket on the MacStudio (Tailscale address).
 // Hardcoded here for the same reason as ZACUS_HINTS_BASE_URL — moves to
 // NVS in a follow-up slice. The bridge endpoint is documented in
@@ -530,6 +536,9 @@ void app_main(void) {
                 ESP_LOGE(TAG, "npc_engine_init failed: %s",
                          esp_err_to_name(npc_err));
             }
+            // Push each scene change to the voice gateway so the phone NPCs
+            // disguise the CURRENT scene's hint (best-effort, see main.c URL).
+            npc_engine_set_gateway(ZACUS_GATEWAY_BASE_URL, ZACUS_GATEWAY_TOKEN);
 
             // Slice 5: bring up the hints HTTP client (so npc_engine can
             // route hint requests through the real backend) and the voice

plip_voice/main/audio.c

@@ -137,6 +137,12 @@ static void ensure_sd_mounted(void)
     }
 }
 
+bool audio_ensure_sd(void)
+{
+    ensure_sd_mounted();
+    return s_sd_mounted;
+}
+
 /* ── WAV parser ──────────────────────────────────────────────────────────── */
 
 static esp_err_t parse_wav_header(const uint8_t *buf, size_t len, wav_info_t *out)
@@ -599,19 +605,14 @@ int audio_capture_wav(uint8_t *out, size_t out_max, int max_ms, int silence_ms)
     const int max_frames     = (max_ms     / 20);
     const int silence_frames = (silence_ms / 20);
 
-    /* VAD thresholds (raw S16). Tuned for the SLIC handset mic at +24 dB PGA:
-     * speech peaks ~5 % FS / RMS ~1-2 %, noise floor ~0.6 %. Onset must sit
-     * between (catch quiet speech), silence ABOVE the noise floor (so the turn
-     * ends when the caller stops instead of running to max_ms). */
-    /* Measured on the SLIC handset (DC-blocked): speech body sits ~1 % FS RMS
-     * with peaks ~18 %, noise floor ~0.3 %. The previous silence threshold
-     * (1.2 %) was ABOVE the speech body, so the recorder classified the
-     * caller's own voice as silence and cut the turn after ~0.6 s → empty STT.
-     * Onset must clear noise (3-frame sustained confirm also guards it); silence
-     * must sit between the noise floor and the speech body so the turn ends only
-     * on a real pause. */
-    const int32_t  vad_onset_rms_sq   = 450 * 450;   /* ~1.4% FS² — speech onset above noise */
-    const int32_t  vad_silence_rms_sq = 200 * 200;   /* ~0.6% FS² — below speech body, above noise floor */
+    /* Calibrated to the QUIET handset voice (DC-blocked: body 0.16-0.8 % FS RMS,
+     * loud syllables ~2-4 %, noise floor ~0.3 %). The old onset (1.4 %) NEVER
+     * triggered → "no sustained voice"; the old silence (0.6 %) sat ABOVE the
+     * body → cut mid-sentence. Now: onset catches a real syllable just above the
+     * floor (3-frame confirm guards clicks); silence sits just above the floor so
+     * the turn ends only on a true pause, holding the whole sentence. */
+    const int32_t  vad_onset_rms_sq   = 230 * 230;   /* ~0.70% FS² — quiet-voice onset */
+    const int32_t  vad_silence_rms_sq = 110 * 110;   /* ~0.34% FS² — just above noise floor */
 
     int  silent_frames = 0;
     int  total_frames  = 0;

plip_voice/main/audio.h

@@ -39,6 +39,12 @@ esp_err_t audio_play_async(const char *path);
 /* Stop current playback immediately. */
 esp_err_t audio_stop(void);
 
+/* Mount the microSD card at /sdcard on demand (best-effort, idempotent) and
+ * report whether it is mounted. Unlike playback, this does NOT depend on the
+ * hook state — it lets the REST layer stage a voice pack onto the SD while the
+ * handset is down. Returns true if /sdcard is usable. */
+bool audio_ensure_sd(void);
+
 /* True while the audio worker is playing a clip (tone/WAV). The conversation
  * LISTEN loop polls this to stay half-duplex: never capture while playing
  * (avoids the earpiece→mic feedback that saturated the line). */

plip_voice/main/conversation.c

@@ -47,7 +47,9 @@
 #define CAPTURE_MAX_IRAM    (128 * 1024)
 #define CAPTURE_MAX_MS_PSRAM  8000
 #define CAPTURE_MAX_MS_IRAM   4000
-#define CAPTURE_SILENCE_MS     600   /* end-of-speech VAD: shorter = snappier reply (was 800) */
+#define CAPTURE_SILENCE_MS     900   /* end-of-speech: needs to ride through brief
+                                      * mid-sentence pauses so a whole phrase is
+                                      * captured (quiet handset voice). 900 ms. */
 #define REPLY_POLL_MS          200   /* interval for checking hook during playback */
 #define REPLY_PLAYBACK_EXTRA_MS 500  /* safety margin added to computed WAV duration */
 #define BETWEEN_TURNS_MS       300   /* short pause between capture rounds */
@@ -124,6 +126,10 @@ static void enter_incoming_greet(void)
 {
     s_incoming_armed = false;
     phone_ring_stop();
+    slic_ring_stop();   /* belt-and-suspenders: kill the physical bell directly in
+                         * case phone.c's s_ringing flag desynced from slic.c's
+                         * (otherwise phone_ring_stop early-returns and the bell
+                         * keeps ringing through the answered call). */
     tones_stop();
     dialer_reset();
     s_offhook = true;

plip_voice/main/net.c

@@ -22,6 +22,7 @@
 #include <string.h>
 #include <stdio.h>
 #include <errno.h>
+#include <sys/stat.h>
 
 #include "audio.h"
 #include "tones.h"
@@ -53,7 +54,8 @@
 
 #define SPIFFS_LABEL  "storage"
 #define SPIFFS_BASE   "/spiffs"
-#define MAX_BODY      (256 * 1024)
+#define MAX_BODY      (512 * 1024)   /* streamed in 2 KB chunks → RAM-safe; raised
+                                        so full-length say() hint WAVs fit on SD */
 
 static volatile bool    s_connected  = false;
 static httpd_handle_t   s_httpd      = NULL;
@@ -209,14 +211,39 @@ static esp_err_t handle_file_post(httpd_req_t *req)
     if (req->content_len <= 0 || req->content_len > MAX_BODY)
         return send_json(req, "413 Payload Too Large", "{\"error\":\"too large\"}");
 
-    ensure_spiffs();
+    /* Route to the microSD when the path is sd-prefixed ("sd/…", "sdcard/…"
+     * or "/sdcard/…"); otherwise stage in SPIFFS (default). The SD is mounted
+     * on demand here so a voice pack can be staged without an off-hook play. */
+    const char *base;
+    const char *rel = fpath;
+    bool to_sd = false;
+    if      (strncmp(fpath, "sd/", 3) == 0)       { rel = fpath + 3; to_sd = true; }
+    else if (strncmp(fpath, "sdcard/", 7) == 0)   { rel = fpath + 7; to_sd = true; }
+    else if (strncmp(fpath, "/sdcard/", 8) == 0)  { rel = fpath + 8; to_sd = true; }
 
-    /* Build full SPIFFS path. */
-    char full[160];
-    if (fpath[0] == '/') {
-        snprintf(full, sizeof(full), "%s%s", SPIFFS_BASE, fpath);
+    if (to_sd) {
+        if (!audio_ensure_sd())
+            return send_json(req, "503 Service Unavailable", "{\"error\":\"no sd card\"}");
+        base = PLIP_SD_MOUNT;   /* "/sdcard" */
     } else {
-        snprintf(full, sizeof(full), "%s/%s", SPIFFS_BASE, fpath);
+        ensure_spiffs();
+        base = SPIFFS_BASE;
+    }
+    while (*rel == '/') rel++;   /* avoid a double slash when joining */
+
+    char full[192];
+    snprintf(full, sizeof(full), "%s/%s", base, rel);
+
+    /* Create the immediate parent dir (one level) so a pack can live in a
+     * subfolder like /sdcard/voice/<file>.wav — fopen won't create it. FAT
+     * supports mkdir; SPIFFS is flat so we only do this for the SD path. */
+    if (to_sd) {
+        char *slash = strrchr(full, '/');
+        if (slash && slash != full) {
+            *slash = '\0';
+            mkdir(full, 0775);   /* best-effort; ignore EEXIST */
+            *slash = '/';
+        }
     }
 
     FILE *f = fopen(full, "wb");

plip_voice/sdkconfig.defaults

@@ -52,3 +52,7 @@ CONFIG_PLIP_HOOK_ACTIVE_HIGH=y
 # Example: CONFIG_PLIP_GATEWAY_URL="http://192.168.0.175:8401"
 #          CONFIG_PLIP_GATEWAY_TOKEN="testtoken"
 # Default (Kconfig): http://192.168.0.50:8401 with empty token.
+
+# Long file names on the SD (voice sample pack uses >8.3 names)
+CONFIG_FATFS_LFN_HEAP=y
+CONFIG_FATFS_MAX_LFN=255