vite-plus 0.2.7 → 0.2.9

package/docs/guide/commit-hooks.md

@@ -1,6 +1,7 @@
 # Commit Hooks
 
-Use `vp config` to install commit hooks, 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
 
@@ -8,16 +9,65 @@ Vite+ supports commit hooks and staged-file checks without additional tooling.
 
 Use:
 
-- `vp config` to set up project hooks and related integrations
+- `vp hooks enable` / `disable` / `status` to manage the generated hook dispatcher
+- `vp config` to install the dispatcher (when not disabled) and update agent integration
 - `vp staged` to run checks against the files currently staged in Git
 
 If you use [`vp create`](/guide/create) or [`vp migrate`](/guide/migrate), Vite+ prompts you to set this up for your project automatically.
 
+### Quick start
+
+```bash
+# Install or refresh the dispatcher
+vp hooks enable
+
+# Check what is active in this clone
+vp hooks status
+
+# Turn hooks off in this clone (survives npm install / prepare)
+vp hooks disable
+
+# Turn them back on
+vp hooks enable
+```
+
 ## Commands
 
+### `vp hooks`
+
+Manage the Vite+ Git hook dispatcher for the current repository:
+
+```bash
+vp hooks enable
+vp hooks enable --hooks-dir .custom-hooks
+vp hooks disable
+vp hooks status
+```
+
+| Command   | Behavior                                                                                                                                                                                                           |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `enable`  | Install or refresh the generated dispatcher under `<hooks-dir>/_` and set `core.hooksPath`. Clears a previous disable preference.                                                                                  |
+| `disable` | Tear down the dispatcher (unset `core.hooksPath` when it points at Vite+, remove `<hooks-dir>/_`) and **persist** the disable decision in local git config so `vp config` / lifecycle scripts do not reinstall it. |
+| `status`  | Show preference, `core.hooksPath`, dispatcher presence, and project-owned hook scripts.                                                                                                                            |
+
+By default, project hooks live in `.vite-hooks`. Pass `--hooks-dir` to use another subdirectory. After the first successful enable, the directory is remembered in local git config for later `enable` / `disable` / `status` / `vp config` calls in this clone.
+
+`status` reports preference as:
+
+- `not set` — no disable preference and no prior enable in this clone
+- `enabled` — enable has run (or the dispatcher is currently owned)
+- `disabled (local)` — after `vp hooks disable`
+
+Check the `Dispatcher` and `core.hooksPath` lines to see whether hooks are actually active.
+
+`disable` / `enable` do **not** delete project-owned hook scripts (for example `.vite-hooks/pre-commit`), the `staged` block in `vite.config.ts`, or lifecycle scripts that call `vp config`.
+
 ### `vp config`
 
-`vp config` configures Vite+ for the current project. It installs Git hooks, sets up the hook directory, and can also handle related project integration such as agent setup. By default, hooks are written to `.vite-hooks`:
+`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
@@ -26,16 +76,24 @@ vp config --no-hooks
 vp config --no-agent
 ```
 
-Use `--no-hooks` when you want `vp config` to leave existing Git hook setup 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.
+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 `VITE_GIT_HOOKS=0` to disable hook installation from lifecycle scripts such as
+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.
+
 ### `vp staged`
 
-`vp staged` runs staged-file checks using the `staged` config from `vite.config.ts`. If you set up Vite+ to handle your commit hooks, it will automatically run when you commit your local changes.
+`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
@@ -43,6 +101,10 @@ vp staged --verbose
 vp staged --fail-on-changes
 ```
 
+```sh [.vite-hooks/pre-commit]
+vp staged
+```
+
 ## Configuration
 
 Define staged-file checks in the `staged` block in `vite.config.ts`:
@@ -57,7 +119,12 @@ export default defineConfig({
 });
 ```
 
-This is the default Vite+ approach and should replace separate `lint-staged` configuration in most projects. 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
 
@@ -65,13 +132,13 @@ The installed hooks check the environment on every run, so you can disable them
 
 ### Environment variable
 
-Set `VITE_GIT_HOOKS=0` in the environment of the process that runs `git commit`, and every Vite+ hook exits immediately without running:
+Set `VP_GIT_HOOKS=0` in the environment of the process that runs `git commit`, and every Vite+ hook exits immediately without running:
 
 ```bash
-VITE_GIT_HOOKS=0 git commit -m "content update"
+VP_GIT_HOOKS=0 git commit -m "content update"
 ```
 
-`HUSKY=0` is honored the same way for ecosystem tooling compatibility. Setting `VITE_GIT_HOOKS=0` in an environment also keeps `vp config` from reinstalling hooks there when a lifecycle script such as `prepare` runs.
+`HUSKY=0` is honored the same way for ecosystem tooling compatibility. Setting `VP_GIT_HOOKS=0` in an environment also keeps `vp config` / `vp hooks enable` from reinstalling hooks there when a lifecycle script such as `prepare` runs.
 
 ### Init script
 
@@ -83,27 +150,51 @@ Before checking the environment variable, each hook sources an init script if on
 To disable hooks for a whole machine, create the init script and export the variable there:
 
 ```sh [~/.config/vite-plus/hooks-init.sh]
-export VITE_GIT_HOOKS=0
+export VP_GIT_HOOKS=0
 ```
 
 Because the hook itself reads this file, it works even when the committing process does not inherit your shell environment, for example if a daemon or web server is making commits.
 
 ## Removing commit hooks
 
-To fully remove Vite+ commit hooks, undo each thing `vp config` set up:
-
-1. Unset the Git hooks path that points at the Vite+ dispatcher:
+To stop using the Vite+ hook dispatcher in this clone (and keep `prepare` / `vp config` from
+reinstalling it):
 
 ```bash
-git config --unset core.hooksPath
+vp hooks disable
+# or, if you used a custom directory:
+vp hooks disable --hooks-dir .custom-hooks
 ```
 
-2. Remove the hooks directory (use your `--hooks-dir` value if you changed it):
+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
+
+To re-enable:
 
 ```bash
-rm -rf .vite-hooks
+vp hooks enable
 ```
 
-3. Remove `vp config` from the `prepare` script in `package.json`. Otherwise the next install re-runs `vp config` and reinstalls the hooks.
+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
+
+If you prefer to do it by hand:
+
+```bash
+git config --unset core.hooksPath
+rm -rf .vite-hooks/_
+# optional: prevent prepare/vp config from reinstalling in this clone
+git config --local vp.hooks.disabled true
+# optional: remembered hooks directory (set by enable/disable)
+# git config --local vp.hooks.dir .vite-hooks
+```
 
-4. Remove the `staged` block from `vite.config.ts` if it exists
+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

@@ -49,23 +49,26 @@ Run `vp create --list` to see the built-in templates and the common shorthand te
 - `--no-editor` skips editor config setup
 - `--git` initialize a git repository
 - `--no-git` skips git repository initialization
-- `--hooks` enables pre-commit hook setup
-- `--no-hooks` skips hook setup
 - `--package-manager <name>` uses a specified package manager (`pnpm`, `npm`, `yarn`, or `bun`)
 - `--approve-builds` approves and runs gated dependency build scripts without prompting
 - `--no-interactive` runs without prompts
 - `--verbose` shows detailed scaffolding output
 - `--list` prints the available built-in and popular templates
+- `--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).
 
 ### Dependency build scripts
 
-For security, pnpm, bun, and yarn (Berry) do not run a dependency's build scripts (`install` / `postinstall`, e.g. native builds like `better-sqlite3`) until you approve them. When a template adds such a dependency directly, `vp create` surfaces it after installing instead of leaving the project in a half-built state:
+For security, pnpm, bun, yarn (Berry), and npm (v12+) do not run a dependency's build scripts (`install` / `postinstall`, e.g. native builds like `better-sqlite3`) until you approve them. When a template adds such a dependency directly, `vp create` surfaces it after installing instead of leaving the project in a half-built state:
 
 - Interactive: you are asked which of those dependencies to approve and build (nothing is selected by default).
 - Non-interactive: a note lists them and points at `vp pm approve-builds`.
 - `--approve-builds`: approves and builds them automatically, so non-interactive runs (CI) can produce a ready-to-use project.
 
-Approval is recorded the way each package manager expects: pnpm's `allowBuilds`, bun's `trustedDependencies`, or yarn's `dependenciesMeta.<pkg>.built` (in the workspace root manifest). Transitive build scripts you did not choose (e.g. `esbuild` pulled in by Vite) are left at the package manager's defaults and are not surfaced. npm runs build scripts by default, so there is nothing to approve there.
+Approval is recorded the way each package manager expects: pnpm's `allowBuilds`, bun's `trustedDependencies`, npm's `allowScripts`, or yarn's `dependenciesMeta.<pkg>.built` (in the workspace root manifest). Transitive build scripts you did not choose (e.g. `esbuild` pulled in by Vite) are left at the package manager's defaults and are not surfaced. npm 11 and older run build scripts during install, so there is nothing to approve there.
 
 ## Template Options
 

package/docs/guide/env.md

@@ -6,12 +6,16 @@
 
 Managed mode is on by default, so `node`, `npm`, and related shims resolve through Vite+ and pick the right Node.js version for the current project.
 
-The project Node.js version is resolved from these sources, in priority order:
+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 (current or parent directories)
+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. The global default (`vp env default`), then the latest LTS
+4. `.nvmrc` file
+
+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.
 
@@ -112,7 +116,7 @@ vp env print                  # Print shell snippet for this session
 
 # Manage
 vp env pin lts                # Pin the project to the latest LTS release
-vp env install                # Install the version from .node-version or package.json
+vp env install                # Install the version from .node-version, package.json, or .nvmrc
 vp env default lts            # Set the global default version
 vp env use 20                 # Use Node.js 20 for the current shell session
 vp env use --unset            # Remove the session override

package/docs/guide/fmt.md

@@ -20,11 +20,11 @@ vp fmt . --write
 
 Put formatting configuration directly in the `fmt` block in `vite.config.ts` so all your configuration stays in one place. We do not recommend using `.oxfmtrc.json` with Vite+.
 
-For editors, point the formatter config path at `./vite.config.ts` so format-on-save uses the same `fmt` block:
+For editors, disable nested formatter configs so format-on-save uses the root Vite+ `fmt` block:
 
 ```json [.vscode/settings.json]
 {
-  "oxc.fmt.configPath": "./vite.config.ts"
+  "oxc.fmt.disableNestedConfig": true
 }
 ```
 

package/docs/guide/github-actions-cache.md

@@ -63,6 +63,10 @@ vp run lint # should print "cache hit"
 
 Restore `node_modules/.vite/task-cache` after `vp install`, because package installation can recreate or modify `node_modules`.
 
+Set `<setup-vp-version>` below 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.
+
+See [Automatic Version Updates](/guide/ci#automatic-version-updates) to configure Dependabot or Renovate.
+
 ```yaml [.github/workflows/ci.yml]
 name: CI
 
@@ -80,7 +84,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: voidzero-dev/setup-vp@v1
+      - uses: voidzero-dev/setup-vp@<setup-vp-version>
         with:
           node-version: '24'
           cache: true

package/docs/guide/ide-integration.md

@@ -26,7 +26,8 @@ You can also manually set up the VS Code config:
   "[javascriptreact]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
   "[typescript]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
   "[typescriptreact]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
-  "oxc.fmt.configPath": "./vite.config.ts",
+  "oxc.disableNestedConfig": true,
+  "oxc.fmt.disableNestedConfig": true,
   "editor.formatOnSave": true,
   "editor.formatOnSaveMode": "file",
   "editor.codeActionsOnSave": {
@@ -35,7 +36,7 @@ You can also manually set up the VS Code config:
 }
 ```
 
-This gives the project a shared default formatter and enables Oxc-powered fix actions on save. The language-specific override blocks (`[javascript]`, `[typescript]`, etc.) are required because VS Code prioritizes user-level `[language]` settings over the workspace-level `editor.defaultFormatter` — without them, a global Prettier configuration would silently take over. Setting `oxc.fmt.configPath` to `./vite.config.ts` keeps editor format-on-save aligned with the `fmt` block in your Vite+ config. Vite+ uses `formatOnSaveMode: "file"` because Oxfmt does not support partial formatting.
+This gives the project a shared default formatter and enables Oxc-powered fix actions on save. The language-specific override blocks (`[javascript]`, `[typescript]`, etc.) are required because VS Code prioritizes user-level `[language]` settings over the workspace-level `editor.defaultFormatter` — without them, a global Prettier configuration would silently take over. Setting `oxc.disableNestedConfig` and `oxc.fmt.disableNestedConfig` prevents nested Oxlint and Oxfmt configs from diverging from the root Vite+ config. Vite+ uses `formatOnSaveMode: "file"` because Oxfmt does not support partial formatting.
 
 To let the VS Code NPM Scripts panel run scripts through `vp`, add the following to your `.vscode/settings.json`:
 
@@ -99,3 +100,61 @@ You can also manually set up the Zed config:
 ```
 
 Setting `oxfmt.fmt.configPath` to `./vite.config.ts` keeps editor format-on-save aligned with the `fmt` block in your Vite+ config. The full generated config covers additional languages (CSS, HTML, JSON, Markdown, etc.) — run `vp create` or `vp migrate` to get the complete file written automatically.
+
+## JetBrains (IntelliJ, WebStorm, etc...)
+
+For the best Vite+ experience with JetBrains IDEs such as IntelliJ & WebStorm, install the [Oxc](https://plugins.jetbrains.com/plugin/27061-oxc) plugin from the JetBrains marketplace.
+
+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.
+:::
+
+You can also manually set up the IDE configuration to match your Vite+ setup:
+
+```xml [.idea/externalDependencies.xml]
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ExternalDependencies">
+    <plugin id="com.github.oxc.project.oxcintellijplugin" />
+  </component>
+</project>
+```
+
+```xml [.idea/workspace.xml]
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <!-- other settings... -->
+  <component name="PropertiesComponent">
+    <![CDATA[{
+      "keyToString": {
+        // other settings
+        "javascript.nodejs.core.library.configured.version": "24.18.0", // Replace with your selected Node.js version
+        "javascript.nodejs.core.library.typings.version": "24.13.3", // Replace with the version of @types/node that corresponds to your runtime (or omit if you don't want it)
+        "javascript.preferred.runtime.type.id": "node",
+        "nodejs_interpreter_path": "$USER_HOME$/.vite-plus/bin/node",
+        "nodejs_package_manager_path": "pnpm" // Replace with your package manager of choice
+      }
+    }]]>
+  </component>
+</project>
+```
+
+```xml [.idea/OxfmtSettings.xml]
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="OxfmtSettings">
+    <option name="preferOxfmtCodeStyleSettings" value="true" />
+  </component>
+</project>
+```
+
+Often, `.idea` folders are gitignored in a project, even the `externalDependencies.xml` file, which is used to tell your IDE what plugins should be used for the workspace.
+
+Please make sure to add this line to your main `.gitignore` file, to ensure that the file will be included:
+
+```gitignore [.gitignore]
+!.idea/externalDependencies.xml
+```

package/docs/guide/index.md

@@ -4,7 +4,7 @@ Vite+ is the unified toolchain and entry point for web development. It manages y
 
 Vite+ ships in two parts: `vp`, the global command-line tool, and `vite-plus`, the local package installed in each project. If you already have a Vite project, use [`vp migrate`](/guide/migrate) to migrate it to Vite+, or paste our [migration prompt](/guide/migrate#migration-prompt) into your coding agent.
 
-Building with an AI assistant? Copy a ready-made setup prompt:
+Building with an AI assistant? View and copy a ready-made setup prompt:
 
 <CopyPrompt />
 
@@ -92,7 +92,8 @@ Vite+ can handle the entire local frontend development cycle from starting a pro
 
 - [`vp create`](/guide/create) creates new apps, packages, and monorepos.
 - [`vp migrate`](/guide/migrate) moves existing projects onto Vite+.
-- [`vp config`](/guide/commit-hooks) configures commit hooks and agent integration.
+- [`vp config`](/guide/commit-hooks) installs the Git hook dispatcher and configures agent integration.
+- [`vp hooks`](/guide/commit-hooks) manages the Git hook dispatcher (`enable`, `disable`, `status`).
 - [`vp staged`](/guide/commit-hooks) runs checks on staged files.
 - [`vp install`](/guide/install) installs dependencies with the right package manager.
 - [`vp env`](/guide/env) manages Node.js versions.
@@ -126,6 +127,7 @@ Vite+ can handle the entire local frontend development cycle from starting a pro
 
 ### Maintain
 
+- [`vp toolchain`](/guide/upgrade#show-the-toolchain) shows the versions and relationships in the active Vite+ toolchain.
 - [`vp upgrade`](/guide/upgrade) updates the `vp` installation itself.
 - [`vp implode`](/guide/implode) removes `vp` and related Vite+ data from your machine.
 

package/docs/guide/install.md

@@ -39,6 +39,13 @@ A range resolves to an already-downloaded satisfying version when possible, othe
 
 Vite+ currently downloads the declared package manager (the `onFail: "download"` behavior); the other `onFail` values are accepted but not yet differentiated.
 
+A `packageManager` pin can carry an integrity hash (`yarn@4.17.1+sha512.…`). `corepack use` writes that hash. Vite+ hashes the same artifact as Corepack:
+
+- the extracted CLI binary (`bin/yarn.js`) for Yarn 2 and later
+- the npm package tarball for npm, pnpm, and Yarn Classic
+
+Vite+ hashes the CLI once, when it installs Yarn, and records the pin it verified. A later command compares its own pin against that record. A pin that does not match the record fails the check, and the command stops. Corepack keeps the same kind of record for its own cache.
+
 The explicit `packageManager` field (or the `devEngines.packageManager` declaration) also affects matching package-manager shims. If a project has `packageManager: "npm@10.9.4"`, `npm` and `npx` use npm 10.9.4. Other generated alias pairs behave the same way: `pnpm`/`pnpx`, `yarn`/`yarnpkg`, and `bun`/`bunx`. Mismatched tools are not translated; `npm` in a `pnpm` project still resolves as npm.
 
 ## Usage
@@ -69,6 +76,8 @@ Use the `-g` flag for installing, updating or removing globally installed packag
 - `vp list -g [pkg]` lists global packages
 - `vp outdated -g [pkg]` prints outdated packages
 
+Updates keep the version spec a package was installed with: a package installed from a dist-tag (e.g. `vp install -g some-pkg@nightly`) updates to the newest version of that tag, and a version range stays within the range. Reinstall with a different spec (e.g. `vp update -g some-pkg@latest`) to switch, or pass `--latest` to `vp update -g` to move packages to the `latest` tag and clear their recorded specs. `vp outdated -g` reports both the newest version matching the recorded spec (`Wanted`) and the newest version on the `latest` tag.
+
 ::: warning
 These commands do **NOT** interact with the underlying package manager's global installation directory.
 
@@ -147,6 +156,11 @@ Use these when you need to understand the current state of dependencies.
 - `vp why react` explains why `react` is installed
 - `vp info react` shows registry metadata such as versions and dist-tags
 
+These commands show the packages that the package manager installed. They do
+not show tools that Vite+ bundles or compiles. Run `vp toolchain [tool]` to show
+these tools, including Vite, Rolldown, and Oxc. For readable output, `vp why`
+shows a hint when Vite+ also provides the package.
+
 #### Rebuild
 
 Use `vp rebuild` when native modules need to be recompiled, for example after switching Node.js versions or when a C/C++ addon fails to load.
@@ -165,6 +179,19 @@ vp rebuild -- --update-binary
 
 With pnpm v10+, bare `vp rebuild` only rebuilds packages whose build scripts are listed in `onlyBuiltDependencies` (or approved via `pnpm approve-builds`); name the package explicitly to force a rebuild that bypasses the approval gate.
 
+#### Dependency build scripts (npm v12+)
+
+npm v12 skips dependency install scripts (`preinstall` / `install` / `postinstall`, including implicit `node-gyp` builds) unless the `allowScripts` field in package.json covers them; the install succeeds and npm warns about what it skipped. `vp pm approve-builds` manages that allowlist:
+
+- `vp pm approve-builds <pkg...>` approves the named packages (`npm approve-scripts`)
+- `vp pm approve-builds !<pkg...>` denies them (`npm deny-scripts`)
+- `vp pm approve-builds --all` approves everything currently pending
+- `vp pm approve-builds` lists the packages whose scripts are not yet covered
+
+Approval only records the allowlist: scripts an earlier install skipped do not run until you run `vp rebuild <pkg>`. With npm 11.16 - 11.x the same commands work, but npm treats the allowlist as advisory and still runs scripts.
+
+npm v12 also 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.
+
 #### Advanced
 
 Use these when you need lower-level package-manager behavior.

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

@@ -100,6 +100,17 @@ These variables configure the installed Vite+ CLI. `VP_HOME` (above) also applie
 - **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
@@ -147,14 +158,14 @@ Vite+ sets additional `VP_*` variables during shim dispatch and shell integratio
 
 ## Logging and Debugging
 
-### `VITE_LOG`
+### `VP_LOG`
 
 - **Purpose**: Log filter string for `tracing_subscriber`
 - **Default**: None
 - **Example**:
   ```bash
-  VITE_LOG=debug vp dev
-  VITE_LOG=vite_task=trace vp build
+  VP_LOG=debug vp dev
+  VP_LOG=vt=trace vp build
   ```
 
 ### `VP_DEBUG_SHIM`

package/docs/guide/lint.md

@@ -43,8 +43,10 @@ We recommend enabling both `typeAware` and `typeCheck` in the `lint` block:
 - `typeAware: true` enables rules that require TypeScript type information
 - `typeCheck: true` enables full type checking during linting
 
-This path is powered by [tsgolint](https://github.com/oxc-project/tsgolint) on top of the TypeScript Go toolchain. It gives Oxlint access to type information and allows type checking directly via `vp lint` and `vp check`.
+This path is powered by [tsgolint](https://github.com/oxc-project/tsgolint) on top of the TypeScript 7 (aka TypeScript Go) toolchain. It gives Oxlint access to type information and allows type checking directly via `vp lint` and `vp check`.
 
 ## JS Plugins
 
 If you are migrating from ESLint and still depend on a few critical JavaScript-based ESLint plugins, Oxlint has [JS plugin support](https://oxc.rs/docs/guide/usage/linter/js-plugins) that can help you keep those plugins running while you complete the migration.
+
+JS Plugins also enable [writing your own custom rules](https://oxc.rs/docs/guide/usage/linter/writing-js-plugins.html) for Oxlint.

package/docs/guide/migrate.md

@@ -22,6 +22,9 @@ The positional `PATH` argument is optional.
 
 - If omitted, `vp migrate` migrates the current directory
 - If provided, it migrates that target directory instead
+- For a monorepo, the target must be the workspace root. Vite+ cannot
+  migrate one workspace member, because migration updates the package-manager
+  configuration, the catalogs, and the lockfiles that all members share.
 
 ```bash
 vp migrate
@@ -69,6 +72,40 @@ After running the migration:
 - Run `vp test`
 - Run `vp build`
 
+## Manual Installation & Migration
+
+If you are manually migrating a project to Vite+, install these dev dependencies first:
+
+```bash
+vp install -D vite-plus
+```
+
+You need to add overrides to your package manager so that other packages resolve the Vite+ versions: alias `vite` to `@voidzero-dev/vite-plus-core`, and pin `vitest` to the version Vite+ bundles (run `vp --version`) 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):
+
+```json
+"overrides": {
+  "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+  "vitest": "4.1.10"
+}
+```
+
+If you are using `pnpm`, add this to your `pnpm-workspace.yaml`:
+
+```yaml
+overrides:
+  vite: npm:@voidzero-dev/vite-plus-core@latest
+  vitest: 4.1.10
+```
+
+Or, if you are using Yarn:
+
+```json
+"resolutions": {
+  "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+  "vitest": "4.1.10"
+}
+```
+
 ## Migration Prompt
 
 If you want to hand this work to a coding agent (or the reader is a coding agent!), use this migration prompt:
@@ -168,17 +205,25 @@ export default defineConfig({
 });
 ```
 
-After migrating, remove lint-staged from your dependencies and delete any lint-staged config files. See the [Commit hooks guide](/guide/commit-hooks) and [Staged config reference](/config/staged) for details.
+When no existing hook policy owns the workflow, `vp migrate` can move supported lint-staged rules
+and remove the old configuration and dependency. If an existing hook tool is preserved, keep
+lint-staged in place until you convert that hook policy manually. See the
+[Commit hooks guide](/guide/commit-hooks) and [Staged config reference](/config/staged) for details.
 
 ### Git hook tools
 
-The `vp migrate` command can set up Vite+ commit hooks for you, but it doesn't automatically migrate every type of Git hook tool. This automatic migration path is specifically designed to handle Husky v9+ and lint-staged-style setups. Projects using Husky versions older than 9.0.0 are skipped and should upgrade to Husky v9 before using the automatic migration path.
+The `vp migrate` command does not automatically convert Husky setups. When Husky is detected,
+Vite+ leaves its hooks, lifecycle scripts, configuration, and dependencies unchanged and shows a
+warning. You can migrate the project manually using the [Commit hooks guide](/guide/commit-hooks).
+
+Existing project-owned Vite+ hooks are also preserved. The default staged workflow is introduced
+only when no existing hook policy is found.
 
 If your project currently uses `lefthook`, `simple-git-hooks`, or `yorkie`, `vp migrate` will leave your existing configuration alone and show a warning. This happens even if you choose to set up hooks during the prompt or include the `--hooks` flag.
 
-If you want to move one of those tools over to Vite+ manually, you can follow these steps. First, move your staged-file commands into the `staged` block within `vite.config.ts`. Then, update your lifecycle script so it runs `vp config`. You will also need to create a Vite+ hook at `.vite-hooks/pre-commit` that runs `vp staged`. Finally, once you have confirmed that the Vite+ hook is working as expected, you can remove the old tool's configuration and dependency.
+If you want to move one of those tools over to Vite+ manually, you can follow these steps. First, move your staged-file commands into the `staged` block within `vite.config.ts`. Then, update your lifecycle script so it runs `vp config`. You will also need to create a Vite+ hook at `.vite-hooks/pre-commit` that runs `vp staged`. Run `vp hooks enable` (or `vp config`) to install the dispatcher and set `core.hooksPath`. Finally, once you have confirmed that the Vite+ hook is working as expected, you can remove the old tool's configuration and dependency.
 
-You can find more details about the full Vite+ hook setup in the [Commit hooks guide](/guide/commit-hooks).
+Use `vp hooks status` to verify the dispatcher is active, and `vp hooks disable` if you need to turn it off again in this clone. You can find more details about the full Vite+ hook setup in the [Commit hooks guide](/guide/commit-hooks).
 
 ## Examples