diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..67c95b2
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,39 @@
+# CHANGELOG
+
+## [Unreleased]
+
+### BREAKING CHANGES
+
+- **admin:stack:mode 命令全删**：list/use/apply/rollback/current 子命令全部移除（含 app 层和 extend/base/ 层）。下游执行 `php think admin:update` 同步上游代码后，这些命令将不再可用。
+
+### 新增
+
+- **B-route 多模式运行**：每个运行模式（default/docker-serve/docker-dev/full/author）独立目录，各自直接运行。业务代码始终一套，在仓库根目录。
+  - default 模式：根目录直接 `php think run`
+  - Docker 模式：`cd source/stack/<mode> && docker compose up -d`
+- **docker-dev compose profile**：原 docker-dev-sync 模式合并为 docker-dev 的 `sync` profile（Windows I/O 优化）。使用 `docker compose --profile sync up -d` 或设置 `COMPOSE_PROFILES=sync`。
+- 根 `.dockerignore`：合并各模式排除规则，排除 `source/stack/` 避免镜像臃肿。
+- `source/stack/stack.json` 简化为纯文档元数据（schema v2），加 category 分类。
+
+### 迁移指引
+
+**原 admin:stack:mode use 用户**：
+- 旧方式：`php think admin:stack:mode use docker-dev`
+- 新方式：`cd source/stack/docker-dev && docker compose up -d`
+- 切换回 default：停掉 Docker 容器，根目录 `php think run`
+
+**原 admin:stack:mode current 用户**：
+- 旧方式：运行命令查询当前模式
+- 新方式：检查根目录有无 Docker 文件（无 = default 模式）；查看 `source/stack/stack.json` 或 `source/stack/` 目录了解可用模式
+
+**原 admin:stack:mode list 用户**：
+- 旧方式：运行命令列模式
+- 新方式：查看 `source/stack/` 目录（`Get-ChildItem source\stack -Directory`）或读 `source/stack/stack.json`
+
+**原 docker-dev-sync 用户**：
+- 旧方式：`php think admin:stack:mode use docker-dev-sync`
+- 新方式：`cd source/stack/docker-dev && docker compose --profile sync up -d ulthon_admin_sync mysql redis phpmyadmin`
+- Windows 自动激活：在 PowerShell profile 加 `$env:COMPOSE_PROFILES = if ($env:OS -eq 'Windows_NT') { 'sync' } else { '' }`
+
+**原依赖 state file 的脚本**：
+- state file（runtime/agents/stack-current.json）已删除。判断模式改读根目录状态。