zenf-docs 是 ZenForge 的 SSOT（单一事实来源）文档入口。它面向希望登记长期文档、把某文档提升为权威来源、解决重复来源或搜索注册表的调用方。其核心理念是：文件本身为权威版本，注册表只保存身份、分类、标签、哈希和可搜索快照。
用途
- 登记长期存在的文档，并维护可检索的元数据记录。
- 将文档提升为某个主题的权威来源，或以新文档取代、收窄既有文档。
- 解决同一主题的重复来源问题。
- 在注册表中按关键词、类型、范围、状态、标签检索文档。
主要能力
- 分类：类型可选 ARCHITECTURE、ADR、SPEC、RULE、GUIDE、REFERENCE、MEMORY、OTHER；范围可选 GLOBAL、PROJECT、PLAN、TASK，当范围为 PLAN/TASK 时需指定 scope_ref（计划 slug 或任务 id）；状态可选 DRAFT、ACTIVE、SUPERSEDED、ARCHIVED。
- 身份标识：key 为简短稳定句柄（如 ARCH、ADR-004、MCP），slug 为人类可读唯一名称并默认等于 key；project_slug 为空表示全局；key 与 slug 在每个项目内唯一。
- 路径确认：path 必须指向规范文件（绝对路径或仓库相对路径），注册前需确认文件存在且可读。
- 注册：可通过 MCP（docs(action=create)）或 HTTP（POST /api/v1/docs）提交相同字段；省略 content 时由守护进程读取文件，仅在文件故意不可用时才自行提供内容；超过 4 MiB 的文件注册时不生成快照。
- 刷新：编辑后调用 docs(action=refresh, id=...) 或 POST /api/v1/docs/{id}/refresh，重新计算哈希、大小、版本与全文检索（FTS）索引。
- 退役：先设为 status=SUPERSEDED 并关联替代文档，再归档；归档仅隐藏记录而不删除文件；删除只移除注册表行，文件仍留在 Git 中。
- 媒体处理：图片、PDF、DOCX、XML 等媒体仅以绝对路径记录，绝不内联二进制内容。
使用方式
- 先读 docs/README.md 找到该主题现有的权威来源，判断文档是全局（跨仓库规则/参考）还是项目范围。
- 写之前先搜索：docs(action=search, query=...) 或 GET /api/v1/docs/search?query=；若已有权威，应修订而非另立并行文档。
- 选择写入通道：MCP 可用时优先使用 MCP（docs 与 search）；MCP 不可用时使用 HTTP 的 /api/v1/docs 端点；守护进程不可达时只能更新 Markdown 与 docs/README.md 的放置矩阵，并报告登记待处理。
- 完成分类、身份与路径确认后注册，编辑后刷新，退役时设置取代关系再归档。
元数据规则
- title：一句话，不重复 slug。
- summary：一到两行，用于搜索结果展示。
- tags：小写、稳定词汇（如 architecture、security、mcp），优先复用已有标签。
- path：仅规范文件，不得指向草稿或生成的构建产物。
- content：仅用于 FTS 的快照，永远不是权威来源。
- status：内容评审通过后才设为 ACTIVE。
适用场景
- 跨仓库的架构规则与参考文档登记为全局权威。
- 项目内 ADR、规范、指南、参考文档的登记、检索与版本刷新。
- 计划或任务范围内文档的挂接与追踪。
- 冲突权威的识别与取代关系维护。
限制与约束
- 每个主题只能有一个权威；新文件必须取代或收窄既有文档，不得创建隐式并行来源。
- 不要将生成或临时文件（构建输出、草稿、.agents/scratch/）登记为 SSOT。
- 不要通过编辑快照来修改内容，应修改文件后刷新。
- 全局文档必须真正跨项目，项目规则保持项目范围。
- 标签词汇漂移会使搜索失效，应优先复用已有标签。
- 媒体仅记录路径；大文件不生成快照。
- 具体 API 载荷与 schema 字段需参考 /zenfd-tools，本文未提供。
输出格式 文档信息包含 key/slug/type/scope/status、project（slug 或 global）、path、hash（sha256 前缀）、字节数与版本号；验证信息包含文件是否存在、指定查询的 FTS 命中情况与取代关系。