diff --git a/QWEN.md b/QWEN.md
index 326bfac..5c43703 100644
--- a/QWEN.md
+++ b/QWEN.md
@@ -4,7 +4,7 @@
 
 具有以下功能：
 
-- cli: 提供一个cli工具，用于将目录内的各种ttrpg文档编译为html。
+- cli: 提供一个cli工具，用于预览和校验目录内的各种ttrpg文档。
 - markdown：解析以各种格式编写的ttrpg内容，并支持扩展的语法。
 - ttrpg组件：用于ttrpg内容的各种UI组件，且可以在markdown中通过扩展语法插入。
 
@@ -13,7 +13,8 @@
 cli使用子命令组织：
 
 - `serve`: 运行一个web服务器预览目录中的内容，并实时侦听更新。
-- `compile`: 将目录中的内容输出为带hash路由、单个html入口的web应用。
+- `check`: 静态校验目录中的 tttk 文档，输出结构化诊断（文件、行号、代码），存在错误时以退出码 1 结束。`--json` 输出机器可读结果。
+- `compile`: [未实现] 存根命令，不会产生任何输出。
 
 ## 输入文件
 
diff --git a/README.md b/README.md
index b6b3fd3..376d43c 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,15 @@
 # TTTK — Tabletop Toolkit
 
-A TTRPG content preview and compilation tool based on `solid.js` and `rsbuild`. Write markdown, preview in browser.
+A TTRPG content preview and validation tool based on `solid.js` and `rsbuild`. Write markdown, preview in browser, validate before you ship.
 
 ## 快速开始
 
 ```bash
 # 无需安装，直接使用
 npx tttk serve ./content
+
+# 校验内容（存在错误时退出码为 1）
+npx tttk check ./content
 ```
 
 ## 文档导航
@@ -22,7 +25,7 @@ npx tttk serve ./content
 
 ## 功能概览
 
-- **CLI 工具**: `tttk serve` 预览模式 和 `tttk compile` 编译模式
+- **CLI 工具**: `tttk serve` 预览模式、`tttk check` 校验模式（`tttk compile` 尚未实现）
 - **Markdown 解析**: 支持指令语法、YAML 标签、mermaid 图表
 - **TTRPG 组件**: 骰子、表格、卡牌、标记、命令追踪器等
 
@@ -30,11 +33,11 @@ npx tttk serve ./content
 
 | 组件 | 语法 | 说明 |
 |------|------|------|
-| 🎲 骰子 | `:dice[2d6+d8]` | 掷骰并记录结果 |
-| 📊 表格 | `:table[./data.csv]` | 标签页式表格 |
-| 🃏 卡牌 | `:md-deck[./cards.csv]` | 卡牌布局 |
-| 📍 标记 | `:md-pin[A]{x=40 y=40}` | 图片标记 |
-| 📋 追踪器 | `:md-commander` | 命令历史和状态追踪 |
+| 🎲 骰子 | `:md-dice[2d6+d8]` | 掷骰并记录结果 |
+| 📊 表格 | `:md-table[./data.csv]` | 标签页式表格 |
+| 🃏 卡牌 | `:md-deck[./cards.csv]` | 卡牌布局（推荐 `yaml role=tag` 写法） |
+| 📍 标记 | `:md-pins[./map.png]{pins="A:25,50"}` | 图片标记 |
+| 📋 追踪器 | `:md-commander[./commands.csv]` | 命令历史和状态追踪 |
 
 ## 技术栈
 
diff --git a/docs/cli.md b/docs/cli.md
index 59a0f70..1f5977f 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,6 +1,8 @@
 # CLI 使用说明
 
-TTTK 提供一个 CLI 工具，用于将目录内的各种 TTRPG 文档编译为 HTML。
+TTTK 提供一个 CLI 工具，用于预览和校验目录内的 TTRPG 文档。
+
+> 将内容编译为 HTML 的 `compile` 命令尚未实现（见下方说明）。
 
 ## 安装
 
@@ -59,46 +61,111 @@ tttk serve ./my-ttrpg-content
 tttk serve ./docs -p 8080
 ```
 
-### compile - 编译模式
+### check - 校验模式
 
-将目录中的内容输出为带 hash 路由、单个 HTML 入口的 Web 应用。
+静态校验目录内的 tttk 文档，输出结构化诊断（文件、行号、代码），存在错误时以退出码 `1` 结束。
 
 ```bash
-tttk compile [dir] -o ./dist/output
+tttk check [dir] --json
 ```
 
+`lint` 是 `check` 的别名。
+
 **参数：**
 
 | 参数 | 说明 | 默认值 |
 |------|------|--------|
-| `[dir]` | 要编译的目录 | `.` (当前目录) |
+| `[dir]` | 要校验的目录 | `.` (当前目录) |
 
 **选项：**
 
 | 选项 | 说明 | 默认值 |
 |------|------|--------|
-| `-o, --output <dir>` | 输出目录 | `./dist/output` |
+| `--json` | 以 JSON 输出诊断 | `false` |
+| `--strict` | 将警告视为错误 | `false` |
+| `--quiet` | 只报告错误 | `false` |
 
-**功能：**
+**退出码：**
 
-- 扫描目录下的所有 `.md` 文件
-- 解析 Markdown 并生成路由
-- 打包为带 hash 路由的单个 HTML 入口
-- 复制引用的资源文件（图片、CSV 等）
+| 代码 | 含义 |
+|------|------|
+| `0` | 无错误（`--strict` 下存在警告也会失败） |
+| `1` | 存在错误（或 `--strict` 下存在警告） |
+| `2` | 用法 / IO 错误（例如目录不存在） |
+
+**输出示例：**
+
+```
+content/adventures/hollow-mill/adventure.md
+  12:1   error   TTTK-C001  :md-table reference "./npcs.csv" does not resolve
+                           hint: expected a file relative to this document, or an inline id defined in it
+  40:8   warning TTTK-R002  spark-table first header "Name" is not a dice formula
+
+2 errors, 1 warning
+12 files checked
+```
+
+**诊断代码：**
+
+| 代码 | 级别 | 说明 |
+|------|------|------|
+| `TTTK-S001` | error | Markdown 解析失败 |
+| `TTTK-S002` | error | 容器指令 `:::` 未闭合 |
+| `TTTK-D001` | error | 未知的 `:md-*` 元素名 |
+| `TTTK-R001` | error | 未知的代码块 `role=`（块内容会被静默丢弃） |
+| `TTTK-R002` | warning | `role=spark-table` 首列表头不是骰点公式 |
+| `TTTK-R003` | error | `role=declare` 解析失败（缺少 `key`/`expr` 等） |
+| `TTTK-R005` | error | `role=tag` 的 YAML 无法解析 |
+| `TTTK-R006` | error | `role=tag` 缺少 `tag:` 或元素未知 |
+| `TTTK-C001` | error | 内容引用无法解析（文件不存在，或内联 id 未定义） |
+| `TTTK-C002` | warning | 引用解析到的文件类型不符合预期 |
+| `TTTK-C003` | info | 同一文档中重复引用同一 CSV |
+| `TTTK-C004` | error | `:md-embed` 循环引用 |
+| `TTTK-L001` | error | 链接目标文件不存在 |
+| `TTTK-L002` | warning | `#锚点` 未匹配到任何标题 |
+| `TTTK-A001` | warning | 图标在 `assets/` 中不存在 |
+| `TTTK-A002` | warning | 图片不存在 |
+
+**尚未实现的校验：** CSV 数据校验（解析错误、列数不一致、`label` 重复、`{{prop}}` 引用无效列）、畸形属性块、`role=declare` 被跳过的行。
+
+**实现说明：**
+
+- 校验复用与应用相同的 `scanDoc` 与内容注册表，因此通过校验意味着应用也能解析。
+- 定位基于**原始文件**（行号准确），围栏代码块与行内代码中的示例语句会被跳过。
+- 图标校验假设校验根目录之上不存在 `assets/` 目录。
 
 **示例：**
 
 ```bash
-# 编译当前目录
-tttk compile
+# 校验当前目录
+tttk check
 
-# 编译指定目录并输出到指定位置
-tttk compile ./content -o ./build
+# 校验指定目录并输出 JSON
+tttk check ./content --json
 
-# 编译并部署
-tttk compile ./docs -o ./public && npm run preview
+# CI：只关注错误
+npx tttk check ./content --quiet
 ```
 
+### compile - 编译模式（未实现）
+
+> **存根命令。** `compile` 目前不会产生任何输出，`--help` 中也已标明。
+> 请使用 `tttk serve` 预览内容、`tttk check` 校验内容。
+
+原计划的用法如下（仅供参考，尚未实现）：
+
+```bash
+tttk compile [dir] -o ./dist/output
+```
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `[dir]` | 要编译的目录 | `.` (当前目录) |
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-o, --output <dir>` | 输出目录 | `./dist/output` |
+
 ## 输入文件
 
 CLI 会搜索目录下的以下文件：
@@ -106,6 +173,7 @@ CLI 会搜索目录下的以下文件：
 - `.md` - Markdown 文档
 - `.csv` - 表格数据
 - `.yarn` - Yarn Spinner 叙事文件
+- `.svg` - 矢量图标
 
 ### 文件组织建议
 
@@ -126,19 +194,21 @@ my-ttrpg-content/
 
 ### 相对路径引用
 
-若 Markdown 文件通过相对路径引用了其他文件（如图片、CSV），CLI 会在打包时自动处理这些引用：
+若 Markdown 文件通过相对路径引用了其他文件（如图片、CSV），引用会相对于当前文档所在目录解析：
 
 ```markdown
 <!-- 引用同目录下的 CSV -->
-:table[./sparks.csv]
+:md-table[./sparks.csv]
 
 <!-- 引用子目录的图片 -->
 ![地图](./maps/city-map.png)
 
 <!-- 引用上级目录的文件 -->
-:deck[../data/cards.csv]
+:md-deck[../data/cards.csv]
 ```
 
+使用 `tttk check` 可以校验这些引用是否都能解析。
+
 ## 开发服务器特性
 
 ### 实时索引
@@ -165,14 +235,17 @@ my-ttrpg-content/
 tttk serve -p 8080
 ```
 
-### 编译输出为空
+### check 报告了很多警告
 
-检查输入目录是否包含 `.md` 文件：
+先用 `--quiet` 只看错误，或在 CI 中配合 `--strict`：
 
 ```bash
-# 查看目录内容
-ls -R ./content
-
-# 重新编译
-tttk compile ./content -o ./dist/output
+tttk check ./content --quiet
+tttk check ./content --json
 ```
+
+警告通常确有其事（例如锚点或图标不存在），建议逐条确认。
+
+### compile 没有输出
+
+`compile` 目前是未实现的存根命令，不会产生任何输出。请使用 `tttk serve` 预览，使用 `tttk check` 校验。
diff --git a/docs/development.md b/docs/development.md
index 68f4d0f..a857d81 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -31,7 +31,10 @@ npm test
 tttk/
 ├── src/
 │   ├── cli/                    # CLI 工具源码
-│   │   ├── commands/           # 命令实现 (serve, compile)
+│   │   ├── commands/           # 命令实现 (serve, check, compile)
+│   │   ├── validate/           # tttk check 校验器（扫描、规则、诊断）
+│   │   ├── content-registry.ts # 内容注册表（CLI / 前端共享）
+│   │   ├── content-index.ts    # 目录文件递归读取
 │   │   ├── index.ts            # CLI 入口
 │   │   └── types.ts            # 类型定义
 │   ├── components/             # TTRPG 组件