项目维护的说明文档统一归入 docs/，公开完整的当前实现架构；内部设计讨论、研究、需求、问题和运行证据归入 docs/private/。总导航见 README。
目录与职责
| 位置 | 内容 | 发布范围 |
|---|---|---|
ARCHITECTURE.md、architecture/ | 当前功能、服务边界、消息流程、生命周期与数据架构 | 公开 |
getting-started/、guides/ | 安装、配置、功能使用与接入 | 公开 |
reference/ | API、协议、配置与支持范围 | 公开 |
deployment/ | 通用部署、升级与排错 | 公开 |
product/、demos/ | 公开产品说明与示例 | 公开 |
adr/ | 原有编号决策记录，保持原位 | 维持原发布范围 |
private/requirements/ | PRD、需求、验收条件 | 私有 |
private/research/ | 外部产品、框架、模型与供应商研究 | 私有 |
private/design/ | 内部产品和技术方案讨论 | 私有 |
private/experiments/ | 假设、对照实验、参数与可复现实验记录 | 私有 |
private/issues/ | 问题、故障、原因、修复和关闭证据 | 私有 |
private/reports/ | 测试、回归、性能、安全和审查报告 | 私有 |
private/evidence/ | 新增原始日志、截图、音频、指标及证据清单 | 私有 |
private/archive/ | 已被替代的历史材料与停止使用的技能产物 | 私有 |
private/templates/ | 实验、测试报告、问题报告模板 | 私有 |
private/organization/ | 文档盘点、迁移映射和校验结果 | 私有 |
当前公开专题文档保留已有路径，避免破坏 ADR、技能引用和公开链接；通过总导航按用途分类。新架构详解进入 architecture/，不再扩张根目录的专题文件。现有源码、部署、素材目录中的就地 README 是入口或资源说明，详细项目说明应写入 docs/ 并由入口链接。
技能与运行资源的例外
根目录 CONTEXT.md 是技能约定的术语表；docs/adr/ 是决策记录。两者不移动、不重编号、不批量重写。skills/ 中的技能说明、config/personas/ 中的运行时人设及第三方依赖自带说明按各自的加载约定保留，不能作为普通项目文档搬迁。根目录 README、LICENSE、贡献和安全入口保留平台约定位置。
docs/specs/ 原两篇文档未找到可验证的生成技能记录，现归入私有设计区，不能仅凭目录名称判定是 Superpowers 产物或已废弃。明确引用 Superpowers 工作流的原 docs/superpowers/ 整体归档。
命名、状态与维护
- 新工作记录采用
YYYY-MM-DD-主题.md；原文件名、ADR 编号和已发布路由不批量更名。 - 每篇新增内部文档标注类型、状态、日期、负责人或维护方、适用版本、关联需求/问题和证据。没有负责人时写“待分配”，不得虚构。
- 状态按文档类型区分：方案为草案/已接受/已替代，实验为计划/进行中/已完成，问题为待确认/已复现/修复中/待回归/已关闭。
- 当前能力必须与装配代码一致；目标设计、实验分支、条件可用功能和历史实现分别标识。日期不代替代码核查。
- 修复关闭需链接回归结果；测试报告列明失败、跳过和未覆盖项；实验记录保留不支持假设的结果。
- 既有日期报告与其附件作为完整证据包保留，不为目录美观拆散相对引用。新证据统一存
private/evidence/日期-主题/，由报告引用。 - 归档保留内容、来源与迁移清单；不把整个历史归档重新表述为当前有效设计。
发布边界
docs/private/ 同时从 Git 和 Docker 构建上下文排除；历史 docs-private/ 等忽略规则保留，防止旧路径重新生成时泄漏。私有资料需要独立受控备份，开源仓库不承担备份。
前端 /docs 只发布 apps/web/lib/public-documents.ts 的显式白名单。scripts/build-public-documents.mjs 生成文章数据；Markdown 图片与附件也遵循相同边界。文档源位于 docs/ 不代表可以发布，禁止扫描整个目录自动发布，禁止将私有路径软链到 public/。
Git 仓库和前端站点是两个发布面。下架页面不能删除已提交正文；.gitignore 不会取消已有跟踪，也不能撤回 Git 历史或线上旧版。迁移未自动提交、推送或部署。
更新后检查源文件存在、文档链接、公开白名单、私有路径解析、Git/Docker 排除、生成文章数据，以及架构图与正文的一致性。