docs: document pkg.pr.new preview builds

Author: fengmk2

docs/guide/upgrade.md

@@ -77,3 +77,66 @@ vp --version
 ```
 
 Then set the `vitest` override to that exact version, or rerun `vp migrate` to update the pin for you.
+
+## Preview Builds
+
+Some Vite+ pull requests publish temporary packages through `pkg.pr.new`. Treat these as nightly or bleeding-edge builds: they are useful when you want to verify a specific fix, test a fresh upstream dependency bump, or confirm a change before the next npm release. For day-to-day work, prefer the published `latest` release.
+
+You can find preview builds in pull requests that automatically update upstream dependencies. For examples, search the merged pull requests for [upstream dependency updates](https://github.com/voidzero-dev/vite-plus/pulls?q=is%3Apr+is%3Amerged+upgrade+upstream+dependencies).
+
+Preview builds are addressed by pull request number or commit SHA. They are not a stable version range, and you should avoid leaving them in long-lived branches unless a maintainer asks you to.
+
+### Global `vp` Preview
+
+Install a preview build of the global CLI by passing `VP_PR_VERSION` to the installer:
+
+```bash
+curl -fsSL https://vite.plus | VP_PR_VERSION=<pr-or-sha> bash
+```
+
+On Windows:
+
+```powershell
+$env:VP_PR_VERSION = "<pr-or-sha>"
+irm https://vite.plus/ps1 | iex
+Remove-Item Env:\VP_PR_VERSION
+```
+
+Run `vp --version` afterward to confirm which build and bundled tool versions are active. When you are done testing, return to the published release with `vp upgrade --force` or by running the installer again without `VP_PR_VERSION`.
+
+### Local `vite-plus` Preview
+
+To test an unreleased local package in a project, install the matching preview package:
+
+```bash
+vp add -D https://pkg.pr.new/voidzero-dev/vite-plus@<pr-or-sha>
+vp install
+```
+
+The preview `vite-plus` package points its own Vite+ workspace dependencies at matching `pkg.pr.new` packages. If your project also has a direct `@voidzero-dev/vite-plus-core` dependency or a `vite` override that still points at `npm:@voidzero-dev/vite-plus-core@latest`, update that entry to the matching core preview while you test:
+
+```json
+{
+  "overrides": {
+    "vite": "https://pkg.pr.new/voidzero-dev/vite-plus/@voidzero-dev/vite-plus-core@<pr-or-sha>"
+  }
+}
+```
+
+For pnpm workspaces, make the same temporary change in `pnpm-workspace.yaml` if that is where your Vite+ overrides live:
+
+```yaml
+overrides:
+  vite: "https://pkg.pr.new/voidzero-dev/vite-plus/@voidzero-dev/vite-plus-core@<pr-or-sha>"
+```
+
+After installing a preview, check the bundled versions with `vp --version`. If the preview includes a newer bundled Vitest, update your `vitest` override to that exact version so `vp test` and project imports keep using the same Vitest copy.
+
+When testing is complete, replace the preview package with the published release again:
+
+```bash
+vp add -D vite-plus@latest
+vp install
+```
+
+Then restore any temporary `vite` / `@voidzero-dev/vite-plus-core` override to `npm:@voidzero-dev/vite-plus-core@latest`.