vite-plus 1.4.0 → 1.5.1

package/docs/guide/local-cli.md

@@ -87,6 +87,27 @@ overrides:
 
 :::
 
+::: warning Existing direct dependencies with npm
+If your npm project already lists `vite` in `dependencies` or `devDependencies`, change that entry to the same alias as `overrides.vite`. npm requires a direct dependency and its override to use the [same dependency specification](https://docs.npmjs.com/cli/v11/configuring-npm/package-json/#overrides). Otherwise, `npm install` fails with `EOVERRIDE`.
+
+For example, update an existing `vite` development dependency as follows. Keep the other dependencies in your manifest:
+
+```json [package.json]
+{
+  "devDependencies": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@<vite-plus-version>",
+    "vite-plus": "<vite-plus-version>"
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@<vite-plus-version>",
+    "vitest": "<vitest-version>"
+  }
+}
+```
+
+If you also declare `vitest` directly, set its dependency entry to the exact version in `overrides.vitest`. Run `npm install` after these changes to update the lockfile and installed dependencies.
+:::
+
 ::: details Why are these settings needed?
 
 Dependencies and plugins can import `vite` or `vitest` directly, even when your own code imports from `vite-plus`. These overrides align their dependencies with the toolchain Vite+ uses:
@@ -127,7 +148,7 @@ The project-local CLI can be used independently for:
 - [`vp pack`](/guide/pack) with tsdown
 - [`vp toolchain`](/guide/upgrade#show-the-toolchain) for inspecting the versions bundled with the project-local package
 - [`vp run`](/guide/run) and task caching across workspaces
-- [package-manager commands](/guide/package-management) using the Node.js runtime already active in your shell
+- [package-manager commands](/guide/package-management/) using the Node.js runtime already active in your shell
 - [`vp create`](/guide/create), [`vp migrate`](/guide/migrate), and project configuration commands
 
 The local package cannot manage the machine-level Vite+ installation. The `vp env`, `vp upgrade`, and `vp implode` commands require the [global CLI](/guide/global-cli). Upgrade or remove a local-only installation through your package manager.

package/docs/guide/migrate-rules.md

@@ -200,7 +200,7 @@ Object-valued nested npm and Bun overrides are preserved: they are user-defined
 
 `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.
+- `vite-plus` is not a guaranteed superset of Vite's exposed surface. It owns only `defineConfig`, `defineProject`, `lazyPlugins`, and `resolveConfigFromFile`, 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.
@@ -250,18 +250,20 @@ The `prefer-vite-plus-imports` lint rule follows the same Nuxt exception, so lin
 
 Migration rewrites commands provided by the Vite+ toolchain in `package.json` scripts while preserving their arguments:
 
-| Before        | After                                       |
-| ------------- | ------------------------------------------- |
-| `vite`        | `vp dev`, or the matching `vp` subcommand   |
-| `vitest`      | `vp test`                                   |
-| `oxlint`      | `vp lint`                                   |
-| `oxfmt`       | `vp fmt`                                    |
-| `tsdown`      | `vp pack`                                   |
-| `lint-staged` | `vp staged`                                 |
-| `eslint`      | `vp lint`, when its optional migration runs |
-| `prettier`    | `vp fmt`, when its optional migration runs  |
-| `tsup`        | `vp pack`, when its optional migration runs |
-| `tsx`         | `vpx`, when its optional migration runs     |
+| Before        | After                                        |
+| ------------- | -------------------------------------------- |
+| `vite`        | `vp dev`, or the matching `vp` subcommand    |
+| `vitest`      | `vp test`                                    |
+| `oxlint`      | `vp lint`                                    |
+| `oxfmt`       | `vp fmt`                                     |
+| `tsdown`      | `vp pack`                                    |
+| `lint-staged` | `vp staged`                                  |
+| `eslint`      | `vp lint`, when its optional migration runs  |
+| `prettier`    | `vp fmt`, when its optional migration runs   |
+| `tsup`        | `vp pack`, when its optional migration runs  |
+| `tsx`         | `vpx`, when its optional migration runs      |
+| `oxnode`      | `vpx`, when its optional migration runs      |
+| `ts-node`     | `vpx`, for supported transpile-only commands |
 
 For commands launched through `bunx`, migration preserves `bunx` and its `--bun` flag (keeping the user's chosen runtime) and rewrites only the managed command. tsx is the exception: `bunx tsx` becomes `vpx`, and `bunx --bun tsx` keeps tsx (see [tsx to `vpx`](#tsx-to-vpx)). This also works when `bunx` follows a command-launcher delimiter such as `run` or `--`:
 
@@ -278,23 +280,80 @@ Unrelated `bunx` commands and other package-executor forms remain unchanged.
 
 When a `package.json` script, a lint-staged task, or a `#!/usr/bin/env tsx` shebang runs [tsx](https://tsx.is), migration offers to move it to [`vpx`](/guide/vpx), Vite+'s TypeScript script runner. It rewrites scripts and lint-staged tasks in `package.json` and JSON lint-staged files, and `#!/usr/bin/env tsx` shebangs in script files:
 
-| Before                                                                     | After                                      |
-| -------------------------------------------------------------------------- | ------------------------------------------ |
-| `tsx src/seed.ts --rows 10`                                                | `vpx src/seed.ts --rows 10`                |
-| `tsx watch --include "*.json" src/a.ts`                                    | `vpx --watch --include "*.json" src/a.ts`  |
-| `npx tsx a.ts`, `pnpm exec tsx a.ts`, `pnpm dlx tsx a.ts`, `bunx tsx a.ts` | `vpx a.ts`                                 |
-| `node --import tsx ./a.ts`                                                 | `vpx ./a.ts`                               |
-| `cross-env NODE_ENV=dev tsx a.ts`                                          | `cross-env NODE_ENV=dev vpx a.ts`          |
-| `concurrently "tsx watch a.ts" "vp dev"`                                   | `concurrently "vpx --watch a.ts" "vp dev"` |
+| Before                                                                     | After                                              |
+| -------------------------------------------------------------------------- | -------------------------------------------------- |
+| `tsx src/seed.ts --rows 10`                                                | `vpx src/seed.ts --rows 10`                        |
+| `tsx watch --include "*.json" src/a.ts`                                    | `vpx --watch --include "*.json" src/a.ts`          |
+| `npx tsx a.ts`, `pnpm exec tsx a.ts`, `pnpm dlx tsx a.ts`, `bunx tsx a.ts` | `vpx a.ts`                                         |
+| `node --import tsx ./a.ts`                                                 | `node --import vite-plus/register ./a.ts`          |
+| `node --import=tsx --test`                                                 | `node --import=vite-plus/register --test`          |
+| `NODE_OPTIONS='--import tsx' mocha`                                        | `NODE_OPTIONS='--import vite-plus/register' mocha` |
+| `cross-env NODE_ENV=dev tsx a.ts`                                          | `cross-env NODE_ENV=dev vpx a.ts`                  |
+| `concurrently "tsx watch a.ts" "vp dev"`                                   | `concurrently "vpx --watch a.ts" "vp dev"`         |
 
 `tsx watch` becomes `vpx --watch`, never `vpx watch`, which runs the npm package `watch`. Node.js options and tsx watch options keep their order, and `--no-cache` is dropped. A quoted command is rewritten only for programs that run it, such as `concurrently`, `nodemon --exec`, `sh -c`, and `cross-env-shell`; a quoted argument of other programs, as in `echo "tsx a.ts"`, is data. `vpx` needs the same Node.js versions as Vite+ itself, and migration already upgrades incompatible runtime pins to them (see [Vitest 5](/guide/vitest-v5)).
 
-Migration keeps tsx, with a warning, for a command `vpx` cannot run: `--eval`, `--print`, or `--check`, the REPL, `--test` without files or in watch mode, an entry without a file extension, commands that set `TSX_TSCONFIG_PATH` (pass `--tsconfig` to `vpx` instead) or load tsx through `NODE_OPTIONS`, and commands with pipes, variables, or subshells. It also reads the scripts a command runs, including local `--require` and `--import` modules, and keeps tsx when one does not exist yet, as when an earlier command generates it, and when `vpx` would fail on one: a `require()` of `./a.js` that only tsx resolves to `a.ts`, and, because tsx compiles ES module syntax to CommonJS, a `.cts` file with `import` or `export`, and a file that mixes `import` with `__dirname`, `__filename`, `require()`, or `module.exports` in a package without `"type": "module"`. This check skips globs and scripts after a `cd` or another shell state change, and reads only the files a command names, not the modules they import. It does not look for what else `vpx` handles differently, such as standard decorators, tsconfig `paths` in `require()`, or a tsconfig `module` of `node16` or `nodenext`; `vpx` reports those when the script runs. A package that lists tsx in `dependencies`, `optionalDependencies`, or `peerDependencies` keeps it too, since `vpx` comes from the `vite-plus` devDependency.
+The plain `node --import tsx` and `node --import=tsx` forms keep Node.js, its options, wrappers, and arguments. They use [`vite-plus/register`](/guide/vpx#using-nodejs-directly), so Node.js retains its eval, test discovery, and native watch behavior. Literal `NODE_OPTIONS` assignments also migrate, including assignments through `cross-env` and known command launchers. `vite-plus/register` accepts `TSX_TSCONFIG_PATH` as a fallback. Assignments that also load a legacy tsx hook, or reach a command that still needs tsx, stay unchanged.
+
+For the tsx executable and legacy loader forms such as `--loader tsx/esm` and `-r tsx/cjs`, migration keeps the existing `vpx` rules. It keeps tsx, with a warning, for `--eval`, `--print`, or `--check`, the REPL, `--test` without files or in watch mode, an entry without a file extension, or commands that load tsx through `NODE_OPTIONS`. Commands with pipes, variables, or subshells also stay unchanged. `vpx` accepts `TSX_TSCONFIG_PATH` as a fallback too; an explicit `--tsconfig` takes priority.
+
+Both migration paths read the scripts a command names, including local `--require` and `--import` modules. They keep tsx when a script does not exist yet, as when an earlier command generates it, or when the Vite+ loader would fail on it: a `require()` of `./a.js` that only tsx resolves to `a.ts`, a `.cts` file with `import` or `export`, or a file that mixes `import` with `__dirname`, `__filename`, `require()`, or `module.exports` in a package without `"type": "module"`. This check skips globs and scripts after a `cd` or another shell state change, and reads only the files a command names, not the modules they import. It does not look for other compiler differences, such as standard decorators, tsconfig `paths` in `require()`, or a tsconfig `module` of `node16` or `nodenext`; the loader reports those when the script runs. A package that lists tsx in `dependencies`, `optionalDependencies`, or `peerDependencies` keeps it too, since the replacement comes from the `vite-plus` devDependency.
 
 Migration removes the `tsx` devDependency only when nothing uses tsx anymore: no kept script, no import of `tsx` or its subpaths such as `tsx/esm/api` (in source, build output, or a `package.json` `imports` alias), no shebang, no tool setting such as `--import=tsx` in `package.json` or a JSON or JavaScript config, and no tsx command in CI workflows, git hooks, or shell scripts. The root's dependency stays while any workspace package still uses tsx, and a package's dependency stays while a nested package under it does. When tsx stays, the warning names what still uses it.
 
+Tool configurations and source files need manual edits. For example, change `nodeArguments: ['--import=tsx']` to `nodeArguments: ['--import=vite-plus/register']`, or Mocha's `"import": "tsx"` setting to `"import": "vite-plus/register"`. Keep tsx if the project uses its programmatic APIs.
+
 See [Coming from tsx](/guide/vpx#coming-from-tsx) for the other differences.
 
+### oxnode to `vpx`
+
+Migration offers to replace `oxnode`, the command from `@oxc-node/cli`, with `vpx`. It rewrites `package.json` scripts, lint-staged tasks in `package.json` and JSON files, and `#!/usr/bin/env oxnode` shebangs. Node.js preload shebangs such as `#!/usr/bin/env -S node --import @oxc-node/core/register` keep Node.js and use `vite-plus/register`, including in extensionless scripts. The migration preserves the shebang's `env` syntax, flags, and relative paths. On a project that already uses Vite+, run `vp migrate --full` to include this migration.
+
+| Before                                                    | After                                                |
+| --------------------------------------------------------- | ---------------------------------------------------- |
+| `oxnode ./scripts/seed.ts`                                | `vpx ./scripts/seed.ts`                              |
+| `oxnode -C dev ./build.ts`                                | `vpx -C dev ./build.ts`                              |
+| `oxnode watch --include "config/*.json" ./server.ts`      | `vpx --watch --include "config/*.json" ./server.ts`  |
+| `node --import @oxc-node/core/register ./scripts/seed.ts` | `node --import vite-plus/register ./scripts/seed.ts` |
+| `NODE_OPTIONS='--import @oxc-node/core/register' mocha`   | `NODE_OPTIONS='--import vite-plus/register' mocha`   |
+
+The `node --import @oxc-node/core/register` and `register.mjs` forms keep Node.js, its wrappers, arguments, and native watch, eval, and test modes. Literal `NODE_OPTIONS` assignments also use the public preload. Commands that use the `oxnode` executable follow the `vpx` rules instead: `oxnode --watch` stays unchanged because it starts Node.js's watcher, while `oxnode watch` and `vpx --watch` use oxc-node's watcher.
+
+Commands that explicitly set `OXC_TRANSFORM_ALL` to anything other than `typescript` stay unchanged. Nonempty `VP_SCRIPT_TSCONFIG` and `TSX_TSCONFIG_PATH` assignments also stay unchanged because they would change config selection. Commands that read an environment file stay unchanged because it can select a different transform mode. Migration checks the named script and local preloads for standalone oxc-node API usage, which would configure a different loader after migration; it does not follow their imports.
+
+Custom asynchronous `--loader` and `--experimental-loader` hooks stay in their original order when the register import changes. This supports project loaders for resolution and assets alongside the Vite+ TypeScript loader. It does not establish compatibility with a second TypeScript transformer or arbitrary synchronous `module.registerHooks()` chains.
+
+Direct `oxnode` commands and Node.js preload commands stay unchanged when an additional `--require` or `--import` can change loader settings. Node.js commands also stay unchanged when inline code still calls standalone oxc-node APIs. Migration checks explicit local shebang loaders relative to the owning package for standalone API references, without following their imports. It leaves the paths unchanged: at runtime, relative loader paths use the caller's working directory, not the script's directory.
+
+The `@oxc-node/cli` and `@oxc-node/core` development dependencies are removed only when no remaining use needs them. Loader references, API imports, CI commands, hooks, and shell scripts can keep these dependencies installed. Migration also checks files named by `--env-file` and `--env-file-if-exists`, regardless of their filename. If it cannot resolve or read an environment file, it keeps the dependencies for manual review. Runtime and peer dependencies stay in place.
+
+### ts-node to `vpx`
+
+Migration offers to replace supported ts-node commands with `vpx` only when type-checking is explicitly disabled. Plain `ts-node` type-checks before execution; `vpx` does not. Commands that still type-check stay unchanged with a warning, even when another option enables transpile-only mode.
+
+| Before                                                                            | After                                                               |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `ts-node --transpileOnly ./scripts/seed.ts`                                       | `vpx ./scripts/seed.ts`                                             |
+| `ts-node -T -P tsconfig.scripts.json ./scripts/seed.ts`                           | `vpx --tsconfig=tsconfig.scripts.json ./scripts/seed.ts`            |
+| `ts-node-transpile-only ./scripts/seed.ts`                                        | `vpx ./scripts/seed.ts`                                             |
+| `node -r ts-node/register/transpile-only ./scripts/seed.ts`                       | `node --import vite-plus/register ./scripts/seed.ts`                |
+| `node --loader ts-node/esm/transpile-only ./scripts/seed.ts`                      | `node --import vite-plus/register ./scripts/seed.ts`                |
+| `NODE_OPTIONS='--require ts-node/register/transpile-only' node ./scripts/seed.ts` | `NODE_OPTIONS='--import vite-plus/register' node ./scripts/seed.ts` |
+
+The migration also reads `transpileOnly` and `typeCheck` from local JSONC tsconfig files, local `extends` chains, and literal `TS_NODE_TRANSPILE_ONLY` / `TS_NODE_TYPE_CHECK` assignments. `-P`, `--project`, and `TS_NODE_PROJECT` select the configuration. A directory passed to `-P` or `--project` resolves to its `tsconfig.json`; a directory in `TS_NODE_PROJECT` stays unchanged. When ts-node discovers a config implicitly, migration pins that file with `--tsconfig` so `vpx` uses it for the whole run. `ts-node-esm` and `--esm` are supported when type-checking is disabled.
+
+If an existing config and its local `extends` chain omit both `target` and `useDefineForClassFields`, the command stays unchanged with a warning. ts-node defaults to assignment semantics for class fields in this case, while `vpx` defaults to define semantics. Set `compilerOptions.useDefineForClassFields` to `false` to preserve assignment semantics before migrating.
+
+Supported Node.js preload commands keep Node.js and replace both the old loader option and module with `--import vite-plus/register`. Literal `NODE_OPTIONS` assignments also migrate when they reach a known `node` command and pass the same checks. An existing `TS_NODE_PROJECT` file selection stays in place. A preload that needs an implicit config pinned stays unchanged: set `TS_NODE_PROJECT` to the config file before migration, because Node.js cannot take `--tsconfig`.
+
+Preloads also stay unchanged when the working directory has no config but the entry file would discover a different one. Migration does not scan imported modules for additional config files.
+
+Custom compilers, transpilers, SWC, ts-node compiler overrides, unsupported configuration inheritance, eval, and REPL usage stay unchanged. Environment files, Node.js config files, additional preloads, and unsupported `NODE_OPTIONS` assignments also keep the original command because they can change ts-node settings before registration. Nonempty `VP_SCRIPT_TSCONFIG`, `TSX_TSCONFIG_PATH`, or `OXC_TSCONFIG_PATH` assignments stay unchanged because they would select a different config. Migration checks named scripts for known module incompatibilities; it does not follow their imports. Migrated scripts use the [tsconfig and module rules of `vpx`](/guide/vpx#tsconfig).
+
+Entries with static imports or re-exports of CommonJS values also stay unchanged. This includes named, namespace, and default bindings, `.js` files in CommonJS packages, and package entry points. Migration checks both import and require resolution without executing dependencies. Unresolved targets and targets that differ between these modes stay unchanged for manual review. Even `esModuleInterop: true` can unwrap a CommonJS `__esModule.default` value differently from Node.js, so that setting alone does not make a default import safe. Type-only imports and exports, imports used only for side effects, checked ES module targets, and named Node.js built-in bindings do not trigger this check.
+
+As with oxnode, migration rewrites package scripts, JSON lint-staged tasks, and supported env shebangs. Shebangs that need a pinned config stay unchanged because the config path depends on the caller's working directory. Existing Vite+ projects use `vp migrate --full`. The `ts-node` development dependency is removed only when no remaining command, loader, API import, or config reference needs it. Runtime and peer dependencies remain, and `typescript` is not removed.
+
 ## 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.

package/docs/guide/migrate.md

@@ -8,7 +8,7 @@ import { migrationPrompt, upgradePrompt } from '../.vitepress/theme/data/migrati
 
 ## Overview
 
-This command is the starting point for consolidating separate Vite, Vitest, Oxlint, Oxfmt, ESLint, Prettier, tsdown, tsup, and tsx setups into Vite+.
+This command is the starting point for consolidating separate Vite, Vitest, Oxlint, Oxfmt, ESLint, Prettier, tsdown, tsup, tsx, oxnode, and ts-node 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.
 
@@ -95,21 +95,21 @@ Upgrade the [global CLI](./upgrade.md#global-vp) to your target 1.0 release, the
 
 ### 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.4.0` release:
+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.5.1` release:
 
 ::: code-group
 
 ```bash [pnpm]
-pnpm dlx --package=vite-plus@1.4.0 vp migrate --no-interactive
+pnpm dlx --package=vite-plus@1.5.1 vp migrate --no-interactive
 ```
 
 ```bash [npm]
-npx --package=vite-plus@1.4.0 vp migrate --no-interactive
+npx --package=vite-plus@1.5.1 vp migrate --no-interactive
 ```
 
 :::
 
-Replace `1.4.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.
+Replace `1.5.1` 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:
 
@@ -151,7 +151,7 @@ View and copy this prompt into your coding agent to upgrade an existing Vite+ 0.
 
 ### Vitest
 
-Vitest is automatically migrated through `vp migrate`. `vite-plus` re-exports upstream `vitest@5.0.5` 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.1.0` under `vite-plus/test*`, so for node-mode tests a single `vite-plus` install is enough — you no longer need to install `vitest` directly.
 
 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`).
 
@@ -234,11 +234,11 @@ 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/commit-hooks) and [Staged Config](/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/commit-hooks).
 
 Existing project-owned Vite+ hooks are also preserved. The default staged workflow is introduced only when no existing hook policy is found.
 
@@ -246,7 +246,7 @@ If your project currently uses `lefthook`, `simple-git-hooks`, or `yorkie`, `vp
 
 If you want to move one of those tools over to Vite+ manually, you can follow these steps. First, move your staged-file commands into the `staged` block within `vite.config.ts`. Then, update your lifecycle script so it runs `vp config`. You will also need to create a Vite+ hook at `.vite-hooks/pre-commit` that runs `vp staged`. Run `vp hooks enable` (or `vp config`) to install the dispatcher and set `core.hooksPath`. Finally, once you have confirmed that the Vite+ hook is working as expected, you can remove the old tool's configuration and dependency.
 
-Use `vp hooks status` to verify the dispatcher is active, and `vp hooks disable` if you need to turn it off again in this clone. You can find more details about the full Vite+ hook setup in the [Commit hooks guide](/guide/commit-hooks).
+Use `vp hooks status` to verify the dispatcher is active, and `vp hooks disable` if you need to turn it off again in this clone. You can find more details about the full Vite+ hook setup in the [Commit Hooks](/guide/commit-hooks).
 
 ## Examples
 

package/docs/guide/package-management/add.md

@@ -0,0 +1,84 @@
+# vp add
+
+Add packages to the project and update its manifest and lockfile.
+
+```bash
+vp add react
+vp add -D typescript
+vp add --save-peer react
+vp add --filter web react
+```
+
+## Options
+
+Choose one dependency target at a time. Peer dependencies follow the native manager's behavior, including whether it also records a development dependency.
+
+| Option                       | Description                                            | Notes                                                                          |
+| ---------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| `-P, --save-prod`            | Save to dependencies, the default target.              | Choose one dependency target.                                                  |
+| `-D, --save-dev`             | Save to devDependencies.                               | Choose one dependency target.                                                  |
+| `--save-peer`                | Request the manager's peer-dependency save behavior.   | Choose one dependency target.                                                  |
+| `-O, --save-optional`        | Save to optionalDependencies.                          | Choose one dependency target.                                                  |
+| `-E, --save-exact`           | Save an exact dependency version.                      |                                                                                |
+| `--save-catalog-name <name>` | Save the dependency to a named catalog.                |                                                                                |
+| `--save-catalog`             | Save the dependency to the default catalog.            |                                                                                |
+| `--allow-build <names>`      | Allow the named packages to run postinstall scripts.   |                                                                                |
+| `--ignore-scripts`           | Do not run lifecycle scripts.                          |                                                                                |
+| `--no-optional`              | Do not install optionalDependencies.                   | Cannot be combined with --global.                                              |
+| `--frozen-lockfile`          | Prevent lockfile changes.                              | Cannot be combined with --global. Overrides an earlier `--no-frozen-lockfile`. |
+| `--no-frozen-lockfile`       | Explicitly allow lockfile updates.                     | Cannot be combined with --global. Overrides an earlier `--frozen-lockfile`.    |
+| `--lockfile-only`            | Update the lockfile without a full install.            | Cannot be combined with --global.                                              |
+| `--prefer-offline`           | Use cached packages when available.                    | Cannot be combined with --global.                                              |
+| `--offline`                  | Only use packages already in cache.                    | Cannot be combined with --global.                                              |
+| `-f, --force`                | Request a forced reinstall.                            | Cannot be combined with --global.                                              |
+| `--no-lockfile`              | Skip reading or generating a lockfile.                 | Cannot be combined with --global.                                              |
+| `--shamefully-hoist`         | Create a flat `node_modules` layout.                   | Cannot be combined with --global.                                              |
+| `--silent`                   | Suppress Vite+ output and request native quiet output. | Cannot be combined with --global.                                              |
+| `--filter <pattern>`         | Select workspaces by pattern.                          | Can be repeated.                                                               |
+| `-w, --workspace-root`       | Add to workspace root.                                 |                                                                                |
+| `--workspace`                | Require the dependency to exist in the workspace.      |                                                                                |
+| `-g, --global`               | Install globally.                                      | Requires the global CLI. Uses the [global package store](./global-packages).   |
+| `--node <version>`           | Node.js version to use for global installation.        | Requires --global.                                                             |
+| `--concurrency <number>`     | Number of global package installs to run in parallel.  | Requires --global. Must be a positive integer.                                 |
+
+## Compatibility
+
+The commands below describe project operations. Global mode is described under [Options](#options).
+
+- **npm:** `npm install`.
+- **pnpm:** `pnpm add`.
+- **Yarn Classic:** `yarn add`.
+- **Yarn Modern:** `yarn add`.
+- **Bun:** `bun add`.
+
+| Option                       | npm             | pnpm             | Yarn Classic | Yarn Modern | Bun            | Notes                                              |
+| ---------------------------- | --------------- | ---------------- | ------------ | ----------- | -------------- | -------------------------------------------------- |
+| `-P, --save-prod`            | Yes             | Yes              | Yes          | Yes         | Yes            |                                                    |
+| `-D, --save-dev`             | Yes             | Yes              | Yes          | Yes         | Yes            |                                                    |
+| `--save-peer`                | Yes             | Yes              | Yes          | Yes         | Yes            |                                                    |
+| `-O, --save-optional`        | Yes             | Yes              | Yes          | Yes         | Yes            |                                                    |
+| `-E, --save-exact`           | Yes             | Yes              | Yes          | Yes         | Yes            |                                                    |
+| `--save-catalog-name <name>` | No              | 10.12.0 or later | No           | No          | 1.4 or later   |                                                    |
+| `--save-catalog`             | No              | 10.12.0 or later | No           | No          | 1.4 or later   |                                                    |
+| `--allow-build <names>`      | No              | 10.4.0 or later  | No           | No          | No             |                                                    |
+| `--ignore-scripts`           | Yes             | Yes              | Yes          | 3 or later  | Yes            | On Yarn Modern, lockfile-only mode takes priority. |
+| `--no-optional`              | Yes             | Yes              | Yes          | No          | Yes            |                                                    |
+| `--frozen-lockfile`          | No              | No               | Yes          | No          | Yes            |                                                    |
+| `--no-frozen-lockfile`       | No              | No               | No           | No          | Yes            |                                                    |
+| `--lockfile-only`            | Yes             | Yes              | No           | 3 or later  | Yes            |                                                    |
+| `--prefer-offline`           | Yes             | Yes              | Yes          | No          | 1.4.1 or later |                                                    |
+| `--offline`                  | Yes             | Yes              | Yes          | No          | 1.4.1 or later |                                                    |
+| `-f, --force`                | Yes             | Yes              | Yes          | No          | Yes            |                                                    |
+| `--no-lockfile`              | Yes             | Yes              | Yes          | No          | No             |                                                    |
+| `--shamefully-hoist`         | No              | Yes              | No           | No          | No             |                                                    |
+| `--silent`                   | Yes             | Yes              | Yes          | No          | Yes            |                                                    |
+| `--filter <pattern>`         | 7.14.0 or later | Yes              | No           | Yes         | 1.4 or later   |                                                    |
+| `-w, --workspace-root`       | 8.1.0 or later  | Yes              | Yes          | No          | No             |                                                    |
+| `--workspace`                | No              | Yes              | No           | No          | No             |                                                    |
+| `-g, --global`               | Yes             | Yes              | Yes          | Yes         | Yes            |                                                    |
+| `--node <version>`           | Yes             | Yes              | Yes          | Yes         | Yes            |                                                    |
+| `--concurrency <number>`     | Yes             | Yes              | Yes          | Yes         | Yes            |                                                    |
+
+## Native Options
+
+For native options, see [npm install](https://docs.npmjs.com/cli/v11/commands/npm-install), [pnpm add](https://pnpm.io/cli/add), [Yarn add](https://yarnpkg.com/cli/add), [Yarn Classic add](https://classic.yarnpkg.com/en/docs/cli/add), and [Bun add](https://bun.com/docs/pm/cli/add). To pass these options through Vite+, see [Native Arguments](./#native-arguments).

package/docs/guide/package-management/approve-builds.md

@@ -0,0 +1,48 @@
+# vp pm approve-builds
+
+Approve dependency lifecycle scripts using the selected manager's trust policy. Approve only packages whose install scripts you intend to execute.
+
+```bash
+vp pm approve-builds
+vp pm approve-builds sharp
+vp pm approve-builds '!untrusted-package'
+vp pm approve-builds --all
+```
+
+## Options
+
+Supply packages to approve, or prefix a name with `!` to request denial where supported. Quote denial arguments to avoid shell history expansion.
+
+| Option  | Description                                         | Notes                                                              |
+| ------- | --------------------------------------------------- | ------------------------------------------------------------------ |
+| `--all` | Approve all packages pending build-script approval. | Cannot be combined with package names, including names after `--`. |
+
+## Compatibility
+
+- **npm:** 11.16 or later: `npm approve-scripts`. Earlier versions warn and skip. Denials use `npm deny-scripts`.
+- **pnpm:** 10.1 or later: `pnpm approve-builds`. Earlier versions warn and skip.
+- **Yarn Classic:** No command. Warns and exits successfully without performing the operation.
+- **Yarn Modern:** No command. Warns and exits successfully without performing the operation.
+- **Bun:** `bun pm trust` for named packages or `--all`.
+
+| Option  | npm              | pnpm             | Yarn Classic | Yarn Modern | Bun | Notes |
+| ------- | ---------------- | ---------------- | ------------ | ----------- | --- | ----- |
+| `--all` | 11.16.0 or later | 10.32.0 or later | No           | No          | Yes |       |
+
+With no package names, pnpm opens its interactive flow and npm lists pending packages with `--allow-scripts-pending`. Bun does not open an interactive selector; inspect pending packages with `bun pm untrusted` and then name the packages to trust.
+
+Denial arguments prefixed with `!` require pnpm 11 or later or npm 11.16 or later. npm requires separate approval and denial invocations. Bun skips denial entries with a warning because it uses `trustedDependencies` rather than a denylist.
+
+For Yarn Modern, configure `enableScripts: false` and explicitly allow trusted packages through `dependenciesMeta`.
+
+### npm Build-Script Policy
+
+npm 12 enforces `allowScripts` in `package.json`. Dependency install scripts not covered by the policy are skipped, including implicit native builds. Approval updates policy but does not run scripts skipped earlier. Follow it with [`vp pm rebuild <package>`](./rebuild).
+
+In npm 11.16 through 11.x, this policy is advisory. Scripts still run and npm warns about unreviewed packages.
+
+## Native Options
+
+For native options, see [npm approve-scripts](https://docs.npmjs.com/cli/v11/commands/npm-approve-scripts), [npm deny-scripts](https://docs.npmjs.com/cli/v11/commands/npm-deny-scripts), [pnpm approve-builds](https://pnpm.io/cli/approve-builds), [Bun pm trust](https://bun.com/docs/pm/cli/pm), and [Bun pm untrusted](https://bun.com/docs/pm/cli/pm). To pass these options through Vite+, see [Native Arguments](./#native-arguments).
+
+For script policy configuration, see [npm package.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-json), [Yarn enableScripts](https://yarnpkg.com/configuration/yarnrc#enableScripts), and [Bun lifecycle scripts](https://bun.com/docs/pm/lifecycle).

package/docs/guide/package-management/audit.md

@@ -0,0 +1,39 @@
+# vp pm audit
+
+Audit dependencies for known vulnerabilities.
+
+```bash
+vp pm audit
+vp pm audit --json
+vp pm audit --production --level high
+```
+
+## Options
+
+| Option            | Description                                  | Notes                             |
+| ----------------- | -------------------------------------------- | --------------------------------- |
+| `--fix`           | Request automatic vulnerability remediation. |                                   |
+| `--json`          | Request native JSON output.                  | Output retains the native schema. |
+| `--level <level>` | Minimum vulnerability level to report.       |                                   |
+| `--production`    | Only audit production dependencies.          |                                   |
+
+## Compatibility
+
+- **npm:** `npm audit` or `npm audit fix`.
+- **pnpm:** `pnpm audit`.
+- **Yarn Classic:** `yarn audit`.
+- **Yarn Modern:** 2.4 or later: `yarn npm audit`. Earlier versions warn and skip.
+- **Bun:** `bun audit` or `bun audit fix`.
+
+| Option            | npm | pnpm | Yarn Classic | Yarn Modern | Bun             | Notes |
+| ----------------- | --- | ---- | ------------ | ----------- | --------------- | ----- |
+| `--fix`           | Yes | Yes  | No           | No          | 1.4 or later    |       |
+| `--json`          | Yes | Yes  | Yes          | Yes         | Yes             |       |
+| `--level <level>` | Yes | Yes  | Yes          | Yes         | Yes             |       |
+| `--production`    | Yes | Yes  | Yes          | Yes         | 1.2.21 or later |       |
+
+Vulnerability output and failure thresholds retain the native manager's semantics.
+
+## Native Options
+
+For native options, see [npm audit](https://docs.npmjs.com/cli/v11/commands/npm-audit), [pnpm audit](https://pnpm.io/cli/audit), [Yarn npm audit](https://yarnpkg.com/cli/npm/audit), [Yarn Classic audit](https://classic.yarnpkg.com/en/docs/cli/audit), and [Bun audit](https://bun.com/docs/pm/cli/audit). To pass these options through Vite+, see [Native Arguments](./#native-arguments).

package/docs/guide/package-management/cache.md

@@ -0,0 +1,53 @@
+# vp pm cache
+
+Inspect or clean the package manager's download cache or store. This is distinct from [`vp cache`](/guide/cache), which manages task results.
+
+```bash
+vp pm cache dir
+vp pm cache clean
+```
+
+## Options
+
+- `dir` and `path` print the cache or store location.
+- `clean` requests native cache cleanup.
+
+Other subcommands warn and exit successfully without running a command. There are no additional Vite+ options.
+
+### `dir`
+
+Print the cache or store location. Alias: `path`. There are no command-specific options.
+
+### `clean`
+
+Request native cache cleanup. There are no command-specific options.
+
+## Compatibility
+
+### `dir`
+
+- **npm:** `npm config get cache`.
+- **pnpm:** `pnpm store path`.
+- **Yarn Classic:** `yarn cache dir`.
+- **Yarn Modern:** `yarn config get cacheFolder`.
+- **Bun:** `bun pm cache`.
+
+### `clean`
+
+- **npm:** `npm cache clean`.
+- **pnpm:** `pnpm store prune`. Prunes the store rather than deleting all content.
+- **Yarn Classic:** `yarn cache clean`.
+- **Yarn Modern:** `yarn cache clean`.
+- **Bun:** `bun pm cache rm`.
+
+npm normally requires an explicit native `--force` for cache deletion:
+
+```bash
+vp pm cache clean -- --force
+```
+
+That example is npm-specific. Vite+ does not expose a separate `vp pm store` command.
+
+## Native Options
+
+For native options, see [npm config](https://docs.npmjs.com/cli/v11/commands/npm-config), [npm cache](https://docs.npmjs.com/cli/v11/commands/npm-cache), [pnpm store](https://pnpm.io/cli/store), [Yarn config get](https://yarnpkg.com/cli/config/get), [Yarn cache clean](https://yarnpkg.com/cli/cache/clean), [Yarn Classic cache](https://classic.yarnpkg.com/en/docs/cli/cache), and [Bun pm cache](https://bun.com/docs/pm/cli/pm). To pass these options through Vite+, see [Native Arguments](./#native-arguments).

package/docs/guide/package-management/ci.md

@@ -0,0 +1,28 @@
+# vp pm ci
+
+Install dependencies with a frozen lockfile for CI.
+
+```bash
+vp pm ci
+vp pm ci -- --ignore-scripts
+```
+
+## Options
+
+This command has no additional Vite+ options. For translated Vite+ options, use [`vp install --frozen-lockfile`](./install).
+
+There are no command-specific options.
+
+## Compatibility
+
+- **npm:** `npm ci`.
+- **pnpm:** `pnpm install --frozen-lockfile`.
+- **Yarn Classic:** `yarn install --frozen-lockfile`.
+- **Yarn Modern:** `yarn install --immutable`.
+- **Bun:** `bun install --frozen-lockfile`.
+
+The native manager determines installation cleanup and lockfile validation. This command does not make all managers behave like `npm ci` beyond the frozen-lockfile request.
+
+## Native Options
+
+For native options, see [npm ci](https://docs.npmjs.com/cli/v11/commands/npm-ci), [pnpm install](https://pnpm.io/cli/install), [Yarn install](https://yarnpkg.com/cli/install), [Yarn Classic install](https://classic.yarnpkg.com/en/docs/cli/install), and [Bun install](https://bun.com/docs/pm/cli/install). To pass these options through Vite+, see [Native Arguments](./#native-arguments). For CI setup, see the [CI guide](/guide/ci).