vite-plus 0.3.2 → 1.0.0-rc.0

package/docs/guide/env.md

@@ -1,12 +1,21 @@
 # Environment
 
-`vp env` manages the complete JavaScript environment: one Node.js runtime and one selected package manager. npm, pnpm, Yarn, and Bun are peer package-manager families.
+`vp env` manages the complete JavaScript environment: one Node.js runtime and one selected package manager. npm, pnpm, Yarn, and Bun are peer package-manager families. It belongs to the [global CLI](/guide/global-cli) and is not included in the project-local `vite-plus` package.
 
 ## Overview
 
+Think of the project environment as two independently selected components:
+
+- **Node.js** is the runtime used to execute JavaScript tools and scripts. Each project can declare the Node.js version it needs.
+- **The package manager** installs and manages project dependencies. Each project can select npm, pnpm, Yarn, or Bun and declare its version.
+
+For example, a project can use Node.js 24 with pnpm 10. Changing its Node.js version does not change its package-manager selection, and switching from pnpm to Yarn does not change its Node.js version. Vite+ resolves both components when you run a command so that you can move between projects without manually switching tools.
+
+Vite+ connects these selections to your shell through **shims**: small launchers named `node`, `npm`, `pnpm`, `yarn`, and `bun`, along with their aliases. In managed mode, a shim resolves and launches the appropriate tool for the current project. Commands such as `vp install` use the project's selected package manager; invoking `pnpm` directly always runs pnpm, even in a project that selects another manager.
+
 Managed mode is on by default, so Node.js and configured package-manager shims resolve through Vite+ and pick the right versions for the current project. Fresh installers record managed mode for npm, pnpm, Yarn, and Bun after the user enables environment management.
 
-When an upgrade adds a package-manager shim that has no recorded mode, its first interactive invocation asks what to do only when the corresponding system binary is already on PATH. The current family defaults to managed mode; choosing a system tool or applying a choice to every family remains explicit. Non-interactive invocations use managed mode without recording a choice.
+Use `vp env off` to disable managed mode for Node.js and package managers. See [Environment Modes](#environment-modes) below for details and how to switch to system tools.
 
 Most commands operate on both components when no selector is given. Add `node`, `pm`, `npm`, `pnpm`, `yarn`, or `bun` to narrow the command. `pm` means all four families for listing and cleanup, but the single selected package manager for project operations.
 
@@ -19,16 +28,18 @@ vp env pin node@24 pnpm@12      # Both components
 vp env pin 22.0.0 pnpm@10.18.0  # Also both components
 ```
 
-Vite+ checks the current directory first, then walks up through its parents. The nearest directory
-with a supported declaration wins. Within each directory, sources are checked in this order:
+Use `vp env pin` to save a project's versions, `vp env default` to set fallback versions, and `vp env use` to override versions for the current shell. Run `vp env current` to see the resolved environment.
+
+## Node.js Selection
+
+To select the project's Node.js version, Vite+ checks the current directory first, then walks up through its parents. The nearest directory with a supported declaration wins. Within each directory, sources are checked in this order:
 
 1. `.node-version` file
 2. `devEngines.runtime` in `package.json` (the [devEngines standard](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#devengines))
 3. `engines.node` in `package.json`
 4. `.nvmrc` file
 
-If no directory declares a version, Vite+ uses the global default (`vp env default`) and then the
-latest LTS.
+If no directory declares a version, Vite+ uses the global default (`vp env default`) and then the latest LTS.
 
 `devEngines.runtime` ranks above `engines.node` because it declares the development-environment requirement, while `engines.node` is a consumer-facing support range. `vp env doctor` warns when declared sources conflict.
 
@@ -44,6 +55,8 @@ pnpm config set --global runtimeOnFail ignore
 This setting also disables pnpm's automatic management of other declared runtimes, including Bun and Deno. Consider whether any of your projects rely on that behavior before setting it globally.
 :::
 
+## Package-Manager Selection
+
 Package-manager selection uses this priority:
 
 1. Explicit command override
@@ -52,16 +65,16 @@ Package-manager selection uses this priority:
 4. `devEngines.packageManager`
 5. Lockfile or manager-specific configuration
 6. The named package manager's global default version
-7. The named shim's latest release
+7. The named shim's latest release (Node.js' bundled version for `npm`)
 
 `VP_PACKAGE_MANAGER` selects the manager and version for commands such as `vp install`. Direct package-manager shims ignore this variable and use independent version overrides:
 
-| Variable          | Shims             |
-| ----------------- | ----------------- |
-| `VP_NPM_VERSION`  | `npm`, `npx`      |
-| `VP_PNPM_VERSION` | `pnpm`, `pnpx`    |
-| `VP_YARN_VERSION` | `yarn`, `yarnpkg` |
-| `VP_BUN_VERSION`  | `bun`, `bunx`     |
+| Variable          | Shims                       |
+| ----------------- | --------------------------- |
+| `VP_NPM_VERSION`  | `npm`, `npx`                |
+| `VP_PNPM_VERSION` | `pnpm`, `pnpx`, `pn`, `pnx` |
+| `VP_YARN_VERSION` | `yarn`, `yarnpkg`           |
+| `VP_BUN_VERSION`  | `bun`, `bunx`               |
 
 These variables accept a version or range, such as `10.18.0`, `10`, or `latest`, and override the matching shim's project and default versions. They do not change the manager or version selected by `vp install`.
 
@@ -76,16 +89,19 @@ VP_PNPM_VERSION=10.20.0 pnpm --version
 
 The overrides apply in managed mode. A package manager can also perform its own version switching after Vite+ launches it; for example, pnpm's `managePackageManagerVersions` setting may switch back to the version in `package.json`.
 
-A project selection applies only to its matching shims. For example, pnpm controls `pnpm` and `pnpx`; invoking `npm` still resolves npm independently. Without a matching project selection, a named shim uses its configured default version and otherwise uses the latest release without prompting. The resolved version is cached for one hour and an expired cache remains available when the registry cannot be reached. The directly invoked npm shim keeps its Node-bundled fallback, while an explicit `vp env ... npm` family scope uses standalone npm's latest release.
+A project selection applies only to its matching shims. For example, pnpm controls `pnpm`, `pnpx`, `pn`, and `pnx`; invoking `npm` still resolves npm independently. Without a matching project selection, a named shim uses its configured default version and otherwise uses the latest release without prompting. The npm shim falls back to Node's bundled npm. `vp env use npm` selects standalone npm's latest release for the current shell when no project version or global default is configured.
 
-A fresh install uses the split platform layout by default. On Unix, Vite+
-stores managed runtimes and related files in `~/.local/share/vite-plus`. It
-stores executables in the Vite+-owned `~/.local/share/vite-plus/bin` directory.
-On Windows, Vite+ uses `%LOCALAPPDATA%\vite-plus\data` for data and
-`%LOCALAPPDATA%\vite-plus\bin` for executables. Vite+ does not move an existing
-`~/.vite-plus` install. `VP_HOME` puts all categories under one custom root.
+::: details Latest-version caching
+When a named shim falls back to the latest release, the resolved version is cached for one hour. An expired cache remains available when the registry cannot be reached.
+:::
+
+`pn` runs the same managed binary as `pnpm`, and `pnx` runs the same managed binary as `pnpx` (`pnpm dlx`). These aliases also work with managed pnpm versions older than v11.
+
+## Environment Modes
 
-If you want to keep that behavior, run:
+Managed mode is on by default, so Node.js and configured package-manager shims resolve through Vite+ and pick the right versions for the current project. Fresh installers record managed mode for npm, pnpm, Yarn, and Bun after the user enables environment management.
+
+To enable managed mode, run:
 
 ```bash
 vp env on
@@ -106,17 +122,20 @@ If you do not want Vite+ to manage Node.js first, run:
 vp env off
 ```
 
-This switches both components to system-first mode. Vite+ prefers system tools and falls back to managed installations. Mixed configurations compose: a system package-manager launcher receives the Node.js selected by the Node mode.
+This switches both components to system-first mode. Vite+ prefers system tools and falls back to managed installations. Mixed configurations compose: package-manager launchers that look up Node.js through PATH receive the runtime selected by the Node mode.
 
-Using `pm` records the selected mode for all currently supported package managers and replaces their individual choices. An unscoped `on` or `off` does the same while also changing Node.js. A family without a recorded mode remains undecided until its shim is first used or an `on` / `off` command configures it.
+Using `pm` records the selected mode for all currently supported package managers and replaces their individual choices. An unscoped `on` or `off` does the same while also changing Node.js.
 
 ## Commands
 
 ### Setup
 
-- `vp env setup` creates or updates the `node`, `npm`, `npx`, `pnpm`, `pnpx`, `yarn`, `yarnpkg`, `bun`, `bunx`, `vpx`, and `vpr` shims in the resolved bin directory. It writes shell setup scripts in the config directory.
-- `vp env on` / `vp env off` changes both modes; append `node`, `pm`, `npm`, `pnpm`, `yarn`, or `bun` to narrow the change
-- `vp env print` prints PATH setup for both components; append a selector to print one
+- `vp env setup` creates tool shims and writes shell setup scripts.
+- `vp env setup --refresh` recreates Vite+ shims and regenerates shell setup scripts using your saved preferences.
+- `vp env on` / `vp env off` switches between Vite+-managed and system-first modes; append `node`, `pm`, `npm`, `pnpm`, `yarn`, or `bun` to narrow the change.
+- `vp env print` prints PATH setup for both components; append a selector to print one.
+
+Upgrades refresh the setup automatically. Open a new terminal or reload your shell setup script afterward.
 
 PowerShell needs to dot-source the generated setup script in the current shell before `vp env use` can affect only that shell session:
 
@@ -124,8 +143,7 @@ PowerShell needs to dot-source the generated setup script in the current shell b
 . "$env:APPDATA\vite-plus\env.ps1"
 ```
 
-If an older Vite+ install uses `%USERPROFILE%\.vite-plus`, source the `env.ps1`
-file in that directory instead.
+If an older Vite+ install uses `%USERPROFILE%\.vite-plus`, source the `env.ps1` file in that directory instead.
 
 Add that line to the end of your PowerShell `$PROFILE` to apply it automatically in new shells. It does not require elevated privileges.
 
@@ -151,10 +169,7 @@ vp-use --unset
 
 Only `vp env use` needs this alternate command. Other `vp env` commands work normally in Command Prompt. `vp env setup` creates `vp-use.cmd` in the bin directory on Windows.
 
-In CI, `vp env use` can run without shell initialization. It writes a temporary
-session file per runtime or package manager in the resolved state directory,
-such as `.session-node-version` or `.session-pnpm-version`. Later
-shim calls in the same job use these files to resolve the same environment.
+In CI, `vp env use` can run without shell initialization. It writes a temporary session file per runtime or package manager in the resolved state directory, such as `.session-node-version` or `.session-pnpm-version`. Later shim calls in the same job use these files to resolve the same environment.
 
 ### Manage
 

package/docs/guide/fmt.md

@@ -20,9 +20,11 @@ vp fmt . --write
 
 Put formatting configuration directly in the `fmt` block in the root `vite.config.ts` so all your configuration stays in one place. We do not recommend using `.oxfmtrc.json` with Vite+.
 
-Vite+ does not currently support nested format configuration. For now, use [`fmt.overrides`](/guide/monorepo#format-overrides) in the root `vite.config.ts` for file- or package-specific options. The long-term behavior is open for discussion; [share your use case and expectations](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) to help shape it.
+When the workspace-root config has a `fmt` block, `vp fmt` and `vp check` use it even when run from a package directory. Package configs cannot replace the root format settings. Commands keep the package working directory, so relative file arguments retain their meaning. Use [`fmt.overrides`](/guide/monorepo#format-overrides) for file- or package-specific options.
 
-For editors, disable nested formatter configs so format-on-save uses the root Vite+ `fmt` block:
+An explicit `vp fmt -c <path>` or `vp fmt --config <path>` selects another config. Otherwise, when running from the workspace root or when the root config has no `fmt` block, Oxfmt discovers the nearest `vite.config.*` file with a `fmt` block. Supported extensions are `.js`, `.mjs`, `.ts`, `.cjs`, `.mts`, and `.cts`. Nested configs do not override settings for individual files.
+
+For editors, disable nested formatter configs to prevent per-file overrides:
 
 ```json [.vscode/settings.json]
 {

package/docs/guide/global-cli.md

@@ -0,0 +1,426 @@
+<script setup lang="ts">
+import { getScrollOffset } from 'vitepress';
+import { nextTick, onMounted, onUnmounted } from 'vue';
+
+function openTarget() {
+  let target: HTMLElement | null;
+  try {
+    target = document.getElementById(decodeURIComponent(location.hash.slice(1)));
+  } catch {
+    return;
+  }
+  if (!target?.closest('details')) return;
+
+  for (let details = target.closest('details'); details; details = details.parentElement?.closest('details') ?? null) {
+    details.open = true;
+  }
+
+  // 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);
+  });
+}
+
+function onAnchorClick(event: MouseEvent) {
+  if (event.button !== 0 || event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;
+  const link = event.target instanceof Element ? event.target.closest('a') : null;
+  // Clicking the current hash again does not emit hashchange.
+  if (link?.href === location.href) openTarget();
+}
+
+onMounted(async () => {
+  window.addEventListener('hashchange', openTarget);
+  document.addEventListener('click', onAnchorClick);
+  await nextTick();
+  openTarget();
+});
+
+onUnmounted(() => {
+  window.removeEventListener('hashchange', openTarget);
+  document.removeEventListener('click', onAnchorClick);
+});
+</script>
+
+# Global CLI
+
+The global CLI is a standalone `vp` binary for machine-level runtime and package management. It includes a Vite+ toolchain, does not require Node.js to be installed first, and can be used without adding `vite-plus` to a project.
+
+Choose the global CLI when you want one command available across projects for any combination of:
+
+- managing Node.js and package-manager versions
+- selecting and downloading package managers
+- installing dependencies and running package binaries
+- running `package.json` scripts and cached workspace tasks
+- using the Vite+ frontend toolchain without pinning it in every project
+
+Installing the global CLI does not require you to adopt the project-local package. You can use it only for runtime management, package management, and the task runner if that is all you need.
+
+## Install
+
+::: code-group
+
+```bash [macOS / Linux]
+curl -fsSL https://vite.plus | bash
+```
+
+```powershell [Windows]
+irm https://vite.plus/ps1 | iex
+```
+
+:::
+
+On Windows, you can instead download and run [`vp-setup.exe`](https://setup.viteplus.dev).
+
+After installation, open a new shell and run:
+
+```bash
+vp help
+```
+
+When you enable environment management during installation, Vite+ records managed mode for Node.js and the npm, pnpm, Yarn, and Bun shims. Run `vp env off` to prefer system tools, or scope the change with `vp env off node` or `vp env off pm`.
+
+::: details Installer Environment Variables & Options
+
+The Vite+ installers (`vp-setup.exe`, `install.ps1`, and `install.sh`) and the installed `vp` CLI read the environment variables below.
+
+### 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:
+
+#### Nushell and XDG directories
+
+If you customize `XDG_DATA_HOME` or `XDG_CONFIG_HOME`, set them **before starting Nushell**, through your terminal application, operating system, or parent shell. This is a [Nushell startup requirement](https://www.nushell.sh/book/configuration.html#changing-default-directories); setting them only in `config.nu` or `env.nu` does not configure the running session's startup directories.
+
+Assignments in those files still affect child processes. The Vite+ installer starts a child Nushell to locate its vendor autoload directory, so it can write `vite-plus.nu` to a directory that normal new sessions do not read. Installation can succeed while `vp` remains unavailable in those sessions.
+
+If this happens, open your Nushell configuration with `config nu` and add a `source` line pointing to the installed Vite+ `env.nu` file. For a default fresh macOS or Linux installation without a custom `XDG_CONFIG_HOME`, use:
+
+```nu
+source ~/.config/vite-plus/env.nu
+```
+
+For a custom `XDG_CONFIG_HOME`, use the absolute path to `<XDG_CONFIG_HOME>/vite-plus/env.nu` as resolved during installation. For an installation under `VP_HOME` or an existing `~/.vite-plus` installation, use `<VP_HOME>/env.nu` or `~/.vite-plus/env.nu` instead. Replace placeholders with actual paths and quote paths containing spaces. Open a new Nushell session and run `vp help` to verify the configuration.
+
+#### `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.
+
+:::
+
+### Homebrew
+
+For a Homebrew installation, the first `vp` command sets up your shell, shims, and environment-management preferences. It reuses Homebrew's binary and bundled JavaScript. Setup stores its completion state in your user directories and does not need write access to the Homebrew prefix.
+
+Later commands reuse that setup while the installed binary remains unchanged. Generated shims follow Homebrew's public `vp` entrypoint when Homebrew replaces a version. Setup preserves your saved management preferences during this replacement.
+
+To prefer your existing Node.js and package managers during the first run, use:
+
+```bash
+VP_NODE_MANAGER=no VP_PM_MANAGER=no vp help
+```
+
+After setup, use `vp env off` to change this preference. Commands that need missing runtimes or project dependencies can still download them.
+
+Use Homebrew to [upgrade](/guide/upgrade#homebrew) or [remove](/guide/implode#homebrew) its package.
+
+`vp env doctor` identifies the Homebrew installation and its binary path. It checks the `vp` command and the user shim directory on `PATH` separately. If only the shim directory is missing, follow its shell setup instructions to enable the shims.
+
+## Use It Without a Local Package
+
+The global installation is enough for runtime, package-manager, and task-runner workflows:
+
+```bash
+vp env pin lts       # Pin and install Node.js for this project
+vp install           # Use the package manager declared by the project
+vp run build         # Run a package.json script or configured task
+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.
+
+## 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.
+
+For development commands such as `vp dev`, `vp build`, `vp test`, and `vp run`, the global CLI delegates to the project's installed version when available:
+
+| Current project                     | Toolchain used by `vp`            |
+| ----------------------------------- | --------------------------------- |
+| Has `vite-plus` installed locally   | The project's installed toolchain |
+| Does not have `vite-plus` installed | The globally installed toolchain  |
+
+In a monorepo, the local installation can be shared at the workspace root. You do not need to install `vite-plus` separately in every package.
+
+For example, if a project has Vite+ version A installed and your global installation is version B, `vp build` uses version A's toolchain. Upgrading the global installation does not change that project's installed toolchain.
+
+Package-manager commands such as `vp install` and `vp add` use the global CLI. Commands for managing your environment or global installation, such as `vp env`, `vp upgrade`, and `vp implode`, also stay with the global CLI regardless of the project's version.
+
+To see which toolchain is selected for your current project, run `vp toolchain`. Use `vp toolchain --global` to inspect the global installation.
+
+## 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.
+- [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.
+
+::: details Platform support
+
+Prebuilt binaries are distributed for:
+
+- Linux x64 and arm64 with glibc
+- Windows x64 and arm64
+- macOS x64 and arm64
+- Linux x64 and arm64 with musl
+
+If a prebuilt binary is not available for your platform, installation fails with an error. On Alpine Linux, install `libstdc++` before using the managed [unofficial Node.js builds](https://unofficial-builds.nodejs.org/):
+
+```sh
+apk add libstdc++
+```
+
+:::

package/docs/guide/ide-integration.md

@@ -120,8 +120,7 @@ For the best Vite+ experience with JetBrains IDEs such as IntelliJ & WebStorm, i
 When you create or migrate a project, Vite+ prompts you to choose whether you want the editor config written for JetBrains IDEs.
 
 ::: tip Vite+ does not merge with existing config files
-Due to some complexities with merging XML files, Vite+ currently does not merge your current files if the files already exist.
-You'll be given the opportunity to replace any existing files, instead of merging.
+Due to some complexities with merging XML files, Vite+ currently does not merge your current files if the files already exist. You'll be given the opportunity to replace any existing files, instead of merging.
 :::
 
 You can also manually set up the IDE configuration to match your Vite+ setup:

package/docs/guide/implode.md

@@ -1,6 +1,6 @@
 # Removing Vite+
 
-Use `vp implode` to remove `vp` and all related Vite+ data from your machine.
+Use `vp implode` to remove the Vite+-managed [global `vp` installation](/guide/global-cli) and related user data from your machine. It does not remove `vite-plus` dependencies from projects or packages owned by Homebrew.
 
 ## Overview
 
@@ -21,3 +21,16 @@ Skip the confirmation prompt with:
 ```bash
 vp implode --yes
 ```
+
+## Homebrew
+
+Run `vp implode` first to remove Vite+-managed runtimes, global packages, configuration, shims, and shell entries. Then remove the Homebrew package:
+
+```bash
+vp implode
+brew uninstall vite-plus
+```
+
+The confirmation prompt explains that the Homebrew package will remain installed. After cleanup, `vp implode` directs you to `brew uninstall vite-plus`.
+
+Restart your terminal before you run `vp` again. In Bash, you can run `hash -r` instead to clear cached command paths. If the Homebrew package is still installed, the next `vp` command starts first-run setup again.