vite-plus 1.1.0 → 1.2.0

package/docs/guide/global-cli.md

@@ -1,5 +1,4 @@
 <script setup lang="ts">
-import { getScrollOffset } from 'vitepress';
 import { nextTick, onMounted, onUnmounted } from 'vue';
 
 function openTarget() {
@@ -18,9 +17,7 @@ function openTarget() {
   // VitePress cannot measure a heading inside closed details. Correct the scroll after revealing it.
   requestAnimationFrame(() => {
     if (!target.isConnected) return;
-    const top = window.scrollY + target.getBoundingClientRect().top - getScrollOffset()
-      + Number.parseInt(window.getComputedStyle(target).paddingTop, 10);
-    window.scrollTo(0, top);
+    target.scrollIntoView({ block: 'start' });
   });
 }
 
@@ -111,7 +108,7 @@ These variables control the installer scripts and the standalone Windows install
 #### `VP_HOME`
 
 - **Purpose**: Optional pin for the single-root layout. Set it to an absolute path. Vite+ then puts bin, data, cache, config, and state under that directory. The installed CLI reads the same variable. See [Environment](/guide/env).
-- **Default**: unset. Vite+ reuses an existing install in `~/.vite-plus` on Unix or `%USERPROFILE%\.vite-plus` on Windows. The directory must contain a `current` link. Otherwise, a fresh install uses the split platform layout. On Unix, it uses `~/.local/share/vite-plus` and its Vite+-owned `bin` subdirectory. On Windows, it uses `%LOCALAPPDATA%\vite-plus\data` and `%LOCALAPPDATA%\vite-plus\bin`.
+- **Default**: unset. Vite+ reuses an existing install in `~/.vite-plus` on Unix or `%USERPROFILE%\.vite-plus` on Windows. The directory must contain a `current` link. Otherwise, a fresh install uses the split platform layout shown below.
 - **Example**:
 
   ```bash
@@ -124,6 +121,20 @@ These variables control the installer scripts and the standalone Windows install
   $env:VP_HOME = "D:\vite-plus"; irm https://vite.plus/ps1 | iex
   ```
 
+Fresh split-layout installations use these defaults:
+
+| Directory | macOS and Linux            | Windows                          |
+| --------- | -------------------------- | -------------------------------- |
+| Data      | `~/.local/share/vite-plus` | `%LOCALAPPDATA%\vite-plus\data`  |
+| Bin       | `<DATA>/bin`               | `%LOCALAPPDATA%\vite-plus\bin`   |
+| Cache     | `~/.cache/vite-plus`       | `%LOCALAPPDATA%\vite-plus\cache` |
+| Config    | `~/.config/vite-plus`      | `%APPDATA%\vite-plus`            |
+| State     | `~/.local/state/vite-plus` | `%LOCALAPPDATA%\vite-plus\state` |
+
+On macOS and Linux, absolute `XDG_DATA_HOME`, `XDG_CACHE_HOME`, `XDG_CONFIG_HOME`, and `XDG_STATE_HOME` values override the corresponding base directories. The bin directory follows the data directory.
+
+Low-priority managed shims live in `<DATA>/fallback-bin`, where `<DATA>` is the resolved data directory.
+
 #### `VP_BIN_DIR` / `VP_DATA_DIR` / `VP_CACHE_DIR`
 
 - **Purpose**: Internal absolute directory overrides for integrations that must pin a split install. Set all three variables together. The installer rejects an incomplete group. Vite+ ignores the group when `VP_HOME` is set or when it reuses an existing `~/.vite-plus` install.
@@ -143,6 +154,17 @@ These variables control the installer scripts and the standalone Windows install
 - **Purpose**: Custom npm registry URL
 - **Default**: `https://registry.npmjs.org`
 - **CLI equivalent**: `--registry`
+- **Managed package managers**: When Vite+ downloads a pinned npm, pnpm,
+  Yarn, or Bun version, it also reads the workspace-root and user `.npmrc`.
+  Package-scoped registries and registry-scoped `_authToken`, `_auth`, or
+  `username`/`_password` credentials are honored. Keep secrets in environment
+  variables and reference them from `.npmrc`, for example:
+
+  ```ini
+  registry=https://npm.corp.example/repository/npm/
+  //npm.corp.example/repository/npm/:_authToken=${NPM_TOKEN}
+  ```
+
 - **Example**:
   ```bash
   curl -fsSL https://vite.plus | NPM_CONFIG_REGISTRY=https://registry.npmmirror.com bash
@@ -189,7 +211,7 @@ These management variables are installation choices, saved in Vite+'s config. Th
 
 #### Development variables
 
-Use `VP_LOCAL_TGZ` and `VP_LOCAL_BINARY` when you develop Vite+ itself. `VP_LOCAL_TGZ` specifies a local `vite-plus.tgz` file. `VP_LOCAL_BINARY` specifies a local `vp` binary. The installers use these files for the local build. They use `VP_DUMP_DIRS=1` to get the layout mode and all five `EnvConfig` category roots from the selected binary. They do not resolve the directory variables. The installers set `VP_INSTALL_STOP`; do not set it manually.
+Use `VP_LOCAL_TGZ` and `VP_LOCAL_BINARY` when you develop Vite+ itself. `VP_LOCAL_TGZ` specifies a local `vite-plus.tgz` file. `VP_LOCAL_BINARY` specifies a local `vp` binary. The installers use these files for the local build.
 
 ### Runtime Variables
 
@@ -251,10 +273,11 @@ These variables configure the installed Vite+ CLI. `VP_HOME` (above) also applie
 #### `VP_BYPASS`
 
 - **Purpose**: Bypass the Vite+ shim and use the system tool
-- **Values**: `PATH`-style list of directories to bypass
-- **Default**: None
+- **Values**: Setting this variable, including to an empty string, enables bypass mode. Its value is a `PATH`-style list of additional directories to exclude from the search. The Vite+ bin directory and Vite+ shims are skipped automatically.
+- **Default**: Unset
 - **Example**:
   ```bash
+  # Find a system Node.js on PATH, excluding /usr/local/bin.
   VP_BYPASS=/usr/local/bin node -v
   ```
 
@@ -289,7 +312,6 @@ Vite+ sets additional `VP_*` variables during shim dispatch and shell integratio
 #### `VP_LOG`
 
 - **Purpose**: Log filter string for `tracing_subscriber`
-- **Installer behavior**: When `CI=true`, `install.sh` hides shell file errors. Set `VP_LOG=trace` to show these errors.
 - **Default**: None
 - **Example**:
   ```bash
@@ -381,6 +403,10 @@ vp dlx create-vite   # Download and run a package binary
 
 You do not need a local `vite-plus` dependency to run existing `package.json` scripts. Add the [project-local CLI](/guide/local-cli) when you want the frontend toolchain version recorded in the project's manifest and lockfile.
 
+## Run a Command in Another Directory
+
+Use `vp -C <dir> <command>` to run any `vp` command from another working directory. See [Targeting a package with `-C`](/guide/monorepo#targeting-a-package-with-c) for examples and details.
+
 ## Use Both CLIs Together
 
 The global CLI and the project-local `vite-plus` package work together. You keep using the same `vp` command, while each project can choose its own toolchain version.
@@ -403,7 +429,7 @@ To see which toolchain is selected for your current project, run `vp toolchain`.
 ## Next Steps
 
 - [Environment](/guide/env) covers Node.js and package-manager selection, pinning, shims, and managed installations.
-- [Package Management](/guide/install) covers pnpm, npm, Yarn, and Bun workflows.
+- [Package Management](/guide/package-management) covers pnpm, npm, Yarn, and Bun workflows.
 - [Run](/guide/run) covers package scripts and cached workspace tasks.
 - [Upgrading Vite+](/guide/upgrade) explains global CLI upgrades. See [Update Vite+](/guide/upgrade-project) for project-local upgrades.
 - [Removing Vite+](/guide/implode) removes the global binary and its managed data.

package/docs/guide/ide-integration.md

@@ -1,6 +1,6 @@
 # IDE Integration
 
-Vite+ supports VS Code and Zed through editor-specific settings that `vp create` and `vp migrate` can automatically write into your project.
+Vite+ supports VS Code, Zed, and JetBrains IDEs through editor-specific settings that `vp create` and `vp migrate` can automatically write into your project.
 
 ## VS Code
 

package/docs/guide/index.md

@@ -82,12 +82,12 @@ This is required because the managed [unofficial-builds](https://unofficial-buil
 With the global CLI installed, create a project, install dependencies, and use the default commands:
 
 ```bash
-vp create # Create a new project
+vp create  # Create a new project
 vp install # Install dependencies
-vp dev # Start the dev server
-vp check # Format, lint, type-check
-vp test # Run JavaScript tests
-vp build # Build for production
+vp dev     # Start the dev server
+vp check   # Format, lint, type-check
+vp test    # Run JavaScript tests
+vp build   # Build for production
 ```
 
 You can also run `vp` on its own to open the interactive command line. In a local-only setup, run the same commands through your package manager, such as `pnpm exec vp check`.
@@ -100,9 +100,9 @@ Vite+ covers the full frontend development cycle, from starting a project throug
 
 - [`vp create`](/guide/create) creates new apps, packages, and monorepos.
 - [`vp migrate`](/guide/migrate) moves existing projects onto Vite+.
-- [`vp install`](/guide/install) installs dependencies with the right package manager.
-- [`vp add`](/guide/install), [`vp remove`](/guide/install), [`vp update`](/guide/install), [`vp dedupe`](/guide/install), [`vp outdated`](/guide/install), [`vp list`](/guide/install), [`vp why`](/guide/install), and [`vp info`](/guide/install) cover the rest of the package-management workflow.
-- [`vp link`](/guide/install), [`vp unlink`](/guide/install), [`vp rebuild`](/guide/install), and [`vp pm <command>`](/guide/install) provide lower-level package-manager operations.
+- [`vp install`](/guide/package-management) installs dependencies with the right package manager.
+- [`vp add`](/guide/package-management), [`vp remove`](/guide/package-management), [`vp update`](/guide/package-management), [`vp dedupe`](/guide/package-management), [`vp outdated`](/guide/package-management), [`vp list`](/guide/package-management), [`vp why`](/guide/package-management), and [`vp info`](/guide/package-management) cover the rest of the package-management workflow.
+- [`vp link`](/guide/package-management), [`vp unlink`](/guide/package-management), [`vp rebuild`](/guide/package-management), and [`vp pm <command>`](/guide/package-management) provide lower-level package-manager operations.
 
 ### Project Toolchain
 

package/docs/guide/local-cli.md

@@ -39,12 +39,28 @@ The documentation uses bare `vp` commands for readability. Without the global CL
 
 ### Manual Installation
 
-If you are manually migrating a project to Vite+, install these dev dependencies first:
+If you are manually migrating a project to Vite+, install `vite-plus` as a development dependency:
 
-```bash
-vp install -D vite-plus
+::: code-group
+
+```bash [npm]
+npm install -D vite-plus
 ```
 
+```bash [Yarn]
+yarn add -D vite-plus
+```
+
+```bash [pnpm]
+pnpm add -D vite-plus
+```
+
+```bash [Bun]
+bun add -D vite-plus
+```
+
+:::
+
 Add overrides to your package manager so that other packages resolve the Vite+ versions. Alias `vite` to `@voidzero-dev/vite-plus-core`, setting `<vite-plus-version>` to the installed `vite-plus` version. Pin `vitest` to `<vitest-version>`, using the bundled version shown by `vp toolchain vitest` 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):
 
 ::: code-group
@@ -111,7 +127,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/install) 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

@@ -7,7 +7,7 @@ Except for [Before You Migrate](#before-you-migrate), which lists steps you take
 ## 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.
-2. Upgrade the project to Vite 8+ and Vitest 4.1+ when necessary.
+2. Upgrade the project to Vite 7+ and Vitest 4+ 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.
 5. Validate with `vp install`, `vp check`, `vp test`, and `vp build`.
@@ -18,7 +18,7 @@ Migration is idempotent: running it again after a successful migration should no
 
 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.
+- `--full` also runs the setup actions: git hooks, editor config, agent files, ESLint, Prettier, and tsup 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.
@@ -42,7 +42,7 @@ When a default upgrade skips setup actions that would apply, it prints a hint to
 | `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 checks the project's installed tsdown version before the final dependency install. For Vite+ pack configs, it reads the installed `vite-plus/dist/toolchain.json`. This includes `tsdown.config.*` files that already import `vite-plus/pack` before migration rewrites imports. Standalone tsdown configs use their installed tsdown version. Older Vite+ installations without this manifest retain the legacy defaults. For tsdown 0.23 or later, it does not insert compatibility defaults. For older or unknown versions, it 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.
 
 The inserted settings include comments with documentation links and instructions for adopting the new defaults. Remove `deps.resolveDepSubpath: true` to [preserve external subpath imports as written](https://tsdown.dev/options/dependencies#deps-resolvedepsubpath). Remove the inserted `attw.profile: 'strict'` to use the new `esm-only` [resolution profile](https://tsdown.dev/options/lint#profiles). This skips `node10` and CommonJS resolution checks. Keep either setting if your package requires the previous behavior. Migration does not add these comments to explicit settings.
 

package/docs/guide/migrate.md

@@ -65,7 +65,7 @@ For the Vitest v5 upgrade, read the [compatibility settings and review checklist
 
 Before running the migration:
 
-- For projects that do not use Vite+ yet, upgrade to Vite 8+ and Vitest 4.1+ first
+- For projects that do not use Vite+ yet, upgrade to Vite 7+ and Vitest 4+ first
 - Make sure you understand any existing lint, format, or test setup that should be preserved
 
 After running the migration:
@@ -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.1.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.2.0` release:
 
 ::: code-group
 
 ```bash [pnpm]
-pnpm dlx --package=vite-plus@1.1.0 vp migrate --no-interactive
+pnpm dlx --package=vite-plus@1.2.0 vp migrate --no-interactive
 ```
 
 ```bash [npm]
-npx --package=vite-plus@1.1.0 vp migrate --no-interactive
+npx --package=vite-plus@1.2.0 vp migrate --no-interactive
 ```
 
 :::
 
-Replace `1.1.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.2.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:
 
@@ -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.3` 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.4` 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`).
 
@@ -183,7 +183,7 @@ const { page } = await import('vite-plus/test/browser/context');
 
 `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.
+When the project's installed tsdown version is older than 0.23 or cannot be determined, the transform preserves earlier defaults by inserting `deps.resolveDepSubpath: true` and, when ATTW checks are enabled, `attw.profile: 'strict'` if these settings are absent. For Vite+ pack configs, it reads the installed `vite-plus/dist/toolchain.json`. This includes `tsdown.config.*` files that already import `vite-plus/pack` before migration rewrites imports. Standalone tsdown configs use their installed tsdown version. Older Vite+ installations without this manifest retain the legacy defaults. Projects already using tsdown 0.23 or later do not receive these defaults. 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:
 
@@ -220,7 +220,7 @@ After merging, delete `tsdown.config.ts`. See the [Pack guide](/guide/pack) for
 
 ### lint-staged
 
-Vite+ replaces lint-staged with its own `staged` block in `vite.config.ts`. Only the `staged` config format is supported. Standalone `.lintstagedrc` in non-JSON format and `lint-staged.config.*` are not migrated automatically.
+Vite+ replaces lint-staged with its own `staged` block in `vite.config.ts`. `vp staged` reads its configuration from the `staged` block in `vite.config.ts`, not from standalone lint-staged configuration files. Standalone `.lintstagedrc` in non-JSON format and `lint-staged.config.*` are not migrated automatically.
 
 Move your lint-staged rules into the `staged` block:
 
@@ -229,7 +229,7 @@ import { defineConfig } from 'vite-plus';
 
 export default defineConfig({
   staged: {
-    '*.{js,ts,tsx,vue,svelte}': 'vp check --fix',
+    '*': 'vp check --fix',
   },
 });
 ```

package/docs/guide/{install.md → package-management.md}

@@ -61,6 +61,10 @@ vp install -w
 
 ## Global Packages
 
+::: info
+Global package operations with `-g` require the [global CLI](/guide/global-cli).
+:::
+
 Use the `-g` flag for installing, updating or removing globally installed packages:
 
 - `vp install -g <pkg>` installs a package globally
@@ -98,7 +102,11 @@ Vite+ provides all the familiar package management commands:
 - `vp rebuild` rebuilds native modules (e.g. after switching Node.js versions)
 - `vp link` and `vp unlink` manage local package links
 - `vp dlx <pkg>` runs a package binary without adding it to the project
-- `vp pm <command>` forwards a raw package-manager-specific command when you need behavior outside the normalized `vp` command set
+- `vp pm <command>` provides additional package-management commands adapted to the detected package manager
+
+::: info
+The `vp list` and `vp rebuild` shortcuts are available only in the global CLI. With the [project-local CLI](/guide/local-cli), use `vp pm list` and `vp pm rebuild`.
+:::
 
 ### Command Guide
 
@@ -115,6 +123,10 @@ Use `vp install` when you want to install exactly what the current `package.json
 - `vp install --filter <pattern>` scopes install work in monorepos
 - `vp install -w` installs in the workspace root
 
+::: info
+Option support depends on the detected package manager and its version. Unsupported options cause `vp` to exit with an error before running the package-manager command.
+:::
+
 ##### Git and remote tarball dependencies (npm v12+)
 
 npm v12 stops resolving git dependencies (`github:`, `git+https:`) and remote tarball URLs by default; such installs fail with `EALLOWGIT` / `EALLOWREMOTE`. Opt back in per project with npm's `allow-git` / `allow-remote` config.
@@ -194,7 +206,16 @@ Use these when you need lower-level package-manager behavior.
 
 - `vp link` and `vp unlink` manage local development links
 - `vp dlx create-vite` runs a package binary without saving it as a dependency
-- `vp pm <command>` forwards directly to the resolved package manager
+- `vp pm <command>` provides additional package-management commands adapted to the detected package manager.
+
+  - **Dependencies**: `ci`, `prune`, `list`, `rebuild`, `approve-builds`
+  - **Patching**: `patch`, `patch-commit`
+  - **Packaging and publishing**: `pack`, `version`, `publish`, `stage`, `dist-tag`, `deprecate`
+  - **Inspection**: `view`, `search`, `audit`, `fund`, `ping`
+  - **Authentication and access**: `login`, `logout`, `whoami`, `token`, `owner`
+  - **Configuration**: `config`, `cache`
+
+  Command support depends on the package manager and its version. Run `vp pm --help` to list commands or `vp pm <command> --help` for available options.
 
 Examples:
 
@@ -218,8 +239,8 @@ vp pm stage reject <stage-id>    # discard a staged version (2FA)
 ```
 
 - pnpm (`pnpm stage`, requires pnpm ≥ 11.3) and npm (`npm stage`, requires npm ≥ 11.15 and Node ≥ 22.14) pass through directly.
-- yarn (Berry) uses its npm plugin (`yarn npm publish --staged`, `yarn npm stage …`); `view`/`download` fall back to npm.
-- yarn Classic and bun have no staged-publishing support and fall back to `npm stage`.
+- Yarn 4.16.0 and later uses its npm plugin (`yarn npm publish --staged`, `yarn npm stage …`). The `view` and `download` subcommands, and `publish` with an explicit tarball or folder target, fall back to `npm stage`.
+- Yarn versions earlier than 4.16.0 and Bun fall back to `npm stage`.
 
 ## Package-Manager Integrity Verification
 

package/docs/guide/run.md

@@ -32,12 +32,14 @@ building legacy app for production...
 Use `vp run` without a task name to use the interactive task runner:
 
 ```
-Select a task (↑/↓, Enter to run, Esc to clear):
+Select a task (↑/↓, Enter to run, type to search):
 
   › build: node compile-legacy-app.js
     test: jest
 ```
 
+With [shell completion](/guide/env#shell-completion) enabled, press Tab after `vp run ` or `vpr ` to complete task names from your project.
+
 ## Built-in Commands vs Scripts
 
 `vp dev` is a built-in command. `vp run dev` is your `dev` script. Built-in commands cannot be overwritten, so adding a `dev` script does not change what `vp dev` does:
@@ -69,7 +71,7 @@ $ node compile-legacy-app.js
 If nothing changes, the output is replayed from the cache on the next run:
 
 ```
-$ node compile-legacy-app.js ✓ cache hit, replaying
+$ node compile-legacy-app.js ◉ cache hit, replaying
 ✓ built in 69s
 
 ---
@@ -79,7 +81,7 @@ vp run: cache hit, 69s saved.
 If an input changes, the task runs again:
 
 ```
-$ node compile-legacy-app.js ✗ cache miss: 'legacy/index.js' modified, executing
+$ node compile-legacy-app.js ○ cache miss: 'legacy/index.js' modified, executing
 ```
 
 ## Task Definitions
@@ -250,18 +252,18 @@ $ vp build
 ✓ built in 28ms
 
 ---
-vp run: 0/2 cache hit (0%).
+vp run: 0/2 cache hit (0%), 2/2 successful.
 ```
 
-Each sub-task has its own cache entry. If only `.ts` files changed but lint still passes, only `vp build` runs again the next time `vp run --cache check` is called:
+Each sub-task has its own cache entry. For example, if a file used only by the build changes, such as `index.html`, only the build runs again the next time `vp run --cache check` is called:
 
 ```
-$ vp lint ✓ cache hit, replaying
-$ vp build ✗ cache miss: 'src/index.ts' modified, executing
+$ vp lint ◉ cache hit, replaying
+$ vp build ○ cache miss: 'index.html' modified, executing
 ✓ built in 30ms
 
 ---
-vp run: 1/2 cache hit (50%), 120ms saved.
+vp run: 1/2 cache hit (50%), 2/2 successful, 120ms saved.
 ```
 
 ### Nested `vp run`

package/docs/guide/test.md

@@ -2,7 +2,9 @@
 
 `vp test` runs tests with [Vitest](https://vitest.dev).
 
-The bundled runner uses Vitest `5.0.3` 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.
+Vite+ depends on Vitest `5.0.4`, which 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.
+
+`vp test` resolves Vitest from `vite-plus`'s dependencies first, then from your project.
 
 ## Overview
 

package/docs/guide/troubleshooting.md

@@ -8,10 +8,10 @@ Vite+ 1.0 is available. We continue to improve it and welcome community feedback
 
 ## Supported Tool Versions
 
-Vite+ expects modern upstream tool versions.
+Automatic migration requires these minimum versions for existing Vite and Vitest dependencies:
 
-- Vite 8 or newer
-- Vitest 4.1 or newer
+- Vite 7 or newer
+- Vitest 4 or newer
 
 If you are migrating an existing project and it still depends on older Vite or Vitest versions, upgrade those first before adopting Vite+.
 
@@ -22,7 +22,7 @@ Run `vp toolchain` to show the versions from the local Vite+ package. Run `vp to
 - 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 <tsconfig path>` 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
 
@@ -30,7 +30,7 @@ When running `vp lint`, `vp fmt`, or `vp check`, configs in subdirectories do no
 
 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, `disableNestedConfig` and `fmt.disableNestedConfig` disable per-file nested lint and format configs. See [IDE Integration](/guide/ide-integration) for setup instructions for your editor.
+Configure your editor's linting and formatting to use the workspace-root `vite.config.ts`. See [IDE Integration](/guide/ide-integration) for editor-specific setup instructions.
 
 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.
 
@@ -114,6 +114,8 @@ export default defineConfig({
 });
 ```
 
+Import the plugin packages directly inside the callback. A dynamic `import()` of a local module, such as `await import('./vite.plugins.ts')`, does not avoid the cost: Vite bundles the config before loading it and follows dynamic imports of local files, so that module and the packages it imports are still processed on every command, even though the callback never runs.
+
 ## Asking for Help
 
 If you are stuck, please reach out:

package/docs/guide/upgrade-project.md

@@ -6,11 +6,7 @@ Updating `vite-plus` and its related project dependencies. To upgrade the global
 
 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
-```
+Before updating the project's dependencies, [run the target migrator through your package manager](./migrate.md#without-the-global-cli).
 
 If your global CLI is newer than the project's version, running `vp migrate` upgrades the project to that global version instead:
 

package/docs/guide/upgrade.md

@@ -41,6 +41,12 @@ vp upgrade <version>              # install a specific version
 vp upgrade --registry <registry>  # use a custom npm registry
 ```
 
+### Automatic Update Checks
+
+The global CLI checks for updates in the background during normal terminal use, caching results for 24 hours. When a newer version is available, it prints a notice to stderr without installing it.
+
+Set `VP_NO_UPDATE_CHECK=1` to disable these checks and notices. They are also disabled in CI and for Homebrew installations.
+
 ### 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.

package/docs/guide/vitest-v5.md

@@ -1,6 +1,6 @@
 # Upgrade to Vitest 5
 
-Vite+ bundles Vitest `5.0.3`. Use Node `^22.18.0 || ^24.11.0 || >=26.0.0` for the CLI and tests.
+Vite+ bundles Vitest `5.0.4`. Use Node `^22.18.0 || ^24.11.0 || >=26.0.0` for the CLI and tests.
 
 ## Before you migrate
 
@@ -126,7 +126,7 @@ Review calls with benchmark options, imported or reassigned callbacks, callback
 
 ## Entry points and packages
 
-Use `vite-plus/test` for assertions and supported runner APIs. Keep coverage providers and `@vitest/ui` at the bundled runner's exact version, `5.0.3`. Keep `@vitest/web-worker` aligned when your project uses it.
+Use `vite-plus/test` for assertions and supported runner APIs. Keep coverage providers and `@vitest/ui` at the bundled runner's exact version, `5.0.4`. Keep `@vitest/web-worker` aligned when your project uses it.
 
 | v4 import                                | v5 import or action                                                         |
 | ---------------------------------------- | --------------------------------------------------------------------------- |

package/docs/guide/vpx.md

@@ -8,8 +8,8 @@ Use `vpx`, `vp exec`, and `vp dlx` to run binaries without switching between loc
 
 Use the other binary commands when you need stricter control:
 
-- `vpx` resolves a package binary locally first by default and downloads it if not found; with `pkg@version`, `--package/-p`, or `--shell-mode`, it runs via `vp dlx`
-- `vp exec` runs a binary from the current project's `node_modules/.bin`
+- `vpx` looks for a binary in local `node_modules/.bin` directories, Vite+-managed global packages, and system `PATH`, in that order, then falls back to `vp dlx`. With `pkg@version`, `--package/-p`, or `--shell-mode`, it runs via `vp dlx` directly.
+- `vp exec` runs a command from local `node_modules/.bin` directories, falling back to `PATH` if not found
 - `vp dlx` runs a package binary without adding it as a dependency
 
 ## `vpx`
@@ -37,7 +37,7 @@ vpx -p cowsay -c 'echo "hi" | cowsay'
 
 ## `vp exec`
 
-Use `vp exec` when the binary must come from the current project, for example a binary from a dependency installed in `node_modules/.bin`.
+Use `vp exec` to run tools already installed in your project or available in your environment.
 
 ```bash
 vp exec <command> [args...]