文档编写约定
第一次接触 Clumsies 的读者，应能找到适合自己的路线，理解系统，并查到可靠的操作说明或接口契约，而不必先读源码。完成一组教程和理解系统架构是两种需求，文档都要照顾。
内容如何组织
每页有一个主要目的。操作中可以解释一个必要概念，接口中也可以给一个示例；需要展开的内容应放到独立页面。
| 页面类型 | 应当写什么 | Clumsies 入口 |
|---|---|---|
| 入门教程 | 明确起点、一条完整练习路线、分步操作和可观察的结果 | 快速开始 |
| 任务指南 | 具体目标、所需权限、影响步骤的选择、操作、验证与恢复 | 任务指南 |
| 概念与设计 | 问题、对象关系、数据归属、设计原因、取舍与边界 | 概览、架构、数据模型、完整流程 |
| 接口参考 | 精确的操作、字段、类型、权限、前置条件、错误和版本规则 | 领域接口、MCP、HTTP |
| 索引 | 面向谁、阅读顺序、前置条件、预期结果和入口 | 首页、指南索引、参考索引 |
“开发与维护”是读者分组，其中的页面仍按上述职责编写。例如，准备开发环境属于任务指南，解释运行时归属属于设计说明。历史内容标明日期或适用版本，并链接当前行为。
怎样维护阅读路线
首页照顾三类读者：使用 Memory 的团队成员、理解设计的技术读者，以及开发集成、运维或修改实现的人。每条路线都说明读完后能完成或解释什么。
五步教程的顺序固定为：创建 Project → 选择已有组织 Memory → 让 Codex 使用 → 明确要求 Codex 提出修改 → 人审阅并发布，再回 Codex 验证。安装和登录属于开始前的准备，不编号。
统一使用 Payments、clumsies-demo 和 deployment-rollback.md。示例文档应已存在于 Organization Memory 中，不是产品内置数据。空组织先进入创建 Memory，完成后再回主线。选择是引用共享文档，不是复制正文。
调整导航时，同时检查：
- 中英文的“上一页”“下一页”与预期阅读顺序一致。
- 需要上一步结果的页面，能链接到产生这个结果的说明。
- 内部专题和历史文档放在标注清楚的折叠分组中。
- 已发布 URL 和有用的章节锚点继续可达；旧入口引向当前说明，不再保留另一套完整教程。
- 中英文的前置条件、示例、角色和完成结果相互对应。
每页应怎样写
入门教程： 先说明要完成什么，如何判断进展。名词在需要时解释。安装替代方案、完整 API 请求和设计讨论链接到各自页面。
任务指南： 从真实问题开始，例如选择共享知识或恢复同步失败。写清起点，以及哪些选择会改变步骤。结尾说明怎样确认结果、失败后到哪里继续处理，不重述整套首次使用流程。
概念与设计： 先建立概念之间的关系，再介绍实现名词。解释哪些数据是正式来源、哪些是派生结果，为什么需要某个边界，以及这种选择带来的代价。使用具体例子；适合用图时，图与文字表达同一关系。仅列一张实体名称表，不足以解释数据模型。
接口参考： 使用一致的结构，让人直接查到输入、权限、错误或并发规则。区分数据库行、HTTP 响应和本地对象。标明节选和占位值，并说明实际 ID、哈希或版本从哪里取得。
索引： 链接到持续维护的详细说明。如果索引逐渐变成第二份解释或教程，就应收短。已发布的成员使用 URL现在保留为任务索引。
怎样判断内容是否准确
| 要写的事实 | 应核对的依据 |
|---|---|
| 某项操作存在，某个角色可以执行 | 当前动作代码、权限处理和相关测试 |
| 一个字段或响应具有某种含义 | 类型或数据库迁移，以及真正使用它的处理器或序列化逻辑 |
| 保存、同步或发布已经完成 | 事务边界、队列处理、状态变化和失败测试 |
| 调用方可以安全恢复或重试 | 错误路径、幂等或版本检查，以及已知限制 |
| 某种 App 安装包可以获取 | 实际 Release 资产与受支持的安装入口 |
设计提案和旧文档可以提供背景，不能证明当前行为。路由覆盖也不能单独证明 schema 准确。在变更说明或相关页面记录核对的版本与依据；实现变化后，不能继续用一个旧基线笼统宣称整站已核验。
实现名词只在有助于理解时出现。明确区分本地保存、Server 同步和共享发布；分别检查 Project 角色与组织角色；说明检索结果是片段还是全文。
计划中的行为要标为计划。性能证据写清环境与日期。静态源码核对不能表述成已经完成 App 实测，也不能引用不存在的图片或其他素材。
以初次读者的身份验收
审核者应能从相应页面回答：
| 读者 | 验收问题 |
|---|---|
| 团队成员 | 从哪里开始？哪些东西需要事先存在？选择是否会复制文档？Codex 何时可以提出修改？谁负责发布，怎样确认结果？ |
| 技术读者 | App、daemon、Server 各负责什么？内容与提案由哪些对象表示？发布时哪个版本发生变化？过程中哪些环节可能失败？ |
| 集成开发者或维护者 | 应使用哪个接口？权限与版本前提是什么？错误、恢复规则、实现与测试在哪里？ |
还要检查：必要的陌生术语是否已经解释或链接，示例是否跨页一致，下一步入口是否回答读者自然产生的问题。
提交前检查
先审核事实与阅读路线，再运行相关的现有检查：
bun install --frozen-lockfile
bun run build
bun dev/check-docs-search.mjs涉及 HTTP 路由变化时，还应执行：
cargo test -p server --lib axum_routes_match_public_and_admin_openapi核对内部链接、章节锚点、中英文对应页、示例请求和引用素材；根据变更的事实选择相关行为测试。站点构建通过只表示页面可以生成，不代表操作说明或接口行为一定正确。
发布到文档站
VitePress 源文件在 docs/，静态素材在 docs/public/，构建产物在 docs/.vitepress/dist/。发布流程以仓库的 Site Delivery 工作流为准。交付说明应区分本地预览、部署完成和线上已验证。
结构参考与采用方式
- Diátaxis区分学习、完成工作、理解原理和查阅信息四种需求。上面的页面职责参考了其教程、任务指南、解释与参考说明。
- Kubernetes 文档把 Concepts、Tasks、Tutorials 和 Reference 分设入口。Clumsies 同样让概念解释和接口契约可以独立阅读。
- Docker Get started先区分安装与按目标选择教程。Clumsies 把安装、登录放在五步练习之前。
- GitHub Get started同时提供 quickstart、overview 和具体主题入口。Clumsies 据此区分首次操作、理解项目和查找任务的路线。
这些来源提供组织方法；Clumsies 的示例、权限、操作和保证，仍须依据本项目的当前行为。