tirtc-device-builder 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Install and run TiRTC device-development skills for Codex.",
   "license": "MIT",
   "author": {

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

@@ -13,14 +13,16 @@ Turn board evidence into an evidence-backed ESP-IDF project. Treat the Hardware
 2. Locate the versioned ESP32 Device Kit root containing `device-sim/` using the explicit input, `TIRTC_THING_CONNECT_ROOT`, the managed setup configuration, or workspace discovery. Treat its manifest and packaged protocol documents as the generation facts. If the user explicitly supplies a full ThingConnect source workspace, also read its applicable `AGENTS.md`.
 3. Run the Doctor through the managed environment helper when one exists; otherwise run `python3 <skill-dir>/scripts/doctor.py --expected-idf 5.5 --target esp32s3`. Add `--require-workspace` when generation or repository reference documents are needed; a self-contained generated project can instead resolve its bundled SDK through `--project`. Resolve every required failure before claiming build readiness.
 4. Read [workflow.md](references/workflow.md). Select the registered-board, new-board intake, or existing-project branch. The branch is selected when every supplied artifact has been accounted for and the exact board revision is known or explicitly unresolved.
-5. Read [hardware-ir.md](references/hardware-ir.md) when a Hardware IR must be created or updated. Record a source and verification level for every hardware fact that affects a requested feature.
+5. Read [hardware-ir.md](references/hardware-ir.md) when a Hardware IR must be created or updated. New intake uses schema v2; schema v1 remains readable for existing H.264 projects. Record a source and verification level for every hardware fact that affects a requested feature.
 6. Run `python3 <skill-dir>/scripts/hardware_ir.py validate <hardware-ir.json>` and then `assess --strict`. Generation may proceed for a requested feature only when it is `READY_TO_PORT` or `HIL_VERIFIED`; otherwise report the exact missing evidence and continue with safe discovery or scaffolding only.
 
 ## Build the project
 
 Run `<device-kit-root>/device-sim/scripts/create_esp32_project.py` for the current ESP32-S3 H5/AI starter. Keep ThingConnect onboarding, H5, AI, TiRTC lifecycle, callback, stream, and generation behavior in the existing deep modules. Put board-specific camera, microphone, encoder, codec, amplifier, GPIO, DMA, and task behavior behind the `starter_media` seam or a board media adapter owned by it.
 
-Before changing media code, read [capability-rules.md](references/capability-rules.md) and the repository documents it routes to. A camera sensor alone does not establish H5 video support; the complete H.264 Annex-B and key-frame path must be evidenced. Choose half duplex for AI when the supplied hardware and BSP do not establish a usable full-duplex/AEC path.
+Before changing media code, read [capability-rules.md](references/capability-rules.md) and [porting-risks.md](references/porting-risks.md), then read the repository documents they route to. A camera sensor alone does not establish H5 video support; validate the user-selected MJPEG, H.264, or H.265 profile end to end. Choose half duplex for AI when the supplied hardware and BSP do not establish a usable full-duplex/AEC path.
+
+Keep the Skill board-agnostic. The prompt supplies product intent and artifact locations; Hardware IR stores evidence; the generated board adapter owns concrete sensors, codecs, pins, clocks, slots, DMA, and task allocation. Never add one board's values to Skill defaults to make an assessment pass.
 
 Run focused tests before ESP-IDF build. Resolve the TiRTC SDK target and `manifest/build-contract.env` against the generated `sdkconfig`; a mismatched precompiled SDK is a blocked build, not a code-generation problem.
 
@@ -28,7 +30,7 @@ Run focused tests before ESP-IDF build. Resolve the TiRTC SDK target and `manife
 
 Flash only when the user requested hardware mutation and the exact serial port and chip have been resolved. When more than one candidate device exists, obtain the target choice before writing. Keep credentials outside generated files and redact device keys, Wi-Fi passwords, MQTT/WHIP tokens, and user media from logs and reports.
 
-Read [reporting.md](references/reporting.md) before end-to-end verification. Report every acceptance level as `PASS`, `FAIL`, or `SKIP`, with commands and evidence. A build-only result is not H5 or AI completion; missing hardware, browser, account, service, or network evidence remains an explicit `SKIP` or blocker.
+Read [reporting.md](references/reporting.md) before end-to-end verification. Report every acceptance level as `PASS`, `FAIL`, or `SKIP`, with commands and evidence. Bind HIL observations to the exact firmware SHA-256 with `assess --artifact-sha256`; an older artifact cannot verify a newer build. A build-only result is not H5 or AI completion; missing hardware, browser, account, service, or network evidence remains an explicit `SKIP` or blocker.
 
 ## Finish
 

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

@@ -14,20 +14,23 @@ npx tirtc-device-builder@latest setup esp32 --install
 ```text
 $tirtc-esp32-builder
 
-在“厂商 + 完整开发板型号 + PCB 版本”上实现：
-- H5 实时视频和声音
-- H5 按住说话
-- AI 双向对讲
+开发板：<厂商、完整型号、PCB 版本>
+资料与实物对应：<是/否/未知>
 
 资料：
-- 产品页或资料链接：...
-- 原理图：/absolute/path/board-schematic.pdf
-- BSP 或示例工程：/absolute/path/vendor-bsp
-- 输出目录：/absolute/path/my-tirtc-device
+- <原理图、BSP/厂商示例、数据手册和产品页；一行一个>
 
-先完成能力分析；具备条件后生成并编译。只有我明确指定串口时才烧录。
+目标：<H5 实时音视频、H5 对讲、AI 双向语音等>
+视频：<MJPEG/H264/H265/根据证据选择>
+Wi-Fi 与设备绑定：<指定方案/根据 BSP 和平台合同选择>
+工程：<输出目录或现有工程的绝对路径>
+
+先运行 Doctor，再生成 Hardware IR v2。达到 READY_TO_PORT 后完成板级适配和编译，输出 TIRTC_PORTING_REPORT.md。
+本轮不访问串口、不烧录、不擦除 NVS，也不把凭证写入源码或报告。
 ```
 
+可直接复制的版本见[开发板接入提示词](assets/developer-intake-prompt.md)。SoftAP 只是可选方案；没有 AP 配网时，Skill 会根据 BSP 和产品要求评估其他可重配路径。生产 SSID 和密码不能进入源码或报告。
+
 ## ESP32 Device Kit
 
 一键安装会下载固定版本的最小资源包并校验 SHA-256，不需要克隆 ThingConnect 服务端仓库。安装路径由下面的文件记录：
@@ -92,8 +95,8 @@ python3 <skill-dir>/scripts/hardware_ir.py validate /tmp/hardware-ir.json
 python3 <skill-dir>/scripts/hardware_ir.py assess --strict /tmp/hardware-ir.json
 ```
 
-`BLOCKED` 表示资料已确认硬件不满足；`NEEDS_CONFIRMATION` 表示仍有未知项或只有单一来源；`READY_TO_PORT` 表示可以生成并实现板级适配；`HIL_VERIFIED` 表示端到端实机验收通过。
+`init` 默认创建 schema v2；v1 仅用于兼容已有 H.264 IR。`BLOCKED` 表示资料已确认硬件/合同/资源或凭证策略不满足；`NEEDS_CONFIRMATION` 表示仍有未知项或只有单一来源；`READY_TO_PORT` 表示可以生成并实现板级适配；`HIL_VERIFIED` 还要求 `--artifact-sha256` 匹配该固件的 L5/L6 运行证据。
 
 ## 当前边界
 
-ThingConnect 仓库提供 ESP32-S3 H5/AI 模板和生成器，但默认媒体适配器不包含特定开发板的摄像头、麦克风、H.264 编码和扬声器驱动。模板生成和编译成功只证明工程与协议骨架可用，不代表 Web 已经出图或 AI 音频已经通过实机验收。
+ThingConnect 仓库提供 ESP32-S3 H5/AI 模板和生成器，但默认媒体适配器不包含特定开发板的摄像头、麦克风、选定视频路径、Wi-Fi 凭证方法和扬声器驱动。模板生成和编译成功只证明工程与协议骨架可用，不代表 Web 已经出图或 AI 音频已经通过实机验收。

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

@@ -0,0 +1,50 @@
+# TiRTC ESP32 开发板接入提示词
+
+不用先把所有硬件参数查齐。你只要说明是哪块板、资料放在哪里、想实现什么，以及工程输出到哪里。其余内容由 Skill 从原理图、BSP、Device Kit 和数据手册中提取；确实不知道的地方写“未知”。
+
+## 精简模板
+
+```text
+$tirtc-esp32-builder
+
+请为下面这块开发板完成 ThingConnect TiRTC ESP32 接入。
+
+开发板：
+- 厂商、完整型号、PCB/硬件版本：<填写>
+- 资料与手中实物是否对应：<是/否/未知>
+
+资料：
+- <原理图、BSP/厂商示例、数据手册、产品页等本地绝对路径或固定链接；一行一个>
+
+目标：
+- <例如：H5 实时视频和声音、H5 语音对讲、AI 双向语音对讲>
+- 视频选择：<MJPEG/H264/H265/根据合同和硬件证据选择>
+- 双工或 AEC 的硬要求：<无，初版可半双工/必须全双工或 AEC/未知>
+
+接入方式：
+- Wi-Fi：<选择一种，或写“根据 BSP 选择”>
+- 设备绑定：<选择一种，或写“根据平台合同选择”>
+
+工程：
+- 输出目录或现有工程：<绝对路径>
+
+执行要求：
+1. 先运行 Device Kit Doctor，读完全部资料，再生成 Hardware IR v2。没有证据的器件、GPIO 和媒体能力保持未知。
+2. 资料不足时，列出矛盾、缺失项和最小补充动作；达到 READY_TO_PORT 后再生成板级 adapter、编译并记录 BIN/ELF SHA-256。
+3. 移植前核对媒体合同、板级资源、内存预算、配网和绑定状态。具体板卡参数只写入该板的 Hardware IR 和 adapter。
+4. 输出 TIRTC_PORTING_REPORT.md，并把编译结果与 L2-L7 实机验收分开记录。
+5. 本轮不访问串口、不烧录、不擦除 NVS。Wi-Fi 密码、设备密钥、token、私钥和用户音视频也不能写入工程或报告。
+```
+
+## 只有已知时才补充
+
+这些信息如果手头已有，也可以附上；没有就交给 Skill 查资料：
+
+- 主控/模组完整型号、Flash 和 PSRAM 容量及总线模式；
+- BSP 的 commit、tag 或 release，以及已验证的摄像头、录音和播放示例；
+- H5/AI 媒体合同链接、选定 profile、stream ID 和帧或 access unit 边界；
+- 凭证保存与重配方式、已有绑定处理和独立清除入口；
+- 已知资料矛盾、实机 PID、串口日志或已知良好固件 SHA-256；
+- 非默认 ESP-IDF、TiRTC SDK、Device Kit、服务发现地址或 HTTP/HTTPS 分阶段要求。
+
+直接把它们追加在提示词末尾即可，不必逐项填表。

package/skills/tirtc-esp32-builder/assets/hardware-ir-v2.example.json

@@ -0,0 +1,122 @@
+{
+  "schema_version": 2,
+  "board": {
+    "id": "example_esp32s3_media_board",
+    "vendor": "Example Vendor",
+    "model": "ESP32-S3 Media Board",
+    "hardware_revision": "unspecified"
+  },
+  "sources": [
+    {
+      "id": "board-materials",
+      "kind": "user-supplied-materials",
+      "location": "user-supplied://board-materials",
+      "revision": "unspecified"
+    }
+  ],
+  "soc": {
+    "target": "esp32s3",
+    "module": "ESP32-S3-WROOM-1-N16R8",
+    "flash_mb": 16,
+    "psram_mb": 8,
+    "source_refs": [
+      "board-materials"
+    ]
+  },
+  "toolchain": {
+    "framework": "esp-idf",
+    "framework_version": "5.5.x",
+    "verification": "extracted",
+    "tirtc": {
+      "platform": "espressif-esp32s3",
+      "version": "2.3.0",
+      "sdk_path": "device-sim/sdk/espressif-esp32s3/2.3.0",
+      "build_contract": "manifest/build-contract.env"
+    },
+    "source_refs": [
+      "board-materials"
+    ]
+  },
+  "camera": {
+    "present": null,
+    "sensor": null,
+    "interface": null,
+    "selected_video_profile": null,
+    "video_profiles": [],
+    "source_refs": [
+      "board-materials"
+    ]
+  },
+  "audio_input": {
+    "present": null,
+    "interface": null,
+    "codecs": [],
+    "source_refs": [
+      "board-materials"
+    ]
+  },
+  "audio_output": {
+    "present": null,
+    "interface": null,
+    "codecs": [],
+    "source_refs": [
+      "board-materials"
+    ]
+  },
+  "hardware_resources": {
+    "i2c": {
+      "used": null,
+      "driver_family": null,
+      "single_driver_family": null,
+      "verification": "extracted"
+    },
+    "i2s": {
+      "used": null,
+      "controller_and_gpio_ownership_resolved": null,
+      "verification": "extracted"
+    },
+    "audio_channel_mapping": {
+      "required": null,
+      "resolved": null,
+      "verification": "extracted"
+    },
+    "camera_realtime": {
+      "pipeline_safe": null,
+      "verification": "extracted"
+    },
+    "memory": {
+      "startup_and_media_budgeted": null,
+      "verification": "extracted"
+    },
+    "source_refs": [
+      "board-materials"
+    ]
+  },
+  "onboarding": {
+    "wifi_credentials": {
+      "selected_method": null,
+      "methods": [],
+      "credentials_committed_to_source": null,
+      "reprovisioning_defined": null
+    },
+    "device_binding": {
+      "selected_method": null,
+      "methods": [],
+      "credentials_committed_to_source": null,
+      "stored_credential_state_handled": null,
+      "clear_binding_control": null
+    },
+    "source_refs": [
+      "board-materials"
+    ]
+  },
+  "runtime_evidence": [],
+  "features": {
+    "requested": [
+      "h5_live_audio",
+      "h5_live_video",
+      "h5_talkback",
+      "ai_talk"
+    ]
+  }
+}

package/skills/tirtc-esp32-builder/assets/report-template.md

@@ -5,6 +5,9 @@
 - Board ID: `{{BOARD_ID}}`
 - Model/revision: `{{BOARD_MODEL_REVISION}}`
 - Requested features: `{{REQUESTED_FEATURES}}`
+- Selected media profile: `{{SELECTED_MEDIA_PROFILE}}`
+- Selected Wi-Fi credential method: `{{SELECTED_WIFI_METHOD}}`
+- Selected device-binding method: `{{SELECTED_BINDING_METHOD}}`
 - Output project: `{{PROJECT_PATH}}`
 
 ## Locked inputs
@@ -46,6 +49,18 @@
 - Firmware SHA-256: `{{FIRMWARE_SHA256}}`
 - Flash command/result: `{{FLASH_RESULT}}`
 
+## Artifact-bound runtime evidence
+
+| Artifact SHA-256 | Acceptance levels | Observations | Current/superseded |
+|---|---|---|---|
+|  |  |  |  |
+
+## Runtime metrics
+
+- Wi-Fi BSSID/channel/RSSI and roaming: `{{WIFI_RUNTIME_METRICS}}`
+- Media tx/rx/drop/error and queue watermarks: `{{MEDIA_RUNTIME_METRICS}}`
+- Camera overflow, internal heap/largest block, PSRAM: `{{RESOURCE_RUNTIME_METRICS}}`
+
 ## Remaining work and risks
 
 `{{REMAINING_WORK}}`

package/skills/tirtc-esp32-builder/references/capability-rules.md

@@ -1,32 +1,57 @@
 # Capability rules
 
-Run `hardware_ir.py assess --strict` before generation. The script applies the minimum current starter contract; use this reference when explaining or extending the result.
+Run `hardware_ir.py assess --strict` before generation. Hardware IR v2 validates the selected product contract rather than assuming one video codec or provisioning method. Schema v1 remains readable for existing H.264 projects.
 
 ## Current starter contract
 
 | Feature | Required hardware/media path |
 |---|---|
-| `h5_live_audio` | Microphone path that produces G.711 A-law, 8 kHz, mono for stream 10 |
-| `h5_live_video` | Camera plus H.264 Annex-B access units, SPS/PPS and IDR, and key-frame request control for stream 11 |
-| `h5_talkback` | G.711 A-law, 8 kHz downlink decode and speaker path for stream 14 |
-| `ai_talk` | A-law 8 kHz microphone and speaker paths for AI stream 1, started only after `start_session` succeeds |
+| `h5_live_audio` | Microphone path producing G.711 A-law, 8 kHz, mono for stream 10; audio controller/channel ownership and memory budget resolved |
+| `h5_live_video` | Camera plus the selected MJPEG, H.264, or H.265 profile for stream 11; refresh/key-frame control, realtime pipeline, and memory budget resolved |
+| `h5_talkback` | G.711 A-law, 8 kHz downlink decode and speaker path for stream 14; audio controller/GPIO ownership and memory budget resolved |
+| `ai_talk` | A-law 8 kHz microphone and speaker paths for AI stream 1, started only after `start_session`; audio ownership/channel mapping and memory budget resolved |
 
-The complete media path must be at least `corroborated` to become `READY_TO_PORT`. A path with unknown facts is `NEEDS_CONFIRMATION`; a confirmed missing or incompatible resource is `BLOCKED`. Only an end-to-end board run becomes `HIL_VERIFIED`.
+The complete media path must be at least `corroborated` to become `READY_TO_PORT`. A path with unknown facts is `NEEDS_CONFIRMATION`; a confirmed missing or incompatible resource is `BLOCKED`.
 
-## Non-negotiable checks
+## Selected video profiles
+
+Hardware IR v2 stores one or more `camera.video_profiles` and exactly one selected profile for H5 video:
+
+| Codec | Required output contract |
+|---|---|
+| `mjpeg` | `jpeg_complete_frames`: one complete JPEG per send; each frame independently refreshable |
+| `h264` | `h264_annex_b_access_units`: Annex-B access units with SPS/PPS and IDR request behavior |
+| `h265` | `h265_annex_b_access_units`: Annex-B access units with parameter-set and refresh behavior defined by the coordinated H5 contract |
+
+Available but unselected profiles do not satisfy or block the selected contract. Stream IDs and codec support must come from the applicable ThingConnect/H5 contract, not this table alone.
+
+## Project gates
+
+Schema v2 also requires:
+
+- one evidenced I2C driver family when I2C is used;
+- a selected Wi-Fi credential method that is available, reprovisionable, and keeps credentials outside source control;
+- one evidenced binding method—verification code, factory-bound identity, development credentials, or documented custom flow—plus stored-binding behavior and reset control;
+- feature-specific I2S/GPIO ownership, channel/TDM mapping, realtime camera policy, and startup/media memory budget.
+
+SoftAP is one Wi-Fi option, not a universal requirement. BLE, SmartConfig, factory NVS, development configuration, or a documented custom method can satisfy intake when the selected path is evidenced. Committed plaintext credentials are always `BLOCKED`.
+
+## Non-negotiable runtime checks
 
 - Match the TiRTC precompiled SDK platform to the ESP-IDF target and its `manifest/build-contract.env` to the generated configuration.
-- Keep H5 stream IDs and formats stable unless the user explicitly authorizes a coordinated public contract change across the server and all consumers.
-- Start AI media only after the successful `start_session` response, and stop/flush media before disconnecting the session.
-- Copy SDK callback payloads into bounded queues before returning. Perform decoding, playback, HTTP, and lifecycle changes outside SDK callbacks.
+- Keep H5 stream IDs and formats stable unless the user explicitly authorizes a coordinated contract change across the server and consumers.
+- Start AI media only after the successful `start_session` response; stop and flush media before disconnecting.
+- Copy SDK callback payloads into bounded queues before returning. Perform decoding, playback, HTTP, and lifecycle changes outside callbacks.
 - Use monotonic timestamps and session generation to reject stale frames and delayed callbacks.
+- Record runtime evidence with the exact BIN/ELF SHA-256. Use `assess --artifact-sha256 <sha>`; documentation verification alone never becomes v2 `HIL_VERIFIED`.
 
 ## Typical blocked cases
 
-- A camera outputs JPEG but no evidenced H.264 encoder produces Annex-B access units.
-- The board has a microphone but no encoder path for the required A-law sample rate.
-- The board has a codec but its playback pins, clock, amplifier enable, or BSP driver remain unknown.
-- A generic ESP32-S3 module is named without the carrier board that defines camera/audio wiring.
-- The available TiRTC archive targets another chip, ESP-IDF ABI, or FreeRTOS configuration.
+- The selected MJPEG/H.264/H.265 profile lacks its required output or refresh semantics.
+- Audio hardware exists, but the A-law path, physical channel/TDM slot, clock, amplifier, or resource ownership is unresolved.
+- Third-party components introduce both legacy and new ESP-IDF I2C drivers.
+- A generic ESP32-S3 module is named without the carrier board wiring and hardware revision.
+- Wi-Fi credentials are embedded in tracked source, or no available/reprovisionable credential path is selected.
+- The TiRTC archive targets another chip, ESP-IDF ABI, or FreeRTOS configuration.
 
-When a blocked case would require changing the H5 contract, replacing hardware, or obtaining a new TiRTC SDK build, report those alternatives instead of silently changing the project.
+When a blocked case requires changing a public contract, replacing hardware, obtaining a new SDK, or choosing a provisioning policy, report alternatives instead of silently changing the project.

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

@@ -1,49 +1,69 @@
 # Hardware IR
 
-Hardware IR is a generated, reviewable description of one exact board revision. It is the only input consumed by deterministic capability checks. Start from [the example](../assets/hardware-ir.example.json) with:
+Hardware IR describes one exact board revision and product contract. It is the deterministic handoff from board evidence to capability assessment, generation, build, and HIL reporting.
+
+Create the current schema:
 
 ```bash
 python3 <skill-dir>/scripts/hardware_ir.py init <output>/hardware-ir.json
 ```
 
+The initializer creates schema v2. The validator still accepts schema v1 for existing H.264-only projects; update new or materially changed boards to v2.
+
 ## Evidence rules
 
 - Give every source a stable `id`, `kind`, `location`, and revision when available.
-- Reference those IDs from `soc`, `toolchain`, `camera`, `audio_input`, and `audio_output`.
-- Use `null` for unknown presence, pins, formats, or encoder properties. Empty strings are invalid facts.
-- Hardware revision `unspecified` is acceptable during intake but blocks registration as a reusable supported board.
-- Keep desired features under `features.requested`; do not encode wishes as hardware facts.
-- Record the strongest evidenced verification level, not the intended future state.
+- Reference source IDs from board facts, selected profiles, onboarding methods, resources, and runtime evidence.
+- Use `null` for unknown facts. Retain contradictory values as explicit issues instead of choosing silently.
+- Hardware revision `unspecified` is valid during intake but blocks reusable-board readiness.
+- Keep requested product features under `features.requested`; desired behavior is not hardware evidence.
+- Store concrete sensors, pins, clocks, codecs, slots, and task allocation in this board IR/adapter, never in generic Skill defaults.
 
 Verification levels are ordered:
 
-1. `extracted`: obtained from one source.
-2. `corroborated`: confirmed by another authoritative artifact, such as schematic plus BSP.
-3. `build_verified`: the matching implementation builds with the locked toolchain.
-4. `hardware_verified`: the peripheral works on the exact physical revision.
-5. `hil_verified`: the requested H5/AI path passes end to end.
+1. `extracted`: one source.
+2. `corroborated`: another authoritative artifact confirms it.
+3. `build_verified`: matching implementation builds with the locked toolchain.
+4. `hardware_verified`: the local peripheral works on the exact board revision.
+5. `hil_verified`: retained for legacy facts; schema v2 feature HIL additionally requires matching artifact evidence.
 
-## Minimum facts
+## Schema v2 contracts
 
 The IR contains:
 
-- exact board identity and revision;
-- SoC target, module, Flash, and PSRAM;
-- ESP-IDF and TiRTC SDK platform/version/build contract plus their verification level;
-- camera presence, sensor/interface, and H.264 output/key-frame properties;
-- audio input and output presence, interface, codecs, sample rates, and verification;
-- requested ThingConnect feature IDs.
+- exact board identity, module, Flash/PSRAM, ESP-IDF, TiRTC SDK and build contract;
+- camera identity evidence plus `video_profiles[]` and `selected_video_profile`;
+- audio input/output paths;
+- `hardware_resources` for I2C, I2S/GPIO ownership, audio channel mapping, camera realtime policy, and memory budget;
+- `onboarding.wifi_credentials` with selectable SoftAP/BLE/SmartConfig/factory/development/custom methods;
+- selectable ThingConnect binding methods plus stored-binding states and reset control;
+- requested features;
+- optional `runtime_evidence[]`, each bound to a full firmware SHA-256.
+
+The selected Wi-Fi method must be available and corroborated, credentials must remain outside tracked source, and reprovisioning must be defined. A board without SoftAP is valid when another selected method meets those conditions.
+
+The selected video profile controls assessment. An unselected H.264 fallback cannot make an MJPEG target pass, and missing H.264 cannot block an evidenced MJPEG target.
+
+## Artifact-bound HIL
+
+Run:
+
+```bash
+python3 <skill-dir>/scripts/hardware_ir.py assess hardware-ir.json \
+  --artifact-sha256 <64-character-sha256> --strict
+```
 
-Pin and driver details may live in a board adapter manifest referenced from the IR once the adapter exists. Until then, missing pins remain capability issues even if the high-level media path appears possible.
+H5 features require matching L5 evidence; AI requires matching L6 evidence. Evidence from an older firmware remains provenance but does not verify the current artifact.
 
 ## Intake quality
 
-Preferred input order:
+Preferred evidence order:
 
 1. exact schematic/netlist and BOM for the physical revision;
 2. official BSP pinned to a commit or release;
-3. sensor, codec, amplifier, and module datasheets;
-4. a minimal project that has been built for the board;
-5. product pages, README files, photographs, and community material.
+3. sensor, codec, amplifier and module datasheets;
+4. minimal peripheral projects built for that board;
+5. product pages, photographs and community material;
+6. artifact-bound boot, media and browser observations.
 
-A schematic establishes electrical connectivity, not driver maturity, encoding throughput, acoustic behavior, or end-to-end TiRTC compatibility. Preserve those as separate verification facts.
+A schematic establishes connectivity, not driver family compatibility, encoding throughput, acoustic behavior, provisioning usability, network performance, or end-to-end TiRTC operation. Preserve each as a separate fact and verification level.

package/skills/tirtc-esp32-builder/references/porting-risks.md

@@ -0,0 +1,49 @@
+# Board-porting risk gates
+
+Read this reference for every new board or failing media bring-up. It defines generic evidence gates; concrete values belong in the board's Hardware IR and adapter.
+
+## Freeze the contract before code
+
+Record the selected video profile, audio formats and stream IDs, duplex/AEC policy, onboarding method, platform-discovery transport, output path, and mutation authorization. Keep unknown values explicit. A server supporting several codecs does not select one for the device.
+
+## Hardware identity and ownership
+
+- Sensor and codec identity: reconcile schematic/BOM names with BSP probes or ID registers. Store every evidenced variant in an allowlist; retain contradictions as issues.
+- I2C: select one ESP-IDF driver family for the final image. Audit the linked ELF when third-party components can introduce another family; a conflict bypass is not a resolution.
+- I2S/audio: record controller, GPIO, master/slave mode, clocks, DMA, channel/TDM slot to physical-signal mapping, and shared-signal handoff. A codec name or I2C address does not prove the audio path.
+- Realtime camera path: record DMA/event queues, task core/priority, and competing Wi-Fi work. Treat queue overflows as scheduling or throughput evidence, then change one variable per HIL comparison.
+
+Turn every discovered invariant that can regress into a focused test or post-link gate. Generate board-specific values with the project; keep the Skill generic.
+
+## Wi-Fi credentials and device binding
+
+Wi-Fi provisioning and ThingConnect binding are separate state machines.
+
+Select one evidenced Wi-Fi credential method from SoftAP, BLE, SmartConfig, secure factory/NVS provisioning, development configuration, or a documented custom path. SoftAP is not mandatory. A board without AP provisioning can reach `READY_TO_PORT` through another available method when credentials remain outside source control and a reprovisioning path is defined.
+
+Development configuration may inject credentials through an untracked sdkconfig, environment, or provisioning artifact. Treat committed plaintext credentials as `BLOCKED`. Never copy SSIDs/passwords into Hardware IR, reports, examples, or source.
+
+Select the binding method from the applicable platform/product contract: verification code, factory-bound identity, development credentials, or a documented custom flow. When verification-code binding is selected, distinguish at least:
+
+- no Wi-Fi credentials;
+- Wi-Fi present but no device binding, so the verification-code flow runs;
+- stored binding present, so verification is skipped intentionally;
+- binding-only reset and Wi-Fi reset.
+
+For every method, keep device credentials outside source control, handle an already stored identity explicitly, and define binding reset/replacement behavior.
+
+## Startup memory, TLS, and transport
+
+Platform service discovery and the TiRTC SDK service endpoint are different settings. Record both. HTTPS requires valid time, DNS, certificate validation, TLS client/TLS 1.2, and enough contiguous internal memory.
+
+Before sizing TiRTC buffers, measure internal free/largest blocks, PSRAM, frame size distribution, queue watermarks, and send/drop rates. A larger queue can prevent drops, exhaust startup memory, or add buffer latency. If an authorized HTTP baseline exists, stage transport changes separately from media changes and retain the HTTPS requirements as a pending acceptance item.
+
+## Network and media evidence
+
+Disable Wi-Fi power saving for the realtime baseline unless the product contract says otherwise. Record BSSID, channel, RSSI, reconnect/roaming events, media counters, queue watermarks, camera overflows, internal heap, and largest block. Establish a strong, stable AP baseline before controlled weak-network testing.
+
+Confirm SDK send return semantics and callback payload lifetimes from the selected SDK version. Keep SDK callbacks bounded and copy payloads before returning.
+
+## Artifact discipline
+
+Record BIN/ELF SHA-256 for every build used in HIL. Runtime evidence applies only to the exact artifact. Diagnose one failing invariant, make the smallest correction, rerun that layer, and preserve the comparison in the report.

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

@@ -18,6 +18,10 @@ Use [the report template](../assets/report-template.md) and preserve separate `P
 
 ## Evidence
 
-Record exact board revision, toolchain and SDK versions, source/adapter revisions, commands, return codes, firmware size and SHA-256, serial port/chip, sanitized log paths, browser or platform observations, and every unavailable dependency.
+Record exact board revision, selected media, Wi-Fi, and binding profiles, toolchain and SDK versions, source/adapter revisions, commands, return codes, firmware size and SHA-256, serial port/chip, sanitized log paths, browser or platform observations, and every unavailable dependency.
+
+Runtime evidence belongs to one artifact. Label superseded artifacts and keep their observations as history; do not promote them to the current BIN/ELF. For HIL assessment, add the full SHA-256 to `runtime_evidence` and run `hardware_ir.py assess --artifact-sha256 <sha> --strict`.
+
+For L3-L7 media runs, capture the signals that distinguish software regressions from environment changes: onboarding/binding state, BSSID/channel/RSSI, reconnect or roaming events, audio/video send/receive/drop/error counters, queue watermarks, camera overflow count, internal heap/largest block, PSRAM, and measured latency when available. Never record credential values.
 
 Reports describe observed current behavior. A `SKIP` caused by missing hardware, account, service, browser, or external network does not become a pass. If the user's requested completion level includes a skipped critical case, the final outcome remains incomplete.

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

@@ -19,11 +19,12 @@ The branch is complete when the new run has its own build and verification evide
 Use this branch when the user supplies a board model, vendor URL, schematic, BOM, pin map, BSP, datasheets, photographs, or peripheral example projects without a verified adapter.
 
 1. Resolve the full model, module, PCB marking, and hardware revision. Treat different revisions as different boards.
-2. Prefer official schematic/BOM and BSP facts. For a PDF schematic, inspect page labels and net names; prefer an exported netlist, pin CSV, or vendor board definition when available.
-3. Cross-check critical pins, clocks, power enables, reset lines, sensor/codec variants, and ESP-IDF version across at least two independent artifacts when possible.
-4. Create the Hardware IR. Use `null` for unknown facts and retain contradictory values as an explicit issue instead of selecting one silently.
-5. Validate and assess requested features. Ask only for unresolved facts that block the next safe step.
-6. When all requirements reach `READY_TO_PORT`, generate the starter and implement the board adapter. When requirements remain blocked, generate only the IR, capability report, and an optional compile-safe skeleton if requested.
+2. Freeze the user-supplied product contract: selected video profile, audio/stream formats, duplex/AEC policy, supported Wi-Fi credential methods, selected onboarding method, transport staging, output path, and mutation boundary. Use `unknown` where the prompt lacks an answer.
+3. Prefer official schematic/BOM and BSP facts. For a PDF schematic, inspect page labels and net names; prefer an exported netlist, pin CSV, or vendor board definition when available.
+4. Cross-check critical pins, clocks, power enables, reset lines, sensor/codec variants, ESP-IDF version, resource ownership, and onboarding behavior across at least two independent artifacts when possible.
+5. Create the Hardware IR v2. Use `null` for unknown facts and retain contradictory values as an explicit issue instead of selecting one silently. Store concrete board values in the IR/adapter rather than Skill files.
+6. Validate and assess requested features. Ask only for unresolved facts that block the next safe step. SoftAP is optional when another evidenced Wi-Fi credential method is available, keeps credentials outside source, and defines reprovisioning.
+7. When all requirements reach `READY_TO_PORT`, generate the starter and implement the board adapter. When requirements remain blocked, generate only the IR, capability report, and an optional compile-safe skeleton if requested.
 
 The branch is complete when every supplied artifact maps to an IR fact, provenance entry, contradiction, or declared irrelevant item.
 
@@ -55,16 +56,16 @@ The runtime-facing `starter_media` interface stays stable. A reusable board inte
 
 The adapter owns:
 
-- camera capture and H.264 encoding tasks;
+- camera capture and the selected MJPEG/H.264/H.265 media path;
 - microphone capture and audio encoding;
 - downlink audio decode, buffering, codec, amplifier, and I2S playback;
-- DMA buffers, hardware clocks, power, reset, GPIO, and key-frame requests;
+- DMA buffers, hardware clocks, power, reset, GPIO, refresh/key-frame requests, and realtime task allocation;
 - bounded stop, resource release, and generation-aware flushing.
 
 The stable modules own stream IDs, negotiated/contracted formats, TiRTC callback copying, connection handles, session generation, and H5/AI sequencing.
 
 ## Verification loop
 
-Use a bounded loop per layer: diagnose one failing invariant, make the smallest correction, and rerun that layer before moving forward. Stop and report when the remaining failure requires unavailable hardware, credentials, a new SDK binary, a public protocol change, or a user choice.
+Use a bounded loop per layer: diagnose one failing invariant, make the smallest correction, and rerun that layer before moving forward. Change one high-risk variable per HIL comparison. Turn reusable invariants into tests or post-link gates. Stop and report when the remaining failure requires unavailable hardware, credentials, a new SDK binary, a public protocol change, or a user choice.
 
-Do not use successful compilation as evidence for camera frames, speaker output, Web rendering, AI audio, or long-run stability.
+Do not use successful compilation as evidence for camera frames, speaker output, Web rendering, AI audio, or long-run stability. Bind every runtime conclusion to the tested firmware SHA-256.