diff --git a/docs/.vitepress/sidebar.en.ts b/docs/.vitepress/sidebar.en.ts
index b4d3ebd4..2a2d81da 100644
--- a/docs/.vitepress/sidebar.en.ts
+++ b/docs/.vitepress/sidebar.en.ts
@@ -8,6 +8,7 @@ export default {
         { text: 'First Build', link: '/en/guide/first-build' },
         { text: 'PHP SAPI Reference', link: '/en/guide/sapi-reference' },
         { text: 'CLI Reference', link: '/en/guide/cli-reference' },
+        { text: 'Migrating from v2', link: '/en/guide/migrate-from-v2' },
       ],
     },
     {
diff --git a/docs/.vitepress/sidebar.zh.ts b/docs/.vitepress/sidebar.zh.ts
index f6ba09ef..07872db9 100644
--- a/docs/.vitepress/sidebar.zh.ts
+++ b/docs/.vitepress/sidebar.zh.ts
@@ -8,6 +8,7 @@ export default {
         { text: '第一次构建', link: '/zh/guide/first-build' },
         { text: 'PHP SAPI 构建参考', link: '/zh/guide/sapi-reference' },
         { text: '命令行参考', link: '/zh/guide/cli-reference' },
+        { text: '从 v2 迁移', link: '/zh/guide/migrate-from-v2' },
       ],
     },
     {
diff --git a/docs/en/guide/migrate-from-v2.md b/docs/en/guide/migrate-from-v2.md
new file mode 100644
index 00000000..54bfa163
--- /dev/null
+++ b/docs/en/guide/migrate-from-v2.md
@@ -0,0 +1,210 @@
+# Migrating from v2
+
+StaticPHP v3 is a ground-up rewrite. The core build workflow (`download → build → combine`) remains familiar, but several commands, options, and configuration fields have changed. This page covers everything you need to update before switching.
+
+::: info Scope
+This guide only covers user-facing CLI commands, options, `craft.yml` fields, and `env.ini` variable names. Internal PHP APIs are not covered.
+:::
+
+## Documentation URL Change
+
+The official documentation site has moved:
+
+- **v3 docs (current)**: [https://static-php.dev](https://static-php.dev) — the main site now hosts v3 documentation.
+- **v2 docs (archived)**: [https://static-php.github.io/v2-docs/](https://static-php.github.io/v2-docs/) — v2 documentation is preserved here for reference.
+
+Update any bookmarks or internal links accordingly.
+
+## `spc` Binary Download URL Change
+
+The nightly `spc` self-contained binary has moved to a new path:
+
+| | URL |
+|---|---|
+| **v2** | `https://dl.static-php.dev/static-php-cli/spc-bin/nightly/` |
+| **v3** | `https://dl.static-php.dev/v3/spc-bin/nightly/` |
+
+Update any CI scripts or bootstrap commands that download the `spc` binary directly. For example:
+
+```bash
+# v2
+curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
+
+# v3
+curl -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64
+```
+
+## Removed Commands
+
+| v2 Command | v3 Replacement | Notes |
+|---|---|---|
+| `del-download` | `spc reset` | `reset` also accepts `--with-pkgroot` and `--with-download` for finer control |
+| `del-download --all` | `spc reset --with-download` | Removes the downloads cache directory |
+
+## Removed Options
+
+### `--with-added-patch` / `-P` (build command)
+
+This option allowed injecting external PHP patch scripts at specific build stages. **It has been removed in v3.**
+
+There is no direct drop-in replacement. If you relied on this feature:
+
+- Consider contributing your patches upstream to the StaticPHP repository.
+- For project-specific patches, use a custom registry with a package class. See [Writing Package Classes](/en/develop/extending/package-classes) for details.
+
+::: tip Future Plans
+A single-file hook API for lightweight patches may be provided in a future release.
+:::
+
+### Windows-only: `--with-sdk-binary-dir` and `--vs-ver`
+
+These options are no longer accepted on the command line. Instead, set the `PHP_SDK_PATH` environment variable to point to your PHP SDK binary tools directory. The Visual Studio version is now managed by the toolchain configuration.
+
+## Renamed / Deprecated Options
+
+The following options have been renamed. The old names are accepted where noted, but you should update your scripts.
+
+| v2 Option | v3 Option | Status |
+|---|---|---|
+| `--prefer-pre-built` | `--prefer-binary` / `-p` | Old name kept as a deprecated alias |
+| `--with-libs=<list>` | `--with-packages=<list>` | — |
+| `--with-suggested-libs` / `-L` | `--with-suggests` | Old `-L` / `-E` flags removed |
+| `--with-suggested-exts` / `-E` | `--with-suggests` | Merged into a single flag |
+
+### Example
+
+```bash
+# v2
+spc build curl,gd --build-cli --with-libs="openssl" -L -E
+
+# v3
+spc build curl,gd --build-cli --with-packages="openssl" --with-suggests
+```
+
+## Changed `build` Command Behaviour
+
+The `build` command (alias: `build:php`) still works. However, v3 also provides **dedicated single-target commands** that do not require SAPI selection flags:
+
+| v2 | v3 Equivalent |
+|---|---|
+| `spc build exts --build-cli` | `spc build:php-cli exts` |
+| `spc build exts --build-fpm` | `spc build:php-fpm exts` |
+| `spc build exts --build-cgi` | `spc build:php-cgi exts` |
+| `spc build exts --build-micro` | `spc build:php-micro exts` |
+| `spc build exts --build-embed` | `spc build:php-embed exts` |
+| `spc build exts --build-frankenphp` | `spc build:frankenphp exts` |
+
+Use `build:php` when you need to build multiple SAPIs in one pass (the `--build-*` flags remain valid there).
+
+### Automatic Download in Build Commands
+
+In v3, all `build:*` commands automatically download any missing dependencies before building. You no longer need to run `spc download` as a separate step:
+
+```bash
+# v2 — two steps required
+spc download --for-extensions=curl,gd
+spc build curl,gd --build-cli
+
+# v3 — one step is enough
+spc build:php-cli curl,gd
+```
+
+To opt out of the automatic download (for example in CI where sources are pre-cached), pass `--no-download`:
+
+```bash
+spc build:php-cli curl,gd --no-download
+```
+
+## Changed `download` Command Options
+
+| v2 | v3 | Notes |
+|---|---|---|
+| `--prefer-pre-built` | `--prefer-binary` / `-p` | Deprecated alias kept |
+| `--with-libs` | `--for-libs` | Separate from packages |
+| *(no equivalent)* | `--for-packages` | Unified package filter |
+| *(no equivalent)* | `--parallel` / `-P` | Parallel downloads |
+| *(no equivalent)* | `--retry` / `-R` | Retry on failure |
+
+## Removed Dev Commands
+
+These development utility commands have been removed or consolidated:
+
+| v2 Command | v3 Replacement |
+|---|---|
+| `dev:extensions` / `list-ext` | `spc dev:info <package>` |
+| `dev:ext-version` / `dev:ext-ver` | `spc dev:info <package>` |
+| `dev:lib-version` / `dev:lib-ver` | `spc dev:info <package>` |
+| `dev:php-version` / `dev:php-ver` | `spc dev:info php-src` |
+| `dev:gen-ext-dep-docs` + `dev:gen-lib-dep-docs` | `spc dev:gen-deps-data` |
+
+## Renamed Dev Commands
+
+| v2 | v3 | Notes |
+|---|---|---|
+| `dev:sort-config` / `sort-config` | `dev:lint-config` | Old alias still accepted |
+
+## New Commands in v3
+
+These commands are new in v3 with no v2 equivalent:
+
+| Command | Description |
+|---|---|
+| `spc reset` | Clean `buildroot/` and `source/` directories |
+| `spc check-update` | Check for newer artifact versions |
+| `spc build:php-cli` | Build CLI SAPI (no flags needed) |
+| `spc build:php-fpm` | Build PHP-FPM (no flags needed) |
+| `spc build:php-cgi` | Build PHP CGI (no flags needed) |
+| `spc build:php-micro` | Build phpmicro (no flags needed) |
+| `spc build:php-embed` | Build embed SAPI (no flags needed) |
+| `spc build:frankenphp` | Build FrankenPHP (no flags needed) |
+| `spc dev:shell` | Interactive shell with build environment |
+| `spc dev:is-installed` | Check whether a package is installed |
+| `spc dev:dump-stages` | Dump all package build stages to JSON |
+| `spc dev:dump-capabilities` | Dump buildable/installable capabilities |
+| `spc dev:info` | Show configuration info for a package |
+
+## `craft.yml` Changes
+
+### Removed: `build-options.with-added-patch`
+
+The `with-added-patch` key inside `build-options` is no longer parsed and will be silently ignored. Remove it from your `craft.yml`:
+
+```yaml
+# v2 — remove this block
+build-options:
+  with-added-patch:
+    - my-patch.php
+```
+
+### `libs` → `packages` (both work)
+
+The top-level `libs` field still works. The preferred v3 field name is `packages`, which is a superset covering libraries and other tool packages:
+
+```yaml
+# v2
+libs: nghttp2,liblz4
+
+# v3 (preferred)
+packages: nghttp2,liblz4
+```
+
+## `env.ini` Variable Renames
+
+If you customise `config/env.ini` or export environment variables in CI, update the following names:
+
+| v2 Variable | v3 Variable |
+|---|---|
+| `SPC_LINUX_DEFAULT_CC` | `SPC_DEFAULT_CC` |
+| `SPC_LINUX_DEFAULT_CXX` | `SPC_DEFAULT_CXX` |
+| `SPC_LINUX_DEFAULT_AR` | `SPC_DEFAULT_AR` |
+| `SPC_LINUX_DEFAULT_LD` | `SPC_DEFAULT_LD` |
+| `SPC_LIBC` | `SPC_TARGET` |
+
+`SPC_TARGET` uses a new format that encodes both architecture and libc in a single string, for example:
+
+| v2 | v3 |
+|---|---|
+| `SPC_LIBC=musl` | `SPC_TARGET=x86_64-linux-musl` |
+| `SPC_LIBC=gnu` | `SPC_TARGET=x86_64-linux-gnu.2.17` |
+
+New logging variables were also added (`SPC_ENABLE_LOG_FILE`, `SPC_LOGS_DIR`, `SPC_PRESERVE_LOGS`). Refer to [Environment Variables](/en/guide/env-vars) for details.
diff --git a/docs/zh/guide/migrate-from-v2.md b/docs/zh/guide/migrate-from-v2.md
new file mode 100644
index 00000000..81297acf
--- /dev/null
+++ b/docs/zh/guide/migrate-from-v2.md
@@ -0,0 +1,210 @@
+# 从 v2 迁移
+
+StaticPHP v3 是一次完整的重写。核心构建流程（`download → build → combine`）保持不变，但部分命令、选项和配置字段已发生变化。本页列出了切换前所有需要更新的内容。
+
+::: info 范围说明
+本指南仅涵盖面向用户的 CLI 命令、选项、`craft.yml` 字段和 `env.ini` 变量名称。不涵盖内部 PHP API。
+:::
+
+## 文档地址变更
+
+官方文档站点已迁移：
+
+- **v3 文档（当前）**：[https://static-php.dev](https://static-php.dev) — 主站现在托管 v3 文档。
+- **v2 文档（归档）**：[https://static-php.github.io/v2-docs/](https://static-php.github.io/v2-docs/) — v2 文档已归档保留，供参考。
+
+请更新你保存的书签或内部链接。
+
+## `spc` 二进制下载地址变更
+
+nightly `spc` 自包含二进制文件已迁移到新路径：
+
+| | 地址 |
+|---|---|
+| **v2** | `https://dl.static-php.dev/static-php-cli/spc-bin/nightly/` |
+| **v3** | `https://dl.static-php.dev/v3/spc-bin/nightly/` |
+
+请更新所有直接下载 `spc` 二进制的 CI 脚本或初始化命令，例如：
+
+```bash
+# v2
+curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
+
+# v3
+curl -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64
+```
+
+## 已移除的命令
+
+| v2 命令 | v3 替代方案 | 说明 |
+|---|---|---|
+| `del-download` | `spc reset` | `reset` 支持 `--with-pkgroot` 和 `--with-download` 以进行更细粒度的控制 |
+| `del-download --all` | `spc reset --with-download` | 删除下载缓存目录 |
+
+## 已移除的选项
+
+### `--with-added-patch` / `-P`（build 命令）
+
+该选项允许在特定构建阶段注入外部 PHP patch 脚本。**v3 已完全移除此功能。**
+
+目前没有直接的替代方案。如果你依赖此功能，请考虑以下方式：
+
+- 将你的 patch 贡献到 StaticPHP 的上游仓库。
+- 对于项目专用的 patch，可以使用自定义 registry 并编写 Package 类。详情参见[编写 Package 类](/zh/develop/extending/package-classes)。
+
+::: tip 未来计划
+未来版本可能会提供用于轻量级 patch 的单文件 hook API。
+:::
+
+### Windows 专有：`--with-sdk-binary-dir` 和 `--vs-ver`
+
+这两个选项已不再被命令行接受。请改为设置 `PHP_SDK_PATH` 环境变量，指向你的 PHP SDK binary tools 目录。Visual Studio 版本现在由工具链配置统一管理。
+
+## 已重命名 / 已弃用的选项
+
+以下选项已重命名。部分旧名称仍作为弃用别名被接受，但建议尽快更新脚本。
+
+| v2 选项 | v3 选项 | 状态 |
+|---|---|---|
+| `--prefer-pre-built` | `--prefer-binary` / `-p` | 旧名称保留为弃用别名 |
+| `--with-libs=<list>` | `--with-packages=<list>` | — |
+| `--with-suggested-libs` / `-L` | `--with-suggests` | 旧 `-L` / `-E` 已移除 |
+| `--with-suggested-exts` / `-E` | `--with-suggests` | 已合并为单一标志 |
+
+### 示例
+
+```bash
+# v2
+spc build curl,gd --build-cli --with-libs="openssl" -L -E
+
+# v3
+spc build curl,gd --build-cli --with-packages="openssl" --with-suggests
+```
+
+## `build` 命令行为变化
+
+`build` 命令（别名：`build:php`）仍然可用。但 v3 新增了**专用的单目标构建命令**，无需再传入 SAPI 选择标志：
+
+| v2 | v3 等价命令 |
+|---|---|
+| `spc build exts --build-cli` | `spc build:php-cli exts` |
+| `spc build exts --build-fpm` | `spc build:php-fpm exts` |
+| `spc build exts --build-cgi` | `spc build:php-cgi exts` |
+| `spc build exts --build-micro` | `spc build:php-micro exts` |
+| `spc build exts --build-embed` | `spc build:php-embed exts` |
+| `spc build exts --build-frankenphp` | `spc build:frankenphp exts` |
+
+如果需要在一次构建中同时编译多个 SAPI，请继续使用 `build:php`（`--build-*` 标志在该命令下仍然有效）。
+
+### 构建命令自动下载依赖
+
+v3 中，所有 `build:*` 命令在构建前会自动下载缺失的依赖包，不再需要单独执行 `spc download`：
+
+```bash
+# v2 — 需要两步
+spc download --for-extensions=curl,gd
+spc build curl,gd --build-cli
+
+# v3 — 一步即可
+spc build:php-cli curl,gd
+```
+
+如需跳过自动下载（例如在 CI 中源码已预先缓存），可传入 `--no-download`：
+
+```bash
+spc build:php-cli curl,gd --no-download
+```
+
+## `download` 命令选项变化
+
+| v2 | v3 | 说明 |
+|---|---|---|
+| `--prefer-pre-built` | `--prefer-binary` / `-p` | 弃用别名保留 |
+| `--with-libs` | `--for-libs` | 与包过滤分开 |
+| *（无等价）* | `--for-packages` | 统一包过滤器 |
+| *（无等价）* | `--parallel` / `-P` | 并行下载 |
+| *（无等价）* | `--retry` / `-R` | 失败重试 |
+
+## 已移除的 dev 命令
+
+以下开发辅助命令已被移除或合并：
+
+| v2 命令 | v3 替代方案 |
+|---|---|
+| `dev:extensions` / `list-ext` | `spc dev:info <package>` |
+| `dev:ext-version` / `dev:ext-ver` | `spc dev:info <package>` |
+| `dev:lib-version` / `dev:lib-ver` | `spc dev:info <package>` |
+| `dev:php-version` / `dev:php-ver` | `spc dev:info php-src` |
+| `dev:gen-ext-dep-docs` + `dev:gen-lib-dep-docs` | `spc dev:gen-deps-data` |
+
+## 已重命名的 dev 命令
+
+| v2 | v3 | 说明 |
+|---|---|---|
+| `dev:sort-config` / `sort-config` | `dev:lint-config` | 旧别名仍可用 |
+
+## v3 新增命令
+
+以下命令为 v3 新增，v2 中没有对应命令：
+
+| 命令 | 说明 |
+|---|---|
+| `spc reset` | 清理 `buildroot/` 和 `source/` 目录 |
+| `spc check-update` | 检查 artifact 的最新版本 |
+| `spc build:php-cli` | 构建 CLI SAPI（无需标志） |
+| `spc build:php-fpm` | 构建 PHP-FPM（无需标志） |
+| `spc build:php-cgi` | 构建 PHP CGI（无需标志） |
+| `spc build:php-micro` | 构建 phpmicro（无需标志） |
+| `spc build:php-embed` | 构建 embed SAPI（无需标志） |
+| `spc build:frankenphp` | 构建 FrankenPHP（无需标志） |
+| `spc dev:shell` | 进入带构建环境的交互式 shell |
+| `spc dev:is-installed` | 检查某个包是否已正确安装 |
+| `spc dev:dump-stages` | 将所有包的构建阶段导出为 JSON |
+| `spc dev:dump-capabilities` | 导出包的可构建/可安装能力 |
+| `spc dev:info` | 显示某个包的配置信息 |
+
+## `craft.yml` 变化
+
+### 已移除：`build-options.with-added-patch`
+
+`build-options` 下的 `with-added-patch` 键不再被解析，将被静默忽略。请从你的 `craft.yml` 中移除它：
+
+```yaml
+# v2 — 请删除此块
+build-options:
+  with-added-patch:
+    - my-patch.php
+```
+
+### `libs` → `packages`（两者均可用）
+
+顶层 `libs` 字段仍然有效。v3 中推荐使用 `packages`，它是 `libs` 的超集，还涵盖其他工具类包：
+
+```yaml
+# v2
+libs: nghttp2,liblz4
+
+# v3（推荐）
+packages: nghttp2,liblz4
+```
+
+## `env.ini` 变量重命名
+
+如果你在 `config/env.ini` 中进行了自定义，或在 CI 中导出了环境变量，请更新以下变量名：
+
+| v2 变量名 | v3 变量名 |
+|---|---|
+| `SPC_LINUX_DEFAULT_CC` | `SPC_DEFAULT_CC` |
+| `SPC_LINUX_DEFAULT_CXX` | `SPC_DEFAULT_CXX` |
+| `SPC_LINUX_DEFAULT_AR` | `SPC_DEFAULT_AR` |
+| `SPC_LINUX_DEFAULT_LD` | `SPC_DEFAULT_LD` |
+| `SPC_LIBC` | `SPC_TARGET` |
+
+`SPC_TARGET` 使用新的格式，将架构与 libc 编码在一个字符串中，例如：
+
+| v2 | v3 |
+|---|---|
+| `SPC_LIBC=musl` | `SPC_TARGET=x86_64-linux-musl` |
+| `SPC_LIBC=gnu` | `SPC_TARGET=x86_64-linux-gnu.2.17` |
+
+v3 还新增了若干日志相关变量（`SPC_ENABLE_LOG_FILE`、`SPC_LOGS_DIR`、`SPC_PRESERVE_LOGS`）。详情参见[环境变量](/zh/guide/env-vars)。