From 4eacb3db023abbeec25238ca05ea4ffadb7d11d8 Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Thu, 13 Nov 2025 17:23:42 +0800
Subject: [PATCH 01/17] doc: draft

---
 docs/1 - Getting Started.md    |  0
 docs/2 - Task Orchestration.md |  0
 docs/main_points.md            |  1 +
 docs/tui_design.md             | 22 ++++++++++++++++++++++
 4 files changed, 23 insertions(+)
 create mode 100644 docs/1 - Getting Started.md
 create mode 100644 docs/2 - Task Orchestration.md
 create mode 100644 docs/main_points.md
 create mode 100644 docs/tui_design.md

diff --git a/docs/1 - Getting Started.md b/docs/1 - Getting Started.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/2 - Task Orchestration.md b/docs/2 - Task Orchestration.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/main_points.md b/docs/main_points.md
new file mode 100644
index 00000000..32eebd35
--- /dev/null
+++ b/docs/main_points.md
@@ -0,0 +1 @@
+- Distributed
diff --git a/docs/tui_design.md b/docs/tui_design.md
new file mode 100644
index 00000000..0e00de10
--- /dev/null
+++ b/docs/tui_design.md
@@ -0,0 +1,22 @@
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <ul>
+          <li>Apple
+            <ul>
+              <li>Black tea</li>
+              <li>Green tea</li>
+            </ul>
+          </li>
+          <li>Banana</li>
+          <li>Orange</li>
+        </ul>
+      </td>
+      <td>
+        <b>Fruits</b>
+      </td>
+    </tr>
+
+</tbody>
+</table>

From 72ed61137350676afa7faba9b7d020c255067ef5 Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Thu, 13 Nov 2025 17:44:02 +0800
Subject: [PATCH 02/17] update

---
 docs/tui_design.md | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/docs/tui_design.md b/docs/tui_design.md
index 0e00de10..07a3e815 100644
--- a/docs/tui_design.md
+++ b/docs/tui_design.md
@@ -1,20 +1,25 @@
+# Vite task TUI Design
+
 <table>
   <tbody>
     <tr>
       <td>
         <ul>
-          <li>Apple
+          <li><code>vite run ready</code>
             <ul>
-              <li>Black tea</li>
-              <li>Green tea</li>
+              <li><code>pkg1#build</code>
+              <ul>
+              <li><code>pkg1#build</code></li>
+              <ul>
+              </li>
+              <li><code>pkg2#build</code></li>
+              <li><code>pkg3#build</code></li>
             </ul>
           </li>
-          <li>Banana</li>
-          <li>Orange</li>
         </ul>
       </td>
       <td>
-        <b>Fruits</b>
+        <div style="height: 100%">terminal</dib>
       </td>
     </tr>
 

From 5f033f802b9c69b84edd1f4e947e13839c00b56e Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Thu, 13 Nov 2025 18:05:51 +0800
Subject: [PATCH 03/17] update

---
 docs/tui_design.md | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/docs/tui_design.md b/docs/tui_design.md
index 07a3e815..20cd04c2 100644
--- a/docs/tui_design.md
+++ b/docs/tui_design.md
@@ -1,5 +1,13 @@
 # Vite task TUI Design
 
+```json
+{
+  "script": {
+    "ready": "tsc --noEmit && vite lint && vite run -r build"
+  }
+}
+```
+
 <table>
   <tbody>
     <tr>
@@ -7,19 +15,18 @@
         <ul>
           <li><code>vite run ready</code>
             <ul>
-              <li><code>pkg1#build</code>
+              <li><code>tsc --noEmit</code></li>
+              <li><code>vite lint</code></li>
+              <li><code>vite run -r build</code>
               <ul>
               <li><code>pkg1#build</code></li>
-              <ul>
-              </li>
               <li><code>pkg2#build</code></li>
               <li><code>pkg3#build</code></li>
-            </ul>
           </li>
         </ul>
       </td>
       <td>
-        <div style="height: 100%">terminal</dib>
+        <pre style="height: 100%">terminal</pre>
       </td>
     </tr>
 

From 2972a3ff4084572c8ccce7761845d39d19f889a3 Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Thu, 13 Nov 2025 18:17:16 +0800
Subject: [PATCH 04/17] update

---
 docs/tui_design.md | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/docs/tui_design.md b/docs/tui_design.md
index 20cd04c2..fc838918 100644
--- a/docs/tui_design.md
+++ b/docs/tui_design.md
@@ -10,7 +10,7 @@
 
 <table>
   <tbody>
-    <tr>
+    <tr style="vertical-align: top">
       <td>
         <ul>
           <li><code>vite run ready</code>
@@ -26,7 +26,19 @@
         </ul>
       </td>
       <td>
-        <pre style="height: 100%">terminal</pre>
+      <pre>
+$ vite build <br />
+VITE+ v1.0.0 building for production
+transforming...
+✓ 32 modules transformed...
+rendering chunks...
+computing gzip size...
+dist/index.html  0.46 kB | gzip: 0.30 kB
+dist/assets/react-CHdo91hT.svg  4.13 kB | gzip: 2.05 kB
+dist/assets/index-D8b4DHJx.css  1.39 kB | gzip: 0.71 kB
+dist/assets/index-CAl1KfkQ.js188.06 kB | gzip: 59.21 kB
+✓ built in 308ms
+</pre>
       </td>
     </tr>
 

From 1cadbdc500551db5ff95a94d581342a0d18ba7fe Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Thu, 13 Nov 2025 18:32:39 +0800
Subject: [PATCH 05/17] align

---
 docs/tui_design.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tui_design.md b/docs/tui_design.md
index fc838918..3b717974 100644
--- a/docs/tui_design.md
+++ b/docs/tui_design.md
@@ -10,7 +10,7 @@
 
 <table>
   <tbody>
-    <tr style="vertical-align: top">
+    <tr valign="top" align="left">
       <td>
         <ul>
           <li><code>vite run ready</code>

From 71cd20fd8f0966a511df39d5bc0f81f7f4ba40da Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Thu, 13 Nov 2025 18:36:19 +0800
Subject: [PATCH 06/17] update

---
 docs/tui_design.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tui_design.md b/docs/tui_design.md
index 3b717974..ce48a168 100644
--- a/docs/tui_design.md
+++ b/docs/tui_design.md
@@ -27,7 +27,7 @@
       </td>
       <td>
       <pre>
-$ vite build <br />
+$ vite build <small>(cache hit, replaying)</small><br />
 VITE+ v1.0.0 building for production
 transforming...
 ✓ 32 modules transformed...

From 30a99295ec7b3b747d0d749267c064fc0948dc74 Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Sat, 15 Nov 2025 18:29:40 +0800
Subject: [PATCH 07/17] updatre

---
 docs/1 - Getting Started.md    |  54 ++++++++++++++++
 docs/2 - Defining Tasks.md     |  96 +++++++++++++++++++++++++++
 docs/2 - Task Orchestration.md |   0
 docs/3 - CLI Options.md        |   5 ++
 docs/4 - Task Orchestration.md | 115 +++++++++++++++++++++++++++++++++
 docs/5 - Configuring Cache.md  |  19 ++++++
 docs/tui_design.md             |  25 ++++---
 7 files changed, 306 insertions(+), 8 deletions(-)
 create mode 100644 docs/2 - Defining Tasks.md
 delete mode 100644 docs/2 - Task Orchestration.md
 create mode 100644 docs/3 - CLI Options.md
 create mode 100644 docs/4 - Task Orchestration.md
 create mode 100644 docs/5 - Configuring Cache.md

diff --git a/docs/1 - Getting Started.md b/docs/1 - Getting Started.md
index e69de29b..25870dbc 100644
--- a/docs/1 - Getting Started.md	
+++ b/docs/1 - Getting Started.md	
@@ -0,0 +1,54 @@
+# Getting Started
+
+Vite is designed to work out of the box with zero configuration. Simply run `vite run <script>` to execute any script defined in your `package.json` file.
+
+For example, if you have the following script defined in your `package.json`:
+
+```
+// package.json
+{
+    "scripts": {
+        "lint": "vite lint"
+    }
+}
+```
+
+The first time of `vite run build`, Vite Task will execute it just like `npm run build`:
+
+```
+$ vite run lint
+
+> vite lint
+
+Found 0 warnings and 0 errors.
+✓ Finished in 103ms on 3192 files with 88 rules using 10 threads.
+```
+
+And if you run it again immediately, Vite Task will detect that nothing has changed and replay the cached ouput instantly without re-running the script:
+
+```
+$ vite run lint
+
+> vite lint (cache hit, replaying)
+
+Found 0 warnings and 0 errors.
+✓ Finished in 103ms on 3192 files with 88 rules using 10 threads.
+```
+
+Then, if you modify some source files and run it again, Vite Task will re-execute the script to produce fresh output:
+
+```
+$ echo "debugger;" > src/index.js && vite run lint
+
+> vite lint (cache miss, because the content of src/index.js changed)
+
+  ⚠ eslint(no-debugger): `debugger` statement is not allowed
+   ╭─[src/index.js:1:1]
+ 1 │ debugger;
+   · ─────────
+   ╰────
+  help: Remove the debugger statement
+
+Found 1 warning and 0 errors.
+✓ Finished in 114ms on 3192 files with 88 rules using 10 threads.
+```
diff --git a/docs/2 - Defining Tasks.md b/docs/2 - Defining Tasks.md
new file mode 100644
index 00000000..845e3665
--- /dev/null
+++ b/docs/2 - Defining Tasks.md	
@@ -0,0 +1,96 @@
+# Defining Tasks
+
+There are two ways to define tasks in Vite Task:
+
+- **`scripts` in `package.json`**: Any script you define there can be run with `vite run <script-name>`, just like `npm run <script-name>`.
+- **`vite-task.json`**: You can also define tasks in a dedicated `vite-task.json` file for more flexible configurations.
+
+## `vite-task.json`
+
+The `vite-task.json` file allows you to define tasks with more flexibility and options compared to `package.json` scripts. **It can be placed in in any packages alongside `package.json` to define tasks specific to that package.**
+
+Here is an example of a `vite-task.json` file:
+
+```json
+{
+  "tasks": {
+    "build": {
+      "command": "vite build",
+      "cwd": "./packages/app",
+      "env": {
+        "NODE_ENV": "production"
+      }
+    },
+    "test": {
+      "command": "vite test",
+      "cwd": "./packages/app"
+    }
+  }
+}
+```
+
+Configurable fields for each task:
+
+- `command` (string): The command to execute for the task.
+- `cwd` (string, optional): The working directory to run the command in. Defaults to the directory containing the `vite-task.json` file.
+- `dependsOn` (array of strings, optional): A list of other tasks that this task depends on. See [Task Orchestration](4%20-%20Task%20Orchestration) for details.
+- `cache`, `envs`, `passthroughEnvs`, `inputs`, `outputs`: see [Configuring Cache](5%20-%20Configuring%20Cache.md) for details.
+
+## Configuration Merging
+
+### Merging with `package.json` Scripts
+
+If your want to keep your existing `package.json` scripts, but also need more advanced configurations for some of them, you can define a task with the same name in `vite-task.json`. **Vite Task will use the configuration from `vite-task.json` and the command from `package.json`**.
+
+For example, the following combination of `package.json` and `vite-task.json`:
+
+```json
+// package.json
+{
+    "scripts": {
+        "build": "webpack",
+    }
+}
+// vite-task.json
+{
+    "tasks": {
+        "type-check": {
+            "envs": ["NODE_ENV"]
+        }
+    }
+}
+```
+
+is equivalent to:
+
+```json
+// vite-task.json
+{
+  "tasks": {
+    "build": {
+      "command": "webpack",
+      "envs": ["NODE_ENV"]
+    }
+  }
+}
+```
+
+> If both script in `package.json` and `command` in `vite-task.json` are defined for the same name, Vite Task will report the conflict and abort.
+
+### Merging with `defaults` in `vite-task.json`
+
+You can provide default configurations by defining `defaults` in `vite-task.json` located in the root of the workspace. **Each configuration defined in `defaults` will be applied to all tasks in the workspace with the same name**, unless they explicitly override the configuration.
+
+```json
+// vite-task.json
+{
+  "defaults": {
+    "build": {
+      // Disable caching for all tasks named "build"
+      "cache": false
+    }
+  }
+}
+```
+
+> `defaults` field in non-root `vite-task.json` files are currently not allowed. Vite Task will report an error and abort if it sees one.
diff --git a/docs/2 - Task Orchestration.md b/docs/2 - Task Orchestration.md
deleted file mode 100644
index e69de29b..00000000
diff --git a/docs/3 - CLI Options.md b/docs/3 - CLI Options.md
new file mode 100644
index 00000000..3eac1c56
--- /dev/null
+++ b/docs/3 - CLI Options.md	
@@ -0,0 +1,5 @@
+# CLI Options
+
+- `vite run <task_name>`: Executes the specified task defined in `vite-task.json` or `package.json` in the current package.
+- `vite run <package_name>#<task_name>`: Executes the specified task in the given package within a monorepo.
+- `vite run -r <task_name>`: Executes the task with the specified name across all packages in a monorepo, in topological order based on dependencies.
diff --git a/docs/4 - Task Orchestration.md b/docs/4 - Task Orchestration.md
new file mode 100644
index 00000000..b44befe7
--- /dev/null
+++ b/docs/4 - Task Orchestration.md	
@@ -0,0 +1,115 @@
+# Task Orchestration
+
+## Compositing Tasks Inside Scripts
+
+Vite Task allows you to composite tasks with bash-like syntaxes right inside your scripts defined in `package.json`/`vite-task.json`.
+
+### Multi-step Tasks
+
+You may have already use `&&` in your scripts to run multiple commands in sequence. Vite Task regognizes this pattern and caches each step individually.
+
+For example:
+
+```json
+// package.json
+{
+  "name": "app",
+  "scripts": {
+    "build": "vite build && vite preview"
+  }
+}
+```
+
+Vite Task will show `vite build` and `vite preview` as individual commands with their own cache status under the `build` task.
+
+- `app#build`
+  - `vite build`
+  - `vite preview`
+
+### Nested Tasks
+
+Vite Task recursively expands `vite run ...` in scripts to run nested tasks directly instead of spawning a new vite task subprocess. This gives you a cleaner overview of all the executions and avoids unnecessary process spawning overhead.
+
+```json
+// package.json
+{
+  "name": "monorepoRoot",
+  "scripts": {
+    "ready": "vite run format && vite run -r build",
+    "format": "dprint fmt && vite fmt"
+  }
+}
+```
+
+Vite Task will show:
+
+- `monorepoRoot#ready`
+  - `monorepoRoot#format`
+    - `dprint fmt`
+    - `vite fmt`
+
+### Supported Syntaxes
+
+In order for multi-step and nested tasks to be recognized correctly, Vite Task currently supports a subset of bash syntaxes:
+
+- Simple commands: `program arg1 arg2 ...`
+- Commands prefixed with environment variables: `VAR=value program arg1 arg2`
+- Referencing variables with `$`, supporting default values: `program $FOO a${BAR}b ${BAZ:42}`
+- Sequential commands: `program1 && VAR=value program2 $FOO && ...`
+
+If a script contains syntaxes beyoud these, Vite Task falls back to normal script execution with system shells. For example, the following script will not be split into multiple steps because of the `if` statement:
+
+```json
+{
+  "scripts": {
+    "complex": "if [ -f file.txt ]; then vite lint && vite build ; fi"
+  }
+}
+```
+
+Note that even if a script is not expanded, Vite Task is still able to **cache the entire script execution as a single unit**.
+
+If you put a `vite run ...` command inside a script with unsupported syntax, like the example below, the **inner `vite run ...` will fail** at execution time, because it is currently not supported to cache both `build` tasks and `complex` as a single unit at the same time.
+
+```bash
+{
+    "scripts": {
+        "complex": "if [ -f file.txt ]; then vite run -r build; fi"
+    }
+}
+```
+
+To make it work, you can disable caching for the outer task by adding `"cache": false` in `vite-task.json`:
+
+```json
+/// vite-task.json
+{
+  "tasks": {
+    "complex": {
+      "cache": false,
+      "script": "if [ -f file.txt ]; then vite run -r build; fi"
+    }
+  }
+}
+```
+
+## Task Dependencies
+
+Task dependencies can be defined in `vite-task.json` file. You can specify which tasks need to be executed before a particular task runs.
+
+```json
+{
+  "tasks": {
+    "build": {
+      "dependsOn": ["lint", "test"],
+      "script": "vite build"
+    },
+    "lint": {
+      "script": "eslint src/"
+    },
+    "test": {
+      "script": "jest"
+    }
+  }
+}
+```
diff --git a/docs/5 - Configuring Cache.md b/docs/5 - Configuring Cache.md
new file mode 100644
index 00000000..d213a584
--- /dev/null
+++ b/docs/5 - Configuring Cache.md	
@@ -0,0 +1,19 @@
+```json
+{
+  "scripts": {
+    "build": "vite build",
+    "lint": "eslint src/",
+    "test": "jest"
+  },
+  "cache": false,
+  "inputs": [
+    "src/**",
+    "!src/**/*.test.ts",
+    "package.json",
+    "vite.config.ts"
+  ],
+  "outputs": [
+    "dist/**"
+  ]
+}
+```
diff --git a/docs/tui_design.md b/docs/tui_design.md
index ce48a168..a033763e 100644
--- a/docs/tui_design.md
+++ b/docs/tui_design.md
@@ -3,7 +3,8 @@
 ```json
 {
   "script": {
-    "ready": "tsc --noEmit && vite lint && vite run -r build"
+    "ready": "vite run format && tsc --noEmit && vite run -r build",
+    "format": "dprint fmt && vite fmt"
   }
 }
 ```
@@ -15,8 +16,13 @@
         <ul>
           <li><code>vite run ready</code>
             <ul>
+              <li><code>vite run format</code>
+              <ul>
+                <li><code>dprint fmt</code></li>
+                <li><code>vite fmt</code></li>
+              </ul>
+              </li>
               <li><code>tsc --noEmit</code></li>
-              <li><code>vite lint</code></li>
               <li><code>vite run -r build</code>
               <ul>
               <li><code>pkg1#build</code></li>
@@ -27,20 +33,23 @@
       </td>
       <td>
       <pre>
-$ vite build <small>(cache hit, replaying)</small><br />
+$ vite build
+
+<small>(cache hit, replaying)</small><br />
 VITE+ v1.0.0 building for production
 transforming...
 ✓ 32 modules transformed...
 rendering chunks...
 computing gzip size...
-dist/index.html  0.46 kB | gzip: 0.30 kB
-dist/assets/react-CHdo91hT.svg  4.13 kB | gzip: 2.05 kB
-dist/assets/index-D8b4DHJx.css  1.39 kB | gzip: 0.71 kB
+dist/index.html 0.46 kB | gzip: 0.30 kB
+dist/assets/react-CHdo91hT.svg 4.13 kB | gzip: 2.05 kB
+dist/assets/index-D8b4DHJx.css 1.39 kB | gzip: 0.71 kB
 dist/assets/index-CAl1KfkQ.js188.06 kB | gzip: 59.21 kB
 ✓ built in 308ms
 </pre>
-      </td>
-    </tr>
+
+</td>
+</tr>
 
 </tbody>
 </table>

From 6390ead416abfa45985d44126473419586b709d3 Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Sat, 15 Nov 2025 20:53:46 +0800
Subject: [PATCH 08/17] update

---
 docs/1 - Getting Started.md    |   2 +-
 docs/2 - Defining Tasks.md     |  21 ++--
 docs/4 - Task Orchestration.md |  97 ++++++++++++++---
 docs/5 - Configuring Cache.md  | 194 ++++++++++++++++++++++++++++++---
 docs/main_points.md            |   1 -
 docs/tui_design.md             |  55 ----------
 6 files changed, 271 insertions(+), 99 deletions(-)
 delete mode 100644 docs/main_points.md
 delete mode 100644 docs/tui_design.md

diff --git a/docs/1 - Getting Started.md b/docs/1 - Getting Started.md
index 25870dbc..e6e74f44 100644
--- a/docs/1 - Getting Started.md	
+++ b/docs/1 - Getting Started.md	
@@ -35,7 +35,7 @@ Found 0 warnings and 0 errors.
 ✓ Finished in 103ms on 3192 files with 88 rules using 10 threads.
 ```
 
-Then, if you modify some source files and run it again, Vite Task will re-execute the script to produce fresh output:
+Then, if you modify some source files and run it again, Vite Task will tell you the reason of cache miss, and re-execute the script:
 
 ```
 $ echo "debugger;" > src/index.js && vite run lint
diff --git a/docs/2 - Defining Tasks.md b/docs/2 - Defining Tasks.md
index 845e3665..7e327cdf 100644
--- a/docs/2 - Defining Tasks.md	
+++ b/docs/2 - Defining Tasks.md	
@@ -2,12 +2,12 @@
 
 There are two ways to define tasks in Vite Task:
 
-- **`scripts` in `package.json`**: Any script you define there can be run with `vite run <script-name>`, just like `npm run <script-name>`.
-- **`vite-task.json`**: You can also define tasks in a dedicated `vite-task.json` file for more flexible configurations.
+- `scripts` in `package.json`: Any script you define there can be run with `vite run <script-name>`, just like `npm run <script-name>`.
+- `vite-task.json`: You can also define tasks in a dedicated `vite-task.json` file.
 
 ## `vite-task.json`
 
-The `vite-task.json` file allows you to define tasks with more flexibility and options compared to `package.json` scripts. **It can be placed in in any packages alongside `package.json` to define tasks specific to that package.**
+The `vite-task.json` file allows you to define tasks with more flexibility and options compared to `package.json` scripts. **It can be placed in roots of packages alongside `package.json` to define tasks specific to that package.**
 
 Here is an example of a `vite-task.json` file:
 
@@ -15,15 +15,12 @@ Here is an example of a `vite-task.json` file:
 {
   "tasks": {
     "build": {
-      "command": "vite build",
-      "cwd": "./packages/app",
-      "env": {
-        "NODE_ENV": "production"
-      }
+      "command": "webpack",
+      "envs": ["NODE_ENV"]
     },
     "test": {
-      "command": "vite test",
-      "cwd": "./packages/app"
+      "command": "vite lint",
+      "cwd": "./src"
     }
   }
 }
@@ -40,7 +37,7 @@ Configurable fields for each task:
 
 ### Merging with `package.json` Scripts
 
-If your want to keep your existing `package.json` scripts, but also need more advanced configurations for some of them, you can define a task with the same name in `vite-task.json`. **Vite Task will use the configuration from `vite-task.json` and the command from `package.json`**.
+If your want to keep your existing `package.json` scripts, but also need customized configurations for them, you can define a task with the same name in `vite-task.json`. **Vite Task will use the configuration from `vite-task.json` and the command from `package.json`**.
 
 For example, the following combination of `package.json` and `vite-task.json`:
 
@@ -75,7 +72,7 @@ is equivalent to:
 }
 ```
 
-> If both script in `package.json` and `command` in `vite-task.json` are defined for the same name, Vite Task will report the conflict and abort.
+> If both script in `package.json` and `command` in `vite-task.json` are defined with the same name, Vite Task will report the conflict and abort.
 
 ### Merging with `defaults` in `vite-task.json`
 
diff --git a/docs/4 - Task Orchestration.md b/docs/4 - Task Orchestration.md
index b44befe7..04bf5b1a 100644
--- a/docs/4 - Task Orchestration.md	
+++ b/docs/4 - Task Orchestration.md	
@@ -22,9 +22,41 @@ For example:
 
 Vite Task will show `vite build` and `vite preview` as individual commands with their own cache status under the `build` task.
 
-- `app#build`
-  - `vite build`
-  - `vite preview`
+<table>
+  <tbody>
+    <tr valign="top" align="left">
+      <td>
+        <ul>
+          <li><code>app#build</code>
+            <ul>
+              <li><code>vite build</code></li>
+              <li><code>vite preview</code></li>
+              <ul>
+          </li>
+        </ul>
+      </td>
+      <td>
+      <pre>
+$ vite build
+
+<small>(cache hit, replaying)</small><br />
+VITE+ v1.0.0 building for production
+transforming...
+✓ 32 modules transformed...
+rendering chunks...
+computing gzip size...
+dist/index.html 0.46 kB | gzip: 0.30 kB
+dist/assets/react-CHdo91hT.svg 4.13 kB | gzip: 2.05 kB
+dist/assets/index-D8b4DHJx.css 1.39 kB | gzip: 0.71 kB
+dist/assets/index-CAl1KfkQ.js188.06 kB | gzip: 59.21 kB
+✓ built in 308ms
+</pre>
+
+</td>
+</tr>
+
+</tbody>
+</table>
 
 ### Nested Tasks
 
@@ -43,10 +75,42 @@ Vite Task recursively expands `vite run ...` in scripts to run nested tasks dire
 
 Vite Task will show:
 
-- `monorepoRoot#ready`
-  - `monorepoRoot#format`
-    - `dprint fmt`
-    - `vite fmt`
+<table>
+  <tbody>
+    <tr valign="top" align="left">
+      <td>
+        <ul>
+          <li><code>monorepoRoot#ready</code>
+            <ul>
+              <li><code>vite run format</code>
+              <ul>
+                <li><code>dprint fmt</code></li>
+                <li><code>vite fmt</code></li>
+              </ul>
+              </li>
+              <li><code>vite run -r build</code>
+              <ul>
+              <li><code>pkg1#build</code></li>
+              <li><code>pkg2#build</code></li>
+              <li><code>pkg3#build</code></li>
+          </li>
+        </ul>
+      </td>
+      <td>
+      <pre>
+$ vite lint
+
+<small>(cache hit, replaying)</small><br />
+VITE+ v1.0.0 lint
+Found 0 warnings and 0 errors.
+✓ Finished in 1ms on 3 files with 88 rules using 10 threads.
+</pre>
+
+</td>
+</tr>
+
+</tbody>
+</table>
 
 ### Supported Syntaxes
 
@@ -54,7 +118,7 @@ In order for multi-step and nested tasks to be recognized correctly, Vite Task c
 
 - Simple commands: `program arg1 arg2 ...`
 - Commands prefixed with environment variables: `VAR=value program arg1 arg2`
-- Referencing variables with `$`, supporting default values: `program $FOO a${BAR}b ${BAZ:42}`
+- Referencing variables with `$`: `program $FOO a${BAR}b ${BAZ:42}`
 - Sequential commands: `program1 && VAR=value program2 $FOO && ...`
 
 If a script contains syntaxes beyoud these, Vite Task falls back to normal script execution with system shells. For example, the following script will not be split into multiple steps because of the `if` statement:
@@ -87,7 +151,7 @@ To make it work, you can disable caching for the outer task by adding `"cache":
   "tasks": {
     "complex": {
       "cache": false,
-      "script": "if [ -f file.txt ]; then vite run -r build; fi"
+      "command": "if [ -f file.txt ]; then vite run -r build; fi"
     }
   }
 }
@@ -95,21 +159,22 @@ To make it work, you can disable caching for the outer task by adding `"cache":
 
 ## Task Dependencies
 
-Task dependencies can be defined in `vite-task.json` file. You can specify which tasks need to be executed before a particular task runs.
+Task dependencies can be defined in `vite-task.json` file. You can specify which tasks need to be executed before a particular task runs:
 
 ```json
 {
   "tasks": {
     "build": {
-      "dependsOn": ["lint", "test"],
-      "script": "vite build"
+      "command": "vite build",
+      "dependsOn": ["lint", "ui#test", "^build"]
     },
     "lint": {
-      "script": "eslint src/"
-    },
-    "test": {
-      "script": "jest"
+      "script": "vite lint"
     }
   }
 }
 ```
+
+- `lint` refers to the `lint` task in the same package.
+- `ui#test` refers to the `test` task in the `ui` package.
+- `^build` refers to all the tasks named `build` in the dependencies of the current package.
diff --git a/docs/5 - Configuring Cache.md b/docs/5 - Configuring Cache.md
index d213a584..ac9d544d 100644
--- a/docs/5 - Configuring Cache.md	
+++ b/docs/5 - Configuring Cache.md	
@@ -1,19 +1,185 @@
+# Configuring Cache
+
+Fields `cache`, `envs`, `passthroughEnvs`, `inputs`, and `outputs` in `vite-task.json` can be used to configure caching behavior for tasks. All of them are optional. The default values are:
+
 ```json
 {
-  "scripts": {
-    "build": "vite build",
-    "lint": "eslint src/",
-    "test": "jest"
-  },
-  "cache": false,
-  "inputs": [
-    "src/**",
-    "!src/**/*.test.ts",
-    "package.json",
-    "vite.config.ts"
+  "cache": true,
+  "envs": [],
+  "passthroughEnvs": [
+    "PATH",
+    "HOME" /* ... */
   ],
-  "outputs": [
-    "dist/**"
-  ]
+  "inputs": "inferred",
+  "outputs": [],
+  "idempotent": false
+}
+```
+
+> You generally don't need to configure caching for vite+ subcommands like `vite build` and `vite test`. They are automatically adjusted. The default values above are for 3rd party tools only.
+
+### `cache` (boolean, default: `true`)
+
+Cache are enabled by default, so that scripts in `package.json` are cached unless explicitly disabled.
+
+Caching are automatically disabled for tasks that failed, or received user inputs from stdin (such as prompts or `Ctrl-C`), so it's generally safe to enable caching long-running tasks such as dev servers.
+
+> If cache is disabled, all the other cache-related configurations are irrelevant.
+
+Here are some scenarios where you may want to disable caching explicitly:
+
+```json
+// vite-task.json
+{
+  "tasks": {
+    "server": {
+      "command": "node start-server.js",
+      // If this server may exit normally without any stdin interaction,
+      // Vite Task cannot determine its long-running nature automatically.
+      // We have to disable caching explicitly.
+      "cache": false
+    },
+    "fetch": {
+      "command": "wgets http://example.com/data",
+      // This task produces non-deterministic outputs from network requests.
+      "cache": false
+    },
+    "roll-dice": {
+      "command": "shuf -i 1-6 -n 1",
+      // This task produces non-deterministic outputs from RNG.
+      "cache": false
+    }
+  }
+}
+```
+
+### `envs` (array of strings, default: `[]`)
+
+`envs` specifies a list of environment variables that are passed to the task and are considered when fingerprinting for caching. If any of these environment variables change, the cache will be invalidated and the task will be re-executed.
+
+By default, no environment variables are included in the cache fingerprint, and only those listed in `passthroughEnvs` are passed to the task.
+
+> The descison of passing no envs instead of all envs by default is made to avoid unintentional cache misses due to unrelated env changes. Some of the envs are updated by shell every frequently, even after every command execution, making caching practically useless.
+
+### `passthroughEnvs` (array of strings, default: see above)
+
+`passthroughEnvs` specifies a list of environment variables that are always passed to the task, but are not considered when fingerprinting for caching. This is useful for envs that are necessary for the task to run, but should not affect caching, such as `PATH` and `HOME`.
+
+Example:
+
+```json
+// vite-task.json
+{
+  "tasks": {
+    "build": {
+      "command": "webpack",
+      // This task reads NODE_ENV,
+      // and changes to NODE_ENV should invalidate the cache.
+      "envs": ["NODE_ENV"],
+      // This tasks reads GITHUB_TOKEN,
+      // but changes to GITHUB_TOKEN should not invalidate the cache.
+      "passthroughEnvs": ["GITHUB_TOKEN"]
+    }
+  }
+}
+```
+
+### `inputs` (array of strings or `"inferred"`, default: `"inferred"`)
+
+`inputs` specifies the input files or directories that are considered when fingerprinting for caching. You can specify specific files or directories, or use glob patterns. If set to `"inferred"`, Vite Task will automatically infer the input files.
+
+> `inferred` mode are guaranteed to work for vite+ subcommands like `vite build` and `vite test`. For other tools, it may not be able to infer all input files correctly, be too cauious to include unnecessary files. In such cases, you can manually specify the input files.
+
+Example:
+
+```json
+// vite-task.json
+{
+  "tasks": {
+    "install": {
+      "command": "pnpm install",
+      // Changing these files invalidates the cache for `pnpm install`
+      "inputs": [
+        "package.json",
+        "pnpm-lock.yaml",
+        "patches/**"
+      ]
+    }
+  }
+}
+```
+
+### `outputs` (array of strings, default: `[]`)
+
+`outputs` specifies the output files or directories that are produced by the task. Vite Task will cache these output files and restore them from cache when the cache is hit. You can specify specific files or directories, or use glob patterns. If not specified, no output files are cached.
+
+> stdout and stderr are always cached regardless of this setting.
+
+> `outputs` for `vite build` are automatically configured without the need of explicit settings.
+
+Example:
+
+```json
+// vite-task.json
+{
+  "tasks": {
+    "build": {
+      "command": "webpack",
+      // Saving files in folder "dist" in cache,
+      // and restoring them when cache is hit.
+      "inputs": [
+        "dist/**"
+      ]
+    }
+  }
+}
+```
+
+### idempotent (boolean, default: `false`)
+
+Vite Task infers all the filesystem reads and writes during task execution. If it is detected that a task reads and writes the same file, Vite Task will not cache the task because an immediate re-execution may produce different results because of the file change.
+
+However, some tools are designed to be idempotent, meaning that re-executing them will not change the file again. For example, a code formatter may read and write the same source files, but running it multiple times will not change the formatted files after the first run.
+
+Vite Task cannot infer idempotency automatically for 3rd party tools, so you can explicitly mark a task as idempotent to allow caching even if it reads and writes the same file.
+
+> `vite lint` and `vite format` are automatically marked as idempotent.
+
+Example:
+
+```json
+// vite-task.json
+{
+  "tasks": {
+    // formatter and autofix linter tasks are usually idempotent
+    "format": {
+      "command": "prettier --write src/**",
+      "idempotent": true
+    },
+    "autofix-lint": {
+      "command": "eslint --fix src/**",
+      "idempotent": true
+    }
+  }
+}
+```
+
+## Cache Restrictions on Compound Tasks
+
+When a task is expanded into multiple steps or nested tasks (see [Task Orchestration](4%20-%20Task%20Orchestration) for details), Vite Task currently only supports caching each individual step separately. The overall task cannot be cached as a whole, and trying to enable caching for such tasks will result in an error.
+
+Example:
+
+```json
+// vite-task.json
+{
+  "tasks": {
+    "build-and-test": {
+      "command": "vite build && vite test",
+      // Error: caching is not supported for multi-step tasks.
+      // It's not necessary anyway, as each step can be cached separately.
+      "cache": true
+    }
+  }
 }
 ```
diff --git a/docs/main_points.md b/docs/main_points.md
deleted file mode 100644
index 32eebd35..00000000
--- a/docs/main_points.md
+++ /dev/null
@@ -1 +0,0 @@
-- Distributed
diff --git a/docs/tui_design.md b/docs/tui_design.md
deleted file mode 100644
index a033763e..00000000
--- a/docs/tui_design.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# Vite task TUI Design
-
-```json
-{
-  "script": {
-    "ready": "vite run format && tsc --noEmit && vite run -r build",
-    "format": "dprint fmt && vite fmt"
-  }
-}
-```
-
-<table>
-  <tbody>
-    <tr valign="top" align="left">
-      <td>
-        <ul>
-          <li><code>vite run ready</code>
-            <ul>
-              <li><code>vite run format</code>
-              <ul>
-                <li><code>dprint fmt</code></li>
-                <li><code>vite fmt</code></li>
-              </ul>
-              </li>
-              <li><code>tsc --noEmit</code></li>
-              <li><code>vite run -r build</code>
-              <ul>
-              <li><code>pkg1#build</code></li>
-              <li><code>pkg2#build</code></li>
-              <li><code>pkg3#build</code></li>
-          </li>
-        </ul>
-      </td>
-      <td>
-      <pre>
-$ vite build
-
-<small>(cache hit, replaying)</small><br />
-VITE+ v1.0.0 building for production
-transforming...
-✓ 32 modules transformed...
-rendering chunks...
-computing gzip size...
-dist/index.html 0.46 kB | gzip: 0.30 kB
-dist/assets/react-CHdo91hT.svg 4.13 kB | gzip: 2.05 kB
-dist/assets/index-D8b4DHJx.css 1.39 kB | gzip: 0.71 kB
-dist/assets/index-CAl1KfkQ.js188.06 kB | gzip: 59.21 kB
-✓ built in 308ms
-</pre>
-
-</td>
-</tr>
-
-</tbody>
-</table>

From 6c53dd27f6a24faf02d317950b1dfd046727d3b1 Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Sat, 15 Nov 2025 21:00:36 +0800
Subject: [PATCH 09/17] Fix typos and improve clarity in documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Fix typos: "ouput" → "output", "regognizes" → "recognizes", "beyoud" → "beyond", "descison" → "decision", "cauious" → "cautious"
- Simplify wording: remove unnecessary words like "flexibility and", "currently", "practically"
- Improve grammar: fix subject-verb agreement ("Cache are" → "Caching is")
- Clarify explanations: rework awkward phrases for better readability
- Maintain technical accuracy while making text more concise

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/1 - Getting Started.md    |  6 +++---
 docs/2 - Defining Tasks.md     | 10 +++++-----
 docs/4 - Task Orchestration.md | 16 ++++++++--------
 docs/5 - Configuring Cache.md  | 30 +++++++++++++++---------------
 4 files changed, 31 insertions(+), 31 deletions(-)

diff --git a/docs/1 - Getting Started.md b/docs/1 - Getting Started.md
index e6e74f44..a3a9a216 100644
--- a/docs/1 - Getting Started.md	
+++ b/docs/1 - Getting Started.md	
@@ -13,7 +13,7 @@ For example, if you have the following script defined in your `package.json`:
 }
 ```
 
-The first time of `vite run build`, Vite Task will execute it just like `npm run build`:
+The first time you run `vite run lint`, Vite Task will execute it just like `npm run lint`:
 
 ```
 $ vite run lint
@@ -24,7 +24,7 @@ Found 0 warnings and 0 errors.
 ✓ Finished in 103ms on 3192 files with 88 rules using 10 threads.
 ```
 
-And if you run it again immediately, Vite Task will detect that nothing has changed and replay the cached ouput instantly without re-running the script:
+If you run it again immediately, Vite Task will detect that nothing has changed and replay the cached output instantly without re-running the script:
 
 ```
 $ vite run lint
@@ -35,7 +35,7 @@ Found 0 warnings and 0 errors.
 ✓ Finished in 103ms on 3192 files with 88 rules using 10 threads.
 ```
 
-Then, if you modify some source files and run it again, Vite Task will tell you the reason of cache miss, and re-execute the script:
+If you modify a source file and run it again, Vite Task will tell you why the cache was missed and re-execute the script:
 
 ```
 $ echo "debugger;" > src/index.js && vite run lint
diff --git a/docs/2 - Defining Tasks.md b/docs/2 - Defining Tasks.md
index 7e327cdf..15716014 100644
--- a/docs/2 - Defining Tasks.md	
+++ b/docs/2 - Defining Tasks.md	
@@ -7,7 +7,7 @@ There are two ways to define tasks in Vite Task:
 
 ## `vite-task.json`
 
-The `vite-task.json` file allows you to define tasks with more flexibility and options compared to `package.json` scripts. **It can be placed in roots of packages alongside `package.json` to define tasks specific to that package.**
+The `vite-task.json` file lets you define tasks with more options than `package.json` scripts. **Place it in the root of a package alongside `package.json` to define tasks for that package.**
 
 Here is an example of a `vite-task.json` file:
 
@@ -37,7 +37,7 @@ Configurable fields for each task:
 
 ### Merging with `package.json` Scripts
 
-If your want to keep your existing `package.json` scripts, but also need customized configurations for them, you can define a task with the same name in `vite-task.json`. **Vite Task will use the configuration from `vite-task.json` and the command from `package.json`**.
+If you want to keep your existing `package.json` scripts but also need custom configurations for them, you can define a task with the same name in `vite-task.json`. **Vite Task will use the configuration from `vite-task.json` and the command from `package.json`**.
 
 For example, the following combination of `package.json` and `vite-task.json`:
 
@@ -72,11 +72,11 @@ is equivalent to:
 }
 ```
 
-> If both script in `package.json` and `command` in `vite-task.json` are defined with the same name, Vite Task will report the conflict and abort.
+> If a script in `package.json` and a `command` in `vite-task.json` have the same name, Vite Task will report the conflict and abort.
 
 ### Merging with `defaults` in `vite-task.json`
 
-You can provide default configurations by defining `defaults` in `vite-task.json` located in the root of the workspace. **Each configuration defined in `defaults` will be applied to all tasks in the workspace with the same name**, unless they explicitly override the configuration.
+You can provide default configurations by defining `defaults` in `vite-task.json` at the root of the workspace. **Each configuration defined in `defaults` will be applied to all tasks in the workspace with the same name**, unless a task explicitly overrides it.
 
 ```json
 // vite-task.json
@@ -90,4 +90,4 @@ You can provide default configurations by defining `defaults` in `vite-task.json
 }
 ```
 
-> `defaults` field in non-root `vite-task.json` files are currently not allowed. Vite Task will report an error and abort if it sees one.
+> The `defaults` field is only allowed in the root `vite-task.json` file. Vite Task will report an error and abort if it finds one elsewhere.
diff --git a/docs/4 - Task Orchestration.md b/docs/4 - Task Orchestration.md
index 04bf5b1a..ab1cd3fd 100644
--- a/docs/4 - Task Orchestration.md	
+++ b/docs/4 - Task Orchestration.md	
@@ -1,12 +1,12 @@
 # Task Orchestration
 
-## Compositing Tasks Inside Scripts
+## Composing Tasks Inside Scripts
 
-Vite Task allows you to composite tasks with bash-like syntaxes right inside your scripts defined in `package.json`/`vite-task.json`.
+Vite Task lets you compose tasks with bash-like syntax inside your scripts defined in `package.json` or `vite-task.json`.
 
 ### Multi-step Tasks
 
-You may have already use `&&` in your scripts to run multiple commands in sequence. Vite Task regognizes this pattern and caches each step individually.
+You may already use `&&` in your scripts to run multiple commands in sequence. Vite Task recognizes this pattern and caches each step individually.
 
 For example:
 
@@ -60,7 +60,7 @@ dist/assets/index-CAl1KfkQ.js188.06 kB | gzip: 59.21 kB
 
 ### Nested Tasks
 
-Vite Task recursively expands `vite run ...` in scripts to run nested tasks directly instead of spawning a new vite task subprocess. This gives you a cleaner overview of all the executions and avoids unnecessary process spawning overhead.
+Vite Task recursively expands `vite run ...` in scripts to run nested tasks directly instead of spawning a new subprocess. This gives you a cleaner overview of all executions and avoids unnecessary overhead.
 
 ```json
 // package.json
@@ -114,14 +114,14 @@ Found 0 warnings and 0 errors.
 
 ### Supported Syntaxes
 
-In order for multi-step and nested tasks to be recognized correctly, Vite Task currently supports a subset of bash syntaxes:
+For multi-step and nested tasks to be recognized correctly, Vite Task supports a subset of bash syntax:
 
 - Simple commands: `program arg1 arg2 ...`
 - Commands prefixed with environment variables: `VAR=value program arg1 arg2`
 - Referencing variables with `$`: `program $FOO a${BAR}b ${BAZ:42}`
 - Sequential commands: `program1 && VAR=value program2 $FOO && ...`
 
-If a script contains syntaxes beyoud these, Vite Task falls back to normal script execution with system shells. For example, the following script will not be split into multiple steps because of the `if` statement:
+If a script contains syntax beyond these, Vite Task falls back to normal script execution with system shells. For example, the following script will not be split into multiple steps because of the `if` statement:
 
 ```json
 {
@@ -131,9 +131,9 @@ If a script contains syntaxes beyoud these, Vite Task falls back to normal scrip
 }
 ```
 
-Note that even if a script is not expanded, Vite Task is still able to **cache the entire script execution as a single unit**.
+Even if a script is not expanded, Vite Task can still **cache the entire script execution as a single unit**.
 
-If you put a `vite run ...` command inside a script with unsupported syntax, like the example below, the **inner `vite run ...` will fail** at execution time, because it is currently not supported to cache both `build` tasks and `complex` as a single unit at the same time.
+If you put a `vite run ...` command inside a script with unsupported syntax, like the example below, the **inner `vite run ...` will fail** at execution time, because caching both `build` tasks and `complex` as a single unit is not currently supported.
 
 ```bash
 {
diff --git a/docs/5 - Configuring Cache.md b/docs/5 - Configuring Cache.md
index ac9d544d..7d679397 100644
--- a/docs/5 - Configuring Cache.md	
+++ b/docs/5 - Configuring Cache.md	
@@ -20,9 +20,9 @@ Fields `cache`, `envs`, `passthroughEnvs`, `inputs`, and `outputs` in `vite-task
 
 ### `cache` (boolean, default: `true`)
 
-Cache are enabled by default, so that scripts in `package.json` are cached unless explicitly disabled.
+Caching is enabled by default, so scripts in `package.json` are cached unless explicitly disabled.
 
-Caching are automatically disabled for tasks that failed, or received user inputs from stdin (such as prompts or `Ctrl-C`), so it's generally safe to enable caching long-running tasks such as dev servers.
+Caching is automatically disabled for tasks that fail or receive user input from stdin (such as prompts or `Ctrl-C`), so it's generally safe to enable caching for long-running tasks like dev servers.
 
 > If cache is disabled, all the other cache-related configurations are irrelevant.
 
@@ -59,11 +59,11 @@ Here are some scenarios where you may want to disable caching explicitly:
 
 By default, no environment variables are included in the cache fingerprint, and only those listed in `passthroughEnvs` are passed to the task.
 
-> The descison of passing no envs instead of all envs by default is made to avoid unintentional cache misses due to unrelated env changes. Some of the envs are updated by shell every frequently, even after every command execution, making caching practically useless.
+> The decision to pass no environment variables by default avoids unintentional cache misses due to unrelated changes. Some environment variables are updated by the shell very frequently, even after every command execution, which would make caching useless.
 
 ### `passthroughEnvs` (array of strings, default: see above)
 
-`passthroughEnvs` specifies a list of environment variables that are always passed to the task, but are not considered when fingerprinting for caching. This is useful for envs that are necessary for the task to run, but should not affect caching, such as `PATH` and `HOME`.
+`passthroughEnvs` specifies a list of environment variables that are always passed to the task, but are not considered when fingerprinting for caching. This is useful for variables that are necessary for the task to run but should not affect caching, such as `PATH` and `HOME`.
 
 Example:
 
@@ -76,7 +76,7 @@ Example:
       // This task reads NODE_ENV,
       // and changes to NODE_ENV should invalidate the cache.
       "envs": ["NODE_ENV"],
-      // This tasks reads GITHUB_TOKEN,
+      // This task reads GITHUB_TOKEN,
       // but changes to GITHUB_TOKEN should not invalidate the cache.
       "passthroughEnvs": ["GITHUB_TOKEN"]
     }
@@ -88,7 +88,7 @@ Example:
 
 `inputs` specifies the input files or directories that are considered when fingerprinting for caching. You can specify specific files or directories, or use glob patterns. If set to `"inferred"`, Vite Task will automatically infer the input files.
 
-> `inferred` mode are guaranteed to work for vite+ subcommands like `vite build` and `vite test`. For other tools, it may not be able to infer all input files correctly, be too cauious to include unnecessary files. In such cases, you can manually specify the input files.
+> `inferred` mode is guaranteed to work for vite+ subcommands like `vite build` and `vite test`. For other tools, it may not infer all input files correctly or may be too cautious and include unnecessary files. In such cases, you can manually specify the input files.
 
 Example:
 
@@ -111,11 +111,11 @@ Example:
 
 ### `outputs` (array of strings, default: `[]`)
 
-`outputs` specifies the output files or directories that are produced by the task. Vite Task will cache these output files and restore them from cache when the cache is hit. You can specify specific files or directories, or use glob patterns. If not specified, no output files are cached.
+`outputs` specifies the output files or directories that are produced by the task. Vite Task will cache these output files and restore them when the cache is hit. You can specify specific files or directories, or use glob patterns. If not specified, no output files are cached.
 
 > stdout and stderr are always cached regardless of this setting.
 
-> `outputs` for `vite build` are automatically configured without the need of explicit settings.
+> `outputs` for `vite build` are automatically configured without explicit settings.
 
 Example:
 
@@ -135,13 +135,13 @@ Example:
 }
 ```
 
-### idempotent (boolean, default: `false`)
+### `idempotent` (boolean, default: `false`)
 
-Vite Task infers all the filesystem reads and writes during task execution. If it is detected that a task reads and writes the same file, Vite Task will not cache the task because an immediate re-execution may produce different results because of the file change.
+Vite Task infers all filesystem reads and writes during task execution. If it detects that a task reads and writes the same file, Vite Task will not cache the task because an immediate re-execution may produce different results.
 
-However, some tools are designed to be idempotent, meaning that re-executing them will not change the file again. For example, a code formatter may read and write the same source files, but running it multiple times will not change the formatted files after the first run.
+However, some tools are designed to be idempotent, meaning that re-executing them will not change the file again. For example, a code formatter may read and write the same source files, but running it multiple times will not change the files after the first run.
 
-Vite Task cannot infer idempotency automatically for 3rd party tools, so you can explicitly mark a task as idempotent to allow caching even if it reads and writes the same file.
+Vite Task cannot infer idempotency automatically for third-party tools, so you can explicitly mark a task as idempotent to allow caching even if it reads and writes the same file.
 
 > `vite lint` and `vite format` are automatically marked as idempotent.
 
@@ -151,7 +151,7 @@ Example:
 // vite-task.json
 {
   "tasks": {
-    // formatter and autofix linter tasks are usually idempotent
+    // Formatters and autofix linters are usually idempotent
     "format": {
       "command": "prettier --write src/**",
       "idempotent": true
@@ -166,7 +166,7 @@ Example:
 
 ## Cache Restrictions on Compound Tasks
 
-When a task is expanded into multiple steps or nested tasks (see [Task Orchestration](4%20-%20Task%20Orchestration) for details), Vite Task currently only supports caching each individual step separately. The overall task cannot be cached as a whole, and trying to enable caching for such tasks will result in an error.
+When a task is expanded into multiple steps or nested tasks (see [Task Orchestration](4%20-%20Task%20Orchestration) for details), Vite Task only supports caching each individual step separately. The overall task cannot be cached as a whole, and trying to enable caching for such tasks will result in an error.
 
 Example:
 
@@ -177,7 +177,7 @@ Example:
     "build-and-test": {
       "command": "vite build && vite test",
       // Error: caching is not supported for multi-step tasks.
-      // It's not necessary anyway, as each step can be cached separately.
+      // Each step can be cached separately.
       "cache": true
     }
   }

From 61ddf963b785df97d9ca17dfa9dbad8ce3f5b21e Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Sat, 15 Nov 2025 21:01:13 +0800
Subject: [PATCH 10/17] update

---
 docs/5 - Configuring Cache.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/5 - Configuring Cache.md b/docs/5 - Configuring Cache.md
index 7d679397..d7dc0919 100644
--- a/docs/5 - Configuring Cache.md	
+++ b/docs/5 - Configuring Cache.md	
@@ -177,7 +177,7 @@ Example:
     "build-and-test": {
       "command": "vite build && vite test",
       // Error: caching is not supported for multi-step tasks.
-      // Each step can be cached separately.
+      // It's not necessary anyway, as each step is already cached separately.
       "cache": true
     }
   }

From 51a2f7b2ea20e834cb25e3040f71b691a74cffa3 Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Sat, 15 Nov 2025 21:04:16 +0800
Subject: [PATCH 11/17] Restructure documentation for better flow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Move CLI usage patterns from separate file into Getting Started
- Remove standalone "CLI Options" file (too minimal, only 3 lines)
- Reorder: put "Configuring Cache" before "Task Orchestration"
  - Cache concepts are referenced in orchestration
  - Logical progression: define tasks → cache them → orchestrate them
- Update all cross-references to reflect new numbering

New structure:
1. Getting Started (now includes CLI usage)
2. Defining Tasks
3. Task Orchestration (was 4)
4. Configuring Cache (was 5)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/1 - Getting Started.md                   | 28 +++++++++++++++++++
 docs/2 - Defining Tasks.md                    |  4 +--
 docs/3 - CLI Options.md                       |  5 ----
 ...estration.md => 3 - Task Orchestration.md} |  0
 ...ring Cache.md => 4 - Configuring Cache.md} |  2 +-
 5 files changed, 31 insertions(+), 8 deletions(-)
 delete mode 100644 docs/3 - CLI Options.md
 rename docs/{4 - Task Orchestration.md => 3 - Task Orchestration.md} (100%)
 rename docs/{5 - Configuring Cache.md => 4 - Configuring Cache.md} (96%)

diff --git a/docs/1 - Getting Started.md b/docs/1 - Getting Started.md
index a3a9a216..4594a91d 100644
--- a/docs/1 - Getting Started.md	
+++ b/docs/1 - Getting Started.md	
@@ -52,3 +52,31 @@ $ echo "debugger;" > src/index.js && vite run lint
 Found 1 warning and 0 errors.
 ✓ Finished in 114ms on 3192 files with 88 rules using 10 threads.
 ```
+
+## Running Tasks
+
+### Single Package
+
+Run a task in the current package:
+
+```bash
+vite run <task_name>
+```
+
+This executes the task defined in `vite-task.json` or `package.json` in the current directory.
+
+### Monorepo
+
+Target a specific package:
+
+```bash
+vite run <package_name>#<task_name>
+```
+
+Run a task across all packages:
+
+```bash
+vite run -r <task_name>
+```
+
+The `-r` (recursive) flag executes the task in all packages in topological order based on dependencies. This means if package A depends on package B, the task in B will run before the task in A.
diff --git a/docs/2 - Defining Tasks.md b/docs/2 - Defining Tasks.md
index 15716014..45e424aa 100644
--- a/docs/2 - Defining Tasks.md	
+++ b/docs/2 - Defining Tasks.md	
@@ -30,8 +30,8 @@ Configurable fields for each task:
 
 - `command` (string): The command to execute for the task.
 - `cwd` (string, optional): The working directory to run the command in. Defaults to the directory containing the `vite-task.json` file.
-- `dependsOn` (array of strings, optional): A list of other tasks that this task depends on. See [Task Orchestration](4%20-%20Task%20Orchestration) for details.
-- `cache`, `envs`, `passthroughEnvs`, `inputs`, `outputs`: see [Configuring Cache](5%20-%20Configuring%20Cache.md) for details.
+- `dependsOn` (array of strings, optional): A list of other tasks that this task depends on. See [Task Orchestration](3%20-%20Task%20Orchestration.md) for details.
+- `cache`, `envs`, `passthroughEnvs`, `inputs`, `outputs`: see [Configuring Cache](4%20-%20Configuring%20Cache.md) for details.
 
 ## Configuration Merging
 
diff --git a/docs/3 - CLI Options.md b/docs/3 - CLI Options.md
deleted file mode 100644
index 3eac1c56..00000000
--- a/docs/3 - CLI Options.md	
+++ /dev/null
@@ -1,5 +0,0 @@
-# CLI Options
-
-- `vite run <task_name>`: Executes the specified task defined in `vite-task.json` or `package.json` in the current package.
-- `vite run <package_name>#<task_name>`: Executes the specified task in the given package within a monorepo.
-- `vite run -r <task_name>`: Executes the task with the specified name across all packages in a monorepo, in topological order based on dependencies.
diff --git a/docs/4 - Task Orchestration.md b/docs/3 - Task Orchestration.md
similarity index 100%
rename from docs/4 - Task Orchestration.md
rename to docs/3 - Task Orchestration.md
diff --git a/docs/5 - Configuring Cache.md b/docs/4 - Configuring Cache.md
similarity index 96%
rename from docs/5 - Configuring Cache.md
rename to docs/4 - Configuring Cache.md
index d7dc0919..0dcf140f 100644
--- a/docs/5 - Configuring Cache.md	
+++ b/docs/4 - Configuring Cache.md	
@@ -166,7 +166,7 @@ Example:
 
 ## Cache Restrictions on Compound Tasks
 
-When a task is expanded into multiple steps or nested tasks (see [Task Orchestration](4%20-%20Task%20Orchestration) for details), Vite Task only supports caching each individual step separately. The overall task cannot be cached as a whole, and trying to enable caching for such tasks will result in an error.
+When a task is expanded into multiple steps or nested tasks (see [Task Orchestration](3%20-%20Task%20Orchestration.md) for details), Vite Task only supports caching each individual step separately. The overall task cannot be cached as a whole, and trying to enable caching for such tasks will result in an error.
 
 Example:
 

From e3413dadbf4c5decea9dd068d4d5d812728c5b04 Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Sat, 15 Nov 2025 21:10:54 +0800
Subject: [PATCH 12/17] json -> jsonc

---
 docs/1 - Getting Started.md    |  8 ++++----
 docs/2 - Defining Tasks.md     |  8 ++++----
 docs/3 - Task Orchestration.md | 10 +++++-----
 docs/4 - Configuring Cache.md  | 14 +++++++-------
 4 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/docs/1 - Getting Started.md b/docs/1 - Getting Started.md
index 4594a91d..8b305a90 100644
--- a/docs/1 - Getting Started.md	
+++ b/docs/1 - Getting Started.md	
@@ -4,12 +4,12 @@ Vite is designed to work out of the box with zero configuration. Simply run `vit
 
 For example, if you have the following script defined in your `package.json`:
 
-```
+```jsonc
 // package.json
 {
-    "scripts": {
-        "lint": "vite lint"
-    }
+  "scripts": {
+    "lint": "vite lint"
+  }
 }
 ```
 
diff --git a/docs/2 - Defining Tasks.md b/docs/2 - Defining Tasks.md
index 45e424aa..45fcd6fb 100644
--- a/docs/2 - Defining Tasks.md	
+++ b/docs/2 - Defining Tasks.md	
@@ -11,7 +11,7 @@ The `vite-task.json` file lets you define tasks with more options than `package.
 
 Here is an example of a `vite-task.json` file:
 
-```json
+```jsonc
 {
   "tasks": {
     "build": {
@@ -41,7 +41,7 @@ If you want to keep your existing `package.json` scripts but also need custom co
 
 For example, the following combination of `package.json` and `vite-task.json`:
 
-```json
+```jsonc
 // package.json
 {
     "scripts": {
@@ -60,7 +60,7 @@ For example, the following combination of `package.json` and `vite-task.json`:
 
 is equivalent to:
 
-```json
+```jsonc
 // vite-task.json
 {
   "tasks": {
@@ -78,7 +78,7 @@ is equivalent to:
 
 You can provide default configurations by defining `defaults` in `vite-task.json` at the root of the workspace. **Each configuration defined in `defaults` will be applied to all tasks in the workspace with the same name**, unless a task explicitly overrides it.
 
-```json
+```jsonc
 // vite-task.json
 {
   "defaults": {
diff --git a/docs/3 - Task Orchestration.md b/docs/3 - Task Orchestration.md
index ab1cd3fd..10d0f4d7 100644
--- a/docs/3 - Task Orchestration.md	
+++ b/docs/3 - Task Orchestration.md	
@@ -10,7 +10,7 @@ You may already use `&&` in your scripts to run multiple commands in sequence. V
 
 For example:
 
-```json
+```jsonc
 // package.json
 {
   "name": "app",
@@ -62,7 +62,7 @@ dist/assets/index-CAl1KfkQ.js188.06 kB | gzip: 59.21 kB
 
 Vite Task recursively expands `vite run ...` in scripts to run nested tasks directly instead of spawning a new subprocess. This gives you a cleaner overview of all executions and avoids unnecessary overhead.
 
-```json
+```jsonc
 // package.json
 {
   "name": "monorepoRoot",
@@ -123,7 +123,7 @@ For multi-step and nested tasks to be recognized correctly, Vite Task supports a
 
 If a script contains syntax beyond these, Vite Task falls back to normal script execution with system shells. For example, the following script will not be split into multiple steps because of the `if` statement:
 
-```json
+```jsonc
 {
   "scripts": {
     "complex": "if [ -f file.txt ]; then vite lint && vite build ; fi"
@@ -145,7 +145,7 @@ If you put a `vite run ...` command inside a script with unsupported syntax, lik
 
 To make it work, you can disable caching for the outer task by adding `"cache": false` in `vite-task.json`:
 
-```json
+```jsonc
 /// vite-task.json
 {
   "tasks": {
@@ -161,7 +161,7 @@ To make it work, you can disable caching for the outer task by adding `"cache":
 
 Task dependencies can be defined in `vite-task.json` file. You can specify which tasks need to be executed before a particular task runs:
 
-```json
+```jsonc
 {
   "tasks": {
     "build": {
diff --git a/docs/4 - Configuring Cache.md b/docs/4 - Configuring Cache.md
index 0dcf140f..cd436a22 100644
--- a/docs/4 - Configuring Cache.md	
+++ b/docs/4 - Configuring Cache.md	
@@ -2,7 +2,7 @@
 
 Fields `cache`, `envs`, `passthroughEnvs`, `inputs`, and `outputs` in `vite-task.json` can be used to configure caching behavior for tasks. All of them are optional. The default values are:
 
-```json
+```jsonc
 {
   "cache": true,
   "envs": [],
@@ -28,7 +28,7 @@ Caching is automatically disabled for tasks that fail or receive user input from
 
 Here are some scenarios where you may want to disable caching explicitly:
 
-```json
+```jsonc
 // vite-task.json
 {
   "tasks": {
@@ -67,7 +67,7 @@ By default, no environment variables are included in the cache fingerprint, and
 
 Example:
 
-```json
+```jsonc
 // vite-task.json
 {
   "tasks": {
@@ -92,7 +92,7 @@ Example:
 
 Example:
 
-```json
+```jsonc
 // vite-task.json
 {
   "tasks": {
@@ -119,7 +119,7 @@ Example:
 
 Example:
 
-```json
+```jsonc
 // vite-task.json
 {
   "tasks": {
@@ -147,7 +147,7 @@ Vite Task cannot infer idempotency automatically for third-party tools, so you c
 
 Example:
 
-```json
+```jsonc
 // vite-task.json
 {
   "tasks": {
@@ -170,7 +170,7 @@ When a task is expanded into multiple steps or nested tasks (see [Task Orchestra
 
 Example:
 
-```json
+```jsonc
 // vite-task.json
 {
   "tasks": {

From 50de74603148307b7265863e5f484e50b8a71b4a Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Sat, 15 Nov 2025 21:12:40 +0800
Subject: [PATCH 13/17] fix typo

---
 docs/2 - Defining Tasks.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/2 - Defining Tasks.md b/docs/2 - Defining Tasks.md
index 45fcd6fb..6f7a310c 100644
--- a/docs/2 - Defining Tasks.md	
+++ b/docs/2 - Defining Tasks.md	
@@ -51,7 +51,7 @@ For example, the following combination of `package.json` and `vite-task.json`:
 // vite-task.json
 {
     "tasks": {
-        "type-check": {
+        "build": {
             "envs": ["NODE_ENV"]
         }
     }

From a1d46564af3c15de10e32886afb528044aae2b85 Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Sat, 15 Nov 2025 21:18:54 +0800
Subject: [PATCH 14/17] Fix documentation inconsistencies
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Change "script" to "command" in Task Orchestration example for consistency
- Fix "inputs" to "outputs" in Configuring Cache example to match the comment about saving dist files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/3 - Task Orchestration.md | 2 +-
 docs/4 - Configuring Cache.md  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/3 - Task Orchestration.md b/docs/3 - Task Orchestration.md
index 10d0f4d7..1c5fead9 100644
--- a/docs/3 - Task Orchestration.md	
+++ b/docs/3 - Task Orchestration.md	
@@ -169,7 +169,7 @@ Task dependencies can be defined in `vite-task.json` file. You can specify which
       "dependsOn": ["lint", "ui#test", "^build"]
     },
     "lint": {
-      "script": "vite lint"
+      "command": "vite lint"
     }
   }
 }
diff --git a/docs/4 - Configuring Cache.md b/docs/4 - Configuring Cache.md
index cd436a22..4799d5be 100644
--- a/docs/4 - Configuring Cache.md	
+++ b/docs/4 - Configuring Cache.md	
@@ -127,7 +127,7 @@ Example:
       "command": "webpack",
       // Saving files in folder "dist" in cache,
       // and restoring them when cache is hit.
-      "inputs": [
+      "outputs": [
         "dist/**"
       ]
     }

From e69f3e7401ce0fbb7da3b57a782b8068e3a38545 Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Sat, 15 Nov 2025 21:20:29 +0800
Subject: [PATCH 15/17] update tui example

---
 docs/3 - Task Orchestration.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs/3 - Task Orchestration.md b/docs/3 - Task Orchestration.md
index 1c5fead9..2a14cb12 100644
--- a/docs/3 - Task Orchestration.md	
+++ b/docs/3 - Task Orchestration.md	
@@ -98,12 +98,10 @@ Vite Task will show:
       </td>
       <td>
       <pre>
-$ vite lint
+$ dprint fmt
 
 <small>(cache hit, replaying)</small><br />
-VITE+ v1.0.0 lint
-Found 0 warnings and 0 errors.
-✓ Finished in 1ms on 3 files with 88 rules using 10 threads.
+Formatted 3 files.
 </pre>
 
 </td>

From b6777419a0fb92878ef1bf494539c923f1eb1904 Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Sat, 15 Nov 2025 21:22:31 +0800
Subject: [PATCH 16/17] update docs

---
 docs/4 - Configuring Cache.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/4 - Configuring Cache.md b/docs/4 - Configuring Cache.md
index 4799d5be..b367b837 100644
--- a/docs/4 - Configuring Cache.md	
+++ b/docs/4 - Configuring Cache.md	
@@ -22,9 +22,9 @@ Fields `cache`, `envs`, `passthroughEnvs`, `inputs`, and `outputs` in `vite-task
 
 Caching is enabled by default, so scripts in `package.json` are cached unless explicitly disabled.
 
-Caching is automatically disabled for tasks that fail or receive user input from stdin (such as prompts or `Ctrl-C`), so it's generally safe to enable caching for long-running tasks like dev servers.
+Caching is automatically disabled for tasks that fail or receive user input from stdin (such as prompts or `Ctrl-C`), so it's generally safe to enable caching for long-running tasks like dev servers, because they won't be cached anyway when they exit on `Ctrl-C`.
 
-> If cache is disabled, all the other cache-related configurations are irrelevant.
+> If cache is disabled, all the other fields mentioned in this pages are irrelevant.
 
 Here are some scenarios where you may want to disable caching explicitly:
 

From 4e706a6007e03ee8a344bc7cbf676d8604d58d29 Mon Sep 17 00:00:00 2001
From: branchseer <dk4rest@gmail.com>
Date: Sat, 15 Nov 2025 21:35:55 +0800
Subject: [PATCH 17/17] update

---
 docs/2 - Defining Tasks.md    | 2 +-
 docs/4 - Configuring Cache.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/2 - Defining Tasks.md b/docs/2 - Defining Tasks.md
index 6f7a310c..aad410e5 100644
--- a/docs/2 - Defining Tasks.md	
+++ b/docs/2 - Defining Tasks.md	
@@ -7,7 +7,7 @@ There are two ways to define tasks in Vite Task:
 
 ## `vite-task.json`
 
-The `vite-task.json` file lets you define tasks with more options than `package.json` scripts. **Place it in the root of a package alongside `package.json` to define tasks for that package.**
+The `vite-task.json` file lets you define tasks with more options than `package.json` scripts. It should be placed in the root of any package alongside `package.json` to define tasks for that package.
 
 Here is an example of a `vite-task.json` file:
 
diff --git a/docs/4 - Configuring Cache.md b/docs/4 - Configuring Cache.md
index b367b837..288c0e2c 100644
--- a/docs/4 - Configuring Cache.md	
+++ b/docs/4 - Configuring Cache.md	
@@ -115,7 +115,7 @@ Example:
 
 > stdout and stderr are always cached regardless of this setting.
 
-> `outputs` for `vite build` are automatically configured without explicit settings.
+> `outputs` for `vite build` are automatically configured without the need for manual setup.
 
 Example: