tirtc-device-builder 0.9.2 → 0.9.4

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Codex workflows for building and validating TiRTC device firmware across supported chip platforms.",
   "author": {
     "name": "TangeAI",

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 This project follows Semantic Versioning.
 
+## 0.9.4
+
+- Add a knowledge-only Waveshare ESP32-P4-WIFI6-Touch-LCD-3.5 package with
+  pinned source maps, media/resource lessons and explicit hardware/HIL limits.
+- Expose validated knowledge references for model candidates without granting
+  adapter reuse; allow unknown PCB revisions only in knowledge-only packages.
+- Add focused media/resource diagnosis guidance covering directional stream
+  contracts, WithCaps task cleanup, reserved codec ownership and UI cadence.
+- Test candidate discovery, unknown revisions and reference path boundaries.
+
+## 0.9.3
+
+- Pin ESP32 Device Kit 1.1.4 and use wildcard DNS plus HTTP probe redirects for
+  the local captive portal without misadvertising the HTML page as a DHCP
+  option 114 CAPPORT API.
+- Canonicalize ustar headers across GNU tar versions and require the release
+  workflow to match the rebuilt archive against the checksum pinned in the
+  release tag.
+- Keep every SoftAP prompt aligned with the `captive_portal: true` Hardware IR
+  contract, and include the reviewed knowledge-only ESP32-S3 board identities.
+
 ## 0.9.2
 
 - Pin ESP32 Device Kit 1.1.3 with captive portal discovery through DHCP option

package/README.md

@@ -12,7 +12,7 @@ H5/AI 的 ESP32-S3 托管模板、协议文档和 TiRTC SDK 已打包在独立
 
 - npm 包：[tirtc-device-builder](https://www.npmjs.com/package/tirtc-device-builder)
 - GitHub 仓库：[tangeai/tirtc-device-builder](https://github.com/tangeai/tirtc-device-builder)
-- ESP32 Device Kit：[kit-esp32s3-v1.1.3](https://github.com/tangeai/tirtc-device-builder/releases/tag/kit-esp32s3-v1.1.3)
+- ESP32 Device Kit：[kit-esp32s3-v1.1.4](https://github.com/tangeai/tirtc-device-builder/releases/tag/kit-esp32s3-v1.1.4)
 
 文档导航：
 
@@ -283,7 +283,7 @@ board-materials/
 | ESP-IDF | 5.5.x |
 | 自动安装版本 | ESP-IDF v5.5.4 |
 | TiRTC SDK | `espressif-esp32s3/2.3.0` |
-| ESP32 Device Kit | 1.1.3 |
+| ESP32 Device Kit | 1.1.4 |
 | Node.js | 18 或更高版本 |
 | 支持自动安装的系统 | Linux、WSL、macOS |
 | 原生 Windows | 使用 Espressif 官方安装器准备 ESP-IDF，再重新运行检查 |
@@ -392,7 +392,7 @@ Cline 当前还需要在 `Settings → Features → Enable Skills` 中启用实
 |---|---|
 | Agent Skill | 上表中所选目录下的 `tirtc-esp32-builder` |
 | 托管根目录 | `~/.tirtc-device-builder` |
-| Device Kit | `~/.tirtc-device-builder/kits/esp32s3/1.1.3` |
+| Device Kit | `~/.tirtc-device-builder/kits/esp32s3/1.1.4` |
 | ESP-IDF | `~/.tirtc-device-builder/esp-idf-v5.5.4` |
 | Espressif 工具 | `~/.tirtc-device-builder/espressif` |
 | 安装记录 | `~/.tirtc-device-builder/config.json` |
@@ -437,7 +437,7 @@ npx --yes tirtc-device-builder@latest setup esp32 --install \
 
 ```bash
 npx --yes tirtc-device-builder@latest setup esp32 --install \
-  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.3.tar.gz
+  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.4.tar.gz
 ```
 
 安装器仍会核对固定的 SHA-256、目录结构、清单和每个资源文件，不接受未经验证的同名压缩包。
@@ -652,7 +652,7 @@ bootloader、分区表和应用镜像；无需手工维护多条 `esptool.py`
 
 ### Wi-Fi 凭证和设备绑定
 
-SoftAP 是可选方案，不是接入前提。Hardware IR 要根据 BSP 的实际能力和产品要求，选择 SoftAP、BLE、SmartConfig、安全工厂/NVS 注入、不纳入版本控制的开发配置，或有文档的自定义方案。若选择 SoftAP，热点名必须以 `TiRTC-` 开头、使用开放认证（无需密码），AP 网关和配网页面地址固定为 `192.168.6.1`（`http://192.168.6.1`），并通过 DHCP Option 114、通配 DNS 和 HTTP 回退启用 captive portal 自动发现。系统没有自动弹窗时仍可手动打开该 HTTP 地址；HTTPS 不能透明重定向。这些值要写入 Hardware IR 并通过门禁；目标 WLAN 的 SSID 和密码仍不得写死在源码中。
+SoftAP 是可选方案，不是接入前提。Hardware IR 要根据 BSP 的实际能力和产品要求，选择 SoftAP、BLE、SmartConfig、安全工厂/NVS 注入、不纳入版本控制的开发配置，或有文档的自定义方案。若选择 SoftAP，热点名必须以 `TiRTC-` 开头、使用开放认证（无需密码），AP 网关和配网页面地址固定为 `192.168.6.1`（`http://192.168.6.1`），并通过通配 DNS 和 HTTP 回退启用 captive portal 自动发现。DHCP Option 114 只用于 RFC 8908 HTTPS/JSON API，不能指向本地 HTML 页面。系统没有自动弹窗时仍可手动打开该 HTTP 地址；HTTPS 不能透明重定向。这些值要写入 Hardware IR 并通过门禁；目标 WLAN 的 SSID 和密码仍不得写死在源码中。
 
 无论选择哪种方法，都要有当前 PCB/BSP 的支持证据，凭证不能进入 Git、源码或报告，并且要保留清除或重配入口。没有 SoftAP、但支持工厂 NVS 注入的设备同样可以接入。只要工程提交了明文密码，Hardware IR v2 门禁就会判为 `BLOCKED`。
 
@@ -820,7 +820,7 @@ npx --yes tirtc-device-builder@latest setup esp32 --install --force-skill
 
 ```bash
 npx --yes tirtc-device-builder@latest setup esp32 --install \
-  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.3.tar.gz
+  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.4.tar.gz
 ```
 
 安装器会校验 SHA-256 和内部文件清单。如果校验不一致，请重新获取官方 Release 附件，不要跳过校验。
@@ -932,25 +932,25 @@ python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
 ```bash
 npm run pack:esp32-kit -- \
   --source /absolute/path/tirtc-server-example/thing-connect \
-  --kit-version 1.1.3
+  --kit-version 1.1.4
 ```
 
 输出位于 `dist/`：
 
 ```text
-tirtc-esp32s3-kit-1.1.3.tar.gz
-tirtc-esp32s3-kit-1.1.3.tar.gz.sha256
+tirtc-esp32s3-kit-1.1.4.tar.gz
+tirtc-esp32s3-kit-1.1.4.tar.gz.sha256
 ```
 
 校验后推送独立的 `kit-esp32s3-v<version>` 标签。`publish-kit.yml` 会从 metadata 固定的上游 commit 重建压缩包、核对 SHA-256，并使用 GitHub Actions token 创建 Release：
 
 ```bash
 cd dist
-sha256sum -c tirtc-esp32s3-kit-1.1.3.tar.gz.sha256
+sha256sum -c tirtc-esp32s3-kit-1.1.4.tar.gz.sha256
 cd ..
 
-git tag -a kit-esp32s3-v1.1.3 -m "TiRTC ESP32-S3 Device Kit 1.1.3"
-git push origin kit-esp32s3-v1.1.3
+git tag -a kit-esp32s3-v1.1.4 -m "TiRTC ESP32-S3 Device Kit 1.1.4"
+git push origin kit-esp32s3-v1.1.4
 ```
 
 metadata 中的版本、标签、上游 commit 和期望 SHA-256 必须与本地可复现打包结果一致；工作流不会从浮动的 `main` 取发布内容。
@@ -961,8 +961,8 @@ metadata 中的版本、标签、上游 commit 和期望 SHA-256 必须与本地
 
 ```bash
 npm test
-git tag -a v0.9.2 -m "v0.9.2"
-git push origin v0.9.2
+git tag -a v0.9.4 -m "v0.9.4"
+git push origin v0.9.4
 ```
 
 不要重复发布已经存在的 npm 版本。版本变化同步更新 `package.json`、`.codex-plugin/plugin.json` 和发布说明。

package/bin/esp32-kit-metadata.js

@@ -1,9 +1,9 @@
 export const ESP32_KIT = Object.freeze({
-  archiveName: "tirtc-esp32s3-kit-1.1.3.tar.gz",
-  archiveRoot: "tirtc-esp32s3-kit-1.1.3",
-  releaseTag: "kit-esp32s3-v1.1.3",
-  sha256: "3239d3045a82082beb73b9bbbd2217e9da278bf8fbbe2941ae9131a20830d45c",
-  sourceCommit: "e685e33c6622fedfed66e9132447ddaae1e2a40e",
-  url: "https://github.com/tangeai/tirtc-device-builder/releases/download/kit-esp32s3-v1.1.3/tirtc-esp32s3-kit-1.1.3.tar.gz",
-  version: "1.1.3",
+  archiveName: "tirtc-esp32s3-kit-1.1.4.tar.gz",
+  archiveRoot: "tirtc-esp32s3-kit-1.1.4",
+  releaseTag: "kit-esp32s3-v1.1.4",
+  sha256: "b041baca1fbf6f3f3bd1299921793f0f708c669023b39148a34e3f478e3789fc",
+  sourceCommit: "7e9c595b8b5531bd781e42344c584095f3f74a1b",
+  url: "https://github.com/tangeai/tirtc-device-builder/releases/download/kit-esp32s3-v1.1.4/tirtc-esp32s3-kit-1.1.4.tar.gz",
+  version: "1.1.4",
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Install and run TiRTC device-development Agent Skills across popular coding clients.",
   "license": "MIT",
   "author": {

package/skills/tirtc-esp32-builder/SKILL.md

@@ -43,6 +43,12 @@ A probable match supplies hypotheses; a component match supplies only component
 lessons. Any identity conflict creates a new variant and keeps concrete GPIO,
 clock, DMA and task values unresolved.
 
+Read a match's `knowledge_refs` before scanning reference repositories. These
+are source maps and evidence, not permission to install a candidate adapter.
+For an existing project's media, memory or scheduling bug, read
+[runtime-resource-review.md](references/runtime-resource-review.md); preserve
+the user's business baseline separately from the hardware reference.
+
 ## 3. Prove the business flows before board porting
 
 When device-call or WeChat VoIP is requested, first build and run the pinned

package/skills/tirtc-esp32-builder/USAGE.md

@@ -74,7 +74,7 @@ printf '%s\n' "$TIRTC_THING_CONNECT_ROOT"
 python3 <skill-dir>/scripts/doctor.py \
   --expected-idf 5.5 \
   --target esp32s3 \
-  --thing-connect-root ~/.tirtc-device-builder/kits/esp32s3/1.1.3 \
+  --thing-connect-root ~/.tirtc-device-builder/kits/esp32s3/1.1.4 \
   --require-workspace
 ```
 

package/skills/tirtc-esp32-builder/VERSION

@@ -1 +1 @@
-0.9.2
+0.9.4

package/skills/tirtc-esp32-builder/assets/developer-intake-prompt.md

@@ -27,7 +27,7 @@
 
 接入方式：
 - Wi-Fi：<选择一种，或写“根据 BSP 选择”>
-- 选择 SoftAP 时：热点名以 `TiRTC-` 开头、开放认证无需密码，AP 网关和配网页面为 `192.168.6.1` / `http://192.168.6.1`，启用 DHCP/DNS/HTTP captive portal 自动发现并保留手动打开地址的回退说明
+- 选择 SoftAP 时：热点名以 `TiRTC-` 开头、开放认证无需密码，AP 网关和配网页面为 `192.168.6.1` / `http://192.168.6.1`，启用通配 DNS 和 HTTP 重定向进行 captive portal 自动发现，不把 DHCP Option 114 指向本地 HTML 页面，并保留手动打开地址的回退说明
 - 设备绑定：<选择一种，或写“根据平台合同选择”>
 
 工程：

package/skills/tirtc-esp32-builder/assets/lckfb-szpi-esp32s3-portable-prompt.md

@@ -8,7 +8,7 @@
 
 ```bash
 export TIRTC_AGENT_CLIENT=codex
-npx --yes tirtc-device-builder@0.9.2 setup esp32 --install \
+npx --yes tirtc-device-builder@0.9.4 setup esp32 --install \
   --client "$TIRTC_AGENT_CLIENT" --force-skill
 ```
 
@@ -17,11 +17,11 @@ npx --yes tirtc-device-builder@0.9.2 setup esp32 --install \
 本轮第一步先只读运行：
 
 ```bash
-npx --yes tirtc-device-builder@0.9.2 --version
-npx --yes tirtc-device-builder@0.9.2 setup esp32 --client "$TIRTC_AGENT_CLIENT"
+npx --yes tirtc-device-builder@0.9.4 --version
+npx --yes tirtc-device-builder@0.9.4 setup esp32 --client "$TIRTC_AGENT_CLIENT"
 ```
 
-必须根据命令的实际输出和本机文件确认：npm 包为 0.9.2、已安装 Skill 的 `VERSION` 为 0.9.2、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.3，并且 Doctor 对 `--expected-kit 1.1.3` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
+必须根据命令的实际输出和本机文件确认：npm 包为 0.9.4、已安装 Skill 的 `VERSION` 为 0.9.4、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.4，并且 Doctor 对 `--expected-kit 1.1.4` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
 
 工作区与 clean-room 边界：
 - 将启动 Agent 客户端时的当前目录定义为 `WORKSPACE_ROOT`。
@@ -60,7 +60,7 @@ npx --yes tirtc-device-builder@0.9.2 setup esp32 --client "$TIRTC_AGENT_CLIENT"
 - AI 对讲必须实现全双工和 AEC；构建阶段必须证明同时采集播放、真实播放参考与 `echo_cancellation.enabled=true`，实机结果仍只能在 L2-L7 验证后声明。
 
 接入要求：
-- SoftAP 配网：热点名使用 `TiRTC-` 前缀、开放认证无需密码，AP 网关和配网页面为 `192.168.6.1` / `http://192.168.6.1`；目标 Wi-Fi 凭证保存 NVS。
+- SoftAP 配网：热点名使用 `TiRTC-` 前缀、开放认证无需密码，AP 网关和配网页面为 `192.168.6.1` / `http://192.168.6.1`；启用通配 DNS 和 HTTP 重定向进行 captive portal 自动发现，不把 DHCP Option 114 指向本地 HTML 页面；Hardware IR 记录 `captive_portal: true`；目标 Wi-Fi 凭证保存 NVS。
 - 验证码绑定，并复用已有绑定。
 - 分别实现 `wifi-clear` 和 `tirtc-clear`。
 - 平台发现本轮先使用 HTTP；HTTPS 留待独立验收。

package/skills/tirtc-esp32-builder/knowledge/board-registry.json

@@ -1,4 +1,44 @@
 {
   "schema_version": 1,
-  "boards": []
+  "boards": [
+    {
+      "package_id": "waveshare_esp32p4_wifi6_touch_lcd_35_unknown_rev",
+      "status": "knowledge_only",
+      "identity": {
+        "vendor": "Waveshare",
+        "model": "ESP32-P4-WIFI6-Touch-LCD-3.5",
+        "aliases": ["微雪ESP32-P4-WIFI6-Touch-LCD-3.5", "Waveshare ESP32-P4-WIFI6-Touch-LCD-3.5"],
+        "hardware_revision": null,
+        "target": "esp32p4",
+        "module": null,
+        "flash_mb": 16,
+        "psram_mb": 32,
+        "components": [
+          {"kind": "camera", "model": "OV5647"},
+          {"kind": "audio_codec", "model": "ES8311"},
+          {"kind": "display", "model": "ST7796"},
+          {"kind": "touch", "model": "FT6336"},
+          {"kind": "network", "model": "ESP32-C6"}
+        ],
+        "probes": []
+      },
+      "compatibility": {"idf": "5.5.4", "tirtc_sdk": "2.3.0"},
+      "artifacts": {},
+      "knowledge_refs": ["waveshare-esp32-p4-wifi6-touch-lcd-3.5/knowledge.md"],
+      "lessons": [
+        {
+          "id": "waveshare_p4_media_receive_identity",
+          "scope": "board",
+          "subject": "VoIP receive admission",
+          "guidance": "Observed WeChat JPEG stream1 differs from subscribe/uplink stream11. Check active connection, generation and codec; reproduce with actual ingress before editing filters. See knowledge_refs for evidence and limitations.",
+          "action": "warn",
+          "verification": "corroborated",
+          "applies_to": {"package_id": "waveshare_esp32p4_wifi6_touch_lcd_35_unknown_rev"},
+          "evidence": [{"board_package_id": "waveshare_esp32p4_wifi6_touch_lcd_35_unknown_rev", "source_ref": "waveshare-esp32-p4-wifi6-touch-lcd-3.5/knowledge.md#media-and-failures-worth-remembering"}]
+        }
+      ]
+    },
+    {"package_id":"lckfb_szpi_esp32s3_v1_0_1","status":"knowledge_only","identity":{"vendor":"深圳嘉立创科技集团股份有限公司（立创开发板）","model":"立创·实战派 ESP32-S3 开发板","aliases":["LCKFB SZPI ESP32-S3"],"hardware_revision":"V1.0.1","target":"esp32s3","module":"ESP32-S3 module","flash_mb":16,"psram_mb":8,"components":[{"kind":"camera","model":"GC2145"},{"kind":"aec_reference","model":"ES7210 MIC3 hardware reference"}],"probes":[]},"compatibility":{"idf":"5.5.4","tirtc_sdk":"2.3.0"},"artifacts":{},"lessons":[]},
+    {"package_id":"alientek_atk_dnesp32s3_v1","status":"knowledge_only","identity":{"vendor":"正点原子 (ALIENTEK)","model":"ATK-DNESP32S3","aliases":[],"hardware_revision":"V1.0","target":"esp32s3","module":"ATK-MWS3S","flash_mb":16,"psram_mb":8,"components":[{"kind":"camera","model":"OV5640 PID 0x5640"},{"kind":"audio_codec","model":"ES8388"}],"probes":[]},"compatibility":{"idf":"5.5.4","tirtc_sdk":"2.3.0"},"artifacts":{},"lessons":[]}
+  ]
 }

package/skills/tirtc-esp32-builder/knowledge/waveshare-esp32-p4-wifi6-touch-lcd-3.5/knowledge.md

@@ -0,0 +1,84 @@
+# Waveshare ESP32-P4-WIFI6-Touch-LCD-3.5
+
+2026-09-07. Knowledge only; PCB and silicon revisions unresolved. This package
+contains source-correlated observations and targeted regressions, not an
+installable adapter or complete Hardware IR. A matching sales name does not
+authorize pin reuse. No credentials, raw call logs or user media are retained.
+
+## Read only the needed source
+
+| Baseline | Pinned source | Locate next |
+| --- | --- | --- |
+| Product business | xiaotai, baseline `8d67f0fe1b7385485e9d3de57065be53d10639ed` plus uncommitted P4 port | `lckfb-szpi-esp32s3-tirtc/components/starter_runtime/src/starter_runtime.c`, shared `starter_product`, `starter_tirtc` |
+| Hardware/media | tirtc-device-example `cad4cbe58c3ff451906322930ceede19e6bf6a07`, app 1.5.3 | `complete-applications/esp32-p4/device-monitor/main/` |
+| Vendor | waveshareteam/ESP32-P4-WIFI6-Touch-LCD-3.5 `870588e62daaf723f3c52f0060d8dc053665ed30` | `examples/esp-idf/06_I2SCodec`, `docs/revisions.md`, schematic |
+| Cross-check | xiaozhi-esp32 `1ce658bcb9ce9aac69d3f87af9894a715b7175f6` | `main/boards/waveshare/esp32-p4-wifi6-touch-lcd-3.5/` |
+
+Source paths are repository-relative, not prerequisites for a particular home
+directory. Product HEAD alone does not identify dirty source; retain the local
+diff and BIN/ELF identity when promoting this package. Project source maps live
+under `docs/boards/waveshare-esp32-p4-wifi6-touch-lcd-3.5/`; current build status
+is in `waveshare-esp32p4-xiaotai/PORT_STATUS.md` and `BUILD_IDENTITY.md`.
+
+## Hardware candidates (source-correlated, re-probe on new hardware)
+
+- P4, 32 MiB PSRAM, 16 MiB flash; ESP32-C6 over Hosted SDIO. P4 requires its own
+  RISC-V SDK; the tested IDF is 5.5.4-dirty, TiRTC 2.3.0.
+- ST7796 **SPI**, physical 320x480 / landscape 480x320; FT6336 uses the FT5x06
+  driver family. CSI camera does not imply a DSI display.
+- No onboard IMU is documented for this model: vendor hardware inventory omits
+  one, pinned monitor BSP declares `BSP_CAPS_IMU=0`, and vendor BSP 2.0.1 lists
+  IMU unavailable. External sensing is needed for motion-based rotation; BSP
+  support flags alone are not proof of hardware absence. Sources checked
+  2026-09-07: https://docs.waveshare.com/ESP32-P4-WIFI6-Touch-LCD-3.5 and
+  https://components.espressif.com/components/waveshare/esp32_p4_wifi6_touch_lcd_3_5/versions/2.0.1/readme
+- Shared I2C1 SDA7/SCL8: pass the existing bus to camera SCCB (`init_sccb=false`),
+  codec and touch; an unused I2C0 macro is not evidence for a second owner.
+- ES8311 I2S1 MCLK13/BCLK12/WS10/DOUT9/DIN11; PA53 high. Shared TX/RX,
+  16 kHz stereo 16-bit, left MIC/right DAC reference. Monitor uses
+  `.no_dac_ref=false`, codec register 0x44=0x58. Validate reference energy and
+  double-talk; a board-level reference macro in Xiaozhi does not prove its
+  actual codec object enables reference input.
+- LCD MOSI20/CLK21/CS23/DC26/RST27/BL28; touch RST29/INT50; BOOT35.
+  Verify combined rotation/mirror and all four touch corners. BOOT is distinct
+  from AXP2101 power controls; PMIC power sequencing remains unverified.
+- C6 SDIO CLK18/CMD19/D0..3=14..17/RST54. Read host/slave versions; STA working
+  does not verify SoftAP/captive portal. Read the remote STA MAC after got-IP.
+- OV5647 source: `main/drivers/camera/camera_driver.c`. Sensor mode may run
+  faster than requested output: observed 800x640@50 sensor paced to 15 fps.
+  Verify PID and actual silicon revision before selecting rev<3 defaults.
+
+## Media and failures worth remembering
+
+| Symptom | Evidence and correction | Regression / next source |
+| --- | --- | --- |
+| VoIP audio but no remote image | Callback metadata stream=1/media=65 (JPEG), rx=37 and decoded=0; adapter only allowed stream11. Receive by active connection/generation/codec, not uplink ID. User later reported image visible. | P4 `tools/test_video_ingress.py`, actual `p4_video_submit`/`drain_video`; monitor `tirtc_session_on_video` |
+| Remote producer not requested | Monitor subscribes then sends its version-specific video-enable command `(SN<<16)\u007c0x1105`, byte1. Added missing request, but this alone was not proven to fix image. | `tools/test_p4_video.py`; monitor `tirtc_session.c`, `tirtc_commands.c` |
+| H264 open fails with >8 MiB free | Singleton output workspace remained reserved for old profile. Stop worker, apply profile, reconcile reservation, restart. | `tools/test_p4_profile_switch.py`; `camera_pipeline_on_rtc_video_config_changed` |
+| Repeated WHIP attempts leak | Shared worker used WithCaps creation and ordinary deletion. Fixed to paired deletion; 24 KiB stack plus TCB per completed attempt was retained. | S3 `tools/test_voip_task_cleanup.py`; installed IDF `esp_additions/idf_additions.c` |
+| UI slow / video not smooth | Product UI tick100ms limits presentation near10fps; renderer input24x256KiB plus output20x480x320x2 dominate pools. Retained pools are intentional, not proven optimal for this product. | `call_video_renderer_config.h`, `p4_video_ui_tick`; measure before tuning |
+
+Product-specific media: device CALL H264 both directions; WeChat VOIP H264 up /
+MJPEG down, profile video enabled with 640x480, 8k mono A-law. Preserve explicit
+voice calls. Camera privacy disables local capture/send while keeping remote
+decode/audio; microphone is independent. Profile declaration is not proof of
+actual packets or display. P4 H264 encode is hardware; downstream H264 here is
+software, MJPEG uses hardware JPEG plus scaling.
+
+## Evidence boundary
+
+P4 `xiaotai-p4-voip.8` compiled with host regressions including 100 simulated
+worker exits; no repeated-call heap HIL yet.
+
+- BIN SHA256: `8bb2e46f3ce68318ebdd544c6cff979e6885e1c40b70ff0ee1731342b07c55e1`
+- ELF SHA256: `6a138dede2fe20e7980937801c48a0206b0a78a3634a49a9ef3e31f9bce811aa`
+- P4 SDK archive SHA256: `a7a01ffd496a55364c7e4d665ff3884d078147bba96752a965d97befca12e451`
+
+These identify historical local artifacts, not bundled binaries or a reproducible
+release. User reports video visible after the stream-filter correction, without
+a complete artifact-bound capture. Startup logs prove one successful media
+start, not long-run stability. Earlier HMAC signing -> invalid LVGL event crash
+is unresolved; no claim it was fixed by task cleanup. AEC/double-talk, weak
+network, repeated calls, PMIC controls and full product parity remain pending.
+Promote only after exact identity, portable adapter/IR/contracts and per-flow
+artifact-bound acceptance are retained.

package/skills/tirtc-esp32-builder/references/board-knowledge.md

@@ -51,6 +51,13 @@ Registry package status controls reuse:
 
 An older HIL result is provenance, not proof for a newly built artifact.
 
+Knowledge-only packages may record an unknown PCB revision as `null`; verified
+packages still require an explicit revision. `match` returns registry-relative
+`knowledge_refs` for exact/model candidates, including knowledge-only packages.
+Read that source map first and inspect only relevant source deltas. A probable
+match provides investigation leads, not validated pins or an installable adapter.
+The Waveshare ESP32-P4-WIFI6-Touch-LCD-3.5 package follows this boundary.
+
 ## Learning loop
 
 After the final assessment, create a project-local candidate:

package/skills/tirtc-esp32-builder/references/environment.md

@@ -16,7 +16,7 @@ The automatic branch never runs `sudo` or modifies a persistent shell profile. W
 When `<setup-root>/env.sh` exists, use it only as an activation prefix for the current command:
 
 ```bash
-bash -lc '. "<setup-root>/env.sh" && python3 "<skill-dir>/scripts/doctor.py" --expected-idf 5.5 --expected-kit 1.1.3 --target esp32s3 --require-workspace'
+bash -lc '. "<setup-root>/env.sh" && python3 "<skill-dir>/scripts/doctor.py" --expected-idf 5.5 --expected-kit 1.1.4 --target esp32s3 --require-workspace'
 ```
 
 The helper contains paths, not device or network credentials. Read `<setup-root>/config.json` when exact managed paths are needed; the environment helper does not authorize unrelated downloads, shell-profile changes, flashing, or credential writes.
@@ -26,7 +26,7 @@ Run the doctor before generation, build, flash, or monitor:
 ```bash
 python3 <skill-dir>/scripts/doctor.py \
   --expected-idf 5.5 \
-  --expected-kit 1.1.3 \
+  --expected-kit 1.1.4 \
   --target esp32s3 \
   --require-workspace
 ```

package/skills/tirtc-esp32-builder/references/hardware-ir.md

@@ -74,10 +74,12 @@ When the selected method is SoftAP:
   the setup page at `http://192.168.6.1`, and lease clients from that subnet.
   With ESP-IDF, stop DHCP before changing the AP netif IP information and
   restart it afterward;
-- enable captive portal discovery with DHCP option 114, wildcard DNS resolving
-  names to `192.168.6.1`, and an HTTP fallback redirect to the setup page. Keep
-  the direct HTTP address documented because client auto-popup is not
-  guaranteed and HTTPS cannot be transparently redirected.
+- enable captive portal discovery with wildcard DNS resolving names to
+  `192.168.6.1` and an HTTP fallback redirect to the setup page. Do not point
+  DHCP option 114 at the local HTML page: that option requires an RFC 8908
+  HTTPS/JSON API endpoint. Keep the direct HTTP address documented because
+  client auto-popup is not guaranteed and HTTPS cannot be transparently
+  redirected.
 
 Record these values on the selected SoftAP method as `ssid_prefix: "TiRTC-"`,
 `auth_mode: "open"`, `ipv4_address: "192.168.6.1"`, and

package/skills/tirtc-esp32-builder/references/runtime-resource-review.md

@@ -0,0 +1,58 @@
+# Existing-project media and resource review
+
+Use for missing remote video, allocation failures, task leaks, slow UI or call
+switching. This is a focused diagnostic route, not a requirement to redo board
+intake, replay every simulator flow or regenerate a working product.
+
+## Establish a narrow baseline
+
+Record business baseline and hardware reference separately. Keep the user's
+contacts, call arbitration, onboarding and UI semantics in the former; borrow
+drivers, capture and codec resource ownership from the latter. Read the matched
+knowledge package's source map, compare pinned commits and relevant dirty files,
+then inspect only the path under investigation. Reuse prior build evidence only
+when artifact identity matches; otherwise label it historical.
+
+## Receive-to-display contract
+
+For each active mode record uplink codec, subscribe ID, downlink codec and
+observed receive metadata independently. H5 video-up stream 11 remains valid;
+it does not establish a universal receive stream ID. Authenticate the active
+connection, validate generation and negotiated media, and test actual ingress
+with captured non-sensitive frame metadata before changing filters.
+
+Use bounded counters at callback, admission, queue, decoder, converter and
+presentation boundaries. Count admission rejection separately from overflow.
+`rx>0, decoded=0` is not automatically a codec failure. Test enabling remote
+production separately from subscription; protocol commands are SDK/reference
+specific, not generic magic constants.
+
+## Resource lifecycle
+
+- Inventory task creation and deletion pairs. ESP-IDF `xTaskCreate*WithCaps`
+  requires `vTaskDeleteWithCaps`; ordinary deletion retains its statically
+  registered stack/TCB. Confirm the installed IDF implementation. Self-deletion
+  may allocate a helper task; under tight internal RAM prefer owner-driven
+  cleanup after the worker has stopped. A mock API-pair test is not heap HIL.
+- Distinguish free capacity, largest contiguous block, DMA capability and
+  reserved-workspace ownership. Stop the old codec owner before reconfiguring
+  or acquiring a singleton workspace. Retry cannot repair stale ownership.
+- Budget internal RAM and PSRAM independently for idle, handshake, duplex media
+  and stop/reconnect overlap. Include codec pools, ingress copies, UI surfaces,
+  worker stacks and SDK queues; a retained pool is not a per-call leak.
+- Measure receive, decode and presentation cadence independently. A 100 ms UI
+  timer caps presentation near 10 fps even if decode runs at 15 fps. Evaluate
+  dedicated video presentation and smaller MJPEG latest-frame pools against
+  audio deadlines; H264 recovery buffers have different dependencies.
+
+## Completion evidence
+
+Run an actual-code regression for the failing seam. Report build/host tests
+separately from hardware. For resource changes, compare post-warmup baselines
+over repeated connect/cancel/hangup cycles and a sustained duplex call: heap
+free/largest/minimum by capability, task stack low-water marks, queue drops,
+decode/present rates and audio starvation. Sample cheaply outside realtime
+callbacks; choose intervals for the experiment, not permanent noisy polling.
+Unreproduced crashes remain unresolved even if a later call succeeds. Change
+one high-risk variable per hardware comparison and retain redacted artifact-
+bound results; user-reported video is evidence of video, not AEC or stability.

package/skills/tirtc-esp32-builder/scripts/board_registry.py

@@ -95,12 +95,16 @@ def validate_probe(item: Any, path: str, errors: list[str]) -> None:
         errors.append(f"{path}.required_for_exact must be true or false")
 
 
-def validate_identity(identity: Any, path: str, errors: list[str]) -> None:
+def validate_identity(identity: Any, path: str, errors: list[str], *, allow_unknown_revision: bool = False) -> None:
     if not isinstance(identity, dict):
         errors.append(f"{path} must be an object")
         return
-    for field in ("vendor", "model", "hardware_revision", "target"):
+    for field in ("vendor", "model", "target"):
         nonempty(identity.get(field), f"{path}.{field}", errors)
+    if allow_unknown_revision:
+        nullable_nonempty(identity.get("hardware_revision"), f"{path}.hardware_revision", errors)
+    else:
+        nonempty(identity.get("hardware_revision"), f"{path}.hardware_revision", errors)
     aliases = string_array(identity.get("aliases", []), f"{path}.aliases", errors)
     names = [identity.get("model"), *aliases]
     normalized_names = [normalized(value) for value in names if normalized(value)]
@@ -244,7 +248,15 @@ def validate_registry(data: dict[str, Any], registry_path: Path) -> list[str]:
             errors.append(
                 f"{prefix}.status must be one of {', '.join(sorted(PACKAGE_STATUSES))}"
             )
-        validate_identity(board.get("identity"), f"{prefix}.identity", errors)
+        validate_identity(board.get("identity"), f"{prefix}.identity", errors,
+                          allow_unknown_revision=status == "knowledge_only")
+        for ref_index, value in enumerate(string_array(
+            board.get("knowledge_refs", []), f"{prefix}.knowledge_refs", errors
+        )):
+            resolved = safe_registry_path(registry_path, value,
+                f"{prefix}.knowledge_refs[{ref_index}]", errors)
+            if resolved is not None and not resolved.is_file():
+                errors.append(f"{prefix}.knowledge_refs[{ref_index}] does not exist")
         compatibility = board.get("compatibility")
         if not isinstance(compatibility, dict):
             errors.append(f"{prefix}.compatibility must be an object")
@@ -453,6 +465,10 @@ def match_board(board: dict[str, Any], query: dict[str, Any]) -> dict[str, Any]
             {"kind": kind, "model": model} for kind, model in shared_components
         ],
         "applicable_lessons": applicable_lessons,
+        # A model candidate can read its evidence without acquiring GPIO/adapter
+        # authority. Component-only matches must not inherit board-specific docs.
+        "knowledge_refs": board.get("knowledge_refs", [])
+            if classification in {"exact", "probable"} else [],
         "artifacts": board.get("artifacts", {}) if reuse == "registered_board" else {},
     }