Clarify when to use vp dev vs vp run dev / vpr dev #2243

Problem

Users frequently run vp dev when they actually intend to run the project's dev script. This causes confusion because vp dev is a Vite+ built-in command, while many projects expect script-based behavior.

Current behavior

• Some guidance already points users toward vp run <script> for validation tasks
• Other docs/prompts still describe Vite usage in terms of vp dev / vp build
• This mixed guidance likely contributes to incorrect usage

Expected behavior

Guidance should clearly distinguish:

• vp dev -> Vite+ built-in command
• vp run dev / vpr dev -> project script execution path

When the goal is to respect custom scripts, framework wrappers, or more complex project setups, docs/prompts should prefer the script-based path.

Suggested improvements

1. Update generated prompts / AGENTS.md / docs to prefer vpr where appropriate
2. Clarify when to use:
   • vp dev
   • vp run dev
   • vpr dev
3. Add a runtime hint when a user runs vp dev and a matching dev script exists, e.g.:
   • "You are running vp dev as a Vite+ built-in command. If you meant to run the dev npm script, use vpr dev instead."
4. Apply the same hint pattern to other built-in commands that collide with script names
5. Add evals/tests to catch prompt/doc regressions around this distinction

Why this matters

Using the script path better preserves project-specific behavior, especially for meta-frameworks, custom wrappers, and more complex setups.

Reference

• Related tweet: https://x.com/theo/status/2080874570370924904