vite-plus 0.3.2 → 1.0.0-rc.0

package/docs/guide/migrate.md

@@ -1,10 +1,14 @@
+<script setup lang="ts">
+import { migrationPrompt, upgradePrompt } from '../.vitepress/theme/data/migration-prompts.ts';
+</script>
+
 # Migrate to Vite+
 
 `vp migrate` helps move existing projects onto Vite+.
 
 ## Overview
 
-This command is the starting point for consolidating separate Vite, Vitest, Oxlint, Oxfmt, ESLint, Prettier, and tsup setups into Vite+.
+This command is the starting point for consolidating separate Vite, Vitest, Oxlint, Oxfmt, ESLint, Prettier, tsdown, and tsup setups into Vite+.
 
 Use it when you want to take an existing project and move it onto the Vite+ defaults instead of wiring each tool by hand.
 
@@ -22,9 +26,7 @@ The positional `PATH` argument is optional.
 
 - If omitted, `vp migrate` migrates the current directory
 - If provided, it migrates that target directory instead
-- For a monorepo, the target must be the workspace root. Vite+ cannot
-  migrate one workspace member, because migration updates the package-manager
-  configuration, the catalogs, and the lockfiles that all members share.
+- For a monorepo, the target must be the workspace root. Vite+ cannot migrate one workspace member, because migration updates the package-manager configuration, the catalogs, and the lockfiles that all members share.
 
 ```bash
 vp migrate
@@ -53,16 +55,17 @@ The `migrate` command is designed to move existing projects onto Vite+ quickly.
 - Can write agent and editor configuration files
 - Formats the migrated project
 
-See [Migration Rules](./migrate-rules.md) for the exact dependency, source
-rewrite, and package-manager behavior.
+See [Migration Rules](./migrate-rules.md) for the exact dependency, source rewrite, and package-manager behavior.
 
 Most projects will require further manual adjustments after running `vp migrate`.
 
+For the Vitest v5 upgrade, read the [compatibility settings and review checklist](./vitest-v5.md) and the [upstream Vitest migration guide](https://vitest.dev/guide/migration/). The preflight checks your original runner version and Node runtime before dependency updates. Keep the original lockfile available and resolve blocking findings before retrying.
+
 ## Recommended Workflow
 
 Before running the migration:
 
-- Upgrade to Vite 8+ and Vitest 4.1+ first
+- For projects that do not use Vite+ yet, upgrade to Vite 8+ and Vitest 4.1+ first
 - Make sure you understand any existing lint, format, or test setup that should be preserved
 
 After running the migration:
@@ -72,74 +75,89 @@ After running the migration:
 - Run `vp test`
 - Run `vp build` (or `vp pack` if you are building a library)
 
-## Manual Installation & Migration
+## Migration Prompt
 
-If you are manually migrating a project to Vite+, install these dev dependencies first:
+View and copy this prompt into your coding agent to migrate an existing project to Vite+:
 
-```bash
-vp install -D vite-plus
-```
+<CopyPrompt :prompt="migrationPrompt" label="View Migration Prompt" />
 
-You need to add overrides to your package manager so that other packages resolve the Vite+ versions: alias `vite` to `@voidzero-dev/vite-plus-core`, and pin `vitest` to the version Vite+ bundles (run `vp --version`) so the whole project shares a single Vitest copy with `vp test`. Without the `vitest` pin, a dependency or workspace package can pull a different Vitest than the bundled runner, splitting Vitest's internals (mocks, `expect`, runner state):
+## Upgrade from Vite+ 0.3 to 1.0
 
-```json
-"overrides": {
-  "vite": "npm:@voidzero-dev/vite-plus-core@latest",
-  "vitest": "4.1.11"
-}
-```
+Vite+ 1.0 includes the breaking changes in Vitest 5. Read the [Vite+ compatibility guide](./vitest-v5.md) alongside the [upstream migration guide](https://vitest.dev/guide/migration/).
+
+Library builds also use tsdown 0.23. Review the [pack configuration migration rules](./migrate-rules.md#pack-configuration) and [upstream release notes](https://github.com/rolldown/tsdown/releases/tag/v0.23.0) for option changes and new defaults.
 
-If you are using `pnpm`, add this to your `pnpm-workspace.yaml`:
+Keep your project's original dependencies and lockfile until migration identifies the old runner. Updating the project dependencies first can prevent the migration from preserving v4 behavior. Use one of the following paths from the workspace root.
+
+### With the Global CLI
+
+Upgrade the [global CLI](./upgrade.md#global-vp) to your target 1.0 release, then run `vp migrate --no-interactive`. For a preview, follow the [preview installation instructions](./upgrade.md#global-vp-preview).
+
+### Without the Global CLI
+
+Use an existing Node.js runtime that satisfies `^22.18.0 || ^24.11.0 || >=26.0.0`. Run the target migrator through your package manager without adding it to the project first. For the `1.0.0-rc.0` release:
+
+::: code-group
+
+```bash [pnpm]
+pnpm dlx --package=vite-plus@1.0.0-rc.0 vp migrate --no-interactive
+```
 
-```yaml
-overrides:
-  vite: npm:@voidzero-dev/vite-plus-core@latest
-  vitest: 4.1.11
+```bash [npm]
+npx --package=vite-plus@1.0.0-rc.0 vp migrate --no-interactive
 ```
 
-Or, if you are using Yarn:
+:::
 
-```json
-"resolutions": {
-  "vite": "npm:@voidzero-dev/vite-plus-core@latest",
-  "vitest": "4.1.11"
-}
+Replace `1.0.0-rc.0` with your target release. For a preview, use the version from the PR and pass `--registry=https://registry-bridge.viteplus.dev` to `pnpm` or `npx` before the `vp` command. Keep the version in `--package` explicit so you run the target migrator rather than the old local CLI.
+
+After migration, finish dependency installation and validate with the updated local CLI:
+
+::: code-group
+
+```bash [pnpm]
+pnpm install
+pnpm exec vp check
+pnpm exec vp test
+pnpm exec vp build
 ```
 
-## Migration Prompt
+```bash [npm]
+npm install
+npm exec -- vp check
+npm exec -- vp test
+npm exec -- vp build
+```
 
-If you want to hand this work to a coding agent (or the reader is a coding agent!), use this migration prompt:
+:::
 
-```md
-Migrate this project to Vite+. Vite+ replaces the current split tooling around runtime management, package management, dev/build/test commands, linting, formatting, and packaging. Run `vp help` to understand Vite+ capabilities and `vp help migrate` before making changes. Use `vp migrate --no-interactive` in the workspace root. Make sure the project is using Vite 8+ and Vitest 4.1+ before migrating.
+Use `vp pack` in place of `vp build` for a library that uses the pack command. Run configured browser, coverage, and benchmark suites as well.
 
-After the migration:
+### Review the Upgrade
 
-- Confirm `vite` imports were rewritten to `vite-plus` where needed
-- Confirm `vitest` imports were rewritten to `vite-plus/test` (and `@vitest/browser*` to `vite-plus/test/browser*`) where needed
-- On pnpm, keep the `vite`, `vitest` dependency entries configured by `vp migrate` so the workspace aliases and overrides stay effective; with other package managers, you can remove them once those rewrites are confirmed
-- Move remaining tool-specific config into the appropriate blocks in `vite.config.ts`
+On an existing Vite+ project, use the default upgrade flow. Add `--full` if you also want to repeat project setup. Resolve blockers and review the file-specific report before committing. See [Upgrade vs. Full Setup](./migrate-rules.md#upgrade-vs-full-setup) for the scope of each mode.
 
-Command mapping to keep in mind:
+After the migrated project passes validation, [check whether you can remove the generated v4 compatibility settings](./vitest-v5.md#remove-unneeded-compatibility-settings) with no code changes or small, localized fixes. Keep compatibility for now if removal requires extensive test changes or you cannot validate the result.
 
-- `vp run <script>` is the equivalent of `pnpm run <script>`
-- `vp dev` and `vp test` always run the built-ins; `vp run dev` and `vp run test` run the `dev` and `test` scripts from `package.json`
-- `vp install`, `vp add`, and `vp remove` delegate through the package manager declared by `packageManager`
-- `vp dev`, `vp build`, `vp preview`, `vp lint`, `vp fmt`, `vp check`, and `vp pack` replace the corresponding standalone tools
-- Prefer `vp check` for validation loops
+For libraries, review the generated [tsdown compatibility settings](#tsdown) after a successful `vp pack` run. Follow their documentation links before adopting the new defaults, and check the emitted imports and declarations with your package's consumers.
 
-Finally, verify the migration by running: `vp install`, `vp check`, `vp test`, and `vp build`
+### Copy Prompt
 
-Summarize the migration at the end and report any manual follow-up still required.
-```
+View and copy this prompt into your coding agent to upgrade an existing Vite+ 0.3 project:
+
+<CopyPrompt :prompt="upgradePrompt" label="View Upgrade Prompt" />
 
 ## Tool-Specific Migrations
 
 ### Vitest
 
-Vitest is automatically migrated through `vp migrate`. `vite-plus` re-exports upstream `vitest@4.x` under `vite-plus/test*`, so for node-mode tests a single `vite-plus` install is enough — you no longer need to install `vitest` directly.
+Vitest is automatically migrated through `vp migrate`. `vite-plus` re-exports upstream `vitest@5.0.1` under `vite-plus/test*`, so for node-mode tests a single `vite-plus` install is enough — you no longer need to install `vitest` directly.
 
-Browser mode is more nuanced. `vite-plus` bundles the base browser runtime (`@vitest/browser`) and the preview provider (`@vitest/browser-preview`), but the **Playwright** and **WebdriverIO** providers stay opt-in: `@vitest/browser-playwright` (with its `playwright` peer) and `@vitest/browser-webdriverio` (with its `webdriverio` peer) are **not** shipped with `vite-plus`, so non-browser projects never pull them in. `vp migrate` detects the provider you actually use and adds it — pinned to the bundled vitest version — together with its framework. If you migrate manually and use one of these providers, install the provider package and its framework yourself so `vite-plus/test/browser-playwright` / `vite-plus/test/browser-webdriverio` can resolve.
+For browser mode, you can use the base browser runtime (`@vitest/browser`) and Preview provider (`@vitest/browser-preview`) included in `vite-plus`. To use Playwright or WebDriverIO, you also need the opt-in provider (`@vitest/browser-playwright` or `@vitest/browser-webdriverio`) and its framework peer (`playwright` or `webdriverio`).
+
+`vp migrate` adds the Playwright provider at the bundled Vitest version and ensures its framework peer. You can import it from `vite-plus/test/browser-playwright`.
+
+For WebDriverIO, import from the community-maintained `@vitest/browser-webdriverio`. Migration restores legacy Vite+ provider imports, ensures a provider version of at least `5.0.0`, and adds an `@vitest/browser` override that matches the bundled runner. Manage later provider upgrades and framework peers yourself. See [Community WebDriverIO provider](./vitest-v5.md#community-webdriverio-provider).
 
 If you are migrating manually, update all the imports to `vite-plus/test*` instead:
 
@@ -163,6 +181,17 @@ const { page } = await import('vite-plus/test/browser/context');
 
 ### tsdown
 
+`vp migrate` updates supported static options in `pack` blocks and `tsdown.config.*` for tsdown 0.23. This also runs for existing Vite+ projects and workspace packages without `--full`. See [Pack Configuration](./migrate-rules.md#pack-configuration) for the option mappings and cases that require manual review.
+
+The transform preserves earlier defaults by inserting `deps.resolveDepSubpath: true` and, when ATTW checks are enabled, `attw.profile: 'strict'` if these settings are absent. Each inserted setting includes a `tsdown <0.23 compatibility` comment with a documentation link and removal guidance. Explicit settings remain unchanged.
+
+Keep these settings for the first `vp pack` run. After validation, review whether your package can adopt the new defaults:
+
+- Removing `deps.resolveDepSubpath: true` [preserves external subpath imports as written](https://tsdown.dev/options/dependencies#deps-resolvedepsubpath). Check that consumers can resolve the emitted imports.
+- Removing the inserted `attw.profile: 'strict'` selects the `esm-only` [resolution profile](https://tsdown.dev/options/lint#profiles). This skips `node10` and CommonJS resolution checks. Keep `strict` if your package requires those checks.
+
+Remove each accepted setting's generated comment too. Run `vp pack` and your package's consumer checks after each change. Keep the setting when you cannot validate the result.
+
 If your project uses a `tsdown.config.ts`, move its options into the `pack` block in `vite.config.ts`:
 
 ```ts [tsdown.config.ts] {4-6}
@@ -205,19 +234,13 @@ export default defineConfig({
 });
 ```
 
-When no existing hook policy owns the workflow, `vp migrate` can move supported lint-staged rules
-and remove the old configuration and dependency. If an existing hook tool is preserved, keep
-lint-staged in place until you convert that hook policy manually. See the
-[Commit hooks guide](/guide/commit-hooks) and [Staged config reference](/config/staged) for details.
+When no existing hook policy owns the workflow, `vp migrate` can move supported lint-staged rules and remove the old configuration and dependency. If an existing hook tool is preserved, keep lint-staged in place until you convert that hook policy manually. See the [Commit hooks guide](/guide/commit-hooks) and [Staged config reference](/config/staged) for details.
 
 ### Git hook tools
 
-The `vp migrate` command does not automatically convert Husky setups. When Husky is detected,
-Vite+ leaves its hooks, lifecycle scripts, configuration, and dependencies unchanged and shows a
-warning. You can migrate the project manually using the [Commit hooks guide](/guide/commit-hooks).
+The `vp migrate` command does not automatically convert Husky setups. When Husky is detected, Vite+ leaves its hooks, lifecycle scripts, configuration, and dependencies unchanged and shows a warning. You can migrate the project manually using the [Commit hooks guide](/guide/commit-hooks).
 
-Existing project-owned Vite+ hooks are also preserved. The default staged workflow is introduced
-only when no existing hook policy is found.
+Existing project-owned Vite+ hooks are also preserved. The default staged workflow is introduced only when no existing hook policy is found.
 
 If your project currently uses `lefthook`, `simple-git-hooks`, or `yorkie`, `vp migrate` will leave your existing configuration alone and show a warning. This happens even if you choose to set up hooks during the prompt or include the `--hooks` flag.
 

package/docs/guide/monorepo.md

@@ -6,7 +6,11 @@ Because `vite.config.ts` is just JavaScript, you can choose to put your entire c
 
 ## Root Config With Overrides
 
-Vite+ does not currently support nested lint or format configuration. Package-level `lint` and `fmt` blocks are not automatically applied. For now, define file- or package-specific settings with overrides in the root `vite.config.ts`. The long-term behavior is open for discussion; [share your use case and expectations](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) to help shape it.
+Run `vp lint`, `vp fmt`, and `vp check` from the workspace root to apply the root lint and format settings across packages. These commands do not apply nested configs to individual files. Define file- or package-specific settings with overrides in the root `vite.config.ts`.
+
+When run from a package directory, `vp lint`, `vp fmt`, and `vp check` still use the root `lint` and `fmt` blocks. Package configs cannot replace root format settings, lint rules, or type-check options. File arguments remain relative to the package working directory.
+
+Use `-c <path>` or `--config <path>` with `vp lint` or `vp fmt` to select another config. If the root config has no block for that tool, the tool uses native discovery from the working directory.
 
 Use `lint.overrides` for Oxlint rules that only apply to some packages:
 

package/docs/guide/run.md

@@ -1,6 +1,6 @@
 # Run
 
-`vp run` runs `package.json` scripts and tasks defined in `vite.config.ts`. It works like `pnpm run`, with caching, dependency ordering, and workspace-aware execution built in.
+`vp run` runs `package.json` scripts and tasks defined in `vite.config.ts`. It works like `pnpm run`, with caching, dependency ordering, and workspace-aware execution built in. The task runner is available from both the [global CLI](/guide/global-cli) and the [project-local CLI](/guide/local-cli).
 
 ::: tip
 `vpr` is available as a standalone shorthand for `vp run`. All examples below work with both `vp run` and `vpr`.

package/docs/guide/test.md

@@ -2,6 +2,8 @@
 
 `vp test` runs tests with [Vitest](https://vitest.dev).
 
+The bundled runner uses Vitest `5.0.1` and requires Node `^22.18.0 || ^24.11.0 || >=26.0.0`. For existing projects, follow [Upgrade to Vitest 5](./vitest-v5.md) before updating dependencies.
+
 ## Overview
 
 `vp test` is built on [Vitest](https://vitest.dev/), so you get a Vite-native test runner that reuses your Vite config and plugins, supports Jest-style expectations, snapshots, and coverage, and handles modern ESM, TypeScript, and JSX projects cleanly.

package/docs/guide/troubleshooting.md

@@ -15,28 +15,24 @@ Vite+ expects modern upstream tool versions.
 
 If you are migrating an existing project and it still depends on older Vite or Vitest versions, upgrade those first before adopting Vite+.
 
-Run `vp toolchain` to show the versions from the local Vite+ package.
-Run `vp toolchain --global` to show the versions from the global Vite+ release.
+Run `vp toolchain` to show the versions from the local Vite+ package. Run `vp toolchain --global` to show the versions from the global Vite+ release.
 
 ## `vp check` does not run type-aware lint rules or type checks
 
 - Confirm that `lint.options.typeAware` and `lint.options.typeCheck` are enabled in `vite.config.ts`
 - Check whether your `tsconfig.json` still uses `compilerOptions.baseUrl`
 
-The Oxlint type checker path powered by `tsgolint` does not support `baseUrl`.
-`vp migrate` and `vp lint --init` try to run the `vp dlx @andrewbranch/ts5to6 --fixBaseUrl .`
-fix before enabling type-aware linting. If that fix fails or is declined, Vite+
-skips `typeAware` and `typeCheck`.
+The Oxlint type checker path powered by `tsgolint` does not support `baseUrl`. `vp migrate` and `vp lint --init` try to run the `vp dlx @andrewbranch/ts5to6 --fixBaseUrl .` fix before enabling type-aware linting. If that fix fails or is declined, Vite+ skips `typeAware` and `typeCheck`.
 
 ## Nested lint or format config is not applied
 
-Vite+ does not currently support nested lint or format configuration. When running `vp lint`, `vp fmt`, or `vp check` from the workspace root, do not rely on configs in subdirectories or on `lint` and `fmt` blocks in package-level `vite.config.ts` files to override the root settings.
+When running `vp lint`, `vp fmt`, or `vp check`, configs in subdirectories do not override settings for individual files. Commands run from a package directory still use the workspace-root `lint` and `fmt` blocks when they exist. Use `-c <path>` or `--config <path>` with `vp lint` or `vp fmt` to select another config. If the root config has no block for that tool, the tool uses native discovery from the working directory.
 
 Keep lint and format settings in the root `vite.config.ts`. Use [`lint.overrides`](/guide/monorepo#root-config-with-overrides) and [`fmt.overrides`](/guide/monorepo#format-overrides) for file- or package-specific settings. You can also [import configuration objects](/guide/monorepo#composing-configuration-files) into the root config to keep settings in separate files.
 
-For IDE integration, we have `disableNestedConfig` and `fmt.disableNestedConfig` config to disable nested lint and format configs and keep editor behavior aligned with the root Vite+ config. See [IDE Integration](/guide/ide-integration) for setup instructions for your editor.
+For IDE integration, `disableNestedConfig` and `fmt.disableNestedConfig` disable per-file nested lint and format configs. See [IDE Integration](/guide/ide-integration) for setup instructions for your editor.
 
-We're holding off on nested config support for now. Some of the factors we're considering are how implicit config discovery affects the predictability of linting and formatting, what context AI agents need to understand the settings that apply, and the potential performance cost of finding and loading multiple configs. At the same time, we recognize that keeping package-specific context close to the code may have benefits. The use cases we've heard so far haven't given us a strong enough reason to commit to those semantics. Waiting leaves room to add support later, and we'd like to hear why your project needs nested configs, especially where root-level overrides fall short.
+We're holding off on applying nested configs to individual files for now. Some of the factors we're considering are how implicit config discovery affects the predictability of linting and formatting, what context AI agents need to understand the settings that apply, and the potential performance cost of finding and loading multiple configs. At the same time, we recognize that keeping package-specific context close to the code may have benefits. The use cases we've heard so far haven't given us a strong enough reason to commit to those semantics. Waiting leaves room to add support later, and we'd like to hear why your project needs nested configs, especially where root-level overrides fall short.
 
 Do you need nested configs? [Share your use case and opinion on GitHub](https://github.com/voidzero-dev/vite-plus/discussions/2669), including your project structure, the reason why you want them and whether root-level overrides meet your needs.
 
@@ -76,8 +72,7 @@ If `vp staged` fails or your pre-commit hook does not run:
 - if status shows `Preference: disabled (local)`, re-enable with `vp hooks enable`
 - check whether hooks were skipped intentionally through `VP_GIT_HOOKS=0`
 
-To stop hooks in this clone without deleting project policy files, run `vp hooks disable`.
-See the [Commit hooks guide](/guide/commit-hooks) for the full workflow.
+To stop hooks in this clone without deleting project policy files, run `vp hooks disable`. See the [Commit hooks guide](/guide/commit-hooks) for the full workflow.
 
 A minimal staged config looks like this:
 

package/docs/guide/upgrade-project.md

@@ -0,0 +1,61 @@
+# Update Vite+
+
+Updating `vite-plus` and its related project dependencies. To upgrade the global `vp` binary, see [Upgrading Vite+](/guide/upgrade).
+
+## Update with Migrate
+
+The recommended way to update a project is to use `vp migrate`, which keeps the toolchain dependencies aligned.
+
+After updating the project's `vite-plus` dependency, run the local CLI to align the toolchain versions:
+
+```bash
+./node_modules/.bin/vp migrate
+```
+
+If your global CLI is newer than the project's version, running `vp migrate` upgrades the project to that global version instead:
+
+```bash
+vp migrate
+```
+
+On a project that is already on Vite+, migrate does a toolchain version upgrade only: it re-pins `vite-plus`, the `vite` -> `@voidzero-dev/vite-plus-core` alias, and the `vitest` pin to the versions bundled with the CLI running the migration, across every workspace package. It skips the first-time setup steps (git hooks, editor and agent files, lint migration), so a version bump does not re-touch things you already configured. Pass `--full` to also run that setup.
+
+## Manually Updating
+
+Update `vite-plus` and the `vite` alias to `@voidzero-dev/vite-plus-core` together, keeping the core version aligned with `vite-plus`. Update these entries wherever they are declared in your workspace, including overrides or catalogs, then install dependencies to refresh the lockfile. Also [update the Vitest pin](#updating-the-vitest-pin) to match the bundled version.
+
+Without the global CLI, run the `vp` commands on this page through your package manager, for example `pnpm exec vp toolchain vitest`.
+
+### Updating the Vitest Pin
+
+If you migrated with `vp migrate`, your project pins `vitest` to an exact version so the whole project shares a single Vitest copy with the bundled `vp test` runner. The pin lives in your package manager's override block:
+
+- **npm / Bun:** a `vitest` entry under `overrides` in `package.json`
+- **Yarn:** a `vitest` entry under `resolutions` in `package.json`
+- **pnpm:** a `vitest@*` entry under `overrides` in `pnpm-workspace.yaml`. If your `package.json` already has a `pnpm` field, the entry lives under `pnpm.overrides` in `package.json` instead. pnpm ignores `pnpm-workspace.yaml` overrides when `package.json` defines `pnpm.overrides`.
+
+A Vite+ release can bump the bundled Vitest. Because that pin also applies to `vite-plus`'s own `vitest` dependency, an out-of-date pin keeps installing the previous runner even after you upgrade `vite-plus` — splitting Vitest's internals (mocks, `expect`, runner state) between the pinned copy and the one `vp test` loads.
+
+After upgrading `vite-plus`, re-pin `vitest` to the version Vite+ now bundles. Check that version with:
+
+```bash
+vp toolchain vitest
+```
+
+Then set the `vitest` override to that exact version and reinstall dependencies.
+
+::: details Why pnpm overrides use `@*`
+Under pnpm the managed keys use an explicit `@*` range (`vite@*`, `vitest@*`). pnpm applies an override by replacing the declared spec on every manifest, importer manifests included. A bare key matches any spec, including `catalog:`. The `@*` range keeps the override on the semver ranges that transitive and peer declarations use, and leaves `catalog:` references intact. `vp up` therefore no longer rewrites them to a concrete version.
+:::
+
+## Preview Builds
+
+After [installing a preview build of the global CLI](/guide/upgrade#global-vp-preview), run migrate in the project to move its local `vite-plus` onto the same build:
+
+```bash
+vp migrate
+```
+
+Migrate writes the bridge registry to `.npmrc`. For Yarn Berry, it writes the registry to `.yarnrc.yml`. It pins `vite-plus` and the `vite` alias to the matching `0.0.0-commit.<sha>` version. The `vite` alias points to `@voidzero-dev/vite-plus-core`. Commit the registry line if the project CI must test the preview.
+
+After the install, run `vp toolchain` to show the selected versions. After testing, set `vite-plus` to `latest`. Remove the bridge `registry` line from `.npmrc` or `.yarnrc.yml`. Then run `vp install`.

package/docs/guide/upgrade.md

@@ -1,13 +1,13 @@
 # Upgrading Vite+
 
-Use `vp upgrade` to update the global `vp` binary, and use Vite+'s package management commands to update the local `vite-plus` package in a project.
+Use `vp upgrade` to update the global `vp` binary. To update the local `vite-plus` package in a project, see [Update Vite+](/guide/upgrade-project).
 
 ## Overview
 
 There are two parts to upgrading Vite+:
 
 - The global `vp` command installed on your machine
-- The local `vite-plus` package used by an individual project
+- The [local `vite-plus` package](/guide/upgrade-project) used by an individual project
 
 You can upgrade both of them independently.
 
@@ -22,20 +22,18 @@ vp toolchain vite rolldown oxc
 vp toolchain --json
 ```
 
-The command uses the local `vite-plus` package when the project has one. Use
-`--global` to show the release for the global `vp` command:
+The command uses the local `vite-plus` package when the project has one. Use `--global` to show the release for the global `vp` command:
 
 ```bash
 vp toolchain --global
 ```
 
-`vp why <package>` shows the dependency graph from the package manager. It
-cannot show code bundled into `@voidzero-dev/vite-plus-core`. It also cannot
-show engines compiled into Vite+. Use `vp toolchain` to show those versions and
-relationships.
+`vp why <package>` shows the dependency graph from the package manager. It cannot show code bundled into `@voidzero-dev/vite-plus-core`. It also cannot show engines compiled into Vite+. Use `vp toolchain` to show those versions and relationships.
 
 ## Global `vp`
 
+Update the global CLI with:
+
 ```bash
 vp upgrade                        # upgrade to the latest version
 vp upgrade --check                # check for updates without installing
@@ -45,27 +43,14 @@ vp upgrade --registry <registry>  # use a custom npm registry
 
 ### Move an Existing Install to the Split Directory Layout
 
-Vite+ 0.3.0 is the first release that supports the split directory layout.
-Vite+ 0.2.x and earlier use the single-root layout for fresh installs and
-upgrades.
+Vite+ 0.3.0 is the first release that supports the split directory layout. Vite+ 0.2.x and earlier use the single-root layout for fresh installs and upgrades.
 
-`vp upgrade` keeps an existing default install in `~/.vite-plus` on Unix or
-`%USERPROFILE%\.vite-plus` on Windows. The command upgrades the CLI in that
-directory. It does not move the install to the split platform directories. You
-can continue to use the existing layout.
+`vp upgrade` keeps an existing default install in `~/.vite-plus` on Unix or `%USERPROFILE%\.vite-plus` on Windows. The command upgrades the CLI in that directory. It does not move the install to the split platform directories. You can continue to use the existing layout.
 
-To use the split layout now, remove the existing install. Then install Vite+
-again. Run `vp implode` in a shell that uses the current install. The command
-removes the generated environment file and shell profile entries. It does not
-unset directory variables in the current shell. Unset all Vite+ directory
-variables before you run the installer. This can include values from an earlier
-preview environment file. Alternatively, start a new shell after `vp implode`.
-Then run the installer in the new shell.
+To use the split layout now, remove the existing install. Then install Vite+ again. Run `vp implode` in a shell that uses the current install. The command removes the generated environment file and shell profile entries. It does not unset directory variables in the current shell. Unset all Vite+ directory variables before you run the installer. This can include values from an earlier preview environment file. Alternatively, start a new shell after `vp implode`. Then run the installer in the new shell.
 
 ::: warning
-`vp implode` removes all Vite+-managed Node.js runtimes, global packages,
-configuration, and caches. Keep the existing layout if you do not want to
-recreate that data.
+`vp implode` removes all Vite+-managed Node.js runtimes, global packages, configuration, and caches. Keep the existing layout if you do not want to recreate that data.
 :::
 
 ```bash
@@ -82,11 +67,7 @@ Remove-Item Env:\VP_HOME, Env:\VP_DATA_DIR, Env:\VP_BIN_DIR, Env:\VP_CACHE_DIR -
 irm https://vite.plus/ps1 | iex
 ```
 
-Also remove persistent definitions of `VP_HOME`, `VP_DATA_DIR`, `VP_BIN_DIR`,
-and `VP_CACHE_DIR` from your shell profile or system environment. A fresh
-install uses `VP_HOME` or a complete `VP_*_DIR` group that remains set.
-`VP_HOME` selects the single-root layout. If you install Vite+ 0.2.x or earlier,
-the installer also uses this layout. The installer prints a notice.
+Also remove persistent definitions of `VP_HOME`, `VP_DATA_DIR`, `VP_BIN_DIR`, and `VP_CACHE_DIR` from your shell profile or system environment. A fresh install uses `VP_HOME` or a complete `VP_*_DIR` group that remains set. `VP_HOME` selects the single-root layout. If you install Vite+ 0.2.x or earlier, the installer also uses this layout. The installer prints a notice.
 
 ### Rollback
 
@@ -98,35 +79,17 @@ vp upgrade --rollback
 
 Older versions are pruned automatically after each upgrade. The active version and the previous version are always kept, so a rollback target is never removed.
 
-## Local `vite-plus`
+### Homebrew
 
-The recommended way to upgrade an existing Vite+ project is `vp migrate`:
+Homebrew owns its installed binary and JavaScript package. Update them with:
 
 ```bash
-vp migrate
+brew upgrade vite-plus
 ```
 
-On a project that is already on Vite+, migrate does a toolchain version upgrade only: it re-pins `vite-plus`, the `vite` -> `@voidzero-dev/vite-plus-core` alias, and the `vitest` pin to the versions the global `vp` now bundles, across every workspace package. It skips the first-time setup steps (git hooks, editor and agent files, lint migration), so a version bump does not re-touch things you already configured. Pass `--full` to also run that setup.
-
-### Updating the Vitest Pin
-
-If you migrated with `vp migrate`, your project pins `vitest` to an exact version so the whole project shares a single Vitest copy with the bundled `vp test` runner. The pin lives in your package manager's override block:
-
-- **npm / Bun:** a `vitest` entry under `overrides` in `package.json`
-- **Yarn:** a `vitest` entry under `resolutions` in `package.json`
-- **pnpm:** a `vitest@*` entry under `overrides` in `pnpm-workspace.yaml`. If your `package.json` already has a `pnpm` field, the entry lives under `pnpm.overrides` in `package.json` instead. pnpm ignores `pnpm-workspace.yaml` overrides when `package.json` defines `pnpm.overrides`.
+`vp upgrade` detects Homebrew installations and directs you to this command without downloading or installing another version. This also applies to `--force`, a specific version, and `--rollback`. Use Homebrew to manage these installations.
 
-Under pnpm the managed keys use an explicit `@*` range (`vite@*`, `vitest@*`). pnpm applies an override by replacing the declared spec on every manifest, importer manifests included. A bare key matches any spec, including `catalog:`. The `@*` range keeps the override on the semver ranges that transitive and peer declarations use, and leaves `catalog:` references intact. `vp up` therefore no longer rewrites them to a concrete version.
-
-A Vite+ release can bump the bundled Vitest. Because that pin also applies to `vite-plus`'s own `vitest` dependency, an out-of-date pin keeps installing the previous runner even after you upgrade `vite-plus` — splitting Vitest's internals (mocks, `expect`, runner state) between the pinned copy and the one `vp test` loads.
-
-After upgrading `vite-plus`, re-pin `vitest` to the version Vite+ now bundles. Check that version with:
-
-```bash
-vp toolchain vitest
-```
-
-Then set the `vitest` override to that exact version, or rerun `vp migrate` to update the pin for you.
+`vp upgrade --check` directs you to `brew outdated vite-plus`. Automatic npm update checks and notices are disabled for Homebrew installations.
 
 ## Preview Builds
 
@@ -160,12 +123,4 @@ The installer uses the registry bridge to resolve the ref to a `0.0.0-commit.<sh
 
 ### Local `vite-plus` Preview
 
-After installing the preview global CLI above, run migrate in the project to move its local `vite-plus` onto the same build:
-
-```bash
-vp migrate
-```
-
-Migrate writes the bridge registry to `.npmrc`. For Yarn Berry, it writes the registry to `.yarnrc.yml`. It pins `vite-plus` and the `vite` alias to the matching `0.0.0-commit.<sha>` version. The `vite` alias points to `@voidzero-dev/vite-plus-core`. Commit the registry line if the project CI must test the preview.
-
-After the install, run `vp toolchain` to show the selected versions. After testing, set `vite-plus` to `latest`. Remove the bridge `registry` line from `.npmrc` or `.yarnrc.yml`. Then run `vp install`.
+To use the same preview in a project, follow [Update Vite+](/guide/upgrade-project#preview-builds).