Imported from tom-cat-mao/TaskWizard (pages/AGENTS.md). Install upstream with npx skills add tom-cat-mao/TaskWizard --skill pages. Copyright stays with the author.

pages/ — 文档标准守护

本目录是 mkdocs.yml 的 docs_dir：这里的每一页都是公开文档站的一页，nav 在 mkdocs.yml。 全仓军规在仓库根的 AGENTS.md，为什么这样设计在 .agents/notes/，事故沿革在 postmortem/—— 这三者都在本站之外，站内链接不要把路径指出去。

四条铁律

1. 一事实一归宿。一个事实只在一处写正文，别处链接过去。pages/ 写是什么与怎么用；根 AGENTS.md 写 不可违反的军规；模块 docstring 写模块契约；.agents/notes/ 写当时的取舍；postmortem/ 写事故。同一事实 写两遍，就是两处都要改——漂移只是时间问题。
2. 只写当下事实。描述此刻的契约与用法，不写沿革与变迁（谁取代了谁、某种说法何时改口、旧形态长什么样）。 要讲因果与历史，写 .agents/notes/ 或 postmortem/。
3. 不手抄生成物。配置键、env 变量、默认值、工具与能力清单这些以源码为准的清单，抄进文档就是第二份真相： 要么链接源码，要么只写语义。完整配置键清单的归宿是 pages/configuration.md。
4. 代码块必须可跑。示例是真命令：改文件名、改默认参数、删入口时同批改示例；跑不通的示例等于错误文档。

第 2-4 条各有机器门禁，都在 tests/docs/：变迁措辞（test_docs_freshness.py）、笔记格式 （test_notes_format.py）、配置键三方一致（test_config_keys_sync.py）、bash 块可解析 （test_doc_bash_blocks.py）。行为规则句里的变迁词可以带 <!-- allow:词 --> 行级豁免：注释与命中词同行或 紧邻上一行才生效，渲染后不可见——它是一句「这行是规则」的声明，不是一个页面的免检牌。

锚点是兼容面

P0 表除 #9、#10（仓库规则，无正文）与 #23（链到笔记规则）外，每行都链到本目录的 {#anchor}；历史链接与 文档站深链也按它落地。改小节标题可以，改锚点 id 不行——它是对外契约。

锚点 id 靠人工约定维护：tests/docs/test_doc_references.py 跳过含 # 的 token，没有机器核对锚点是否 存在，改标题时自己回头核对本文件与根 AGENTS.md 里的引用。

字数超限怎么办

本目录每页有词数预算，清单在 tests/docs/doc-budgets.json，由 pytest tests/docs -q 校验。超了就按顺序走 三步，别跳步：

1. 下沉迁移：把细节挪进更专门的页面或子模块文档，本页只留结论与链接；
2. 精简浓缩：删重复叙述、删能从源码直接读出的事实、删修饰语；
3. 申请提额：改 tests/docs/doc-budgets.json 的数字，并在 PR 里写明理由——前两步为什么不够、 新增的正文为什么必须常驻本页。

发布门禁

pytest tests/docs -q                # 预算、引用存在性、变迁词、笔记格式、配置键、bash 块
python -m mkdocs build --strict     # 站内链接、nav 与构建

本文件不进 nav：它是写文档的人的纪律，不是对外页面。