tirtc-device-builder 0.7.2 → 0.8.0

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

@@ -27,6 +27,9 @@
 | H5 live video |  |  |
 | H5 talkback |  |  |
 | AI intercom |  |  |
+| Device-to-device call |  |  |
+| WeChat VoIP |  |  |
+| Full-duplex AEC/reference path |  |  |
 
 ## Semantic build gates
 
@@ -37,6 +40,8 @@
 - Audio contract path/SHA-256: `{{AUDIO_CONTRACT}}`
 - Codec clock-table result: `{{AUDIO_CLOCK_GATE}}`
 - I2S mode/controller/slot/handoff result: `{{AUDIO_TOPOLOGY_GATE}}`
+- Simultaneous capture/playback and AEC result: `{{AEC_GATE}}`
+- Device-call/WeChat protocol and arbiter result: `{{BUSINESS_RUNTIME_GATE}}`
 - Video contract path/SHA-256: `{{VIDEO_CONTRACT}}`
 - Camera lock/PID/CPU/frame/backpressure result: `{{VIDEO_GATE}}`
 - Final ELF I2C driver-family result: `{{I2C_ELF_GATE}}`
@@ -54,7 +59,7 @@
 | L3 Online |  |  |
 | L4 Media |  |  |
 | L5 H5 |  |  |
-| L6 AI |  |  |
+| L6 AI/CALL/VOIP/AEC |  |  |
 | L7 Stability |  |  |
 
 ## Firmware and flash record

package/skills/tirtc-esp32-builder/assets/tirtc-runtime-contract.example.json

@@ -6,5 +6,18 @@
     "app_main": "main/app_main.c",
     "starter_tirtc": "components/starter_tirtc/src/starter_tirtc.c",
     "starter_runtime": "components/starter_runtime/src/starter_runtime.c"
+  },
+  "business": {
+    "features": [],
+    "protocol_revision": null,
+    "session_arbiter": {
+      "single_foreground_owner": null,
+      "pending_capacity": null,
+      "generation_guard": null,
+      "monotonic_deadlines": null,
+      "deferred_lifecycle": null,
+      "restore_h5_after_call": null
+    },
+    "implementation_assertions": []
   }
 }

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

@@ -0,0 +1,4 @@
+{
+  "schema_version": 1,
+  "boards": []
+}

package/skills/tirtc-esp32-builder/references/audio-contract.md

@@ -10,12 +10,40 @@ The contract must describe:
 
 - the PCM sample rate, MCLK ratio, resulting MCLK, and every clocked codec driver table;
 - capture/playback controller, role, and standard/TDM/DSP/PCM mode;
+- per-direction slot count and slot bit width when simultaneous directions use
+  different framing modes;
 - TDM enable, slot count/order, physical signal at each slot, selected slot, and mapping evidence when TDM is used;
 - shared clock GPIOs, whether directions are simultaneous, and the release/recreate handoff;
+- paired-channel ownership and equal BCLKs per frame when one controller runs
+  simultaneous standard TX and TDM RX;
+- when AEC is selected, the hardware sample rate plus distinct microphone and
+  playback-reference slots/signals;
 - source assertions tying the normalized contract to the actual adapter implementation.
 
 A generic header comment such as “typically 256” is not coefficient evidence. After `idf.py reconfigure` resolves managed components, the selected `(MCLK, sample rate)` pair must exist in every locked codec table named by the contract.
 
+Simultaneous directions do not have to use the same ESP-IDF mode name. A valid
+mixed-mode topology must set `shared_clock.paired_channels=true`, use the same
+controller, and provide `slot_count` plus `slot_bit_width` for both directions;
+their products must match. For example, four 16-bit TDM RX slots and two 32-bit
+standard TX slots both consume 64 BCLKs per frame. This exception does not allow
+two independent masters to drive shared clock GPIOs.
+
+For hardware-reference AEC, add `echo_cancellation` with `enabled`,
+`sample_rate_hz`, `microphone_slot`/`microphone_signal`, and
+`reference_slot`/`reference_signal`. The gate verifies that AEC runs while both
+directions are active, uses the hardware clock rate, and maps two distinct TDM
+signals. Implementation assertions must still bind the contract to the paired
+channel setup, AEC library configuration, and exact slot extraction code.
+
+AEC is not optional when Hardware IR requests `ai_talk`, `device_call`, or
+`wechat_voip`. For those features, `echo_cancellation.enabled=false`, missing
+playback-reference wiring, or non-simultaneous capture/playback is a hard
+`BLOCKED` result. Do not silently downgrade the product to push-to-talk. The
+contract verifier exports structured `simultaneous_capture_playback` and
+`echo_cancellation_enabled` results so the Hardware IR assessor enforces this
+rule rather than trusting summary text.
+
 ## Mandatory gate
 
 Run the gate before claiming an audio-capable build:
@@ -44,8 +72,10 @@ Audio reaches `BUILD_VERIFIED` only when all of these are true:
 1. the contract has at least two authoritative source IDs;
 2. its arithmetic and codec table lookups pass;
 3. its topology, TDM mapping, and handoff are internally consistent;
-4. its adapter assertions pass;
-5. the gate is part of the ordinary build;
-6. the exact BIN/ELF is hashed after that build.
+4. simultaneous mixed framing has equal BCLKs per frame and any AEC reference is
+   mapped to a distinct evidenced slot;
+5. its adapter assertions pass;
+6. the gate is part of the ordinary build;
+7. the exact BIN/ELF is hashed after that build.
 
 Compilation without this gate is `COMPILE_PASS`, not audio `BUILD_VERIFIED`.

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

@@ -0,0 +1,72 @@
+# Board knowledge and identity
+
+Use this reference when identifying a board, reusing an existing adapter, or
+capturing lessons after bring-up. The registry is curated, versioned input. It
+does not train a model or mutate an installed Skill from conversation history.
+
+## Identity boundary
+
+An ESP32 can report its SoC target, revision, Flash/PSRAM, MAC and sometimes its
+module. Board firmware can probe camera PIDs, codec chip IDs and other bus
+devices. These observations identify components, not necessarily the carrier
+board sales model, PCB marking, hardware revision, wiring, power topology or
+acoustic path. Obtain those facts from the developer and board documents.
+
+Create a project-local identity file, merge the developer declaration with safe
+read-only observations, then query the registry:
+
+```bash
+python3 <skill-dir>/scripts/board_registry.py init-identity \
+  --output <project>/board-identity.json
+python3 <skill-dir>/scripts/board_registry.py match \
+  --identity <project>/board-identity.json
+```
+
+Use only an `exact` result with `safe_registered_reuse=true` to install a saved
+adapter. `probable` can supply hypotheses while missing revision or probe facts
+are resolved. `component` can supply component-level risks and driver patterns,
+but never GPIO, clock, DMA or adapter values. A conflict creates a new variant.
+
+Exact matching requires vendor, model or alias, hardware revision, SoC/resource
+compatibility, and every probe marked `required_for_exact`. Marketing names are
+not enough because vendors may substitute sensors or codecs without renaming a
+product.
+
+## Knowledge scopes
+
+- `generic`: an ESP32/TiRTC invariant. Promote only after two independent board
+  packages support it and a focused regression test enforces it.
+- `component`: a sensor, codec, amplifier or library observation. Reuse it on a
+  different carrier only as a hypothesis until that board supplies evidence.
+- `board`: a fact for one exact package identity. Apply it only to an exact
+  match.
+
+Registry package status controls reuse:
+
+- `knowledge_only`: lessons are usable, but the normal new-board intake remains
+  mandatory.
+- `adapter_verified`: the Hardware IR, adapter, configuration and semantic
+  contracts are complete enough for the registered-board workflow.
+- `hil_verified`: the reusable package also retains artifact-bound HIL evidence.
+
+An older HIL result is provenance, not proof for a newly built artifact.
+
+## Learning loop
+
+After the final assessment, create a project-local candidate:
+
+```bash
+python3 <skill-dir>/scripts/board_registry.py candidate \
+  --hardware-ir <project>/hardware-ir.json \
+  --output <project>/board-knowledge-candidate.json
+```
+
+Review the candidate before promotion. Add exact runtime probes, copy only
+portable project-relative adapter/config/contract inputs, classify each lesson's
+scope, attach the tested artifact SHA-256 for hardware or HIL claims, and add a
+regression test for every generic invariant. Then commit it to a maintained
+registry and publish a new Skill version. An installed Skill never edits itself
+or promotes an observation automatically.
+
+Keep credentials, MAC-derived identity, device keys, Wi-Fi secrets, tokens and
+user media out of identity files, candidates and registries.

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

@@ -9,7 +9,16 @@ Run `hardware_ir.py assess --phase intake --strict` before generation. Hardware
 | `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 |
+| `ai_talk` | A-law 8 kHz microphone and speaker paths for AI stream 1, started only after `start_session`; simultaneous capture/playback, physical reference, enabled AEC, audio ownership/channel mapping and memory budget resolved |
+| `device_call` | Device-call protocol and arbiter contract plus simultaneous A-law capture/playback, physical reference and enabled AEC |
+| `wechat_voip` | WeChat VoIP protocol and arbiter contract plus simultaneous A-law capture/playback, physical reference and enabled AEC |
+
+`ai_talk`, `device_call`, and `wechat_voip` are AEC-required features. They are
+`BLOCKED` when the board cannot capture a playback reference, cannot keep RX/TX
+active together, or has no evidenced AEC implementation. At build time the audio
+contract must explicitly report both simultaneous directions and enabled AEC;
+generic full-duplex labels, a software flag without reference routing, or a
+half-duplex fallback do not satisfy the gate.
 
 Hardware identity, wiring, the selected media contract, and the adapter/resource design must be at least `corroborated` to become `READY_TO_PORT`. At intake, `available=true` means a pinned source path can implement the selected profile; it does not claim that the final adapter or physical media path has run. Implementation composition, final ELF policy, runtime memory margin, browser media, and stability belong to the build or HIL phases.
 
@@ -45,6 +54,7 @@ SoftAP is one Wi-Fi option, not a universal requirement. BLE, SmartConfig, facto
 - 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 contract change across the server and consumers.
 - Start AI media only after the successful `start_session` response; stop and flush media before disconnecting.
+- Route AI, device-call and WeChat VoIP through the same foreground-session arbiter and keep AEC active for the entire simultaneous capture/playback interval.
 - 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 --phase hil --artifact-sha256 <sha>`; documentation verification alone never becomes v2 `HIL_VERIFIED`.

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

@@ -48,6 +48,19 @@ For an explicitly selected legacy workspace, omit `--expected-kit`; otherwise re
 
 The default managed root is `<setup-root>/kits/esp32s3/<kit-version>`. The public ThingConnect workspace remains an optional legacy/development input; the doctor accepts either a Device Kit root, a repository root, or its `thing-connect/` child.
 
+The managed Kit currently contains the ESP32-S3 H5/AI starter. When the requested
+portfolio includes device-to-device calling or WeChat VoIP and the selected Kit
+does not contain `device-sim-c`, `device-call.md`, `device-voip.md`, and the API
+reference, use a full `tirtc-server-example` checkout pinned to a recorded commit
+for the simulator and porting source. Cloning is an external write and requires
+user authorization. Do not track a moving default branch as build evidence.
+
+ESP32-P4 uses a separate `espressif_esp32p4` SDK archive and RISC-V toolchain.
+The managed setup does not install that archive or generate a P4 starter. A P4
+task therefore needs an explicit BSP/network project plus the exact P4 SDK and
+`manifest/build-contract.env`; run Doctor with `--target esp32p4` and never accept
+the packaged S3 archive as a compatible fallback.
+
 SDK resolution is independent after generation: an explicit `--sdk-dir` wins, followed by `<project>/third_party/tirtc`, then the SDK packaged in the resolved Device Kit or legacy workspace. The generated project remains diagnosable after it is moved away from the Kit.
 
 Before copying a generated project to another machine, run:
@@ -58,6 +71,13 @@ python3 <skill-dir>/scripts/project_portability.py <generated-project> --export
 
 Copy source inputs only. Never export `build/`: CMake caches absolute source, toolchain, and Python paths from the originating machine. `managed_components/` may be regenerated from the committed `dependencies.lock`; the bundled `third_party/tirtc` SDK and its build contract must remain in the source package. CMake must invoke shell gates through `bash <script>` so the build does not depend on archive- or filesystem-specific executable bits.
 
+The export check also requires Hardware IR, every requested-feature semantic
+contract, `sdkconfig.defaults`, a referenced custom partition table, and each
+artifact retained in `build_evidence.artifacts[]`. Inside a Git worktree these
+inputs must not be untracked files hidden by `.gitignore`. Ignore local build
+trees and intermediate firmware snapshots, then explicitly include the exact
+validated release bundle used by retained evidence.
+
 ## Required checks
 
 - `python3`, `git`, `idf.py`, and the target compiler are available in the active shell;

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

@@ -10,6 +10,11 @@ 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.
 
+Schema v1 cannot represent an MJPEG/H.265 selection, semantic-contract paths,
+or artifact-bound v2 HIL. If an existing v1 project requests H5 video without
+an available H.264 path, migrate it to v2 rather than interpreting the legacy
+H.264 assessment failure as a board or platform codec failure.
+
 ## Evidence rules
 
 - Give every source a stable `id`, `kind`, `location`, and revision when available.
@@ -37,16 +42,23 @@ The IR contains:
 - 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;
+- `hardware_resources` for I2C, I2S/GPIO ownership, audio channel mapping,
+  full-duplex/AEC capability, camera realtime policy, and memory budget;
 - project-relative `hardware_resources.audio_semantic_contract` for every project requesting audio;
 - project-relative `hardware_resources.video_semantic_contract` for every project requesting video;
-- project-relative `hardware_resources.runtime_semantic_contract` for every generated H5/AI project;
+- project-relative `hardware_resources.runtime_semantic_contract` for every generated H5/AI/call/VoIP project;
 - `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.
 - `build_evidence.artifacts[]` containing each accepted BIN/ELF path, byte size, and full SHA-256.
 
+When `ai_talk`, `device_call`, or `wechat_voip` is requested,
+`hardware_resources.duplex_audio` must establish simultaneous capture/playback,
+an actual playback-reference signal, and an AEC implementation. Unknown values
+remain `NEEDS_CONFIRMATION`; a confirmed missing value is `BLOCKED`. Build/HIL
+assessment also requires the project audio semantic gate to prove enabled AEC.
+
 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.
@@ -72,7 +84,9 @@ python3 <skill-dir>/scripts/hardware_ir.py assess hardware-ir.json \
   --phase hil --artifact-sha256 <64-character-sha256> --strict
 ```
 
-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.
+H5 features require matching L5 evidence; AI, device-call and WeChat VoIP
+require matching L6 evidence. Evidence from an older firmware remains
+provenance but does not verify the current artifact.
 
 ## Intake quality
 

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

@@ -13,6 +13,17 @@ Record the selected video profile, audio formats and stream IDs, duplex/AEC poli
 - 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.
 
+Distinguish the camera driver's event task from an adapter-owned software
+JPEG/H.26x task. Core isolation of the driver does not prove that a CPU-bound
+encoder is isolated. On ESP32-S3, code using floating point can cause an
+unpinned task to become pinned to the first core where it uses the FPU; AEC and
+other DSP tasks therefore need intentional affinity when they would otherwise
+land on the Wi-Fi core. A DMA-fed loop or software encoder that can remain
+continuously runnable must block on a queue/semaphore or yield at a bounded
+frame boundary. Keep the idle-task watchdog enabled, and expose maximum
+processing time plus deadline misses instead of hiding starvation by widening
+or disabling the watchdog.
+
 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
@@ -38,6 +49,13 @@ Platform service discovery and the TiRTC SDK service endpoint are different sett
 
 Define a conservative static budget before implementation using the locked SDK contract, framebuffer geometry, DMA/queue bounds, task stacks, and an internal-memory reserve. Before claiming runtime margin or tuning TiRTC buffers, measure internal free/largest blocks, PSRAM, frame size distribution, queue watermarks, and send/drop rates on the exact artifact. 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.
 
+Treat PSRAM framebuffer placement, direct peripheral DMA into PSRAM, and an
+internal-DMA staging buffer as three separate facts. PSRAM capacity does not
+prove DMA compatibility or frame integrity for a sensor/pixel format. Promote
+direct PSRAM DMA only after artifact-bound HIL checks image boundaries and line
+integrity; otherwise retain the evidenced staging path and budget its internal
+DMA reserve explicitly.
+
 ## 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.
@@ -47,3 +65,10 @@ Confirm SDK send return semantics and callback payload lifetimes from the select
 ## 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.
+
+Local intermediate snapshots may be ignored, but the Hardware IR, semantic
+contracts, `dependencies.lock`, custom partition input, and the artifact named
+by retained build evidence must survive the chosen export mechanism. Broad
+`*.json`, `*.csv`, or `artifacts/` ignore rules are invalid when they hide an
+untracked required input; `project_portability.py --export` checks this when the
+project is inside a Git worktree.

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

@@ -13,7 +13,7 @@ Use [the report template](../assets/report-template.md) and preserve separate `P
 | L3 Online | Wi-Fi provisioning, binding, MQTT, and TiRTC reach ready state |
 | L4 Media | Camera/microphone/speaker local paths work and counters/measurements are captured |
 | L5 H5 | Browser receives the declared video/audio and talkback reaches the device |
-| L6 AI | Token, WHIP, `start_session`, bidirectional audio, stop, and H5 recovery work |
+| L6 Sessions | AI, device-call and WeChat VoIP requested flows work; simultaneous capture/playback, AEC/double-talk, stop, timeout and H5 recovery are observed separately |
 | L7 Stability | Requested weak-network, repeated-session, resource, and soak criteria pass |
 
 Run and record the intake assessment before L0, the build assessment with `--project` and the exact artifact SHA-256 at L1, and the HIL assessment only when matching runtime evidence exists. Before assessment, copy final deliverable BIN/ELF files to project-relative `artifacts/` paths and record their actual byte size and SHA-256 in `build_evidence.artifacts[]`; the assessor reopens the file and rejects stale metadata. Missing serial or browser access is a `SKIP` for the affected L2-L7 levels, not an L0/L1 failure.

package/skills/tirtc-esp32-builder/references/runtime-contract.md

@@ -1,6 +1,6 @@
 # TiRTC runtime protocol contract
 
-Use this gate for every generated H5/AI project. It verifies protocol behavior that is
+Use this gate for every generated H5/AI/call/VoIP project. It verifies protocol behavior that is
 neither a board clock fact nor a camera fact: service discovery wiring, SDK callback
 lifecycle, stream/media metadata, and AI session negotiation.
 
@@ -30,5 +30,15 @@ The gate requires all of the following:
 - AI media starts only after a matching response provides a non-empty session ID and
   authoritative input/output audio formats matching the implemented codec;
 - remote `end_session` converges through the runtime control task.
+- requested device-call/WeChat VoIP endpoints, MQTT event names, `call`/`wxcall`
+  commands and their pinned `tirtc-server-example` protocol revision are present
+  in implementation files;
+- one foreground-session arbiter owns STREAM/AI/CALL/VOIP state, allows one
+  pending request, rejects stale generations, uses monotonic deadlines, defers
+  lifecycle work outside callbacks and restores H5 after foreground calls.
 
-Compilation without this gate is not an H5/AI `BUILD_VERIFIED` result.
+For device-call or WeChat VoIP, populate the example contract's `business`
+section. An empty `business.features` list remains valid for H5/AI-only projects,
+but cannot satisfy Hardware IR that requests `device_call` or `wechat_voip`.
+
+Compilation without this gate is not an H5/AI/call/VoIP `BUILD_VERIFIED` result.

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

@@ -0,0 +1,92 @@
+# TiRTC and ThingConnect platform contract
+
+Read this reference when integrating the C SDK, selecting an ESP32 target, or
+implementing H5, AI, device-call or WeChat VoIP.
+
+## Authoritative sources
+
+- TiRTC documentation: <https://docs.tange.ai/products/tirtc/>
+- C API: <https://docs.tange.ai/products/tirtc/api-reference/c.html>
+- C SDK integration: <https://docs.tange.ai/products/tirtc/guides/sdk-integration/c.html>
+- ESP32-S3 notes: <https://docs.tange.ai/products/tirtc/guides/integration-notes/espressif/esp32-s3.html>
+- ESP32-P4 notes: <https://docs.tange.ai/products/tirtc/guides/integration-notes/espressif/esp32-p4.html>
+- ThingConnect reference platform: <https://github.com/tangeai/tirtc-server-example>
+- Demo platform: <https://demo-open.tange-ai.com/>
+
+Use the locked SDK header/build contract and a pinned ThingConnect commit during
+generation. Public pages explain the contract but do not replace the exact files
+used by a build.
+
+## SDK lifecycle
+
+TiRTC is one process-wide runtime. The exact selected header governs API and
+option availability. For SDK 2.3.0 the important order is:
+
+1. Set `TIRTC_OPT_MAX_SEND_BUFFER` before `TiRtcInit()` when overriding it.
+2. Call `TiRtcInit()` once.
+3. Set `TIRTC_OPT_DEVICE_SECRET_KEY`, `TIRTC_OPT_CLIENT_ID`, the discovered
+   service endpoint, and applicable network options before `TiRtcStart()`.
+4. Call `TiRtcStart(device_id, &callbacks)` once and wait for
+   `TIRTC_EVENT_SYS_STARTED`; return value zero only accepts the request.
+5. Establish or accept connections, then use `TiRtcSendVideoStream()` and
+   `TiRtcSendAudioStream()` with the selected complete-frame contract.
+6. Stop sessions and connections through deferred lifecycle work before the one
+   final `TiRtcStop()` / `TiRtcUninit()` sequence.
+
+The callback table and its context outlive the SDK runtime. Callback payloads
+are borrowed; copy required data into bounded application-owned storage before
+returning.
+
+## Product features
+
+### H5 live view and talkback
+
+The device starts as a listener, accepts the H5 connection, sends the selected
+audio/video streams, receives talkback, and handles refresh/key-frame requests.
+Browser rendering and audible talkback are HIL evidence.
+
+### AI intercom
+
+Obtain the current AI connection parameters, connect, send `start_session`,
+validate the authoritative session ID and input/output formats, then start
+media. Remote or local `end_session` converges through the runtime task and
+restores the H5 baseline.
+
+### Device-to-device call
+
+Follow the pinned `device-call.md`: contact authorization, `POST
+/v1/call/request`, incoming MQTT routing, accept through `POST
+/v1/call/device/info`, reject/cancel/hangup, room recovery and `TiRtcConnect`.
+Expose `call <device_id> [video|audio]` only after those paths and conflict rules
+are implemented.
+
+### WeChat VoIP
+
+Follow the pinned `device-voip.md`: report the device media profile, maintain the
+authorized contact list, route WeChat MQTT events, and use `POST
+/v1/voip/device/call` for device-originated calls. `wxcall [N] [video|audio]`
+selects an authorized contact; it is not a direct SDK API. Mini-program
+authorization and plugin behavior are separate platform acceptance evidence.
+
+## Simulator before hardware
+
+For the four-feature portfolio, use the pinned Linux C reference implementation
+with file-backed media to prove platform credentials, HTTP/MQTT fields,
+connection tokens, commands and the session arbiter before replacing media with
+board drivers. Record this separately from ESP32 L1-L7 evidence.
+
+The managed ESP32-S3 starter may expose fewer businesses than the full reference
+repository. Missing generated modules are implementation work, not permission to
+drop a requested feature or call it verified.
+
+## ESP32 targets
+
+The current managed generator and Device Kit automate ESP32-S3. Official SDK
+2.3.0 also provides a distinct ESP32-P4 package. P4 needs ESP-IDF 5.5.4, matching
+RISC-V toolchain/build contract, PSRAM, and an evidenced network path such as
+ESP-Hosted with C6/C61 or Ethernet. P4 and S3 archives are not interchangeable.
+
+Use FreeRTOS tasks, bounded queues and explicit memory capabilities. PSRAM is
+suitable for large media, fixed pools and eligible background stacks; internal
+RAM remains necessary for DMA descriptors/buffers, ISR-visible state, control
+objects and allocations required while flash cache is unavailable.

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

@@ -4,13 +4,18 @@
 
 ### Registered board
 
-Use this branch when a board and exact hardware revision already have a Hardware IR plus a matching board media adapter.
-
-1. Validate and assess the saved Hardware IR against the requested features.
-2. Confirm that its BSP, ESP-IDF, TiRTC SDK, and adapter revisions are still resolvable.
-3. Generate a new starter project without overwriting an existing path.
-4. Install the matching board adapter and configuration overlay.
-5. Build, optionally flash, execute the requested acceptance levels, and issue a fresh report.
+Use this branch only when `board_registry.py match` returns `exact` with
+`safe_registered_reuse=true` and the package has a Hardware IR plus matching
+board adapter.
+
+1. Recheck every required runtime probe and reject a changed sensor/codec as a
+   new variant.
+2. Validate and assess the saved Hardware IR against the requested features.
+3. Confirm that its BSP, ESP-IDF, TiRTC SDK, business protocol, and adapter
+   revisions are still resolvable.
+4. Generate a new starter project without overwriting an existing path.
+5. Install the matching board adapter and configuration overlay.
+6. Build, optionally flash, execute the requested acceptance levels, and issue a fresh report.
 
 The branch is complete when the new run has its own build and verification evidence; an older board report is provenance, not proof of the new artifact.
 
@@ -18,7 +23,10 @@ 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.
+1. Create `board-identity.json`, combine the developer's full model/PCB marking
+   with safe SoC/component probes, and query the board registry. Treat different
+   revisions or conflicting required probes as different variants. A probable
+   or component match supplies hypotheses only.
 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.
@@ -46,13 +54,16 @@ Read only the documents for the active branch, but read each selected document c
 - ESP32 starter or adapter work: `device-sim/device-sim-esp32/README.md`, `device-sim/ESP32_STARTER.md`, the selected SDK package README, and the generated template README.
 - H5 live view or talkback: `device-h5-live.md`.
 - AI intercom: `device-ai.md`.
+- Device-to-device call: `device-call.md` and the applicable API reference.
+- WeChat VoIP: `device-voip.md`, the mini-program integration document, and the
+  applicable API reference.
 - H5/AI switching, delayed callbacks, ownership, or timeouts: `device-session-model.md` and `device-session-arbiter.md`.
 - Onboarding, binding, MQTT, token, or identity: `device-integration.md`.
 - Public HTTP field or error changes: `api-reference.md` and `error-response-policy.md`.
 
 ## Generation and board seam
 
-The runtime-facing `starter_media` interface stays stable. A reusable board integration should implement an internal `BoardMediaAdapterV1`-style adapter owned by `starter_media` rather than editing H5, AI, `starter_runtime`, or `starter_tirtc` for each board.
+The runtime-facing `starter_media` interface stays stable. A reusable board integration should implement an internal `BoardMediaAdapterV1`-style adapter owned by `starter_media` rather than editing H5, AI, CALL, VOIP, `starter_runtime`, or `starter_tirtc` for each board.
 
 The adapter owns:
 
@@ -62,13 +73,22 @@ The adapter owns:
 - 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 the discovered TiRTC service endpoint, stream IDs, negotiated/contracted formats, TiRTC callback copying, connection handles, session generation, and H5/AI sequencing. SDK lifecycle changes such as disconnect run in a worker/state-machine context, never directly inside an SDK callback.
+The stable modules own the discovered TiRTC service endpoint, stream IDs,
+negotiated/contracted formats, HTTP/MQTT business fields, TiRTC callback copying,
+connection handles, pending calls, monotonic deadlines, session generation, and
+H5/AI/CALL/VOIP sequencing. SDK lifecycle changes such as disconnect run in a
+worker/state-machine context, never directly inside an SDK callback.
 
 ## Verification loop
 
 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.
 
-For every generated H5/AI project, validate `tirtc-runtime-contract.json` and run `install_runtime_gate.py <project>` before the ordinary build. Audio and video projects additionally install their media gates. A build that bypasses any applicable gate is not `BUILD_VERIFIED`.
+For every generated H5/AI/call/VoIP project, validate `tirtc-runtime-contract.json` and run `install_runtime_gate.py <project>` before the ordinary build. Audio and video projects additionally install their media gates. AI/call/VoIP also require the full-duplex AEC result from the audio gate. A build that bypasses any applicable gate is not `BUILD_VERIFIED`.
+
+When CALL or VOIP is requested, the runtime contract must also bind the project
+to the pinned business protocol and unified session arbiter. First prove those
+flows with the Linux C simulator. Simulator success establishes the protocol
+baseline but cannot replace the ESP32 build or HIL levels.
 
 Run the assessor once per layer: