docs: add cross-repo roadmap and centralize doc conventions

- docs/ROADMAP.md: decompose enhancement work into sub-projects P0-P8
  (ops foundation -> product value -> governance) with ordering rationale
- docs/CHANGELOG.md: start the wrapper changelog
- AGENTS.md: monorepo wrapper role, master-direct commits scoped to the
  wrapper, all specs/plans live in this repo's docs/ from now on

AGENTS.md

@@ -2,13 +2,13 @@
 
 ## Repository role
 
-Docker Compose orchestration for the crearte full stack. Three repos must stay siblings:
+Monorepo wrapper for the crearte full stack. This repo tracks `AGENTS.md`, `clone_all.sh`, and `docs/` (roadmap and all cross-repo design/plan docs). The three product repos are nested clones, each with its own git history and `AGENTS.md`:
 
 ```
-repos/
+crearte-monorepo/     # this repo (wrapper)
 ├── crearte/          # frontend (build context for web-* images)
 ├── crearte-server/   # backend Go API (build context for api-* images)
-└── crearte-deploy/   # this repo — compose only, no app code
+└── crearte-deploy/   # compose orchestration, no app code
 ```
 
 Everything runs in containers. Do not introduce host-run workflows (no `npm run dev` / `go run` on the host) in docs, scripts, or compose.
@@ -16,9 +16,9 @@ Everything runs in containers. Do not introduce host-run workflows (no `npm run
 ## Safety Rules
 
 - Branch naming: `{feat|fix|docs|chore}/{branch-name}` (e.g. `fix/compose-port-clash`).
-- Before `git commit`: run `git branch --show-current`. If on `master`, do NOT commit — ask the user for a branch name, create it, and commit there.
+- Commits in this monorepo wrapper may go directly on `master` (user-approved 2026-09-29). In the inner repos (`crearte/`, `crearte-server/`, `crearte-deploy/`): before `git commit`, run `git branch --show-current`. If on `master`, do NOT commit — ask the user for a branch name, create it, and commit there.
 - `.env` is gitignored and must stay that way. Never commit secrets. Any new secret must land in `.env.example` as an empty placeholder (with a comment) in the same commit that introduces it.
-- Changes → `docs/CHANGELOG.md` (this repo is not under `web/`, so `CHANGELOG_webui.md` never applies). Higher versions on top.
+- Changes → `docs/CHANGELOG.md` of the repo being changed (this wrapper's `docs/CHANGELOG.md`, or an inner repo's `docs/CHANGELOG.md` for its own changes). This workspace is not under `web/`, so `CHANGELOG_webui.md` never applies. Higher versions on top.
 - CHANGELOG entry format: same entry has English line then Chinese line on consecutive lines (no blank line between them); different entries are separated by a blank line.
 - Merging into `master`: always create a merge commit — `git merge --no-ff <branch>` (never fast-forward, the integration point must be recorded). Delete the merged branch afterwards.
 - Compose changes that alter usage must update `README.md` in the same commit.
@@ -41,8 +41,12 @@ Everything runs in containers. Do not introduce host-run workflows (no `npm run
 3. Smoke-test the affected path (e.g. `docker compose exec api-dev wget -qO- http://127.0.0.1:8080/healthz`, or the upload flow through http://localhost:8080).
 4. Tear down with plain `down` (never `-v`) unless the task is specifically about destroying data.
 
+## Documentation
+
+- All specs, implementation plans, roadmaps, and cross-repo coordination docs live in this wrapper's `docs/` (`docs/ROADMAP.md`, `docs/specs/`, `docs/plans/`). Do not scatter them into the inner repos; their `docs/superpowers/` copies are legacy (in `crearte` that path is gitignored). This supersedes the crearte-deploy 0.3.0 "canonical home" convention.
+- Register every new spec/plan in the doc index table at the bottom of `docs/ROADMAP.md`.
+
 ## Layout notes
 
-- `docs/superpowers/` (plans/specs) is tracked in this repo — unlike in `crearte`, where it is gitignored.
 - No app code, no tests, no build scripts live here; those belong to `crearte` / `crearte-server`.
 

docs/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog / 更新日志
+
+All notable changes to this repository should be documented in this file.
+本仓库的重要变更建议统一记录在此文件中。
+
+The format loosely follows Keep a Changelog and can be adapted to the team's habits.
+本文档参考了 Keep a Changelog 的思路，也可以根据团队习惯调整。
+
+## [0.1.0] - 2026-09-29
+
+### Added / 新增
+
+- Added `docs/ROADMAP.md`: the cross-repo roadmap decomposed into sub-projects P0–P8 (ops foundation → product value → governance), with ordering rationale and a doc index for future specs and plans.
+- 新增 `docs/ROADMAP.md`：跨仓库路线图，分解为 P0–P8 子项目（上线底座 → 产品价值 → 治理长尾），含排序理由与后续 spec/计划的文档索引。
+
+### Changed / 变更
+
+- Doc convention: all specs, implementation plans and cross-repo coordination docs now live in the monorepo `docs/` instead of per-repo `docs/superpowers/`; this supersedes the crearte-deploy 0.3.0 "canonical home" convention. Commits in the monorepo wrapper may go directly to `master` (user-approved); the three inner repos keep their own branch rules.
+- 文档约定：所有 spec、实现计划与跨仓库协作文档统一收归 monorepo `docs/`，不再散落各内层仓库的 `docs/superpowers/`；此约定取代 crearte-deploy 0.3.0 的「canonical home」约定。monorepo wrapper 可直接提交 `master`（维护者确认），内层三仓仍遵循各自分支规范。

docs/ROADMAP.md

@@ -0,0 +1,53 @@
+# crearte 路线图 / Roadmap
+
+跨三个仓库（`crearte` 前端 / `crearte-server` 后端 / `crearte-deploy` 编排）的子项目路线图与索引，维护在 monorepo wrapper（本仓库）。
+
+- **版本 v0**：2026-09-29 与维护者确认的分解与顺序。
+- **现状基线**：crearte 0.13.0 / crearte-server 0.11.0 / crearte-deploy 0.3.1。
+
+## 分解原则
+
+- 按「依赖关系 + 是否阻塞上线」排序；每个子项目的规模控制在一份 spec 能装下。
+- 每个子项目独立走 **spec → 实现计划 → 实现 → 验证** 的循环。
+- 隐藏复杂度出现时升级路径（拆出新子项目），不硬塞进当前子项目。
+
+## 第一波：上线底座（运维 / 可靠性，顺序敏感）
+
+| # | 子项目 | 内容 | 涉及仓库 | 依赖 | 状态 |
+|---|--------|------|----------|------|------|
+| P0 | 已知缺陷清理 | ① CORS `Access-Control-Allow-Headers` 补 `If-None-Match`（解锁 e2e:stack Step5：revoke 410 + 降级）② 清理 compose 配置漂移（`BUNDLE_KEY_STORE` 环境变量、`bundle-keys-*` 卷——密钥自 server 0.6.0 起在 Postgres）③ `crearte-deploy` CHANGELOG 补账 | server, deploy | 无 | 进行中 |
+| P1 | prod 写侧可用 | prod 栈补对象存储（prod MinIO 或外部 S3）+ `api-prod` 配 `STORAGE_S3_*` / `GAMES_BASE_DOMAIN` / `CORS_ALLOWED_ORIGINS`；密码默认值、TLS 起步。现状：prod 无对象存储时写侧路由（上传/投稿/审核/预览）不注册，生产只读 | deploy（少量 server） | P0 | 待启动 |
+| P2 | CI + 测试基线 | 后端 / 部署仓建 CI（gofmt/vet/test + `TEST_DATABASE_URL` 集成层 + e2e:stack 全链路）；与前端已有 `validate.yml` 对齐。现状：后端/部署仓无 CI，Postgres 集成测试无 `TEST_DATABASE_URL` 时静默 skip | 三仓 | P0（e2e 依赖其修复） | 待启动 |
+| P3 | 备份 + 可观测 | `pg_dump` 定时备份 + MinIO 数据保护 + 恢复演练 runbook；结构化 / 请求日志 + `/metrics`；限流器单实例问题记录权衡 | server, deploy | P1（拓扑定型） | 待启动 |
+
+## 第二波：产品价值（可与第一波部分并行）
+
+| # | 子项目 | 内容 | 涉及仓库 | 依赖 | 状态 |
+|---|--------|------|----------|------|------|
+| P4 | 作者主页 | `/users/:user` 聚合页（该作者全部作品），API 列表按作者过滤；顺带 `/games/:user/:slug` 面包屑与作者名互链 | 三仓（API 过滤 + 前端页面） | 无强依赖，可提前并行 | 待启动 |
+| P5 | 收藏 / 评分 | 新数据表 + 用户态 API + 目录/详情页 UI；产品线里最大的一块 | 三仓 | 建议 P2 先落地 | 待启动 |
+| P6 | hosted 作品投稿 | 范围模糊，需先定义 hosted 托管语义（只存 URL 还是真托管文件），再定投稿/审核流 | 三仓 | 需先决策 | 待澄清 |
+
+## 第三波：治理与长尾（随时可插队）
+
+| # | 子项目 | 内容 | 状态 |
+|---|--------|------|------|
+| P7 | 管理后台增强 | 用户列表 / 角色管理 UI（替代 CLI `user set-role`）+ 审计日志 | 待启动 |
+| P8 | 长尾打包 | 权限开关 UI 全量（`inlineStyle/wasm/coop/fullscreen/gamepad`）、后端 triage 小项（`games.Detail` 400 细分、admin 路由 slug 校验、approve 同名竞态测试）、账号注销、静态兜底目录、CHANGELOG 模板文案 | 待启动 |
+
+## 排序理由
+
+- **P0 最先**：几十行的修复，却解锁整条 e2e 回归链路——后面每一波都靠它做验证保障。
+- **P1 紧随**：不做则生产环境投稿 / 审核根本不可用，产品功能再丰富也上不了线。
+- **P4 可提前**：无依赖且范围清晰，若想先看到用户可感知的产品变化，可与第一波并行。
+
+## 文档与提交约定
+
+- 所有 spec / 实现计划 / 跨仓库协作文档统一放在本仓库 `docs/`（`docs/specs/`、`docs/plans/`、`docs/ROADMAP.md`），并在下表登记；内层仓库只保留各自的 `docs/CHANGELOG.md` 与 `docs/README.md`。此约定取代 crearte-deploy 0.3.0 确立的「crearte-deploy 为跨仓库文档 canonical home」。
+- monorepo（本仓库）可直接在 `master` 提交；内层三仓仍遵循各自 `AGENTS.md` 的分支与合并规范。
+
+## 子项目文档索引
+
+| 子项目 | spec | 实现计划 |
+|--------|------|----------|
+| （待补） | | |