tirtc-device-builder 0.2.0

package/SECURITY.md

@@ -0,0 +1,15 @@
+# Security policy
+
+## Report a vulnerability
+
+Use a private GitHub security advisory:
+
+https://github.com/tangeai/tirtc-device-builder/security/advisories/new
+
+Do not include device keys, Wi-Fi passwords, service tokens, certificates, private user data, or captured media in a public Issue. Redact logs and provide the smallest reproduction that still demonstrates the problem.
+
+## Scope
+
+Reports may cover unsafe command execution, path handling, credential disclosure, unintended network access, serial-device selection, firmware flashing authorization, package installation behavior, and generated-project security boundaries.
+
+Vulnerabilities in ESP-IDF, TiRTC SDK, ThingConnect, vendor BSPs, chip toolchains, or board firmware should also be reported to the corresponding upstream maintainer.

package/bin/tirtc-device-builder.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const PACKAGE = JSON.parse(
+  readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"),
+);
+
+const PLATFORMS = new Map([
+  [
+    "esp32",
+    {
+      aliases: new Set(["esp32", "esp32s3", "tirtc-esp32-builder"]),
+      skill: "tirtc-esp32-builder",
+      summary: "ESP32-S3 / ESP-IDF 5.5.x",
+    },
+  ],
+]);
+
+function printHelp() {
+  console.log(`TiRTC Device Builder ${PACKAGE.version}
+
+Usage:
+  tirtc-device-builder list
+  tirtc-device-builder install <platform> [--skills-dir <path>] [--force]
+  tirtc-device-builder doctor <platform> [doctor options]
+  tirtc-device-builder --version
+
+Platforms:
+  esp32       ESP32-S3 / ESP-IDF 5.5.x
+
+Examples:
+  npx tirtc-device-builder install esp32
+  npx tirtc-device-builder install esp32 --skills-dir /absolute/path/skills
+  npx tirtc-device-builder doctor esp32 --project /absolute/path/project
+
+Install defaults to ${"$"}{CODEX_HOME:-~/.codex}/skills. Existing skills are
+preserved unless --force is explicitly supplied.`);
+}
+
+function fail(message) {
+  console.error(`ERROR: ${message}`);
+  return 1;
+}
+
+function resolvePlatform(identifier) {
+  for (const [name, platform] of PLATFORMS) {
+    if (platform.aliases.has(identifier)) {
+      return { name, ...platform };
+    }
+  }
+  return null;
+}
+
+function defaultSkillsDir() {
+  const codexHome = process.env.CODEX_HOME
+    ? resolve(process.env.CODEX_HOME)
+    : join(homedir(), ".codex");
+  return join(codexHome, "skills");
+}
+
+function parseInstallOptions(args) {
+  const options = {
+    force: false,
+    skillsDir: defaultSkillsDir(),
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === "--force") {
+      options.force = true;
+      continue;
+    }
+    if (argument === "--skills-dir") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("--skills-dir requires a path");
+      }
+      options.skillsDir = resolve(value);
+      index += 1;
+      continue;
+    }
+    throw new Error(`unknown install option: ${argument}`);
+  }
+
+  return options;
+}
+
+function installSkill(platform, options) {
+  const source = join(PACKAGE_ROOT, "skills", platform.skill);
+  const skillsDir = options.skillsDir;
+  const target = join(skillsDir, platform.skill);
+  const nonce = `${process.pid}-${Date.now()}`;
+  const staged = join(skillsDir, `.${platform.skill}.install-${nonce}`);
+  const backup = join(skillsDir, `.${platform.skill}.backup-${nonce}`);
+
+  if (!existsSync(join(source, "SKILL.md"))) {
+    throw new Error(`package is missing ${platform.skill}/SKILL.md`);
+  }
+  if (existsSync(target) && !options.force) {
+    throw new Error(
+      `${target} already exists; rerun with --force only when replacement is intended`,
+    );
+  }
+
+  mkdirSync(skillsDir, { recursive: true });
+  let movedExisting = false;
+  try {
+    cpSync(source, staged, {
+      errorOnExist: true,
+      force: false,
+      recursive: true,
+    });
+    if (!existsSync(join(staged, "SKILL.md"))) {
+      throw new Error("staged skill failed validation");
+    }
+    if (existsSync(target)) {
+      renameSync(target, backup);
+      movedExisting = true;
+    }
+    renameSync(staged, target);
+  } catch (error) {
+    if (existsSync(staged)) {
+      rmSync(staged, { force: true, recursive: true });
+    }
+    if (movedExisting && !existsSync(target) && existsSync(backup)) {
+      renameSync(backup, target);
+    }
+    throw error;
+  }
+
+  if (movedExisting && existsSync(backup)) {
+    rmSync(backup, { force: true, recursive: true });
+  }
+  console.log(`Installed ${platform.skill} ${PACKAGE.version} to ${target}`);
+  console.log(`Start a new Codex session, then invoke $${platform.skill}.`);
+}
+
+function runDoctor(platform, args) {
+  const script = join(
+    PACKAGE_ROOT,
+    "skills",
+    platform.skill,
+    "scripts",
+    "doctor.py",
+  );
+  if (!existsSync(script)) {
+    return fail(`package is missing doctor script for ${platform.name}`);
+  }
+
+  const python = process.env.PYTHON || "python3";
+  const result = spawnSync(python, [script, ...args], {
+    stdio: "inherit",
+  });
+  if (result.error) {
+    return fail(`could not run ${python}: ${result.error.message}`);
+  }
+  return Number.isInteger(result.status) ? result.status : 1;
+}
+
+function main(args) {
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    printHelp();
+    return 0;
+  }
+  if (args[0] === "--version" || args[0] === "-v") {
+    console.log(PACKAGE.version);
+    return 0;
+  }
+  if (args[0] === "list") {
+    for (const [name, platform] of PLATFORMS) {
+      console.log(`${name}\t${platform.skill}\t${platform.summary}`);
+    }
+    return 0;
+  }
+
+  const [command, identifier, ...rest] = args;
+  if (command !== "install" && command !== "doctor") {
+    return fail(`unknown command: ${command}; run with --help`);
+  }
+  if (!identifier) {
+    return fail(`${command} requires a platform; run "list" to see options`);
+  }
+  const platform = resolvePlatform(identifier);
+  if (!platform) {
+    return fail(`unsupported platform: ${identifier}; run "list" to see options`);
+  }
+
+  if (command === "doctor") {
+    return runDoctor(platform, rest);
+  }
+
+  try {
+    const options = parseInstallOptions(rest);
+    installSkill(platform, options);
+    return 0;
+  } catch (error) {
+    return fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
+process.exitCode = main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "tirtc-device-builder",
+  "version": "0.2.0",
+  "description": "Install and run TiRTC device-development skills for Codex.",
+  "license": "MIT",
+  "author": {
+    "name": "TangeAI",
+    "url": "https://github.com/tangeai"
+  },
+  "type": "module",
+  "bin": {
+    "tirtc-device-builder": "bin/tirtc-device-builder.js"
+  },
+  "files": [
+    ".codex-plugin/",
+    "bin/",
+    "skills/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE",
+    "SECURITY.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tangeai/tirtc-device-builder.git"
+  },
+  "homepage": "https://github.com/tangeai/tirtc-device-builder#readme",
+  "bugs": {
+    "url": "https://github.com/tangeai/tirtc-device-builder/issues"
+  },
+  "keywords": [
+    "codex",
+    "skill",
+    "tirtc",
+    "esp32",
+    "esp-idf",
+    "embedded",
+    "ai-intercom"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "npm run test:node && npm run test:python && npm run validate && npm run validate:tarball && npm run test:package",
+    "test:node": "node --test test/*.test.js",
+    "test:python": "python3 -m unittest discover -s skills/tirtc-esp32-builder/scripts -p 'test_*.py'",
+    "validate": "python3 scripts/validate_package.py",
+    "validate:tarball": "node scripts/validate-tarball.js",
+    "test:package": "node scripts/test-packed-package.js",
+    "prepack": "npm test"
+  }
+}

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

@@ -0,0 +1,34 @@
+---
+name: tirtc-esp32-builder
+description: Check or set up ESP-IDF, then generate, port, build, flash, and validate ThingConnect TiRTC ESP32 projects from a board model, schematic, BSP, pin map, or peripheral examples when H5 live view/talkback or AI intercom is requested. Use for environment diagnosis, supported-board generation, and new-board hardware intake; exclude Linux device-sim-c and server-only work.
+---
+
+# TiRTC Embedded Builder
+
+Turn board evidence into an evidence-backed ESP-IDF project. Treat the Hardware IR as the single handoff between probabilistic document extraction and deterministic capability, generation, build, and verification steps.
+
+## Start
+
+1. Locate the ThingConnect root containing `device-sim/` using the explicit input, `TIRTC_THING_CONNECT_ROOT`, or workspace discovery. Read its applicable `AGENTS.md` and preserve its public protocol contracts.
+2. Read [environment.md](references/environment.md) and run `python3 <skill-dir>/scripts/doctor.py --expected-idf 5.5 --target esp32s3`. Add `--require-workspace` when generation or repository reference documents are needed; a self-contained generated project can instead resolve its bundled SDK through `--project`. Resolve every required failure before claiming build readiness. Installation, cloning, or shell-profile changes require an explicit destination and the applicable authorization.
+3. Read [workflow.md](references/workflow.md). Select the registered-board, new-board intake, or existing-project branch. The branch is selected when every supplied artifact has been accounted for and the exact board revision is known or explicitly unresolved.
+4. Read [hardware-ir.md](references/hardware-ir.md) when a Hardware IR must be created or updated. Record a source and verification level for every hardware fact that affects a requested feature.
+5. Run `python3 <skill-dir>/scripts/hardware_ir.py validate <hardware-ir.json>` and then `assess --strict`. Generation may proceed for a requested feature only when it is `READY_TO_PORT` or `HIL_VERIFIED`; otherwise report the exact missing evidence and continue with safe discovery or scaffolding only.
+
+## Build the project
+
+Run `<thing-connect-root>/device-sim/scripts/create_esp32_project.py` for the current ESP32-S3 H5/AI starter. Keep ThingConnect onboarding, H5, AI, TiRTC lifecycle, callback, stream, and generation behavior in the existing deep modules. Put board-specific camera, microphone, encoder, codec, amplifier, GPIO, DMA, and task behavior behind the `starter_media` seam or a board media adapter owned by it.
+
+Before changing media code, read [capability-rules.md](references/capability-rules.md) and the repository documents it routes to. A camera sensor alone does not establish H5 video support; the complete H.264 Annex-B and key-frame path must be evidenced. Choose half duplex for AI when the supplied hardware and BSP do not establish a usable full-duplex/AEC path.
+
+Run focused tests before ESP-IDF build. Resolve the TiRTC SDK target and `manifest/build-contract.env` against the generated `sdkconfig`; a mismatched precompiled SDK is a blocked build, not a code-generation problem.
+
+## Flash and verify
+
+Flash only when the user requested hardware mutation and the exact serial port and chip have been resolved. When more than one candidate device exists, obtain the target choice before writing. Keep credentials outside generated files and redact device keys, Wi-Fi passwords, MQTT/WHIP tokens, and user media from logs and reports.
+
+Read [reporting.md](references/reporting.md) before end-to-end verification. Report every acceptance level as `PASS`, `FAIL`, or `SKIP`, with commands and evidence. A build-only result is not H5 or AI completion; missing hardware, browser, account, service, or network evidence remains an explicit `SKIP` or blocker.
+
+## Finish
+
+Return the generated project path, Hardware IR, capability assessment, build artifacts, flash record when applicable, and `TIRTC_PORTING_REPORT.md`. The task is complete only when every requested feature is either verified at the requested level or named as a blocker with the smallest next action that can resolve it.

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

@@ -0,0 +1,94 @@
+# TiRTC ESP32 Builder 使用说明
+
+安装后可在 Codex 中显式调用：
+
+```text
+$tirtc-esp32-builder
+
+在“厂商 + 完整开发板型号 + PCB 版本”上实现：
+- H5 实时视频和声音
+- H5 按住说话
+- AI 双向对讲
+
+资料：
+- 产品页或资料链接：...
+- 原理图：/absolute/path/board-schematic.pdf
+- BSP 或示例工程：/absolute/path/vendor-bsp
+- ThingConnect：/absolute/path/tirtc-server-example/thing-connect
+- 输出目录：/absolute/path/my-tirtc-device
+
+先完成能力分析；具备条件后生成并编译。只有我明确指定串口时才烧录。
+```
+
+## ThingConnect 工作区
+
+这个 Skill 不复制 ThingConnect 源码和 TiRTC 静态库。首次使用可以准备公开仓库：
+
+```bash
+git clone https://github.com/tangeai/tirtc-server-example.git \
+  /absolute/path/tirtc-server-example
+
+export TIRTC_THING_CONNECT_ROOT=\
+/absolute/path/tirtc-server-example/thing-connect
+```
+
+也可以在调用 Skill 时直接给出 ThingConnect 绝对路径，不需要设置持久环境变量。
+
+## 常见输入方式
+
+只有板卡型号：
+
+```text
+$tirtc-esp32-builder 分析 <厂商> <型号> <硬件版本>，目标是 H5 实时视频、talkback 和 AI 对讲。先输出缺失资料与能力结论。
+```
+
+提供本地资料：
+
+```text
+$tirtc-esp32-builder 使用原理图 /path/board.pdf、BSP /path/vendor-project 和 ThingConnect /path/tirtc-server-example/thing-connect，为该板生成 TiRTC H5/AI ESP-IDF 工程并编译。
+```
+
+完整实机流程：
+
+```text
+$tirtc-esp32-builder 使用 /path/hardware-ir.json 生成工程，编译后烧录到 /dev/ttyACM0，验证绑定、H5 和 AI，并生成 TIRTC_PORTING_REPORT.md。
+```
+
+## ESP-IDF 环境检查
+
+将 `<skill-dir>` 替换为安装后的 Skill 路径，例如 `~/.codex/skills/tirtc-esp32-builder`。
+
+生成工程前检查工作区和开发环境：
+
+```bash
+python3 <skill-dir>/scripts/doctor.py \
+  --expected-idf 5.5 \
+  --target esp32s3 \
+  --thing-connect-root /absolute/path/tirtc-server-example/thing-connect \
+  --require-workspace
+```
+
+工程生成后检查其内置 SDK 和配置契约：
+
+```bash
+python3 <skill-dir>/scripts/doctor.py \
+  --expected-idf 5.5 \
+  --target esp32s3 \
+  --project /absolute/path/my-tirtc-device
+```
+
+如果 `idf.py` 缺失，Skill 默认只报告安装计划。只有明确授权安装版本、目录和环境修改后，才按照 Espressif 官方步骤安装并重新运行检查。
+
+## Hardware IR 工具
+
+```bash
+python3 <skill-dir>/scripts/hardware_ir.py init /tmp/hardware-ir.json
+python3 <skill-dir>/scripts/hardware_ir.py validate /tmp/hardware-ir.json
+python3 <skill-dir>/scripts/hardware_ir.py assess --strict /tmp/hardware-ir.json
+```
+
+`BLOCKED` 表示资料已确认硬件不满足；`NEEDS_CONFIRMATION` 表示仍有未知项或只有单一来源；`READY_TO_PORT` 表示可以生成并实现板级适配；`HIL_VERIFIED` 表示端到端实机验收通过。
+
+## 当前边界
+
+ThingConnect 仓库提供 ESP32-S3 H5/AI 模板和生成器，但默认媒体适配器不包含特定开发板的摄像头、麦克风、H.264 编码和扬声器驱动。模板生成和编译成功只证明工程与协议骨架可用，不代表 Web 已经出图或 AI 音频已经通过实机验收。

package/skills/tirtc-esp32-builder/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TiRTC ESP32 Builder"
+  short_description: "从开发板资料生成并验证 TiRTC ESP32 固件"
+  default_prompt: "Use $tirtc-esp32-builder to analyze my ESP32 board materials and build a TiRTC H5 live-view and AI intercom project."

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

@@ -0,0 +1,78 @@
+{
+  "schema_version": 1,
+  "board": {
+    "id": "example_esp32s3_media_board",
+    "vendor": "Example Vendor",
+    "model": "ESP32-S3 Media Board",
+    "hardware_revision": "unspecified"
+  },
+  "sources": [
+    {
+      "id": "board-materials",
+      "kind": "user-supplied-materials",
+      "location": "user-supplied://board-materials",
+      "revision": "unspecified"
+    }
+  ],
+  "soc": {
+    "target": "esp32s3",
+    "module": "ESP32-S3-WROOM-1-N16R8",
+    "flash_mb": 16,
+    "psram_mb": 8,
+    "source_refs": [
+      "board-materials"
+    ]
+  },
+  "toolchain": {
+    "framework": "esp-idf",
+    "framework_version": "5.5.x",
+    "verification": "extracted",
+    "tirtc": {
+      "platform": "espressif-esp32s3",
+      "version": "2.3.0",
+      "sdk_path": "device-sim/sdk/espressif-esp32s3/2.3.0",
+      "build_contract": "manifest/build-contract.env"
+    },
+    "source_refs": [
+      "board-materials"
+    ]
+  },
+  "camera": {
+    "present": null,
+    "sensor": null,
+    "interface": null,
+    "h264": {
+      "available": null,
+      "output_format": null,
+      "key_frame_control": null,
+      "verification": "extracted"
+    },
+    "source_refs": [
+      "board-materials"
+    ]
+  },
+  "audio_input": {
+    "present": null,
+    "interface": null,
+    "codecs": [],
+    "source_refs": [
+      "board-materials"
+    ]
+  },
+  "audio_output": {
+    "present": null,
+    "interface": null,
+    "codecs": [],
+    "source_refs": [
+      "board-materials"
+    ]
+  },
+  "features": {
+    "requested": [
+      "h5_live_audio",
+      "h5_live_video",
+      "h5_talkback",
+      "ai_talk"
+    ]
+  }
+}

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

@@ -0,0 +1,55 @@
+# TiRTC Porting Report
+
+## Target
+
+- Board ID: `{{BOARD_ID}}`
+- Model/revision: `{{BOARD_MODEL_REVISION}}`
+- Requested features: `{{REQUESTED_FEATURES}}`
+- Output project: `{{PROJECT_PATH}}`
+
+## Locked inputs
+
+| Input | Version/revision | Source or SHA-256 |
+|---|---|---|
+| Hardware IR |  |  |
+| ESP-IDF |  |  |
+| TiRTC SDK |  |  |
+| BSP/board adapter |  |  |
+
+## Capability assessment
+
+| Feature | Status | Evidence or blocker |
+|---|---|---|
+| H5 live audio |  |  |
+| H5 live video |  |  |
+| H5 talkback |  |  |
+| AI intercom |  |  |
+
+## Acceptance
+
+| Level | PASS/FAIL/SKIP | Command and evidence |
+|---|---|---|
+| L-1 Environment |  |  |
+| L0 Generate |  |  |
+| L1 Build |  |  |
+| L2 Boot |  |  |
+| L3 Online |  |  |
+| L4 Media |  |  |
+| L5 H5 |  |  |
+| L6 AI |  |  |
+| L7 Stability |  |  |
+
+## Firmware and flash record
+
+- Serial port/chip: `{{SERIAL_TARGET}}`
+- Firmware artifacts: `{{FIRMWARE_ARTIFACTS}}`
+- Firmware SHA-256: `{{FIRMWARE_SHA256}}`
+- Flash command/result: `{{FLASH_RESULT}}`
+
+## Remaining work and risks
+
+`{{REMAINING_WORK}}`
+
+## Sanitization
+
+Logs and artifacts were checked for device keys, Wi-Fi passwords, complete MQTT/WHIP tokens, and user media: `{{SANITIZATION_RESULT}}`.

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

@@ -0,0 +1,32 @@
+# Capability rules
+
+Run `hardware_ir.py assess --strict` before generation. The script applies the minimum current starter contract; use this reference when explaining or extending the result.
+
+## Current starter contract
+
+| Feature | Required hardware/media path |
+|---|---|
+| `h5_live_audio` | Microphone path that produces G.711 A-law, 8 kHz, mono for stream 10 |
+| `h5_live_video` | Camera plus H.264 Annex-B access units, SPS/PPS and IDR, and key-frame request control for stream 11 |
+| `h5_talkback` | G.711 A-law, 8 kHz downlink decode and speaker path for stream 14 |
+| `ai_talk` | A-law 8 kHz microphone and speaker paths for AI stream 1, started only after `start_session` succeeds |
+
+The complete media path must be at least `corroborated` to become `READY_TO_PORT`. A path with unknown facts is `NEEDS_CONFIRMATION`; a confirmed missing or incompatible resource is `BLOCKED`. Only an end-to-end board run becomes `HIL_VERIFIED`.
+
+## Non-negotiable checks
+
+- Match the TiRTC precompiled SDK platform to the ESP-IDF target and its `manifest/build-contract.env` to the generated configuration.
+- Keep H5 stream IDs and formats stable unless the user explicitly authorizes a coordinated public contract change across the server and all consumers.
+- Start AI media only after the successful `start_session` response, and stop/flush media before disconnecting the session.
+- Copy SDK callback payloads into bounded queues before returning. Perform decoding, playback, HTTP, and lifecycle changes outside SDK callbacks.
+- Use monotonic timestamps and session generation to reject stale frames and delayed callbacks.
+
+## Typical blocked cases
+
+- A camera outputs JPEG but no evidenced H.264 encoder produces Annex-B access units.
+- The board has a microphone but no encoder path for the required A-law sample rate.
+- The board has a codec but its playback pins, clock, amplifier enable, or BSP driver remain unknown.
+- A generic ESP32-S3 module is named without the carrier board that defines camera/audio wiring.
+- The available TiRTC archive targets another chip, ESP-IDF ABI, or FreeRTOS configuration.
+
+When a blocked case would require changing the H5 contract, replacing hardware, or obtaining a new TiRTC SDK build, report those alternatives instead of silently changing the project.

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

@@ -0,0 +1,54 @@
+# ESP-IDF environment
+
+Run the doctor before generation, build, flash, or monitor:
+
+```bash
+python3 <skill-dir>/scripts/doctor.py \
+  --expected-idf 5.5 \
+  --target esp32s3 \
+  --require-workspace
+```
+
+Add `--project <generated-project>` after generation so the doctor can compare `sdkconfig` or `sdkconfig.defaults` with the TiRTC SDK build contract. Use `--json` when the result will be included in another report.
+
+## ThingConnect workspace
+
+This distributable skill does not bundle the ThingConnect source tree or TiRTC static library. Resolve the public ThingConnect workspace in this order:
+
+1. an explicit `--thing-connect-root <path>`;
+2. `TIRTC_THING_CONNECT_ROOT`;
+3. an ancestor of the project or current directory containing `device-sim/scripts/create_esp32_project.py`;
+4. an ancestor whose `thing-connect/` child contains that generator.
+
+The public source is `https://github.com/tangeai/tirtc-server-example`. Clone it only into an explicit destination. The root accepted by the doctor may be either the repository root or its `thing-connect/` child.
+
+SDK resolution is independent after generation: an explicit `--sdk-dir` wins, followed by `<project>/third_party/tirtc`, then the SDK packaged in the resolved ThingConnect workspace. The generated project path therefore remains diagnosable after it is moved away from the source repository.
+
+## Required checks
+
+- `python3`, `git`, `idf.py`, and the target compiler are available in the active shell;
+- `idf.py --version` matches the project's required ESP-IDF line;
+- `IDF_PATH` is coherent when set;
+- the TiRTC SDK contains its header, archive, and `manifest/build-contract.env`;
+- generated Kconfig values explicitly match TiRTC's FreeRTOS ABI-sensitive contract;
+- the requested serial port exists and is writable before flash or monitor.
+
+CMake and Ninja are reported separately because an activated ESP-IDF environment may provide or select its own managed versions.
+
+## Missing ESP-IDF
+
+Checking is read-only. Installing ESP-IDF downloads code and tools, consumes disk space, and may change the developer's shell setup, so perform it only after the user approves the exact version, install directory, supported target, and shell activation method.
+
+For an approved installation:
+
+1. Confirm the project and TiRTC package require the same ESP-IDF major/minor line. This repository's current ESP32-S3 starter requires 5.5.x.
+2. Consult the current official Espressif installation instructions for the developer's operating system.
+3. Install a pinned 5.5.x release into a user-approved directory; enable the `esp32s3` target and keep the vendor installer logs.
+4. Activate the installed environment in the current shell. Modify a persistent shell profile only when the user explicitly requests it.
+5. Rerun the doctor. Installation is complete only when the IDF version, compiler, SDK files, and project contract checks pass.
+
+When downloads, package installation, administrator rights, USB drivers, or group membership are required, surface the exact action and obtain the applicable authorization instead of treating it as an ordinary code edit.
+
+## Existing but inactive ESP-IDF
+
+If `IDF_PATH/tools/idf.py` exists but `idf.py` or the target compiler is absent from `PATH`, report the environment as inactive. Activate that installation using its vendor-provided export script and rerun the doctor; do not install a second copy merely because the current shell is inactive.