From c659cc0321d66a36d5df51afc906a1ebeeefb446 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Wed, 22 Jul 2026 04:23:22 +0000
Subject: [PATCH] docs: add migration guide for 0.7
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Covers the cac peer-dependency move and the createCli → createCac rename, the one breaking change between 0.6.x and 0.7.0.
---
 docs/.vitepress/config.ts   |  1 +
 docs/guide/migration-0.7.md | 45 +++++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)
 create mode 100644 docs/guide/migration-0.7.md

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 0580692..0c63445 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -132,6 +132,7 @@ export function devframeNav(prefix = ''): DefaultTheme.NavItem[] {
         { text: 'Contributing', link: `${repo}/blob/main/CONTRIBUTING.md` },
         {
           items: [
+            { text: 'Migrating to 0.7', link: `${prefix}/guide/migration-0.7` },
             { text: 'Migrating to 0.6', link: `${prefix}/guide/migration-0.6` },
           ],
         },
diff --git a/docs/guide/migration-0.7.md b/docs/guide/migration-0.7.md
new file mode 100644
index 0000000..6f7d5e7
--- /dev/null
+++ b/docs/guide/migration-0.7.md
@@ -0,0 +1,45 @@
+---
+outline: deep
+---
+
+# Migrating to 0.7
+
+0.7's one breaking change moves the `cac` CLI framework out of `devframe`'s bundled dependencies and renames the adapter that wraps it. This page covers the change between 0.6.x and 0.7.
+
+## `cac` is now an optional peer dependency
+
+`devframe` no longer depends on [`cac`](https://github.com/cacjs/cac) directly — it moved to an optional `peerDependency`. Any project that calls into the CLI adapter (formerly `createCli`, now `createCac`) needs to install `cac` itself:
+
+```sh
+npm install devframe cac
+```
+
+Tools that don't use the CLI adapter — a Vite-hosted plugin, an embedded devframe, anything built from the [lower-level factories](./standalone-cli#use-your-own-cli-framework) — are unaffected and never need `cac` installed.
+
+## `devframe/adapters/cli` → `devframe/adapters/cac`
+
+The adapter itself is renamed, and its factory with it:
+
+| 0.6.x | 0.7 |
+|-------|-----|
+| `import { createCli } from 'devframe/adapters/cli'` | `import { createCac } from 'devframe/adapters/cac'` |
+| `CreateCliOptions` | `CreateCacOptions` |
+| `CliHandle` | `CacHandle` |
+
+```ts
+// 0.6.x
+import { createCli } from 'devframe/adapters/cli'
+
+await createCli(devframe).parse()
+```
+
+```ts
+// 0.7
+import { createCac } from 'devframe/adapters/cac'
+
+await createCac(devframe).parse()
+```
+
+`devframe/adapters/cli` still exports `createCli` as a deprecated alias of `createCac` (same for `CreateCliOptions` and `CliHandle`), so existing imports keep compiling — but the underlying `cac` peer dependency still needs installing per above, and the alias will be removed in a future major release. Move call sites over now rather than waiting for that removal.
+
+See [CLI (cac)](/adapters/cac) for the full adapter reference.