vite-plus 0.3.2 → 0.3.3

package/docs/guide/migrate-rules.md

@@ -1,52 +1,31 @@
 # Migration Rules
 
-This reference describes exactly what `vp migrate` does to a project: how it
-updates dependencies, rewrites source imports and package scripts, and adjusts
-package-manager configuration. See the [migration guide](./migrate.md) for the
-command overview and workflow.
+This reference describes exactly what `vp migrate` does to a project: how it updates dependencies, rewrites source imports and package scripts, and adjusts package-manager configuration. See the [migration guide](./migrate.md) for the command overview and workflow.
 
-Except for [Before You Migrate](#before-you-migrate), which lists steps you
-take yourself, everything below describes automatic behavior.
+Except for [Before You Migrate](#before-you-migrate), which lists steps you take yourself, everything below describes automatic behavior.
 
 ## Before You Migrate
 
-1. Run `vp upgrade` so the global CLI has the latest migration rules. A stale
-   local `vite-plus` is not a blocker: when the project's local copy is older,
-   migration delegates to the global CLI.
+1. Run `vp upgrade` so the global CLI has the latest migration rules. A stale local `vite-plus` is not a blocker: when the project's local copy is older, migration delegates to the global CLI.
 2. Upgrade the project to Vite 8+ and Vitest 4.1+ when necessary.
-3. Run `vp migrate` from the workspace root. Use `--no-interactive` in
-   automated environments.
-4. Review every changed manifest, package-manager config, source rewrite, and
-   generated lockfile.
+3. Run `vp migrate` from the workspace root. Use `--no-interactive` in automated environments.
+4. Review every changed manifest, package-manager config, source rewrite, and generated lockfile.
 5. Validate with `vp install`, `vp check`, `vp test`, and `vp build`.
 
-Migration is idempotent: running it again after a successful migration should
-not produce another diff.
+Migration is idempotent: running it again after a successful migration should not produce another diff.
 
 ## Upgrade vs. Full Setup
 
-On a project that already depends on `vite-plus`, `vp migrate` performs an
-upgrade only: it updates dependencies and package-manager configuration and
-finalizes imports. It does not touch project setup.
+On a project that already depends on `vite-plus`, `vp migrate` performs an upgrade only: it updates dependencies and package-manager configuration and finalizes imports. It does not touch project setup.
 
-- `--full` also runs the setup actions: git hooks, editor config, agent files,
-  ESLint and Prettier migration, framework shims, the tsconfig `baseUrl` fix,
-  and the `.nvmrc`/Volta to `.node-version` conversion.
-- `--hooks`, `--agent`, and `--editor` opt into a single setup action without
-  `--full`.
+- `--full` also runs the setup actions: git hooks, editor config, agent files, ESLint and Prettier migration, framework shims, the tsconfig `baseUrl` fix, and the `.nvmrc`/Volta to `.node-version` conversion.
+- `--hooks`, `--agent`, and `--editor` opt into a single setup action without `--full`.
 
-When a default upgrade skips setup actions that would apply, it prints a hint
-to run `vp migrate --full`. Fresh (non Vite+) projects always run the full
-migration.
+When a default upgrade skips setup actions that would apply, it prints a hint to run `vp migrate --full`. Fresh (non Vite+) projects always run the full migration.
 
 ## Pack Configuration
 
-`vp migrate` updates static `pack` objects in `vite.config.*` and exported
-objects in `tsdown.config.*` for [tsdown 0.23](https://github.com/rolldown/tsdown/releases/tag/v0.23.0).
-This also runs on existing Vite+ projects without `--full`, including workspace
-packages. Arrays and direct objects returned by `defineConfig` callbacks are
-supported. JSON tsdown configs receive the same updates after they merge into
-`vite.config.ts`.
+`vp migrate` updates static `pack` objects in `vite.config.*` and exported objects in `tsdown.config.*` for [tsdown 0.23](https://github.com/rolldown/tsdown/releases/tag/v0.23.0). This also runs on existing Vite+ projects without `--full`, including workspace packages. Arrays and direct objects returned by `defineConfig` callbacks are supported. JSON tsdown configs receive the same updates after they merge into `vite.config.ts`.
 
 | Previous option                                                    | Updated option                                                                        |
 | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
@@ -63,27 +42,13 @@ supported. JSON tsdown configs receive the same updates after they merge into
 | `dts.cjsReexport`                                                  | Removed; tsdown generates CJS declarations separately                                 |
 | `--public-dir` in `tsdown` or `vp pack` scripts                    | `--copy`                                                                              |
 
-Migration preserves the previous defaults by setting `deps.resolveDepSubpath`
-to `true` when absent. Enabled ATTW checks receive `profile: 'strict'` when
-no profile is set. Explicit values, including `false`, remain unchanged.
+Migration preserves the previous defaults by setting `deps.resolveDepSubpath` to `true` when absent. Enabled ATTW checks receive `profile: 'strict'` when no profile is set. Explicit values, including `false`, remain unchanged.
 
-`noExternal` moves to `deps.alwaysBundle`, preserving matcher expressions,
-references, and callback methods. Existing `deps.alwaysBundle` values remain
-unchanged.
+`noExternal` moves to `deps.alwaysBundle`, preserving matcher expressions, references, and callback methods. Existing `deps.alwaysBundle` values remain unchanged.
 
-When `external` accompanies either `skipNodeModulesBundle` form, static matchers
-and references to local constants move to `inputOptions.external` before
-`deps.neverBundle` is set. Constant declarations and references stay intact.
-This preserves the original matching rules, including external file paths. Unsupported matchers,
-conflicting `inputOptions`, and declaration-specific dependency rules leave the
-pack object unchanged and produce a manual-migration warning.
+When `external` accompanies either `skipNodeModulesBundle` form, static matchers and references to local constants move to `inputOptions.external` before `deps.neverBundle` is set. Constant declarations and references stay intact. This preserves the original matching rules, including external file paths. Unsupported matchers, conflicting `inputOptions`, and declaration-specific dependency rules leave the pack object unchanged and produce a manual-migration warning.
 
-The transform does not evaluate configuration code. Objects with spreads,
-computed keys, or duplicate keys, and conflicting old and new options require
-manual review. Dynamic boolean selectors remain unchanged. Unrelated Vite and
-plugin options remain unchanged. Run `vp pack` after migration to check the
-result. Node.js requirements, TypeScript module resolution, and programmatic
-`build()` return values require separate review.
+The transform does not evaluate configuration code. Objects with spreads, computed keys, or duplicate keys, and conflicting old and new options require manual review. Dynamic boolean selectors remain unchanged. Unrelated Vite and plugin options remain unchanged. Run `vp pack` after migration to check the result. Node.js requirements, TypeScript module resolution, and programmatic `build()` return values require separate review.
 
 ## Dependency Rules
 
@@ -99,216 +64,115 @@ What happens to each toolchain dependency, at a glance:
 
 ### Version Selection
 
-- `vite-plus` is pinned to the concrete version of the CLI running the
-  migration, never the `latest` dist-tag.
-- The `vite` alias targets `@voidzero-dev/vite-plus-core` from the same Vite+
-  release.
-- A catalog-backed manifest may contain `catalog:` or a named catalog
-  reference. Migration keeps the reference and updates the referenced catalog
-  value to the concrete toolchain target.
-- Deliberate protocol pins are preserved: `workspace:`, `file:`, `link:`,
-  `npm:`, `github:`, Git URLs, and HTTP URLs.
-- Migration reconciles every workspace package, not only the root manifest.
-  Shared overrides and catalogs stay at the workspace root; dependencies that
-  provide a peer belong in each package that needs them.
+- `vite-plus` is pinned to the concrete version of the CLI running the migration, never the `latest` dist-tag.
+- The `vite` alias targets `@voidzero-dev/vite-plus-core` from the same Vite+ release.
+- A catalog-backed manifest may contain `catalog:` or a named catalog reference. Migration keeps the reference and updates the referenced catalog value to the concrete toolchain target.
+- Deliberate protocol pins are preserved: `workspace:`, `file:`, `link:`, `npm:`, `github:`, Git URLs, and HTTP URLs.
+- Migration reconciles every workspace package, not only the root manifest. Shared overrides and catalogs stay at the workspace root; dependencies that provide a peer belong in each package that needs them.
 
 ### Vite and Overrides
 
-Package-manager overrides do not create dependency edges by themselves. Under
-pnpm, a package that lists `vite-plus` in `dependencies` or `devDependencies`
-but has no `vite` entry anywhere (`dependencies`, `devDependencies`,
-`optionalDependencies`, or `peerDependencies`) lets pnpm auto-install upstream
-Vite to satisfy Vitest's required `vite` peer, splitting the project across
-separate Vite+, Vite, and Vitest instances. To prevent this, `vp migrate` adds
-the missing `vite` entry to `devDependencies` of every such package; the
-workspace override then redirects it to Vite+ core.
+Package-manager overrides do not create dependency edges by themselves. Under pnpm, a package that lists `vite-plus` in `dependencies` or `devDependencies` but has no `vite` entry anywhere (`dependencies`, `devDependencies`, `optionalDependencies`, or `peerDependencies`) lets pnpm auto-install upstream Vite to satisfy Vitest's required `vite` peer, splitting the project across separate Vite+, Vite, and Vitest instances. To prevent this, `vp migrate` adds the missing `vite` entry to `devDependencies` of every such package; the workspace override then redirects it to Vite+ core.
 
 Related rules:
 
-- A direct `vite` declaration is never removed merely because a root override
-  exists.
+- A direct `vite` declaration is never removed merely because a root override exists.
 - Plain or stale aliases are normalized; named catalog references are kept.
-- Under pnpm the managed override 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:`, and `vp up` then rewrites that reference to a concrete version.
-  The `@*` range keeps the override on the semver ranges that transitive and
-  peer declarations use. It leaves `catalog:` references to the catalog, which
-  already resolves them to Vite+ core. Migration re-keys a project that still
-  holds the bare key, and keeps its named-catalog choice.
-- The direct-entry rule above is pnpm-specific. Bun mirrors its core alias as
-  a direct dependency for its peer resolver, and npm browser-provider layouts
-  may need a top-level `vite` edge so nested Vitest packages can resolve
-  `vite`.
+- Under pnpm the managed override 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:`, and `vp up` then rewrites that reference to a concrete version. The `@*` range keeps the override on the semver ranges that transitive and peer declarations use. It leaves `catalog:` references to the catalog, which already resolves them to Vite+ core. Migration re-keys a project that still holds the bare key, and keeps its named-catalog choice.
+- The direct-entry rule above is pnpm-specific. Bun mirrors its core alias as a direct dependency for its peer resolver, and npm browser-provider layouts may need a top-level `vite` edge so nested Vitest packages can resolve `vite`.
 
 ### When Vitest Is Directly Required
 
-Migration keeps or adds a package-local `vitest` at the exact bundled version
-when any of the following is true:
+Migration keeps or adds a package-local `vitest` at the exact bundled version when any of the following is true:
 
-- an installed dependency has a non-optional `vitest` peer, whether exact or a
-  range;
+- an installed dependency has a non-optional `vitest` peer, whether exact or a range;
 - the package uses Vitest browser mode or an opt-in browser provider;
 - source or TypeScript configuration retains an upstream `vitest` reference;
 - the package declares `@nuxt/test-utils`; or
-- dependency metadata is unavailable and an existing direct `vitest` might be
-  satisfying an unknown required peer.
+- dependency metadata is unavailable and an existing direct `vitest` might be satisfying an unknown required peer.
 
-Detection reads installed peer metadata, so integrations such as
-`vite-plugin-gherkin` are handled even though their names do not contain
-`vitest`.
+Detection reads installed peer metadata, so integrations such as `vite-plugin-gherkin` are handled even though their names do not contain `vitest`.
 
 When a package qualifies, migration:
 
-- adds `vitest` to that package, not indiscriminately to every workspace
-  package;
-- uses the existing catalog reference when supported, otherwise the exact
-  bundled version; and
-- keeps a matching workspace override or resolution so the graph resolves a
-  single Vitest version.
+- adds `vitest` to that package, not indiscriminately to every workspace package;
+- uses the existing catalog reference when supported, otherwise the exact bundled version; and
+- keeps a matching workspace override or resolution so the graph resolves a single Vitest version.
 
-A peer declaration alone does not install Vitest. If a surviving
-`peerDependencies.vitest` uses a catalog entry that migration will remove, it
-is resolved to the public peer range first.
+A peer declaration alone does not install Vitest. If a surviving `peerDependencies.vitest` uses a catalog entry that migration will remove, it is resolved to the public peer range first.
 
 ### Vitest Ecosystem Packages
 
-Official current `@vitest/*` packages generally publish in lockstep with
-Vitest. Migration aligns the ones the project directly installs, including
-`@vitest/coverage-v8`, `@vitest/coverage-istanbul`, `@vitest/ui`, and
-`@vitest/web-worker`:
+Official current `@vitest/*` packages generally publish in lockstep with Vitest. Migration aligns the ones the project directly installs, including `@vitest/coverage-v8`, `@vitest/coverage-istanbul`, `@vitest/ui`, and `@vitest/web-worker`:
 
-- when the package manager supports catalogs, they are referenced through the
-  toolchain catalog: an existing `catalog:` / `catalog:<name>` reference is
-  preserved, a catalog entry is added for any package that lacks one, and each
-  entry is updated to the bundled Vitest version;
-- when catalogs are unsupported (npm, a standalone bun project, or a
-  pre-catalog pnpm/Yarn), the concrete bundled version is written instead.
+- when the package manager supports catalogs, they are referenced through the toolchain catalog: an existing `catalog:` / `catalog:<name>` reference is preserved, a catalog entry is added for any package that lacks one, and each entry is updated to the bundled Vitest version;
+- when catalogs are unsupported (npm, a standalone bun project, or a pre-catalog pnpm/Yarn), the concrete bundled version is written instead.
 
 Packages that are **not** aligned:
 
 - `@vitest/eslint-plugin` follows its own version line;
-- `@vitest/coverage-c8` stopped at an older release and has no Vitest 4
-  version; and
-- third-party `vitest-*` integrations keep their own compatible versions,
-  though their required Vitest peer may still trigger
-  [direct provisioning](#when-vitest-is-directly-required).
-
-For browser mode, the base `@vitest/browser` runtime and
-`@vitest/browser-preview` are bundled by Vite+ and are removed as direct
-dependencies. The Playwright and WebdriverIO providers stay opt-in: a kept or
-injected provider is referenced through the preferred toolchain catalog at the
-bundled Vitest version (or written concretely when catalogs are unsupported),
-and its `playwright` or `webdriverio` peer is installed alongside.
-
-Providers are detected before imports are rewritten. This covers legacy
-projects that aliased `vitest` to `@voidzero-dev/vite-plus-test` and import
-from `vitest/browser-<provider>`, `vitest/browser/providers/<provider>`, or
-`vitest/plugins/browser-<provider>`: those imports still install the
-corresponding `@vitest/browser-playwright` or `@vitest/browser-webdriverio`
-dependency and its framework peer.
-
-Object-valued nested npm and Bun overrides are preserved: they are
-user-defined scopes rather than scalar version pins.
+- `@vitest/coverage-c8` stopped at an older release and has no Vitest 4 version; and
+- third-party `vitest-*` integrations keep their own compatible versions, though their required Vitest peer may still trigger [direct provisioning](#when-vitest-is-directly-required).
+
+For browser mode, the base `@vitest/browser` runtime and `@vitest/browser-preview` are bundled by Vite+ and are removed as direct dependencies. The Playwright and WebdriverIO providers stay opt-in: a kept or injected provider is referenced through the preferred toolchain catalog at the bundled Vitest version (or written concretely when catalogs are unsupported), and its `playwright` or `webdriverio` peer is installed alongside.
+
+Providers are detected before imports are rewritten. This covers legacy projects that aliased `vitest` to `@voidzero-dev/vite-plus-test` and import from `vitest/browser-<provider>`, `vitest/browser/providers/<provider>`, or `vitest/plugins/browser-<provider>`: those imports still install the corresponding `@vitest/browser-playwright` or `@vitest/browser-webdriverio` dependency and its framework peer.
+
+Object-valued nested npm and Bun overrides are preserved: they are user-defined scopes rather than scalar version pins.
 
 ## Source Rewrite Rules
 
 ### `vite` Imports
 
-`vite` and `vite/*` imports are rewritten to `vite-plus` **only in config
-entry files**: `vite.config.*`, `vitest.config.*`, and any config file the
-migration resolved. Every other file keeps its `vite` imports, for two
-reasons:
-
-- `vite-plus` is not a guaranteed superset of Vite's exposed surface. It owns
-  only `defineConfig`, `defineProject`, and `lazyPlugins`, so rewriting a
-  pass-through symbol such as `createBuilder` or `loadConfigFromFile`
-  (including in `typeof import('vite')` type positions) can break.
-- An unrewritten `vite` import still resolves through the
-  `@voidzero-dev/vite-plus-core` alias in a Vite+ project.
-
-Plugin packages (an unscoped name starting with `vite-plugin-` or
-`unplugin-`, or `vite` in `peerDependencies`/`dependencies`) skip the rewrite
-even in config files. Only the `vite` specifier is in scope for this rule.
-
-`declare module 'vite'` augmentations follow the same rule and are preserved
-outside config files. Through the core alias they reach the same
-`@voidzero-dev/vite-plus-core` module whose `UserConfig` types `defineConfig`
-from `vite-plus`, so they keep working after migration; `vite-plus` itself
-exports no `UserConfig` symbol, so a rewritten `declare module 'vite-plus'`
-augmentation would merge with nothing. Extensions aimed at `vite-plus`'s own
-surface are written against `vite-plus` by hand.
+`vite` and `vite/*` imports are rewritten to `vite-plus` **only in config entry files**: `vite.config.*`, `vitest.config.*`, and any config file the migration resolved. Every other file keeps its `vite` imports, for two reasons:
+
+- `vite-plus` is not a guaranteed superset of Vite's exposed surface. It owns only `defineConfig`, `defineProject`, and `lazyPlugins`, so rewriting a pass-through symbol such as `createBuilder` or `loadConfigFromFile` (including in `typeof import('vite')` type positions) can break.
+- An unrewritten `vite` import still resolves through the `@voidzero-dev/vite-plus-core` alias in a Vite+ project.
+
+Plugin packages (an unscoped name starting with `vite-plugin-` or `unplugin-`, or `vite` in `peerDependencies`/`dependencies`) skip the rewrite even in config files. Only the `vite` specifier is in scope for this rule.
+
+`declare module 'vite'` augmentations follow the same rule and are preserved outside config files. Through the core alias they reach the same `@voidzero-dev/vite-plus-core` module whose `UserConfig` types `defineConfig` from `vite-plus`, so they keep working after migration; `vite-plus` itself exports no `UserConfig` symbol, so a rewritten `declare module 'vite-plus'` augmentation would merge with nothing. Extensions aimed at `vite-plus`'s own surface are written against `vite-plus` by hand.
 
 ### `vitest` and Browser Imports
 
-- Ordinary `vitest` and `vitest/*` imports are rewritten to
-  `vite-plus/test*`.
-- Legacy Playwright and WebdriverIO provider imports are detected before this
-  rewrite so their optional provider dependencies are not lost.
-- Scoped `@vitest/browser*` imports are rewritten to the corresponding
-  `vite-plus/test/browser*` exports, provisioning opt-in providers when
-  needed.
+- Ordinary `vitest` and `vitest/*` imports are rewritten to `vite-plus/test*`.
+- Legacy Playwright and WebdriverIO provider imports are detected before this rewrite so their optional provider dependencies are not lost.
+- Scoped `@vitest/browser*` imports are rewritten to the corresponding `vite-plus/test/browser*` exports, provisioning opt-in providers when needed.
 - Existing `vite-plus/test*` imports are left unchanged.
 
 ### Oxlint JS Plugin Imports
 
-Vite+ bundles Oxlint, so the migration removes a standalone `oxlint`
-dependency. Your own Oxlint JS plugins import the authoring API by name. That
-import stops resolving when the dependency goes away. `vp lint` then fails to
-load the plugin.
+Vite+ bundles Oxlint, so the migration removes a standalone `oxlint` dependency. Your own Oxlint JS plugins import the authoring API by name. That import stops resolving when the dependency goes away. `vp lint` then fails to load the plugin.
 
 The migration repoints those imports at Vite+:
 
 - It rewrites `@oxlint/plugins` to `vite-plus/lint/plugins`.
 - It rewrites `oxlint/plugins-dev` to `vite-plus/lint/plugins-dev`.
-- It rewrites `oxlint` to `vite-plus/lint/plugins` when the import names a
-  binding from the authoring API, such as `defineRule`, `definePlugin`, or
-  `Context`. Older Oxlint releases exposed that API from the main entry. It now
-  lives in `@oxlint/plugins`.
+- It rewrites `oxlint` to `vite-plus/lint/plugins` when the import names a binding from the authoring API, such as `defineRule`, `definePlugin`, or `Context`. Older Oxlint releases exposed that API from the main entry. It now lives in `@oxlint/plugins`.
 
-An import through Vite+ always matches the version of Oxlint that Vite+
-bundles. You pin no second package. The import also resolves from any package
-that already depends on `vite-plus`.
+An import through Vite+ always matches the version of Oxlint that Vite+ bundles. You pin no second package. The import also resolves from any package that already depends on `vite-plus`.
 
 The migration leaves three forms alone:
 
-- `oxlint` imports that name only the config surface, such as `defineConfig`,
-  `OxlintConfig`, or `OxlintOverride`. These still resolve against the
-  standalone package.
-- Default and namespace `oxlint` imports. They name no binding, so the
-  migration cannot tell the two surfaces apart.
+- `oxlint` imports that name only the config surface, such as `defineConfig`, `OxlintConfig`, or `OxlintOverride`. These still resolve against the standalone package.
+- Default and namespace `oxlint` imports. They name no binding, so the migration cannot tell the two surfaces apart.
 - Bare side-effect `oxlint` imports, for the same reason.
 
-The migration also skips a package that declares `oxlint` or `@oxlint/plugins`
-in `dependencies` or `peerDependencies`, or `@oxlint/plugins` in
-`optionalDependencies`. These dependencies can supply a published Oxlint plugin.
-Its consumers may not run Vite+.
+The migration also skips a package that declares `oxlint` or `@oxlint/plugins` in `dependencies` or `peerDependencies`, or `@oxlint/plugins` in `optionalDependencies`. These dependencies can supply a published Oxlint plugin. Its consumers may not run Vite+.
 
-The cleanup retains a development dependency on `@oxlint/plugins` when source,
-package import aliases, or built plugins still reference it. This includes
-ignored output in directories such as `dist`, `build`, and `out`.
+The cleanup retains a development dependency on `@oxlint/plugins` when source, package import aliases, or built plugins still reference it. This includes ignored output in directories such as `dist`, `build`, and `out`.
 
 ### What Is Never Rewritten
 
-- `declare module 'vitest'` and `declare module '@vitest/browser*'`: module
-  augmentation must retain the upstream module identity.
-- References that stay behind, such as `compilerOptions.types`,
-  `require.resolve`, `import.meta.resolve`, and `vitest/package.json`,
-  require package-local Vitest (see
-  [When Vitest Is Directly Required](#when-vitest-is-directly-required)).
-- In a package that declares `@nuxt/test-utils`, every `vitest` and
-  `vitest/*` module specifier is preserved package-wide: the Nuxt transform
-  requires the upstream identity and can otherwise inject a duplicate `vi`
-  import. This exception does not apply to sibling packages or to scoped
-  `@vitest/browser*` imports.
-
-The `prefer-vite-plus-imports` lint rule follows the same Nuxt exception, so
-lint autofix preserves these imports too.
+- `declare module 'vitest'` and `declare module '@vitest/browser*'`: module augmentation must retain the upstream module identity.
+- References that stay behind, such as `compilerOptions.types`, `require.resolve`, `import.meta.resolve`, and `vitest/package.json`, require package-local Vitest (see [When Vitest Is Directly Required](#when-vitest-is-directly-required)).
+- In a package that declares `@nuxt/test-utils`, every `vitest` and `vitest/*` module specifier is preserved package-wide: the Nuxt transform requires the upstream identity and can otherwise inject a duplicate `vi` import. This exception does not apply to sibling packages or to scoped `@vitest/browser*` imports.
+
+The `prefer-vite-plus-imports` lint rule follows the same Nuxt exception, so lint autofix preserves these imports too.
 
 ## Package Script Rewrite Rules
 
-Migration rewrites commands provided by the Vite+ toolchain in `package.json`
-scripts while preserving their arguments:
+Migration rewrites commands provided by the Vite+ toolchain in `package.json` scripts while preserving their arguments:
 
 | Before        | After                                       |
 | ------------- | ------------------------------------------- |
@@ -322,10 +186,7 @@ scripts while preserving their arguments:
 | `prettier`    | `vp fmt`, when its optional migration runs  |
 | `tsup`        | `vp pack`, when its optional migration runs |
 
-For commands launched through `bunx`, migration preserves `bunx` and its
-`--bun` flag (keeping the user's chosen runtime) and rewrites only the managed
-command. This also works when `bunx` follows a command-launcher delimiter such
-as `run` or `--`:
+For commands launched through `bunx`, migration preserves `bunx` and its `--bun` flag (keeping the user's chosen runtime) and rewrites only the managed command. This also works when `bunx` follows a command-launcher delimiter such as `run` or `--`:
 
 | Before                                                  | After                                                    |
 | ------------------------------------------------------- | -------------------------------------------------------- |
@@ -338,112 +199,54 @@ Unrelated `bunx` commands and other package-executor forms remain unchanged.
 
 ## Continuous Integration Rules
 
-Migration replaces exact `voidzero-dev/setup-vp@v1` references in GitHub
-Actions workflows and composite actions under `.github` with the latest exact
-`setup-vp` release known to that Vite+ version. The frozen `v1` tag does not
-receive new releases. Existing exact versions and commit SHAs are left
-unchanged.
+Migration replaces exact `voidzero-dev/setup-vp@v1` references in GitHub Actions workflows and composite actions under `.github` with the latest exact `setup-vp` release known to that Vite+ version. The frozen `v1` tag does not receive new releases. Existing exact versions and commit SHAs are left unchanged.
 
 ## Node.js Version Rules
 
-Migration converts legacy Node.js version-manager files to `.node-version`,
-the format Vite+ reads. On an existing Vite+ project this conversion is part
-of the full setup bucket, so it runs with `vp migrate --full`; fresh
-migrations run it unconditionally.
+Migration converts legacy Node.js version-manager files to `.node-version`, the format Vite+ reads. On an existing Vite+ project this conversion is part of the full setup bucket, so it runs with `vp migrate --full`; fresh migrations run it unconditionally.
 
-- `.nvmrc` and Volta `volta.node` pins are converted to `.node-version`. An
-  existing `.node-version` is kept.
-- When `.nvmrc` is removed, any `actions/setup-node` `node-version-file:
-.nvmrc` reference in `.github/workflows/*.{yml,yaml}` and composite actions
-  under `.github` (`.github/**/action.{yml,yaml}`) is repointed to
-  `.node-version` so CI does not fail with "node version file ... does not
-  exist".
+- `.nvmrc` and Volta `volta.node` pins are converted to `.node-version`. An existing `.node-version` is kept.
+- When `.nvmrc` is removed, any `actions/setup-node` `node-version-file: .nvmrc` reference in `.github/workflows/*.{yml,yaml}` and composite actions under `.github` (`.github/**/action.{yml,yaml}`) is repointed to `.node-version` so CI does not fail with "node version file ... does not exist".
 
 ## Package-Manager Rules
 
 ### pnpm
 
-**Root settings location.** pnpm 10.6.2+ uses `pnpm-workspace.yaml` as the
-single source for supported root settings. Migration moves recognized
-`package.json#pnpm` fields there, including overrides, peer rules, patch
-settings, package extensions, architecture and build policy, audit/update
-configuration, and configuration dependencies. It removes the `pnpm` object
-when it becomes empty and preserves unknown keys that may belong to other
-tooling.
-
-- When both files define the same migrated setting, object entries are merged
-  recursively and unique array entries are retained. Values from
-  `package.json#pnpm` win at conflicting scalar leaves, while workspace-only
-  sibling entries are preserved.
-- Before pnpm 10.6.2, these settings stay in `package.json#pnpm`. (Workspace
-  settings support arrived incrementally: 10.5.0 in general, 10.5.1 for
-  overrides, 10.6.2 for `peerDependencyRules`. pnpm 11 no longer reads the
-  legacy `package.json` settings.)
-
-**Catalogs.** Catalogs are a separate feature, supported from pnpm 9.5.0,
-independent of the settings boundary above. Even below 10.6.2, where
-overrides stay in `package.json#pnpm`, migration still rewrites the workspace
-catalog off stale wrapper aliases and keeps `catalog:` overrides as
-references rather than inlining them to concrete versions.
-
-- Dependency references, default and named catalogs, overrides, and
-  `peerDependencyRules` are kept consistent with each other.
-- pnpm accepts the logical default catalog as either top-level `catalog` or
-  `catalogs.default`, but not both. Migration preserves the existing form and
-  never creates the other form beside it.
-- When an existing named catalog already owns `vite-plus`, `vite`, or
-  `vitest`, migration reuses that managed toolchain catalog for newly added
-  dependencies and overrides. It creates a top-level default catalog only
-  when no managed or default catalog can be reused.
+**Root settings location.** pnpm 10.6.2+ uses `pnpm-workspace.yaml` as the single source for supported root settings. Migration moves recognized `package.json#pnpm` fields there, including overrides, peer rules, patch settings, package extensions, architecture and build policy, audit/update configuration, and configuration dependencies. It removes the `pnpm` object when it becomes empty and preserves unknown keys that may belong to other tooling.
+
+- When both files define the same migrated setting, object entries are merged recursively and unique array entries are retained. Values from `package.json#pnpm` win at conflicting scalar leaves, while workspace-only sibling entries are preserved.
+- Before pnpm 10.6.2, these settings stay in `package.json#pnpm`. (Workspace settings support arrived incrementally: 10.5.0 in general, 10.5.1 for overrides, 10.6.2 for `peerDependencyRules`. pnpm 11 no longer reads the legacy `package.json` settings.)
+
+**Catalogs.** Catalogs are a separate feature, supported from pnpm 9.5.0, independent of the settings boundary above. Even below 10.6.2, where overrides stay in `package.json#pnpm`, migration still rewrites the workspace catalog off stale wrapper aliases and keeps `catalog:` overrides as references rather than inlining them to concrete versions.
+
+- Dependency references, default and named catalogs, overrides, and `peerDependencyRules` are kept consistent with each other.
+- pnpm accepts the logical default catalog as either top-level `catalog` or `catalogs.default`, but not both. Migration preserves the existing form and never creates the other form beside it.
+- When an existing named catalog already owns `vite-plus`, `vite`, or `vitest`, migration reuses that managed toolchain catalog for newly added dependencies and overrides. It creates a top-level default catalog only when no managed or default catalog can be reused.
 
 **Other rules.**
 
-- Each package that declares `vite-plus` also gets a direct `vite` dev
-  dependency (see [Vite and Overrides](#vite-and-overrides)).
+- Each package that declares `vite-plus` also gets a direct `vite` dev dependency (see [Vite and Overrides](#vite-and-overrides)).
 - Unrelated selector-shaped and object-valued overrides are preserved.
 
 ### npm
 
-- Direct aliases are normalized before the matching override is added, so npm
-  does not fail with `EOVERRIDE`.
-- When a real Vite installation changes to the core alias, stale Vite install
-  and lockfile state is removed before reinstalling.
-- Opt-in browser-provider layouts get a top-level `vite` edge when nested
-  Vitest packages otherwise cannot resolve it.
+- Direct aliases are normalized before the matching override is added, so npm does not fail with `EOVERRIDE`.
+- When a real Vite installation changes to the core alias, stale Vite install and lockfile state is removed before reinstalling.
+- Opt-in browser-provider layouts get a top-level `vite` edge when nested Vitest packages otherwise cannot resolve it.
 
 ### Yarn
 
-- Vite+ does not support Plug'n'Play. Migration detects explicit and implicit
-  PnP and converts the project to `nodeLinker: node-modules`, preserving all
-  unrelated `.yarnrc.yml` settings. `--no-interactive` accepts the
-  conversion; a process-level `YARN_NODE_LINKER=pnp` must be fixed by the
-  caller.
+- Vite+ does not support Plug'n'Play. Migration detects explicit and implicit PnP and converts the project to `nodeLinker: node-modules`, preserving all unrelated `.yarnrc.yml` settings. `--no-interactive` accepts the conversion; a process-level `YARN_NODE_LINKER=pnp` must be fixed by the caller.
 - Catalog references and user hoisting settings are preserved.
-- Migration avoids split Vitest copies under workspace hoisting isolation: it
-  applies a package-level fix where possible and warns when the isolation
-  cannot be changed safely.
+- Migration avoids split Vitest copies under workspace hoisting isolation: it applies a package-level fix where possible and warns when the isolation cannot be changed safely.
 
 ### Bun
 
-- Bun catalogs only resolve inside a workspace (a root `package.json` with a
-  non-empty `workspaces`). In a bun workspace, existing top-level or
-  workspace catalog locations and named catalog references are preserved. A
-  standalone (single-package) bun project keeps concrete specs and gets no
-  catalog field, because `bun install` cannot resolve `catalog:` outside a
-  workspace.
-- The core alias is mirrored as a direct `vite` dependency so Bun sees the
-  peer provider before applying overrides.
+- Bun catalogs only resolve inside a workspace (a root `package.json` with a non-empty `workspaces`). In a bun workspace, existing top-level or workspace catalog locations and named catalog references are preserved. A standalone (single-package) bun project keeps concrete specs and gets no catalog field, because `bun install` cannot resolve `catalog:` outside a workspace.
+- The core alias is mirrored as a direct `vite` dependency so Bun sees the peer provider before applying overrides.
 
 ## After the Migration
 
-- Each Vite config is inspected for Rolldown-incompatible patterns (such as
-  `manualChunks`). Anything found is reported as a warning; the config is not
-  changed.
-- Dependencies are reinstalled once to refresh the lockfile. If installation
-  fails, migration reports the error and exits with a nonzero status.
-- After a successful migration, `vp fmt` runs on the files changed during
-  migration, excluding paths that were already dirty in the Git worktree.
-  Oxfmt selects the supported formats; non-Git projects retain full-project
-  formatting. Formatting is skipped while the project still uses Prettier. A
-  formatter failure is reported as a warning so the migration result and the
-  manual formatting command remain available.
+- Each Vite config is inspected for Rolldown-incompatible patterns (such as `manualChunks`). Anything found is reported as a warning; the config is not changed.
+- Dependencies are reinstalled once to refresh the lockfile. If installation fails, migration reports the error and exits with a nonzero status.
+- After a successful migration, `vp fmt` runs on the files changed during migration, excluding paths that were already dirty in the Git worktree. Oxfmt selects the supported formats; non-Git projects retain full-project formatting. Formatting is skipped while the project still uses Prettier. A formatter failure is reported as a warning so the migration result and the manual formatting command remain available.

package/docs/guide/migrate.md

@@ -22,9 +22,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,8 +51,7 @@ 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`.
 
@@ -72,40 +69,6 @@ After running the migration:
 - Run `vp test`
 - Run `vp build` (or `vp pack` if you are building a library)
 
-## Manual Installation & Migration
-
-If you are manually migrating a project to Vite+, install these dev dependencies first:
-
-```bash
-vp install -D vite-plus
-```
-
-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):
-
-```json
-"overrides": {
-  "vite": "npm:@voidzero-dev/vite-plus-core@latest",
-  "vitest": "4.1.11"
-}
-```
-
-If you are using `pnpm`, add this to your `pnpm-workspace.yaml`:
-
-```yaml
-overrides:
-  vite: npm:@voidzero-dev/vite-plus-core@latest
-  vitest: 4.1.11
-```
-
-Or, if you are using Yarn:
-
-```json
-"resolutions": {
-  "vite": "npm:@voidzero-dev/vite-plus-core@latest",
-  "vitest": "4.1.11"
-}
-```
-
 ## Migration Prompt
 
 If you want to hand this work to a coding agent (or the reader is a coding agent!), use this migration prompt:
@@ -205,19 +168,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/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`.