diff --git a/docs/1 - Getting Started.md b/docs/1 - Getting Started.md
new file mode 100644
index 00000000..8b305a90
--- /dev/null
+++ b/docs/1 - Getting Started.md	
@@ -0,0 +1,82 @@
+# 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`:
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "lint": "vite lint"
+  }
+}
+```
+
+The first time you run `vite run lint`, Vite Task will execute it just like `npm run lint`:
+
+```
+$ vite run lint
+
+> vite lint
+
+Found 0 warnings and 0 errors.
+✓ Finished in 103ms on 3192 files with 88 rules using 10 threads.
+```
+
+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
+
+> vite lint (cache hit, replaying)
+
+Found 0 warnings and 0 errors.
+✓ Finished in 103ms on 3192 files with 88 rules using 10 threads.
+```
+
+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
+
+> 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.
+```
+
+## 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
new file mode 100644
index 00000000..aad410e5
--- /dev/null
+++ b/docs/2 - Defining Tasks.md	
@@ -0,0 +1,93 @@
+# 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.
+
+## `vite-task.json`
+
+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:
+
+```jsonc
+{
+  "tasks": {
+    "build": {
+      "command": "webpack",
+      "envs": ["NODE_ENV"]
+    },
+    "test": {
+      "command": "vite lint",
+      "cwd": "./src"
+    }
+  }
+}
+```
+
+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](3%20-%20Task%20Orchestration.md) for details.
+- `cache`, `envs`, `passthroughEnvs`, `inputs`, `outputs`: see [Configuring Cache](4%20-%20Configuring%20Cache.md) for details.
+
+## Configuration Merging
+
+### Merging with `package.json` Scripts
+
+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`:
+
+```jsonc
+// package.json
+{
+    "scripts": {
+        "build": "webpack",
+    }
+}
+// vite-task.json
+{
+    "tasks": {
+        "build": {
+            "envs": ["NODE_ENV"]
+        }
+    }
+}
+```
+
+is equivalent to:
+
+```jsonc
+// vite-task.json
+{
+  "tasks": {
+    "build": {
+      "command": "webpack",
+      "envs": ["NODE_ENV"]
+    }
+  }
+}
+```
+
+> 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` 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.
+
+```jsonc
+// vite-task.json
+{
+  "defaults": {
+    "build": {
+      // Disable caching for all tasks named "build"
+      "cache": false
+    }
+  }
+}
+```
+
+> 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/3 - Task Orchestration.md b/docs/3 - Task Orchestration.md
new file mode 100644
index 00000000..2a14cb12
--- /dev/null
+++ b/docs/3 - Task Orchestration.md	
@@ -0,0 +1,178 @@
+# Task Orchestration
+
+## Composing Tasks Inside Scripts
+
+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 already use `&&` in your scripts to run multiple commands in sequence. Vite Task recognizes this pattern and caches each step individually.
+
+For example:
+
+```jsonc
+// 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.
+
+<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
+
+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.
+
+```jsonc
+// package.json
+{
+  "name": "monorepoRoot",
+  "scripts": {
+    "ready": "vite run format && vite run -r build",
+    "format": "dprint fmt && vite fmt"
+  }
+}
+```
+
+Vite Task will show:
+
+<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>
+$ dprint fmt
+
+<small>(cache hit, replaying)</small><br />
+Formatted 3 files.
+</pre>
+
+</td>
+</tr>
+
+</tbody>
+</table>
+
+### Supported 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 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:
+
+```jsonc
+{
+  "scripts": {
+    "complex": "if [ -f file.txt ]; then vite lint && vite build ; fi"
+  }
+}
+```
+
+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 caching both `build` tasks and `complex` as a single unit is not currently supported.
+
+```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`:
+
+```jsonc
+/// vite-task.json
+{
+  "tasks": {
+    "complex": {
+      "cache": false,
+      "command": "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:
+
+```jsonc
+{
+  "tasks": {
+    "build": {
+      "command": "vite build",
+      "dependsOn": ["lint", "ui#test", "^build"]
+    },
+    "lint": {
+      "command": "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/4 - Configuring Cache.md b/docs/4 - Configuring Cache.md
new file mode 100644
index 00000000..288c0e2c
--- /dev/null
+++ b/docs/4 - Configuring Cache.md	
@@ -0,0 +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:
+
+```jsonc
+{
+  "cache": true,
+  "envs": [],
+  "passthroughEnvs": [
+    "PATH",
+    "HOME" /* ... */
+  ],
+  "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`)
+
+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, because they won't be cached anyway when they exit on `Ctrl-C`.
+
+> 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:
+
+```jsonc
+// 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 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 variables that are necessary for the task to run but should not affect caching, such as `PATH` and `HOME`.
+
+Example:
+
+```jsonc
+// 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 task 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 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:
+
+```jsonc
+// 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 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 for manual setup.
+
+Example:
+
+```jsonc
+// vite-task.json
+{
+  "tasks": {
+    "build": {
+      "command": "webpack",
+      // Saving files in folder "dist" in cache,
+      // and restoring them when cache is hit.
+      "outputs": [
+        "dist/**"
+      ]
+    }
+  }
+}
+```
+
+### `idempotent` (boolean, default: `false`)
+
+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 files after the first run.
+
+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.
+
+Example:
+
+```jsonc
+// vite-task.json
+{
+  "tasks": {
+    // Formatters and autofix linters 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](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:
+
+```jsonc
+// 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 is already cached separately.
+      "cache": true
+    }
+  }
+}
+```