taphound 0.2.0-dev.1 → 0.2.0-dev.11

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/brand/taphound-mark.svg" width="128" alt="TapHound HoundMark">
+  <img src="assets/brand/taphound-mark.svg" width="128" alt="TapHound - AI-Agent-driven Android UI testing and state verification CLI">
 </p>
 
 # TapHound
@@ -8,193 +8,93 @@ 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.
+**An AI-Agent-driven CLI for native Android UI testing and state verification.**
 
-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 records, generates, and deterministically replays UI **Journeys** for native Android apps. The current development release is TapHound for Android. It is built for teams whose AI coding agents (Droid, Claude Code, Codex, Cursor, ...) write code faster than people can review it: the agent proposes test steps from your source code and live device state, and TapHound executes, verifies, and reports — deterministically, with no AI or visual guessing inside the replay loop — so "done" means proven on a device.
 
-TapHound only handles verification. Compiling and installing the APK are independent prerequisites, handled by the developer or AI agent in a separate loop:
+The TapHound Journey is its own JSON protocol with its own recorder, generation, replay, and assertion model — distinct from and incompatible with the Android CLI's Journey concept.
+
+## How It Works
+
+TapHound Core never invokes AI models. Agents may analyze source and propose actions, but state binding, risk confirmation, device execution, final replay, and assertions are all handled deterministically by TapHound.
+
+TapHound only handles verification. Building and installing the APK are independent prerequisites in the developer/agent loop, which the bundled Skills check at two depths:
 
 ```
-edit code → build APK → install to device → taphound verify → loop until passing
+classify the change → edit code → build & install → taphound-flash (seconds, smoke) → repeat
+                                                  → taphound-verify-change (proof) → done
 ```
 
-## Requirements
+The change type picks the proof: new behavior (with or without UI) must pass an Acceptance Contract; a refactor, including an XML → Compose migration, must reproduce previously captured behavior. See [Workflow Skills](https://github.com/caikaidev/TapHound/blob/main/docs/workflow-skills.md).
 
-- 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
+## Capabilities
 
-Run environment diagnostics first:
+- **Record** — interactively record a Journey on a real device (`taphound record`).
+- **Verify** — deterministically replay a Journey and publish a report (`taphound verify`); `verify --diff <ref>` replays only the Journeys a Git change affects.
+- **Generate** — AI-agent-driven Journey generation: evidence-bound steps, risk confirmation for sensitive actions, and a final exact replay before a Journey is published (`taphound generation ...`).
+- **Trust chain** — Acceptance Contracts, behavior Baselines, and Failure Classification turn a replay into an auditable verdict.
+- **Knowledge** — semantic Anchors and Screens let Journeys survive UI refactors and resource-id renames.
+- **Agent Skills** — five installable Skills (`taphound init`): `taphound-flash` (a standalone adb-only smoke check while coding), `taphound-verify-change` (the done-gate: accept new behavior or preserve existing behavior), `taphound-journey-brief-author` and `taphound-journey-generator` (turn a Case into a verified Journey), and `taphound-case-suite` (many Cases, one at a time).
 
-```bash
-taphound doctor --project /path/to/android-project
-```
+## Requirements
 
-When `--device` is omitted, exactly one device with status `device` must be connected; use `--device <serial>` to select among multiple devices.
+- Node.js 22 or newer
+- Android SDK, ADB, and the `android` CLI on PATH
+- An online device or emulator with the target APK already installed
+- On macOS, grant Android CLI the Accessibility and Screen Recording permissions
 
-## Installation and Local Development
+`taphound-flash` alone needs only Node.js 18+ and ADB.
 
-Install from source:
+Check your environment first:
 
 ```bash
-npm ci
-npm run build
-npm link
-taphound --help
+taphound doctor --project /path/to/android-project
 ```
 
-Full local quality gate:
+## Installation
 
 ```bash
-npm test
-npm run typecheck
-npm run lint
-npm run build
-npm run brand:render
-git diff --exit-code -- assets/brand/png
+npm ci
+npm run dev:setup   # tests, typecheck, lint, build, npm link
 ```
 
-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.
+See the [local testing guide](https://github.com/caikaidev/TapHound/blob/main/docs/local-testing.md) for tarball and device validation steps, and [Releasing](https://github.com/caikaidev/TapHound/blob/main/docs/releasing.md) for how versions are published.
 
-## CLI Commands
+## Quick Start
 
-- `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.
+Create `.taphound/config.json` in your Android project (full reference: [config-schema](https://github.com/caikaidev/TapHound/blob/main/docs/config-schema.md), complete example: [`examples/.taphound/config.json`](https://github.com/caikaidev/TapHound/blob/main/examples/.taphound/config.json)):
 
 ```json
 {
   "version": 1,
-  "run": {
-    "packageName": "com.example.app",
-    "activity": ".MainActivity"
-  },
-  "idle": {
-    "pollIntervalMs": 200,
-    "stablePolls": 2,
-    "timeoutMs": 5000
-  },
-  "artifactsDir": ".taphound/runs"
+  "run": { "packageName": "com.example.app", "activity": ".MainActivity" }
 }
 ```
 
-## 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:
+Record a Journey, then replay it:
 
 ```bash
-taphound init
+taphound record --project . --name "Search flow" --output .taphound/journeys/search.json
+taphound verify --project . --journey .taphound/journeys/search.json
 ```
 
-Non-interactive mode:
+For AI agents, install the bundled Skills and let the agent drive generation:
 
 ```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
+## Documentation
 
-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.
+- [Journey protocol](https://github.com/caikaidev/TapHound/blob/main/docs/journey-schema.md) · [Configuration reference](https://github.com/caikaidev/TapHound/blob/main/docs/config-schema.md) · [Report schema](https://github.com/caikaidev/TapHound/blob/main/docs/report-schema.md)
+- [Principles](https://github.com/caikaidev/TapHound/blob/main/docs/principles.md) · [Workflow Skills and development scenarios](https://github.com/caikaidev/TapHound/blob/main/docs/workflow-skills.md) · [Agent integration](https://github.com/caikaidev/TapHound/blob/main/docs/agent-integration.md) · [Journey Generator guide](https://github.com/caikaidev/TapHound/blob/main/docs/journey-generator-guide.md)
+- [Acceptance Contracts](https://github.com/caikaidev/TapHound/blob/main/docs/contract-schema.md) · [Baselines & regression](https://github.com/caikaidev/TapHound/blob/main/docs/checkpoint-regression.md) · [Failure classification](https://github.com/caikaidev/TapHound/blob/main/docs/failure-classification.md)
+- [Semantic Anchors](https://github.com/caikaidev/TapHound/blob/main/docs/semantic-anchor.md) · [Capability matrix](https://github.com/caikaidev/TapHound/blob/main/docs/capability-matrix.md) · [`observe`](https://github.com/caikaidev/TapHound/blob/main/docs/observe.md)
+- [Runtime backends](https://github.com/caikaidev/TapHound/blob/main/docs/architecture/runtime-backend.md) · [Local development & testing](https://github.com/caikaidev/TapHound/blob/main/docs/local-testing.md) · [Releasing](https://github.com/caikaidev/TapHound/blob/main/docs/releasing.md)
 
 ## 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.
+- Android only, with a single explicitly selected device.
+- TapHound does not build or install APKs; the target app must already be installed.
+- The Recorder is a TapHound-mediated interaction flow; it does not observe arbitrary user touches.
+- Replay, device operations, and assertions are fully deterministic — no AI or visual inference in Core.

package/README.zh-CN.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/brand/taphound-mark.svg" width="128" alt="TapHound HoundMark">
+  <img src="assets/brand/taphound-mark.svg" width="128" alt="TapHound - 基于 AI Agent 的 Android UI 测试与状态验证 CLI 工具">
 </p>
 
 # TapHound
@@ -8,23 +8,42 @@
 
 > Follow every tap. Catch every regression.
 
-TapHound 是一个用于 App Journey 录制、生成与确定性验证的 TypeScript/Node.js CLI。当前开发版本 TapHound for Android 支持录制原生 Android 工作流，也支持外部 Agent 基于 Project Context 和实时设备状态生成 Journey。
+**一款基于 AI Agent 驱动的 Android 原生应用 UI 测试与状态验证 CLI 工具。**
 
-TapHound Journey 是本项目完全自研的 JSON 协议、Recorder、Generation、Replay 与断言模型，与 Android CLI 官方 Journey 概念不同且不兼容。TapHound Core 不调用模型：外部 Agent 可以分析源码并提出操作，但状态绑定、风险确认、设备执行、最终 Replay 与断言均由 TapHound 确定性完成。
+TapHound 面向原生 Android 应用，提供 UI **Journey** 的录制、生成与确定性回放，当前开发版本为 TapHound for Android。它面向这样的团队：AI 编码 Agent（Droid、Claude Code、Codex、Cursor 等）写代码的速度已经快过人能审阅的速度。Agent 基于源码与实时设备状态提出测试步骤，TapHound 负责执行、验证与报告——全程确定性，回放链路中不含任何 AI 或视觉猜测——让"完成"意味着在真机上被证明过。
 
-TapHound 只负责验证。编译和安装 APK 是独立的前置步骤，由开发者或 AI Agent 在验证循环中完成：
+TapHound Journey 是本项目自研的 JSON 协议，拥有独立的 Recorder、Generation、Replay 与断言模型，与 Android CLI 官方 Journey 概念不同且不兼容。
+
+## 工作原理
+
+TapHound Core 不调用 AI 模型。外部 Agent 可以分析源码并提出操作，但状态绑定、风险确认、设备执行、最终 Replay 与断言均由 TapHound 确定性完成。
+
+TapHound 只负责验证。编译和安装 APK 是开发者/Agent 循环中独立的前置步骤，内置 Skill 在两个深度上做检查：
 
 ```
-修改代码 → 编译 APK → 安装到设备 → taphound verify → 循环直到符合预期
+判断改动类型 → 修改代码 → 编译并安装 → taphound-flash（几秒，冒烟）→ 继续修改
+                                      → taphound-verify-change（证明）→ 完成
 ```
 
+改动类型决定证明方式：新行为（无论是否涉及 UI）必须通过 Acceptance Contract；重构（包括 XML → Compose 迁移）必须复现改动前采集的行为。详见 [Workflow Skills](https://github.com/caikaidev/TapHound/blob/main/docs/workflow-skills.md)。
+
+## 核心能力
+
+- **录制** —— 在真机上交互式录制 Journey（`taphound record`）。
+- **验证** —— 确定性回放 Journey 并发布报告（`taphound verify`）；`verify --diff <ref>` 只回放某次 Git 变更影响的 Journey。
+- **生成** —— AI Agent 驱动的 Journey 生成：步骤绑定证据、敏感操作需风险确认，发布前必须通过一次精确回放（`taphound generation ...`）。
+- **信任链** —— Acceptance Contract、行为 Baseline 与 Failure Classification，把一次回放转化为可审计的判定结论。
+- **知识体系** —— 语义化的 Anchor 与 Screen，让 Journey 在 UI 重构和 resource-id 改名后仍然可用。
+- **Agent Skill** —— 五个可安装的 Skill（`taphound init`）：`taphound-flash`（编码过程中只依赖 adb 的独立冒烟检查）、`taphound-verify-change`（完成前的把关：验收新行为或证明行为保持不变）、`taphound-journey-brief-author` 与 `taphound-journey-generator`（把一个 Case 变成经过验证的 Journey）、`taphound-case-suite`（多个 Case 逐个推进）。
+
 ## 环境要求
 
 - Node.js 22 或更高版本
-- Android SDK、ADB 和一个在线设备或模拟器
-- 目标 APK 已安装到设备（TapHound 不负责编译或安装）
-- 可调用的 `android` CLI
-- macOS 上授予 Android CLI 所需的辅助功能、屏幕录制等权限
+- Android SDK、ADB，以及可调用的 `android` CLI
+- 一个在线设备或模拟器，且目标 APK 已安装
+- macOS 上需授予 Android CLI 辅助功能与屏幕录制权限
+
+单独使用 `taphound-flash` 只需要 Node.js 18+ 与 ADB。
 
 先执行环境诊断：
 
@@ -32,169 +51,50 @@ TapHound 只负责验证。编译和安装 APK 是独立的前置步骤，由开
 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 run dev:setup   # 测试、类型检查、Lint、构建、npm link
 ```
 
-完整的源码、npm tarball 与 Android 设备验证步骤见[本地测试指南](docs/local-testing.md)。更换开发机器时按[换机后 TODO](TODO.md)继续跟踪剩余验收与 npm `dev` 预发布。
+tarball 与真机验证步骤见[本地测试指南](https://github.com/caikaidev/TapHound/blob/main/docs/local-testing.md)，版本发布流程见[发布](https://github.com/caikaidev/TapHound/blob/main/docs/releasing.md)。
 
-## 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)。
+在 Android 项目中创建 `.taphound/config.json`（完整字段参考 [config-schema](https://github.com/caikaidev/TapHound/blob/main/docs/config-schema.md)，完整示例见 [`examples/.taphound/config.json`](https://github.com/caikaidev/TapHound/blob/main/examples/.taphound/config.json)）：
 
 ```json
 {
   "version": 1,
-  "run": {
-    "packageName": "com.example.app",
-    "activity": ".MainActivity"
-  },
-  "idle": {
-    "pollIntervalMs": 200,
-    "stablePolls": 2,
-    "timeoutMs": 5000
-  },
-  "artifactsDir": ".taphound/runs"
+  "run": { "packageName": "com.example.app", "activity": ".MainActivity" }
 }
 ```
 
-## 交互式录制
-
-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：
+录制一条 Journey，然后回放验证：
 
 ```bash
-taphound init
+taphound record --project . --name "Search flow" --output .taphound/journeys/search.json
+taphound verify --project . --journey .taphound/journeys/search.json
 ```
 
-非交互模式：
+面向 AI Agent：安装内置 Skill，由 Agent 驱动生成流程：
 
 ```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`，不会覆盖原始失败，对应可选产物也可能缺失。
+- [Journey 协议](https://github.com/caikaidev/TapHound/blob/main/docs/journey-schema.md) · [配置参考](https://github.com/caikaidev/TapHound/blob/main/docs/config-schema.md) · [报告协议](https://github.com/caikaidev/TapHound/blob/main/docs/report-schema.md)
+- [设计原则](https://github.com/caikaidev/TapHound/blob/main/docs/principles.md) · [Workflow Skill 与开发场景](https://github.com/caikaidev/TapHound/blob/main/docs/workflow-skills.md) · [Agent 集成](https://github.com/caikaidev/TapHound/blob/main/docs/agent-integration.md) · [Journey Generator 指南](https://github.com/caikaidev/TapHound/blob/main/docs/journey-generator-guide.md)
+- [Acceptance Contract](https://github.com/caikaidev/TapHound/blob/main/docs/contract-schema.md) · [Baseline 与回归对比](https://github.com/caikaidev/TapHound/blob/main/docs/checkpoint-regression.md) · [失败分类](https://github.com/caikaidev/TapHound/blob/main/docs/failure-classification.md)
+- [Semantic Anchor](https://github.com/caikaidev/TapHound/blob/main/docs/semantic-anchor.md) · [能力矩阵](https://github.com/caikaidev/TapHound/blob/main/docs/capability-matrix.md) · [`observe`](https://github.com/caikaidev/TapHound/blob/main/docs/observe.md)
+- [运行时后端](https://github.com/caikaidev/TapHound/blob/main/docs/architecture/runtime-backend.md) · [本地开发与测试](https://github.com/caikaidev/TapHound/blob/main/docs/local-testing.md) · [发布](https://github.com/caikaidev/TapHound/blob/main/docs/releasing.md)
 
 ## 当前限制
 
-- 只支持 Android 与单个明确选择的设备。
-- TapHound 不负责编译或安装 APK，假设目标应用已安装到设备。编译和安装由开发者或 AI Agent 在验证循环中独立完成。
+- 仅支持 Android，且同一时刻只操作一台明确选择的设备。
+- TapHound 不负责编译或安装 APK，目标应用必须已安装到设备。
 - 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 前提。
+- 回放、设备操作与断言完全确定性，Core 中不包含 AI 或视觉推理。