voidzero-dev · wan9chi · Jul 27, 2026 · Jul 26, 2026 · Jul 27, 2026 · Jul 27, 2026
diff --git 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`:** 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/...shots/tests/cli_snapshots/fixtures/migration_check/snapshots/migration_check.md b/...shots/tests/cli_snapshots/fixtures/migration_check/snapshots/migration_check.md
@@ -56,8 +56,8 @@ Migration Prompt:
 
   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 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/...s/fixtures/migration_lintstagedrc_json/snapshots/migration_lintstagedrc_json.md b/...s/fixtures/migration_lintstagedrc_json/snapshots/migration_lintstagedrc_json.md
@@ -56,8 +56,8 @@ Migration Prompt:
 
   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 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
@@ -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` 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
@@ -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` 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
@@ -86,7 +86,7 @@ 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 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
@@ -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 `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
 
 `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
@@ -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` 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
@@ -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>` 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
+- `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.
 
 ::: 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
@@ -6,6 +6,10 @@ 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>` 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.

diff --git 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`:** 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
@@ -314,8 +314,8 @@ const helpMessage = renderCliDoc({
         '',
         '  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 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`,',