BrettKinny · Oct 27, 2026 · Jul 12, 2026 · Jul 16, 2026 · Aug 11, 2026 · Sep 12, 2026
diff --git a/.config.yaml.template b/.config.yaml.template
@@ -82,6 +82,10 @@ ASR:
     # Optional decoder bias — short list of canonical phrases improves
     # recall on rare names. Keep under ~200 chars to avoid prompt bleed.
     initial_prompt: null
+    # Bias the decoder toward the wake-name so it stops coming back as
+    # Jody / Donny / Duddy (#164). null disables. Needs faster-whisper >= 1.0
+    # (ignored with a warning on older builds).
+    hotwords: <ROBOT_NAME>
   SenseVoiceOnnx:
     # int8 sherpa-onnx SenseVoiceSmall — no PyTorch, lighter for Pi-class hosts
     # (#135). Opt-in: set selected_module.ASR: SenseVoiceOnnx to use it.

diff --git a/.env.example b/.env.example
@@ -91,6 +91,16 @@ PORT=8081
 # Same key as above works if your provider supports vision models.
 # VISION_API_KEY=sk-or-v1-...
 
+# Keep camera frames and room audio on the LAN (dotty-behaviour). When set,
+# any VLM / audio-caption / narrative URL that is not loopback or a private
+# address is disabled at startup instead of falling back to the cloud
+# default, and weather + calendar fetches are switched off. Point the VLM at
+# a local OpenAI-compatible vision model to keep the camera working:
+# DOTTY_LOCAL_ONLY=1
+# VLM_API_URL=http://127.0.0.1:8080/v1/chat/completions
+# VLM_MODEL=<your-local-vision-model>
+# VLM_API_KEY=local   # any non-empty value; local servers ignore it
+
 # --- Google Calendar integration (optional) ---
 
 # Comma-separated Google Calendar IDs for context injection.

diff --git a/.github/workflows/firmware-release.yml b/.github/workflows/firmware-release.yml
@@ -1,6 +1,12 @@
 # Build StackChan firmware and publish a GitHub Release.
 #
-# Triggered by tags matching fw-v* (e.g. fw-v1.0.0).
+# Manual only (2026-10-21): the firmware's server address is compiled in
+# (CONFIG_OTA_URL), so these binaries only work on the network they were
+# built for. Nothing here stops that: a manual run publishes whatever
+# CONFIG_OTA_URL the pinned source has, so don't run it until #190 makes a
+# prebuilt that can be pointed at any server, then restore the fw-v* tag
+# trigger. A manual run names the release after the ref it runs on, so run
+# it from a tag.
 # Uses the Espressif IDF Docker container to build the ESP32-S3 firmware,
 # then attaches the binaries + SHA256 checksums to a GitHub Release.
 #
@@ -11,9 +17,7 @@
 name: Firmware Release
 
 on:
-  push:
-    tags:
-      - 'fw-v*'
+  workflow_dispatch:
 
 permissions:
   contents: write

diff --git a/.gitignore b/.gitignore
@@ -38,6 +38,23 @@ sbom-server.json
 htmlcov/
 .pytest_cache/
 
+# Local UAT evidence. Keep compact manifests/results/draft issue summaries
+# visible for selective review, but never offer raw household media, event
+# streams, health snapshots, or container logs for an accidental commit.
+/uat-sessions/**/video/
+/uat-sessions/**/clips/
+/uat-sessions/**/logs/
+/uat-sessions/**/ndjson/
+/uat-sessions/**/snapshots/
+
+# Generated audit/session outputs. These can contain machine-local paths,
+# prompts, or deployment observations; regenerate or curate before publishing.
+/AUDIT-REPORT.md
+/audit-draft-issues.md
+/pi-session-*.html
+# Session-id file a test writes when a DB path is ":memory:".
+*.ses
+
 # Frontend build deps for the dashboard's vendored Tailwind bundle.
 # package.json + tailwind.config.js are committed; build artifacts and
 # the npm install state are not. Re-run `npm install && npm run build:css`

diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -27,7 +27,7 @@ The voice path runs through a single LLM provider — `PiVoiceLLM`, selected via
 
 ```
                  StackChan hardware → configured persona
-                   │  ESP32-S3, xiaozhi firmware (built from m5stack/StackChan source)
+                   │  ESP32-S3, xiaozhi firmware (pinned BrettKinny/StackChan@dotty fork)
                    │  WiFi / WebSocket (Xiaozhi protocol)
                    ▼
                  xiaozhi-esp32-server (Docker)
@@ -197,7 +197,8 @@ For hardware specs, protocol details, model internals, latent capabilities, and
 
 - xiaozhi-esp32-server: https://github.com/xinnan-tech/xiaozhi-esp32-server
 - xiaozhi-esp32 firmware (upstream): https://github.com/78/xiaozhi-esp32
-- StackChan (hardware + firmware patches): https://github.com/m5stack/StackChan
+- StackChan upstream (hardware + base firmware): https://github.com/m5stack/StackChan
+- Dotty firmware fork (the pinned build source): https://github.com/BrettKinny/StackChan/tree/dotty
 - Emotion protocol: https://xiaozhi.dev/en/docs/development/emotion/
 
 ## Agent skills

diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md
@@ -13,11 +13,16 @@ For protocol wire formats see `docs/protocols.md`.
 
 | Component | Current Version | Protocol / Interface | Breaking Change Policy |
 |---|---|---|---|
-| StackChan firmware (m5stack/StackChan v1.2.4) | v1.2.4 | Xiaozhi WebSocket protocol, MCP over WS (JSON-RPC 2.0) | Pin firmware to a known-good build; do not OTA-update without verifying server compatibility first |
+| StackChan firmware (`BrettKinny/StackChan@dotty`) | `fw-v1.3.3` release; submodule `969c2b2` | Xiaozhi WebSocket protocol, MCP over WS (JSON-RPC 2.0), StateManager event contract | Build the pinned submodule; do not substitute the official upstream tree or OTA-update without coordinated verification |
 | xiaozhi-esp32-server (local build) | `xiaozhi-esp32-server-piper:local` | Custom LLM provider API, `.config.yaml` schema, Xiaozhi WS server | Rebuild image only after checking upstream changelog for provider API or config schema changes |
-| dotty-pi (pi agent) | `dotty-pi:0.1.0` | pi RPC (JSONL over stdio), the five `dotty-pi-ext` voice tools | Pin the image tag; pi-version or model changes need end-to-end cutover testing |
+| dotty-pi (pi agent) | `dotty-pi:0.1.0` | pi RPC (JSONL over stdio), the seven `dotty-pi-ext` voice tools | Pin the image tag; pi-version or model changes need end-to-end cutover testing |
 | dotty-behaviour | `dotty-behaviour:0.1.0` | HTTP API (`/api/perception/*`, `/api/vision/*`, `/api/audio/*`, `/health`) | Endpoint signatures stable; perception event-schema changes require firmware + xiaozhi review |
-| bridge.py (dashboard) | unversioned (HEAD) | `/ui` dashboard, `/admin/*`, `/health` | Dashboard/admin service only post-#36; admin route changes require updating dashboard callers |
+| bridge.py (dashboard) | `dotty-bridge:0.1.0` image from repo HEAD | `/ui` dashboard, `/admin/*`, `/health` | Dashboard/admin service only post-#36; admin route changes require updating dashboard callers |
+
+The public `fw-v1.3.3` superproject tag (commit `24a009c`, 2026-07-12) is the
+current coordinated release pointer. It pins firmware submodule `969c2b2` and
+the matching server-side patches. Draft PRs and a dirty submodule are not a
+released compatibility set.
 
 ## What counts as a breaking change
 
@@ -42,27 +47,28 @@ Any of the following require coordinated updates across components:
 
 ## Versioning strategy
 
-No formal versioning is adopted yet (tracked in
-[ROADMAP.md](ROADMAP.md#community-wishlist) under "Firmware/server
-compatibility matrix"). When adopted, the plan is:
+The repo uses separate tag namespaces:
+
+- `server-vX.Y.Z` for server-only release milestones.
+- `fw-vX.Y.Z` for coordinated firmware release pointers in this superproject.
 
-- Separate tag namespaces: `server-vX.Y.Z` and `fw-vX.Y.Z`.
-- This matrix will document which server versions are compatible with which
-  firmware versions.
-- The bridge will carry its own version once it moves to a tagged release
-  cadence.
+Container image tags remain `0.1.0` today and are not sufficient by themselves
+to identify the exact source revision; retain the Git commit/tag alongside a
+deployment record.
 
 ## Upgrade guidance
 
 1. **Check this matrix first.** Confirm the component you are upgrading is
    compatible with the versions of the other components you are running.
-2. **Back up before upgrading.** Run `scripts/backup.sh` (or the equivalent
-   manual steps) to snapshot config, persona files, and bridge state.
+2. **Back up before upgrading.** Manually snapshot `.env`, rendered
+   `data/.config.yaml`, persona/household files, `brain.db` (including WAL/SHM
+   companions), and the bridge state directory. This repo does not currently
+   ship an automated backup script.
 3. **Upgrade one component at a time.** Validate with a health check
    (`curl http://<XIAOZHI_HOST>:8090/health` and `:8081/health`) plus a live
    voice turn before moving to the next component.
-4. **Tail logs during validation.** Watch both the xiaozhi-server container
-   logs and the bridge journal simultaneously to catch mismatches early.
+4. **Tail logs during validation.** Watch the xiaozhi-server, dotty-pi,
+   dotty-behaviour, and bridge container logs together to catch mismatches.
 5. **Roll back if broken.** Restore from the backup taken in step 2 and
    revert to the previous image or binary.
 
@@ -96,7 +102,11 @@ Server and firmware are versioned independently:
 The docs live as plain markdown under `docs/` and render on GitHub directly —
 there is no separate docs-site build to deploy.
 
-GitHub Actions handles image builds and artifact publishing from the tag.
+Pushing a tag does not trigger any build or publish. The firmware release
+workflow (`firmware-release.yml`) is manual-only, and no firmware binaries are
+published at the moment, because the server address is compiled in; a
+portable prebuilt is tracked in
+[#190](https://github.com/BrettKinny/dotty-stackchan/issues/190).
 
 ### Compatibility matrix updates
 
@@ -106,4 +116,4 @@ versions work with which firmware versions.
 
 ---
 
-Last verified: 2026-05-22.
+Last verified against the repository and `fw-v1.3.3` pin: 2026-07-16.
diff --git a/Dockerfile b/Dockerfile
@@ -1,7 +1,28 @@
 # Pinned 2026-05-17 from :server_0.9.3
 FROM ghcr.io/xinnan-tech/xiaozhi-esp32-server@sha256:3accd82a7d1a6c01c58f32f6199400a11655d607780b80219493123dedbb347e
 
-RUN pip install --no-cache-dir piper-tts scipy numpy mido faster-whisper sherpa-onnx==1.13.2
+# Versions pinned to the image that passed the 2026-10-20 A/V run; an unpinned
+# rebuild could otherwise change the Whisper stack underneath WhisperLocal.
+RUN pip install --no-cache-dir piper-tts==1.8.0 scipy==1.15.3 numpy==1.26.4 mido==1.3.3 \
+        faster-whisper==1.2.1 ctranslate2==4.8.3 sherpa-onnx==1.13.2
+
+# CTranslate2 (faster-whisper) dlopens libcublas.so.12 and cuDNN by name and
+# doesn't look inside the pip CUDA wheels, so WhisperLocal on device=cuda fails
+# every utterance with "libcublas.so.12 is not found" without this.
+ENV LD_LIBRARY_PATH=/usr/local/lib/python3.10/site-packages/nvidia/cublas/lib:/usr/local/lib/python3.10/site-packages/nvidia/cudnn/lib
+
+# Patch upstream TTS consumers and the audio sender to treat explicitly
+# registered server-push sentence IDs as independent from chat-turn
+# stale-message arbitration (#104).
+COPY scripts/patch-tts-server-push.py /tmp/patch-tts-server-push.py
+RUN python /tmp/patch-tts-server-push.py \
+        /opt/xiaozhi-esp32-server/core/providers/tts \
+        /opt/xiaozhi-esp32-server/core/handle/sendAudioHandle.py
+
+# Keep ~1.2 s of audio from before the VAD fires (upstream ~0.6 s), so a soft
+# first word still reaches ASR.
+COPY scripts/patch-asr-preroll.py /tmp/patch-asr-preroll.py
+RUN python /tmp/patch-asr-preroll.py /opt/xiaozhi-esp32-server/core/providers/asr/base.py
 
 # fluidsynth + General MIDI soundfont for runtime rendering of dance/song MIDI
 # files to Opus. Installed as the LAST layer so iteration on Python deps above

diff --git a/Makefile b/Makefile
@@ -221,9 +221,10 @@ setup: _preflight-compose ## Interactive first-run wizard (re-runnable; remember
 	 echo -e "$(GREEN)$(BOLD)Setup complete.$(RESET)"; \
 	 echo ""; \
 	 echo "Next steps:"; \
-	 echo "  1. Flash the StackChan firmware (see SETUP.md or m5stack/StackChan repo)."; \
-	 echo "  2. In the device's Advanced Options, set the OTA URL to:"; \
-	 echo "       http://$$XIAOZHI_HOST:8003/xiaozhi/ota/"; \
+	 echo "  1. Build and flash StackChan firmware with this compiled setting:"; \
+	 echo "       CONFIG_OTA_URL=\"http://$$XIAOZHI_HOST:8003/xiaozhi/ota/\""; \
+	 echo "     See SETUP.md. The on-device Settings app has no OTA URL editor."; \
+	 echo "  2. Provision the robot's 2.4 GHz Wi-Fi using its displayed setup flow."; \
 	 echo "  3. Run 'make doctor' to verify everything is healthy."; \
 	 echo ""