tirtc-device-builder 0.11.4 → 0.11.6

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.11.4",
-  "description": "Codex workflows for building and validating TiRTC device firmware across supported chip platforms.",
+  "version": "0.11.6",
+  "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,23 @@
 
 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
+  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

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.4",
+  "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.4
+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.4
+0.11.6

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

@@ -0,0 +1,116 @@
+---
+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.
+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
+
+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.
+
+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;
+- `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, 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
+
+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.6

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.

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.