@tanlinfeng/project-docs-workflow 2.2.0 → 3.0.0

package/NOTICE

@@ -8,22 +8,20 @@ Licensed under the MIT License (see LICENSE).
 Third-party attribution
 -----------------------
 
-Portions of the bundled skills in this package are trimmed / adapted from:
+Portions of the internal fallback references in this package are trimmed / adapted from:
 
   https://github.com/mattpocock/skills
   MIT License
   Copyright (c) 2026 Matt Pocock
 
-The following bundled skills contain material derived from the project above:
+This package does not bundle standalone dependency skills. The following internal fallback
+references (used when the standalone skill is absent) contain material derived from the
+project above:
 
-  - skills/grilling
-  - skills/grill-me
-  - skills/grill-with-docs
-  - skills/domain-modeling
-  - skills/tdd
-  - skills/deepwork
-  - skills/retro
-  - skills/improve-codebase-architecture
+  - skills/project-docs-workflow/references/deps/grilling.md
+  - skills/project-docs-workflow/references/deps/domain-modeling.md
+  - skills/project-docs-workflow/references/deps/tdd.md
+  - skills/project-docs-workflow/references/deps/boundaries.md
 
 The MIT permission notice for the upstream material is reproduced below.
 

package/README.md

@@ -1,198 +1,152 @@
 # @tanlinfeng/project-docs-workflow
 
-> 项目文档工作流 skill 包：提供 issue tracker、ADR、PDR、术语表与协作工作流约定，自带轻量依赖 skill 与 ref 兜底，可独立分发。
+面向 AI agent 的项目文档工作流 skill：帮助项目建立并维护 issue tracker、ADR、PDR、领域术语和开发工作流。主 skill 自带依赖兜底材料，可独立使用。
 
-## 这是什么
+## 快速开始
 
-`project-docs-workflow` 是一套面向 AI agent 的「项目文档工作流」skill。它把项目中的几类关键文档沉淀为可复用的模板与约定：
+**前置条件：** Node.js >= 18，并可使用 `npx`。安装器默认将 skill 安装到 `~/.agents/skills`。
 
-- **issue tracker**：任务 / 缺陷的登记与追踪约定
-- **ADR**（Architecture Decision Record）：架构决策记录
-- **PDR**（Product/Project Design Record）：设计与需求记录
-- **terminology**：领域术语表，统一团队与 agent 的词汇
-- **workflow**：上述文档之间的协作与更新流程
+```bash
+# 默认动作即安装；@latest 是 dist-tag，不保证等于最高版本
+npx @tanlinfeng/project-docs-workflow@latest install
 
-skill 本身是自包含的：主 skill 内部带 `references/deps/*.md` 兜底材料，因此即使没有安装任何依赖 skill，也能独立工作。包内同时附带了若干**轻量依赖 skill**（来自 `mattpocock/skills` 的精简版本）以及一个**附赠的 `doc-opt` skill**。
+# 也可指定一个实际已发布的确切版本（示例）
+npx @tanlinfeng/project-docs-workflow@2.2.0 install
+```
 
-## 安装
+不带版本时，`npx` 可能**优先使用当前项目已安装的版本**；要选择安装器版本，请显式写 `@latest` 或 `@<版本>`（缓存 / 网络策略另计）。安装器自身**不获取版本**，而是从所选源包同步内容。
 
-通过 npx 直接安装到默认的 skills 根目录（`~/.agents/skills`）：
+**兼容性限定：** `npx <pkg>@<版本> install` 运行的是**该版本自带的安装器代码**。本页描述的自动同步 / `--force` 等语义**仅适用于包含本安装策略的包版本**；更早的已发布版本保留其当时的行为（例如 `--force` 可能只覆盖主 skill）。因此「指定较旧版本」只在这类兼容版本内才是等价回滚。示例中的 `@2.2.0` 仅用于说明 npm 语法（须为实际已发布的版本），不表示该版本具备上述新语义。
 
-```bash
-npx @tanlinfeng/project-docs-workflow
-```
+这一步只安装 skill，**不会初始化任何项目文档**。安装完成后，进入要设置文档的**目标项目根目录**，使用当前 agent 自己的 skill 调用方式手动运行 `project-docs-workflow`。例如可以这样请求：
 
-常用选项：
+> 请使用 project-docs-workflow skill，为当前项目初始化项目文档工作流。
 
-| 命令 | 说明 |
-| --- | --- |
-| `npx @tanlinfeng/project-docs-workflow` | 默认动作 `install`：安装主 skill 及所有依赖 skill |
-| `npx @tanlinfeng/project-docs-workflow --dir <path>` | 指定 skills 根目录（默认 `~/.agents/skills`） |
-| `npx @tanlinfeng/project-docs-workflow --force` | 覆盖已存在的 `project-docs-workflow`（**仅主 skill**；依赖 skill 仍不覆盖） |
-| `npx @tanlinfeng/project-docs-workflow --dry-run` | 只打印将执行的操作，不写入任何文件 |
-| `npx @tanlinfeng/project-docs-workflow --with-matt-skills` | 可选：依赖 skill 改从上游 `mattpocock/skills` 安装**完整版**（需 Node >= 22.20） |
-| `npx @tanlinfeng/project-docs-workflow --matt-agent <name>` | 上游安装使用的 agent（默认 `codex`，落盘到其全局目录 `~/.agents/skills`） |
-| `npx @tanlinfeng/project-docs-workflow check` | 检查依赖 skill 的解析状态，全部可解析时退出码为 0，否则为 1 |
-| `npx @tanlinfeng/project-docs-workflow uninstall` | 依据**安装清单**卸载本包安装的 skill（只删本包装的，见下文「卸载」） |
-| `npx @tanlinfeng/project-docs-workflow uninstall --dry-run` | 只打印卸载计划（将删除 / 保留哪些），不写入 |
-| `npx @tanlinfeng/project-docs-workflow uninstall --force` | 跳过交互确认；非 TTY 场景下**必须**加此参数 |
+skill 会检查并创建缺少的内容，包括：
 
-### 覆盖策略（安全优先）
+- `AGENTS.md` 中的 `## Agent skills` 区块
+- `docs/agents/issues.md`、`docs/agents/domain.md`、`docs/agents/workflow.md`
+- `docs/agents/deps/` 依赖兜底文件
+- `docs/issues/` issue 目录树
+- `docs/adr/README.md`、`docs/pdr/00-README.md`、`docs/current/00-README.md` 和 `CONTEXT.md`
 
-安装器**永不覆盖用户已存在的同名 skill**。若目标目录中已存在同名目录，会打印 `同名 skill 已存在，保留用户版本：<name>` 并跳过。只有对主 skill `project-docs-workflow` 使用 `--force` 时才会覆盖它；依赖 skill 即使加了 `--force` 也仍会跳过。
+每个项目手动运行一次即可。以后模板更新时可以再次运行，以检查对齐情况并报告差异；运行是幂等的，不会改写已有内容。例外是：若 `AGENTS.md` 已存在但没有 `## Agent skills`，skill 会在文件末尾追加该区块；若区块已存在，则只比较、不重写。
 
-### 可选：从上游安装「完整版」依赖 skill
+## 命令与选项
 
-包内自带的依赖 skill 是来自 `mattpocock/skills` 的**轻量版**。如果你更想要**完整上游版本**，可以启用 `--with-matt-skills`：安装器会调用官方 `skills` CLI（npm 包 `skills`）执行
+| 场景 | 命令 / 选项 | 说明 |
+| --- | --- | --- |
+| 安装到默认目录 | `npx @tanlinfeng/project-docs-workflow` | 默认动作是安装，目标为 `~/.agents/skills`。 |
+| 预览安装 | `npx @tanlinfeng/project-docs-workflow --dry-run` | 仅显示计划：不写文件、不询问、不执行上游；Node 相关判断（如上游可用性）如实反映。 |
+| 指定 skills 根目录 | `npx @tanlinfeng/project-docs-workflow --dir <path>` | 覆盖默认目录。 |
+| 覆盖第一方 skill | `npx @tanlinfeng/project-docs-workflow --force` | 当第一方条目无法被有效清单确认为包内安装时，显式替换它；**不**更新外部依赖（外部更新需显式 `--with-matt-skills`）。卸载时表示跳过交互确认。 |
+| 显式刷新上游依赖 | `npx @tanlinfeng/project-docs-workflow --with-matt-skills` | 可选增强：通过 `npx` 安装缺失 + 更新已存在的 8 个外部上游完整版；仅在默认 codex 全局目标可执行，其他组合在写入前拒绝。需 Node.js >= 22.20；失败不复制独立轻量版。 |
+| 检查依赖 | `npx @tanlinfeng/project-docs-workflow check` | 逐项检查：目标目录存在同名 skill（按名解析，**不**验证是否为完整版）**或**主 skill 内置回退 `references/deps/*` 可用即通过；全新安装（未装任何独立依赖）也会通过。不检查主 skill 是否安装，也不检查项目文档是否初始化。 |
+| 预览卸载 | `npx @tanlinfeng/project-docs-workflow uninstall --dry-run` | 只显示删除计划，不询问、不删除。 |
+| 交互卸载 | `npx @tanlinfeng/project-docs-workflow uninstall` | 根据安装清单卸载本包记录的内容；TTY 下询问确认（默认否）。 |
+| 非交互卸载 | `npx @tanlinfeng/project-docs-workflow uninstall --force` | 跳过确认；非 TTY 下必须显式传入 `--force`。 |
 
-```bash
-npx --yes skills@latest add mattpocock/skills -g -y -a <agent> -s <name1> <name2> ...
-```
+更多安装依赖的选项及行为见下方「高级细节」。
 
-- **交互式询问**：不带 `--with-matt-skills` 时，仅当 stdout 与 stdin **都是 TTY**、动作为 `install`（非 `check`）、且非 `--dry-run` 时，才提示一次 `是否从上游安装依赖 skill 的完整版（mattpocock/skills）？[y/N] `，**默认否**（空输入或其它输入均视为否）。非 TTY / 管道 / CI 场景**完全不询问**，不会挂起。
-- **受管集合**：仅这 8 个名字参与上游安装：`grilling`、`grill-me`、`grill-with-docs`、`domain-modeling`、`tdd`、`deepwork`、`retro`、`improve-codebase-architecture`；`doc-opt` 与主 skill 不属于上游集合，维持原有行为。
-- **永不覆盖**：调用上游前会先检测这 8 个名字里哪些在目标目录中**已存在**，已存在者**原样保留、绝不提交给上游**；只有缺失的名字才会通过 `-s` 传给上游。
-- **顺序与去重**：先跑上游；随后复核上游目标目录，仍然缺失的名字才回退复制本包的轻量版。启用上游时，由上游负责的名字不会再复制轻量版；未启用时（默认）行为与之前完全一致。
-- **降级、绝不失败**：Node < 22.20、找不到 `npx`、上游非 0 退出或网络错误时，只打印中文告警并回退到缺失项的轻量版安装，整体仍以退出码 0 结束。
-- **agent 与目录注意**：上游固定以 `-a <agent> -g` 安装到该 agent 的**全局目录**（默认 `codex` → `~/.agents/skills`，正好与默认目标一致）。可用 `--matt-agent <name>` 覆盖 agent。若你传入了非默认的 `--dir`，上游部分**无法跟随 `--dir`**（仍落到 agent 全局目录），安装器会明确告警，同时 `--dir` 下的轻量版仍按原逻辑处理。
-- **dry-run**：`--dry-run --with-matt-skills` 只打印将执行的上游命令、以及哪些名字因已存在而跳过，不实际执行。
+## 安装与更新语义
 
-## 卸载
+普通安装（默认动作）对**第一方 skill**（`project-docs-workflow`、`doc-opt`、`docs-html-view`）执行**全目录同步**：
 
-安装时，本包会在 `<target>/.project-docs-workflow.install.json`（`<target>` 为 `--dir` 或默认 `~/.agents/skills`）写入一份**安装清单**，记录每个被处理过的 skill 及其**归属**。卸载完全依据这份清单，而不是靠猜测。
+- 若上一份**有效清单**确认该路径由本包安装（`installed` / `forced`、本地），安装会用源包内容覆盖该目录——**可能覆盖你对本地文件所做的修改**。第一方受管安装目录是可整体替换的分发副本。
+- 若某第一方路径无法被有效清单确认为包内安装（手工复制、清单记为 `skipped`、清单缺失、清单损坏 / 不可解析、符号链接），默认**保留**不动；只有显式 `--force` 才替换该第一方条目。替换的是该路径本身，符号链接指向的 referent 不被改动。
 
-清单形如：
+**外部依赖默认不分发、不自动安装**：普通安装与 `--force` 默认都**不**安装或更新独立外部依赖（`--force` 只作用于第一方）；唯一的例外是用户在上文「可选增强」中明确同意安装缺失的上游完整版。缺失的独立名称**不等于能力缺失**——主 skill 内置回退 `references/deps/*` 已可用，全新安装即可独立工作。安装**先检查 / 列出**依赖：已存在的独立依赖一律保留；对**缺失**的受支持名称，仅在交互式安装（stdin 与 stdout 均为 TTY、非 dry-run）且上游目标安全、Node 达标时，**可选**询问一次是否安装上游完整版（回答 yes 只安装缺失项、不更新已有）。No / 回车 / 非 TTY / 非等价的自定义 `--dir` / Node 不足 → 直接使用内部回退，**不**复制任何独立轻量 skill。要**刷新已有外部依赖**，须显式 `--with-matt-skills`（见「可选上游依赖」）或自行手动更新。主 skill 的内部引用（`references/deps/*`）随主 skill 一起更新，不当作独立外部依赖单独管理。
 
-```json
-{
-  "version": "2.2.0",
-  "target": "/home/me/.agents/skills",
-  "updatedAt": "2026-10-12T05:24:36.386Z",
-  "entries": {
-    "project-docs-workflow": { "kind": "main",     "action": "installed", "at": "…" },
-    "tdd":                    { "kind": "lite",     "action": "installed", "at": "…" },
-    "doc-opt":                { "kind": "doc-opt",  "action": "installed", "at": "…" },
-    "deepwork":               { "kind": "lite",     "action": "skipped",   "at": "…" },
-    "retro":                  { "kind": "upstream", "action": "installed", "agent": "codex", "at": "…" }
-  }
-}
-```
+安装只处理 skills 目录，**不会**初始化或改写目标项目内已物化的文档（`AGENTS.md`、`docs/agents/*` 等）；项目文档需要显式运行 skill 对齐 / 迁移。`--dry-run` 不写任何文件、不询问、不执行上游，逐条显示将执行的精确动作。本包不提供独立的 `update` 命令；更新即重新运行安装。
 
-- `kind`：`main` / `lite` / `doc-opt`（本包复制的轻量版）/ `upstream`（委托上游 `skills` CLI 安装的完整版）。
-- `action`：`installed`（本次由本包创建）、`forced`（被 `--force` 覆盖，仍属本包）、`skipped`（安装时已存在，本包原样保留，**永不删除**）。
-- 每次成功 `install` 都会**合并更新**清单（不会丢失旧条目）；`--dry-run` 不写清单。
+**边界说明（简明）：**
 
-**归属规则（安全优先）**：`uninstall` 只删除清单中 `action` 为 `installed` / `forced` 的名字——无论是本包复制的轻量版，还是本包委托上游安装的完整版。凡是安装时**已存在**（记为 `skipped`）的名字，一律不碰；首次记为 `skipped` 的名字即使后续再次安装也始终保持 `skipped`。
+- **清单文件本身是符号链接时始终拒绝**（即使 `--force`），以免覆盖外部文件；这与「第一方 skill 路径是符号链接」不同——后者在 `--force` 下可替换该路径本身。
+- 替换按**单个 skill** 进行：某次替换失败时会尝试恢复旧内容；若无法恢复，则保留备份并在报告中给出路径。这只是单个 skill 的失败处理，**不是**所有 skill 的事务性原子操作。
 
-用法：
+## 卸载安全须知
 
-```bash
-npx @tanlinfeng/project-docs-workflow uninstall [--dir <path>] [--dry-run] [--force]
-```
+安装器会在目标 skills 根目录写入 `<target>/.project-docs-workflow.install.json`，卸载时依据清单记录的 skill **名称和操作类型**决定删除哪些路径：`installed` / `forced` 项会删除，`skipped` 项保留。清单记录的是名称和操作，**不记录内容哈希，也不记录你对本地文件的改动指纹**：如果你之后把自己或其他工具的内容放到一个记录为本包安装的同名路径下，卸载仍会删除该路径。第一方受管安装目录是可整体替换的分发副本。运行卸载前请先检查清单和目标目录；不确定时先使用 `--dry-run`。
 
-- **确认**：在交互式终端会询问一次 `确认卸载本包安装的 skill？[y/N] `，**默认否**。非交互式（管道 / CI / 非 TTY）**拒绝执行**，除非显式传入 `--force`。`--dry-run` 从不询问、从不写入。
-- **删除方式**：`main` / `lite` / `doc-opt` 直接删除 `<target>/<name>` 目录。`upstream` 的完整版**优先委托上游** `skills` CLI 卸载（按 agent 批量）：`npx --yes skills@latest remove <names> -g -y -a <agent>`；当无法委托时（Node < 22.20、找不到 `npx`、上游非 0 退出）会打印告警并**回退直接删除**目录，并提示上游锁文件 `~/.agents/.skill-lock.json` 可能残留过期条目，可用 `npx skills@latest list` 核对。
-- **收尾**：处理完成后删除清单文件本身；**不会**删除目标目录本身，其它文件与空目录保持不动。
-- **幂等**：没有可删项时打印友好提示并以退出码 0 结束。若**清单缺失**，会告警「无清单，尽力而为」，此时**仅**在 `project-docs-workflow` 存在时询问是否删除它，其余 skill 一律不动。
+如果清单不存在，卸载器只会处理主 skill `project-docs-workflow`，不会推测或删除其他依赖。实际卸载中，只有存在可移除条目时才会在完成后删除清单；dry-run、取消操作和没有可移除条目的运行都会保留清单。清单里的上游完整版会尽量通过 `skills` CLI 卸载；无法调用 CLI 时会回退为直接删除，可能留下上游锁文件中的过期条目。
 
-## 用法示例
+## 手动复制
 
-```bash
-# —— 安装 ——
-npx @tanlinfeng/project-docs-workflow                       # 装到默认 ~/.agents/skills（轻量依赖）
-npx @tanlinfeng/project-docs-workflow --dir ~/.config/opencode/skills
-npx @tanlinfeng/project-docs-workflow --dry-run             # 预演，不写入
-npx @tanlinfeng/project-docs-workflow --force               # 覆盖主 skill（依赖仍不覆盖）
-npx @tanlinfeng/project-docs-workflow --with-matt-skills    # 依赖改从上游装完整版（需 Node >= 22.20）
-npx @tanlinfeng/project-docs-workflow --with-matt-skills --matt-agent opencode
-
-# —— 检查依赖解析 ——
-npx @tanlinfeng/project-docs-workflow check                 # 全部可解析退出 0，否则 1
-
-# —— 卸载 ——
-npx @tanlinfeng/project-docs-workflow uninstall --dry-run   # 只出计划
-npx @tanlinfeng/project-docs-workflow uninstall             # 交互确认（默认否）
-npx @tanlinfeng/project-docs-workflow uninstall --force     # 非交互必传；只删本包安装的
-npx @tanlinfeng/project-docs-workflow uninstall --dir ~/.config/opencode/skills --force
-```
+也可以不使用 npm 安装器，直接将 `skills/` 中需要的目录复制到 skills 根目录；只复制 `skills/project-docs-workflow` 也可以独立工作，因为主 skill 内含依赖 ref 兜底。手动复制不创建安装清单，因此这些路径属于「无法被有效清单确认」的第一方路径，安装时默认**保留**，只有显式 `--force` 才替换。之后运行 `uninstall` 时无法识别手动复制的依赖；若没有安装清单，它只会处理主 skill。
 
-- 交互式终端下、不带 `--with-matt-skills` 安装时，会**询问一次**是否装上游完整版（默认否）；管道 / CI 不提示、不挂起。
-- 卸载在非 TTY 下没有 `--force` 会**拒绝执行**（退出码 1）；`--dry-run` 从不询问、从不写入。
+## docs-html-view（可选：手动渲染文档）
 
-## 直接复制（不使用 npm 安装器）
+本包附带一个第一方 skill `docs-html-view`（与主 skill、`doc-opt` 一样，不属于上游集合）。安装器会随包一起分发它，但**安装时不会运行它**，项目文档初始化时也不会启用它；它只在用户手动调用时工作。
 
-也可以完全跳过安装器，手动把 `skills/` 下需要的内容复制进你的 skills 根目录：
+用途：把项目文档（PDR / Current / ADR）用标准的 Read the Docs（RTD）主题与 MyST Markdown 解析渲染成静态 HTML，输出到 `docs/docsHtmlView/build/html`。仅供本地浏览与分享，不替代源文档。
 
-- 逐个复制 `skills/*` 中的目录；**遇到同名目录就跳过，绝不覆盖用户版本**。
-- 也可以**只复制 `skills/project-docs-workflow` 这一个目录**：它会通过内部的 ref 兜底（`references/deps/*.md`）独立工作，无需其他依赖 skill。
+**边界（重要）：**
 
-## 两级解析协议
+- **先确认再动手**：初始化与构建前，agent 会先列出所需的 Python 包、环境以及将要创建 / 修改的文件，取得你的明确同意后才执行；不会静默装包或改环境。
+- **环境**：优先复用项目明确约定的文档环境；没有合适环境时才创建独立的 `.venv-docs`，不修改系统或应用环境。
+- **标准构建**：首次使用 `sphinx-quickstart` 初始化，之后复用配置，通过 `make html`（或 `sphinx-build`）按需增量构建，不自建渲染封装器。
+- **全手动**：不注册自动钩子，不自动打开浏览器，不启动常驻服务，不部署。
+- **源文档只读**：渲染只读取源文档，不修改 `docs/` 下的 PDR / Current / ADR 源文件。
+- **不参与 `check`**：`project-docs-workflow check` 只检查主 skill 的依赖解析状态，**不检查** `docs-html-view`，也不校验其渲染结果。
 
-skill 在引用依赖能力时，遵循两级解析：
+具体的脚本、命令与参数以该 skill 的 `SKILL.md` 为准（安装后位于 `<skills 根目录>/docs-html-view/SKILL.md`），README 不再重复其接口。
 
-1. **按名解析**：如果 skills 根目录下存在同名 skill（`<target>/<name>/SKILL.md`），直接使用该已安装的 skill。
-2. **ref 兜底**：否则，回退到主 skill 内部自带的 `references/deps/<fallback>.md`。
+## English summary
 
-| 引用名 | 兜底文件 |
-| --- | --- |
-| `grilling` | `grilling.md` |
-| `grill-me` | `grilling.md` |
-| `grill-with-docs` | `grilling.md`、`domain-modeling.md` |
-| `domain-modeling` | `domain-modeling.md` |
-| `tdd` | `tdd.md` |
-| `deepwork` | `boundaries.md` |
-| `retro` | `boundaries.md` |
-| `doc-opt` | `doc-opt.md` |
-| `improve-codebase-architecture` | `boundaries.md` |
+`@tanlinfeng/project-docs-workflow` is an agent skill for setting up and maintaining project documentation workflows: issues, ADRs, PDRs, domain terminology, and development practices. Install it with `npx @tanlinfeng/project-docs-workflow@latest install`, or pin an exact published version with an npm spec such as `@2.2.0` (Node.js >= 18; default destination `~/.agents/skills`). Without a spec, npx may prefer the version already installed in the current project; write `@latest` or `@<version>` to select the installer version (cache/network policy is separate), and the installer never fetches versions itself. Because `npx <pkg>@<version> install` runs that version's own installer code, the sync / `--force` semantics on this page apply only to package versions that contain this installation strategy; older published versions keep their historical behavior (e.g. `--force` may only overwrite the main skill), so pinning an older version is only an equivalent rollback within such compatible versions. Installation does not initialize a project: from the target project root, manually invoke the skill using your agent's own skill mechanism. It creates missing documentation, reports drift on reruns, and does not overwrite existing content, except that it appends a missing `## Agent skills` block to an existing `AGENTS.md`.
 
-`check` 子命令会对照上表逐个报告「按名可解析（skill 已安装）」或「ref 兜底可用」，只要每个名字能通过任一级解析即视为通过。
+An ordinary install full-directory-syncs the first-party skills (`project-docs-workflow`, `doc-opt`, `docs-html-view`) when a valid manifest confirms the package installed them, so it may overwrite local edits; a first-party path not confirmed as package-owned is preserved unless `--force` replaces that entry. External dependencies are preserved by default, and `--force` alone does not update them; explicit `--with-matt-skills` refreshes the eight supported upstream names (updating existing ones and installing missing) only on the default codex target, with other target/agent combinations rejected before any write. The package ships no standalone dependency skills: missing external names are covered by the skill's internal fallback references (`references/deps/*`), no independent lite skill is copied, and existing standalone installs (including older lite copies) are preserved and never auto-cleaned or migrated. A manifest file that is itself a symlink is always refused (even with `--force`), unlike a first-party skill path that is a symlink; per-skill replacement failures restore the old content or retain a backup and report the path, so this is not an all-skills transaction. The installer supports custom directories, dry runs, dependency checks, and manifest-based uninstall. Uninstall removes recorded package-owned paths by name, not by content hash, and records no local-edit fingerprints; review the manifest or use a dry run before deleting anything. See the advanced details below for optional upstream dependencies and manifest behavior.
 
-## 内置 skill 与来源
+The package also ships a first-party `docs-html-view` skill (manual invocation only; distributed but not run at install). It renders PDR/Current/ADR docs to `docs/docsHtmlView/build/html` with Sphinx, MyST, and the stock RTD theme. After approval of packages, environment, and files, it uses `sphinx-quickstart` once and standard `make html` or `sphinx-build` thereafter. It never hooks, opens a browser, serves, deploys, or mutates source docs. `check` does not cover it.
 
-| skill | 说明 | 来源 |
-| --- | --- | --- |
-| `project-docs-workflow` | 主 skill：issue / ADR / PDR / 术语 / 工作流 | 本包 |
-| `grilling`、`grill-me`、`grill-with-docs` | 需求拷问相关 | `mattpocock/skills` 精简版（MIT，Matt Pocock） |
-| `domain-modeling` | 领域建模 | 同上 |
-| `tdd` | 测试驱动开发 | 同上 |
-| `deepwork`、`retro`、`improve-codebase-architecture` | 精简/占位版本 | 同上 |
-| `doc-opt` | 文档优化（附赠完整版） | 本包附赠 |
+<details>
+<summary>高级细节</summary>
 
-部分内置 skill 内容摘自 <https://github.com/mattpocock/skills>（MIT License，Copyright (c) 2026 Matt Pocock），详见 [`NOTICE`](./NOTICE)。
+### 可选上游依赖
 
-上表中的 8 个上游依赖 skill 都可以改用完整版：安装时加 `--with-matt-skills` 即会从上游安装（见上文「可选：从上游安装『完整版』依赖 skill」）。
+主 skill **自带内部回退**（`references/deps/{grilling,domain-modeling,tdd,doc-opt,boundaries}.md`）：外部依赖未安装时按对应回退执行，功能可用。本包**不**随包分发独立依赖 skill——默认只分发三个第一方 skill（`project-docs-workflow`、`doc-opt`、`docs-html-view`）；安装器也不复制任何独立轻量 skill。
 
-## 版本说明
+**默认（不带 `--with-matt-skills`）：**
+- 已存在的独立依赖一律**保留**（含旧版本曾复制的轻量目录），不判定完整版、不自动清理 / 迁移。
+- 缺失的受支持名称：仅在交互式安装（stdin 与 stdout 均为 TTY、非 dry-run）且上游目标安全、Node >= 22.20 时**可选**询问一次；这是**可选的完整版增强**，不是必需依赖。回答 yes 只安装缺失项；No / 直接回车 / 非 TTY / 非等价的自定义 `--dir` / Node 不足时，直接使用内部回退（**不**复制独立轻量 skill）。
+- `--force` 单独使用**不**安装或更新外部依赖。
 
-本包版本 `2.x` 与「模板生成 v2」对齐：模板结构与生成约定以 v2 为准。
+**显式 `--with-matt-skills`（可选增强）：** 通过 `npx` 安装缺失 + **更新**已存在的 8 个外部上游完整版；不询问，提示**本地依赖改动可能被覆盖**。第一方自带集合（主 skill、`doc-opt`、`docs-html-view`）**不提交上游**，但仍照常执行普通第一方全目录同步；命名集合之外的外部目录保留不动。需 Node.js >= 22.20。
 
-## License
+仅以下 8 个名称参与上游操作：`grilling`、`grill-me`、`grill-with-docs`、`domain-modeling`、`tdd`、`deepwork`、`retro`、`improve-codebase-architecture`。`/grill-me` 不再由本包提供独立入口；需要独立入口请安装上游，主 skill 的内部回退仍支持相同行为（无斜杠别名）。
 
-MIT，见 [`LICENSE`](./LICENSE)。
+**目标目录安全（重要）：** 上游 `skills` CLI 没有 `--dir`，其目标由 `-g -a <agent>` 决定。本安装器只在**默认 codex 全局目标**（或与其 realpath 等价、可验证匹配的目录）下才执行上游操作；只有**非等价的自定义 `--dir`，或未经验证的 `--matt-agent` 组合**无法证明匹配，会在**任何写入之前拒绝** `--with-matt-skills` 并给出手动更新指引。普通（非等价自定义 `--dir`）安装仍照常保留已有依赖、使用内部回退，不给出误导性的上游询问；realpath 与默认目标等价的别名不受此限，仍可能给出可选询问。
 
----
+**失败处理（非原子）：** 上游 `add -y` 会覆盖，且没有 `--force add`；安装器以窄名称集合 + `--json` 逐个检测成功 / 失败。已有依赖更新**可能部分成功**，本包装器**不负责恢复**，请勿视为原子或可回滚；**不再复制独立轻量版**作为回退。已存在的依赖失败时**不删除、不重建**，保留原归属（可能已被上游部分改动）；仅在**原本缺失、本次尝试新建**的项失败时，清理该新路径（仅此路径）并以非零退出报告。无论成功与否，主 skill 内部回退始终可用，基本安装的主 skill 可正常工作；可选的上游请求未满足时**明确失败**（非零退出），不报告成功。仅在已知安全目标上确认成功的项才在清单中记为 upstream-owned。上游 CLI 的 `--json` 输出契约并未稳定公开；若其格式变化导致无法解析，安装器将**保守地按失败报告**（不声称成功）。
 
-## English summary
+### 安装清单格式
 
-`project-docs-workflow` is an npm-packaged agent **skill bundle** for project documentation workflows: issue tracking, ADRs, PDRs, a terminology glossary, and the workflow that ties them together. The main skill is self-contained via internal `references/deps/*.md` fallbacks, and ships with lightweight dependency skills (trimmed from [mattpocock/skills](https://github.com/mattpocock/skills), MIT, Matt Pocock) plus a bundled `doc-opt` bonus skill.
+清单合并记录每个 skill 名称的处理结果，不含内容哈希。字段包括包版本、目标目录、更新时间和按名称索引的条目；条目记录类型、操作以及上游 agent（适用时）。示例：
 
-Install with `npx @tanlinfeng/project-docs-workflow` (defaults to `~/.agents/skills`; options: `--dir <path>`, `--force`, `--dry-run`, `--with-matt-skills`, `--matt-agent <name>`, and the `check` / `uninstall` subcommands). The installer **never overwrites** an existing skill of the same name — it skips it, preserving your version. `--force` overwrites only the main `project-docs-workflow` skill.
+```json
+{
+  "version": "<package-version>",
+  "target": "/home/me/.agents/skills",
+  "updatedAt": "<iso-timestamp>",
+  "entries": {
+    "project-docs-workflow": { "kind": "main", "action": "installed", "at": "…" },
+    "doc-opt": { "kind": "doc-opt", "action": "installed", "at": "…" },
+    "docs-html-view": { "kind": "docs-html-view", "action": "skipped", "at": "…" },
+    "retro": { "kind": "upstream", "action": "installed", "agent": "codex", "at": "…" }
+  }
+}
+```
 
-Every successful install writes an **install manifest** at `<target>/.project-docs-workflow.install.json` recording, per skill name, the `kind` (`main`/`lite`/`doc-opt`/`upstream`) and `action` (`installed`/`forced`/`skipped`), merged across re-installs. `uninstall [--dir <path>] [--dry-run] [--force]` removes **only** the names this package owns (`installed`/`forced`) and never touches names that pre-existed (`skipped`, decided by the record, not by guessing). On a TTY it asks once (`[y/N]`, default No); on a non-TTY it refuses unless `--force` is given. Lite/main/doc-opt copies are deleted directly; upstream full versions are removed via the `skills` CLI (`npx --yes skills@latest remove <names> -g -y -a <agent>`), falling back to direct deletion with a warning about a possibly-stale `~/.agents/.skill-lock.json` if delegation is impossible. `--dry-run` prints the plan and never prompts or writes; the manifest is deleted afterwards, the target directory itself is left in place.
+`kind` 可为 `main`、`doc-opt`、`docs-html-view` 或 `upstream`；历史清单里还可能出现 `lite`（早期版本曾复制独立轻量 skill）——安装时一律保留，用户主动运行 `uninstall` 时仍按历史归属处理（升级时不会静默清除用户目录；清理 / 迁移仅在用户显式授权时进行）。`action` 可为 `installed`、`forced` 或 `skipped`。卸载按记录的路径/名称操作：`skipped` 以及未知状态的条目保留。上游项会尽量通过 `skills` CLI 批量移除；若 CLI 无法运行或返回失败，安装器会直接删除对应目录作为回退，这可能使 `~/.agents/.skill-lock.json` 留有过期记录。
 
-Optionally, `--with-matt-skills` installs the **full upstream** versions of the dependency skills from `mattpocock/skills` via the official `skills` CLI (`npx --yes skills@latest add mattpocock/skills -g -y -a <agent> -s ...`, requires Node >= 22.20). Without the flag, an interactive TTY gets a single prompt (default **No**); non-TTY/piped/CI runs never prompt. The 8 upstream-managed names are `grilling`, `grill-me`, `grill-with-docs`, `domain-modeling`, `tdd`, `deepwork`, `retro`, `improve-codebase-architecture`; `doc-opt` and the main skill are unaffected. Any name already present is left untouched and never sent upstream, and the installer re-checks afterwards, falling back to the bundled lite copy for anything still missing. If upstream can't run (Node too old, no `npx`, non-zero exit, network error), it warns and falls back — the install still exits 0. Upstream installs into the agent's global dir (`codex` → `~/.agents/skills`), so it cannot follow a custom `--dir` (a warning is printed).
+### 依赖解析与来源
 
-You can also copy `skills/*` directly into your skills root (skip any existing directory name, never overwrite); copying just `skills/project-docs-workflow` works standalone thanks to the internal ref fallbacks.
+`check` 逐项检查依赖：目标目录中存在同名 skill（按名解析即可，**不**验证是否为完整版）**或**主 skill 内置 `references/deps/*.md` 回退可用，即视为通过——因此全新安装（未装任何独立依赖）也会通过。这不是主 skill 安装检查，也不是项目初始化检查。
 
-Resolution is two-level: use an installed skill by name if present, otherwise follow `references/deps/*.md` inside the skill. Version `2.x` aligns with template generation v2. Licensed MIT (see `LICENSE` and `NOTICE`).
+内部回退文档中**源自上游的部分**（见 [`NOTICE`](./NOTICE)：`references/deps/{grilling,domain-modeling,tdd,boundaries}.md`）裁剪 / 改编自 [mattpocock/skills](https://github.com/mattpocock/skills)（MIT，Matt Pocock）；`references/deps/doc-opt.md` 为本包第一方回退，**非**上游派生。本包**不**随包分发独立依赖 skill；`doc-opt` 与 `docs-html-view` 是本包附带的第一方 skill。主 skill 对引用能力先按名解析已安装的独立 skill，不存在时执行内部 ref 回退。详见 [`NOTICE`](./NOTICE)。
 
-**Examples**
+</details>
 
-```bash
-npx @tanlinfeng/project-docs-workflow                       # install (default ~/.agents/skills)
-npx @tanlinfeng/project-docs-workflow --dir <path> --dry-run
-npx @tanlinfeng/project-docs-workflow --with-matt-skills    # full upstream deps (Node >= 22.20)
-npx @tanlinfeng/project-docs-workflow check
-npx @tanlinfeng/project-docs-workflow uninstall --dry-run
-npx @tanlinfeng/project-docs-workflow uninstall --force     # only removes what this package installed
-```
+## License
+
+MIT，见 [`LICENSE`](./LICENSE)。