docs: add coding agent guide

docs/.vitepress/config.mts

@@ -73,6 +73,7 @@ const guideSidebar = [
       { text: 'CI', link: '/guide/ci' },
       { text: 'Commit Hooks', link: '/guide/commit-hooks' },
       { text: 'Monorepo Guide', link: '/guide/monorepo' },
+      { text: 'Coding Agents', link: '/guide/coding-agents' },
       { text: 'Troubleshooting', link: '/guide/troubleshooting' },
     ],
   },

docs/guide/coding-agents.md

@@ -0,0 +1,127 @@
+# Coding Agents
+
+This page is a compact command guide for AI coding agents and humans directing them. Read this before automating Vite+ workflows so arguments are sent to the right command and validation uses the Vite+ command surface.
+
+## Quick Rules
+
+- Run `vp help` and `vp help <command>` before guessing command syntax.
+- Prefer non-interactive flags in automated runs, such as `--no-interactive`, when a command supports them.
+- Keep Vite+ command options before `--`; put template or underlying-tool options after `--` only where the command documents forwarding.
+- Prefer `vp check` for local validation loops because it runs the configured format, lint, and type-check workflow together.
+- Use `vp run <script-or-task>` for project scripts. Do not call package-manager scripts directly unless you specifically need package-manager behavior.
+
+## Forwarding Arguments
+
+`--` separates Vite+ options from options that should be forwarded to another tool. The most common case is `vp create <template> -- <template-options>`.
+
+For example, the Vite template selector belongs to `create-vite`, not to `vp create` itself:
+
+```bash
+vp create vite -- --template react-ts
+```
+
+Vite+ options still go before the separator:
+
+```bash
+vp create vite --directory apps/web --no-interactive -- --template react-ts
+```
+
+If a command page does not document `--` forwarding, do not assume it exists. Check `vp help <command>` or the relevant guide page first.
+
+## Creating Projects
+
+Use [`vp create`](/guide/create) for scaffolding. Agents should choose an explicit template when they already know the target stack.
+
+```bash
+# Interactive project creation
+vp create
+
+# Create a Vite app and forward the Vite template option
+vp create vite -- --template react-ts
+
+# Create from a built-in Vite+ template without prompts
+vp create vite:application --directory apps/web --no-interactive
+
+# List built-in and common shorthand templates
+vp create --list
+
+# Use a specific entry from a known organization manifest
+vp create @your-org:web --no-interactive
+```
+
+Common mistakes:
+
+```bash
+# Wrong: --template is parsed as a vp create option instead of a template option
+vp create vite --template react-ts
+
+# Right: forward --template to create-vite
+vp create vite -- --template react-ts
+
+# Wrong: @org without an entry is an interactive picker and exits non-zero in --no-interactive mode
+vp create @your-org --no-interactive
+
+# Right: pass a concrete manifest entry when automating org templates
+vp create @your-org:web --no-interactive
+```
+
+## Migrating Projects
+
+Use [`vp migrate`](/guide/migrate) to move an existing project onto Vite+. For agent-driven migrations, combine the migration guide's prompt with non-interactive execution when appropriate.
+
+```bash
+# Migrate the current project
+vp migrate
+
+# Migrate without prompts
+vp migrate --no-interactive
+
+# Migrate another directory and write agent/editor setup
+vp migrate my-app --agent claude --editor vscode
+```
+
+After migration, run the normal Vite+ validation loop:
+
+```bash
+vp install
+vp check
+vp test
+vp build
+```
+
+## Running Tasks
+
+Use [`vp run`](/guide/run) for package scripts and Vite+ task definitions.
+
+```bash
+# Run a script or task in the current package
+vp run build
+
+# Run a task for a specific workspace package
+vp run @my/app#build
+
+# Run recursively across workspace packages
+vp run -r build
+
+# Enable task caching for package.json scripts
+vp run --cache build
+```
+
+Remember that `vp test` is the built-in Vite+ test command, while `vp run test` runs the `test` script from `package.json`.
+
+## Validation Checklist
+
+Before handing work back:
+
+1. Run the command-specific help for anything unfamiliar: `vp help <command>`.
+2. Use Vite+ validation commands where possible: `vp check`, `vp test`, and `vp build`.
+3. When creating or migrating projects, confirm whether any flags after `--` are intended for the template or underlying tool.
+4. Summarize which Vite+ commands were run and whether any manual follow-up remains.
+
+## Related Guides
+
+- [Creating a Project](/guide/create)
+- [Migrate to Vite+](/guide/migrate)
+- [Run](/guide/run)
+- [Check](/guide/check)
+- [Commit Hooks and Agent Integration](/guide/commit-hooks)

docs/guide/create.md

@@ -63,6 +63,8 @@ This matters when the template itself accepts flags. For example, you can forwar
 vp create vite -- --template react-ts
 ```
 
+When automating scaffolding, see the [Coding Agents guide](/guide/coding-agents) for argument-forwarding conventions and common mistakes.
+
 ## Examples
 
 ```bash

docs/guide/index.md

@@ -4,6 +4,8 @@ Vite+ is the unified toolchain and entry point for web development. It manages y
 
 Vite+ ships in two parts: `vp`, the global command-line tool, and `vite-plus`, the local package installed in each project. If you already have a Vite project, use [`vp migrate`](/guide/migrate) to migrate it to Vite+, or paste our [migration prompt](/guide/migrate#migration-prompt) into your coding agent.
 
+If Vite+ is being used by a coding agent, point it at the [Coding Agents guide](/guide/coding-agents) for command conventions, argument forwarding, and validation loops.
+
 ## Install `vp`
 
 ### macOS / Linux

docs/guide/migrate.md

@@ -67,7 +67,7 @@ After running the migration:
 
 ## Migration Prompt
 
-If you want to hand this work to a coding agent (or the reader is a coding agent!), use this migration prompt:
+If you want to hand this work to a coding agent (or the reader is a coding agent!), use this migration prompt. For a compact command reference covering argument forwarding and validation loops, see the [Coding Agents guide](/guide/coding-agents).
 
 ```md
 Migrate this project to Vite+. Vite+ replaces the current split tooling around runtime management, package management, dev/build/test commands, linting, formatting, and packaging. Run `vp help` to understand Vite+ capabilities and `vp help migrate` before making changes. Use `vp migrate --no-interactive` in the workspace root. Make sure the project is using Vite 8+ and Vitest 4.1+ before migrating.