tirtc-device-builder 0.11.3 → 0.11.5

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.11.3",
-  "description": "Codex workflows for building and validating TiRTC device firmware across supported chip platforms.",
+  "version": "0.11.5",
+  "description": "Codex workflows for building, validating, and documenting TiRTC device firmware across supported chip platforms.",
   "author": {
     "name": "TangeAI",
     "url": "https://github.com/tangeai"
@@ -34,7 +34,8 @@
       "Analyze my ESP32 board and generate a TiRTC project.",
       "Probe my BK7258 or BK7259 board and assess XiaoTai capabilities.",
       "Check ESP-IDF and build my TiRTC ESP32 firmware.",
-      "Assess whether this board can support H5 live view and AI intercom."
+      "Assess whether this board can support H5 live view and AI intercom.",
+      "Create a user-facing documentation system for my multi-board TiRTC project."
     ]
   }
 }

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 This project follows Semantic Versioning.
 
+## 0.11.5
+
+- Add the `tirtc-project-docs` Skill for designing and reviewing public
+  documentation in multi-board TiRTC and XiaoTai repositories.
+- Define stable roles for quick-start, architecture, contribution, board and
+  media documents, with evidence grading and approval-first bilingual output.
+- Add `install docs` support and package tests for installing the documentation
+  Skill across supported Agent clients.
+
+## 0.11.4
+
+- Add artifact-bound BK7258 H5, AI and WeChat VoIP media lessons: directional
+  capability reporting, 10/11 versus 14/15 STREAM routing, VoIP stream 0,
+  AI stream 1 with 16 kHz Opus, negative-on-failure SDK return semantics and
+  mode-specific uplink readiness gates.
+- Require PCM-domain AEC from the real post-volume DAC reference for all
+  speakerphone full-duplex modes, plus routing/AEC diagnostics, double-talk HIL,
+  reference FIFO health and measured codec-task stack headroom.
+- Update the validated BK7258 identity to the TiRTC-Nano 2.5.0 artifact and add
+  package validation that prevents these media invariants disappearing.
+
 ## 0.11.3
 
 - Add a complete Beken onboarding path to the public README: Skill installation,

package/README.md

@@ -2,12 +2,13 @@
 
 TiRTC Device Builder 用于把 ESP32-S3/ESP32-P4 和 BK7258/BK7259 开发板接入 TiRTC。输入可以只有开发板型号，也可以包含原理图、BSP、引脚表和外设示例。安装后的 Agent Skill 会先检查环境、整理有依据的硬件事实，再生成或移植独立工程并完成板级适配和编译。烧录和实机验证只有在开发者明确给出目标串口并授权后才会执行。
 
-当前仓库提供两个平台 Skill：
+当前仓库提供两个平台 Skill 和一个项目文档 Skill：
 
 | Skill | 平台 | 主要用途 |
 |---|---|---|
 | `tirtc-esp32-builder` | ESP32-S3 / ESP32-P4、ESP-IDF 5.5.x | 板型识别、Hardware IR、工程生成/移植、H5/AI/设备互呼/微信 VoIP、AEC 门禁、编译烧录和分层验收 |
 | `tirtc-beken-builder` | BK7258 / BK7259、Beken Armino | 运行时硬件探测、显示/触摸/音频/内存能力判定、小钛业务移植与实机验收 |
+| `tirtc-project-docs` | TiRTC / 小钛多开发板项目 | 快速体验、架构、贡献、板卡、构建烧录和音视频参数文档；中文版确认后同步英文版 |
 
 BK7258 多媒体项目固定从 Beken 官方 Gitee `bk_avdk_smp` 的
 `release/v3.1.1.8` tag、commit
@@ -108,6 +109,19 @@ npx --yes tirtc-device-builder@latest doctor beken \
 其中 BK7258 的公开基准应是 `release/v3.1.1.8`、commit
 `1cfd56af09a3cb6470f35f1e0c604035ed1b6ee7`。
 
+#### 项目文档
+
+需要建立、检查或维护 TiRTC/小钛项目文档时，安装
+`tirtc-project-docs`：
+
+```bash
+npx --yes tirtc-device-builder@latest install docs
+```
+
+该 Skill 会先按仓库事实整理中文版，检查根文档导航、板卡目录、构建烧录说明、
+媒体参数和证据等级。只有中文版确认通过后，才同步生成英文版。它不会把日期型排障
+记录或迁移历史混入对外使用手册。
+
 ### 3. 重新打开 Agent 客户端
 
 Skill 通常在 Agent 会话启动时被发现。安装完成后，关闭当前会话，再打开一个新会话。

package/bin/tirtc-device-builder.js

@@ -48,6 +48,14 @@ const PLATFORMS = new Map([
       summary: "BK7258 / BK7259 / Beken Armino",
     },
   ],
+  [
+    "docs",
+    {
+      aliases: new Set(["docs", "documentation", "tirtc-project-docs"]),
+      skill: "tirtc-project-docs",
+      summary: "TiRTC / XiaoTai project documentation",
+    },
+  ],
 ]);
 
 function printHelp() {
@@ -56,19 +64,21 @@ function printHelp() {
 Usage:
   tirtc-device-builder list
   tirtc-device-builder clients
-  tirtc-device-builder install <platform> [--client <name>] [--skills-dir <path>] [--force]
+  tirtc-device-builder install <target> [--client <name>] [--skills-dir <path>] [--force]
   tirtc-device-builder setup <platform> [setup options]
   tirtc-device-builder doctor <platform> [doctor options]
   tirtc-device-builder boards <platform> <list|validate|match|init-identity|candidate> [options]
   tirtc-device-builder --version
 
-Platforms:
+Install targets:
   esp32       ESP32-S3 / ESP-IDF 5.5.x
   beken       BK7258 / BK7259 / Beken Armino
+  docs        TiRTC / XiaoTai project documentation
 
 Examples:
   npx tirtc-device-builder install esp32
   npx tirtc-device-builder install beken
+  npx tirtc-device-builder install docs
   npx tirtc-device-builder install esp32 --client qwen-code
   npx tirtc-device-builder setup esp32
   npx tirtc-device-builder setup esp32 --install --client gemini
@@ -274,9 +284,15 @@ function main(args) {
   }
 
   if (command === "doctor") {
+    if (platform.name === "docs") {
+      return fail("doctor is not available for target: docs");
+    }
     return runDoctor(platform, rest);
   }
   if (command === "boards") {
+    if (platform.name === "docs") {
+      return fail("boards is not available for target: docs");
+    }
     return runBoardRegistry(platform, rest);
   }
   if (command === "setup") {

package/package.json

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

package/skills/tirtc-beken-builder/VERSION

@@ -1 +1 @@
-0.11.3
+0.11.5

package/skills/tirtc-beken-builder/references/lckfb-bk7258-lessons.md

@@ -1,7 +1,7 @@
 # LCKFB BK7258 XiaoTai lessons
 
 Use this case study for BK7258 XiaoTai/TiRTC ports and reviews. It distils the
-failures fixed in `lckfb-bk7258-xiaotai` through source commit `8a156ff`. These
+failures fixed in `lckfb-bk7258-xiaotai` through source commit `05d3180`. These
 are gates, not a generic board profile: retain the decisions, but use the exact
 numbers only when the target matches the identity below.
 
@@ -14,9 +14,11 @@ The reproducible public SDK baseline is:
   `release/v3.1.1.8`, commit
   `1cfd56af09a3cb6470f35f1e0c604035ed1b6ee7`;
 - GCC Arm None EABI 10.3.1, Cortex-M33, hard-float;
-- TiRTC-Nano 2.3.0 `mini`, BK7258 hard-float archive;
-- TiRTC build metadata reporting Mbed TLS 2.25.0, linked with the project's
-  BK7258 Mbed TLS 2.28.5 compatibility archive;
+- TiRTC-Nano 2.5.0 `mini`, BK7258 hard-float archive, SHA-256
+  `47e26827ca2419084163e3656dca4d6e508e433381784e9c03f232d3dbaa4171`;
+- TiRTC SSL and DTLS disabled for the validated deployment, with remaining
+  crypto references resolved by the SDK PSA Mbed TLS 3.5.2 component and no
+  application-vendored compatibility archive;
 - AP + CP + bootloader package and 16 MiB PSRAM.
 
 The locally delivered folder named `bk_avdk_smp_v3.1.1.8_20260605` contains a
@@ -25,11 +27,13 @@ project configuration. It is useful only as implementation and fault-history
 evidence. Do not identify it as the public tag, use it for SDK checksums, or make
 it the default Kit source.
 
-Hash the TiRTC and compatibility archives and record the SDK commit, compiler,
+Hash every TiRTC or compatibility archive actually linked and record the SDK commit, compiler,
 float ABI, libc/RTOS and partition maps. AP-only or CP-only output is diagnostic;
 the deliverable is the combined package. A different value makes a new artifact
-that must pass link, DTLS/WHIP and hardware validation again. Disable the SMP
-SDK's ABI-incompatible PSA Mbed TLS 3 path when using this TiRTC package.
+that must pass link, signaling/WHIP and hardware validation again. Do not infer
+a TLS recipe from the version name: the older 2.3.0 artifact required a separate
+compatibility choice, while this validated 2.5.0 artifact uses the SDK PSA path
+with TiRTC SSL/DTLS disabled.
 Treat the AP and CP CMake caches as part of the SDK identity: both the cached
 toolchain path and `beken-armino_SOURCE_DIR` must point inside the selected
 official checkout. Reject or clean a cache created by the local modified SDK;
@@ -91,8 +95,8 @@ hardware:
   `webclient_post(..., NULL, 0)` also requires explicit response handling;
 - configure the send buffer before `TiRtcInit`, initialize/start one TiRTC
   process, and pass SDK option string lengths with the exact convention used by
-  the matching headers/reference. For TiRTC 2.3.0 here, string lengths exclude
-  the trailing NUL;
+  the matching headers/reference; lock the convention with the selected archive
+  instead of carrying a value from an older delivery;
 - treat a positive `TIRTC_OPT_TGTRP_POLL_TIMEOUT` return as the applied timeout,
   not a failure. A false retry loop repeatedly initialized/uninitialized SDK
   task state;
@@ -110,10 +114,51 @@ it. Do not generalize this case study into a universal plain-transport rule.
 
 ## Media and capability gate
 
-The demonstrated audio contract is 8 kHz, 16-bit mono PCM with 20 ms TiRTC
-G.711 A-law packets; the board path may capture/play in larger chunks. SDK
-callbacks enqueue bounded copies and return. A camera-start failure degrades
-video while leaving an otherwise valid audio session active.
+Build an explicit matrix per product mode. The 2026-09-29 validated BK7258
+contract is:
+
+| Mode | Device uplink | Device downlink/subscription | Codec | Uplink gate |
+|---|---|---|---|---|
+| H5 STREAM | audio 10, video 11 | audio 14, video 15 | G.711 A-law, 8 kHz mono | local uplink subscription state |
+| AI | audio 1 | audio 1 | Opus, 16 kHz mono, 20 ms/320 samples | accepted `start_session` |
+| WeChat VoIP | audio 0, video 1 | audio 0, video 1 | G.711 A-law, 8 kHz mono; video not advertised here | protocol call-active state |
+
+These stream IDs are a product/platform contract, not universal TiRTC defaults.
+Verify them against the live profile API and official protocol before reuse.
+Report the complete directional snapshot with `POST /v1/device/profile` before
+sessions and after authenticated reconnect. Sending the locally advertised
+stream does not imply subscribing to that same number: H5 publishes audio 10
+but subscribes to browser talkback audio 14. VoIP publishes and receives audio
+0 and must not wait for an optional H5-style subscription callback once the
+business protocol has entered call-active state.
+
+Treat TiRTC media and subscription API return values as negative-on-failure
+unless the pinned API explicitly documents stricter semantics. Positive returns
+were valid success values in this integration; checking `rc != 0` produced
+false failures and muted paths.
+
+SDK callbacks enqueue bounded copies and return. Prewarm the Opus codec,
+playback, capture and queues before AI `start_session`, but gate microphone
+uplink until the matching acceptance. Retain asynchronous peer descriptors and
+tokens until callbacks complete.
+
+AEC is a PCM pipeline property, not an Opus-only feature. Enable it for every
+speakerphone full-duplex mode that has a playback reference. Feed the
+post-volume PCM actually written to DAC into a bounded reference FIFO and
+process aligned 20 ms microphone blocks. Validate far-end-only, near-end-only
+and double-talk cases; reference underruns or overruns are release evidence,
+not harmless counters. On this BK7258 port Opus encode/decode UsageFaults were
+eliminated only after placing measured 40 KiB task stacks in PSRAM; carry the
+stack size and high-water evidence rather than the number alone.
+
+For one-way audio or echo, add bounded diagnostic logs that correlate mode,
+generation, actual/expected stream ID, packet cadence, mic/reference/output
+energy, AEC residual ratio and reference FIFO under/overruns. Reject or count
+unexpected streams explicitly. Do not tune AEC until routing and reference
+continuity are proven.
+
+A camera-start failure degrades video while leaving an otherwise valid audio
+session active.
 
 BK7258 provides H.264 encoding but no demonstrated H.264 hardware decoder. The
 AVDK virtual H.264 decoder is NAL inspection/logging, not decoded video. The
@@ -134,12 +179,17 @@ Require a host contract test plus artifact-bound HIL. At minimum verify:
 - exact archive hashes, ABI/config/partition invariants and AP-only TiRTC
   ownership;
 - provisioning, binding, clock, signed login and one complete capability report;
-- first uplink/downlink audio frames and first H.264 frame;
+- the exact mode matrix in the reported profile plus actual/expected stream
+  diagnostics; first uplink/downlink audio frames and first H.264 frame;
+- H5 full duplex on 10/14, AI Opus full duplex on 1, and VoIP full duplex on 0;
+- far-end-only, near-end-only and double-talk AEC evidence using the real DAC
+  reference, with bounded underrun/overrun counts;
 - ten AI enter/exit cycles after background polling starts, with no UsageFault,
   HardFault, reboot, leaked media owner or permanent busy state;
 - camera failure with audio preserved, two consecutive remote-view sessions,
   connect/confirmation timeouts and late-callback rejection;
-- minimum/largest internal heap during DTLS, camera and full-duplex overlap.
+- minimum/largest internal heap and task stack high-water during signaling,
+  Opus/AEC, camera and full-duplex overlap.
 
 Use conventional `ERROR`, `WARN`, `INFO`, `DEBUG` levels. The checked-in
 development configuration defaults to `DEBUG` and prints complete HTTP, MQTT

package/skills/tirtc-esp32-builder/VERSION

@@ -1 +1 @@
-0.11.3
+0.11.5

package/skills/tirtc-project-docs/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: tirtc-project-docs
+description: Design, audit, and maintain bilingual documentation systems for TiRTC or XiaoTai multi-board firmware repositories. Use for quick-start READMEs, architecture and contribution guides, board catalogs, build/flash instructions, media parameters, navigation/link checks, or Chinese-to-English synchronization; exclude code-only work and historical status logs.
+---
+
+# TiRTC Project Documentation
+
+Build a documentation system that lets a first-time user run the product, lets
+a developer extend it, and gives an agent reliable pointers into repository
+truth. Documentation describes the current product and supported workflows;
+dated investigations and migration diaries belong in an ignored local history
+area when the repository defines one.
+
+## Establish the contract
+
+1. Read repository guidance such as `AGENTS.md`, the existing documentation
+   index, glossary, documentation contract, board architecture, and build/test
+   entrypoints. Project rules override this Skill.
+2. Inventory existing public documents before adding files. Preserve useful
+   paths and repair their role when possible; do not create a parallel document
+   tree for the same audience.
+3. Identify the requested phase: Chinese drafting, Chinese review, English
+   synchronization, or audit. When the user requests Chinese approval first,
+   stop after the verified Chinese result. Do not create English placeholders.
+4. Map every technical claim to a source. Read
+   [evidence and technical claims](references/evidence.md) when the work covers
+   hardware, media, tools, builds, releases, or validation status.
+
+## Select the document layer
+
+Read [document architecture](references/document-architecture.md) when adding,
+splitting, renaming, or reorganizing documents.
+
+- Root `README.md` is the quick-experience path: identify the board, download
+  the matching release artifact, flash it safely, provision it, and try the
+  principal product flows.
+- Root `ARCHITECTURE.md` explains product capabilities, module interfaces,
+  runtime/media flows, repository responsibilities, and secondary-development
+  entrypoints for both humans and agents.
+- Root `CONTRIBUTING.md` explains environment setup, tests, evidence, adding a
+  board or platform, and the submission workflow.
+- `docs/README.md` is the complete task-oriented index.
+- `docs/boards/README.md` catalogs every board; each board has one independently
+  usable guide under `docs/boards/<board-id>/README.md`.
+- Product, development, and board details stay in their subject directories.
+  Root documents summarize and link instead of copying those details.
+
+Keep a compact navigation line at the top of every public root document. Every
+link must resolve from that file, and all root documents must expose the same
+destinations in the same order.
+
+## Draft from repository truth
+
+Write the minimum information needed at the selected layer. Prefer stable
+interfaces, responsibilities, commands, and decision points over source-tree
+tourism. Explain an unavoidable acronym on first use. Keep one topic per
+paragraph and make commands, warnings, status, and next actions easy to scan.
+
+Use available specialist Skills when they materially apply:
+
+- `research` for facts that require official external sources and citations;
+- `codebase-design` for module interfaces, seams, adapters, and extension paths;
+- `domain-modeling` when canonical terms are missing or conflict;
+- `writing-for-agents` for `AGENTS.md`, Skill instructions, and agent-facing
+  pointers;
+- `humanizer-zh` as the final Chinese prose review after facts are stable.
+
+Their absence must not block ordinary maintenance. Preserve the same outcomes:
+primary sources, explicit interfaces, consistent terms, actionable pointers,
+and natural restrained Chinese.
+
+## Verify before translation
+
+Check every changed command against current scripts or `--help`, every local
+link against the filesystem, every board identifier against its manifest, and
+every download/flash instruction against the release artifact manifest. Run the
+repository's documentation, manifest, and host-test gates. A passing structure
+test does not upgrade build evidence into hardware proof.
+
+Review the Chinese documents for facts, terminology, navigation, paragraph
+shape, and duplicated sources of truth. Present the Chinese result for approval
+when requested. Completion for this phase means all requested Chinese documents
+and checks are complete, with English files still untouched.
+
+## Synchronize English after approval
+
+Read [bilingual synchronization](references/bilingual.md) only after the
+Chinese source has been approved. Translate meaning rather than sentence order,
+preserve commands and identifiers exactly, rebuild relative navigation for the
+English files, and rerun the same checks. Record intentional locale differences
+instead of silently dropping Chinese-only instructions.
+
+## Report the result
+
+List the documents created or changed, the sources used for claims, checks run,
+and unresolved evidence gaps. Separate missing documentation from unsupported
+features. Do not present an unverified artifact, inferred pin map, or stale test
+result as a current product capability.

package/skills/tirtc-project-docs/VERSION

@@ -0,0 +1 @@
+0.11.5

package/skills/tirtc-project-docs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TiRTC Project Docs"
+  short_description: "维护 TiRTC 多开发板项目的中英文文档与证据边界"
+  default_prompt: "Use $tirtc-project-docs to design or audit my TiRTC project documentation, write and verify the Chinese source first, and generate English only after Chinese approval."

package/skills/tirtc-project-docs/references/bilingual.md

@@ -0,0 +1,37 @@
+# Bilingual synchronization
+
+Use this reference only after the project owner has approved the Chinese source.
+
+## File policy
+
+Keep Chinese as the source language unless the repository declares another
+policy. Use stable English siblings such as `README.en.md`,
+`ARCHITECTURE.en.md`, and `CONTRIBUTING.en.md`. Subject documents may use the
+same suffix convention or separate language trees, but one repository should
+use one convention.
+
+Add language selectors only after both targets exist. The Chinese root
+navigation points to Chinese destinations; the English navigation points to
+English destinations where available and to a clearly labelled Chinese page
+only when no English counterpart exists.
+
+## Translation rules
+
+- Preserve commands, paths, board IDs, artifact names, checksums, log fragments,
+  configuration keys, and protocol constants exactly.
+- Use official English vendor and product names. Do not translate identifiers.
+- Translate the meaning and reader task, not Chinese word order.
+- Keep warnings, evidence qualifications, limitations, and follow-up items at
+  the same strength as the Chinese source.
+- Explain acronyms on first use in each independently readable document.
+- Recheck relative links because an English sibling can have different targets.
+
+## Drift review
+
+Compare section coverage rather than raw line count. Every Chinese section must
+have an English counterpart or a recorded locale-specific reason. Verify tables
+row by row, then rerun link, manifest, documentation, and host-test gates.
+
+Translation is complete when the English reader can perform the same supported
+task and sees the same capability and evidence status as the approved Chinese
+reader.

package/skills/tirtc-project-docs/references/document-architecture.md

@@ -0,0 +1,58 @@
+# Document architecture
+
+Use this reference when deciding where information belongs or when a repository
+has accumulated duplicate guides.
+
+## Entry hierarchy
+
+The root is a small set of durable entrypoints:
+
+| Document | Reader question | Content boundary |
+| --- | --- | --- |
+| `README.md` | How do I run this now? | Board choice, release download, safe flashing, provisioning, first experience |
+| `ARCHITECTURE.md` | How does it work and where do I extend it? | Product flows, module interfaces, data/lifecycle paths, repository responsibilities |
+| `CONTRIBUTING.md` | How do I make and verify a change? | Environment, tests, evidence, board/platform intake, submission checks |
+| `docs/README.md` | Where is the complete documentation? | Task-oriented index to product, development, board, test, and reference material |
+
+Do not turn the root README into a complete hardware manual. It may show a
+compact card or table for a small set of primary boards. Each row links to the
+release artifact and the board's full guide. As the catalog grows, keep only the
+primary boards in the root and link the complete catalog.
+
+## Detail ownership
+
+- `docs/product/` owns current user-visible behavior, interaction, protocols,
+  and media contracts.
+- `docs/development/` owns architecture details, toolchains, builds, tests,
+  porting, release mechanics, and AI-assisted development.
+- `docs/boards/<board-id>/` owns model-specific specifications, dependencies,
+  schematics, build/flash steps, first use, verification, and limitations.
+- `boards/<vendor>/<board>/` owns build-participating board facts and a short
+  pointer README when the repository uses this layout.
+- `references/` indexes external SDKs, schematics, examples, and datasheets that
+  are inputs rather than maintained product documentation.
+- Local ignored history owns dated investigations and superseded status
+  snapshots. Public documents state only current behavior and current limits.
+
+## Root navigation
+
+Place navigation immediately after the title or language selector. Keep it
+short and identical across public root documents. A typical Chinese set is:
+
+```markdown
+[快速体验](README.md) · [架构与二次开发](ARCHITECTURE.md) ·
+[参与开发](CONTRIBUTING.md) · [完整文档](docs/README.md)
+```
+
+Add language links only when the target files exist and have passed review.
+Do not publish dead “English coming soon” links.
+
+## Single-source rule
+
+Summaries may repeat a conclusion, but volatile values have one owner. Board
+memory, SDK version, stream identifiers, sample rates, checksums, and build
+commands should be read from manifests, contracts, lock files, release
+metadata, or their designated documentation owner. Other pages link there.
+
+When duplication is unavoidable for a quick-start step, keep the detailed page
+authoritative and add a test that detects drift in the copied value.

package/skills/tirtc-project-docs/references/evidence.md

@@ -0,0 +1,70 @@
+# Evidence and technical claims
+
+Read this reference when documentation states hardware facts, product
+capabilities, media parameters, build requirements, release contents, or test
+status.
+
+## Source order
+
+Use the closest authoritative source:
+
+1. Product behavior and protocol contracts in the maintained product source or
+   product documentation.
+2. Board manifest for identity and build metadata.
+3. Hardware IR, schematic, probe report, or vendor primary source for wiring,
+   fitted devices, memory, clocks, buses, and power sequencing.
+4. Lock files, SDK manifests, compiler output, and build scripts for toolchain
+   and dependency versions.
+5. Release manifest and checksums for downloadable artifacts and flash layout.
+6. Artifact-bound hardware-in-the-loop evidence for runtime claims.
+
+A board manifest is build metadata, not proof that hardware or a product flow
+worked. A successful compile is not a hardware validation result. Evidence from
+one printed-circuit-board revision does not automatically apply to another.
+
+## Board guide minimum
+
+Each supported board guide should independently explain:
+
+- exact public model and printed-circuit-board revision;
+- processor, memory, display, touch, camera, audio, and network specifications;
+- product functions and technical media parameters;
+- operating system, SDK, compiler, libraries, and locked versions;
+- official product page, schematic, and source identity;
+- root-level build command and expected artifacts;
+- safe flash method, offsets, boot mode, and protected factory data;
+- provisioning, binding, and first product experience;
+- verification level, artifact identity, limitations, and explicit follow-up
+  evidence.
+
+Use `unknown` or a clearly scoped follow-up item when a fact lacks evidence.
+Do not fill gaps from a visually similar board or another board using the same
+processor.
+
+## Media and session details
+
+For each H5, AI, device-call, WeChat VoIP, or room flow that the project claims,
+document the applicable direction and parameters:
+
+- stream identifiers;
+- encoding, sample rate, channel count, frame duration, samples and payload
+  relationship;
+- video format, resolution, frame rate, target bitrate, keyframe/refresh rule;
+- AEC input, playback reference, processing frame, delay treatment, and modes
+  where AEC is required;
+- ownership, readiness, stop, reconnect, and resource-release behavior.
+
+Network packet duration and an AEC processing block are different units. State
+both when software splits or aggregates them.
+
+## Release download and flashing
+
+Quick-start pages link to an immutable release or a release selector that makes
+board identity explicit. A release bundle should carry its board ID, version,
+source revision, files, flash offsets, verification status, and SHA-256 values.
+Explain the difference between complete flash images and over-the-air images.
+
+Never infer a flash command from a filename alone. Read the bundle manifest or
+the board's authoritative flash guide, and preserve calibration, credentials,
+keys, and factory partitions unless the product process explicitly replaces
+them.