docs: add Task Runner user documentation

docs/.vitepress/config.mts

@@ -71,7 +71,7 @@ export default extendConfig(
             { text: 'Test', link: '/config/test' },
             { text: 'Lint', link: '/config/lint' },
             { text: 'Format', link: '/config/format' },
-            { text: 'Task Runner', link: '/config/task' },
+            { text: 'Task Runner', link: '/vite/guide/task/config' },
             { text: 'Package Manager', link: '/config/package-manager' },
           ],
         },
@@ -327,40 +327,20 @@ export default extendConfig(
                   link: 'task/getting-started',
                 },
                 {
-                  text: 'Features',
-                  link: '/guide/task/features',
-                },
-                {
-                  text: 'CLI',
-                  link: '/guide/task/cli',
-                },
-                {
-                  text: 'Migration from Turborepo',
-                  link: '/guide/format/migration-from-turborepo',
-                },
-                {
-                  text: 'Migration from Nx',
-                  link: '/guide/format/migration-from-nx',
-                },
-                {
-                  text: 'Migration from Lerna',
-                  link: '/guide/format/migration-from-lerna',
+                  text: 'Running Tasks',
+                  link: 'task/running-tasks',
                 },
                 {
-                  text: 'Migration from pnpm',
-                  link: '/guide/format/migration-from-pnpm',
+                  text: 'Caching',
+                  link: 'task/caching',
                 },
                 {
-                  text: 'Migration from yarn',
-                  link: '/guide/format/migration-from-yarn',
-                },
-                {
-                  text: 'Migration from npm',
-                  link: '/guide/format/migration-from-npm',
+                  text: 'CLI',
+                  link: 'task/cli',
                 },
                 {
-                  text: 'Migration from bun',
-                  link: '/guide/format/migration-from-bun',
+                  text: 'Config',
+                  link: 'task/config',
                 },
               ],
             },
@@ -604,6 +584,15 @@ export default extendConfig(
               },
             ],
           },
+          {
+            text: 'Task Runner',
+            items: [
+              {
+                text: 'Configuring Task Runner',
+                link: '/vite/guide/task/config',
+              },
+            ],
+          },
         ],
         '/apis/': [
           {

docs/vite/guide/task/caching.md

@@ -0,0 +1,115 @@
+# Caching
+
+## How It Works {#how-caching-works}
+
+When a task runs successfully (exit code 0), its terminal output (stdout/stderr) is saved. On the next run, the task runner checks if anything changed:
+
+1. **Arguments** — did the [additional arguments](./cli#additional-arguments) passed to the task change?
+2. **Environment variables** — did any [fingerprinted env vars](./config#envs) change?
+3. **Input files** — did any file that the command reads change?
+
+If everything matches, the cached output is replayed instantly — the command never actually runs.
+
+::: info
+Currently, only terminal output is cached and replayed. Output files (e.g., `dist/`) are not cached — if you delete them, use `--no-cache` to force a re-run. Output file caching is planned for a future release.
+:::
+
+When a cache miss occurs, the task runner tells you exactly why:
+
+```
+$ vp lint ✗ cache miss: 'src/utils.ts' modified, executing
+$ vp build ✗ cache miss: envs changed, executing
+$ vp test ✗ cache miss: args changed, executing
+```
+
+## When Is Caching Enabled? {#when-is-caching-enabled}
+
+A command run by `vp run` is either a **task** (has an entry in `vite.config.ts`) or a **script** (only exists in `package.json` with no corresponding task entry). By default, **tasks are cached and scripts are not.** Three layers control whether caching is on:
+
+### 1. Per-task `cache: false` (highest priority, tasks only)
+
+A task can set [`cache: false`](./config#cache) to opt out. This cannot be overridden by `--cache` or `run.cache` — if a task says no caching, it means no caching.
+
+### 2. CLI flags
+
+`--no-cache` disables caching for everything. `--cache` enables caching for both tasks and scripts — equivalent to setting [`run.cache: true`](./config#run-cache) for that invocation.
+
+### 3. Workspace config
+
+The [`run.cache`](./config#run-cache) option in your root `vite.config.ts` controls the default for each category:
+
+| Setting         | Default | Effect                                |
+| --------------- | ------- | ------------------------------------- |
+| `cache.tasks`   | `true`  | Cache commands that have a task entry |
+| `cache.scripts` | `false` | Cache plain `package.json` scripts    |
+
+Use `--cache` to quickly enable script caching, or set `run.cache.scripts: true` in config to enable it permanently.
+
+## Automatic File Tracking {#automatic-file-tracking}
+
+By default, the task runner tracks which files each command reads during execution. When `vp build` runs, it records which files the process opens — your `.ts` source files, `vite.config.ts`, `package.json`, etc. — and records their content hashes. On the next run, it re-checks those hashes to determine if anything changed.
+
+This means caching works out of the box for most commands without any configuration. The tracker also records:
+
+- **File non-existence** — if a command probes for a file that doesn't exist (e.g., `utils.ts` during module resolution), creating that file later correctly invalidates the cache.
+- **Directory listings** — if a command scans a directory (e.g., a test runner looking for `*.test.ts`), adding or removing files in that directory invalidates the cache.
+
+### Over-fingerprinting {#over-fingerprinting}
+
+Automatic tracking can sometimes include more files than necessary, causing unnecessary cache misses:
+
+- **Tool cache files** — some tools maintain their own cache (e.g., TypeScript's `.tsbuildinfo`, Cargo's `target/`). These files may change between runs even when your source code hasn't, causing unnecessary cache invalidation.
+- **Directory listings** — when a command scans a directory (e.g., globbing for `**/*.js`), the task runner sees the directory read but not the glob pattern. Any file added or removed in that directory — even unrelated ones — invalidates the cache.
+
+Use the [`inputs`](./config#inputs) option to exclude noisy files or replace automatic tracking with explicit file patterns:
+
+```ts
+tasks: {
+  build: {
+    command: 'tsc',
+    inputs: [{ auto: true }, '!**/*.tsbuildinfo'],
+  },
+}
+```
+
+## Environment Variables {#environment-variables}
+
+By default, tasks run in a clean environment — only a small set of common variables (like `PATH`, `HOME`, `CI`) are passed through. Other environment variables are neither visible to the task nor included in the cache fingerprint.
+
+To make a variable affect caching, add it to [`envs`](./config#envs). Changing its value invalidates the cache:
+
+```ts
+tasks: {
+  build: {
+    command: 'webpack --mode production',
+    envs: ['NODE_ENV'],
+  },
+}
+```
+
+To pass a variable to the task **without** affecting the cache, use [`passThroughEnvs`](./config#pass-through-envs). This is useful for variables like `CI` or `GITHUB_ACTIONS` that should be available but shouldn't trigger a rebuild when they change.
+
+See the [config reference](./config#envs) for details on wildcard patterns and the full list of automatically passed-through variables.
+
+## Cache Sharing {#cache-sharing}
+
+The cache is content-based — if two tasks run the same command with the same inputs, they share the cache entry. This happens naturally when multiple tasks include a common step, either as standalone tasks or as parts of [compound commands](./running-tasks#compound-commands):
+
+```json [package.json]
+{
+  "scripts": {
+    "check": "vp lint && vp build",
+    "release": "vp lint && deploy-script"
+  }
+}
+```
+
+With caching enabled (e.g. `--cache` or [`run.cache.scripts: true`](./config#run-cache)), running `check` first means the `vp lint` step in `release` is an instant cache hit, since both run the same command against the same files.
+
+## Clearing the Cache {#clearing-the-cache}
+
+```bash
+vp cache clean
+```
+
+This deletes the entire cache directory. Tasks will run fresh on the next invocation.

docs/vite/guide/task/cli.md

@@ -0,0 +1,73 @@
+# CLI Reference
+
+## `vp run` {#vp-run}
+
+Run tasks defined in `vite.config.ts` or `package.json` scripts.
+
+```bash
+vp run [options] [task] [additional-args]
+```
+
+If `task` is omitted, an interactive selector is shown:
+
+```
+Select a task (↑/↓, Enter to run, Esc to clear):
+
+  › build: vp build
+    lint: vp lint
+```
+
+### Task Argument {#task-argument}
+
+The `[task]` argument can be:
+
+- `build` — runs the `build` task in the current package
+- `@my/app#build` — runs the `build` task in a specific package
+
+### Options {#options}
+
+| Flag                  | Short | Description                                                |
+| --------------------- | ----- | ---------------------------------------------------------- |
+| `--recursive`         | `-r`  | Run in all workspace packages, in topological order        |
+| `--transitive`        | `-t`  | Run in the current package and its transitive dependencies |
+| `--workspace-root`    | `-w`  | Run in the workspace root package                          |
+| `--filter <pattern>`  | `-F`  | Select packages by name, directory, or glob (repeatable)   |
+| `--cache`             | —     | Enable caching for all tasks and scripts                   |
+| `--no-cache`          | —     | Disable caching entirely                                   |
+| `--ignore-depends-on` | —     | Skip explicit `dependsOn` dependencies                     |
+| `--verbose`           | `-v`  | Show detailed execution summary                            |
+| `--last-details`      | —     | Display the summary from the last run                      |
+
+### Additional Arguments {#additional-arguments}
+
+Arguments after the task name are passed through to the task command:
+
+```bash
+vp run test --reporter verbose
+```
+
+### Filter Patterns {#filter-patterns}
+
+| Pattern            | Description                                |
+| ------------------ | ------------------------------------------ |
+| `@my/app`          | Exact package name                         |
+| `@my/*`            | Glob matching                              |
+| `./packages/app`   | By directory                               |
+| `{./packages/app}` | By directory (braced form)                 |
+| `@my/app...`       | Package and its dependencies               |
+| `...@my/core`      | Package and its dependents                 |
+| `@my/app^...`      | Dependencies only (exclude package itself) |
+| `...^@my/core`     | Dependents only (exclude package itself)   |
+| `!@my/utils`       | Exclude a package                          |
+
+Multiple `--filter` flags are combined as a union. Exclusion filters (`!`) are applied after all inclusions.
+
+## `vp cache clean` {#vp-cache-clean}
+
+Delete all cached task results:
+
+```bash
+vp cache clean
+```
+
+Tasks will run fresh on the next invocation.