diff --git a/docs/guide/upgrade.md b/docs/guide/upgrade.md
index d066158f0a..9b5c48e328 100644
--- a/docs/guide/upgrade.md
+++ b/docs/guide/upgrade.md
@@ -26,3 +26,24 @@ vp update vite-plus
 ```
 
 You can also use `vp add vite-plus@latest` if you want to move the dependency explicitly to the latest version.
+
+### Updating Aliased Packages
+
+Vite+ sets up npm aliases for its core packages during installation:
+
+- `vite` is aliased to `npm:@voidzero-dev/vite-plus-core@latest`
+- `vitest` is aliased to `npm:@voidzero-dev/vite-plus-test@latest`
+
+`vp update vite-plus` does not re-resolve these aliases in the lockfile. To fully upgrade, update them separately:
+
+```bash
+vp update @voidzero-dev/vite-plus-core @voidzero-dev/vite-plus-test
+```
+
+Or update everything at once:
+
+```bash
+vp update vite-plus @voidzero-dev/vite-plus-core @voidzero-dev/vite-plus-test
+```
+
+You can verify with `vp outdated` that no Vite+ packages remain outdated.