From 0ea8a27eb0a62f18971dd43ec16e5df919a3a500 Mon Sep 17 00:00:00 2001
From: wan9chi <dk4rest@gmail.com>
Date: Sun, 26 Jul 2026 19:44:32 +0800
Subject: [PATCH 1/3] docs: clarify `vp dev` vs `vp run dev` / `vpr dev`

Built-in commands cannot be overwritten by `package.json` scripts, but the
docs and generated prompts still described Vite usage only in terms of
`vp dev` and `vp build`. That mixed guidance leads users and agents to run a
built-in command when they meant the project's own script.

- Add a "Built-in Commands vs Scripts" section to the run guide
- Note the built-in behavior on the dev and test pages, matching the build page
- Cover `vp dev` in the troubleshooting entry
- Name the `vpr` shorthand in the migration prompt and the READMEs
- Prefer `vpr <script>` in the generated agent instructions

Refs #2243
---
 README.md                                         |  2 +-
 .../migration_check/snapshots/migration_check.md  |  7 ++++---
 .../snapshots/migration_lintstagedrc_json.md      |  7 ++++---
 docs/guide/build.md                               |  2 +-
 docs/guide/dev.md                                 |  4 ++++
 docs/guide/migrate.md                             |  4 ++--
 docs/guide/run.md                                 | 15 +++++++++++++++
 docs/guide/test.md                                |  4 ++++
 docs/guide/troubleshooting.md                     |  9 ++++++---
 packages/cli/AGENTS.md                            |  6 +++++-
 packages/cli/README.md                            |  2 +-
 packages/cli/src/migration/bin.ts                 |  7 ++++---
 12 files changed, 51 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 75f3cf76c2..cdffabc2aa 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,7 @@ Vite+ is the unified entry point for local web development. It combines [Vite](h
 - **`vp check`:** Run formatting, linting, and type checks in one command
 - **`vp test`:** Run tests through bundled Vitest
 - **`vp build`:** Build applications for production with Vite + Rolldown
-- **`vp run`:** Execute monorepo tasks with caching and dependency-aware scheduling
+- **`vp run` / `vpr`:** Run `package.json` scripts and monorepo tasks with caching and dependency-aware scheduling
 - **`vp pack`:** Build libraries for npm publishing or standalone app binaries
 - **`vp create` / `vp migrate`:** Scaffold new projects and migrate existing ones
 
diff --git a/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_check/snapshots/migration_check.md b/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_check/snapshots/migration_check.md
index 7b1e50b9e1..49130640d1 100644
--- a/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_check/snapshots/migration_check.md
+++ b/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_check/snapshots/migration_check.md
@@ -55,9 +55,10 @@ Migration Prompt:
     `vite.config.ts`
 
   Command mapping:
-  - `vp run <script>` is the equivalent of `pnpm run <script>`
-  - `vp test` runs the built-in test command, while `vp run test` runs the
-    `test` script from `package.json`
+  - `vp run <script>` is the equivalent of `pnpm run <script>`; `vpr` is the
+    shorthand for `vp run`
+  - `vp dev` and `vp test` always run the built-ins; `vpr dev` and `vpr test`
+    run the `dev` and `test` scripts from `package.json`
   - `vp install`, `vp add`, and `vp remove` delegate through the package
     manager declared by `packageManager`
   - `vp dev`, `vp build`, `vp preview`, `vp lint`, `vp fmt`, `vp check`,
diff --git a/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_lintstagedrc_json/snapshots/migration_lintstagedrc_json.md b/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_lintstagedrc_json/snapshots/migration_lintstagedrc_json.md
index 1bebff7210..f48ddb6493 100644
--- a/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_lintstagedrc_json/snapshots/migration_lintstagedrc_json.md
+++ b/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_lintstagedrc_json/snapshots/migration_lintstagedrc_json.md
@@ -55,9 +55,10 @@ Migration Prompt:
     `vite.config.ts`
 
   Command mapping:
-  - `vp run <script>` is the equivalent of `pnpm run <script>`
-  - `vp test` runs the built-in test command, while `vp run test` runs the
-    `test` script from `package.json`
+  - `vp run <script>` is the equivalent of `pnpm run <script>`; `vpr` is the
+    shorthand for `vp run`
+  - `vp dev` and `vp test` always run the built-ins; `vpr dev` and `vpr test`
+    run the `dev` and `test` scripts from `package.json`
   - `vp install`, `vp add`, and `vp remove` delegate through the package
     manager declared by `packageManager`
   - `vp dev`, `vp build`, `vp preview`, `vp lint`, `vp fmt`, `vp check`,
diff --git a/docs/guide/build.md b/docs/guide/build.md
index 93f15d9947..4f4e9c92ee 100644
--- a/docs/guide/build.md
+++ b/docs/guide/build.md
@@ -7,7 +7,7 @@
 `vp build` runs the standard Vite production build through Vite+. Since it is directly based on Vite, the build pipeline and configuration model are the same as Vite. For more information about how Vite production builds work, see the [Vite guide](https://vite.dev/guide/build). Note that Vite+ uses Vite 8 and [Rolldown](https://rolldown.rs/) for builds.
 
 ::: info
-`vp build` always runs the built-in Vite production build. If your project also has a `build` script in `package.json`, run `vp run build` when you want to run that script instead.
+`vp build` always runs the built-in Vite production build. If your project also has a `build` script in `package.json`, run `vp run build` or `vpr build` when you want to run that script instead. See [Built-in Commands vs Scripts](/guide/run#built-in-commands-vs-scripts).
 :::
 
 ## Usage
diff --git a/docs/guide/dev.md b/docs/guide/dev.md
index 947764f992..e1c5a141e6 100644
--- a/docs/guide/dev.md
+++ b/docs/guide/dev.md
@@ -6,6 +6,10 @@
 
 `vp dev` runs the standard Vite development server through Vite+, so you keep the normal Vite dev experience while using the same CLI entry point as the rest of the toolchain. For more information about using and configuring the dev server, see the [Vite guide](https://vite.dev/guide/).
 
+::: info
+`vp dev` always runs the built-in Vite dev server. If your project also has a `dev` script in `package.json`, run `vp run dev` or `vpr dev` when you want to run that script instead. See [Built-in Commands vs Scripts](/guide/run#built-in-commands-vs-scripts).
+:::
+
 ## Usage
 
 ```bash
diff --git a/docs/guide/migrate.md b/docs/guide/migrate.md
index c954fd5de3..349a57afd9 100644
--- a/docs/guide/migrate.md
+++ b/docs/guide/migrate.md
@@ -85,8 +85,8 @@ After the migration:
 
 Command mapping to keep in mind:
 
-- `vp run <script>` is the equivalent of `pnpm run <script>`
-- `vp test` runs the built-in test command, while `vp run test` runs the `test` script from `package.json`
+- `vp run <script>` is the equivalent of `pnpm run <script>`; `vpr` is the shorthand for `vp run`
+- `vp dev` and `vp test` always run the built-ins; `vpr dev` and `vpr test` run the `dev` and `test` scripts from `package.json`
 - `vp install`, `vp add`, and `vp remove` delegate through the package manager declared by `packageManager`
 - `vp dev`, `vp build`, `vp preview`, `vp lint`, `vp fmt`, `vp check`, and `vp pack` replace the corresponding standalone tools
 - Prefer `vp check` for validation loops
diff --git a/docs/guide/run.md b/docs/guide/run.md
index 51ba1e2631..2b8cc01c08 100644
--- a/docs/guide/run.md
+++ b/docs/guide/run.md
@@ -38,6 +38,21 @@ Select a task (↑/↓, Enter to run, Esc to clear):
     test: jest
 ```
 
+## Built-in Commands vs Scripts
+
+`vp dev` is a built-in command. `vp run dev` is your `dev` script. Built-in commands cannot be overwritten, so adding a `dev` script does not change what `vp dev` does:
+
+| Command                    | What it runs                                                              |
+| -------------------------- | ------------------------------------------------------------------------- |
+| `vp dev`                   | The built-in Vite dev server                                              |
+| `vp run dev` / `vpr dev`   | The `dev` script in `package.json`, or a `dev` task in `vite.config.ts`   |
+| `vp test`                  | The built-in Vitest command                                               |
+| `vp run test` / `vpr test` | The `test` script in `package.json`, or a `test` task in `vite.config.ts` |
+
+`build`, `preview`, `lint`, `fmt`, `check`, and `pack` work the same way.
+
+If the project defines that script or task, run it with `vpr <name>`. For example, with a `"dev": "astro dev"` script, `vpr dev` starts Astro, while `vp dev` ignores the script and starts Vite.
+
 ## Caching
 
 `package.json` scripts are not cached by default. Use `--cache` to enable caching:
diff --git a/docs/guide/test.md b/docs/guide/test.md
index f3f3e69324..943c320b0e 100644
--- a/docs/guide/test.md
+++ b/docs/guide/test.md
@@ -6,6 +6,10 @@
 
 `vp test` is built on [Vitest](https://vitest.dev/), so you get a Vite-native test runner that reuses your Vite config and plugins, supports Jest-style expectations, snapshots, and coverage, and handles modern ESM, TypeScript, and JSX projects cleanly.
 
+::: info
+`vp test` always runs the built-in Vitest command. If your project also has a `test` script in `package.json`, run `vp run test` or `vpr test` when you want to run that script instead. See [Built-in Commands vs Scripts](/guide/run#built-in-commands-vs-scripts).
+:::
+
 ## Usage
 
 ```bash
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index 10ac108654..a6d3f5ff9f 100644
--- a/docs/guide/troubleshooting.md
+++ b/docs/guide/troubleshooting.md
@@ -31,15 +31,18 @@ If VS Code has multiple folders open, the shared Oxc language server may pick a
 
 - Confirm the extension is using the intended workspace.
 
-## `vp build` does not run my build script
+## `vp dev` or `vp build` does not run my script
 
-Unlike package managers, built-in commands cannot be overwritten. If you are trying to run a `package.json` script use `vp run build` instead.
+Unlike package managers, built-in commands cannot be overwritten. If you are trying to run a `package.json` script, use `vp run <script>` or its `vpr <script>` shorthand instead.
 
 For example:
 
+- `vp dev` always starts the built-in Vite dev server
 - `vp build` always runs the built-in Vite build
 - `vp test` always runs the built-in Vitest command
-- `vp run build` and `vp run test` run `package.json` scripts instead
+- `vpr dev`, `vpr build`, and `vpr test` run the matching `package.json` scripts instead
+
+See [Built-in Commands vs Scripts](/guide/run#built-in-commands-vs-scripts) for when to prefer each path.
 
 ::: info
 You can also run custom tasks defined in `vite.config.ts` and migrate away from `package.json` scripts entirely.
diff --git a/packages/cli/AGENTS.md b/packages/cli/AGENTS.md
index 362b82a43a..c5038ee17f 100644
--- a/packages/cli/AGENTS.md
+++ b/packages/cli/AGENTS.md
@@ -6,11 +6,15 @@ This project is using Vite+, a unified toolchain built on top of Vite, Rolldown,
 
 Docs are local at `node_modules/vite-plus/docs` or online at https://viteplus.dev/guide/.
 
+## Built-in Commands vs Scripts
+
+`vp <name>` runs a built-in command. `vp run <name>`, or `vpr <name>` for short, runs a `package.json` script or a `vite.config.ts` task. Scripts cannot overwrite built-ins, so `vp dev` and `vpr dev` may do different things. Check `package.json` and `vite.config.ts` first, and run `vpr <name>` when the project defines a script or task with that name.
+
 ## Review Checklist
 
 - [ ] Run `vp install` after pulling remote changes and before getting started.
 - [ ] Run `vp check` and `vp test` to format, lint, type check and test changes.
-- [ ] Check if there are `vite.config.ts` tasks or `package.json` scripts necessary for validation, run via `vp run <script>`.
+- [ ] Check if there are `vite.config.ts` tasks or `package.json` scripts necessary for validation, run via `vpr <script>`.
 - [ ] If setup, runtime, or package-manager behavior looks wrong, run `vp env doctor` and include its output when asking for help.
 
 <!--VITE PLUS END-->
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 51ecf29bf2..76cf3023bf 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -15,7 +15,7 @@ Vite+ is the unified entry point for local web development. It combines [Vite](h
 - **`vp check`:** Run formatting, linting, and type checks in one command
 - **`vp test`:** Run tests through bundled Vitest
 - **`vp build`:** Build applications for production with Vite + Rolldown
-- **`vp run`:** Execute monorepo tasks with caching and dependency-aware scheduling
+- **`vp run` / `vpr`:** Run `package.json` scripts and monorepo tasks with caching and dependency-aware scheduling
 - **`vp pack`:** Build libraries for npm publishing or standalone app binaries
 - **`vp create` / `vp migrate`:** Scaffold new projects and migrate existing ones
 
diff --git a/packages/cli/src/migration/bin.ts b/packages/cli/src/migration/bin.ts
index 4065458314..58660640eb 100644
--- a/packages/cli/src/migration/bin.ts
+++ b/packages/cli/src/migration/bin.ts
@@ -313,9 +313,10 @@ const helpMessage = renderCliDoc({
         '    `vite.config.ts`',
         '',
         '  Command mapping:',
-        '  - `vp run <script>` is the equivalent of `pnpm run <script>`',
-        '  - `vp test` runs the built-in test command, while `vp run test` runs the',
-        '    `test` script from `package.json`',
+        '  - `vp run <script>` is the equivalent of `pnpm run <script>`; `vpr` is the',
+        '    shorthand for `vp run`',
+        '  - `vp dev` and `vp test` always run the built-ins; `vpr dev` and `vpr test`',
+        '    run the `dev` and `test` scripts from `package.json`',
         '  - `vp install`, `vp add`, and `vp remove` delegate through the package',
         '    manager declared by `packageManager`',
         '  - `vp dev`, `vp build`, `vp preview`, `vp lint`, `vp fmt`, `vp check`,',

From a9ce1be3071ff7aeb5cec187148da903d02d5ea9 Mon Sep 17 00:00:00 2001
From: wan9chi <dk4rest@gmail.com>
Date: Mon, 27 Jul 2026 11:06:18 +0800
Subject: [PATCH 2/3] docs: use `vp run` in prose instead of pairing it with
 `vpr`

`vpr` is already introduced in the run guide, the guide index, and `vp help`,
so the prose does not need to spell out both forms, the same way the docs do
not pair `vp install` with `vp i`.
---
 README.md                                          |  2 +-
 .../migration_check/snapshots/migration_check.md   |  7 +++----
 .../snapshots/migration_lintstagedrc_json.md       |  7 +++----
 docs/guide/build.md                                |  2 +-
 docs/guide/dev.md                                  |  2 +-
 docs/guide/migrate.md                              |  4 ++--
 docs/guide/run.md                                  | 14 +++++++-------
 docs/guide/test.md                                 |  2 +-
 docs/guide/troubleshooting.md                      |  4 ++--
 packages/cli/AGENTS.md                             |  4 ++--
 packages/cli/README.md                             |  2 +-
 packages/cli/src/migration/bin.ts                  |  7 +++----
 12 files changed, 27 insertions(+), 30 deletions(-)

diff --git a/README.md b/README.md
index cdffabc2aa..db19882f0a 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,7 @@ Vite+ is the unified entry point for local web development. It combines [Vite](h
 - **`vp check`:** Run formatting, linting, and type checks in one command
 - **`vp test`:** Run tests through bundled Vitest
 - **`vp build`:** Build applications for production with Vite + Rolldown
-- **`vp run` / `vpr`:** Run `package.json` scripts and monorepo tasks with caching and dependency-aware scheduling
+- **`vp run`:** Run `package.json` scripts and monorepo tasks with caching and dependency-aware scheduling
 - **`vp pack`:** Build libraries for npm publishing or standalone app binaries
 - **`vp create` / `vp migrate`:** Scaffold new projects and migrate existing ones
 
diff --git a/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_check/snapshots/migration_check.md b/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_check/snapshots/migration_check.md
index 49130640d1..c1de7ffa38 100644
--- a/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_check/snapshots/migration_check.md
+++ b/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_check/snapshots/migration_check.md
@@ -55,10 +55,9 @@ Migration Prompt:
     `vite.config.ts`
 
   Command mapping:
-  - `vp run <script>` is the equivalent of `pnpm run <script>`; `vpr` is the
-    shorthand for `vp run`
-  - `vp dev` and `vp test` always run the built-ins; `vpr dev` and `vpr test`
-    run the `dev` and `test` scripts from `package.json`
+  - `vp run <script>` is the equivalent of `pnpm run <script>`
+  - `vp dev` and `vp test` always run the built-ins; `vp run dev` and
+    `vp run test` run the `dev` and `test` scripts from `package.json`
   - `vp install`, `vp add`, and `vp remove` delegate through the package
     manager declared by `packageManager`
   - `vp dev`, `vp build`, `vp preview`, `vp lint`, `vp fmt`, `vp check`,
diff --git a/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_lintstagedrc_json/snapshots/migration_lintstagedrc_json.md b/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_lintstagedrc_json/snapshots/migration_lintstagedrc_json.md
index f48ddb6493..500a2461a1 100644
--- a/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_lintstagedrc_json/snapshots/migration_lintstagedrc_json.md
+++ b/crates/vite_cli_snapshots/tests/cli_snapshots/fixtures/migration_lintstagedrc_json/snapshots/migration_lintstagedrc_json.md
@@ -55,10 +55,9 @@ Migration Prompt:
     `vite.config.ts`
 
   Command mapping:
-  - `vp run <script>` is the equivalent of `pnpm run <script>`; `vpr` is the
-    shorthand for `vp run`
-  - `vp dev` and `vp test` always run the built-ins; `vpr dev` and `vpr test`
-    run the `dev` and `test` scripts from `package.json`
+  - `vp run <script>` is the equivalent of `pnpm run <script>`
+  - `vp dev` and `vp test` always run the built-ins; `vp run dev` and
+    `vp run test` run the `dev` and `test` scripts from `package.json`
   - `vp install`, `vp add`, and `vp remove` delegate through the package
     manager declared by `packageManager`
   - `vp dev`, `vp build`, `vp preview`, `vp lint`, `vp fmt`, `vp check`,
diff --git a/docs/guide/build.md b/docs/guide/build.md
index 4f4e9c92ee..deee2b6f12 100644
--- a/docs/guide/build.md
+++ b/docs/guide/build.md
@@ -7,7 +7,7 @@
 `vp build` runs the standard Vite production build through Vite+. Since it is directly based on Vite, the build pipeline and configuration model are the same as Vite. For more information about how Vite production builds work, see the [Vite guide](https://vite.dev/guide/build). Note that Vite+ uses Vite 8 and [Rolldown](https://rolldown.rs/) for builds.
 
 ::: info
-`vp build` always runs the built-in Vite production build. If your project also has a `build` script in `package.json`, run `vp run build` or `vpr build` when you want to run that script instead. See [Built-in Commands vs Scripts](/guide/run#built-in-commands-vs-scripts).
+`vp build` always runs the built-in Vite production build. If your project also has a `build` script in `package.json`, run `vp run build` when you want to run that script instead. See [Built-in Commands vs Scripts](/guide/run#built-in-commands-vs-scripts).
 :::
 
 ## Usage
diff --git a/docs/guide/dev.md b/docs/guide/dev.md
index e1c5a141e6..29aec2869a 100644
--- a/docs/guide/dev.md
+++ b/docs/guide/dev.md
@@ -7,7 +7,7 @@
 `vp dev` runs the standard Vite development server through Vite+, so you keep the normal Vite dev experience while using the same CLI entry point as the rest of the toolchain. For more information about using and configuring the dev server, see the [Vite guide](https://vite.dev/guide/).
 
 ::: info
-`vp dev` always runs the built-in Vite dev server. If your project also has a `dev` script in `package.json`, run `vp run dev` or `vpr dev` when you want to run that script instead. See [Built-in Commands vs Scripts](/guide/run#built-in-commands-vs-scripts).
+`vp dev` always runs the built-in Vite dev server. If your project also has a `dev` script in `package.json`, run `vp run dev` when you want to run that script instead. See [Built-in Commands vs Scripts](/guide/run#built-in-commands-vs-scripts).
 :::
 
 ## Usage
diff --git a/docs/guide/migrate.md b/docs/guide/migrate.md
index 349a57afd9..de4abe3754 100644
--- a/docs/guide/migrate.md
+++ b/docs/guide/migrate.md
@@ -85,8 +85,8 @@ After the migration:
 
 Command mapping to keep in mind:
 
-- `vp run <script>` is the equivalent of `pnpm run <script>`; `vpr` is the shorthand for `vp run`
-- `vp dev` and `vp test` always run the built-ins; `vpr dev` and `vpr test` run the `dev` and `test` scripts from `package.json`
+- `vp run <script>` is the equivalent of `pnpm run <script>`
+- `vp dev` and `vp test` always run the built-ins; `vp run dev` and `vp run test` run the `dev` and `test` scripts from `package.json`
 - `vp install`, `vp add`, and `vp remove` delegate through the package manager declared by `packageManager`
 - `vp dev`, `vp build`, `vp preview`, `vp lint`, `vp fmt`, `vp check`, and `vp pack` replace the corresponding standalone tools
 - Prefer `vp check` for validation loops
diff --git a/docs/guide/run.md b/docs/guide/run.md
index 2b8cc01c08..7a719b0fbd 100644
--- a/docs/guide/run.md
+++ b/docs/guide/run.md
@@ -42,16 +42,16 @@ Select a task (↑/↓, Enter to run, Esc to clear):
 
 `vp dev` is a built-in command. `vp run dev` is your `dev` script. Built-in commands cannot be overwritten, so adding a `dev` script does not change what `vp dev` does:
 
-| Command                    | What it runs                                                              |
-| -------------------------- | ------------------------------------------------------------------------- |
-| `vp dev`                   | The built-in Vite dev server                                              |
-| `vp run dev` / `vpr dev`   | The `dev` script in `package.json`, or a `dev` task in `vite.config.ts`   |
-| `vp test`                  | The built-in Vitest command                                               |
-| `vp run test` / `vpr test` | The `test` script in `package.json`, or a `test` task in `vite.config.ts` |
+| Command       | What it runs                                                              |
+| ------------- | ------------------------------------------------------------------------- |
+| `vp dev`      | The built-in Vite dev server                                              |
+| `vp run dev`  | The `dev` script in `package.json`, or a `dev` task in `vite.config.ts`   |
+| `vp test`     | The built-in Vitest command                                               |
+| `vp run test` | The `test` script in `package.json`, or a `test` task in `vite.config.ts` |
 
 `build`, `preview`, `lint`, `fmt`, `check`, and `pack` work the same way.
 
-If the project defines that script or task, run it with `vpr <name>`. For example, with a `"dev": "astro dev"` script, `vpr dev` starts Astro, while `vp dev` ignores the script and starts Vite.
+If the project defines that script or task, run it with `vp run <name>`. For example, with a `"dev": "astro dev"` script, `vp run dev` starts Astro, while `vp dev` ignores the script and starts Vite.
 
 ## Caching
 
diff --git a/docs/guide/test.md b/docs/guide/test.md
index 943c320b0e..d6524f4cb4 100644
--- a/docs/guide/test.md
+++ b/docs/guide/test.md
@@ -7,7 +7,7 @@
 `vp test` is built on [Vitest](https://vitest.dev/), so you get a Vite-native test runner that reuses your Vite config and plugins, supports Jest-style expectations, snapshots, and coverage, and handles modern ESM, TypeScript, and JSX projects cleanly.
 
 ::: info
-`vp test` always runs the built-in Vitest command. If your project also has a `test` script in `package.json`, run `vp run test` or `vpr test` when you want to run that script instead. See [Built-in Commands vs Scripts](/guide/run#built-in-commands-vs-scripts).
+`vp test` always runs the built-in Vitest command. If your project also has a `test` script in `package.json`, run `vp run test` when you want to run that script instead. See [Built-in Commands vs Scripts](/guide/run#built-in-commands-vs-scripts).
 :::
 
 ## Usage
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index a6d3f5ff9f..c2d90350bf 100644
--- a/docs/guide/troubleshooting.md
+++ b/docs/guide/troubleshooting.md
@@ -33,14 +33,14 @@ If VS Code has multiple folders open, the shared Oxc language server may pick a
 
 ## `vp dev` or `vp build` does not run my script
 
-Unlike package managers, built-in commands cannot be overwritten. If you are trying to run a `package.json` script, use `vp run <script>` or its `vpr <script>` shorthand instead.
+Unlike package managers, built-in commands cannot be overwritten. If you are trying to run a `package.json` script use `vp run <script>` instead.
 
 For example:
 
 - `vp dev` always starts the built-in Vite dev server
 - `vp build` always runs the built-in Vite build
 - `vp test` always runs the built-in Vitest command
-- `vpr dev`, `vpr build`, and `vpr test` run the matching `package.json` scripts instead
+- `vp run dev`, `vp run build`, and `vp run test` run the matching `package.json` scripts instead
 
 See [Built-in Commands vs Scripts](/guide/run#built-in-commands-vs-scripts) for when to prefer each path.
 
diff --git a/packages/cli/AGENTS.md b/packages/cli/AGENTS.md
index c5038ee17f..693c7933c9 100644
--- a/packages/cli/AGENTS.md
+++ b/packages/cli/AGENTS.md
@@ -8,13 +8,13 @@ Docs are local at `node_modules/vite-plus/docs` or online at https://viteplus.de
 
 ## Built-in Commands vs Scripts
 
-`vp <name>` runs a built-in command. `vp run <name>`, or `vpr <name>` for short, runs a `package.json` script or a `vite.config.ts` task. Scripts cannot overwrite built-ins, so `vp dev` and `vpr dev` may do different things. Check `package.json` and `vite.config.ts` first, and run `vpr <name>` when the project defines a script or task with that name.
+`vp <name>` runs a built-in command. `vp run <name>` runs a `package.json` script or a `vite.config.ts` task. Scripts cannot overwrite built-ins, so `vp dev` and `vp run dev` may do different things. Check `package.json` and `vite.config.ts` first, and run `vp run <name>` when the project defines a script or task with that name.
 
 ## Review Checklist
 
 - [ ] Run `vp install` after pulling remote changes and before getting started.
 - [ ] Run `vp check` and `vp test` to format, lint, type check and test changes.
-- [ ] Check if there are `vite.config.ts` tasks or `package.json` scripts necessary for validation, run via `vpr <script>`.
+- [ ] Check if there are `vite.config.ts` tasks or `package.json` scripts necessary for validation, run via `vp run <script>`.
 - [ ] If setup, runtime, or package-manager behavior looks wrong, run `vp env doctor` and include its output when asking for help.
 
 <!--VITE PLUS END-->
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 76cf3023bf..56f6bd17f4 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -15,7 +15,7 @@ Vite+ is the unified entry point for local web development. It combines [Vite](h
 - **`vp check`:** Run formatting, linting, and type checks in one command
 - **`vp test`:** Run tests through bundled Vitest
 - **`vp build`:** Build applications for production with Vite + Rolldown
-- **`vp run` / `vpr`:** Run `package.json` scripts and monorepo tasks with caching and dependency-aware scheduling
+- **`vp run`:** Run `package.json` scripts and monorepo tasks with caching and dependency-aware scheduling
 - **`vp pack`:** Build libraries for npm publishing or standalone app binaries
 - **`vp create` / `vp migrate`:** Scaffold new projects and migrate existing ones
 
diff --git a/packages/cli/src/migration/bin.ts b/packages/cli/src/migration/bin.ts
index 58660640eb..78c6d27ca7 100644
--- a/packages/cli/src/migration/bin.ts
+++ b/packages/cli/src/migration/bin.ts
@@ -313,10 +313,9 @@ const helpMessage = renderCliDoc({
         '    `vite.config.ts`',
         '',
         '  Command mapping:',
-        '  - `vp run <script>` is the equivalent of `pnpm run <script>`; `vpr` is the',
-        '    shorthand for `vp run`',
-        '  - `vp dev` and `vp test` always run the built-ins; `vpr dev` and `vpr test`',
-        '    run the `dev` and `test` scripts from `package.json`',
+        '  - `vp run <script>` is the equivalent of `pnpm run <script>`',
+        '  - `vp dev` and `vp test` always run the built-ins; `vp run dev` and',
+        '    `vp run test` run the `dev` and `test` scripts from `package.json`',
         '  - `vp install`, `vp add`, and `vp remove` delegate through the package',
         '    manager declared by `packageManager`',
         '  - `vp dev`, `vp build`, `vp preview`, `vp lint`, `vp fmt`, `vp check`,',

From edbe440fbb8cc64f81de649199e904eb6a27394c Mon Sep 17 00:00:00 2001
From: wan9chi <dk4rest@gmail.com>
Date: Mon, 27 Jul 2026 17:39:43 +0800
Subject: [PATCH 3/3] docs: list `vpr` alongside `vp run` in the command table

---
 docs/guide/run.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/guide/run.md b/docs/guide/run.md
index 7a719b0fbd..5752752078 100644
--- a/docs/guide/run.md
+++ b/docs/guide/run.md
@@ -42,12 +42,12 @@ Select a task (↑/↓, Enter to run, Esc to clear):
 
 `vp dev` is a built-in command. `vp run dev` is your `dev` script. Built-in commands cannot be overwritten, so adding a `dev` script does not change what `vp dev` does:
 
-| Command       | What it runs                                                              |
-| ------------- | ------------------------------------------------------------------------- |
-| `vp dev`      | The built-in Vite dev server                                              |
-| `vp run dev`  | The `dev` script in `package.json`, or a `dev` task in `vite.config.ts`   |
-| `vp test`     | The built-in Vitest command                                               |
-| `vp run test` | The `test` script in `package.json`, or a `test` task in `vite.config.ts` |
+| Command                    | What it runs                                                              |
+| -------------------------- | ------------------------------------------------------------------------- |
+| `vp dev`                   | The built-in Vite dev server                                              |
+| `vp run dev` / `vpr dev`   | The `dev` script in `package.json`, or a `dev` task in `vite.config.ts`   |
+| `vp test`                  | The built-in Vitest command                                               |
+| `vp run test` / `vpr test` | The `test` script in `package.json`, or a `test` task in `vite.config.ts` |
 
 `build`, `preview`, `lint`, `fmt`, `check`, and `pack` work the same way.