docs: reset documentation IA (readme entry pages, tutorial/troubleshooting split, AGENTS agent-only, pure command ref, maintainer guide)

Separate audiences: README as navigation entry, getting-started as canonical tutorial,
troubleshooting as failure recovery, AGENTS as agent-only operating contract,
COMMANDS as pure reference, maintainer-guide for release/versioning/architecture.

AGENTS.md

@@ -1,627 +1,90 @@
-# PaperForge - Agent Guide
+# PaperForge - Agent Operating Guide
 
-> 本文档面向 **安装完成后的新用户** 和 **AI Agent**。如果还没有安装 PaperForge，请通过 Obsidian 插件市场安装，或查看 [README.md](README.md) 中的安装说明。Docs 版本与 v1.4.18 对应。
+> 本文档面向 **AI Agent**（OpenCode / Claude Code / GPT / Cursor 等）。终端用户请阅读 [使用教程](docs/getting-started.md)。
 
 ---
 
-## 0. 安装后检查清单（第一次使用前必做）
+## 1. 核心不变式
 
-```
-[ ] Zotero 已安装 + Better BibTeX 插件已启用
-[ ] Obsidian 已打开当前 Vault
-[ ] PaperForge 已安装 (pip install paperforge)
-[ ] PaddleOCR API Key 已配置（在 .env 中）
-[ ] 目录结构已创建（安装向导会自动完成）
-[ ] Zotero 数据目录已链接到 <system_dir>/Zotero
-[ ] Better BibTeX 已按下方步骤导出 JSON 到 <system_dir>/PaperForge/exports/
-```
-
-> 安装向导是增量式的：如果你选择的 Vault 或目录里已经有文件，PaperForge 只会补充缺失的目录和文件，不会删除已有内容。
-
-### Better BibTeX 自动导出配置
-
-这一步应在安装向导完成之后再做，因为 `exports/` 目录需要先由安装流程创建。
-
-1. 打开 Zotero
-2. 对你要同步的文献库或分类右键 → `导出...`
-3. 选择格式：**Better BibTeX JSON**
-4. 勾选 **"Keep updated"**（自动导出）
-5. 保存到：`{你的Vault路径}/<system_dir>/PaperForge/exports/`
-6. JSON 文件名会作为 Base 名称，例如 `library.json`、`骨科.json`
+1. **CLI 是命令真相源。** 所有 skill、workflow、文档命令引用必须对齐 `paperforge/cli.py`。
+2. **Python 是运行时真相源。** Plugin 只读 canonical 快照，不做业务推断。
+3. **`paperforge.json` 是路径真相源。** Plugin 和 Python 共享同源路径解析，不硬编码目录名。
+4. **Agent 机械命令和思考工作流分层。** `/pf-sync` `/pf-ocr` `/pf-status` 是机械执行，`/pf-deep` `/pf-paper` 是思考工作流。
 
 ---
 
-## 1. 核心架构（v2.1 契约驱动）
+## 2. 架构边界
 
-PaperForge 在 v2.1（1.4.17rc4）重构为 **契约驱动架构**，分 5 层：
+| 层 | 做什么 | 不做什么 |
+|----|--------|---------|
+| Plugin JS | 读快照、render UI、`execFile` 调 Python | 不读 SQLite、不推断 runtime 状态 |
+| Python CLI | 写快照、sync/ocr/repair/embed/memory | 不被 JS 轮询驱动 |
+| Memory DB | SQLite + FTS5，由 Python 全权重建 | JS 不读 memory DB |
+| Vector DB | ChromaDB，由 `embed build` 管理 | 不与 memory DB 合并语义 |
+| Skill/workflow | 路由 → 执行 CLI → 解释结果 | 不绕过 CLI 直操作文件 |
+
+**运行时快照契约：**
 
 ```
-CLI/Plugin 调用
-    ↓ PFResult 契约 {ok, command, version, data, error}
-┌─────────────────────────────────────────────┐
-│  commands/    CLI 分发层                      │
-├─────────────────────────────────────────────┤
-│  adapter/bbt, zotero_paths, frontmatter    │  ← 独立可测
-│  services/sync_service       ← 编排适配器   │
-├─────────────────────────────────────────────┤
-│  core/result, errors, state   ← 共享数据契约 │
-├─────────────────────────────────────────────┤
-│  worker/sync, ocr, status     ← 机械劳动     │
-│  setup/6个类                  ← 安装流程     │
-├─────────────────────────────────────────────┤
-│  schema/field_registry.yaml   ← 字段注册表   │
-│  doctor/field_validator.py    ← 字段校验     │
-└─────────────────────────────────────────────┘
-```
+Python 写（每次相关 CLI 命令结束时）:
+  runtime-health --json     → runtime-health.json
+  memory status --json      → memory-runtime-state.json
+  embed status --json       → vector-runtime-state.json
+  embed build               → vector-build-state.json
 
-| 层级 | 组件 | 触发方式 | 作用 |
-|------|------|----------|------|
-| **契约层** | `core/`（PFResult, ErrorCode, 状态机） | 被所有模块引用 | 定义 CLI/Plugin/Worker 之间的数据交换格式 |
-| **适配器层** | `adapters/`（bbt, zotero_paths, frontmatter） | 被服务层调用 | 封装外部数据格式与 I/O 操作 |
-| **服务层** | `services/sync_service` | 被 worker 调度 | 编排适配器，实现业务逻辑 |
-| **Worker 层** | `worker/`（sync, ocr, status, repair 等） | Python CLI | 后台自动化（机械劳动） |
-| **Agent 层** | `/pf-deep`, `/pf-paper` | 用户手动触发 | 交互式精读（深度思考） |
-
-**操作速查**：
-| 你要做什么 | 在终端输入 | 在 OpenCode 输入 |
-|-----------|-----------|-----------------|
-| 同步 Zotero 并生成笔记 | `paperforge sync` | `/pf-sync` |
-| 运行 OCR | `paperforge ocr` | `/pf-ocr` |
-| 查看精读队列 | `paperforge deep-reading` | `/pf-deep`（精读具体文献） |
-| 查看系统状态 | `paperforge status` | `/pf-status` |
-| 修复状态分歧 | `paperforge repair` | （终端操作） |
-| 验证安装配置 | `paperforge doctor` | （终端操作） |
-| 查看帮助 | `paperforge --help` | （终端操作） |
-
----
-
-## 2. 完整数据流
-
-```
-Zotero 添加文献
-    ↓ Better BibTeX 自动导出 JSON
-<system_dir>/PaperForge/exports/library.json
-    ↓ 运行 sync
-<resources_dir>/<literature_dir>/<domain>/<key> - <Title>.md（正式笔记，含 frontmatter）
-    ↓ 用户在正式笔记 frontmatter 中设置 do_ocr: true
-运行 ocr → <system_dir>/PaperForge/ocr/<key>/
-    ↓ 用户在正式笔记 frontmatter 中设置 analyze: true
-运行 deep-reading（查看队列，确认就绪）
-    ↓ 用户执行 Agent 命令
-/pf-deep <zotero_key>
-    ↓ Agent 生成
-正式笔记中新增 ## 🔍 精读 区域
+JS 读（同步，不推断）:
+  memoryState.getMemoryRuntime()
+  memoryState.getVectorRuntime()
+  memoryState.getRuntimeHealth()
 ```
 
 ---
 
-## 3. 目录结构（Lite 版，5 个核心目录）
+## 3. 安全命令惯例
 
-```
-{你的Vault根目录}/
-├── <resources_dir>/
-│   ├── <literature_dir>/                    ← 正式文献笔记（sync 生成，含 frontmatter 状态跟踪）
-│   │   ├── 骨科/
-│   │   ├── 运动医学/
-│   │   └── ...（你的分类）
-│
-├── <system_dir>/
-│   ├── PaperForge/
-│   │       ├── exports/                   ← Better BibTeX 自动导出的 JSON
-│   │       │   └── library.json
-│   │       ├── ocr/                       ← OCR 结果（每个文献一个子目录）
-│   │       │   └── ABCDEFG/               ← Zotero key 作为目录名
-│   │       │       ├── fulltext.md        ← OCR 提取的全文
-│   │       │       ├── images/            ← 图表切割图片
-│   │       │       ├── meta.json          ← OCR 元数据（含 ocr_status）
-│   │       │       └── figure-map.json    ← 图表索引（自动创建）
-│   │       ├── indexes/                   ← 索引缓存（formal-library.json 等）
-│   │       └── config/                    ← 领域-收藏夹映射等配置
-│   └── Zotero/                        ← Junction/Symlink 到 Zotero 数据目录
-│
-├── <agent_config_dir>/                         ← OpenCode Agent 配置（自动创建）
-│   └── skills/
-│       └── literature-qa/             ← 深度阅读 Skill
-│           ├── scripts/
-│           │   └── ld_deep.py         ← /pf-deep 核心脚本
-│           ├── prompt_deep_subagent.md ← Agent 精读提示词
-│           └── chart-reading/         ← 14 种图表阅读指南
-│
-├── .env                               ← API Key 等敏感配置
-└── AGENTS.md                          ← 本文件
-```
-
-### 各目录作用速查
-
-| 目录 | 内容 | 谁生成/修改 |
-|------|------|------------|
-| `<resources_dir>/<literature_dir>/` | 正式文献笔记（含 frontmatter + 精读内容） | sync 生成，Agent 写入精读 |
-| `<system_dir>/PaperForge/exports/` | Better BibTeX JSON 导出 | Zotero 自动导出 |
-| `<system_dir>/PaperForge/ocr/` | OCR 全文 + 图表切割 | ocr worker 生成 |
-| `<system_dir>/PaperForge/indexes/` | 索引缓存（formal-library.json） | sync 生成 |
-| `<system_dir>/PaperForge/config/` | 领域-收藏夹映射等 | 用户/安装向导配置 |
-| `<system_dir>/Zotero/` | Zotero 数据目录的链接 | 安装时手动创建 junction |
+- 搜索用 `$PYTHON -m paperforge search`，不用 `grep`/`glob` 扫库。
+- 路径从 bootstrap 或 paper-context 获取，禁止自行拼接。
+- 未完成 paper-context 检查前不读原文（deep-reading、paper-qa）。
+- Reading-log 不是事实源，只能用做复查定位。
+- 未知或拼错的 `/pf-*` 必须提示用户，禁止静默掉进 `project-engineering`。
 
 ---
 
-## 4. 核心 Workers（Lite 版，4 个）
+## 4. 机械 vs 思考路由
 
-### sync
-- **作用**：检测 Zotero 中的新条目并生成正式文献笔记
-- **运行时机**：添加新文献到 Zotero 后，或需要更新笔记格式时
-- **输出**：
-  - `<resources_dir>/<literature_dir>/<domain>/<key> - <Title>.md`
-- **示例**：
-  ```bash
-  paperforge sync
-  # Legacy (备用):
-  # python -m paperforge sync --vault "{vault路径}"
-  ```
-
-### ocr
-- **作用**：将 PDF 上传到 PaddleOCR API，提取全文文本和图表
-- **触发条件**：正式笔记 frontmatter 中 `do_ocr: true`
-- **输出**：`<system_dir>/PaperForge/ocr/<key>/` 目录
-  - `fulltext.md`：提取的全文（含 `<!-- page N -->` 分页标记）
-  - `images/`：自动切割的图表图片
-  - `meta.json`：OCR 状态（`ocr_status: done/pending/processing/failed`）
-  - `figure-map.json`：图表索引（后续自动生成）
-- **注意**：OCR 是异步的，大文件可能需要几分钟
-- **示例**：
-  ```bash
-  paperforge ocr
-  # 诊断模式（不运行，仅检查状态）
-  paperforge ocr --diagnose
-  # Legacy (备用):
-  # python -m paperforge ocr --vault "{vault路径}"
-  ```
-
-### deep-reading
-- **作用**：扫描所有正式笔记，列出 `analyze=true` 且 OCR 完成的文献
-- **运行时机**：用户想看看哪些文献可以开始精读了
-- **输出**：控制台表格，显示队列状态
-- **重要**：这只是**查看队列**，不会自动触发 Agent 精读
-- **示例**：
-  ```bash
-  paperforge deep-reading
-  paperforge deep-reading --verbose  # 显示阻塞条目的修复指令
-  # Legacy (备用):
-  # python -m paperforge deep-reading --vault "{vault路径}"
-  ```
+| Route | 类型 | 动作 |
+|-------|------|------|
+| `/pf-sync` | 机械 | 执行 `paperforge sync`，解释结果 |
+| `/pf-ocr` | 机械 | 执行 `paperforge ocr`，解释结果 |
+| `/pf-status` | 机械 | 执行 `paperforge status --json` 或 `paperforge runtime-health --json`，解读状态 |
+| `/pf-deep` | 思考 | 打开 `workflows/deep-reading.md` 执行完整流程 |
+| `/pf-paper` | 思考 | 打开 `workflows/paper-qa.md` 执行完整流程 |
 
 ---
 
-## 5. Agent 命令（用户手动触发）
-
-PaperForge 的命令分为两类：
-
-| 类型 | 命令 | 用途 | 说明 |
-|------|------|------|------|
-| **深度思考** | `/pf-deep <key>` | 完整 Keshav 三阶段精读 | **必须 Agent 执行** — 需要理解论文、分析图表、生成 callout |
-| **深度思考** | `/pf-paper <key>` | 文献问答 | **必须 Agent 执行** — 需要理解内容并写作 |
-| **机械操作** | `/pf-sync` | 同步 Zotero 并生成笔记 | Agent 可帮你检查状态并执行 |
-| **机械操作** | `/pf-ocr` | 运行 PDF OCR | Agent 可帮你检查队列并执行 |
-| **机械操作** | `/pf-status` | 查看系统状态 | Agent 可帮你解读诊断结果 |
-
-> **双模式调用**：`/pf-sync`、`/pf-ocr`、`/pf-status` 本质上是 CLI 命令的 Agent 包装。你可以在终端直接运行 `paperforge sync/ocr/status`，也可以在 OpenCode 中使用 `/pf-*` 让 Agent 帮你检查前置条件、执行命令、解读输出。
-
-> **v1.4 新增**：所有命令支持全局 `--verbose` / `-v` 参数（如 `paperforge sync --verbose`），输出 DEBUG 级别的诊断信息到 stderr，不影响 stdout 的正常输出。
-
-> **v1.4 新增 — auto_analyze_after_ocr**：如果开启了 `paperforge.json` 中的 `auto_analyze_after_ocr`，OCR 完成后 `analyze` 会自动设为 `true`，无需手动修改 formal note frontmatter。
-
-### 必须 Agent 执行的命令
-
-#### `/pf-deep <zotero_key>` — 完整精读
-
-**用途**：完整 Keshav 三阶段精读
-**前置条件**：OCR 完成 (`ocr_status: done`)
-
-执行流程：
-1. **prepare 阶段**（自动）：查找正式笔记、检查 OCR、生成 figure-map
-2. **精读阶段**（Agent 执行）：Pass 1 概览 → Pass 2 精读还原 → Pass 3 深度理解
-3. **验证阶段**（自动）：检查 callout 间距、section 完整性
-
-#### `/pf-paper <zotero_key>` — 文献问答
-
-**用途**：文献问答（无 OCR 要求）
-**前置条件**：有正式笔记即可
-
----
-
-## 6. Path Resolution（路径解析）
-
-PaperForge 支持三种 Better BibTeX 导出路径格式，并统一转换为 Obsidian wikilink：
-
-### 支持的 BBT 路径格式
-
-| 格式 | 示例 | 处理方式 |
-|------|------|----------|
-| **Absolute Windows** | `D:\Zotero\storage\KEY\file.pdf` | 提取 8 位 KEY，转换为 `storage:KEY/file.pdf` |
-| **storage: prefix** | `storage:KEY/file.pdf` | 直接透传，仅规范化斜杠 |
-| **Bare relative** | `KEY/file.pdf` | 自动添加 `storage:` 前缀 |
-
-### Wikilink 生成规则
-
-- 所有 PDF 路径在正式笔记中存储为 **Obsidian wikilink** 格式：`[[relative/path/to/file.pdf]]`
-- 使用正斜杠 `/`（即使 Windows 系统）
-- 支持中文文件名，无需转义
-- 示例：`[[99_System/Zotero/storage/KEY/中文论文.pdf]]`
-
-### Junction / Symlink 设置
-
-如果 Zotero 数据目录在 Vault 外部，需创建 junction：
-
-```powershell
-# 以管理员身份运行 PowerShell
-New-Item -ItemType Junction -Path "C:\你的Vault\99_System\Zotero" -Target "C:\Users\用户名\Zotero"
-```
-
-或 CMD：
-
-```cmd
-mklink /J "C:\你的Vault\99_System\Zotero" "C:\Users\用户名\Zotero"
-```
-
-运行 `paperforge doctor` 会自动检测 Zotero 位置并推荐正确的 junction 命令。
-
-### 多附件处理
-
-当一篇文献有多个 PDF 附件时：
-- **Main PDF**：title="PDF" 的附件，或最大文件，或第一个 PDF
-- **Supplementary**：其他 PDF 附件列表，以 wikilink 数组形式存储
-
----
-
-## 7. Frontmatter 字段参考
-
-### Formal Note（`Literature/<domain>/<key> - <Title>.md`）
-
-这是**用户控制工作流的核心**。每个文献对应一个 formal note 文件，frontmatter 包含元数据 + 工作流控制字段：
-
-```yaml
----
-zotero_key: "ABCDEFG"           # Zotero citation key（自动生成）
-domain: "骨科"                   # 分类领域（对应 Zotero 收藏夹）
-title: "论文标题"
-year: 2024
-doi: "10.xxxx/xxxxx"
-collection_path: "子分类"        # Zotero 子收藏夹路径
-has_pdf: true                    # 是否有 PDF 附件（自动生成）
-pdf_path: "[[99_System/Zotero/storage/KEY/文件名.pdf]]"  # Wikilink 格式
-bbt_path_raw: "D:\\Zotero\\storage\\KEY\\文件名.pdf"     # 原始 BBT 路径（调试用）
-zotero_storage_key: "KEY"        # 8 位 Zotero storage key
-attachment_count: 2              # 附件总数
-supplementary:                   # 其他 PDF 附件（wikilink 列表）
-  - "[[99_System/Zotero/storage/KEY/supp1.pdf]]"
-  - "[[99_System/Zotero/storage/KEY/supp2.pdf]]"
-fulltext_md_path: "[[99_System/PaperForge/ocr/KEY/fulltext.md]]"
-recommend_analyze: true          # 系统推荐精读（有 PDF 时自动设为 true）
-analyze: false                   # 【用户控制】是否生成精读？设为 true 触发
-do_ocr: true                     # 【用户控制】是否运行 OCR？设为 true 触发
-ocr_status: "done"               # OCR 状态（pending/processing/done/failed）
-deep_reading_status: "pending"   # 精读状态（pending/done）
-path_error: ""                   # 路径错误（not_found/invalid/permission_denied）
-analysis_note: ""                # 预留字段
----
-```
-
-**用户操作方式**：
-- 在 Obsidian 中打开 formal note 文件
-- 修改 `analyze: false` → `analyze: true` 标记要精读的文献
-- 修改 `do_ocr: false` → `do_ocr: true` 触发 OCR
-- 或使用 Obsidian Base 视图批量操作
-
----
-
-## 8. 第一次使用指南（手把手）
-
-### Step 1: 完成 Better BibTeX 自动导出
-
-先按上面的步骤把 JSON 导出到 `<system_dir>/PaperForge/exports/`。这一步没完成前，`sync` 不会读到文献。
-
-### Step 2: 确认 Zotero 有文献
-
-确保 Zotero 中已有至少一篇带 PDF 的文献，且 Better BibTeX 已导出 JSON。
-
-### Step 3: 运行 sync
+## 5. 测试
 
 ```bash
-# 在 Vault 根目录执行
-paperforge sync
-```
+# Python
+python -m pytest tests/unit/ tests/cli/ -v --tb=short
 
-预期输出：
-```
-[INFO] Found 5 new items
-[INFO] Created 骨科/XXXXXXX.md
-[INFO] Generated 5 formal notes
-[INFO] Output: <resources_dir>/<literature_dir>/骨科/XXXXXXX - Title.md
-...
-```
+# JS
+cd paperforge/plugin && npx vitest run
 
-### Step 4: 在 Base 视图中标记 OCR
-
-打开 Obsidian Base 视图，找到该文献，将 `do_ocr` 设为 `true`。
-
-### Step 5: 运行 OCR
-
-```bash
-paperforge ocr
-```
-
-等待完成（可能需要几分钟）。
-
-### Step 6: 在 Base 视图中标记精读
-
-OCR 完成后，在 Base 视图中找到该文献，将 `analyze` 设为 `true`。
-
-### Step 7: 执行精读
-
-先确认队列就绪：
-```bash
-paperforge deep-reading
-```
-
-然后在 OpenCode Agent 中输入：
-```
-/pf-deep XXXXXXX
-```
-
-Agent 会自动：
-1. 准备精读骨架（prepare）
-2. 逐阶段填写精读内容
-3. 验证结构完整性
-
-### Step 8: 查看结果
-
-在 Obsidian 中打开正式笔记，找到 `## 🔍 精读` 区域，精读已完成。
-
----
-
-## 9. 常用命令速查
-
-```bash
-# 检测 Zotero 新条目并生成正式笔记
-paperforge sync
-paperforge sync --verbose      # 显示详细诊断信息
-
-
-
-# 运行 OCR（处理 do_ocr=true 的文献）
-paperforge ocr
-paperforge ocr --verbose       # 显示 OCR 详细日志
-paperforge ocr --diagnose      # 诊断模式，不实际运行
-paperforge ocr --no-progress   # 静默模式，不显示进度条
-
-# 查看精读队列
-paperforge deep-reading
-paperforge deep-reading --verbose  # 显示阻塞条目修复指令
-
-# 修复状态分歧（默认 dry-run）
-paperforge repair --verbose        # 查看三向状态分歧详情
-paperforge repair --fix           # 实际修复（慎用）
-
-# 查看整体状态
-paperforge status
-
-# 验证安装配置
-paperforge doctor
-```
-
-> 如果 `paperforge` 命令未注册，可使用 fallback：
-> ```bash
-> python -m paperforge <command>
-> ```
-> 例如：`python -m paperforge status`
-
-### Agent 命令
-```
-/pf-deep <zotero_key>    # 完整三阶段精读（必须 Agent 执行）
-/pf-paper <zotero_key>   # 文献问答（必须 Agent 执行）
-/pf-sync                 # 同步 Zotero（Agent 包装 CLI）
-/pf-ocr                  # 运行 OCR（Agent 包装 CLI）
-/pf-status               # 查看状态（Agent 包装 CLI）
-```
-
-> 注：`/pf-sync`、`/pf-ocr`、`/pf-status` 与 `paperforge sync/ocr/status` 是同一命令的两种调用方式。在终端直接运行 CLI 即可；在 OpenCode 中使用 `/pf-*` 可以让 Agent 帮你检查前置条件并解读输出。
-
-### Chart-Reading 指南索引
-
-`/pf-deep` 精读时会参考 19 种图表类型的阅读指南，按生物医学文献常见度排序。完整索引参见 `chart-reading/INDEX.md`。
-
----
-
-## 10. 常见问题
-
-### Q: 运行 sync 后没有生成正式笔记？
-- 检查 Better BibTeX JSON 导出路径是否正确
-- 检查 JSON 文件是否包含文献数据
-- 确认 Zotero 中该文献有 citation key
-
-### Q: OCR 一直显示 pending？
-- 检查 PaddleOCR API Key 是否配置正确（`.env` 文件）
-- 检查网络连接
-- 查看 `<system_dir>/PaperForge/ocr/<key>/meta.json` 中的错误信息
-
-### Q: /pf-deep 提示 OCR 未完成？
-- 确认正式笔记 frontmatter 中 `ocr_status: done`
-- 如 OCR 失败，可重新设置 `do_ocr: true` 再运行 ocr worker
-
-### Q: Base 视图中 pdf_path 显示为绝对路径？
-- 这是 Obsidian 渲染问题，数据本身是相对路径
-- 不影响功能，可忽略
-
-### Q: 可以批量操作吗？
-- 可以。使用 Obsidian Base 视图批量修改 `do_ocr` 和 `analyze` 字段
-- 或使用脚本批量修改 formal note frontmatter
-
----
-
-## 11. 升级与维护
-
-### 更新 PaperForge 代码
-
-#### 方式 1：自动更新（推荐）
-
-```bash
-# 自动检测安装方式并更新
-paperforge update
-```
-
-系统会自动检测你是通过 pip、git 还是手动安装，并执行对应的更新方式。
-
-#### 方式 2：Windows 一键脚本
-
-双击运行 Vault 根目录下的 `scripts/update-paperforge.ps1`：
-- 自动检测安装方式
-- 自动执行更新
-- 无需手动输入命令
-
-```powershell
-# 或在 PowerShell 中执行
-.\scripts\update-paperforge.ps1
-
-# 强制更新（跳过确认）
-.\scripts\update-paperforge.ps1 -Force
-
-# 只检测不更新
-.\scripts\update-paperforge.ps1 -DryRun
-```
-
-#### 方式 3：手动更新
-
-**推荐：自动更新**
-```bash
-paperforge update
-```
-系统会自动检测安装方式并执行对应的更新命令。
-
-**pip 安装用户：**
-```bash
-pip install --upgrade paperforge
-```
-
-**pip editable / git clone 用户：**
-```bash
-cd 你的仓库目录
-git pull origin master
-pip install -e .
-```
-
-#### 方式 4：手动复制（最后手段）
-
-```bash
-cp -r 新下载的代码/* <vault_path>/
-```
-
-> [!WARNING] 手动复制容易遗漏文件，建议优先使用自动更新。
-
-### 备份注意事项
-- `<resources_dir>/` 和 `<system_dir>/PaperForge/ocr/` 包含你的数据，需备份
-- `.env` 包含 API Key，不要提交到 git
-- `<system_dir>/PaperForge/exports/` 可重新生成（由 Zotero 自动导出）
-
----
-
-## 12. 命令迁移说明（v1.1 → v1.2）
-
-从 v1.2 开始，PaperForge 采用统一的命令接口：
-
-- **CLI 统一入口**：`paperforge sync`（替代 `selection-sync` + `index-refresh`）、`paperforge ocr`（替代 `ocr run`）
-- **Agent 统一前缀**：`/pf-deep`、`/pf-paper`、`/pf-ocr`、`/pf-sync`、`/pf-status`（替代 `/LD-*` 和 `/lp-*`）
-- **Python 包重命名**：`paperforge`（替代 `paperforge_lite`）
-
-**旧命令仍兼容**：v1.2 继续支持旧命令名（`selection-sync`、`index-refresh`、`ocr run`），但文档已统一使用新命令。
-
-> **v1.4 新增**：结构化日志（`--verbose`）、自动重试、进度条、代码自动化检查。详细迁移步骤和回滚说明参见 [docs/MIGRATION-v1.2.md](docs/MIGRATION-v1.2.md)（v1.1→v1.2）和 [docs/MIGRATION-v1.4.md](docs/MIGRATION-v1.4.md)（v1.3→v1.4）。
-
----
-
-## 13. 开发者指南（AI Agent 必读）
-
-### v2.1 新增模块
-
-v2.1（1.4.17rc4）引入了以下新增模块，开发时请注意：
-
-| 路径 | 内容 | 注意事项 |
-|------|------|---------|
-| `paperforge/core/` | 契约层 — PFResult, ErrorCode, 状态机 | 所有模块都可引用，不循环依赖 |
-| `paperforge/adapters/` | 适配器 — bbt, zotero_paths, frontmatter | 独立可测，从 `sync.py` 提取 |
-| `paperforge/services/` | 服务层 — SyncService | 编排适配器，`sync.py` 变调度壳 |
-| `paperforge/setup/` | 安装层 — 6 个类 | 从 `setup_wizard.py` 拆出 |
-| `paperforge/schema/` | 字段注册表 — `field_registry.yaml` | 44 字段定义 |
-| `paperforge/doctor/` | 校验 — `field_validator.py` | `doctor` 命令使用 |
-
-所有 `--json` 输出统一为 PFResult 格式 `{ok, command, version, data, error}`。修改输出结构时需同时更新 `core/result.py` 和下游 consumer（plugin）。
-
-### 版本号管理
-
-PaperForge 版本只在 `paperforge/__init__.py` 一处定义。升版本时不要手动改多个文件，使用自动化脚本：
-
-```bash
-# 升 patch 版本（1.4.11 → 1.4.12），自动 git commit + tag
-python scripts/bump.py patch
-
-# 升 minor 版本（1.4.11 → 1.5.0）
-python scripts/bump.py minor
-
-# 指定版本号
-python scripts/bump.py 2.0.0
-
-# 预览（不实际修改）
-python scripts/bump.py patch --dry-run
-
-# 只改文件不 commit
-python scripts/bump.py patch --no-git
-```
-
- 脚本会自动更新：
-| 文件 | 字段 |
-|------|------|
-| `paperforge/__init__.py` | `__version__` |
-| `paperforge/plugin/manifest.json` | `version` |
-| `manifest.json` | `version` |
-| `paperforge/plugin/versions.json` | 追加 `"version": "minAppVersion"` |
-
-### 发布 Release 流程
-
-```bash
-# 1. 升版本（自动 commit + tag）
-python scripts/bump.py patch
-
-# 2. 推送代码和 tag
-git push && git push --tags
-
-# 3. 创建 GitHub Release 并上传插件文件
-gh release create v1.4.12 \
-    --title "v1.4.12" \
-    --notes "简短说明" \
-    paperforge/plugin/main.js \
-    paperforge/plugin/styles.css \
-    paperforge/plugin/manifest.json \
-    paperforge/plugin/versions.json
-```
-
-> Obsidian 社区插件要求 Release 附带 `main.js`、`manifest.json`、`styles.css`、`versions.json` 四个单独文件（非 zip）。
-
-### 插件 i18n
-
-插件界面通过 `paperforge/plugin/i18n.js` 做中英文适配：
-- 语言自动检测：读取 Obsidian 语言设置，`zh*` 用中文，其他用英文
-- 新增文本时，需同时在 `i18n.js` 的 `zh` 和 `en` 两块加 key
-- 代码中使用 `t('key_name')` 读取翻译
-- Dashboard 的 `ACTIONS` 标题保持英文（Obsidian 命令面板统一使用英文 ID）
-
-### pre-commit 检查
-
-```bash
-# 提交前运行 ruff lint + format + 一致性审计
+# Lint
 ruff check --fix paperforge/ && ruff format paperforge/
-
-# 运行测试（173 tests）
-python -m pytest tests/unit/ -q --tb=short
 ```
 
 ---
 
-*PaperForge | 快速开始指南 | 安装后阅读*
+## 文档地图
+
+| 受众 | 文件 |
+|------|------|
+| 终端用户教程 | [docs/getting-started.md](docs/getting-started.md) |
+| 故障排除 | [docs/troubleshooting.md](docs/troubleshooting.md) |
+| 命令参考 | [docs/COMMANDS.md](docs/COMMANDS.md) |
+| 更新升级 | [docs/update-upgrade.md](docs/update-upgrade.md) |
+| 架构 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
+| 维护者 | [docs/maintainer-guide.md](docs/maintainer-guide.md) |
+| 迁移历史 | [docs/MIGRATION-v1.2.md](docs/MIGRATION-v1.2.md) |

README.en.md

@@ -68,220 +68,34 @@ Plugin v1.5.0 → Python Package v1.5.0 ✓ Matched
 
 ---
 
-## 3. How Python Interpreter Resolution Works
-
-PaperForge needs to find a working Python on your system. It searches in this order:
-
-| Priority | Source | Description |
-|----------|--------|-------------|
-| 1 | **Manual override** | Settings → `Custom Python Path`, enter the full path (e.g., `C:\Users\you\...\python.exe`). **This is the most reliable method.** |
-| 2 | **venv auto-detect** | Scans `.paperforge-test-venv`, `.venv`, `venv` under your vault root |
-| 3 | **System auto-detect** | Tries `py -3`, `python`, `python3` in order, verifies with `--version` |
-| 4 | **Fallback** | Defaults to `python` if nothing else works |
-
-> If you have multiple Python installations (e.g., system 3.9 + self-installed 3.11), **strongly recommend setting a manual path** in settings to avoid hitting the wrong one.
->
-> The **Validate** button in settings immediately tests the resolved interpreter and shows its version.
-
----
-
-## 4. Setup Wizard — What Each Step Means
-
-Open the plugin settings panel (`Settings` → `Community plugins` → `PaperForge`) and click the **Open Wizard** button. The wizard walks you through configuration. Here's what every step does.
-
-### 4.1 Vault Path
-
-Your Obsidian vault root. Auto-detected, usually no need to change.
-
-### 4.2 AI Agent Platform
-
-PaperForge's deep reading features run through an AI Agent. The core mechanism is **trigger phrases**, not registered plugins: you type `/pf-deep <key>` directly into the Agent chat, and the Agent recognizes the trigger and loads the `literature-qa` Skill automatically.
-
-The setup wizard deploys Skill files to the correct location:
-
-| Agent | Skill location | Trigger example |
-|-------|---------------|-----------------|
-| **OpenCode** | `.opencode/skills/` + `.opencode/command/` | `/pf-deep <key>` |
-| **Claude Code** | `.claude/skills/` | `/pf-deep <key>` |
-| **Cursor** | `.cursor/skills/` | `/pf-deep <key>` |
-| **GitHub Copilot** | `.github/skills/` | `/pf-deep <key>` |
-| **Windsurf** | `.windsurf/skills/` | `/pf-deep <key>` |
-| **Codex** | `.codex/skills/` | `$pf-deep <key>` |
-| **Cline** | `.clinerules/` | `/pf-deep <key>` |
-
-> **Key concept**: `/pf-deep` is NOT a plugin you install on the Agent platform — it's a Skill file deployed inside your Vault. Once the setup wizard copies the files into place, the Agent auto-discovers the triggers on startup. You type the trigger phrase just like any other chat input.
-
-### 4.3 Directory Names
-
-The wizard asks what to name several directories. These are for organizing files inside your vault. **Defaults work for most users.**
-
-| Parameter | Default | Purpose |
-|-----------|---------|---------|
-| `system_dir` | `System` | Root for PaperForge internal data. Contains `exports/` (Zotero JSON exports), `ocr/` (OCR results), `config/`. You rarely need to open this manually. |
-| `resources_dir` | `Resources` | Resources root. Your formal literature notes live under this directory, inside `literature_dir`. |
-| `literature_dir` | `Literature` | Formal literature notes directory. `paperforge sync` generates frontmatter `.md` notes here. |
-| `base_dir` | `Bases` | Obsidian Base view definitions. Dashboard filters ("Pending OCR", "Ready to Read", etc.) are stored here. |
-
-### 4.4 PaddleOCR API Token
-
-OCR requires a PaddleOCR API key. Configured in `.env`:
-
-```
-PADDLEOCR_API_TOKEN=your-api-key
-```
-
-The wizard guides you through setting this. You can also edit `.env` later. The OCR URL usually stays at the default.
-
-### 4.5 Zotero Data Directory
-
-PaperForge creates a junction (Windows) or symlink (macOS/Linux) linking your Zotero data directory into the vault. This is how Obsidian wikilinks resolve to PDF files.
-
-The wizard auto-detects your Zotero installation. If detection fails, manually enter the path to your Zotero data directory — the folder that contains the `storage/` subdirectory (not the Zotero executable).
-
-### 4.6 What Happens During Setup
-
-After confirming your choices, the wizard automatically:
-- Creates all needed directory structures
-- Deploys Agent command files to the correct locations
-- Installs Obsidian plugin files
-- Creates the Zotero junction/symlink
-- Writes `paperforge.json` and `.env`
-
-The process is **incremental** — if files already exist in the chosen directories, the wizard only adds what's missing and never deletes existing content.
-
----
-
-## 5. First-Time Setup Checklist
-
-1. **Version match**: Settings → Runtime Status → confirm plugin and Python package match
-2. **Python path**: Settings → Validate button → confirm it's the Python you want
-3. **Setup wizard**: Settings → PaperForge → Open Wizard
-4. **PaddleOCR key**: Enter your API token in `.env` (wizard guides this)
-5. **Export from Zotero**: Right-click your library → `Export...` → format `Better BibTeX JSON` → check `Keep updated` → save to `<system_dir>/PaperForge/exports/`
-6. **Run Doctor**: Dashboard → `Run Doctor` → all checks should pass
-
----
-
-## 6. Daily Use
-
-### Dashboard (Three-Mode Views)
-
-`Ctrl+P` → `PaperForge: Open Dashboard` opens the control panel with three views:
-
-| View | Purpose |
-|------|---------|
-| **Global** | System homepage: run Sync, OCR, Doctor, and other mechanical operations |
-| **Collection** | Batch workspace: browse paper queues by domain, batch tagging |
-| **Per-paper** | Reading companion: `do_ocr` / `analyze` toggle checkboxes, discussion record cards |
-
-> PDF files in the Dashboard automatically switch to Per-paper mode — no manual switching needed.
-
-### AI Deep Reading & Q&A (Requires Agent)
-
-Launch your Agent app and type commands into its chat input. **The more specific you are about the paper (Zotero Key, title, DOI), the faster the Agent locates it.**
-
-| Route | Command | Does | Trigger examples | Prerequisites |
-|-------|---------|------|-----------------|--------------|
-| Deep Read | `/pf-deep <key>` | Keshav three-pass deep reading, writes to formal note | `deep read XX`, `walk me through`, `journal club` | OCR done, analyze: true |
-| Q&A | `/pf-paper <key>` | Interactive paper Q&A, OCR not required | `take a look at XX`, `what does this paper say` | Formal note exists |
-| Archive | `/pf-end` | Save current `/pf-paper` Q&A session | `save`, `end discussion` | During `/pf-paper` session |
-
-### `/pf-end` Details
-
-- `/pf-end` only applies to `/pf-paper` Q&A sessions. Deep reading (`/pf-deep`) writes directly to the formal note and does not need `/pf-end`.
-- When executed, two files are created in the paper's workspace:
-  - `discussion.md` — human-readable Q&A discussion record
-  - `discussion.json` — structured Q&A data (with timestamps, source tags)
-- Dashboard **Per-paper** view automatically displays these as discussion record cards
-
-> Command prefixes vary by platform (mostly `/`, Codex uses `$`).
-
----
-
-## 7. Full Workflow
-
-```
-Add paper to Zotero
-  ↓ Better BibTeX auto-exports JSON to exports/
-Dashboard → Sync Library
-  ↓ Generates formal note (in Literature/, with frontmatter metadata)
-Set do_ocr: true in the note's frontmatter
-  ↓
-Dashboard → Run OCR
-  ↓ PaddleOCR extracts full text + figures → ocr/ directory
-Set analyze: true in the note's frontmatter
-  ↓
-Open Agent → type /pf-deep <zotero_key>
-  ↓ Agent performs three-pass deep reading
-## 🔍 Deep Reading section appears in the note
-  ↓ (for additional Q&A)
-Open Agent → type /pf-paper <zotero_key>
-  ↓ Interactive Q&A
-Type /pf-end to save the discussion record
-  ↓
-Dashboard Per-paper view shows discussion cards
-```
-
----
-
-## 8. Troubleshooting
-
-### Plugin fails to load
-
-- Confirm `.obsidian/plugins/paperforge/` has `main.js`, `manifest.json`, `styles.css`
-- If upgrading via BRAT from an old version: delete the entire `paperforge` plugin folder and let BRAT re-download
-- Open Developer Console (`Ctrl+Shift+I`) and check the red errors
-
-### "Sync Runtime" doesn't update the version
-
-- The plugin may be calling a different Python than your terminal. Check Settings → Python path
-- Try with `--no-cache-dir` to bypass pip cache
-- Confirm `https://github.com/LLLin000/PaperForge` is reachable
-
-### OCR stays pending
-
-- Confirm `.env` has `PADDLEOCR_API_TOKEN`
-- Run `paperforge ocr --diagnose` to check API connectivity
-- PDF paths may be broken: run `paperforge repair --fix-paths`
-
-### No notes generated after sync
-
-- Is Better BibTeX auto-export configured in Zotero? Are JSON files in `exports/`?
-- Run `paperforge doctor` to find which step failed
-
-### /pf-deep command does nothing
-
-- Make sure you're running it in your Agent app, not a terminal
-- Confirm OCR is done (`ocr_status: done`)
-- Confirm `analyze` is set to `true`
-
----
-
-## 9. Updating
-
-BRAT auto-detects plugin updates. For the Python package:
+## 3. Quickstart
 
 ```bash
-paperforge update
-# or
-pip install --upgrade paperforge
+# 1. Export from Zotero (Better BibTeX JSON, Keep updated) to exports/
+# 2. Sync
+paperforge sync
+
+# 3. Mark a paper for OCR in its frontmatter: do_ocr: true
+# 4. Run OCR
+paperforge ocr
+
+# 5. Mark for deep reading: analyze: true
+# 6. In your Agent chat:
+/pf-deep <zotero_key>
 ```
 
 ---
 
-## 10. Architecture
+## Documentation
 
-```
-paperforge/
-├── core/          Contract layer — PFResult/ErrorCode/state machine
-├── adapters/      Adapter layer — BBT parsing, paths, frontmatter I/O
-├── services/      Service layer — SyncService orchestration
-├── worker/        Worker layer — OCR, status, repair
-├── commands/      CLI dispatch
-├── setup/         Setup wizard (directories, agent deployment, Zotero linking)
-├── plugin/        Obsidian plugin (Dashboard, settings panel)
-└── schema/        Field registry
-```
+| If you want to                          | Read                                      |
+| --------------------------------------- | ----------------------------------------- |
+| Full tutorial, from install to deep read | [Getting Started](docs/getting-started.md) |
+| Troubleshooting                         | [Troubleshooting](docs/troubleshooting.md) |
+| Command reference                       | [Commands](docs/COMMANDS.md)              |
+| How to update                           | [Update Guide](docs/update-upgrade.md)    |
+| Architecture / Maintenance / Release    | [Architecture](docs/ARCHITECTURE.md)      |
+| AI Agent collaboration                  | [AGENTS.md](AGENTS.md)                    |
 
 ---
 

README.md

@@ -75,222 +75,34 @@ Plugin v1.5.0 → Python Package v1.5.0 ✓ Matched
 
 ---
 
-## 3. How Python Interpreter Resolution Works
-
-PaperForge needs to find a working Python on your system. It searches in this order:
-
-| Priority | Source | Description |
-|----------|--------|-------------|
-| 1 | **Manual override** | Settings → `Custom Python Path`, enter the full path (e.g., `C:\Users\you\...\python.exe`). **This is the most reliable method.** |
-| 2 | **venv auto-detect** | Scans `.paperforge-test-venv`, `.venv`, `venv` under your vault root |
-| 3 | **System auto-detect** | Tries `py -3`, `python`, `python3` in order, verifies with `--version` |
-| 4 | **Fallback** | Defaults to `python` if nothing else works |
-
-> If you have multiple Python installations (e.g., system 3.9 + self-installed 3.11), **strongly recommend setting a manual path** in settings to avoid hitting the wrong one.
->
-> The **Validate** button in settings immediately tests the resolved interpreter and shows its version.
-
----
-
-## 4. Setup Wizard — What Each Step Means
-
-Open the plugin settings panel (`Settings` → `Community plugins` → `PaperForge`) and click the **Open Wizard** button. The wizard walks you through configuration. Here's what every step does.
-
-### 4.1 Vault Path
-
-Your Obsidian vault root. Auto-detected, usually no need to change.
-
-### 4.2 AI Agent Platform
-
-PaperForge's deep reading features run through an AI Agent. The core mechanism is **trigger phrases**, not registered plugins: you type `/pf-deep <key>` directly into the Agent chat, and the Agent recognizes the trigger and loads the `literature-qa` Skill automatically.
-
-The setup wizard deploys Skill files to the correct location:
-
-| Agent | Skill location | Trigger example |
-|-------|---------------|-----------------|
-| **OpenCode** | `.opencode/skills/` + `.opencode/command/` | `/pf-deep <key>` |
-| **Claude Code** | `.claude/skills/` | `/pf-deep <key>` |
-| **Cursor** | `.cursor/skills/` | `/pf-deep <key>` |
-| **GitHub Copilot** | `.github/skills/` | `/pf-deep <key>` |
-| **Windsurf** | `.windsurf/skills/` | `/pf-deep <key>` |
-| **Codex** | `.codex/skills/` | `$pf-deep <key>` |
-| **Cline** | `.clinerules/` | `/pf-deep <key>` |
-
-> **Key concept**: `/pf-deep` is NOT a plugin you install on the Agent platform — it's a Skill file deployed inside your Vault. Once the setup wizard copies the files into place, the Agent auto-discovers the triggers on startup. You type the trigger phrase just like any other chat input.
-
-### 4.3 Directory Names
-
-The wizard asks what to name several directories. These are for organizing files inside your vault. **Defaults work for most users.**
-
-| Parameter | Default | Purpose |
-|-----------|---------|---------|
-| `system_dir` | `System` | Root for PaperForge internal data. Contains `exports/` (Zotero JSON exports), `ocr/` (OCR results), `config/`. You rarely need to open this manually. |
-| `resources_dir` | `Resources` | Resources root. Your formal literature notes live under this directory, inside `literature_dir`. |
-| `literature_dir` | `Literature` | Formal literature notes directory. `paperforge sync` generates frontmatter `.md` notes here. |
-| `base_dir` | `Bases` | Obsidian Base view definitions. Dashboard filters ("Pending OCR", "Ready to Read", etc.) are stored here. |
-
-### 4.4 PaddleOCR API Token
-
-OCR requires a PaddleOCR API key. Configured in `.env`:
-
-```
-PADDLEOCR_API_TOKEN=your-api-key
-```
-
-The wizard guides you through setting this. You can also edit `.env` later. The OCR URL usually stays at the default.
-
-### 4.5 Zotero Data Directory
-
-PaperForge creates a junction (Windows) or symlink (macOS/Linux) linking your Zotero data directory into the vault. This is how Obsidian wikilinks resolve to PDF files.
-
-The wizard auto-detects your Zotero installation. If detection fails, manually enter the path to your Zotero data directory — the folder that contains the `storage/` subdirectory (not the Zotero executable).
-
-### 4.6 What Happens During Setup
-
-After confirming your choices, the wizard automatically:
-- Creates all needed directory structures
-- Deploys Agent command files to the correct locations
-- Installs Obsidian plugin files
-- Creates the Zotero junction/symlink
-- Writes `paperforge.json` and `.env`
-
-The process is **incremental** — if files already exist in the chosen directories, the wizard only adds what's missing and never deletes existing content.
-
----
-
-## 5. First-Time Setup Checklist
-
-1. **Version match**: Settings → Runtime Status → confirm plugin and Python package match
-2. **Python path**: Settings → Validate button → confirm it's the Python you want
-3. **Setup wizard**: Settings → PaperForge → Open Wizard
-4. **PaddleOCR key**: Enter your API token in `.env` (wizard guides this)
-5. **Export from Zotero**: Right-click your library → `Export...` → format `Better BibTeX JSON` → check `Keep updated` → save to `<system_dir>/PaperForge/exports/`
-6. **Run Doctor**: Dashboard → `Run Doctor` → all checks should pass
-
----
-
-## 6. Daily Use
-
-### Dashboard (Three-Mode Views)
-
-`Ctrl+P` → `PaperForge: Open Dashboard` opens the control panel with three views:
-
-| View | Purpose |
-|------|---------|
-| **Global** | System homepage: run Sync, OCR, Doctor, and other mechanical operations |
-| **Collection** | Batch workspace: browse paper queues by domain, batch tagging |
-| **Per-paper** | Reading companion: `do_ocr` / `analyze` toggle checkboxes, discussion record cards |
-
-> PDF files in the Dashboard automatically switch to Per-paper mode — no manual switching needed.
-
-### AI Deep Reading & Q&A (Requires Agent)
-
-Launch your Agent app and type commands into its chat input. **The more specific you are about the paper (Zotero Key, title, DOI), the faster the Agent locates it.**
-
-| Route | Command | Does | Trigger examples | Prerequisites |
-|-------|---------|------|-----------------|--------------|
-| Deep Read | `/pf-deep <key>` | Keshav three-pass deep reading, writes to formal note | `deep read XX`, `walk me through`, `journal club` | OCR done, analyze: true |
-| Q&A | `/pf-paper <key>` | Interactive paper Q&A, OCR not required | `take a look at XX`, `what does this paper say` | Formal note exists |
-| Archive | `/pf-end` | Save current `/pf-paper` Q&A session | `save`, `end discussion` | During `/pf-paper` session |
-
-### `/pf-end` Details
-
-- `/pf-end` only applies to `/pf-paper` Q&A sessions. Deep reading (`/pf-deep`) writes directly to the formal note and does not need `/pf-end`.
-- When executed, two files are created in the paper's workspace:
-  - `discussion.md` — human-readable Q&A discussion record
-  - `discussion.json` — structured Q&A data (with timestamps, source tags)
-- Dashboard **Per-paper** view automatically displays these as discussion record cards
-
-> Command prefixes vary by platform (mostly `/`, Codex uses `$`).
-
----
-
-## 7. Full Workflow
-
-```
-Add paper to Zotero
-  ↓ Better BibTeX auto-exports JSON to exports/
-Dashboard → Sync Library
-  ↓ Generates formal note (in Literature/, with frontmatter metadata)
-Set do_ocr: true in the note's frontmatter
-  ↓
-Dashboard → Run OCR
-  ↓ PaddleOCR extracts full text + figures → ocr/ directory
-Set analyze: true in the note's frontmatter
-  ↓
-Open Agent → type /pf-deep <zotero_key>
-  ↓ Agent performs three-pass deep reading
-## 🔍 Deep Reading section appears in the note
-  ↓ (for additional Q&A)
-Open Agent → type /pf-paper <zotero_key>
-  ↓ Interactive Q&A
-Type /pf-end to save the discussion record
-  ↓
-Dashboard Per-paper view shows discussion cards
-```
-
----
-
-## 8. Troubleshooting
-
-### Plugin fails to load
-
-- Confirm `.obsidian/plugins/paperforge/` has `main.js`, `manifest.json`, `styles.css`
-- If upgrading from an old version: delete the entire `paperforge` plugin folder and reinstall via the community plugin browser
-- Open Developer Console (`Ctrl+Shift+I`) and check the red errors
-
-### "Sync Runtime" doesn't update the version
-
-- The plugin may be calling a different Python than your terminal. Check Settings → Python path
-- Try with `--no-cache-dir` to bypass pip cache
-- Confirm `https://github.com/LLLin000/PaperForge` is reachable
-
-### OCR stays pending
-
-- Confirm `.env` has `PADDLEOCR_API_TOKEN`
-- Run `paperforge ocr --diagnose` to check API connectivity
-- PDF paths may be broken: run `paperforge repair --fix-paths`
-
-### No notes generated after sync
-
-- Is Better BibTeX auto-export configured in Zotero? Are JSON files in `exports/`?
-- Run `paperforge doctor` to find which step failed
-
-### /pf-deep command does nothing
-
-- Make sure you're running it in your Agent app, not a terminal
-- Confirm OCR is done (`ocr_status: done`)
-- Confirm `analyze` is set to `true`
-
----
-
-## 9. Updating
-
-The Obsidian plugin auto-updates through the community plugin browser. For the Python package:
+## 3. Quickstart
 
 ```bash
-paperforge update
-# or
-pip install --upgrade paperforge
-```
+# 1. Export from Zotero (Better BibTeX JSON, Keep updated) to exports/
+# 2. Sync
+paperforge sync
 
-If you installed via BRAT, it also auto-detects GitHub Release updates.
+# 3. Mark a paper for OCR in its frontmatter: do_ocr: true
+# 4. Run OCR
+paperforge ocr
+
+# 5. Mark for deep reading: analyze: true
+# 6. In your Agent chat:
+/pf-deep <zotero_key>
+```
 
 ---
 
-## 10. Architecture
+## 文档导航
 
-```
-paperforge/
-├── core/          Contract layer — PFResult/ErrorCode/state machine
-├── adapters/      Adapter layer — BBT parsing, paths, frontmatter I/O
-├── services/      Service layer — SyncService orchestration
-├── worker/        Worker layer — OCR, status, repair
-├── commands/      CLI dispatch
-├── setup/         Setup wizard (directories, agent deployment, Zotero linking)
-├── plugin/        Obsidian plugin (Dashboard, settings panel)
-└── schema/        Field registry
-```
+| 你想做什么                                 | 去看                           |
+| ------------------------------------------ | ------------------------------ |
+| 完整教程，从安装到精读                     | [使用教程](docs/getting-started.md)    |
+| 遇到问题了                                 | [故障排除](docs/troubleshooting.md)    |
+| 查某个命令                                 | [命令参考](docs/COMMANDS.md)           |
+| 如何升级                                   | [更新指南](docs/update-upgrade.md)     |
+| 架构 / 维护 / 发布                         | [架构文档](docs/ARCHITECTURE.md)       |
+| AI Agent 协作                               | [AGENTS.md](AGENTS.md)                |
 
 ---
 

docs/COMMANDS.md

@@ -1,119 +1,104 @@
-# PaperForge 命令总览
+# PaperForge 命令参考
 
-> PaperForge 完整命令参考。Agent 命令与 CLI 命令对照表。
->
-> 另见：[AGENTS.md](../AGENTS.md) — 完整使用指南与架构说明
+> 所有 CLI 命令和 Agent 命令速查。
 
 ---
 
 ## 命令矩阵
 
-| Agent 命令 | CLI 命令 | 说明 | 前置条件 | 示例 |
-|-----------|---------|------|---------|------|
-| `/pf-deep` | `paperforge sync` + `paperforge ocr` | 完整三阶段精读（Keshav 法） | OCR 完成 (`ocr_status: done`) | `/pf-deep ABCDEFG` |
-| `/pf-paper` | `paperforge sync` | 快速摘要与问答工作台 | 正式笔记已生成 | `/pf-paper ABCDEFG` |
-| `/pf-ocr` | `paperforge ocr` | PDF OCR 文本与图表提取 | PDF 存在 + `do_ocr: true` | `paperforge ocr` |
-| `/pf-sync` | `paperforge sync` | 同步 Zotero 到文献库 | Better BibTeX JSON 导出 | `paperforge sync --domain 骨科` |
-| `/pf-status` | `paperforge status` | 查看系统安装与运行状态 | 配置完成 | `paperforge status` |
-
-> **说明**：Agent 命令（`/pf-*`）在对话窗口中输入，由 AI Agent 执行。CLI 命令在终端中输入，由 Python worker 执行。
+| Agent 命令 | CLI 命令 | 用途 | 前置条件 |
+|-----------|---------|------|---------|
+| `/pf-sync` | `paperforge sync` | 同步 Zotero，生成正式笔记 | BBT JSON 导出 |
+| `/pf-ocr` | `paperforge ocr` | PDF OCR 文本与图表提取 | `do_ocr: true` |
+| `/pf-status` | `paperforge status` | 查看系统状态 | 配置完成 |
+| `/pf-deep <key>` | `paperforge deep-reading` | 三阶段精读 | OCR done + `analyze: true` |
+| `/pf-paper <key>` | — | 文献问答 | 正式笔记存在 |
 
 ---
 
-## 快速参考
+## CLI 命令
 
-| 命令 | 一句话说明 |
-|------|-----------|
-| `/pf-deep <key>` | 对单篇论文进行 figure-by-figure 深度精读 |
-| `/pf-paper <key>` | 加载论文 OCR 文本，进入问答模式 |
-| `paperforge ocr` | 处理所有标记 `do_ocr: true` 的文献 |
-| `paperforge sync` | 检测 Zotero 新条目，直接生成正式笔记 |
-| `paperforge status` | 检查安装状态、配置、路径连通性 |
+### `paperforge sync`
 
----
-
-## 工作流参考
-
-典型使用顺序（首次安装后）：
-
-### 第一步：同步文献
 ```bash
-paperforge sync
+paperforge sync                 # 完整同步
+paperforge sync --dry-run       # 预览
+paperforge sync --rebuild-index # 强制重建索引
+paperforge sync --json          # JSON 输出
 ```
-- 检测 Zotero JSON 中的新条目
-- 生成正式笔记 `<resources_dir>/<literature_dir>/<domain>/<key> - Title.md`
 
-### 第二步：标记 OCR
-在 Obsidian 中打开 formal note 文件，将 `do_ocr: false` 改为 `do_ocr: true`。
+### `paperforge ocr`
 
-或使用命令行批量修改（高级用户）：
 ```bash
-# 示例：批量标记某领域的所有文献
-grep -l "do_ocr: false" <resources_dir>/<literature_dir>/骨科/*.md | xargs sed -i 's/do_ocr: false/do_ocr: true/'
+paperforge ocr                  # 处理队列
+paperforge ocr --key ABCDEFG    # 处理指定文献
+paperforge ocr --diagnose       # 诊断模式
+paperforge ocr --json           # JSON 输出
 ```
 
-### 第三步：运行 OCR
+### `paperforge status`
+
 ```bash
-paperforge ocr
+paperforge status               # 完整状态
+paperforge status --json        # JSON 输出
 ```
-- 上传 PDF 到 PaddleOCR API
-- 提取全文文本和图表
-- 输出到 `<system_dir>/PaperForge/ocr/<key>/`
 
-### 第四步：标记精读
-在 formal note 中将 `analyze: false` 改为 `analyze: true`。
+### `paperforge doctor`
 
-### 第五步：执行精读
-在 Agent 对话中输入：
+```bash
+paperforge doctor               # 验证安装配置
+paperforge doctor --json        # JSON 输出
 ```
-/pf-deep ABCDEFG
+
+### `paperforge repair`
+
+```bash
+paperforge repair               # 扫描分歧（dry-run）
+paperforge repair --fix          # 修复
+paperforge repair --fix-paths    # 修复 PDF 路径
+paperforge repair --json         # JSON 输出
 ```
-Agent 自动：
-1. 检查 OCR 状态和 formal note
-2. 生成 `## 精读` 骨架
-3. 逐阶段填写精读内容（Pass 1/2/3）
-4. 验证结构完整性
 
----
+### `paperforge deep-reading`
 
-## 命令详情
+```bash
+paperforge deep-reading          # 查看精读队列
+paperforge deep-reading --verbose # 含修复指令
+```
 
-各命令的详细文档见对应文件：
+### `paperforge embed`
 
-- [`command/pf-deep.md`](../command/pf-deep.md) — 深度精读
-- [`command/pf-paper.md`](../command/pf-paper.md) — 快速摘要
-- [`command/pf-ocr.md`](../command/pf-ocr.md) — OCR 提取
-- [`command/pf-sync.md`](../command/pf-sync.md) — 文献同步
-- [`command/pf-status.md`](../command/pf-status.md) — 状态检查
+```bash
+paperforge embed build           # 构建向量索引
+paperforge embed build --resume  # 续建
+paperforge embed status          # 查看状态
+paperforge embed stop            # 停止构建
+```
 
----
+### `paperforge memory`
 
-## 平台说明
+```bash
+paperforge memory build          # 构建 memory DB
+paperforge memory status         # 查看状态
+```
 
-### OpenCode
+### `paperforge search`
 
-- Agent 命令以 `/pf-` 前缀输入，支持文件附件
-- `/pf-deep` 和 `/pf-paper` 需要 OCR 完成的 PDF 作为上下文
-- Agent 使用 `paperforge paths --json` 获取 Vault 路径配置
-- 多篇文章并行精读时使用 `Task` tool 启动 subagent
+```bash
+paperforge search "<query>" --json
+paperforge search "PEMF" --domain 骨科 --ocr done --year-from 2020
+```
 
-### Codex
+### `paperforge runtime-health`
 
-> **Future**：Codex 平台支持计划开发中。预计采用类似的 `/pf-*` 命令前缀，通过 API 调用 PaperForge CLI。
-
-### Claude Code
-
-> **Future**：Claude Code 平台支持计划开发中。预计通过 `@paperforge` 提及或专用工具调用实现集成。
+```bash
+paperforge runtime-health --json
+```
 
 ---
 
 ## 相关文档
 
-- [AGENTS.md](../AGENTS.md) — 完整使用指南、架构说明、常见问题
-- [docs/INSTALLATION.md](INSTALLATION.md) — 安装步骤
-- [docs/MIGRATION-v1.2.md](MIGRATION-v1.2.md) — v1.1 → v1.2 迁移指南
-- [docs/ARCHITECTURE.md](ARCHITECTURE.md) — 系统架构与设计决策
-
----
-
-*PaperForge Lite v1.2 | 命令参考文档*
+- [使用教程](getting-started.md)
+- [故障排除](troubleshooting.md)
+- [更新指南](update-upgrade.md)

docs/getting-started.md

@@ -0,0 +1,90 @@
+# PaperForge 使用教程
+
+> 面向终端用户。如果你刚安装完 PaperForge，从这里开始。
+
+---
+
+## 1. 安装后检查
+
+1. Obsidian 已打开当前 Vault
+2. PaperForge 插件已在设置中启用
+3. Python 运行时已确认（设置面板 --> 验证）
+
+---
+
+## 2. 配置 Better BibTeX 自动导出
+
+1. 打开 Zotero
+2. 对你要同步的文献库或分类右键 -> `导出...`
+3. 格式选：**Better BibTeX JSON**
+4. 勾选 **"Keep updated"**
+5. 保存到：`{你的Vault路径}/<system_dir>/PaperForge/exports/`
+
+> system_dir 默认是 `System`，例如保存到 `MyVault/System/PaperForge/exports/library.json`
+
+---
+
+## 3. 第一次同步
+
+打开 Dashboard（`Ctrl+P` -> `PaperForge: Open Main Panel`），点击 **Sync Library**。
+
+或者终端执行：
+```bash
+paperforge sync
+```
+
+完成后，正式文献笔记出现在 `Resources/Literature/<领域>/` 下。
+
+---
+
+## 4. 触发 OCR
+
+在正式笔记的 frontmatter 里把 `do_ocr` 改为 `true`，然后运行：
+
+```bash
+paperforge ocr
+```
+
+OCR 结果保存在 `System/PaperForge/ocr/<key>/` 下，包括全文文本和图表。
+
+---
+
+## 5. 深度精读
+
+OCR 完成后，把 formal note 的 `analyze` 改为 `true`。
+
+确认就绪：
+```bash
+paperforge deep-reading
+```
+
+在 Agent 中输入 `/pf-deep <zotero_key>`，Agent 会执行 Keshav 三阶段精读，结果直接写入 formal note 的 `## 精读` 区域。
+
+---
+
+## 6. 文献问答
+
+不强制 OCR。直接输入 `/pf-paper <zotero_key>` 进入交互式问答。
+
+---
+
+## 7. 日常路径
+
+```
+添加文献到 Zotero
+  -> BBT 自动导出到 exports/
+  -> 点 Sync
+  -> 标记 do_ocr: true
+  -> 运行 OCR
+  -> 标记 analyze: true
+  -> /pf-deep <key>
+  -> /pf-paper <key>
+```
+
+---
+
+## 8. 相关文档
+
+- [命令参考](COMMANDS.md) — 所有 CLI 和 Agent 命令速查
+- [故障排除](troubleshooting.md) — 常见问题
+- [更新指南](update-upgrade.md) — 如何升级 PaperForge

docs/maintainer-guide.md

@@ -0,0 +1,74 @@
+# PaperForge 维护者指南
+
+> 面向贡献者和维护者。
+
+---
+
+## 项目结构
+
+```
+paperforge/
+├── core/           PFResult 契约层
+├── adapters/       BBT 解析、frontmatter、路径
+├── services/       SyncService 编排
+├── worker/         OCR、sync、status、repair
+├── memory/         SQLite、ChromaDB、快照
+├── commands/       CLI 分发
+├── setup/          安装向导
+├── schema/         field_registry.yaml
+├── doctor/         字段校验
+├── plugin/         Obsidian 插件
+│   ├── main.js     UI + 快照读取
+│   └── src/testable.js  提取的纯函数
+└── skills/paperforge/  Agent skill 文件
+```
+
+## 架构原则
+
+1. Python 写 canonical 快照，JS 只读
+2. CLI 是所有命令的真相源
+3. `paperforge.json` 是路径真相源
+4. `formal-library.json` 是文献索引真相源
+
+## 版本号
+
+版本只在 `paperforge/__init__.py` 定义。升版本：
+
+```bash
+python scripts/bump.py patch
+python scripts/bump.py minor
+```
+
+自动更新：`__init__.py`、`manifest.json`、`versions.json`、git tag。
+
+## 发布
+
+```bash
+python scripts/bump.py patch
+git push && git push --tags
+gh release create vX.Y.Z \
+    --title "vX.Y.Z" \
+    --notes "说明" \
+    paperforge/plugin/main.js \
+    paperforge/plugin/styles.css \
+    paperforge/plugin/manifest.json \
+    paperforge/plugin/versions.json
+```
+
+## 测试
+
+```bash
+ruff check --fix paperforge/ && ruff format paperforge/
+python -m pytest tests/unit/ tests/cli/ -v --tb=short
+cd paperforge/plugin && npx vitest run
+```
+
+## i18n
+
+插件文案在 `paperforge/plugin/main.js` 的 `LANG` 对象中。中文 keys 在 `LANG.zh`，英文在 `LANG.en`。代码用 `t('key')` 读取。
+
+## 相关文档
+
+- [架构](ARCHITECTURE.md)
+- [命令参考](COMMANDS.md)
+- [AGENTS.md](../AGENTS.md)

docs/troubleshooting.md

@@ -0,0 +1,67 @@
+# PaperForge 故障排除
+
+---
+
+## 插件无法加载
+
+确认 `.obsidian/plugins/paperforge/` 下有 `main.js`、`manifest.json`、`styles.css`。
+
+如果从旧版本升级：删除整个 `paperforge` 插件文件夹，通过社区插件浏览器重新安装。
+
+打开开发者控制台（`Ctrl+Shift+I`）查看红色错误信息。
+
+---
+
+## "Sync Runtime" 不更新版本
+
+插件可能调用了和终端不同的 Python。检查设置面板中的 Python Path。
+
+如果仍不行，使用 `--no-cache-dir` 避开 pip 缓存。
+
+确认 `https://github.com/LLLin000/PaperForge` 可访问。
+
+---
+
+## OCR 一直 pending
+
+1. 确认 `.env` 中有 `PADDLEOCR_API_TOKEN`
+2. 运行 `paperforge ocr --diagnose` 检查接口连通性
+3. 如果 PDF 路径有问题，运行 `paperforge repair --fix-paths`
+
+---
+
+## 同步后没有生成笔记
+
+1. Zotero 的 Better BibTeX 自动导出配好了吗？JSON 文件在 `exports/` 下？
+2. 运行 `paperforge doctor` 定位失败步骤
+
+---
+
+## /pf-deep 无反应
+
+前置条件：`ocr_status: done` 且 `analyze: true`。
+
+确认队列就绪：
+```bash
+paperforge deep-reading --verbose
+```
+
+Agent 必须能访问 vault，确认 Agent 配置路径正确。
+
+---
+
+## Base 视图中 pdf_path 显示绝对路径
+
+Obsidian 渲染问题，数据实际是相对路径。不影响功能。
+
+---
+
+## 命令参考
+
+```bash
+paperforge status          # 查看系统状态
+paperforge doctor          # 验证安装配置
+paperforge repair --fix    # 修复状态分歧
+```
+
+更多见 [命令参考](COMMANDS.md)。

docs/update-upgrade.md

@@ -0,0 +1,32 @@
+# 更新与升级
+
+---
+
+## 插件更新
+
+Obsidian 社区插件浏览器自动更新。BRAT 安装用户同样自动检测更新。
+
+## Python 包更新
+
+```bash
+paperforge update
+# 或
+pip install --upgrade paperforge
+```
+
+## 备份
+
+更新前建议备份：
+- `.env`（API key）
+- `Resources/` 目录（文献笔记）
+- `System/PaperForge/ocr/`（OCR 结果）
+
+## 迁移指南
+
+大版本升级详见：
+- [MIGRATION-v1.2.md](MIGRATION-v1.2.md) — v1.1 -> v1.2
+- [MIGRATION-v1.4.md](MIGRATION-v1.4.md) — v1.3 -> v1.4
+
+---
+
+相关问题见 [故障排除](troubleshooting.md)。

tests/test_command_docs.py

@@ -188,8 +188,8 @@ class TestPaperforgeCommandExamplesInUserDocs:
     @pytest.mark.parametrize(
         "doc_key,pattern",
         [
-            ("README", r"paperforge (status|paths)"),
-            ("AGENTS", r"paperforge (status|paths)"),
+        ("README", r"paperforge (sync|ocr|status)"),
+        ("AGENTS", r"paperforge (search|status|sync)"),
         ],
     )
     def test_user_doc_contains_paperforge_stable_example(