diff --git a/cocoscreator_projects/scripts/README.md b/cocoscreator_projects/scripts/README.md
new file mode 100644
index 0000000..fce472f
--- /dev/null
+++ b/cocoscreator_projects/scripts/README.md
@@ -0,0 +1,24 @@
+# Monorepo 工具链
+
+所有命令在 `cocoscreator_projects/` 下用 `npm run <script>` 执行。
+
+| 命令 | 作用 |
+|------|------|
+| `npm run new-game <name>` | 从 `templates/game-seed` 克隆一个子游戏工程到 `games/<name>`，重置身份、铺 `game/` 骨架、挂 framework junction |
+| `npm run setup-links` | 为 `games/*` 重建 `assets/framework` junction（clone 仓库后必跑一次） |
+| `npm run check-cocos` | 校验所有子游戏工程的 `creator.version` 与宿主 `YouleNexus` 一致（不一致退出码 1） |
+| `npm run bump-cocos <version>` | 批量改宿主+所有子游戏的 `creator.version`（之后仍需逐个用编辑器打开迁移） |
+| `npm test` | 运行工具链全部单元测试 |
+
+## 关键约束
+- **framework 真源**唯一存放于 `YouleNexus/assets/framework`；各子游戏的 `assets/framework` 是指向它的 junction（不入库，见根 `.gitignore`）。clone 后跑 `setup-links` 重建。
+- **Cocos 版本必须全 monorepo 统一**（junction 共享同一份资源，跨版本不兼容）。升级走 `bump-cocos` + 逐工程编辑器迁移，详见 spec §8。
+- 子游戏私有内容只放 `games/<name>/assets/game/`；协议一律引用 `docs/protocol/`（spec §0.1）。
+
+## ⚠️ 删除子游戏工程的注意事项
+子游戏的 `assets/framework` 是指向框架真源的 junction。**不要用 `rm -rf` 删除整个子游戏工程**——git-bash 的 `rm -rf` 可能穿透 junction 误删框架真源。请用 Node 安全删除（对 junction 不穿透）：
+
+```bash
+node -e "require('fs').rmSync('games/<name>', { recursive: true, force: true })"
+```
+或先单独移除 junction（`rmdir games/<name>/assets/framework`）再删工程目录。