用途：辅助在 Switchyard 已发布的 MkDocs 文档站上新增或编辑页面，覆盖 docs/、mkdocs.yml 与 .github/workflows/docs.yml，包括把新页面接入导航。
主要能力：说明公开站点只发布 mkdocs.yml 中 nav 列出且未被 exclude_docs 排除的页面，其余 docs/ 文件为内部设计笔记；强调 mkdocs build --strict 是 CI 与 make publish 的构建契约，任何警告都会导致失败；介绍 mkdocs_hooks.py 的 on_page_markdown 钩子会把仓库内相对路径重写为基于 repo_url 与 extra.source_ref 的源码链接，source_ref 由 MKDOCS_SOURCE_REF 决定，本地回退 main，CI 使用 PR head SHA 或 push SHA；还给出新增页面的流程（判断公开或内部、放置文件、在 mkdocs.yml 的 nav 注册并从 exclude_docs 移除、用相对链接、推送前本地跑 make publish）以及 CI 卫生规范（路径过滤触发、只读默认权限、并发组、setup-uv 缓存、仅同步 docs 组、单一构建产物、PR 预览仅限同仓库 PR）。
使用方式：常用命令包括 cd docs && make env 同步文档依赖、make live 本地预览、make publish 严格构建、make html 增量构建、make clean 清理；可用 grep 查看 nav 与 exclude_docs 当前内容。依赖位于 pyproject.toml 的 docs 组，通过 uv 管理，无独立 requirements 文件。
适用场景与限制：适用于维护该文档站的贡献者。限制包括：代码示例不被 CI 执行、需作者自行验证导入来自 switchyard 公共 API；禁止硬编码仓库 blob/tree URL、禁用 strict、发布内部笔记、引入独立 requirements 文件，或把预览作业改为 pull_request_target；具体内容以仓库当前配置为准。