这里按“文档的用途”而不是按代码目录组织。代码与测试始终是行为事实的最高 来源；本文档树负责解释当前设计、历史决策和专项证据。
- 先读根目录 README，了解产品解决什么问题以及如何运行。
- 再读 架构总览，建立系统、上下文和代码目录的全景。
- 按任务选择 后端架构、 前端架构 或 关键运行流程。
- 修改协议或持久化前，阅读 契约与数据。
- 准备提交前，按 构建与测试 选择验证边界。
- 准备 npm 公开发布时，按 npm 运行时包发布 完成发布门槛与 GitHub/npm 配置。
| 目录 | 内容 | 权威性与维护方式 |
|---|---|---|
architecture/ |
当前系统如何工作 | 与代码同步；只写已经实现的架构 |
adr/ |
已接受的长期决策及其理由 | 历史记录；改变决策时新增“取代”记录 |
design/ |
复杂机制的实现级设计 | 以当前实现为基线，算法变化时更新 |
research/ |
外部项目或方案评估 | 参考材料，不定义 Termestra 产品行为 |
governance/ |
带日期的许可与治理证据，例如公开资产整改记录 | 快照材料，不替代法律意见或当前代码 |
product/ |
已交付能力和发布缺口 | 产品状态，完成或改变范围时更新 |
release/ |
npm 包发布、验证和运维步骤 | 与实际发布工作流、npm 元数据同步 |
根目录 上下文地图 描述后端业务能力的所有权和依赖关系；
每个链接的 CONTEXT.md 只定义该上下文的领域词汇，不记录框架、表结构或实现
细节。
- 当前架构文档必须能反向导航到实际包、入口、端口、迁移或测试。
- 公共协议使用代码中的 wire 名称，例如
snake_case字段和状态值。 - 已接受的 ADR 不通过改写历史来追认新设计；用新的 ADR 明确取代关系。
- 日期型审查在标题处标出快照日期，避免被误读为持续保证。
- 移动文档时同步修改 README、分发打包清单和校验脚本。