From 19a7af512249a135b9b9f8d479399ca7911dc976 Mon Sep 17 00:00:00 2001
From: wuyangfan <1102042793@qq.com>
Date: Sat, 16 May 2026 23:31:14 +0800
Subject: [PATCH 1/2] docs: add coding agent guide

---
 docs/.vitepress/config.mts  |   1 +
 docs/guide/coding-agents.md | 118 ++++++++++++++++++++++++++++++++++++
 docs/guide/create.md        |   2 +
 docs/guide/index.md         |   2 +
 docs/guide/migrate.md       |   2 +-
 5 files changed, 124 insertions(+), 1 deletion(-)
 create mode 100644 docs/guide/coding-agents.md

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 50a7573fd3..d059058e3f 100644
--- a/docs/.vitepress/config.mts
+++ b/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' },
     ],
   },
diff --git a/docs/guide/coding-agents.md b/docs/guide/coding-agents.md
new file mode 100644
index 0000000000..5281cb047e
--- /dev/null
+++ b/docs/guide/coding-agents.md
@@ -0,0 +1,118 @@
+# 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
+
+# Inspect templates when an organization manifest is available
+vp create @your-org --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
+```
+
+## 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)
diff --git a/docs/guide/create.md b/docs/guide/create.md
index 73287a15ef..1830f83097 100644
--- a/docs/guide/create.md
+++ b/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
diff --git a/docs/guide/index.md b/docs/guide/index.md
index 5f50a38883..07f4585912 100644
--- a/docs/guide/index.md
+++ b/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
diff --git a/docs/guide/migrate.md b/docs/guide/migrate.md
index d84b010cce..88dee4f388 100644
--- a/docs/guide/migrate.md
+++ b/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.

From 2de6e2744b79e62f377a13215bee20f2d546e706 Mon Sep 17 00:00:00 2001
From: wuyangfan <1102042793@qq.com>
Date: Sun, 17 May 2026 00:06:36 +0800
Subject: [PATCH 2/2] docs: fix org template automation example

---
 docs/guide/coding-agents.md | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/docs/guide/coding-agents.md b/docs/guide/coding-agents.md
index 5281cb047e..d73f47bf9b 100644
--- a/docs/guide/coding-agents.md
+++ b/docs/guide/coding-agents.md
@@ -42,8 +42,11 @@ vp create vite -- --template react-ts
 # Create from a built-in Vite+ template without prompts
 vp create vite:application --directory apps/web --no-interactive
 
-# Inspect templates when an organization manifest is available
-vp create @your-org --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:
@@ -54,6 +57,12 @@ 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