truthmark 1.3.0 → 1.5.0

package/README.zh.md

@@ -1,294 +1,642 @@
 # Truthmark
 
-**Truthmark 为 AI 软件开发安装仓库事实工作流。**
+**你的代理会写代码。Truthmark 让它们的上下文在 Git 中可审查。**
 
 [English](README.md) | [Deutsch](README.de.md) | 中文 | [Español](README.es.md) | [Русский](README.ru.md)
 
-<img src="docs/assets/truthmark-banner.png" alt="Truthmark 横幅" width="100%" />
+![Truthmark 横幅](docs/assets/truthmark-banner.png)
 
-AI 编码代理已经能很快写代码了。真正昂贵的是让仓库事实和实际变更保持一致。
+AI 编码代理改变仓库的速度，可能比人类对齐上下文的速度更快。
 
-Truthmark 在这个流程里加入了一个收尾阶段的工作流保护。正常路径很简单：
+Truthmark 修复代码写完后通常会坏掉的那一部分：仓库事实。
 
-- 代理修改功能代码
-- 运行相关测试
-- 代理结束前，已安装的 Truth Sync 工作流更新已映射的事实文档
-- 如果产生了事实文档 diff，就审查它
-
-大多数工具要求团队养成一种习惯。Truthmark 把这个习惯变成仓库工作流基础设施。
-
-Truthmark 把 AI 工作流变成仓库基础设施，而不是个人工具配置。它把一个 Git 原生、按分支生效的事实层安装到仓库里，为代理提供明确的路由和有边界的工作流载体，并让这些事实继续以 Git diff 的形式可审查，而不是散落在提示历史、陈旧文档或私有工具状态里。
-
-这之所以重要，是因为工作流跟着分支一起存在。仓库一旦初始化，规则、路由和已安装的工作流载体就会随仓库一起移动，协作和交接也就不再过度依赖某个人的本地配置。
-
-对于已经知道代理能生成代码的团队，Truthmark 解决的是下一个问题：当 AI 辅助开发规模化时，怎样让仓库本身继续保持清晰、可审查、可治理。
-
-## 可视化概览
-
-<table>
-	<tr>
-		<td align="center" width="50%">
-			<img src="docs/assets/truthmark-features.png" alt="Truthmark 功能" width="100%" />
-			<br><strong>功能</strong><br>
-			Truthmark 安装了什么，以及工作流载体如何拆分。
-		</td>
-		<td align="center" width="50%">
-			<img src="docs/assets/truthmark-position.png" alt="Truthmark 定位" width="100%" />
-			<br><strong>定位</strong><br>
-			Truthmark 相对提示词、记忆和规格工作流所处的位置。
-		</td>
-	</tr>
-	<tr>
-		<td align="center" colspan="2">
-			<img src="docs/assets/truthmark-syncflow.png" alt="Truthmark 同步流程" width="100%" />
-			<br><strong>同步流程</strong><br>
-			Truth Sync 如何在交接前收束普通代码变更。
-		</td>
-	</tr>
-</table>
+它安装一个 Git 原生、按分支生效的工作流层，帮助 AI 编码代理更新正确的文档、尊重所有权边界，并把人类可以审查的普通 diff 留下来。
 
-## 为什么团队会采用它
+没有托管服务。
 
-Truthmark 不是为了让代理显得更聪明，而是为了让 AI 辅助的仓库变更更值得信任。
+没有数据库。
 
-- 代码变更后的已安装 Truth Sync 工作流，把文档维护从团队习惯变成工作流保护。
-- 按分支生效的事实会跟着代码一起走，所以审查者可以在普通 Git diff 里检查当前事实。
-- 仓库原生的工作流载体让推广更轻、交接更稳，不再只依赖个人本地配置。
-- `docs/truthmark/areas.md` 和委托的子路由文件里的显式路由，为代理提供更清晰的所有权边界和更安全的写入路径。
-- 本地优先的运行方式避免了守护进程、数据库、远程服务或 MCP 依赖。
-- 路由模型与语言无关，并为常见的 JavaScript、TypeScript、Go、Python、C# 和 Java 代码表面提供覆盖率诊断。
+没有隐藏记忆层。
 
-对技术负责人来说，它的价值是没有额外基础设施负担的治理：测试、代码审查和所有权仍然承担真正的工作；Truthmark 让代理上下文变得持久、可检查，并且限定在当前分支内。
+没有需要运行的额外服务器。
 
-## Truthmark 适合放在哪里
+只有随分支移动的仓库事实。
 
-Truthmark 不是一套通用 AI 生产力套件。它占据的是工具栈里的一个特定层级：随实现保持一致、按分支生效、可审查的仓库事实。
+## 问题
 
-| 如果你需要                                   | 最合适的选择                   |
-| -------------------------------------------- | ------------------------------ |
-| 单次编码会话获得更好结果                     | 更好的提示词和更清晰的任务边界 |
-| 一个代理或操作者跨会话延续便利性             | 记忆类工具                     |
-| 为新功能做规格优先的规划                     | Spec Kit 等规格工具            |
-| 随代码一起流转、可审查、按分支生效的仓库事实 | Truthmark                      |
+AI 编码代理很擅长产出代码。这会制造一种新的失效模式。
 
-重点不是提示词、记忆或规格没有用。重点是，它们单独都不能把仓库事实变成一个已提交、可检查，并且能经受交接、审查和分支分叉的资产。
+实现改变了，但仓库叙事开始漂移：
 
-## 目录
+- 行为存在于聊天历史里
+- 架构文档落后
+- 产品决策在交接后消失
+- 审查者看到代码 diff，却看不到相关的事实 diff
+- 分支悄悄发展出不同版本的“什么是真的”
+- 每个代理会话都必须从头重新发现上下文
 
-- [为什么团队会采用它](#为什么团队会采用它)
-- [Truthmark 解决什么问题](#truthmark-解决什么问题)
-- [Truthmark 适合放在哪里](#truthmark-适合放在哪里)
-- [快速开始](#快速开始)
-- [它如何运行](#它如何运行)
-- [它会安装什么](#它会安装什么)
-- [命令](#命令)
-- [它为什么存在](#它为什么存在)
-- [项目状态](#项目状态)
-- [文档](#文档)
-- [非目标](#非目标)
-- [许可证](#许可证)
+Truthmark 把这种脆弱上下文变成已提交的仓库基础设施。
 
-## Truthmark 解决什么问题
+它不是依赖每个人和每个代理都记住正确的文档习惯，而是把这个习惯安装进仓库。
 
-Truthmark 把仓库事实变成代理可见的显式工作流载体：
+## 承诺
 
-- `.truthmark/config.yml` 定义已提交的层级契约。
-- `docs/truthmark/areas.md` 和委托的子路由文件把代码区域映射到负责它们的文档。
-- Truth Document 在无需修改代码时，为已实现行为生成或修复规范事实文档。
-- Truth Sync 在功能性变更发生时，让已映射的事实文档保持同步。
-- Truth Realize 为文档优先的变更提供有边界的代码更新路径。
-- `truthmark check` 验证最终形成的事实产物。
-- 整个模型保持本地优先和 Git 原生。
+当代理修改功能代码时，工作不应该只以代码 diff 结束。
 
-核心承诺很简单：代理上下文会成为已提交的仓库状态，而不是私有会话产物。
+Truthmark 的正常路径是：
 
-## 快速开始
+```text
+代理修改功能代码
+运行相关测试
+Truth Sync 检查已映射的事实文档
+需要时更新事实文档
+人类审查代码 diff + 事实 diff
+提交或交接
+```
+
+核心价值是：**AI 工作更容易被信任，因为仓库仍然清晰可读。**
 
-在你想初始化的仓库中安装 Truthmark：
+## 两个表面，一个事实系统
+
+Truthmark 不只是一个 CLI。
+
+它有两个不同表面，这个区别很重要。
+
+### 1. 面向人的 CLI
+
+CLI 面向维护者、审查者和自动化。
+
+用它来配置仓库、安装或刷新工作流文件、验证事实产物，并生成可选的审查上下文。
 
 ```bash
-cd /path/to/your-repo
-npm install -g truthmark
 truthmark config
 truthmark init
 truthmark check
 ```
 
-如果你想从源码检出中试用尚未发布的变更：
+CLI 会准备并验证仓库环境。
+
+它不是 AI 工作流运行时。
+
+### 2. 面向 AI 的工作流表面
+
+面向 AI 的表面是给编码代理使用的。
+
+Truthmark 会安装宿主原生的技能、提示、命令、受管说明块和受支持的子代理表面，让 AI 代理能在正常编码工具中遵循仓库专属的事实工作流。
+
+示例：
+
+```text
+/truthmark-sync
+/truthmark-document
+/truthmark-structure
+/truthmark-realize
+/truthmark-preview
+/truthmark-check
+```
+
+它们看起来像命令，是因为代理宿主通过 slash commands、prompts、skills 或 project commands 暴露工作流。
+
+它们不是 shell 命令。
+
+它们是面向 AI 的工作流入口。
+
+这种拆分就是产品：
+
+```text
+人类拥有仓库契约
+Truthmark 把契约安装进 repo
+代理在契约内工作
+事实更新以 Git diff 出现
+人类审查结果
+```
+
+## 快速开始
+
+### 要求
+
+- Node.js `>=20`
+- npm
+- Git 仓库
+
+### 安装 Truthmark
+
+在你想初始化的仓库中运行：
 
 ```bash
-cd /path/to/truthmark
-npm install
-npm run build
 cd /path/to/your-repo
-node /path/to/truthmark/dist/main.js config
-node /path/to/truthmark/dist/main.js init
-node /path/to/truthmark/dist/main.js check
+npm install -g truthmark
 ```
 
-在运行 `init` 之前先检查 `.truthmark/config.yml`；它是已提交的层级契约。`init` 之后，检查生成的工作流载体和路由文件，确保路由指向的文档确实是拥有你代码的文档：
+### 创建仓库事实契约
+
+```bash
+truthmark config
+```
+
+这会创建：
 
 ```text
 .truthmark/config.yml
-docs/truthmark/areas.md
-docs/truthmark/areas/repository.md
-docs/templates/behavior-doc.md
-docs/truth/README.md
-docs/truth/repository/README.md
-docs/truth/repository/overview.md
-AGENTS.md
-CLAUDE.md
-GEMINI.md
 ```
 
-支持的平台是 `codex`、`opencode`、`claude-code`、`github-copilot` 和 `gemini-cli`。默认配置包含全部平台；请先从 `.truthmark/config.yml` 中移除不使用的平台，再重新运行 `truthmark init`。
-默认脚手架把 truth `README.md` 作为索引，并把当前行为事实放在有边界的叶子文档中，例如 `docs/truth/repository/overview.md`。
+继续之前先审查这个文件。它定义仓库中已提交的层级契约。
+
+### 安装工作流表面
+
+```bash
+truthmark init
+```
+
+这会安装或刷新：
 
-现有仓库通常需要在 `init` 之后做一次清理：当生成的 `repository` 路由过宽、所有权跨越多个产品或服务，或路由文件仍指向占位文档时，运行已安装的 Truth Structure 工作流。Truth Structure 会拆分过宽的路由，创建或修复初始的规范事实文档，并在功能代码工作开始前为 Truth Sync 提供精确目标。Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-structure` 调用它；OpenCode 风格的宿主可以用 `/skill truthmark-structure` 调用它。
+- 路由文件
+- 事实文档脚手架
+- 受管说明块
+- 已配置平台的面向 AI 工作流表面
 
-## 它如何运行
+### 验证设置
 
-Truthmark 最强的地方是默认路径，而不是一堆手动命令。由实际执行的代理和宿主环境决定是委托执行，还是内联运行已安装的工作流。
+```bash
+truthmark check
+```
+
+然后在提交前审查生成的文件。
+
+具体文件取决于 `.truthmark/config.yml`，但安装形态始终相同：路由、truth scaffolding、紧凑的受管说明，以及为启用平台生成的 host-native 工作流表面。
 
-### 已实现但无文档的行为
+确切文件取决于 `.truthmark/config.yml`。
 
-当实现已经存在，但规范事实文档缺失或较弱时，使用这个流程：
+## 第一次真实使用
+
+大多数仓库在初始化后需要一次清理。
+
+默认脚手架从一个宽泛的 `repository` 区域开始。真实仓库通常需要更精确的路由。
+
+让你的代理把宽泛路由拆成真实的产品、服务、领域或所有权区域：
 
 ```text
-用户识别一个已实现的行为或 API 端点
-用户显式调用 Truth Document
-代理读取实现、测试、路由和现有文档
-代理只写 truth docs 和路由
-审查 truth-doc diff
+/truthmark-structure 将宽泛的 repository 区域拆成 auth、billing 和 notifications
 ```
 
-Truth Document 是手动、implementation-first 的流程：代码作为证据，事实文档被创建或修复，且不能修改功能代码。Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-document` 调用它；OpenCode 风格的宿主可以用 `/skill truthmark-document` 调用它。
+之后就正常使用你的 AI 编码代理。
+
+当代理修改功能代码时，Truth Sync 会作为收尾保护，在交接前检查已映射的事实文档是否需要改变。
+
+## 你会得到什么
+
+| 能力 | 作用 |
+| --- | --- |
+| Git 原生事实 | 将仓库事实保存在已提交的 Markdown 和配置中。 |
+| 按分支生效的上下文 | 事实随分支移动，而不是存在于私有会话中。 |
+| 面向人的 CLI | 为维护者提供设置、刷新、验证和检查命令。 |
+| 面向 AI 的工作流 | 为代理提供宿主原生的同步、文档、结构、预览、实现和审计工作流。 |
+| 显式路由 | 将代码区域映射到规范事实文档。 |
+| 可审查交接 | 为代码和事实文档都产生普通 Git diff。 |
+| 本地优先运行 | 不需要托管服务、守护进程、数据库或 MCP 服务器。 |
+| 更安全的写入边界 | 区分 code-first、doc-first、read-only 和 doc-only 工作流。 |
+| 验证 | 报告路由、权限边界、frontmatter、链接、生成表面、分支范围、freshness 和覆盖率问题。 |
+
+## 视觉概览
+
+![Truthmark 功能](docs/assets/truthmark-features.png)
+
+**功能：** Truthmark 会安装什么，以及工作流表面如何拆分。
+
+![Truthmark 定位](docs/assets/truthmark-position.png)
+
+**定位：** Truthmark 相对提示词、记忆和规格工作流所处的位置。
+
+![Truthmark 同步流程](docs/assets/truthmark-syncflow.png)
+
+**同步流程：** Truth Sync 如何在交接前收束普通代码变更。
+
+## 为什么团队会采用它
+
+Truthmark 面向已经知道 AI 代理能生成代码的团队。
+
+下一个问题是治理。
+
+不是仪式化治理。治理就是一个简单问题：
+
+> 这次 AI 辅助变更之后，仓库还在讲真话吗？
+
+Truthmark 通过已提交文件、显式路由和可审查 diff 帮助团队回答这个问题。
+
+当你需要这些东西时，它会很有用：
+
+- 更少的文档漂移
+- 更好的交接
+- 按分支生效的产品事实
+- 持久的架构和 API 上下文
+- 文档与代码之间的明确所有权
+- 更安全的代理写入边界
+- 可审查上下文，而不是隐藏记忆
+- 仍然能从已提交 repo 文件运行的 AI 工作流
+
+## Truthmark 适合放在哪里
+
+Truthmark 不替代提示词、记忆、规格、测试或代码审查。
+
+它给这些工作流一个可以落在 Git 里的持久位置。
+
+| 需求 | 更合适的选择 |
+| --- | --- |
+| 单次代理会话获得更好输出 | 更好的提示词 |
+| 个人或会话级连续性 | 记忆工具 |
+| plan-first 的功能工作 | 规格工作流 |
+| 随代码移动、按分支生效的事实 | Truthmark |
+| 验证行为正确性 | 测试和审查 |
+| 审查 AI 辅助的上下文变更 | Truthmark 加 Git 审查 |
+
+Truthmark 的范围故意很窄：
 
 ```text
-/truthmark-document 在 docs/truth/authentication 下记录已实现的会话超时行为
+让仓库事实显式化
+把它路由到代码
+围绕它安装代理工作流
+让结果在 Git 中可审查
 ```
 
-### 常规代码变更
+## Truthmark 如何运行
+
+Truthmark 在本地针对当前 Git worktree 运行。
+
+面向人的 CLI 读取并写入仓库文件，然后退出。
+
+面向 AI 的工作流表面是已提交文件，代理宿主之后可以加载它们。这意味着代理可以从仓库状态遵循已安装工作流，而不依赖后台 Truthmark 进程。
+
+这些层的关系如下：
+
+```mermaid
+flowchart LR
+  Human["Human / CI"] --> CLI["Truthmark CLI"]
+  CLI --> Config["配置与路由图"]
+  CLI --> Truth["规范 truth 文档"]
+  CLI --> Surfaces["生成的 host-native 工作流"]
+  Surfaces --> Hosts["Codex / Claude Code / Copilot / OpenCode / Gemini"]
+  Hosts --> Worktree["当前 Git worktree"]
+  Hosts -->|"helper checks / validate / index"| CLI
+  Worktree --> Truth
+```
+
+Agent 不会连接 Truthmark daemon，但工作流需要验证、索引或 helper checks 时，它们可以运行已安装的 Truthmark CLI。
+
+Truthmark 拥有它生成的工作流表面，但关键契约是架构层面的：仓库内配置和路由把 agent 指向规范 truth 文档，host-native 工作流则让每个受支持的 agent 用自己的方式运行同一套 Truthmark 流程。
+
+生成的工作流表面包含 Truthmark 版本标记。升级 Truthmark 后，重新运行：
+
+```bash
+truthmark init
+```
+
+然后审查生成的 diff。
+
+## 支持的代理平台
+
+默认配置包含所有受支持平台。
 
-多数用户不需要直接调用 Truth Sync。关键在于，只要功能代码发生变化，已安装的代理工作流就会把 Truth Sync 当作收尾保护。正常路径是：
+从 `.truthmark/config.yml` 中移除你不使用的平台，然后重新运行：
+
+```bash
+truthmark init
+```
+
+| 平台配置名 | 生成表面 | 调用形式 |
+| --- | --- | --- |
+| `codex` | Skill packages 和 verifier agents | `/truthmark-*` 或 `$truthmark-*` |
+| `claude-code` | Project skills、verifier agents 和受管说明 | `/truthmark-*` |
+| `github-copilot` | Agent skills、prompt commands、custom agents 和受管说明 | 支持的 Copilot IDE 中使用 `/truthmark-*`；Copilot CLI 中使用 `@truth-*` custom agents |
+| `opencode` | Skill packages 和 verifier agents | `/skill truthmark-*` |
+| `gemini-cli` | Agent skills、slash commands、subagents 和受管说明 | `/truthmark:*` |
+
+未知平台名是配置错误。
+
+移除一个平台会停止该平台未来的刷新。它不会删除此前生成的文件。
+
+## 面向 AI 的工作流
+
+这些工作流会安装到受支持的 AI 编码宿主中。
+
+代理或代理宿主会在仓库工作期间使用它们。它们不是顶层 shell 命令。
+
+| 工作流 | 方向 | 何时使用 | 写入边界 |
+| --- | --- | --- | --- |
+| Truth Structure | topology-first | 默认路由过宽、所有权跨多个区域，或路由文件仍指向占位内容。 | 创建或修复路由和起始事实文档。 |
+| Truth Document | implementation-first | 行为已经存在于代码中，但规范事实文档缺失或薄弱。 | 只写事实文档和路由。不能改变功能代码。 |
+| Truth Sync | code-first | 功能代码已变更，已映射事实文档可能需要在交接前更新。 | 更新事实文档。Truth Sync 不能重写功能代码。 |
+| Truth Preview | read-only | 代理需要在编辑前预览可能的路由。 | 只读。不授权写入。 |
+| Truth Realize | doc-first | 产品或架构事实文档在前，代码应更新以匹配它们。 | 只更新代码。代理不能编辑它正在实现的事实文档。 |
+| Truth Check | audit-first | 审查者或代理需要审计仓库事实健康状况。 | 审计并报告。 |
+
+### 重要区别
+
+不要混淆这两个表面：
+
+| 表面 | 使用者 | 示例 | 含义 |
+| --- | --- | --- | --- |
+| 面向人的 CLI | 人类、脚本、类似 CI 的检查 | `truthmark check` | 从终端验证仓库事实产物。 |
+| 面向 AI 的工作流 | 编码代理和代理宿主 | `/truthmark-check` | 请求代理运行已安装的审计工作流。 |
+
+名称有意相关，但表面不同。
+
+## 普通 AI 辅助代码变更
+
+大多数用户不应该每次都手动调用 Truth Sync。
+
+Truth Sync 是为功能代码变更安装的收尾保护。
 
 ```text
 代理修改功能代码
-运行相关测试
-已安装的 Truth Sync 工作流在代理结束前运行
-如果生成了 truth-doc diff，就审查它
-提交或交接工作
+代理运行或请求相关测试
+已安装工作流检测到功能代码变更
+Truth Sync 检查已映射事实文档
+代理在需要时更新事实文档
+人类审查代码 diff + 事实 diff
+```
+
+直接调用仍然适用于排查问题、强制提前同步，或让交接更明确：
+
+```text
+/truthmark-sync 现在同步仓库事实，然后再交接
 ```
 
-Truth Sync 是 code-first：代码在前，事实文档跟随，且 Truth Sync 不能重写功能代码。它的主要职责是在功能代码发生变化时，通过已安装的代理工作流充当收尾保护。直接调用主要用于排查问题、交接前提前同步，或有意运行这套工作流。
+## 已有行为但没有文档
 
-Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-sync` 调用它。OpenCode 风格的宿主可以用 `/skill truthmark-sync` 调用它。
+当实现已经存在，但仓库事实不完整时，使用 Truth Document。
 
 ```text
-/truthmark-sync 现在同步仓库 truth，然后再交接
+/truthmark-document 在 docs/truth/authentication 下记录已实现的会话超时行为
 ```
 
-### 文档优先变更
+Truth Document 会把实现、测试、路由文件和现有文档作为证据来检查。
+
+它只写事实文档和路由。
 
-当产品或架构决策从文档开始时，使用这个流程：
+它不能改变功能代码。
+
+## Doc-first 变更
+
+当产品或架构决策从文档开始，并且代码应更新以匹配时，使用 Truth Realize。
 
 ```text
-用户编辑 truth docs
-用户显式调用 Truth Realize
-代理读取 truth docs 和相关代码
-代理只更新代码
-运行相关测试
-提交或交接工作
+/truthmark-realize 将 docs/truth/authentication/session-timeout.md 实现到代码中
 ```
 
-Truth Realize 是手动、文档优先的流程：事实文档在前，代码跟随，代理不能编辑它正在实现的事实文档。
+Truth Realize 是 doc-first。
+
+事实文档在前。代码跟随。
 
-Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-realize` 调用它。OpenCode 风格的宿主可以用 `/skill truthmark-realize` 调用它。
+代理不能编辑它正在实现的事实文档。
+
+## 只读路由预览
+
+当代理需要在变更前理解可能的路由时，使用 Truth Preview。
 
 ```text
-/truthmark-realize 将 docs/truth/authentication/session-timeout.md 实现为代码
+/truthmark-preview 预览 billing API 变更的可能事实路由
 ```
 
-## 它会安装什么
+Truth Preview 是 read-only。
 
-Truthmark 把持久化的工作流载体保持得很小，而且是仓库原生的。运行 `truthmark init` 之后，仓库本身就携带路由、规则和已安装的工作流载体，因此团队不再只依赖某个人的本地配置。
+它是选择器和规划辅助，不是写入授权，也不是 Truth Check 的替代品。
 
-- `.truthmark/config.yml`，用于机器可读的已提交层级契约
-- `docs/truthmark/areas.md`，用于根路由索引
-- `docs/truthmark/areas/**/*.md`，用于委托的子路由文件
-- `docs/templates/behavior-doc.md` 以及 `docs/templates/` 下其他按类型划分的模板，用作生成工作流采用的可编辑 truth doc 标准
-- 面向已配置平台的受管说明块，例如 `AGENTS.md`、`CLAUDE.md`、Copilot 指令和 `GEMINI.md`
-- 面向 Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 的宿主原生技能、提示或命令
+## 仓库事实审计
 
-安装后的工作流载体就是运行时：
+当你需要面向代理的审计工作流时，使用 Truth Check。
 
-- Truth Structure 创建或修复区域路由和起始事实文档。
-- Truth Document 为已实现行为创建或修复事实文档。
-- Truth Sync 在功能性变更发生时，让已映射的事实文档保持同步。
-- Truth Realize 更新代码，使其符合事实文档。
-- Truth Check 审计仓库事实的健康状况。
+```text
+/truthmark-check 在审查前审计路由和事实覆盖
+```
 
-功能 `README.md` 是索引。Truth Sync 预期读取并更新用于描述当前行为的有边界叶子文档。生成的工作流载体会保留仓库规则的权威性，同时把实现代码和规范事实文档当作当前行为的证据。
+当你需要终端验证时，使用面向人的 CLI：
 
-生成的载体由 Truthmark 管理，包含版本标记，并可通过 `truthmark init` 刷新。
+```bash
+truthmark check
+```
+
+两者都有用。它们不是同一个表面。
+
+## 面向人的 CLI 命令
+
+大多数维护者从三个命令开始。
+
+| 命令 | 用途 |
+| --- | --- |
+| `truthmark config` | 创建 `.truthmark/config.yml`。除非使用 `--stdout`，否则只写这个文件。 |
+| `truthmark init` | 从已审查配置安装或刷新已配置的工作流表面。 |
+| `truthmark check` | 验证配置、权限边界、路由、承载决策的文档、frontmatter、内部链接、分支范围、生成表面、freshness 和覆盖率诊断。 |
+
+可选的仓库情报辅助工具会为当前 checkout 生成派生审查上下文。生成的工作流 skill packages 也可以暴露 helper manifests 和 helper policies，用来调用已安装的 `truthmark validate ... --json` CLI validators；这些 helpers 是加速器，不是打包进仓库的本地脚本，也不是事实来源。独立的 Copilot prompts 和 Gemini commands 在已安装 runner 可用时使用同一 CLI validator contract；不可用时应报告可见的 skipped helper status，并进行 manual validation。
+
+它们不是事实来源。
+
+| 命令 | 用途 |
+| --- | --- |
+| `truthmark index` | 为当前 checkout 构建 RepoIndex 和 RouteMap JSON。 |
+| `truthmark impact --base <ref>` | 将变更文件映射到已路由事实文档、所属路由、附近测试和公开符号。 |
+| `truthmark context --workflow <workflow> [--base <ref>]` | 为 Truth Sync、Truth Document 或 Truth Realize 生成有边界的 ContextPack。使用 `--format markdown` 生成可读版本。 |
+
+受支持位置可使用 `--json` 获取结构化输出。
+
+## 配置
+
+Truthmark 是 config-first。
+
+主配置文件是：
+
+```text
+.truthmark/config.yml
+```
+
+新仓库应运行：
+
+```bash
+truthmark config
+```
+
+然后先审查生成的配置，再运行：
+
+```bash
+truthmark init
+```
+
+重要配置区域包括：
+
+| 配置区域 | 用途 |
+| --- | --- |
+| `version` | 配置契约版本。 |
+| `platforms` | 应接收平台专属生成表面的代理宿主。 |
+| `docs.layout` | 当前文档布局模式。 |
+| `docs.roots` | 命名的规范文档根。 |
+| `docs.routing.root_index` | 根路由索引路径。 |
+| `docs.routing.area_files_root` | 委托子路由文件目录。 |
+| `docs.routing.default_area` | 初始脚手架子路由 basename。 |
+| `docs.routing.max_delegation_depth` | 当前最大路由委托深度。 |
+| `authority` | 用作仓库事实权威的有序规范文档和 glob。 |
+| `instruction_targets` | 接收共享受管说明块的文件，例如 `AGENTS.md`。 |
+| `frontmatter.required` | 缺失时产生错误诊断的元数据字段。 |
+| `frontmatter.recommended` | 缺失时产生审查诊断的元数据字段。 |
+| `ignore` | 从相关检查和路由逻辑中排除的 glob 模式。 |
+
+## 仓库事实路由
+
+Truthmark 将代码表面映射到事实文档。
+
+主要路由文件是：
+
+```text
+docs/truthmark/areas.md
+docs/truthmark/areas/**/*.md
+```
+
+路由告诉代理：
+
+- 哪个代码表面属于某个区域
+- 哪些事实文档拥有该区域
+- 何时应该更新事实
+- 涉及哪类事实文档
+
+默认脚手架从宽泛路由开始。现有仓库通常应该把默认路由拆成真实所有权区域。
+
+示例：
+
+```text
+/truthmark-structure 将宽泛的 repository 区域拆成 frontend、backend、billing 和 deployment
+```
+
+好的路由会给 Truth Sync 精确目标。
+
+坏的路由会让代理猜。
+
+## Truthmark 会安装什么
+
+Truthmark 安装一个紧凑、仓库原生的事实层。
+
+它分为四层安装：
+
+- 用于所有权边界的配置和路由
+- 规范 truth 文档和起始模板
+- 用于仓库级 agent 上下文的紧凑受管说明块
+- 为配置中启用的平台生成 host-native 工作流包、命令、prompts 和 verifier agents
+
+Truthmark 会保留受管说明块之外的手写内容。
+
+生成的工作流表面由 Truthmark 管理，可以通过重新运行来刷新：
+
+```bash
+truthmark init
+```
+
+## 子代理和有边界证据检查
+
+在宿主支持时，Truthmark 可以安装项目级验证代理和一个带租约的 `truth-doc-writer`。
+
+这些有助于让大型事实任务保持有边界：
+
+- route auditors 检查路由所有权
+- claim verifiers 检查文档声明是否有证据支持
+- doc reviewers 检查事实文档质量
+- leased doc writers 处理有边界的事实文档写入分片
+
+父工作流仍然负责最终解释、写入边界、diff 验证和验收。
+
+这一点很重要：子代理帮助完成有边界的证据工作。它们不替代主工作流契约。
+
+## 审查循环
+
+Truthmark 为普通 Git 审查而设计。
+
+一次好的 AI 辅助交接应该展示：
+
+```text
+代码 diff
+测试证据
+必要时的事实文档 diff
+必要时的路由变更
+代理报告
+```
+
+审查者应该能够回答：
+
+- 什么代码变了？
+- 哪些事实文档拥有这些代码？
+- 这些文档需要更新吗？
+- 如果不需要，为什么？
+- 代理是否留在工作流写入边界内？
+- 是否包含测试或验证证据？
 
-## 命令
+## 示例
 
-Truthmark V1 有意保持 CLI 很小，因为持续运行的工作流应该活在已安装的代理载体里，而不是一长串日常手动命令里。在下游仓库中，`truthmark config` 创建已提交的层级契约，`truthmark init` 根据这份已审查的配置安装和刷新工作流载体，`truthmark check` 则为人工审计、CI 或问题排查验证事实产物，而仓库情报命令会在有本地工具时生成派生审查产物。
+### 初始化仓库
 
 ```bash
+npm install -g truthmark
 truthmark config
 truthmark init
 truthmark check
-truthmark index
-truthmark impact --base main
-truthmark context --workflow truth-sync --base main
-truthmark config --json
-truthmark check --json
-truthmark index --json
-truthmark impact --base main --json
-truthmark context --workflow truth-sync --base main --json
 ```
 
-`config` 只写入 `.truthmark/config.yml`，除非使用 `--stdout`。
+### 移除未使用的代理平台
 
-`init` 需要 `.truthmark/config.yml`，然后安装或刷新本地工作流文件。
+编辑：
 
-`check` 验证配置、权限边界、路由、承载决策的文档、frontmatter、内部链接、分支范围和覆盖率诊断。
+```text
+.truthmark/config.yml
+```
 
-`index` 为当前 checkout 构建 RepoIndex 和 RouteMap JSON。
+然后重新运行：
 
-`impact --base <ref>` 会把变更文件映射到已路由的 truth docs、所属路由、附近测试和 public symbols。
+```bash
+truthmark init
+truthmark check
+```
 
-`context --workflow <workflow> [--base <ref>]` 会为 Truth Sync、Truth Document 或 Truth Realize 生成一个受限的 ContextPack。`--format markdown` 会把它渲染成可读文本。
+### 拆分宽泛路由
 
-Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 是已安装的代理工作流，不是日常使用的顶层 CLI 命令。
+```text
+/truthmark-structure 将宽泛的 repository 区域拆成 auth、billing、notifications 和 deployment
+```
 
-它们通过已配置的代理宿主表面运行，例如 Codex/Claude/Copilot 的 `/truthmark-*`、OpenCode 的 `/skill truthmark-*`，或者 Gemini 的 `/truthmark:*`。
+### 记录已实现行为
 
 ```text
-/truthmark-check 在 review 前审计路由和 truth 覆盖
+/truthmark-document 在 docs/truth/authentication 下记录已实现的密码重置流程
 ```
 
-## 它为什么存在
+### 代码变更后同步
 
-大多数 AI 编码工作流优化的是下一次回答。Truthmark 优化的是下一次交接。
-它假设严肃团队需要：
+```text
+/truthmark-sync 现在同步仓库事实，然后再交接
+```
 
-- 按分支生效的产品事实
-- 持久的架构和 API 决策
-- 文档与代码之间明确的所有权
-- 给代理设置安全的写入边界
-- 人类可以审查的普通 Git diff
-- 团队成员无需特殊工具也能检查的可读 Markdown
-- 随分支一起流转、而不是留在隐藏会话状态里的事实
-- 即使包没有全局安装也能工作的流程
+### 实现 doc-first 决策
 
-## 项目状态
+```text
+/truthmark-realize 将 docs/truth/billing/invoice-retry-policy.md 实现到代码中
+```
 
-Truthmark 不是记忆服务器，也不是 MCP 服务器。它是一套仓库实践，被打包成一个小型 CLI 安装器和代理原生的工作流载体，用来把 AI 工作流规则变成仓库基础设施。
+### 从终端审计事实健康
 
-V1 目前提供：
+```bash
+truthmark check
+```
+
+### 生成分支影响上下文
+
+```bash
+truthmark impact --base main
+```
+
+### 生成工作流上下文
+
+```bash
+truthmark context --workflow truth-sync --base main --format markdown
+```
+
+## 项目状态
+
+Truthmark V1 目前提供：
 
 - `truthmark config`
 - `truthmark init`
@@ -296,15 +644,58 @@ V1 目前提供：
 - `truthmark index`
 - `truthmark impact`
 - `truthmark context`
-- 受管的 `AGENTS.md` 工作流说明
-- 为已配置代理宿主生成的 Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 技能载体
 - 分支范围元数据
-- 配置、权限边界、路由、决策结构、frontmatter、链接和多语言覆盖率诊断
-- RepoIndex、RouteMap、ImpactSet 和 ContextPack 派生产物，可在 CLI 可用时加快本地检查
+- 受管说明块
+- 生成的 Truth Structure 工作流表面
+- 生成的 Truth Document 工作流表面
+- 生成的 Truth Sync 工作流表面
+- 生成的 Truth Preview 工作流表面
+- 生成的 Truth Realize 工作流表面
+- 生成的 Truth Check 工作流表面
+- 路由、权限边界、决策结构、frontmatter、链接、freshness、生成表面和覆盖率诊断
+- 派生的 RepoIndex、RouteMap、ImpactSet 和 ContextPack 产物
+- 面向 Codex、Claude Code、GitHub Copilot、OpenCode 和 Gemini CLI 的宿主专属表面
+
+## 开发
+
+安装依赖：
+
+```bash
+npm install
+```
+
+运行本地开发 CLI：
+
+```bash
+npm run dev -- init
+npm run dev -- check
+```
+
+运行完整项目检查：
+
+```bash
+npm run check
+```
+
+常用脚本：
+
+| 脚本 | 用途 |
+| --- | --- |
+| `npm run dev` | 用 `tsx` 运行 TypeScript CLI 入口。 |
+| `npm run build` | 构建包。 |
+| `npm run lint` | 运行 ESLint。 |
+| `npm run typecheck` | 运行 TypeScript 检查。 |
+| `npm run test` | 运行测试。 |
+| `npm run check` | 运行 lint、typecheck、测试和 build。 |
+| `npm run release:check` | 运行面向发布的验证。 |
+
+修改 Truthmark 本身时，请参阅 [CONTRIBUTORS.md](CONTRIBUTORS.md)。
 
 ## 文档
 
-根 README 面向评估和试用这个包的人。详细的功能和业务规范位于 `docs/` 下：
+README 是评估和设置的快速路径。
+
+详细的当前行为位于 `docs/` 下：
 
 - [文档索引](docs/README.md)
 - [架构概览](docs/architecture/overview.md)
@@ -314,11 +705,11 @@ V1 目前提供：
 - [已安装工作流](docs/truth/workflows/overview.md)
 - [仓库事实维护指南](docs/standards/maintaining-repository-truth.md)
 
-当前行为应放在上面的规范文档树中。
+## 设计边界
 
-## 非目标
+Truthmark 有意保持小而清晰。
 
-Truthmark V1 不是：
+它不是：
 
 - 托管服务
 - MCP 服务器
@@ -327,8 +718,49 @@ Truthmark V1 不是：
 - CI 或 PR 强制执行产品
 - 测试、代码审查或技术领导力的替代品
 - 自主代码重写引擎
+- 模型训练或微调框架
+- 隐藏记忆层
+
+这些边界是产品的一部分。
+
+Truthmark 让工作流保持本地、已提交、按分支生效并可审查。
+
+## 安全和审查纪律
+
+Truthmark 帮助仓库保持诚实。它不能证明代码正确。
+
+团队仍然应该：
+
+- 运行相关测试
+- 审查功能代码变更
+- 审查事实文档变更
+- 不把 secrets 放进文档
+- 把仓库专属说明保留在受管块之外
+- 升级后审查生成工作流表面的 diff
+- 保留人类对产品和架构决策的所有权
+
+Truthmark 让代理上下文可见。它不替代人类判断。
+
+## 路线图方向
+
+当前未来方向强调：
 
-它是一种轻量方式，让本地 AI 编码代理尊重你的团队保存在 Git 中的事实。
+- 更强的 `truthmark check` 证据报告
+- 更清晰的采用示例
+- 展示真实 Truth Sync 循环的示例仓库
+- 面向已经使用代理说明文件团队的迁移指南
+- 生成宿主表面的符合性测试
+- 感知路由的 stale truth 提示
+- 面向 doc-first 工作的有边界实现清单
+
+重心保持不变：
+
+```text
+仓库事实
+代理原生工作流
+Git 审查
+按分支生效的上下文
+```
 
 ## 许可证