From eb279a1895ed9cb8564f0f5eb8839958dd2acc0c Mon Sep 17 00:00:00 2001
From: Tarte12 <101166683+Tarte12@users.noreply.github.com>
Date: Wed, 21 Oct 2026 15:02:03 +0900
Subject: [PATCH 1/3] docs: document env prefixes in task commands

---
 docs/config/run.md |  2 +-
 docs/guide/run.md  | 16 ++++++++++++++++
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/docs/config/run.md b/docs/config/run.md
index 73b03cceb1..55c63e7e5e 100644
--- a/docs/config/run.md
+++ b/docs/config/run.md
@@ -90,7 +90,7 @@ Use the object form when a task needs other fields like `cache`, `dependsOn`, or
 
 - **Type:** `string | string[]`
 
-Defines the shell command to run for the task. The string is interpreted by a shell, so spaces, quoting, `&&`, pipes, and redirects all work as written on the command line.
+Defines the command to run for the task. Quoting, `&&`, pipes, and redirects all work as written on the command line. Vite Task runs simple commands and `&&` chains directly, and falls back to the system shell for other shell syntax. See [Environment Variable Prefixes](/guide/run#environment-variable-prefixes) for details.
 
 ```ts [vite.config.ts]
 tasks: {
diff --git a/docs/guide/run.md b/docs/guide/run.md
index b6458da81e..e4011bb6be 100644
--- a/docs/guide/run.md
+++ b/docs/guide/run.md
@@ -266,6 +266,22 @@ $ vp build ○ cache miss: 'index.html' modified, executing
 vp run: 1/2 cache hit (50%), 2/2 successful, 120ms saved.
 ```
 
+### Environment Variable Prefixes
+
+Vite Task parses simple commands and `&&` chains itself, including environment variable prefixes such as `FOO=bar command`. These work on every platform, including Windows, without `cross-env`:
+
+```json [package.json]
+{
+  "scripts": {
+    "build": "NODE_ENV=production vp build"
+  }
+}
+```
+
+A prefix applies only to the command it precedes. In `FOO=1 a && b`, `FOO` is set for `a` but not for `b`.
+
+If any part of a command uses other shell syntax, such as pipes, redirects, or variable expansion, the whole command runs in the system shell instead: `/bin/sh -c` on macOS and Linux, and `cmd.exe /d /s /c` on Windows. In that case, `FOO=bar command` does not work on Windows, so use `cross-env` there.
+
 ### Nested `vp run`
 
 When a command contains `vp run`, Vite Task inlines it as separate tasks instead of spawning a nested process. Each sub-task is cached independently and output stays flat:

From c0c3a1e8dd3352910802b8ccd0c6513fd7184c33 Mon Sep 17 00:00:00 2001
From: Tarte12 <101166683+Tarte12@users.noreply.github.com>
Date: Sun, 25 Oct 2026 12:24:01 +0900
Subject: [PATCH 2/3] docs: narrow env prefix docs to user-facing behavior

- Move the note that Vite Task parses simple commands to the top of the run guide
- Use a non-`vp` command in the env prefix example
- Replace shell fallback internals with a short warning that points to `cross-env`
- Reword the `command` reference and the `&&` sub-task notes to match
---
 docs/config/run.md |  4 ++--
 docs/guide/run.md  | 16 +++++++++++-----
 2 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/docs/config/run.md b/docs/config/run.md
index 55c63e7e5e..930795fe15 100644
--- a/docs/config/run.md
+++ b/docs/config/run.md
@@ -90,7 +90,7 @@ Use the object form when a task needs other fields like `cache`, `dependsOn`, or
 
 - **Type:** `string | string[]`
 
-Defines the command to run for the task. Quoting, `&&`, pipes, and redirects all work as written on the command line. Vite Task runs simple commands and `&&` chains directly, and falls back to the system shell for other shell syntax. See [Environment Variable Prefixes](/guide/run#environment-variable-prefixes) for details.
+Defines the command to run for the task. Vite Task parses simple commands and `&&` chains itself, so they behave the same on every platform. Other shell syntax, such as pipes and redirects, may behave differently across platforms. See [Environment Variable Prefixes](/guide/run#environment-variable-prefixes) for details.
 
 ```ts [vite.config.ts]
 tasks: {
@@ -117,7 +117,7 @@ tasks: {
 
 Each task defined in `vite.config.ts` must include its own `command`. You cannot define a task in both `vite.config.ts` and `package.json` with the same task name.
 
-Commands joined with `&&` (or supplied as an array) are automatically split into independently cached sub-tasks. See [Compound Commands](/guide/run#compound-commands).
+Array entries, and `&&` chains without other shell syntax, are automatically split into independently cached sub-tasks. See [Compound Commands](/guide/run#compound-commands).
 
 ### `dependsOn`
 
diff --git a/docs/guide/run.md b/docs/guide/run.md
index e4011bb6be..e3a282b3ee 100644
--- a/docs/guide/run.md
+++ b/docs/guide/run.md
@@ -6,6 +6,10 @@
 `vpr` is available as a standalone shorthand for `vp run`. All examples below work with both `vp run` and `vpr`.
 :::
 
+::: info
+Vite Task parses simple commands and [`&&` chains](#compound-commands) itself instead of passing them to a shell, so they behave the same on every platform. Commands that use other shell syntax, such as pipes or redirects, may behave differently across platforms.
+:::
+
 ## Overview
 
 Use `vp run` with existing `package.json` scripts:
@@ -232,7 +236,7 @@ vp run -w build
 
 ## Compound Commands
 
-Commands joined with `&&` are split into independent sub-tasks. Each sub-task is cached separately when [caching is enabled](/guide/cache#when-is-caching-enabled). This works for both `vite.config.ts` tasks and `package.json` scripts:
+Commands joined with `&&` are split into independent sub-tasks, unless they also use other shell syntax. Each sub-task is cached separately when [caching is enabled](/guide/cache#when-is-caching-enabled). This works for both `vite.config.ts` tasks and `package.json` scripts:
 
 ```json [package.json]
 {
@@ -268,19 +272,21 @@ vp run: 1/2 cache hit (50%), 2/2 successful, 120ms saved.
 
 ### Environment Variable Prefixes
 
-Vite Task parses simple commands and `&&` chains itself, including environment variable prefixes such as `FOO=bar command`. These work on every platform, including Windows, without `cross-env`:
+Because Vite Task parses simple commands itself, environment variable prefixes such as `FOO=bar command` work on every platform, including Windows, without `cross-env`:
 
 ```json [package.json]
 {
   "scripts": {
-    "build": "NODE_ENV=production vp build"
+    "build": "NODE_ENV=production node build.js"
   }
 }
 ```
 
-A prefix applies only to the command it precedes. In `FOO=1 a && b`, `FOO` is set for `a` but not for `b`.
+A prefix applies only to the command it directly precedes. In `FOO=1 a && b`, `FOO` is set for `a` but not for `b`.
 
-If any part of a command uses other shell syntax, such as pipes, redirects, or variable expansion, the whole command runs in the system shell instead: `/bin/sh -c` on macOS and Linux, and `cmd.exe /d /s /c` on Windows. In that case, `FOO=bar command` does not work on Windows, so use `cross-env` there.
+::: warning
+If a command also uses other shell syntax, such as pipes or redirects, environment variable prefixes may not work on Windows. Verify such commands at runtime, and use `cross-env` if needed.
+:::
 
 ### Nested `vp run`
 

From fa35ba34f3254610f031e6097e7ab1f25fe48232 Mon Sep 17 00:00:00 2001
From: Tarte12 <101166683+Tarte12@users.noreply.github.com>
Date: Sun, 25 Oct 2026 13:15:40 +0900
Subject: [PATCH 3/3] docs: share Vite Task info block and generalize env
 prefix section

---
 docs/config/run.md | 6 +++++-
 docs/guide/run.md  | 6 +++---
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/docs/config/run.md b/docs/config/run.md
index 930795fe15..284e1ae4b0 100644
--- a/docs/config/run.md
+++ b/docs/config/run.md
@@ -90,7 +90,11 @@ Use the object form when a task needs other fields like `cache`, `dependsOn`, or
 
 - **Type:** `string | string[]`
 
-Defines the command to run for the task. Vite Task parses simple commands and `&&` chains itself, so they behave the same on every platform. Other shell syntax, such as pipes and redirects, may behave differently across platforms. See [Environment Variable Prefixes](/guide/run#environment-variable-prefixes) for details.
+Defines the command to run for the task.
+
+::: info
+Vite Task parses simple commands and `&&` chains itself instead of passing them to a shell, so they behave the same on every platform. Other shell syntax, such as pipes or redirects, may behave differently across platforms.
+:::
 
 ```ts [vite.config.ts]
 tasks: {
diff --git a/docs/guide/run.md b/docs/guide/run.md
index e3a282b3ee..a39055dd1c 100644
--- a/docs/guide/run.md
+++ b/docs/guide/run.md
@@ -7,7 +7,7 @@
 :::
 
 ::: info
-Vite Task parses simple commands and [`&&` chains](#compound-commands) itself instead of passing them to a shell, so they behave the same on every platform. Commands that use other shell syntax, such as pipes or redirects, may behave differently across platforms.
+Vite Task parses simple commands and `&&` chains itself instead of passing them to a shell, so they behave the same on every platform. Other shell syntax, such as pipes or redirects, may behave differently across platforms.
 :::
 
 ## Overview
@@ -272,7 +272,7 @@ vp run: 1/2 cache hit (50%), 2/2 successful, 120ms saved.
 
 ### Environment Variable Prefixes
 
-Because Vite Task parses simple commands itself, environment variable prefixes such as `FOO=bar command` work on every platform, including Windows, without `cross-env`:
+Environment variable prefixes such as `FOO=bar command` work on every platform, without extra tools like `cross-env`:
 
 ```json [package.json]
 {
@@ -285,7 +285,7 @@ Because Vite Task parses simple commands itself, environment variable prefixes s
 A prefix applies only to the command it directly precedes. In `FOO=1 a && b`, `FOO` is set for `a` but not for `b`.
 
 ::: warning
-If a command also uses other shell syntax, such as pipes or redirects, environment variable prefixes may not work on Windows. Verify such commands at runtime, and use `cross-env` if needed.
+Prefixes may not work on every platform when the command also uses other shell syntax.
 :::
 
 ### Nested `vp run`