tirtc-device-builder 0.11.5 → 0.11.6

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 This project follows Semantic Versioning.
 
+## 0.11.6
+
+- Add field-log triage gates for Beken HTTP business failures, generation-bound
+  remote closes, AI tail-audio ordering, worker exit versus processor faults,
+  FT6336 input faults, room-leave evidence and contact-shortcut intent.
+- Improve the project-documentation Skill with reader-task section ordering and
+  small, decision-focused diagram guidance.
+
 ## 0.11.5
 
 - Add the `tirtc-project-docs` Skill for designing and reviewing public

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.11.5",
+  "version": "0.11.6",
   "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.5
+0.11.6

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 `05d3180`. These
+failures fixed in `lckfb-bk7258-xiaotai` through source commit `6ec080f`. These
 are gates, not a generic board profile: retain the decisions, but use the exact
 numbers only when the target matches the identity below.
 
@@ -199,3 +199,36 @@ state transitions but not complete network inputs or responses.
 Contract tests must keep those full-payload format strings behind `BK_LOGD` or
 an equivalent DEBUG guard and reject them at INFO/WARN/ERROR. Treat DEBUG logs as
 sensitive development artifacts and keep them out of source control.
+
+## Field-log triage gate
+
+Reconstruct a failure by monotonic device time and session generation. Terminal
+receive timestamps can batch output and do not establish firmware ordering.
+Separate these layers before changing code:
+
+- transport success from business success: HTTP 200 can still carry a rejected
+  business code such as an offline target;
+- semantic completion from connection closure: TiRTC `-40008` is normal only
+  for the same generation after an explicit hangup or `end_session`; otherwise
+  retain it as an error;
+- locally buffered AI tail from unsent platform audio: after `end_session`, gate
+  uplink and drain queued playback before teardown. If the platform closes in
+  less than one negotiated audio-frame interval, firmware cannot recover audio
+  that never arrived. Require the platform to send the complete final utterance
+  before the end command and transport close;
+- worker cleanup text from a processor crash: an SDK thread-exit warning alone
+  is not reboot evidence. Require a Fault/watchdog record or a new boot sequence;
+- touch-controller I/O failures from media faults: diagnose FT6336 read errors,
+  invalid touch IDs and missing UP events at the board adapter. Submit dangerous
+  tap actions once on DOWN and preserve DOWN/UP pairing for PTT.
+
+For room exit, require all three observable results: the leave API succeeds,
+local media closes, and the refreshed assignment is absent. A page transition
+alone does not prove that the device left the room. For contact shortcuts,
+verify the selected contact class as well as list position; a touch-home WeChat
+shortcut and a physical `contacts[0]` shortcut are distinct product intents.
+
+Lock each corrected business rule in the platform-neutral product tests and the
+adapter ordering in a board contract test. Use the repository's documented
+test entrypoint after locating it; do not invent a generic
+`tools/run_host_tests.sh` path across projects.

package/skills/tirtc-esp32-builder/VERSION

@@ -1 +1 @@
-0.11.5
+0.11.6

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

@@ -25,6 +25,10 @@ area when the repository defines one.
 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.
+5. State the primary reader task for every entry document before drafting its
+   sections. Read [readability and diagrams](references/readability-and-diagrams.md)
+   for root entrypoints, long guides, workflow documents, or any proposed
+   visualization.
 
 ## Select the document layer
 
@@ -56,6 +60,19 @@ 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.
 
+Order sections by the reader's next decision, not by the order in which facts
+were discovered. A quick-start normally moves from board/artifact choice to
+flashing, first experience, and only then source development. An architecture
+guide moves from product scope to layers, runtime flows, contracts, extension,
+and verification. A contribution guide moves from prerequisites to change
+classification, applicable constraints, tests, and submission.
+
+Use a diagram only when it makes a multi-step flow, hierarchy, or branching
+decision materially easier to understand. Keep it small, introduce it in prose,
+and retain critical constraints in nearby text. Do not repeat the same complete
+sequence as both a numbered list and a diagram. Keep complex architecture out
+of the quick-start README unless it is necessary to complete the first run.
+
 Use available specialist Skills when they materially apply:
 
 - `research` for facts that require official external sources and citations;
@@ -78,9 +95,10 @@ 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.
+shape, section order, diagram purpose, 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
 

package/skills/tirtc-project-docs/VERSION

@@ -1 +1 @@
-0.11.5
+0.11.6

package/skills/tirtc-project-docs/references/readability-and-diagrams.md

@@ -0,0 +1,77 @@
+# Readability and diagrams
+
+Use this reference when drafting or auditing root entrypoints, long guides,
+workflows, architecture explanations, or Mermaid diagrams.
+
+## Start from the reader task
+
+Give each document one primary promise. The opening should tell the reader what
+they can accomplish there and point elsewhere for broader detail. Arrange
+sections in prerequisite order so the reader never needs information that is
+introduced later.
+
+Common sequences are guidance, not fixed templates:
+
+- Quick experience: identify board and artifact, verify the bundle, flash it,
+  provision and try the product, then offer source-build and deeper links.
+- Architecture: establish product scope, show layers and ownership, explain
+  runtime or media flows, state contracts, show extension paths, then explain
+  evidence and verification.
+- Contribution: prepare the environment, classify the change, read the rules
+  that apply to that class, implement it, run proportional tests, update
+  documentation, and complete submission checks.
+
+Do not preserve an existing section order merely because every individual
+section is accurate. A source-download chapter placed in the middle of a binary
+quick-start is still a usability defect.
+
+## Shape paragraphs and sections
+
+Introduce context or a decision before commands, tables, or diagrams. Keep one
+main idea per paragraph. Put the result, warning, or next step next to the action
+it qualifies instead of collecting all caveats at the end.
+
+Use headings for real reader tasks, not for every small fact. Keep heading
+levels monotonic and avoid a deep hierarchy in root entrypoints. Lists are
+useful for choices, requirements, and procedures; ordinary explanation should
+remain prose rather than a stack of one-line bullets.
+
+For Chinese, run a natural-language review after the facts and structure are
+stable. Explain an unavoidable acronym on first use in each independently
+readable document. Prefer direct verbs and concrete ownership over abstract
+claims or slogan-like conclusions.
+
+## Decide whether a diagram helps
+
+A diagram is useful for at least three dependent steps, three or more branches,
+layer ownership, or relationships that are hard to reconstruct from prose. Use
+the smallest fitting form: flowchart for sequence or decisions, hierarchy for
+ownership, and table for repeated exact mappings.
+
+Do not add a diagram for a single command, a short list, or decoration. Root
+quick-start pages should normally stay linear. Architecture and contribution
+guides are better candidates because their readers compare layers, lifecycle
+states, or alternative extension paths.
+
+Prefer Mermaid in Markdown repositories that render it. Place a one- or
+two-sentence reading cue immediately before the diagram. Keep labels short,
+define acronyms outside the diagram, and avoid colors or styling that depend on
+one theme.
+
+The diagram must not be the only home of a safety rule, command, protocol
+constant, or evidence qualification. Nearby prose owns those facts. At the same
+time, do not duplicate every node as a numbered list; summarize the governing
+constraint and let the diagram carry the relationship.
+
+## Review and automate
+
+Check heading hierarchy, prerequisite order, paragraph length, local links,
+code-fence balance, and whether every diagram has an introduction and a clear
+job. Render Mermaid when a renderer is already available; do not add a large
+toolchain solely for a small documentation edit.
+
+Repository tests may lock stable document roles, required destinations, and
+project-specific section order. Avoid generic tests that freeze exact prose.
+Tests should catch navigation drift, missing board coverage, broken links,
+oversized paragraphs, duplicated volatile facts, or diagrams spreading into a
+quick-start without a documented reason.