diff --git a/README.md b/README.md
index 75f3cf76c2..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`:** 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/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..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
@@ -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/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..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
@@ -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
index 93f15d9947..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` 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
index 947764f992..29aec2869a 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` 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..de4abe3754 100644
--- 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
index 51ba1e2631..5752752078 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 `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
index f3f3e69324..d6524f4cb4 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` 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..c2d90350bf 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>` 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
index 362b82a43a..693c7933c9 100644
--- 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
index 51ecf29bf2..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`:** 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
index 4065458314..78c6d27ca7 100644
--- 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`,',