vite-plus 0.3.2 → 0.3.3

package/docs/guide/ci.md

@@ -10,37 +10,7 @@ You can use `voidzero-dev/setup-vp` to use Vite+ in CI environments.
 
 Set `<setup-vp-version>` in each example to an exact version from the [`setup-vp` releases page](https://github.com/voidzero-dev/setup-vp/releases). You can use a commit SHA instead. Do not use the `v1` tag. The `v1` tag no longer receives updates.
 
-Run `vp migrate` to replace exact `voidzero-dev/setup-vp@v1` references in
-GitHub Actions workflows and composite actions under `.github` with the latest
-exact release known to your Vite+ version. Existing exact versions and commit
-SHAs remain unchanged.
-
-### Automatic Version Updates
-
-Dependabot and Renovate can update exact versions in GitHub Actions workflows.
-
-To use [Dependabot version updates](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates), add a `github-actions` entry to `.github/dependabot.yml`:
-
-```yaml [.github/dependabot.yml]
-version: 2
-updates:
-  - package-ecosystem: github-actions
-    directory: /
-    schedule:
-      interval: weekly
-```
-
-Dependabot checks `uses:` entries in `.github/workflows` each week.
-
-[Renovate's GitHub Actions manager](https://docs.renovatebot.com/modules/manager/github-actions/) detects `uses:` entries by default. You do not need a package rule for `setup-vp`.
-
-When you use a commit SHA, add the exact release tag in a comment. Renovate uses the comment to find updates:
-
-```yaml
-- uses: voidzero-dev/setup-vp@<commit-sha> # <setup-vp-version>
-```
-
-These settings apply only to GitHub Actions workflows. For GitLab CI/CD and Azure Pipelines, update both version values together.
+Run `vp migrate` to replace exact `voidzero-dev/setup-vp@v1` references in GitHub Actions workflows and composite actions under `.github` with the latest exact release known to your Vite+ version. Existing exact versions and commit SHAs remain unchanged.
 
 ## GitHub Actions
 
@@ -125,6 +95,33 @@ The Azure Pipelines template supports Microsoft-hosted Linux, macOS, and Windows
 
 For advanced configuration and the complete parameter reference, see the [`setup-vp` Azure Pipelines documentation](https://github.com/voidzero-dev/setup-vp#azure-pipelines).
 
+## Automatic Version Updates
+
+Dependabot and Renovate can update exact versions in GitHub Actions workflows.
+
+To use [Dependabot version updates](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates), add a `github-actions` entry to `.github/dependabot.yml`:
+
+```yaml [.github/dependabot.yml]
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+```
+
+Dependabot checks `uses:` entries in `.github/workflows` each week.
+
+[Renovate's GitHub Actions manager](https://docs.renovatebot.com/modules/manager/github-actions/) detects `uses:` entries by default. You do not need a package rule for `setup-vp`.
+
+When you use a commit SHA, add the exact release tag in a comment. Renovate uses the comment to find updates:
+
+```yaml
+- uses: voidzero-dev/setup-vp@<commit-sha> # <setup-vp-version>
+```
+
+These settings apply only to GitHub Actions workflows. For GitLab CI/CD and Azure Pipelines, update both version values together.
+
 ## Simplifying Existing Workflows
 
 If you are migrating an existing GitHub Actions workflow, you can often replace large blocks of Node, package-manager, and cache setup with a single `setup-vp` step.

package/docs/guide/commit-hooks.md

@@ -1,7 +1,6 @@
 # Commit Hooks
 
-Use `vp hooks` to manage the Git hook dispatcher, `vp config` for project setup
-(hooks + agent integration), and `vp staged` to run checks on staged files.
+Use `vp hooks` to manage the Git hook dispatcher, `vp config` for project setup (hooks + agent integration), and `vp staged` to run checks on staged files.
 
 ## Overview
 
@@ -64,10 +63,7 @@ Check the `Dispatcher` and `core.hooksPath` lines to see whether hooks are actua
 
 ### `vp config`
 
-`vp config` configures Vite+ for the current project. It installs the generated Git hook
-dispatcher (unless hooks were disabled with `vp hooks disable`) and can also handle related
-project integration such as agent setup. The hooks directory defaults to `.vite-hooks`, or the
-last directory used by `vp hooks` / `vp config` in this clone:
+`vp config` configures Vite+ for the current project. It installs the generated Git hook dispatcher (unless hooks were disabled with `vp hooks disable`) and can also handle related project integration such as agent setup. The hooks directory defaults to `.vite-hooks`, or the last directory used by `vp hooks` / `vp config` in this clone:
 
 ```bash
 vp config
@@ -76,24 +72,15 @@ vp config --no-hooks
 vp config --no-agent
 ```
 
-Use `--no-hooks` when you want `vp config` to leave the Git hook dispatcher unchanged. Use
-`--no-agent` when you want it to skip updates to existing coding agent instruction files. You can
-pass both flags when you want `vp config` to skip both setup steps. After `vp hooks disable`,
-`vp config` skips reinstalling the dispatcher and points you at `vp hooks enable` instead of
-prompting again.
+Use `--no-hooks` when you want `vp config` to leave the Git hook dispatcher unchanged. Use `--no-agent` when you want it to skip updates to existing coding agent instruction files. You can pass both flags when you want `vp config` to skip both setup steps. After `vp hooks disable`, `vp config` skips reinstalling the dispatcher and points you at `vp hooks enable` instead of prompting again.
 
-You can also set `VP_GIT_HOOKS=0` to disable hook installation from lifecycle scripts such as
-`prepare` or `postinstall`.
+You can also set `VP_GIT_HOOKS=0` to disable hook installation from lifecycle scripts such as `prepare` or `postinstall`.
 
-Project-owned hook scripts such as `.vite-hooks/pre-commit` should be committed to the repository.
-The generated dispatcher and shims under `.vite-hooks/_` are ignored and recreated by `vp config`
-or `vp hooks enable`. Neither command creates or modifies project hook scripts or staged-file
-configuration.
+Project-owned hook scripts such as `.vite-hooks/pre-commit` should be committed to the repository. The generated dispatcher and shims under `.vite-hooks/_` are ignored and recreated by `vp config` or `vp hooks enable`. Neither command creates or modifies project hook scripts or staged-file configuration.
 
 ### `vp staged`
 
-`vp staged` runs staged-file checks using the `staged` config from `vite.config.ts`. To run it
-before each commit, add it to the project-owned pre-commit hook:
+`vp staged` runs staged-file checks using the `staged` config from `vite.config.ts`. To run it before each commit, add it to the project-owned pre-commit hook:
 
 ```bash
 vp staged
@@ -119,12 +106,7 @@ export default defineConfig({
 });
 ```
 
-This is the default Vite+ approach and should replace separate `lint-staged` configuration in most
-projects. When you opt into hooks during `vp create`, Vite+ scaffolds both this configuration and
-the corresponding pre-commit hook. During `vp migrate`, existing hook policy is preserved, and
-the default is introduced only when no existing hook policy is found. Because
-`vp staged` reads from `vite.config.ts`, your staged-file checks stay in the same place as your
-lint, format, test, build, and task-runner config.
+This is the default Vite+ approach and should replace separate `lint-staged` configuration in most projects. When you opt into hooks during `vp create`, Vite+ scaffolds both this configuration and the corresponding pre-commit hook. During `vp migrate`, existing hook policy is preserved, and the default is introduced only when no existing hook policy is found. Because `vp staged` reads from `vite.config.ts`, your staged-file checks stay in the same place as your lint, format, test, build, and task-runner config.
 
 ## Disabling Hooks in Specific Environments
 
@@ -157,8 +139,7 @@ Because the hook itself reads this file, it works even when the committing proce
 
 ## Removing commit hooks
 
-To stop using the Vite+ hook dispatcher in this clone (and keep `prepare` / `vp config` from
-reinstalling it):
+To stop using the Vite+ hook dispatcher in this clone (and keep `prepare` / `vp config` from reinstalling it):
 
 ```bash
 vp hooks disable
@@ -170,8 +151,7 @@ This:
 
 1. Unsets `core.hooksPath` when it points at the Vite+ dispatcher
 2. Removes the generated `<hooks-dir>/_` directory
-3. Records a **local** disable preference so lifecycle scripts skip reinstall until you run
-   `vp hooks enable` again
+3. Records a **local** disable preference so lifecycle scripts skip reinstall until you run `vp hooks enable` again
 
 To re-enable:
 
@@ -179,8 +159,7 @@ To re-enable:
 vp hooks enable
 ```
 
-If you no longer want hooks for the project at all (shared with teammates), also remove `vp config`
-from the `prepare` or `postinstall` script in `package.json`.
+If you no longer want hooks for the project at all (shared with teammates), also remove `vp config` from the `prepare` or `postinstall` script in `package.json`.
 
 ### Manual equivalent
 
@@ -195,6 +174,4 @@ git config --local vp.hooks.disabled true
 # git config --local vp.hooks.dir .vite-hooks
 ```
 
-Project-owned scripts such as `.vite-hooks/pre-commit` and the `staged` block in `vite.config.ts`
-can remain for later use, or you can remove them separately if the project no longer needs them.
-`vp hooks disable` does **not** delete those project-owned files.
+Project-owned scripts such as `.vite-hooks/pre-commit` and the `staged` block in `vite.config.ts` can remain for later use, or you can remove them separately if the project no longer needs them. `vp hooks disable` does **not** delete those project-owned files.

package/docs/guide/create.md

@@ -57,8 +57,7 @@ Run `vp create --list` to see the built-in templates and the common shorthand te
 - `--hooks` enables pre-commit hook setup (dispatcher + `.vite-hooks` + `staged` config)
 - `--no-hooks` skips hook setup
 
-After create, manage the dispatcher with `vp hooks status`, `vp hooks disable`, and `vp hooks enable`.
-See the [Commit hooks guide](/guide/commit-hooks).
+After create, manage the dispatcher with `vp hooks status`, `vp hooks disable`, and `vp hooks enable`. See the [Commit hooks guide](/guide/commit-hooks).
 
 ### Dependency build scripts
 

package/docs/guide/docker.md

@@ -6,16 +6,11 @@ Vite+ publishes an official Docker image with the `vp` CLI preinstalled:
 ghcr.io/voidzero-dev/vite-plus
 ```
 
-Use it for builds, CI, and devcontainers. It is not intended as a production
-runtime image.
+Use it for builds, CI, and devcontainers. It is not intended as a production runtime image.
 
-`vp` resolves the Node.js version from your project (`.node-version`,
-`devEngines.runtime`, or `engines.node`) and downloads that exact version during
-install/build. This means the image does not need Node-version-specific tags.
+`vp` resolves the Node.js version from your project (`.node-version`, `devEngines.runtime`, or `engines.node`) and downloads that exact version during install/build. This means the image does not need Node-version-specific tags.
 
-For production, use a multi-stage build: build the app with the Vite+ image, then
-copy only the resolved Node.js binary, build output, and production dependencies
-into a smaller runtime image.
+For production, use a multi-stage build: build the app with the Vite+ image, then copy only the resolved Node.js binary, build output, and production dependencies into a smaller runtime image.
 
 ## Image tags
 
@@ -28,19 +23,13 @@ Tags track the `vp` version:
 | `ghcr.io/voidzero-dev/vite-plus:<major>.<minor>`         | Latest minor   |
 | `ghcr.io/voidzero-dev/vite-plus:<major>.<minor>.<patch>` | Exact version  |
 
-The examples use `:latest` to track the newest release; pin an exact tag or a
-digest if you need reproducible builds. The image is published for `linux/amd64`
-and `linux/arm64` and runs as the non-root `vp` user by default. That user has
-passwordless `sudo`, so build/CI steps that need root (extra apt packages,
-`playwright install --with-deps`) work without changing the image user.
+The examples use `:latest` to track the newest release; pin an exact tag or a digest if you need reproducible builds. The image is published for `linux/amd64` and `linux/arm64` and runs as the non-root `vp` user by default. That user has passwordless `sudo`, so build/CI steps that need root (extra apt packages, `playwright install --with-deps`) work without changing the image user.
 
 Browse all published versions and digests on the [GitHub package page](https://github.com/voidzero-dev/vite-plus/pkgs/container/vite-plus).
 
 ## Production: SSR / Node.js server app
 
-For apps that run Node.js in production (SvelteKit, Nuxt, a custom Vite SSR
-server, and so on), build with the toolchain image and copy the resolved Node.js
-and the built app into a slim runtime stage:
+For apps that run Node.js in production (SvelteKit, Nuxt, a custom Vite SSR server, and so on), build with the toolchain image and copy the resolved Node.js and the built app into a slim runtime stage:
 
 ```dockerfile [Dockerfile]
 # syntax=docker/dockerfile:1
@@ -86,28 +75,19 @@ EXPOSE 3000
 CMD ["node", "dist/server.js"]
 ```
 
-The deployed image contains only Node.js plus your app and production
-dependencies, and matches `.node-version` exactly. It is much smaller than the
-default `node:*` image; see the distroless tip below for the smallest result.
+The deployed image contains only Node.js plus your app and production dependencies, and matches `.node-version` exactly. It is much smaller than the default `node:*` image; see the distroless tip below for the smallest result.
 
 ::: warning Prune production dependencies in a separate stage
-Install production dependencies in their own `deps` stage as shown. Running
-`vp install --prod` after a full `vp install` in the same stage does not remove
-the already-installed devDependencies, so the `vite-plus` toolchain would be
-copied into the runtime image. If your server bundle is fully self-contained (no
-un-bundled runtime dependencies), you can skip copying `node_modules` entirely.
+Install production dependencies in their own `deps` stage as shown. Running `vp install --prod` after a full `vp install` in the same stage does not remove the already-installed devDependencies, so the `vite-plus` toolchain would be copied into the runtime image. If your server bundle is fully self-contained (no un-bundled runtime dependencies), you can skip copying `node_modules` entirely.
 :::
 
 ::: tip Smaller still
-For a shell-less, minimal-CVE runtime, swap the runtime base for distroless
-(`gcr.io/distroless/cc`) and keep an `ENTRYPOINT` in vector form. It is glibc
-based, so the copied Node.js binary remains compatible.
+For a shell-less, minimal-CVE runtime, swap the runtime base for distroless (`gcr.io/distroless/cc`) and keep an `ENTRYPOINT` in vector form. It is glibc based, so the copied Node.js binary remains compatible.
 :::
 
 ## Production: static SPA / SSG
 
-A static site needs no Node.js at runtime; serve the build output with any static
-server:
+A static site needs no Node.js at runtime; serve the build output with any static server:
 
 ```dockerfile [Dockerfile]
 FROM ghcr.io/voidzero-dev/vite-plus:latest AS build
@@ -123,8 +103,7 @@ COPY --from=build /app/dist /usr/share/nginx/html
 
 ## Continuous integration
 
-Use the image directly in container-based CI (GitLab CI, Buildkite, CircleCI,
-Jenkins, and others):
+Use the image directly in container-based CI (GitLab CI, Buildkite, CircleCI, Jenkins, and others):
 
 ```yaml [.gitlab-ci.yml]
 build:
@@ -140,11 +119,7 @@ On GitHub Actions, prefer [`setup-vp`](./ci) instead of the image.
 
 ## Browser mode tests (Vitest / Playwright)
 
-Running as the non-root `vp` user is what you want for browsers: Chromium keeps
-its sandbox (running a browser as root disables it). Install the browser and its
-system libraries in the job. `playwright install --with-deps` needs root to
-`apt-get install` those libraries. The `vp` user has passwordless `sudo`, so
-Playwright uses it to install them without changing the image user:
+Running as the non-root `vp` user is what you want for browsers: Chromium keeps its sandbox (running a browser as root disables it). Install the browser and its system libraries in the job. `playwright install --with-deps` needs root to `apt-get install` those libraries. The `vp` user has passwordless `sudo`, so Playwright uses it to install them without changing the image user:
 
 ```yaml [.gitlab-ci.yml]
 test:
@@ -155,15 +130,9 @@ test:
     - vp test
 ```
 
-`vp exec` runs the project's own Playwright (from your lockfile), so it installs
-the browser revision your tests expect. Prefer it over `vpx playwright install`,
-which would download whatever Playwright is latest and can fetch a different
-browser revision.
+`vp exec` runs the project's own Playwright (from your lockfile), so it installs the browser revision your tests expect. Prefer it over `vpx playwright install`, which would download whatever Playwright is latest and can fetch a different browser revision.
 
-To bake the browser and its libraries into a derived image instead of installing
-them on every run, install the project dependencies first so the baked browser
-matches your lockfile, then install with the project's Playwright (root is
-available through `sudo`):
+To bake the browser and its libraries into a derived image instead of installing them on every run, install the project dependencies first so the baked browser matches your lockfile, then install with the project's Playwright (root is available through `sudo`):
 
 ```dockerfile [Dockerfile]
 FROM ghcr.io/voidzero-dev/vite-plus:latest
@@ -173,13 +142,11 @@ RUN vp install --frozen-lockfile
 RUN vp exec playwright install --with-deps chromium
 ```
 
-If Chromium crashes under load in CI, give the container more shared memory with
-`--ipc=host`; see the [Playwright Docker docs](https://playwright.dev/docs/docker).
+If Chromium crashes under load in CI, give the container more shared memory with `--ipc=host`; see the [Playwright Docker docs](https://playwright.dev/docs/docker).
 
 ## Devcontainers
 
-Use the image as a ready-to-go development container with the toolchain
-preinstalled:
+Use the image as a ready-to-go development container with the toolchain preinstalled:
 
 ```jsonc [.devcontainer/devcontainer.json]
 {
@@ -197,23 +164,8 @@ docker run --rm -it -v "$PWD:/app" -w /app ghcr.io/voidzero-dev/vite-plus vp bui
 
 ## Notes
 
-- **Node.js version**: provisioned from `.node-version`, `engines.node`, or
-  `devEngines.runtime` at build time, so there is no Node.js-specific image tag. The
-  dependency `COPY` uses a `.node-version*` glob so the file is optional: projects
-  that pin via `engines.node`/`devEngines.runtime` need no `.node-version`, and
-  those that use one have it available in every stage.
-- **Non-root user**: the image runs as the non-root `vp` user, so copy sources
-  with `COPY --chown=vp:vp ...` as shown. Without it, `COPY` writes root-owned
-  files that `vp install` cannot update (permission denied). The `vp` user has
-  passwordless `sudo` for the occasional root step (installing extra apt packages
-  or `playwright install --with-deps`), so you rarely need to switch the image
-  user. The production runtime stage is a separate, vp-free base image, so this
-  convenience does not reach your deployed image.
-- **Native addons**: the image includes a C/C++ build toolchain (`build-essential`,
-  `python3`), so native dependencies such as `better-sqlite3` compile during
-  `vp install`.
-- **glibc**: the image is glibc based so it uses the official, signature-verified
-  Node.js builds.
-- **Custom base image**: to add `vp` to your own base image instead, run the
-  installer: `curl -fsSL https://vite.plus | bash` (set `VP_VERSION` to pin a
-  version).
+- **Node.js version**: provisioned from `.node-version`, `engines.node`, or `devEngines.runtime` at build time, so there is no Node.js-specific image tag. The dependency `COPY` uses a `.node-version*` glob so the file is optional: projects that pin via `engines.node`/`devEngines.runtime` need no `.node-version`, and those that use one have it available in every stage.
+- **Non-root user**: the image runs as the non-root `vp` user, so copy sources with `COPY --chown=vp:vp ...` as shown. Without it, `COPY` writes root-owned files that `vp install` cannot update (permission denied). The `vp` user has passwordless `sudo` for the occasional root step (installing extra apt packages or `playwright install --with-deps`), so you rarely need to switch the image user. The production runtime stage is a separate, vp-free base image, so this convenience does not reach your deployed image.
+- **Native addons**: the image includes a C/C++ build toolchain (`build-essential`, `python3`), so native dependencies such as `better-sqlite3` compile during `vp install`.
+- **glibc**: the image is glibc based so it uses the official, signature-verified Node.js builds.
+- **Custom base image**: to add `vp` to your own base image instead, run the installer: `curl -fsSL https://vite.plus | bash` (set `VP_VERSION` to pin a version).

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
@@ -76,16 +89,17 @@ 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` 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 directly invoked npm shim keeps its Node-bundled fallback, while an explicit `vp env ... npm` family scope uses standalone npm's latest release.
+
+::: 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.
+:::
 
-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.
+## Environment Modes
+
+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.
 
-If you want to keep that behavior, run:
+To enable managed mode, run:
 
 ```bash
 vp env on
@@ -124,8 +138,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 +164,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