fix(migrate): document tsdown compatibility settings

.claude/skills/release-manager/SKILL.md

@@ -19,7 +19,7 @@ Run a standard vite-plus release from version bump to published announcement. An
 When given a release PR (URL or number), do not start from step 1. First audit the release's current state, then continue from the earliest unfinished step:
 
 - Is the binding version synced? (step 2: `grep -c "'<prev>'" packages/cli/binding/index.cjs` on the release branch)
-- Do the release version examples in `docs/guide/migrate.md`, including its Copy Prompt, match `packages/cli/package.json`? (step 2)
+- Do the release version examples in the migration guide and the setup, migration, and upgrade prompts match `packages/cli/package.json`? (step 2)
 - Is the PR description still the `prepare_release` boilerplate, or already a categorized changelog? (step 3)
 - Is a preview build present and for the current head? (step 4)
 - Does `main` have commits the release branch lacks? (`git log origin/release/vX.Y.Z..origin/main`, step 5)
@@ -33,7 +33,7 @@ Before post-release work, fetch `origin/main` and read its copy of this skill (`
 ## Pipeline overview
 
 1. `Prepare Release` workflow bumps versions and opens the release PR (`release/vX.Y.Z` -> `main`).
-2. Release manager: sync `binding/index.cjs` and the migration guide's release version, write the changelog PR description, offer the preview-build smoke test (recommend it when the release has more than 10 commits since the previous tag), get CI green.
+2. Release manager: sync `binding/index.cjs` and the release versions in the documentation and prompts, write the changelog PR description, offer the preview-build smoke test (recommend it when the release has more than 10 commits since the previous tag), get CI green.
 3. Merging the PR pushes a `packages/cli/package.json` change to `main`, which triggers `release.yml`: build, manual approval gate, npm publish, GitHub release, Docker image, Discord notification.
 4. Release manager: polish the GitHub release notes, verify installs, announce.
 
@@ -82,13 +82,18 @@ regenerate this file, so the CI build's regeneration step produces a
 diff that the post-build no-unexpected-changes guard rejects.
 ```
 
-### Migration guide
+### Documentation and prompts
 
-Use the version in the release branch's `packages/cli/package.json` as the target release version in `docs/guide/migrate.md`. Update the `--package=vite-plus@<curr>` pins in the pnpm and npm command examples, the `upgradePrompt` text used by Copy Prompt, and the surrounding prose that names that exact release. Keep an exact version; do not replace it with a major range or `latest`.
+Use the version in the release branch's `packages/cli/package.json` as the target release version in these files:
+
+- `docs/guide/migrate.md`: pnpm and npm migration command examples and matching release prose.
+- `docs/.vitepress/theme/data/migration-prompts.ts`: `setupPrompt`, `migrationPrompt`, `upgradePrompt`, and their shared instructions, including command examples and matching release prose. `CopyPrompt` uses `setupPrompt` on both the homepage and Getting Started guide.
+
+Update every `--package=vite-plus@<curr>` pin and the corresponding `For the <curr> release` and `Replace <curr>` text. Keep an exact version; do not replace it with a placeholder, a major range, or `latest`.
 
 Preserve historical versions such as the migration's source version and the release that introduced a breaking change. Leave Node.js requirements, bundled tool versions, and preview-registry instructions unchanged unless their requirements change.
 
-Commit the guide update on the release branch with the binding sync or in a separate release-version sync commit. Recheck both files after a target-version change or a merge from `main`. Before merging, confirm that the guide and Copy Prompt use the target release in both package-manager commands and their matching prose, then run `git diff --check`.
+Commit these updates on the release branch with the binding sync or in a separate release-version sync commit. Recheck both files and the binding after a target-version change or a merge from `main`. Before merging, confirm that the guide and all three prompts use the target release in both package-manager commands and their matching prose, then run `git diff --check`.
 
 Only these release-version sync commits go directly on the release branch. Everything else goes through `main` (see step 5).
 
@@ -352,7 +357,7 @@ Known release-branch-only failure modes:
 
 ## 6. Merge
 
-Merging the release PR is the release trigger. Before merging confirm: CI green, changelog validated, binding and migration guide versions synced, and (if used) the preview build verified.
+Merging the release PR is the release trigger. Before merging confirm: CI green, changelog validated, binding and documentation versions synced (including all three prompts), and (if used) the preview build verified.
 
 Auto-merge being enabled is not a completed merge. Confirm `mergedAt` and the merge commit, then follow the Release run for that commit; older successful runs can have skipped publishing because the version did not change.
 
@@ -503,7 +508,7 @@ After the release ships and announcements are approved or confirmed complete, re
 
 - [ ] `prepare_release` run for the target version; release PR open
 - [ ] `binding/index.cjs` synced on the release branch (step 2 commit message shape)
-- [ ] `docs/guide/migrate.md` command examples, Copy Prompt, and matching release prose use the exact target version from `packages/cli/package.json`
+- [ ] The migration guide and all three prompts in the step 2 files use the exact target version from `packages/cli/package.json` in their command examples and matching release prose
 - [ ] PR description written from the head branch data; every PR exactly once except documented omissions; breaking changes in their own section above Highlights; no em/en dashes; closing boilerplate intact
 - [ ] Dependency-upgrade PRs consolidated; vite-task bump expanded with upstream credits; security advisories linked
 - [ ] Smoke test offered to the release manager at both levels (local sweep and fork-PR CI), with the commit count stated and a recommendation to run it when that count is above 10; if accepted, forks synced to upstream first, preview build published, and the full ecosystem-ci catalog verified via `test-pkg-pr-new-migrate` (following TESTING.md), with every failure triaged and regressions ruled out against the previous release

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/create_missing_typecheck/snapshots/create_missing_typecheck.md

@@ -70,7 +70,12 @@ import { defineConfig } from "vite-plus";
 
 export default defineConfig({
   pack: {
-    deps: { resolveDepSubpath: true },
+    deps: {
+      // tsdown <0.23 compatibility: resolve external dependency subpaths.
+      // Remove to preserve subpath imports as written (the new default).
+      // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+      resolveDepSubpath: true,
+    },
     dts: {
       generator: "tsgo",
     },

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_from_tsdown/snapshots/migration_from_tsdown.md

@@ -28,7 +28,11 @@ export default defineConfig({
   dts: true,
   unbundle: true,
   copy: 'public',
-  deps: { resolveDepSubpath: true, onlyBundle: false },
+  deps: {
+    // tsdown <0.23 compatibility: resolve external dependency subpaths.
+    // Remove to preserve subpath imports as written (the new default).
+    // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+    resolveDepSubpath: true, onlyBundle: false },
 });
 ```
 
@@ -119,7 +123,11 @@ export default defineConfig({
   dts: true,
   unbundle: true,
   copy: 'public',
-  deps: { resolveDepSubpath: true, onlyBundle: false },
+  deps: {
+    // tsdown <0.23 compatibility: resolve external dependency subpaths.
+    // Remove to preserve subpath imports as written (the new default).
+    // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+    resolveDepSubpath: true, onlyBundle: false },
 });
 ```
 

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_from_tsdown/snapshots/migration_from_tsdown_tsgo.md

@@ -31,7 +31,11 @@ export default defineConfig({
   dts: { generator: 'tsgo' },
   unbundle: true,
   copy: 'public',
-  deps: { resolveDepSubpath: true, onlyBundle: false },
+  deps: {
+    // tsdown <0.23 compatibility: resolve external dependency subpaths.
+    // Remove to preserve subpath imports as written (the new default).
+    // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+    resolveDepSubpath: true, onlyBundle: false },
 });
 ```
 
@@ -57,6 +61,10 @@ export default defineConfig({
   dts: { generator: 'tsgo' },
   unbundle: true,
   copy: 'public',
-  deps: { resolveDepSubpath: true, onlyBundle: false },
+  deps: {
+    // tsdown <0.23 compatibility: resolve external dependency subpaths.
+    // Remove to preserve subpath imports as written (the new default).
+    // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+    resolveDepSubpath: true, onlyBundle: false },
 });
 ```

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_from_tsdown_json_config/snapshots/migration_from_tsdown_json_config.md

@@ -39,7 +39,11 @@ export default defineConfig({
     unbundle: true,
     copy: "public",
     css: { inject: true },
-    "deps": { resolveDepSubpath: true, onlyBundle: false },
+    "deps": {
+      // tsdown <0.23 compatibility: resolve external dependency subpaths.
+      // Remove to preserve subpath imports as written (the new default).
+      // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+      resolveDepSubpath: true, onlyBundle: false },
     "inputOptions": {
       "cwd": "./src"
     }
@@ -125,7 +129,11 @@ export default defineConfig({
     unbundle: true,
     copy: "public",
     css: { inject: true },
-    "deps": { resolveDepSubpath: true, onlyBundle: false },
+    "deps": {
+      // tsdown <0.23 compatibility: resolve external dependency subpaths.
+      // Remove to preserve subpath imports as written (the new default).
+      // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+      resolveDepSubpath: true, onlyBundle: false },
     "inputOptions": {
       "cwd": "./src"
     }

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_from_tsup/snapshots/migration_from_tsup_success.md

@@ -40,7 +40,11 @@ the converted config uses vite-plus pack
 ```
 import { defineConfig } from 'vite-plus/pack';
 
-export default defineConfig({ deps: { resolveDepSubpath: true },
+export default defineConfig({ deps: {
+    // tsdown <0.23 compatibility: resolve external dependency subpaths.
+    // Remove to preserve subpath imports as written (the new default).
+    // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+    resolveDepSubpath: true },
   entry: ['src/index.ts'],
   dts: true,
   format: ['esm', 'cjs'],

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_from_tsup_monorepo/snapshots/migration_from_tsup_monorepo_success.md

@@ -32,7 +32,11 @@ package a gets a converted config
 ```
 import { defineConfig } from 'vite-plus/pack';
 
-export default defineConfig({ deps: { resolveDepSubpath: true },
+export default defineConfig({ deps: {
+    // tsdown <0.23 compatibility: resolve external dependency subpaths.
+    // Remove to preserve subpath imports as written (the new default).
+    // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+    resolveDepSubpath: true },
   entry: ['src/index.ts'],
   dts: true,
   format: 'cjs',
@@ -74,7 +78,11 @@ package b gets a converted config
 ```
 import { defineConfig } from 'vite-plus/pack';
 
-export default defineConfig({ deps: { resolveDepSubpath: true },
+export default defineConfig({ deps: {
+    // tsdown <0.23 compatibility: resolve external dependency subpaths.
+    // Remove to preserve subpath imports as written (the new default).
+    // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+    resolveDepSubpath: true },
   entry: ['src/index.ts'],
   dts: true,
   format: 'cjs',

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_pack_tsdown_023/snapshots/migration_pack_tsdown_023.md

@@ -32,10 +32,18 @@ export default defineConfig(() => ({
       copy: 'public',
       nodeProtocol: 'strip',
       css: { inject: true },
-      deps: { neverBundle: true, onlyBundle: [/^allowed/], resolveDepSubpath: true },
+      deps: { neverBundle: true, onlyBundle: [/^allowed/],
+        // tsdown <0.23 compatibility: resolve external dependency subpaths.
+        // Remove to preserve subpath imports as written (the new default).
+        // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+        resolveDepSubpath: true },
 
       dts: { generator: 'oxc',  },
-      attw: { profile: 'strict' },
+      attw: {
+        // tsdown <0.23 compatibility: keep all declaration resolution checks.
+        // Remove to use the new 'esm-only' profile.
+        // https://tsdown.dev/options/lint#profiles
+        profile: 'strict' },
     },
     {
       entry: 'src/index.ts',
@@ -97,10 +105,18 @@ export default defineConfig(() => ({
       copy: 'public',
       nodeProtocol: 'strip',
       css: { inject: true },
-      deps: { neverBundle: true, onlyBundle: [/^allowed/], resolveDepSubpath: true },
+      deps: { neverBundle: true, onlyBundle: [/^allowed/],
+        // tsdown <0.23 compatibility: resolve external dependency subpaths.
+        // Remove to preserve subpath imports as written (the new default).
+        // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+        resolveDepSubpath: true },
 
       dts: { generator: 'oxc',  },
-      attw: { profile: 'strict' },
+      attw: {
+        // tsdown <0.23 compatibility: keep all declaration resolution checks.
+        // Remove to use the new 'esm-only' profile.
+        // https://tsdown.dev/options/lint#profiles
+        profile: 'strict' },
     },
     {
       entry: 'src/index.ts',

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_pack_tsdown_023/snapshots/migration_pack_tsdown_023_concise_methods.md

@@ -35,7 +35,11 @@ VITE+ - The Unified Toolchain for the Web
 ```
 import { defineConfig } from 'vite-plus/pack';
 
-export default defineConfig(() => ({ deps: { resolveDepSubpath: true },
+export default defineConfig(() => ({ deps: {
+    // tsdown <0.23 compatibility: resolve external dependency subpaths.
+    // Remove to preserve subpath imports as written (the new default).
+    // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+    resolveDepSubpath: true },
   entry: 'src/index.ts',
   unbundle: true,
   dts: { generator: 'oxc' },
@@ -91,7 +95,11 @@ This project is already using Vite+! Happy coding!
 ```
 import { defineConfig } from 'vite-plus/pack';
 
-export default defineConfig(() => ({ deps: { resolveDepSubpath: true },
+export default defineConfig(() => ({ deps: {
+    // tsdown <0.23 compatibility: resolve external dependency subpaths.
+    // Remove to preserve subpath imports as written (the new default).
+    // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+    resolveDepSubpath: true },
   entry: 'src/index.ts',
   unbundle: true,
   dts: { generator: 'oxc' },

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_pack_tsdown_023/snapshots/migration_pack_tsdown_023_external.md

@@ -35,28 +35,44 @@ export default {
       outDir: 'dist/top',
       dts: false,
       inputOptions: { external: ['foo', './external.js'] },
-      deps: { neverBundle: true, resolveDepSubpath: true },
+      deps: { neverBundle: true,
+        // tsdown <0.23 compatibility: resolve external dependency subpaths.
+        // Remove to preserve subpath imports as written (the new default).
+        // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+        resolveDepSubpath: true },
     },
     {
       entry: 'src/index.ts',
       outDir: 'dist/nested',
       dts: false,
       inputOptions: { external: ['foo', './external.js'] },
-      deps: { resolveDepSubpath: true, neverBundle: true },
+      deps: {
+        // tsdown <0.23 compatibility: resolve external dependency subpaths.
+        // Remove to preserve subpath imports as written (the new default).
+        // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+        resolveDepSubpath: true, neverBundle: true },
     },
     {
       entry: 'src/index.ts',
       outDir: 'dist/constant',
       dts: false,
       inputOptions: { external: externalOptions },
-      deps: { neverBundle: true, resolveDepSubpath: true },
+      deps: { neverBundle: true,
+        // tsdown <0.23 compatibility: resolve external dependency subpaths.
+        // Remove to preserve subpath imports as written (the new default).
+        // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+        resolveDepSubpath: true },
     },
     {
       entry: 'src/index.ts',
       outDir: 'dist/alias',
       dts: false,
       inputOptions: { external: externalAlias },
-      deps: { resolveDepSubpath: true, neverBundle: true },
+      deps: {
+        // tsdown <0.23 compatibility: resolve external dependency subpaths.
+        // Remove to preserve subpath imports as written (the new default).
+        // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+        resolveDepSubpath: true, neverBundle: true },
     },
   ],
 };

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_pack_tsdown_023/snapshots/migration_pack_tsdown_023_external_constants.md

@@ -26,8 +26,16 @@ const externalOptions = ['foo'];
 
 export default {
   pack: [
-    { inputOptions: { external: externalOptions }, deps: { neverBundle: true, resolveDepSubpath: true }, unbundle: true, dts: { generator: 'tsgo' } },
-    { inputOptions: { external: externalOptions }, deps: { resolveDepSubpath: true, neverBundle: true }, unbundle: true },
+    { inputOptions: { external: externalOptions }, deps: { neverBundle: true,
+        // tsdown <0.23 compatibility: resolve external dependency subpaths.
+        // Remove to preserve subpath imports as written (the new default).
+        // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+        resolveDepSubpath: true }, unbundle: true, dts: { generator: 'tsgo' } },
+    { inputOptions: { external: externalOptions }, deps: {
+        // tsdown <0.23 compatibility: resolve external dependency subpaths.
+        // Remove to preserve subpath imports as written (the new default).
+        // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+        resolveDepSubpath: true, neverBundle: true }, unbundle: true },
   ],
 };
 ```
@@ -47,8 +55,16 @@ const externalOptions = ['foo'];
 
 export default {
   pack: [
-    { inputOptions: { external: externalOptions }, deps: { neverBundle: true, resolveDepSubpath: true }, unbundle: true, dts: { generator: 'tsgo' } },
-    { inputOptions: { external: externalOptions }, deps: { resolveDepSubpath: true, neverBundle: true }, unbundle: true },
+    { inputOptions: { external: externalOptions }, deps: { neverBundle: true,
+        // tsdown <0.23 compatibility: resolve external dependency subpaths.
+        // Remove to preserve subpath imports as written (the new default).
+        // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+        resolveDepSubpath: true }, unbundle: true, dts: { generator: 'tsgo' } },
+    { inputOptions: { external: externalOptions }, deps: {
+        // tsdown <0.23 compatibility: resolve external dependency subpaths.
+        // Remove to preserve subpath imports as written (the new default).
+        // https://tsdown.dev/options/dependencies#deps-resolvedepsubpath
+        resolveDepSubpath: true, neverBundle: true }, unbundle: true },
   ],
 };
 ```