vite-plus 0.3.2 → 0.3.3

package/docs/guide/troubleshooting.md

@@ -15,18 +15,14 @@ Vite+ expects modern upstream tool versions.
 
 If you are migrating an existing project and it still depends on older Vite or Vitest versions, upgrade those first before adopting Vite+.
 
-Run `vp toolchain` to show the versions from the local Vite+ package.
-Run `vp toolchain --global` to show the versions from the global Vite+ release.
+Run `vp toolchain` to show the versions from the local Vite+ package. Run `vp toolchain --global` to show the versions from the global Vite+ release.
 
 ## `vp check` does not run type-aware lint rules or type checks
 
 - Confirm that `lint.options.typeAware` and `lint.options.typeCheck` are enabled in `vite.config.ts`
 - Check whether your `tsconfig.json` still uses `compilerOptions.baseUrl`
 
-The Oxlint type checker path powered by `tsgolint` does not support `baseUrl`.
-`vp migrate` and `vp lint --init` try to run the `vp dlx @andrewbranch/ts5to6 --fixBaseUrl .`
-fix before enabling type-aware linting. If that fix fails or is declined, Vite+
-skips `typeAware` and `typeCheck`.
+The Oxlint type checker path powered by `tsgolint` does not support `baseUrl`. `vp migrate` and `vp lint --init` try to run the `vp dlx @andrewbranch/ts5to6 --fixBaseUrl .` fix before enabling type-aware linting. If that fix fails or is declined, Vite+ skips `typeAware` and `typeCheck`.
 
 ## Nested lint or format config is not applied
 
@@ -76,8 +72,7 @@ If `vp staged` fails or your pre-commit hook does not run:
 - if status shows `Preference: disabled (local)`, re-enable with `vp hooks enable`
 - check whether hooks were skipped intentionally through `VP_GIT_HOOKS=0`
 
-To stop hooks in this clone without deleting project policy files, run `vp hooks disable`.
-See the [Commit hooks guide](/guide/commit-hooks) for the full workflow.
+To stop hooks in this clone without deleting project policy files, run `vp hooks disable`. See the [Commit hooks guide](/guide/commit-hooks) for the full workflow.
 
 A minimal staged config looks like this:
 

package/docs/guide/upgrade-project.md

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

package/docs/guide/upgrade.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plus",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "The Unified Toolchain for the Web",
   "homepage": "https://viteplus.dev/guide",
   "bugs": {
@@ -359,7 +359,7 @@
     }
   },
   "dependencies": {
-    "@oxc-project/types": "=0.149.0",
+    "@oxc-project/types": "=0.150.0",
     "@oxlint/plugins": "=1.79.0",
     "@vitest/browser": "4.1.11",
     "@vitest/browser-preview": "4.1.11",
@@ -370,23 +370,23 @@
     "@vitest/snapshot": "4.1.11",
     "@vitest/spy": "4.1.11",
     "@vitest/utils": "4.1.11",
-    "oxfmt": "=0.67.0",
-    "oxlint": "=1.82.0",
+    "oxfmt": "=0.68.0",
+    "oxlint": "=1.83.0",
     "oxlint-tsgolint": "=7.0.2001",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.3",
     "vitest": "4.1.11"
   },
   "devDependencies": {
-    "@emnapi/core": "2.0.0-alpha.4",
-    "@emnapi/runtime": "2.0.0-alpha.4",
-    "@napi-rs/cli": "^3.9.0",
+    "@emnapi/core": "2.0.0-alpha.5",
+    "@emnapi/runtime": "2.0.0-alpha.5",
+    "@napi-rs/cli": "^3.10.0",
     "@nkzw/safe-word-list": "^3.1.0",
     "@types/cross-spawn": "^6.0.6",
     "@types/semver": "^7.8.0",
     "@types/validate-npm-package-name": "^4.0.2",
     "@vitest/browser-playwright": "4.1.11",
     "@vitest/browser-webdriverio": "4.1.11",
-    "@voidzero-dev/vite-plus-prompts": "0.0.0",
+    "@voidzero-dev/vite-plus-prompts": "0.3.3",
     "bingo": "^0.9.3",
     "cac": "^7.0.0",
     "cross-spawn": "^7.0.5",
@@ -434,14 +434,14 @@
     "node": "^20.19.0 || ^22.18.0 || >=24.11.0"
   },
   "optionalDependencies": {
-    "@voidzero-dev/vite-plus-darwin-arm64": "0.3.2",
-    "@voidzero-dev/vite-plus-darwin-x64": "0.3.2",
-    "@voidzero-dev/vite-plus-linux-arm64-gnu": "0.3.2",
-    "@voidzero-dev/vite-plus-linux-arm64-musl": "0.3.2",
-    "@voidzero-dev/vite-plus-linux-x64-gnu": "0.3.2",
-    "@voidzero-dev/vite-plus-linux-x64-musl": "0.3.2",
-    "@voidzero-dev/vite-plus-win32-x64-msvc": "0.3.2",
-    "@voidzero-dev/vite-plus-win32-arm64-msvc": "0.3.2"
+    "@voidzero-dev/vite-plus-darwin-arm64": "0.3.3",
+    "@voidzero-dev/vite-plus-darwin-x64": "0.3.3",
+    "@voidzero-dev/vite-plus-linux-arm64-gnu": "0.3.3",
+    "@voidzero-dev/vite-plus-linux-arm64-musl": "0.3.3",
+    "@voidzero-dev/vite-plus-linux-x64-gnu": "0.3.3",
+    "@voidzero-dev/vite-plus-linux-x64-musl": "0.3.3",
+    "@voidzero-dev/vite-plus-win32-x64-msvc": "0.3.3",
+    "@voidzero-dev/vite-plus-win32-arm64-msvc": "0.3.3"
   },
   "scripts": {
     "build": "oxnode -C dev ./build.ts",

package/docs/guide/installer-env-vars.md

@@ -1,286 +0,0 @@
-# Installer Environment Variables
-
-The Vite+ installers (`vp-setup.exe`, `install.ps1`, and `install.sh`) and the installed `vp` CLI read the environment variables on this page.
-
-## Installation Variables
-
-These variables control the installer scripts and the standalone Windows installer (`vp-setup.exe`).
-
-### `VP_VERSION`
-
-- **Purpose**: Version to install
-- **Default**: `latest`
-- **CLI equivalent**: `--version`
-- **Note**: Vite+ 0.2.x and earlier do not support the split directory layout.
-  The installer always puts these releases in the monolithic root (`VP_HOME` or
-  `~/.vite-plus`). This rule also applies to a fresh machine. The installer
-  checks the downloaded binary and prints a notice.
-- **Example**:
-
-  ```bash
-  # Unix
-  curl -fsSL https://vite.plus | VP_VERSION=1.2.3 bash
-  ```
-
-  ```powershell
-  # PowerShell
-  $env:VP_VERSION = "1.2.3"; irm https://vite.plus/ps1 | iex
-  ```
-
-### `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`.
-- **Example**:
-
-  ```bash
-  # Unix
-  curl -fsSL https://vite.plus | VP_HOME=/opt/vite-plus bash
-  ```
-
-  ```powershell
-  # PowerShell
-  $env:VP_HOME = "D:\vite-plus"; irm https://vite.plus/ps1 | iex
-  ```
-
-### `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.
-- **Default**: unset (XDG / platform defaults)
-- **Persistence**: The generated environment file does not export these
-  variables. An integration that uses them must provide the complete group to
-  each Vite+ process.
-- **Example**:
-
-  ```bash
-  export VP_DATA_DIR=$HOME/vite-plus-data
-  export VP_BIN_DIR=$VP_DATA_DIR/bin
-  export VP_CACHE_DIR=$HOME/.cache/vite-plus
-  curl -fsSL https://vite.plus | bash
-  ```
-
-### `NPM_CONFIG_REGISTRY`
-
-- **Purpose**: Custom npm registry URL
-- **Default**: `https://registry.npmjs.org`
-- **CLI equivalent**: `--registry`
-- **Example**:
-  ```bash
-  curl -fsSL https://vite.plus | NPM_CONFIG_REGISTRY=https://registry.npmmirror.com bash
-  ```
-
-### `VP_NODE_MANAGER`
-
-- **Purpose**: Control Node.js version manager setup during installation.
-- **Values**: `yes` or `no`
-- **Default**: Auto-detected
-- **CLI equivalent**: `--no-node-manager` (inverted)
-- **Example**:
-  ```bash
-  # Skip Node.js manager setup in CI
-  curl -fsSL https://vite.plus | VP_NODE_MANAGER=no bash
-  ```
-
-### `VP_PM_MANAGER`
-
-- **Purpose**: Set the management preference for all four package-manager
-  families: npm, pnpm, Yarn, and Bun.
-- **Values**: `yes` uses Vite+ management; `no` prefers system tools, with
-  managed tools as a fallback when a system tool is unavailable.
-- **Default**: Unset. The installer's combined Node.js and package-manager
-  choice remains the default. With the script installers, setting only
-  `VP_NODE_MANAGER` preserves existing package-manager preferences.
-
-### `VP_NPM_MANAGER` / `VP_PNPM_MANAGER` / `VP_YARN_MANAGER` / `VP_BUN_MANAGER`
-
-- **Purpose**: Set the management preference for an individual package-manager
-  family. Each variable overrides `VP_PM_MANAGER` for that family.
-- **Values**: `yes` or `no`, with the same meaning as `VP_PM_MANAGER`.
-- **Default**: Unset (use `VP_PM_MANAGER`, then the combined installer choice,
-  or preserve the existing preference).
-- **Example**:
-
-  ```bash
-  # Keep system Node.js and package managers, but let Vite+ manage pnpm.
-  curl -fsSL https://vite.plus | VP_NODE_MANAGER=no VP_PM_MANAGER=no VP_PNPM_MANAGER=yes bash
-  ```
-
-These management variables are installation choices, saved in Vite+'s config.
-The interactive prompt still controls both Node.js and package managers;
-explicit package-manager variables override that combined choice. The standalone
-`vp-setup` installer uses its existing combined option as the default for both
-variables, in interactive and silent installations alike.
-In-place upgrades preserve the saved choices. Unrecognized values are ignored.
-They select management behavior, not package-manager versions, and do not
-prevent the installer from creating shims. Older releases installed through
-the legacy installer retain their original behavior.
-
-### `VP_PR_VERSION`
-
-- **Purpose**: Install a preview build from a pull request or commit SHA
-- **Values**: PR number or commit SHA
-- **Default**: None
-- **Details**: [Global `vp` Preview](/guide/upgrade#global-vp-preview)
-
-### 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.
-
-## Runtime Variables
-
-These variables configure the installed Vite+ CLI. `VP_HOME` (above) also applies at runtime.
-
-### `VP_NODE_DIST_MIRROR`
-
-- **Purpose**: Node.js distribution mirror URL
-- **Default**: `https://nodejs.org/dist`
-- **Details**: [Custom Node.js Mirror](/guide/env#custom-node-js-mirror)
-
-### `VP_NODE_VERSION`
-
-- **Purpose**: Override Node.js version
-- **Default**: None (auto-detected)
-- **Example**:
-  ```bash
-  # Run a command with a specific Node.js version
-  VP_NODE_VERSION=22 vp env exec node -v
-  ```
-
-### `VP_PACKAGE_MANAGER`
-
-- **Purpose**: Override the selected package manager and version
-- **Default**: None (resolved from the project or global default)
-- **Format**: `npm|pnpm|yarn|bun@<version>`
-- **Example**:
-  ```bash
-  VP_PACKAGE_MANAGER=pnpm@10.18.0 vp install
-  ```
-
-### `VP_NODE_SKIP_SIGNATURE_VERIFY`
-
-- **Purpose**: Skip PGP signature verification of Node.js downloads
-- **Values**: Any non-empty value
-- **Default**: None (verification enabled)
-- **Details**: [Node.js Signature Verification](/guide/env#node-js-signature-verification)
-
-### `VP_DOWNLOAD_TIMEOUT`
-
-- **Purpose**: Per-request timeout, in seconds, for large downloads such as Node.js runtimes and package-manager tarballs
-- **Values**: Positive integer, at most `86400` (24 hours); invalid values are ignored with a warning
-- **Default**: `600` (10 minutes)
-- **Example**:
-  ```bash
-  # Allow up to 30 minutes per download on a slow connection
-  VP_DOWNLOAD_TIMEOUT=1800 vp env install 22
-  ```
-
-### `VP_SHELL`
-
-- **Purpose**: Specify the current shell
-- **Default**: Auto-detected
-- **Example**:
-  ```bash
-  VP_SHELL=bash vp env print
-  ```
-
-### `VP_BYPASS`
-
-- **Purpose**: Bypass the Vite+ shim and use the system tool
-- **Values**: `PATH`-style list of directories to bypass
-- **Default**: None
-- **Example**:
-  ```bash
-  VP_BYPASS=/usr/local/bin node -v
-  ```
-
-### Internal variables
-
-Vite+ sets additional `VP_*` variables during shim dispatch and shell integration (recursion guards, active-version records, wrapper flags); do not set them manually.
-
-## TLS/CA Configuration
-
-### `SSL_CERT_FILE` / `NODE_EXTRA_CA_CERTS`
-
-- **Purpose**: Path to PEM bundle of extra CA certificates (`NODE_EXTRA_CA_CERTS` is the Node.js convention)
-- **Default**: System trust store
-- **Example**:
-  ```bash
-  export SSL_CERT_FILE=/path/to/custom-ca.pem
-  ```
-
-### `VP_INSECURE_TLS`
-
-- **Purpose**: Disable HTTPS certificate verification
-- **Values**: Any non-empty value (`1`, `true`, `yes`)
-- **Default**: None (verification enabled)
-- **Warning**: Diagnostic escape hatch only; do not use in production
-- **Example**:
-  ```bash
-  VP_INSECURE_TLS=1 vp env install 22
-  ```
-
-## Logging and Debugging
-
-### `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
-  VP_LOG=debug vp dev
-  VP_LOG=vt=trace vp build
-  ```
-
-### `VP_DEBUG_SHIM`
-
-- **Purpose**: Enable debug output for shim dispatch
-- **Values**: Any non-empty value
-- **Default**: None
-- **Example**:
-  ```bash
-  VP_DEBUG_SHIM=1 node -v
-  ```
-
-## Standard Environment Variables
-
-Vite+ also respects these standard environment variables:
-
-### `CI`
-
-- **Purpose**: Indicates running in CI environment
-- **Effect**: Enables silent mode (`--yes`) for installers
-
-### `NO_COLOR`
-
-- **Purpose**: Disable colored output
-- **Effect**: Disables ANSI color codes
-
-### `HOME` / `USERPROFILE`
-
-- **Purpose**: User home directory
-- **Effect**: Base for the existing-install probe (`~/.vite-plus`) and for split platform defaults
-
-## Precedence
-
-1. CLI flags (highest priority)
-2. Environment variables
-3. Default values (lowest priority)
-
-For example, `VP_VERSION=1.0.0 vp-setup.exe --version 2.0.0` installs version 2.0.0.