tirtc-device-builder 0.8.1 → 0.9.1

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 This project follows Semantic Versioning.
 
+## 0.9.1
+
+- Pin ESP32 Device Kit 1.1.2 with an open `TiRTC-` SoftAP and provisioning at
+  `http://192.168.6.1`.
+- Reject Device Kit packaging when implementation or documentation retains the
+  legacy SSID, password, or `192.168.4.1` provisioning contract.
+- Make the Hardware IR SoftAP defaults and validation match the device runtime.
+
+## 0.9.0
+
+- Add native Skill-directory installation for Codex, Claude Code, OpenCode,
+  Gemini CLI, GitHub Copilot, Qwen Code, Windsurf Cascade, Cline, and Kiro.
+- Add `--client` support to both `install` and the resumable `setup` workflow,
+  plus a `clients` command that reports resolved user directories.
+- Keep one portable `SKILL.md` and supporting resource tree across clients,
+  while preserving explicit replacement and hardware-operation approvals.
+
 ## 0.8.1
 
 - Separate rapid `idf.py flash` iteration from portable evidence-bundle export,

package/README.md

@@ -1,6 +1,6 @@
 # TiRTC Device Builder
 
-TiRTC Device Builder 用于把 ESP32-S3/ESP32-P4 开发板接入 TiRTC。输入可以只有开发板型号，也可以包含原理图、BSP、引脚表和外设示例。安装后的 Codex Skill 会先检查环境、整理有依据的硬件事实，再生成或移植独立的 ESP-IDF 工程并完成板级适配和编译。烧录和实机验证只有在开发者明确给出目标串口并授权后才会执行。
+TiRTC Device Builder 用于把 ESP32-S3/ESP32-P4 开发板接入 TiRTC。输入可以只有开发板型号，也可以包含原理图、BSP、引脚表和外设示例。安装后的 Agent Skill 会先检查环境、整理有依据的硬件事实，再生成或移植独立的 ESP-IDF 工程并完成板级适配和编译。烧录和实机验证只有在开发者明确给出目标串口并授权后才会执行。
 
 当前仓库提供一个 Skill：
 
@@ -12,7 +12,7 @@ H5/AI 的 ESP32-S3 托管模板、协议文档和 TiRTC SDK 已打包在独立
 
 - npm 包：[tirtc-device-builder](https://www.npmjs.com/package/tirtc-device-builder)
 - GitHub 仓库：[tangeai/tirtc-device-builder](https://github.com/tangeai/tirtc-device-builder)
-- ESP32 Device Kit：[kit-esp32s3-v1.1.1](https://github.com/tangeai/tirtc-device-builder/releases/tag/kit-esp32s3-v1.1.1)
+- ESP32 Device Kit：[kit-esp32s3-v1.1.2](https://github.com/tangeai/tirtc-device-builder/releases/tag/kit-esp32s3-v1.1.2)
 
 文档导航：
 
@@ -43,9 +43,15 @@ npm --version
 npx --yes tirtc-device-builder@latest setup esp32 --install
 ```
 
+默认安装到 Codex。使用其他客户端时增加 `--client`，例如：
+
+```bash
+npx --yes tirtc-device-builder@latest setup esp32 --install --client qwen-code
+```
+
 这条命令会：
 
-- 把 `tirtc-esp32-builder` 安装到 Codex Skill 目录；
+- 把 `tirtc-esp32-builder` 安装到所选 Agent 客户端的 Skill 目录；
 - 下载 ESP32 Device Kit 并校验 SHA-256；
 - 复用当前可用的 ESP-IDF 5.5.x，找不到时安装 ESP-IDF 5.5.4；
 - 安装 Espressif 管理的 ESP32-S3 工具链；
@@ -59,21 +65,21 @@ npx --yes tirtc-device-builder@latest setup esp32 --install
 ```text
 OVERALL: PASS
 SETUP: READY
-Start a new Codex session and invoke $tirtc-esp32-builder.
+Start a new Codex session, then ask it to use tirtc-esp32-builder.
 ```
 
 如果看到 `OVERALL: NEEDS_SETUP`、`MISS` 或 `FAIL`，先看[常见问题](#常见问题)。
 
-### 3. 重新打开 Codex
+### 3. 重新打开 Agent 客户端
 
-Skill 在 Codex 会话启动时被发现。安装完成后，关闭当前 Codex 会话，再打开一个新会话。
+Skill 通常在 Agent 会话启动时被发现。安装完成后，关闭当前会话，再打开一个新会话。
 
-### 4. 把板卡和目标告诉 Codex
+### 4. 把板卡和目标告诉 Agent
 
 把你已经掌握的信息填进下面的提示词即可，不用先查齐所有硬件参数。先指定工作区根目录，本地路径尽量相对工作区填写；不确定的内容写“未知”。可直接复制的版本见[开发板接入提示词](skills/tirtc-esp32-builder/assets/developer-intake-prompt.md)。
 
 ```text
-请使用 $tirtc-esp32-builder 完成这块开发板的 TiRTC 移植。
+请使用 tirtc-esp32-builder Skill 完成这块开发板的 TiRTC 移植。
 
 开发板：
 - 厂商、完整型号、PCB/硬件版本：<填写>
@@ -277,7 +283,7 @@ board-materials/
 | ESP-IDF | 5.5.x |
 | 自动安装版本 | ESP-IDF v5.5.4 |
 | TiRTC SDK | `espressif-esp32s3/2.3.0` |
-| ESP32 Device Kit | 1.1.1 |
+| ESP32 Device Kit | 1.1.2 |
 | Node.js | 18 或更高版本 |
 | 支持自动安装的系统 | Linux、WSL、macOS |
 | 原生 Windows | 使用 Espressif 官方安装器准备 ESP-IDF，再重新运行检查 |
@@ -339,27 +345,54 @@ tirtc-device-builder setup esp32 --install
 
 安装命令是 `npm install`，不要写成 `npm --install`。
 
-只执行 `npm install --global tirtc-device-builder` 会安装 CLI，不会准备完整开发环境。随后还要运行 `setup esp32 --install`，由它安装 Codex Skill、下载 Device Kit，并在需要时安装 ESP-IDF。npm 包没有 `preinstall`、`install` 或 `postinstall` 生命周期脚本，因此不会在安装 CLI 时改动这些目录。
+只执行 `npm install --global tirtc-device-builder` 会安装 CLI，不会准备完整开发环境。随后还要运行 `setup esp32 --install`，由它安装 Agent Skill、下载 Device Kit，并在需要时安装 ESP-IDF。npm 包没有 `preinstall`、`install` 或 `postinstall` 生命周期脚本，因此不会在安装 CLI 时改动这些目录。
 
 安装公开包不需要执行 `npm login`；这个命令只和维护者发布新版本有关。
 
 ### 只安装 Skill
 
-如果 ESP-IDF 和 Device Kit 已经由团队统一准备，可以只复制 Codex Skill：
+如果 ESP-IDF 和 Device Kit 已经由团队统一准备，可以只复制 Agent Skill：
 
 ```bash
 npx --yes tirtc-device-builder@latest install esp32
+npx --yes tirtc-device-builder@latest install esp32 --client gemini
 ```
 
 这条命令不安装 ESP-IDF，也不下载 Device Kit。完整的新用户环境仍建议使用 `setup esp32 --install`。
 
+### 支持的 Agent 客户端
+
+同一个 `tirtc-esp32-builder` Skill 会完整复制到所选客户端的原生目录，不维护客户端专用的内容副本。先用下面的命令查看当前机器解析出的目录：
+
+```bash
+npx --yes tirtc-device-builder@latest clients
+```
+
+| `--client` | 客户端 | 默认 Skill 根目录 |
+|---|---|---|
+| `codex` | Codex（默认） | `${CODEX_HOME:-~/.codex}/skills` |
+| `claude-code` | Claude Code | `~/.claude/skills` |
+| `opencode` | OpenCode | `${XDG_CONFIG_HOME:-~/.config}/opencode/skills` |
+| `gemini` | Gemini CLI | `~/.gemini/skills` |
+| `copilot` | GitHub Copilot | `~/.copilot/skills` |
+| `qwen-code` | Qwen Code | `~/.qwen/skills` |
+| `windsurf` | Windsurf Cascade | `~/.codeium/windsurf/skills` |
+| `cline` | Cline | `~/.cline/skills` |
+| `kiro` | Kiro | `~/.kiro/skills` |
+
+也可以使用 `claude`、`gemini-cli`、`github-copilot`、`qwen`、`cascade`、`kiro-cli` 等别名。`--skills-dir` 的优先级高于默认目录，适合项目级安装或客户端使用非默认配置目录的情况。
+
+`--client` 只选择 Skill 的安装目录和提示文案，不绑定模型服务。DeepSeek、Qwen、GLM、Kimi、OpenAI 或 Claude 等模型仍在对应客户端中配置；只要客户端能发现 Skill 并允许文件、终端等所需工具，就继续使用同一份工作流。
+
+Cline 当前还需要在 `Settings → Features → Enable Skills` 中启用实验性 Skills 功能；安装器不会修改客户端自身的权限或功能开关。
+
 ### 默认目录
 
 | 内容 | 默认位置 |
 |---|---|
-| Codex Skill | `${CODEX_HOME:-~/.codex}/skills/tirtc-esp32-builder` |
+| Agent Skill | 上表中所选目录下的 `tirtc-esp32-builder` |
 | 托管根目录 | `~/.tirtc-device-builder` |
-| Device Kit | `~/.tirtc-device-builder/kits/esp32s3/1.1.1` |
+| Device Kit | `~/.tirtc-device-builder/kits/esp32s3/1.1.2` |
 | ESP-IDF | `~/.tirtc-device-builder/esp-idf-v5.5.4` |
 | Espressif 工具 | `~/.tirtc-device-builder/espressif` |
 | 安装记录 | `~/.tirtc-device-builder/config.json` |
@@ -404,7 +437,7 @@ npx --yes tirtc-device-builder@latest setup esp32 --install \
 
 ```bash
 npx --yes tirtc-device-builder@latest setup esp32 --install \
-  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.1.tar.gz
+  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.2.tar.gz
 ```
 
 安装器仍会核对固定的 SHA-256、目录结构、清单和每个资源文件，不接受未经验证的同名压缩包。
@@ -436,6 +469,7 @@ npx --yes tirtc-device-builder@latest setup esp32
 ```bash
 npx --yes tirtc-device-builder@latest --help
 npx --yes tirtc-device-builder@latest list
+npx --yes tirtc-device-builder@latest clients
 npx --yes tirtc-device-builder@latest setup esp32 --help
 ```
 
@@ -618,7 +652,7 @@ bootloader、分区表和应用镜像；无需手工维护多条 `esptool.py`
 
 ### Wi-Fi 凭证和设备绑定
 
-SoftAP 是可选方案，不是接入前提。Hardware IR 要根据 BSP 的实际能力和产品要求，选择 SoftAP、BLE、SmartConfig、安全工厂/NVS 注入、不纳入版本控制的开发配置，或有文档的自定义方案。SSID 和密码不应写死在源码中。
+SoftAP 是可选方案，不是接入前提。Hardware IR 要根据 BSP 的实际能力和产品要求，选择 SoftAP、BLE、SmartConfig、安全工厂/NVS 注入、不纳入版本控制的开发配置，或有文档的自定义方案。若选择 SoftAP，热点名必须以 `TiRTC-` 开头、使用开放认证（无需密码），AP 网关和配网页面地址固定为 `192.168.6.1`（`http://192.168.6.1`）。这些值要写入 Hardware IR 并通过门禁；目标 WLAN 的 SSID 和密码仍不得写死在源码中。
 
 无论选择哪种方法，都要有当前 PCB/BSP 的支持证据，凭证不能进入 Git、源码或报告，并且要保留清除或重配入口。没有 SoftAP、但支持工厂 NVS 注入的设备同样可以接入。只要工程提交了明文密码，Hardware IR v2 门禁就会判为 `BLOCKED`。
 
@@ -759,15 +793,16 @@ npx --yes tirtc-device-builder@latest setup esp32 --install \
 
 如果指定目录已存在但内容不完整或版本错误，安装器会拒绝覆盖。换一个空的新路径，或先人工备份原目录。
 
-### 安装完成后 Codex 找不到 Skill
+### 安装完成后 Agent 客户端找不到 Skill
 
-关闭当前 Codex 会话并重新打开。再检查默认文件是否存在：
+关闭当前 Agent 会话并重新打开。先查看客户端目录，再检查对应文件是否存在：
 
 ```bash
-ls -l ~/.codex/skills/tirtc-esp32-builder/SKILL.md
+npx --yes tirtc-device-builder@latest clients
+ls -l <skills-dir>/tirtc-esp32-builder/SKILL.md
 ```
 
-设置过 `CODEX_HOME` 或 `--skills-dir` 时，要检查对应目录。不要同时把 Skill 安装到多个位置。
+确认安装和启动的是同一个客户端，例如 Qwen Code 要使用 `--client qwen-code`。设置过 `CODEX_HOME`、`XDG_CONFIG_HOME` 或 `--skills-dir` 时，要检查对应目录。项目级目录由客户端自身规则决定，可以用 `--skills-dir` 显式指定。
 
 ### 已有 Skill，安装器拒绝覆盖
 
@@ -785,7 +820,7 @@ npx --yes tirtc-device-builder@latest setup esp32 --install --force-skill
 
 ```bash
 npx --yes tirtc-device-builder@latest setup esp32 --install \
-  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.1.tar.gz
+  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.2.tar.gz
 ```
 
 安装器会校验 SHA-256 和内部文件清单。如果校验不一致，请重新获取官方 Release 附件，不要跳过校验。
@@ -897,25 +932,25 @@ python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
 ```bash
 npm run pack:esp32-kit -- \
   --source /absolute/path/tirtc-server-example/thing-connect \
-  --kit-version 1.1.1
+  --kit-version 1.1.2
 ```
 
 输出位于 `dist/`：
 
 ```text
-tirtc-esp32s3-kit-1.1.1.tar.gz
-tirtc-esp32s3-kit-1.1.1.tar.gz.sha256
+tirtc-esp32s3-kit-1.1.2.tar.gz
+tirtc-esp32s3-kit-1.1.2.tar.gz.sha256
 ```
 
 校验后推送独立的 `kit-esp32s3-v<version>` 标签。`publish-kit.yml` 会从 metadata 固定的上游 commit 重建压缩包、核对 SHA-256，并使用 GitHub Actions token 创建 Release：
 
 ```bash
 cd dist
-sha256sum -c tirtc-esp32s3-kit-1.1.1.tar.gz.sha256
+sha256sum -c tirtc-esp32s3-kit-1.1.2.tar.gz.sha256
 cd ..
 
-git tag -a kit-esp32s3-v1.1.1 -m "TiRTC ESP32-S3 Device Kit 1.1.1"
-git push origin kit-esp32s3-v1.1.1
+git tag -a kit-esp32s3-v1.1.2 -m "TiRTC ESP32-S3 Device Kit 1.1.2"
+git push origin kit-esp32s3-v1.1.2
 ```
 
 metadata 中的版本、标签、上游 commit 和期望 SHA-256 必须与本地可复现打包结果一致；工作流不会从浮动的 `main` 取发布内容。
@@ -926,8 +961,8 @@ metadata 中的版本、标签、上游 commit 和期望 SHA-256 必须与本地
 
 ```bash
 npm test
-git tag -a v0.8.1 -m "v0.8.1"
-git push origin v0.8.1
+git tag -a v0.9.1 -m "v0.9.1"
+git push origin v0.9.1
 ```
 
 不要重复发布已经存在的 npm 版本。版本变化同步更新 `package.json`、`.codex-plugin/plugin.json` 和发布说明。

package/bin/agent-clients.js

@@ -0,0 +1,141 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export const DEFAULT_AGENT_CLIENT = "codex";
+
+const CLIENTS = [
+  {
+    id: "codex",
+    displayName: "Codex",
+    aliases: ["codex"],
+    skillsDir(environment, home) {
+      const codexHome = environment.CODEX_HOME
+        ? resolve(environment.CODEX_HOME)
+        : join(home, ".codex");
+      return join(codexHome, "skills");
+    },
+  },
+  {
+    id: "claude-code",
+    displayName: "Claude Code",
+    aliases: ["claude-code", "claude"],
+    skillsDir(_environment, home) {
+      return join(home, ".claude", "skills");
+    },
+  },
+  {
+    id: "opencode",
+    displayName: "OpenCode",
+    aliases: ["opencode", "open-code"],
+    skillsDir(environment, home) {
+      const configHome = environment.XDG_CONFIG_HOME
+        ? resolve(environment.XDG_CONFIG_HOME)
+        : join(home, ".config");
+      return join(configHome, "opencode", "skills");
+    },
+  },
+  {
+    id: "gemini",
+    displayName: "Gemini CLI",
+    aliases: ["gemini", "gemini-cli"],
+    skillsDir(_environment, home) {
+      return join(home, ".gemini", "skills");
+    },
+  },
+  {
+    id: "copilot",
+    displayName: "GitHub Copilot",
+    aliases: ["copilot", "github-copilot"],
+    skillsDir(_environment, home) {
+      return join(home, ".copilot", "skills");
+    },
+  },
+  {
+    id: "qwen-code",
+    displayName: "Qwen Code",
+    aliases: ["qwen-code", "qwen"],
+    skillsDir(_environment, home) {
+      return join(home, ".qwen", "skills");
+    },
+  },
+  {
+    id: "windsurf",
+    displayName: "Windsurf Cascade",
+    aliases: ["windsurf", "cascade"],
+    skillsDir(_environment, home) {
+      return join(home, ".codeium", "windsurf", "skills");
+    },
+  },
+  {
+    id: "cline",
+    displayName: "Cline",
+    aliases: ["cline"],
+    activationNote:
+      "Cline may require Settings > Features > Enable Skills before discovery.",
+    skillsDir(_environment, home) {
+      return join(home, ".cline", "skills");
+    },
+  },
+  {
+    id: "kiro",
+    displayName: "Kiro",
+    aliases: ["kiro", "kiro-cli"],
+    skillsDir(_environment, home) {
+      return join(home, ".kiro", "skills");
+    },
+  },
+];
+
+const CLIENT_BY_ALIAS = new Map(
+  CLIENTS.flatMap((client) =>
+    client.aliases.map((alias) => [alias, client]),
+  ),
+);
+
+function userHome(environment) {
+  if (process.platform === "win32") {
+    if (environment.USERPROFILE) {
+      return resolve(environment.USERPROFILE);
+    }
+    if (environment.HOMEDRIVE && environment.HOMEPATH) {
+      return resolve(`${environment.HOMEDRIVE}${environment.HOMEPATH}`);
+    }
+  } else if (environment.HOME) {
+    return resolve(environment.HOME);
+  }
+  return homedir();
+}
+
+export function listAgentClients() {
+  return CLIENTS;
+}
+
+export function resolveAgentClient(identifier) {
+  return CLIENT_BY_ALIAS.get(String(identifier).trim().toLowerCase()) ?? null;
+}
+
+export function requireAgentClient(identifier) {
+  const client = resolveAgentClient(identifier);
+  if (!client) {
+    throw new Error(
+      `unsupported client: ${identifier}; supported clients: ${CLIENTS.map((item) => item.id).join(", ")}`,
+    );
+  }
+  return client;
+}
+
+export function defaultSkillsDir(client, environment = process.env) {
+  const resolvedClient =
+    typeof client === "string" ? requireAgentClient(client) : client;
+  return resolvedClient.skillsDir(environment, userHome(environment));
+}
+
+export function clientSessionHint(client, skillName) {
+  const lines = [
+    `Start a new ${client.displayName} session, then ask it to use ${skillName}.`,
+  ];
+  if (client.activationNote) {
+    lines.push(client.activationNote);
+  }
+  return lines.join("\n");
+}

package/bin/esp32-kit-metadata.js

@@ -1,9 +1,9 @@
 export const ESP32_KIT = Object.freeze({
-  archiveName: "tirtc-esp32s3-kit-1.1.1.tar.gz",
-  archiveRoot: "tirtc-esp32s3-kit-1.1.1",
-  releaseTag: "kit-esp32s3-v1.1.1",
-  sha256: "d9818b1caf73b039d46b7f973ad675ac750d259940db4ef22b35a76896a0cdf3",
-  sourceCommit: "35acd405ffb0ed0917fc0671033b844739fe93dd",
-  url: "https://github.com/tangeai/tirtc-device-builder/releases/download/kit-esp32s3-v1.1.1/tirtc-esp32s3-kit-1.1.1.tar.gz",
-  version: "1.1.1",
+  archiveName: "tirtc-esp32s3-kit-1.1.2.tar.gz",
+  archiveRoot: "tirtc-esp32s3-kit-1.1.2",
+  releaseTag: "kit-esp32s3-v1.1.2",
+  sha256: "93dc63ee6450d54e7f31f9a2f0880b462647faa52fd7e70c287bb71f8d3e0b47",
+  sourceCommit: "9aaf47eb3e120ac146b72140e5357b36f4b131f5",
+  url: "https://github.com/tangeai/tirtc-device-builder/releases/download/kit-esp32s3-v1.1.2/tirtc-esp32s3-kit-1.1.2.tar.gz",
+  version: "1.1.2",
 });

package/bin/setup-esp32.js

@@ -10,6 +10,13 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, dirname, join, resolve } from "node:path";
+import {
+  clientSessionHint,
+  DEFAULT_AGENT_CLIENT,
+  defaultSkillsDir,
+  listAgentClients,
+  requireAgentClient,
+} from "./agent-clients.js";
 import { ESP32_KIT } from "./esp32-kit-metadata.js";
 
 const EXPECTED_IDF_LINE = "5.5";
@@ -43,10 +50,10 @@ function setupRootFrom(environment) {
   );
 }
 
-function takeValue(args, index, option) {
+function takeValue(args, index, option, kind = "a path") {
   const value = args[index + 1];
   if (!value || value.startsWith("--")) {
-    throw new Error(`${option} requires a path`);
+    throw new Error(`${option} requires ${kind}`);
   }
   return value;
 }
@@ -54,13 +61,15 @@ function takeValue(args, index, option) {
 export function parseSetupOptions(args, defaults = {}) {
   const environment = defaults.environment ?? process.env;
   const options = {
+    client:
+      defaults.client ?? requireAgentClient(DEFAULT_AGENT_CLIENT),
     forceSkill: false,
     help: false,
     idfDir: null,
     install: false,
     kitArchive: null,
     rootDir: setupRootFrom(environment),
-    skillsDir: defaults.skillsDir,
+    skillsDir: null,
     thingConnectRoot: null,
   };
 
@@ -78,6 +87,13 @@ export function parseSetupOptions(args, defaults = {}) {
       options.forceSkill = true;
       continue;
     }
+    if (argument === "--client") {
+      options.client = requireAgentClient(
+        takeValue(args, index, argument, "a name"),
+      );
+      index += 1;
+      continue;
+    }
     if (
       argument === "--root" ||
       argument === "--skills-dir" ||
@@ -103,9 +119,7 @@ export function parseSetupOptions(args, defaults = {}) {
     throw new Error(`unknown setup option: ${argument}`);
   }
 
-  if (!options.skillsDir) {
-    throw new Error("setup requires a default skills directory");
-  }
+  options.skillsDir ??= defaultSkillsDir(options.client, environment);
   if (options.forceSkill && !options.install) {
     throw new Error("--force-skill requires --install");
   }
@@ -123,8 +137,9 @@ Usage:
 
 Options:
   --install                    Install missing user-space components
+  --client <name>              Agent client (default: codex)
   --root <path>                Managed files (default: ~/.tirtc-device-builder)
-  --skills-dir <path>          Codex skills directory
+  --skills-dir <path>          Override the selected client's Skill directory
   --thing-connect-root <path>  Reuse an existing Device Kit or legacy workspace
   --kit-archive <path>         Install from a local verified Kit archive
   --idf-dir <path>             Reuse or install ESP-IDF at this path
@@ -133,12 +148,13 @@ Options:
 
 Examples:
   npx tirtc-device-builder setup esp32
-  npx tirtc-device-builder setup esp32 --install
+  npx tirtc-device-builder setup esp32 --install --client gemini
   npx tirtc-device-builder setup esp32 --install --root /opt/tirtc-dev
 
 Check mode is read-only. --install downloads the pinned ESP32 Device Kit,
 may clone ESP-IDF v5.5.4, runs Espressif's user-space tool installer, and
-installs the Codex Skill. It does not run sudo or edit shell profiles.`);
+installs the Agent Skill. It does not run sudo or edit shell profiles.
+Supported clients: ${listAgentClients().map((client) => client.id).join(", ")}.`);
 }
 
 function printCheck(status, name, detail) {
@@ -420,6 +436,7 @@ function writeManagedEnvironment(context, packageVersion) {
     device_kit_version: context.deviceKit.version,
     device_kit_root: context.thingConnectRoot,
     thing_connect_root: context.thingConnectRoot,
+    client: context.client.id,
     skills_dir: context.skillsDir,
   };
   writeAtomic(
@@ -542,6 +559,7 @@ function setupContext(options, runtime) {
   const skillVersion = readSkillVersion(skillTarget);
   return {
     activeIdf: active,
+    client: options.client,
     configPath,
     idf,
     idfDir,
@@ -569,8 +587,8 @@ function printState(context, runtime) {
   printCheck("INFO", "setup root", context.rootDir);
   printCheck(
     context.skillReady ? "PASS" : "MISS",
-    "Codex Skill",
-    `${context.skillTarget} (version ${
+    "Agent Skill",
+    `${context.client.displayName}: ${context.skillTarget} (version ${
       context.skillVersion || "missing"
     }; expected ${runtime.packageVersion})`,
   );
@@ -639,13 +657,13 @@ function installSkill(options, context, runtime) {
   const present = existsSync(join(context.skillTarget, "SKILL.md"));
   if (present && context.skillReady && !options.forceSkill) {
     console.log(
-      `SKIP  Codex Skill ${runtime.packageVersion} already exists: ${context.skillTarget}`,
+      `SKIP  ${context.client.displayName} Skill ${runtime.packageVersion} already exists: ${context.skillTarget}`,
     );
     return;
   }
   if (present && !options.forceSkill) {
     throw new Error(
-      `Codex Skill at ${context.skillTarget} has version ${
+      `${context.client.displayName} Skill at ${context.skillTarget} has version ${
         context.skillVersion || "missing"
       }, expected ${runtime.packageVersion}; rerun with --force-skill to replace it`,
     );
@@ -654,6 +672,8 @@ function installSkill(options, context, runtime) {
     runtime.cliPath,
     "install",
     runtime.platform.name,
+    "--client",
+    context.client.id,
     "--skills-dir",
     options.skillsDir,
   ];
@@ -830,8 +850,8 @@ export function runEsp32Setup(args, input) {
   let options;
   try {
     options = parseSetupOptions(args, {
+      client: input.defaultClient,
       environment: runtime.environment,
-      skillsDir: input.defaultSkillsDir,
     });
   } catch (error) {
     console.error(
@@ -849,8 +869,12 @@ export function runEsp32Setup(args, input) {
   if (!options.install) {
     if (!isReady(context)) {
       console.log("OVERALL: NEEDS_SETUP");
+      const clientOption =
+        context.client.id === "codex"
+          ? ""
+          : ` --client ${context.client.id}`;
       console.log(
-        `NEXT: npx tirtc-device-builder@${runtime.packageVersion} setup esp32 --install`,
+        `NEXT: npx tirtc-device-builder@${runtime.packageVersion} setup esp32 --install${clientOption}`,
       );
       return 1;
     }
@@ -867,7 +891,9 @@ export function runEsp32Setup(args, input) {
     return 1;
   }
   console.log("INSTALL PLAN:");
-  console.log(`  Skill:        ${context.skillTarget}`);
+  console.log(
+    `  Skill:        ${context.skillTarget} (${context.client.displayName})`,
+  );
   console.log(`  Device Kit:   ${context.thingConnectRoot} (${ESP32_KIT.version})`);
   console.log(`  ESP-IDF:      ${context.idfDir} (${PINNED_IDF_VERSION})`);
   console.log(`  IDF tools:    ${context.idfToolsPath || "existing default"}`);
@@ -917,6 +943,6 @@ export function runEsp32Setup(args, input) {
   }
   console.log("SETUP: READY");
   console.log(`Environment helper: ${join(context.rootDir, "env.sh")}`);
-  console.log("Start a new Codex session and invoke $tirtc-esp32-builder.");
+  console.log(clientSessionHint(context.client, runtime.platform.skill));
   return 0;
 }

package/bin/tirtc-device-builder.js

@@ -9,9 +9,15 @@ import {
   renameSync,
   rmSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  clientSessionHint,
+  DEFAULT_AGENT_CLIENT,
+  defaultSkillsDir,
+  listAgentClients,
+  requireAgentClient,
+} from "./agent-clients.js";
 import { runEsp32Setup } from "./setup-esp32.js";
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -35,7 +41,8 @@ function printHelp() {
 
 Usage:
   tirtc-device-builder list
-  tirtc-device-builder install <platform> [--skills-dir <path>] [--force]
+  tirtc-device-builder clients
+  tirtc-device-builder install <platform> [--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]
@@ -46,15 +53,18 @@ Platforms:
 
 Examples:
   npx tirtc-device-builder install esp32
+  npx tirtc-device-builder install esp32 --client qwen-code
   npx tirtc-device-builder setup esp32
-  npx tirtc-device-builder setup esp32 --install
+  npx tirtc-device-builder setup esp32 --install --client gemini
   npx tirtc-device-builder install esp32 --skills-dir /absolute/path/skills
   npx tirtc-device-builder doctor esp32 --project /absolute/path/project
   npx tirtc-device-builder boards esp32 match --identity ./board-identity.json
 
-Install defaults to ${"$"}{CODEX_HOME:-~/.codex}/skills. Existing skills are
-preserved unless --force is explicitly supplied. Setup checks are read-only;
-setup --install installs missing user-space components without running sudo.`);
+Install defaults to the selected client's user Skill directory; Codex is the
+default client. Run "clients" to list supported names and resolved directories.
+Existing skills are preserved unless --force is explicitly supplied. Setup
+checks are read-only; setup --install installs missing user-space components
+without running sudo.`);
 }
 
 function fail(message) {
@@ -71,17 +81,11 @@ function resolvePlatform(identifier) {
   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 = {
+    client: requireAgentClient(DEFAULT_AGENT_CLIENT),
     force: false,
-    skillsDir: defaultSkillsDir(),
+    skillsDir: null,
   };
 
   for (let index = 0; index < args.length; index += 1) {
@@ -90,6 +94,15 @@ function parseInstallOptions(args) {
       options.force = true;
       continue;
     }
+    if (argument === "--client") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("--client requires a name");
+      }
+      options.client = requireAgentClient(value);
+      index += 1;
+      continue;
+    }
     if (argument === "--skills-dir") {
       const value = args[index + 1];
       if (!value || value.startsWith("--")) {
@@ -102,6 +115,7 @@ function parseInstallOptions(args) {
     throw new Error(`unknown install option: ${argument}`);
   }
 
+  options.skillsDir ??= defaultSkillsDir(options.client);
   return options;
 }
 
@@ -151,8 +165,10 @@ function installSkill(platform, options) {
   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}.`);
+  console.log(
+    `Installed ${platform.skill} ${PACKAGE.version} for ${options.client.displayName} to ${target}`,
+  );
+  console.log(clientSessionHint(options.client, platform.skill));
 }
 
 function runDoctor(platform, args) {
@@ -214,6 +230,15 @@ function main(args) {
     }
     return 0;
   }
+  if (args[0] === "clients") {
+    for (const client of listAgentClients()) {
+      const marker = client.id === DEFAULT_AGENT_CLIENT ? " (default)" : "";
+      console.log(
+        `${client.id}\t${client.displayName}${marker}\t${defaultSkillsDir(client)}`,
+      );
+    }
+    return 0;
+  }
 
   const [command, identifier, ...rest] = args;
   if (
@@ -244,7 +269,7 @@ function main(args) {
     }
     return runEsp32Setup(rest, {
       cliPath: fileURLToPath(import.meta.url),
-      defaultSkillsDir: defaultSkillsDir(),
+      defaultClient: requireAgentClient(DEFAULT_AGENT_CLIENT),
       packageRoot: PACKAGE_ROOT,
       packageVersion: PACKAGE.version,
       platform,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.8.1",
-  "description": "Install and run TiRTC device-development skills for Codex.",
+  "version": "0.9.1",
+  "description": "Install and run TiRTC device-development Agent Skills across popular coding clients.",
   "license": "MIT",
   "author": {
     "name": "TangeAI",
@@ -30,6 +30,10 @@
   },
   "keywords": [
     "codex",
+    "agent-skills",
+    "claude-code",
+    "gemini-cli",
+    "qwen-code",
     "skill",
     "tirtc",
     "esp32",

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

@@ -70,6 +70,10 @@ implementation and build facts. Stop before code only for a genuine user choice,
 unknown wiring/identity, unavailable matching SDK, or required public-contract
 change.
 
+When SoftAP is the selected Wi-Fi method, carry the fixed SSID, open-auth and
+IPv4 [product contract](references/hardware-ir.md#softap-product-contract) into
+the IR, generated adapter, user-facing instructions and build checks.
+
 ## 5. Generate and port
 
 Generate a new project without overwriting an existing path. Keep platform

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

@@ -5,14 +5,15 @@
 ```bash
 npx tirtc-device-builder@latest setup esp32
 npx tirtc-device-builder@latest setup esp32 --install
+npx tirtc-device-builder@latest clients
 ```
 
-第一条命令只检查；第二条命令自动安装用户目录内缺失的 Skill、带校验的 ESP32 Device Kit、ESP-IDF 5.5.4 和 ESP32-S3 工具链，最后复跑 Doctor。它不执行 `sudo`，也不修改 shell 配置。安装完成后新开 Codex 会话即可调用 Skill。
+第一条命令只检查；第二条命令自动安装用户目录内缺失的 Skill、带校验的 ESP32 Device Kit、ESP-IDF 5.5.4 和 ESP32-S3 工具链，最后复跑 Doctor。它不执行 `sudo`，也不修改 shell 配置。默认客户端是 Codex；Gemini CLI、GitHub Copilot、Qwen Code、Windsurf、Cline、Kiro、Claude Code 和 OpenCode 可通过 `--client <name>` 选择，第三条命令会列出名称和实际安装目录。安装完成后重新启动所选 Agent 客户端。
 
-安装后可在 Codex 中显式调用：
+安装后可直接要求 Agent 使用该 Skill：
 
 ```text
-$tirtc-esp32-builder
+请使用 tirtc-esp32-builder Skill。
 
 开发板：<厂商、完整型号、PCB 版本>
 资料与实物对应：<是/否/未知>
@@ -48,24 +49,24 @@ printf '%s\n' "$TIRTC_THING_CONNECT_ROOT"
 只有板卡型号：
 
 ```text
-$tirtc-esp32-builder 分析 <厂商> <型号> <硬件版本>，目标是 H5 实时视频、talkback 和 AI 对讲。先输出缺失资料与能力结论。
+请使用 tirtc-esp32-builder Skill 分析 <厂商> <型号> <硬件版本>，目标是 H5 实时视频、talkback 和 AI 对讲。先输出缺失资料与能力结论。
 ```
 
 提供本地资料：
 
 ```text
-$tirtc-esp32-builder 使用原理图 /path/board.pdf、BSP /path/vendor-project 和一键安装的 Device Kit，为该板生成 TiRTC H5/AI/CALL/VOIP ESP-IDF 工程并编译；AI/CALL/VOIP 必须通过 AEC 门禁。
+请使用 tirtc-esp32-builder Skill、原理图 /path/board.pdf、BSP /path/vendor-project 和一键安装的 Device Kit，为该板生成 TiRTC H5/AI/CALL/VOIP ESP-IDF 工程并编译；AI/CALL/VOIP 必须通过 AEC 门禁。
 ```
 
 完整实机流程：
 
 ```text
-$tirtc-esp32-builder 使用 /path/hardware-ir.json 生成工程，编译后烧录到 /dev/ttyACM0，验证绑定、H5 和 AI，并生成 TIRTC_PORTING_REPORT.md。
+请使用 tirtc-esp32-builder Skill 和 /path/hardware-ir.json 生成工程，编译后烧录到 /dev/ttyACM0，验证绑定、H5 和 AI，并生成 TIRTC_PORTING_REPORT.md。
 ```
 
 ## ESP-IDF 环境检查
 
-将 `<skill-dir>` 替换为安装后的 Skill 路径，例如 `~/.codex/skills/tirtc-esp32-builder`。
+将 `<skill-dir>` 替换为 `clients` 命令显示的 Skill 根目录下的 `tirtc-esp32-builder`，例如 `~/.qwen/skills/tirtc-esp32-builder`。
 
 生成工程前检查工作区和开发环境：
 
@@ -73,7 +74,7 @@ $tirtc-esp32-builder 使用 /path/hardware-ir.json 生成工程，编译后烧
 python3 <skill-dir>/scripts/doctor.py \
   --expected-idf 5.5 \
   --target esp32s3 \
-  --thing-connect-root ~/.tirtc-device-builder/kits/esp32s3/1.1.1 \
+  --thing-connect-root ~/.tirtc-device-builder/kits/esp32s3/1.1.2 \
   --require-workspace
 ```
 

package/skills/tirtc-esp32-builder/VERSION

@@ -1 +1 @@
-0.8.1
+0.9.1

package/skills/tirtc-esp32-builder/assets/developer-intake-prompt.md

@@ -5,7 +5,7 @@
 ## 精简模板
 
 ```text
-$tirtc-esp32-builder
+请使用 tirtc-esp32-builder Skill。
 
 请为下面这块开发板完成 ThingConnect TiRTC ESP32 接入。
 
@@ -27,6 +27,7 @@ $tirtc-esp32-builder
 
 接入方式：
 - Wi-Fi：<选择一种，或写“根据 BSP 选择”>
+- 选择 SoftAP 时：热点名以 `TiRTC-` 开头、开放认证无需密码，AP 网关和配网页面为 `192.168.6.1` / `http://192.168.6.1`
 - 设备绑定：<选择一种，或写“根据平台合同选择”>
 
 工程：

package/skills/tirtc-esp32-builder/assets/lckfb-szpi-esp32s3-portable-prompt.md

@@ -1,28 +1,30 @@
-$tirtc-esp32-builder
+请使用 tirtc-esp32-builder Skill。
 
 请在当前工作区完成一次立创·实战派 ESP32-S3 的 ThingConnect TiRTC clean-room L-1/L0/L1 接入验证。
 
 这是 Skill、提示词和开发板资料的独立有效性测试。允许访问外网。
 
-前置条件（必须由开发者在启动本次 Codex 会话前完成，不属于本提示词内的操作）：
+前置条件（必须由开发者在启动本次 Agent 会话前完成，不属于本提示词内的操作）：
 
 ```bash
-npx --yes tirtc-device-builder@0.8.1 setup esp32 --install --force-skill
+export TIRTC_AGENT_CLIENT=codex
+npx --yes tirtc-device-builder@0.9.1 setup esp32 --install \
+  --client "$TIRTC_AGENT_CLIENT" --force-skill
 ```
 
-该命令只允许在当前用户目录安装固定版本的 Skill、managed ESP32 Device Kit、ESP-IDF 和工具链；禁止 sudo、系统级包变更和修改 shell profile。安装完成后，开发者必须关闭原 Codex 会话，再从本 clean-room 工作区启动一个新会话，然后粘贴本提示词。
+把 `TIRTC_AGENT_CLIENT` 改为 `clients` 命令列出的目标客户端名称。该命令只允许在当前用户目录安装固定版本的 Skill、managed ESP32 Device Kit、ESP-IDF 和工具链；禁止 sudo、系统级包变更和修改 shell profile。安装完成后，开发者必须关闭原 Agent 会话，再从本 clean-room 工作区启动一个新会话，然后粘贴本提示词。
 
 本轮第一步先只读运行：
 
 ```bash
-npx --yes tirtc-device-builder@0.8.1 --version
-npx --yes tirtc-device-builder@0.8.1 setup esp32
+npx --yes tirtc-device-builder@0.9.1 --version
+npx --yes tirtc-device-builder@0.9.1 setup esp32 --client "$TIRTC_AGENT_CLIENT"
 ```
 
-必须根据命令的实际输出和本机文件确认：npm 包为 0.8.1、已安装 Skill 的 `VERSION` 为 0.8.1、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.1，并且 Doctor 对 `--expected-kit 1.1.1` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
+必须根据命令的实际输出和本机文件确认：npm 包为 0.9.1、已安装 Skill 的 `VERSION` 为 0.9.1、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.2，并且 Doctor 对 `--expected-kit 1.1.2` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
 
 工作区与 clean-room 边界：
-- 将启动 Codex 时的当前目录定义为 `WORKSPACE_ROOT`。
+- 将启动 Agent 客户端时的当前目录定义为 `WORKSPACE_ROOT`。
 - 所有工程输入和输出必须位于 `WORKSPACE_ROOT`。
 - 不得读取 `WORKSPACE_ROOT` 之外的项目、兄弟目录、父目录项目、备份、旧构建、日志、报告或 artifact。
 - 如果目标输出目录已经存在，停止并报告 clean-room 条件不成立；不要读取、覆盖或删除该目录。
@@ -58,7 +60,7 @@ npx --yes tirtc-device-builder@0.8.1 setup esp32
 - AI 对讲必须实现全双工和 AEC；构建阶段必须证明同时采集播放、真实播放参考与 `echo_cancellation.enabled=true`，实机结果仍只能在 L2-L7 验证后声明。
 
 接入要求：
-- SoftAP 配网，凭证保存 NVS。
+- SoftAP 配网：热点名使用 `TiRTC-` 前缀、开放认证无需密码，AP 网关和配网页面为 `192.168.6.1` / `http://192.168.6.1`；目标 Wi-Fi 凭证保存 NVS。
 - 验证码绑定，并复用已有绑定。
 - 分别实现 `wifi-clear` 和 `tirtc-clear`。
 - 平台发现本轮先使用 HTTP；HTTPS 留待独立验收。

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

@@ -47,7 +47,7 @@ The intake phase requires:
 
 At intake, `corroborated` on these fields means the design is resolved from authoritative sources and is safe to implement. After compilation, promote a field to `build_verified` only when the generated source, component lock, semantic gate, compile result, or post-link gate establishes it. Build assessment reruns the applicable project-relative [audio contract](audio-contract.md), [video contract](video-contract.md), and mandatory [runtime contract](runtime-contract.md); self-declared `resolved=true`, `pipeline_safe=true`, or memory-budget booleans cannot replace them. The build phase requires an exact on-disk artifact SHA-256 and returns `BUILD_VERIFIED` only when every requested feature passes. Runtime measurements never need to be invented to pass intake or build.
 
-SoftAP is one Wi-Fi option, not a universal requirement. BLE, SmartConfig, factory NVS, development configuration, or a documented custom method can satisfy intake when the selected path is evidenced. Committed plaintext credentials are always `BLOCKED`.
+SoftAP is one Wi-Fi option, not a universal requirement. BLE, SmartConfig, factory NVS, development configuration, or a documented custom method can satisfy intake when the selected path is evidenced. A selected SoftAP must satisfy the product contract in [Hardware IR](hardware-ir.md#softap-product-contract). Committed plaintext credentials are always `BLOCKED`.
 
 ## Non-negotiable runtime checks
 

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

@@ -16,7 +16,7 @@ The automatic branch never runs `sudo` or modifies a persistent shell profile. W
 When `<setup-root>/env.sh` exists, use it only as an activation prefix for the current command:
 
 ```bash
-bash -lc '. "<setup-root>/env.sh" && python3 "<skill-dir>/scripts/doctor.py" --expected-idf 5.5 --expected-kit 1.1.1 --target esp32s3 --require-workspace'
+bash -lc '. "<setup-root>/env.sh" && python3 "<skill-dir>/scripts/doctor.py" --expected-idf 5.5 --expected-kit 1.1.2 --target esp32s3 --require-workspace'
 ```
 
 The helper contains paths, not device or network credentials. Read `<setup-root>/config.json` when exact managed paths are needed; the environment helper does not authorize unrelated downloads, shell-profile changes, flashing, or credential writes.
@@ -26,7 +26,7 @@ Run the doctor before generation, build, flash, or monitor:
 ```bash
 python3 <skill-dir>/scripts/doctor.py \
   --expected-idf 5.5 \
-  --expected-kit 1.1.1 \
+  --expected-kit 1.1.2 \
   --target esp32s3 \
   --require-workspace
 ```
@@ -37,7 +37,7 @@ Add `--project <generated-project>` after generation so the doctor can compare `
 
 The automatic setup downloads a versioned minimal Kit instead of cloning the ThingConnect server repository. A managed Kit is ready only when its generator and SDK files exist and `manifest.json` declares the exact pinned `kit_version`. A stale environment or managed configuration that points at an older Kit is ignored in favor of the current versioned managed path. The setup configuration records the version read from that manifest; it never substitutes the desired version for the actual one.
 
-The installed Skill has its own `<skill-dir>/VERSION` marker. Setup requires it to equal the npm package version and reports both values. Replacing a missing or mismatched marker requires the explicit `--install --force-skill` flow and a new Codex session.
+The installed Skill has its own `<skill-dir>/VERSION` marker. Setup requires it to equal the npm package version and reports both values. Replacing a missing or mismatched marker requires the explicit `--install --force-skill` flow and a new session in the selected Agent client.
 
 For an explicitly selected legacy workspace, omit `--expected-kit`; otherwise resolve the generation root in this order:
 

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

@@ -61,6 +61,26 @@ 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.
 
+### SoftAP product contract
+
+When the selected method is SoftAP:
+
+- generate the SSID as `TiRTC-<device suffix>` so its exact, case-sensitive
+  prefix is `TiRTC-`; use a stable non-secret suffix and keep the complete SSID
+  within the ESP32 32-byte limit;
+- configure an open network (`WIFI_AUTH_OPEN`) with an empty AP password so a
+  user can connect directly;
+- assign the AP netif, gateway and provisioning server `192.168.6.1/24`, serve
+  the setup page at `http://192.168.6.1`, and lease clients from that subnet.
+  With ESP-IDF, stop DHCP before changing the AP netif IP information and
+  restart it afterward.
+
+Record these values on the selected SoftAP method as `ssid_prefix: "TiRTC-"`,
+`auth_mode: "open"`, and `ipv4_address: "192.168.6.1"`. The Hardware IR gate
+returns `NEEDS_CONFIRMATION` when one is missing and `BLOCKED` when one differs.
+Keep the provisioning endpoints available only while onboarding is active, and
+disable the AP or restart into STA mode after credentials are accepted.
+
 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.
 
 ## Artifact-bound HIL

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

@@ -30,7 +30,7 @@ Turn every discovered invariant that can regress into a focused test or post-lin
 
 Wi-Fi provisioning and ThingConnect binding are separate state machines.
 
-Select one evidenced Wi-Fi credential method from SoftAP, BLE, SmartConfig, secure factory/NVS provisioning, development configuration, or a documented custom path. SoftAP is not mandatory. A board without AP provisioning can reach `READY_TO_PORT` through another available method when credentials remain outside source control and a reprovisioning path is defined.
+Select one evidenced Wi-Fi credential method from SoftAP, BLE, SmartConfig, secure factory/NVS provisioning, development configuration, or a documented custom path. SoftAP is not mandatory. A board without AP provisioning can reach `READY_TO_PORT` through another available method when credentials remain outside source control and a reprovisioning path is defined. When SoftAP is selected, implement and record the fixed [SoftAP product contract](hardware-ir.md#softap-product-contract).
 
 Development configuration may inject credentials through an untracked sdkconfig, environment, or provisioning artifact. Treat committed plaintext credentials as `BLOCKED`. Never copy SSIDs/passwords into Hardware IR, reports, examples, or source.
 

package/skills/tirtc-esp32-builder/scripts/hardware_ir.py

@@ -61,6 +61,9 @@ WIFI_METHOD_TYPES = {
     "development_config",
     "custom",
 }
+SOFTAP_SSID_PREFIX = "TiRTC-"
+SOFTAP_AUTH_MODE = "open"
+SOFTAP_IPV4_ADDRESS = "192.168.6.1"
 BINDING_METHOD_TYPES = {
     "verification_code",
     "factory_bound",
@@ -444,6 +447,9 @@ def validate_onboarding(
                 errors.append(
                     f"{prefix}.type must be one of " + ", ".join(sorted(WIFI_METHOD_TYPES))
                 )
+            if method_type == "softap":
+                for field in ("ssid_prefix", "auth_mode", "ipv4_address"):
+                    nullable_string(method.get(field), f"{prefix}.{field}", errors)
             nullable_bool(method.get("available"), f"{prefix}.available", errors)
             validate_verification(
                 method.get("verification"), f"{prefix}.verification", errors
@@ -926,6 +932,26 @@ def wifi_requirement(onboarding: dict[str, Any]) -> Requirement:
         return "NEEDS_CONFIRMATION", "selected Wi-Fi method availability is unknown", 0
     if available is False:
         return "BLOCKED", "selected Wi-Fi method is unavailable", 0
+    if method.get("type") == "softap":
+        softap_fields = (
+            ("ssid_prefix", SOFTAP_SSID_PREFIX, "SSID prefix"),
+            ("auth_mode", SOFTAP_AUTH_MODE, "authentication mode"),
+            ("ipv4_address", SOFTAP_IPV4_ADDRESS, "IPv4 address"),
+        )
+        for field, expected, label in softap_fields:
+            value = method.get(field)
+            if value is None:
+                return (
+                    "NEEDS_CONFIRMATION",
+                    f"SoftAP {label} is unknown; expected {expected!r}",
+                    0,
+                )
+            if value != expected:
+                return (
+                    "BLOCKED",
+                    f"SoftAP {label} must be {expected!r}, got {value!r}",
+                    0,
+                )
     verification = method.get("verification")
     level = VERIFICATION_LEVELS.get(verification, 0)
     if level < VERIFICATION_LEVELS["corroborated"]: