taphound 0.2.0-dev.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,200 @@
+<p align="center">
+  <img src="assets/brand/taphound-mark.svg" width="128" alt="TapHound HoundMark">
+</p>
+
+# TapHound
+
+English | [简体中文](./README.zh-CN.md)
+
+> Follow every tap. Catch every regression.
+
+TapHound is a TypeScript/Node.js CLI for recording, generating, and deterministically verifying app journeys. The current development release, TapHound for Android, supports recording native Android workflows and AI-agent-driven journey generation based on a Project Context and live device state.
+
+The TapHound Journey is a purpose-built JSON protocol with its own recorder, generation, replay, and assertion model. It is distinct from and incompatible with the Android CLI's official Journey concept. TapHound Core never invokes AI models: external agents may analyze source code and propose actions, but state binding, risk confirmation, device execution, final replay, and assertions are all handled deterministically by TapHound.
+
+TapHound only handles verification. Compiling and installing the APK are independent prerequisites, handled by the developer or AI agent in a separate loop:
+
+```
+edit code → build APK → install to device → taphound verify → loop until passing
+```
+
+## Requirements
+
+- Node.js 22 or newer
+- Android SDK, ADB, and an online device or emulator
+- Target APK already installed on the device (TapHound does not build or install)
+- The `android` CLI available on PATH
+- On macOS, grant Android CLI the required Accessibility and Screen Recording permissions
+
+Run environment diagnostics first:
+
+```bash
+taphound doctor --project /path/to/android-project
+```
+
+When `--device` is omitted, exactly one device with status `device` must be connected; use `--device <serial>` to select among multiple devices.
+
+## Installation and Local Development
+
+Install from source:
+
+```bash
+npm ci
+npm run build
+npm link
+taphound --help
+```
+
+Full local quality gate:
+
+```bash
+npm test
+npm run typecheck
+npm run lint
+npm run build
+npm run brand:render
+git diff --exit-code -- assets/brand/png
+```
+
+See the [local testing guide](docs/local-testing.md) for source, npm tarball, and Android device validation steps. When switching dev machines, follow the [machine handoff TODO](TODO.md) to track remaining acceptance and npm `dev` pre-release.
+
+## CLI Commands
+
+- `doctor`: checks Node.js, ADB, Android CLI, app installation, permissions, and device.
+- `record`: interactively execute actions and record a Journey.
+- `verify`: deterministically replay a Journey and publish a report.
+- `project describe`: output stable Android project facts.
+- `context validate` / `context status`: validate or check a Project Context.
+- `generation start` / `observe` / `step` / `confirm` / `manual` / `finalize`: manage deterministic Journey generation sessions.
+- `init`: install the TapHound AI Journey Skill for AI agents.
+
+## Configuration
+
+Create a `taphound.config.json` in the Android project. `run.packageName` is required and never guessed from APK filenames or activities; see [`examples/taphound.config.json`](examples/taphound.config.json) for a complete example.
+
+```json
+{
+  "version": 1,
+  "run": {
+    "packageName": "com.example.app",
+    "activity": ".MainActivity"
+  },
+  "idle": {
+    "pollIntervalMs": 200,
+    "stablePolls": 2,
+    "timeoutMs": 5000
+  },
+  "artifactsDir": ".taphound/runs"
+}
+```
+
+## Interactive Recording
+
+The TapHound Recorder displays the current layout, lets you choose an action and target, and executes it through ADB. It does not listen for arbitrary touch events. Each successful step automatically records `activity.before` and `activity.after`; failed steps are not added to the Journey; the complete file is written atomically only after you choose Finish.
+
+```bash
+taphound record \
+  --project /path/to/android-project \
+  --config taphound.config.json \
+  --name "Search flow" \
+  --output journeys/search.json
+```
+
+The Recorder does not auto-generate business `expect` assertions. Activity, Element, or Logcat assertions should be added explicitly by developers or external agents. See [Journey Schema](docs/journey-schema.md) for protocol details.
+
+Supported actions include `click`, `longClick`, `inputText`, `swipe`, `scrollTo`, `back`, and `wait`. `scrollTo` swipes within a deterministic `container` up to `maxSwipes` times, stopping once the target `locator` resolves uniquely without clicking it.
+
+## Agent-Driven Journey Generation
+
+The repository ships a [`taphound-ai-journey` Skill](assets/skills/taphound-ai-journey/SKILL.md) that guides agents such as Droid, Claude Code, Copilot, and Cursor:
+
+1. Use `project describe` and the Android project source to generate a Project Context with evidence hashes.
+2. Use `context validate` / `context status` to check Context validity and freshness.
+3. Start a `generation` session, iteratively observe authoritative device state, propose strict steps, and let TapHound execute them.
+4. Use `generation finalize` to replay from the initial state and publish the Journey only after verification passes.
+
+```bash
+taphound generation start \
+  --project /path/to/android-project \
+  --context .taphound/context/project-context.json \
+  --device emulator-5554 \
+  --json
+```
+
+The device is bound at `generation start`; subsequent `observe`, `step`, `confirm`, and `manual` commands use that binding via the session. See the Skill's [`GUIDE.md`](assets/skills/taphound-ai-journey/GUIDE.md) for the full workflow.
+
+### Installing the Skill for Other AI Agents
+
+`taphound init` copies the TapHound AI Journey Skill into each agent's Skill directory. Interactively select at least one agent:
+
+```bash
+taphound init
+```
+
+Non-interactive mode:
+
+```bash
+taphound init --agent claude,codex,cursor,droid
+```
+
+Global install (user-level directory):
+
+```bash
+taphound init --agent claude --global
+```
+
+Supported agents and paths:
+
+| Agent | Project-level path | User-level path |
+|---|---|---|
+| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
+| Codex | `.agents/skills/` | `~/.agents/skills/` |
+| Cursor | `.cursor/skills/` | `~/.cursor/skills/` |
+| Droid | `.factory/skills/` | `~/.factory/skills/` |
+| Other | `.agents/skills/` | `~/.agents/skills/` |
+
+The Skill is published with the npm package; `taphound init` copies it from the package to the target directory. Re-running `init` overwrites existing Skill files.
+
+## Deterministic Verification
+
+```bash
+taphound verify \
+  --project /path/to/android-project \
+  --config taphound.config.json \
+  --journey journeys/search.json
+```
+
+Temporarily override package, activity, device, or report path:
+
+```bash
+taphound verify \
+  --project /path/to/android-project \
+  --journey journeys/search.json \
+  --device emulator-5554 \
+  --package com.example.app \
+  --activity .MainActivity \
+  --reports /tmp/taphound-runs
+```
+
+For agent invocations:
+
+```bash
+taphound verify --project . --journey journeys/search.json --json
+```
+
+`--json` mode guarantees exactly one final JSON value on stdout; progress and diagnostics go to stderr. See [Agent Integration](docs/agent-integration.md) and [Report Schema](docs/report-schema.md).
+
+## Reports
+
+Each verification writes to an independent directory, always containing `report.json` and `summary.txt`, with step logs provided based on actual execution. A final screenshot and full Logcat are collected on a best-effort basis. The original verification failure is preserved in `primaryFailure`; screenshot or logcat collection issues go into `secondaryErrors` and never overwrite the original failure; corresponding optional artifacts may be missing.
+
+## Current Limitations
+
+- Only Android is supported, with a single explicitly selected device.
+- TapHound does not build or install the APK. It assumes the target app is already installed. Building and installing are done independently by the developer or AI agent in the verification loop.
+- The Recorder is a TapHound-mediated interaction flow; it does not observe arbitrary user touches on the device.
+- The Recorder only provides swipe for scrollable elements that have bounds from the Android CLI; Replay does not guess swipe regions for elements missing bounds.
+- Annotated screenshot fallback applies only to `click` and `longClick`, and requires an explicitly saved `#label`.
+- Replay, device operations, and assertions are fully deterministic, with no AI or visual inference.
+- The repository provides an Agent Skill installable via `taphound init` for other agents, but there is no dedicated SubAgent wrapper yet.
+- Regular tests do not require a real device; Replay and Generation device acceptance requires explicitly setting `TAPHOUND_ACCEPTANCE_DEVICE=1` and meeting external Android prerequisites.

package/README.zh-CN.md

@@ -0,0 +1,200 @@
+<p align="center">
+  <img src="assets/brand/taphound-mark.svg" width="128" alt="TapHound HoundMark">
+</p>
+
+# TapHound
+
+[English](./README.md) | 简体中文
+
+> Follow every tap. Catch every regression.
+
+TapHound 是一个用于 App Journey 录制、生成与确定性验证的 TypeScript/Node.js CLI。当前开发版本 TapHound for Android 支持录制原生 Android 工作流，也支持外部 Agent 基于 Project Context 和实时设备状态生成 Journey。
+
+TapHound Journey 是本项目完全自研的 JSON 协议、Recorder、Generation、Replay 与断言模型，与 Android CLI 官方 Journey 概念不同且不兼容。TapHound Core 不调用模型：外部 Agent 可以分析源码并提出操作，但状态绑定、风险确认、设备执行、最终 Replay 与断言均由 TapHound 确定性完成。
+
+TapHound 只负责验证。编译和安装 APK 是独立的前置步骤，由开发者或 AI Agent 在验证循环中完成：
+
+```
+修改代码 → 编译 APK → 安装到设备 → taphound verify → 循环直到符合预期
+```
+
+## 环境要求
+
+- Node.js 22 或更高版本
+- Android SDK、ADB 和一个在线设备或模拟器
+- 目标 APK 已安装到设备（TapHound 不负责编译或安装）
+- 可调用的 `android` CLI
+- macOS 上授予 Android CLI 所需的辅助功能、屏幕录制等权限
+
+先执行环境诊断：
+
+```bash
+taphound doctor --project /path/to/android-project
+```
+
+未指定 `--device` 时必须恰好有一个状态为 `device` 的设备；存在多个设备时用 `--device <serial>` 明确选择。
+
+## 安装与本地开发
+
+当前版本可从源码安装：
+
+```bash
+npm ci
+npm run build
+npm link
+taphound --help
+```
+
+完整本地质量门：
+
+```bash
+npm test
+npm run typecheck
+npm run lint
+npm run build
+npm run brand:render
+git diff --exit-code -- assets/brand/png
+```
+
+完整的源码、npm tarball 与 Android 设备验证步骤见[本地测试指南](docs/local-testing.md)。更换开发机器时按[换机后 TODO](TODO.md)继续跟踪剩余验收与 npm `dev` 预发布。
+
+## CLI 命令
+
+- `doctor`：检查 Node.js、ADB、Android CLI、应用安装、权限和设备。
+- `record`：交互式执行操作并录制 Journey。
+- `verify`：确定性重放 Journey 并发布报告。
+- `project describe`：输出稳定的 Android 项目事实。
+- `context validate` / `context status`：校验或检查 Project Context。
+- `generation start` / `observe` / `step` / `confirm` / `manual` / `finalize`：管理确定性 Journey 生成会话。
+- `init`：为 AI Agent 安装 TapHound AI Journey Skill。
+
+## 配置
+
+在 Android 项目中创建 `taphound.config.json`。`run.packageName` 必填，不会从 APK 文件名或 Activity 猜测；完整示例见 [`examples/taphound.config.json`](examples/taphound.config.json)。
+
+```json
+{
+  "version": 1,
+  "run": {
+    "packageName": "com.example.app",
+    "activity": ".MainActivity"
+  },
+  "idle": {
+    "pollIntervalMs": 200,
+    "stablePolls": 2,
+    "timeoutMs": 5000
+  },
+  "artifactsDir": ".taphound/runs"
+}
+```
+
+## 交互式录制
+
+TapHound Recorder 展示当前 Layout，让用户选择 Action 和目标，然后由 TapHound 自己通过 ADB 执行操作。它不监听任意触摸。每个成功步骤自动记录 `activity.before` 与 `activity.after`；失败步骤不会加入 Journey；只有选择 Finish 后才原子写入完整文件。
+
+```bash
+taphound record \
+  --project /path/to/android-project \
+  --config taphound.config.json \
+  --name "Search flow" \
+  --output journeys/search.json
+```
+
+Recorder 不自动生成业务 `expect`。Activity、Element 或 Logcat 断言应由开发者或外部 Agent 显式补充。协议细节见 [Journey Schema](docs/journey-schema.md)。
+
+支持的 Action 包括 `click`、`longClick`、`inputText`、`swipe`、`scrollTo`、`back` 和 `wait`。`scrollTo` 在确定的 `container` 中最多滑动 `maxSwipes` 次，目标 `locator` 唯一解析成功后停止，不会继续点击目标。
+
+## Agent 驱动的 Journey 生成
+
+源码仓库提供 [`taphound-ai-journey` Skill](assets/skills/taphound-ai-journey/SKILL.md)，指导 Droid、Claude Code、Copilot、Cursor 等 Agent：
+
+1. 使用 `project describe` 和 Android 项目源码生成带证据哈希的 Project Context。
+2. 使用 `context validate` / `context status` 检查 Context 的有效性和时效性。
+3. 启动 `generation` 会话，循环观察权威设备状态、提出严格步骤并交由 TapHound 执行。
+4. 使用 `generation finalize` 从初始状态完整 Replay，并仅在验证通过后发布 Journey。
+
+```bash
+taphound generation start \
+  --project /path/to/android-project \
+  --context .taphound/context/project-context.json \
+  --device emulator-5554 \
+  --json
+```
+
+设备在 `generation start` 时绑定，后续 `observe`、`step`、`confirm` 和 `manual` 命令通过 session 使用该绑定。完整流程见 Skill 的 [`GUIDE.md`](assets/skills/taphound-ai-journey/GUIDE.md)。
+
+### 为其他 AI Agent 安装 Skill
+
+`taphound init` 将 TapHound AI Journey Skill 复制到各 Agent 的 Skill 目录。交互式多选至少选择一个 Agent：
+
+```bash
+taphound init
+```
+
+非交互模式：
+
+```bash
+taphound init --agent claude,codex,cursor,droid
+```
+
+全局安装（用户级目录）：
+
+```bash
+taphound init --agent claude --global
+```
+
+支持的 Agent 及路径：
+
+| Agent | 项目级路径 | 用户级路径 |
+|---|---|---|
+| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
+| Codex | `.agents/skills/` | `~/.agents/skills/` |
+| Cursor | `.cursor/skills/` | `~/.cursor/skills/` |
+| Droid | `.factory/skills/` | `~/.factory/skills/` |
+| Other | `.agents/skills/` | `~/.agents/skills/` |
+
+Skill 随 npm 包发布，`taphound init` 从包内复制到目标目录。重新运行 `init` 会覆盖已有 Skill 文件。
+
+## 确定性验证
+
+```bash
+taphound verify \
+  --project /path/to/android-project \
+  --config taphound.config.json \
+  --journey journeys/search.json
+```
+
+临时覆盖 Package、Activity、设备或报告路径：
+
+```bash
+taphound verify \
+  --project /path/to/android-project \
+  --journey journeys/search.json \
+  --device emulator-5554 \
+  --package com.example.app \
+  --activity .MainActivity \
+  --reports /tmp/taphound-runs
+```
+
+Agent 调用时使用：
+
+```bash
+taphound verify --project . --journey journeys/search.json --json
+```
+
+`--json` 模式保证 stdout 只有一个最终 JSON 值，进度和诊断写入 stderr。详见 [Agent 集成](docs/agent-integration.md) 与 [报告协议](docs/report-schema.md)。
+
+## 报告
+
+每次验证写入独立目录，固定包含 `report.json` 与 `summary.txt`，按实际执行结果提供步骤日志，并尽力采集最终截图和完整 Logcat。原始验证失败保存在 `primaryFailure`；截图或日志采集问题进入 `secondaryErrors`，不会覆盖原始失败，对应可选产物也可能缺失。
+
+## 当前限制
+
+- 只支持 Android 与单个明确选择的设备。
+- TapHound 不负责编译或安装 APK，假设目标应用已安装到设备。编译和安装由开发者或 AI Agent 在验证循环中独立完成。
+- Recorder 是 TapHound 介导的交互流程，不观察用户在设备上的任意触摸。
+- Recorder 只为 Android CLI 返回了 bounds 的 scrollable 元素提供 swipe；Replay 不会为缺失 bounds 的元素猜测滑动区域。
+- 标注截图回退只适用于 click 与 longClick，且必须显式保存 `#编号`。
+- Replay、设备操作和断言完全确定性，不包含 AI 或视觉推理。
+- 源码仓库提供 Agent Skill，也可通过 `taphound init` 为其他 Agent 安装，但尚无专用 SubAgent 封装。
+- 普通测试不要求真实设备；Replay 与 Generation 真机验收需要显式设置 `TAPHOUND_ACCEPTANCE_DEVICE=1` 并满足外部 Android 前提。

package/assets/brand/taphound-mark.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg"
+     viewBox="0 0 1024 1024"
+     role="img"
+     aria-labelledby="title">
+  <title id="title">TapHound HoundMark</title>
+  <path fill="#1B1D21" fill-rule="evenodd" clip-rule="evenodd" d="M228 702 350 582c31-31 40-59 36-90-6-50-42-81-86-100 45-20 77-47 112-80 40 6 79 26 104 62 16 21 37 31 64 34l70 13c10 2 15 11 12 22-8 35-29 57-60 68l-49 16c-29 9-49 29-62 58l-56 121H228Zm165-355c28 22 48 50 48 80-1 34-19 60-49 72 14-30 16-60 7-87-9-28-19-45-6-65Z"/>
+  <circle cx="755" cy="443" r="24" fill="#FF5A1F"/>
+  <path fill="#FF5A1F" d="M760 359a84 84 0 0 1 84 84 84 84 0 0 1-84 84v-30a54 54 0 0 0 54-54 54 54 0 0 0-54-54v-30Z"/>
+</svg>