@vzn/vx 0.0.638 → 0.0.640

package/docs/schema.md

@@ -87,7 +87,7 @@ absent, which is what a conditional spread
 held to this: its plugins are objects of functions.
 
 `tasks` is a `Record<string, TaskConfig>`. Task names are strings
-referenced by `dependsOn`, by `cache.inputs.tasks`, and by the CLI
+referenced by `dependsOn`, by `inputs.tasks`, and by the CLI
 (`vx run <taskName>` or `vx run <pkg>#<taskName>`), so a name those
 could not spell is refused at load: an empty one, one with surrounding
 whitespace, one holding `#` (the project separator) or `*` (a pattern),
@@ -109,12 +109,13 @@ interface TaskConfig {
   description?: string // one-line blurb for the picker / --dry view
   exec?: ExecConfig // omit to declare a group task
   dependsOn?: readonly string[] // Turbo/Nx micro-syntax
-  cache?: CacheConfig // caching is opt-in; on a group, a key with no outputs
+  inputs?: InputsConfig // what the task reads: its key, cached or not
+  cache?: CacheConfig // caching is opt-in; needs `exec` and `inputs`
 }
 ```
 
 A task either has an `exec` (it does work) or omits `exec` and declares
-`dependsOn` or `cache` (it's a **group task**: an aggregator, or a key).
+`dependsOn` or `inputs` (it's a **group task**: an aggregator, or a key).
 The loader rejects a task that has none of them — a no-op standalone
 task is almost always a config mistake. `dependsOn: []` is the deliberate form: an
 explicit empty group, for a package that wants a task by that name to
@@ -122,7 +123,7 @@ exist and do nothing.
 
 A project whose config and plugins declare no `build` gets one (owner,
 2026-10-04): a group with `dependsOn: ['^build']` keyed on every file of
-the project (`cache.inputs.files: ['**']`, no outputs). It runs nothing,
+the project (`inputs.files: ['**']`, no outputs). It runs nothing,
 but a dependant behind `^build` folds its key, so a package consumed as
 source moves its dependants' keys and reaches them under `--affected`.
 A config can declare a keyed group too (Group tasks, below). A
@@ -156,8 +157,8 @@ places:
 test: {
   description: 'bun test against the tests/ tree',
   exec: { command: 'bun test' },
+  inputs: { files: ['src/**', 'tests/**'] },
   cache: {
-    inputs: { files: ['src/**', 'tests/**'] },
     outputs: { files: [] },
   },
 }
@@ -319,7 +320,7 @@ daemon, a Docker socket, a device, a VPN-only host.
   declares — a worker cannot reach a port served on the submitter. So is
   a task with a `sandbox` block, and its dependants: the sandbox is this
   machine's machinery, and a boundary a worker does not enforce would
-  pass vacuously. So is a task whose key folds `cache.inputs.runtime` or
+  pass vacuously. So is a task whose key folds `inputs.runtime` or
   `workspaceRuntime`: the key holds this machine's answer, which a worker
   cannot prove it shares. Its dependants are not pinned.
 - **Placement is decided once per task**, before scheduling, so the
@@ -341,8 +342,8 @@ daemon, a Docker socket, a device, a VPN-only host.
   ```ts
   install: {
     exec: { command: 'pnpm install --frozen-lockfile', remote: 'only' },
+    inputs: { files: ['package.json', 'pnpm-lock.yaml'] },
     cache: {
-      inputs: { files: ['package.json', 'pnpm-lock.yaml'] },
       outputs: { files: ['node_modules/**'] },
     },
   },
@@ -376,7 +377,7 @@ for it to exit. Instead it considers the task "ready":
   The trailing partial line is tested too, so prompt-style banners
   without a newline (`printf 'Listening on :3000'`) count, and so does
   output read up to 250 ms after the shell exits. A server
-  not ready after 10 s (`run.readyNotice`) is said once, naming
+  not ready after 10 s is said once, naming
   the pattern it waits for, and whether `exec.timeout` bounds the wait.
 
 ```ts
@@ -539,11 +540,11 @@ highest priority:
    build; if one does, say so explicitly:
 
    ```ts
-   cache: { inputs: { files: ['src/**'], env: ['NODE_OPTIONS'] }, outputs: { files: [] } }
+   inputs: { files: ['src/**'], env: ['NODE_OPTIONS'] }, cache: { outputs: { files: [] } }
    ```
 
    That folds its value into the key. The two axes are orthogonal on
-   purpose: `cache.inputs.env` decides what the key _sees_,
+   purpose: `inputs.env` decides what the key _sees_,
    `exec.env.passThrough` decides what the child _gets_.
 
 2. **`passThrough`** names → value taken from host `process.env` at
@@ -564,14 +565,14 @@ exec: {
 }
 ```
 
-Every name in these lists (and in `cache.inputs.env`) must be one an
+Every name in these lists (and in `inputs.env`) must be one an
 environment can hold: non-empty, with no `=` and no NUL, and a `define`
 value holds no NUL. Such a name is refused at load; it used to reach the
 child split at its `=` or not at all. A `passThrough` or `define` name is
 also a shell variable name, `[A-Za-z_][A-Za-z0-9_]*`: the task runs under
 `sh -c`, and dash (Linux's `sh`) drops any other name from the environment
 it hands the command, so `my.var` reached a task on macOS and never on
-Linux. `cache.inputs.env` takes any such name: the key reads it from vx's
+Linux. `inputs.env` takes any such name: the key reads it from vx's
 own environment.
 
 vx also sets `npm_execpath` to the workspace's package manager (the root
@@ -608,8 +609,8 @@ shows it: the task's output and the line vx adds under a shell's 127 or
 replays, the command a cache entry stores (what `vx why` prints and a
 remote cache receives), the `$ command` line, telemetry records,
 `vx show`, the hashes `vx why` gives for such a variable in
-`cache.inputs.env` (its value, unsalted: the row names it and its change), an executor's error, a plugin's warning or failure (a remote's reply; the failure masked in the error `run()` rejects with), a failed `cache.inputs` runtime probe's error (its command and output), and the run's own invocation line that `vx last` prints (a
-secret passed after `--`) and its `--tag`s. So are every string of a
+`inputs.env` (its value, unsalted: the row names it and its change), an executor's error, a plugin's warning or failure (a remote's reply; the failure masked in the error `run()` rejects with), a failed `inputs` runtime probe's error (its command and output), and the run's own invocation line that `vx last` prints (a
+secret passed after `--`). So are every string of a
 task `vx show` prints (a runtime probe, `readyWhen`, the description),
 the description `--dry` and the task picker print, a runtime probe's
 command as the run history stores it and `vx why` names its row (two
@@ -676,8 +677,8 @@ Semantics:
   edge from a `package.json`) and the cross-project `pkg#task` edges.
   With no plugin returning `deps` the workspace has no edge source and
   a `'^name'` is refused (`VX_E_DEPENDS_ON`: "`^build` needs project
-  edges; add pnpm()/bun()/npm()/yarn() or a plugin that returns
-  `deps`"): it would resolve to nothing and fold no upstream into the
+  edges; add pnpm()/bun()/npm()/yarn() and install so its lockfile
+  exists, or a plugin that returns `deps`"): it would resolve to nothing and fold no upstream into the
   key. With one, a project with no deps is a leaf; each path stops at the first dep
   that declares the task and an edge is added to it (Turbo/Nx
   direct-deps parity). The holder's own `dependsOn` is responsible
@@ -701,7 +702,7 @@ Semantics:
   nothing anywhere stays legal, as `'name.*'` does.
 - **`'pkg#name'`** — missing pkg or task is a hard error (you named
   them explicitly). `'//#name'`, Turbo's spelling of the root package,
-  names the root project (D-39) here and in `cache.inputs.tasks`; with no
+  names the root project (D-39) here and in `inputs.tasks`; with no
   root project it is refused as such.
 - **Patterns (`'name.*'` / `'^name.*'`)** — `*` matches any run of
   characters in a task NAME; everything else is literal (the dotted
@@ -714,102 +715,37 @@ Semantics:
   ALL its matches and stops the walk. Patterns are not supported in
   the `'pkg#task'` form. (Nx 19.5 `build-*` parity.)
 - **No bare wildcards or negation here.** `'*'` / `'^*'` / `'!form'`
-  belong in `cache.inputs.tasks` (filtering which upstream hashes
+  belong in `inputs.tasks` (filtering which upstream hashes
   participate in this task's cache key), not in `dependsOn` (declaring
   graph edges). The micro-syntax parser rejects them in this position.
 - **Cycle detection** runs across the resolved graph at the end of
   `buildTaskGraph`. Cycles throw with a path-formatted message.
 
-### `cache` (optional)
-
-```ts
-interface CacheConfig {
-  inputs: CacheInputs // required when `cache` is provided
-  outputs: CacheOutputs // required when `cache` is provided
-  inputStability?: InputStability // optional
-}
-
-interface InputStability {
-  strategy?: 'immutable' | 'mutable' | 'unchecked' // default 'immutable'
-  severity?: 'warn' | 'error' // default 'warn'
-}
-```
-
-`inputStability` says what a write to an input while the command runs
-means. `strategy` says which writes count:
-
-- `'immutable'` (the default, on CI too): any write. An edit undone
-  mid-run, or another task changing the file and putting it back, cannot
-  be told from no edit.
-- `'mutable'`: a file rewritten to the bytes the key folded counts as
-  unchanged, for a task that rewrites its own input identically
-  (tsdown's `package.json`); different bytes still count, and so does
-  any write while another task that may write the file was running (one
-  of the same project, or one whose sandbox grants writes elsewhere in
-  the workspace; a server `vx watch` keeps from an earlier run counts),
-  since it may have changed the file and put it back.
-  The line names that task; order the two with `dependsOn` to save.
-- `'unchecked'`: none. The entry is saved under the key taken before the
-  command, whatever the command did to its inputs; `severity` is ignored.
-  A key that no longer held before the command started still withholds
-  it.
-
-A write that counts withholds the entry, and `severity` says what else
-happens: `'warn'` (the default) keeps the result, says why on the status
-line, and the run goes on; `'error'` fails the task, so the run fails,
-and its label names the file: `failed (src/a.ts changed during the run, exit 1)`
-(`inputMoved` in `vx last --format json`).
-Either way, every task that ran over the task's outputs, down the graph,
-withholds its save too, and a task of any project that declares the
-moved file as an input withholds its own.
-
-Each field is resolved on its own, highest first:
-
-1. `VX_CACHE_INPUT_STABILITY_STRATEGY` (`immutable`, `mutable`,
-   `unchecked`) and `VX_CACHE_INPUT_STABILITY_SEVERITY` (`warn`, `error`), for the whole run
-   (a CI job that wants `error` sets it without editing configs); any
-   other value is refused before a task runs;
-2. the task's own `cache.inputStability`;
-3. the workspace's `inputStability` (`.vx/workspace.ts`);
-4. the default, `'immutable'` and `'warn'`.
-
-Never folded into a cache key.
+### `inputs` (optional)
 
 ```ts
-import { defineProject } from '@vzn/vx/config'
-
-export default defineProject({
-  tasks: {
-    build: {
-      // tsdown rewrites package.json with the same bytes on every build;
-      // different bytes fail the run rather than rebuild next time.
-      exec: { command: 'tsdown' },
-      cache: {
-        inputs: { files: ['src/**', 'package.json'] },
-        outputs: { files: ['dist/**'] },
-        inputStability: { strategy: 'mutable', severity: 'error' },
-      },
-    },
-  },
-})
+inputs?: InputsConfig
 ```
 
-**Caching is opt-in.** Omit `cache` and the task always runs (no read,
-no write). Provide it and caching is active for that task. The
-project loader requires _both_ `inputs` and `outputs` when `cache` is
-set — declaring "what does this read?" and "what does it produce?" is
-a deliberate, conscious choice.
+What the task reads, and so what its key folds. A task is keyed on its
+inputs whether it caches or not, as Turbo and Nx hash every task: a
+dependant folds that key, so an edit to an uncached generator's inputs
+re-runs the cached task behind it. A group with `inputs` is a keyed
+group (Group tasks, below). The default `build` is
+`{ dependsOn: ['^build'], inputs: { files: ['**'] } }`.
 
-**Why opt-in?** Defaulting caching to ON with implicit "all files / no
-outputs" silently produces stale builds the moment a user forgets
-to revisit the config. The cost of a single forgotten cache miss
-(re-run a task) is much less than the cost of a stale cache hit
-(ship broken artifacts).
+A task that runs a command and declares no `inputs` has no key: nothing
+says what it read. A key that folds it is this run's alone, so every
+task behind it misses and saves nothing, never a stale hit. Declare
+`inputs` on an uncached task a cached one depends on;
+`inputs: { files: [] }` is a declaration too: it keys the task on its
+config and its dependencies' keys, and a task behind it can hit. An
+absent `inputs` and an empty one differ.
 
-#### `CacheInputs`
+#### `InputsConfig`
 
 ```ts
-interface CacheInputs {
+interface InputsConfig {
   files: readonly string[] // required
   workspaceFiles?: readonly string[] // optional; workspace-root-relative
   env?: readonly string[] // optional
@@ -880,7 +816,18 @@ lockfile change when a lockfile plugin (`@vzn/vx-lockfile`) is declared.
 
 Always applied to every glob pass (regardless of what you wrote):
 
-- **gitignore filter** — workspace-root + project `.gitignore`.
+- **gitignore filter** — workspace-root + project `.gitignore`, unless
+  an entry names the ignored path outright: a literal (`.env.local`), or
+  a glob whose fixed prefix git ignores (`dist/**`, `dist/*.js`,
+  `.cache/gen/**`), which is then walked on disk under that prefix only.
+  Such a file is hashed from disk and never stored or restored; a
+  missing one is not an input until it exists. A broad glob (`**`,
+  `src/**` over a listed `src`) still skips ignored files, so
+  `node_modules` is never walked, and an install stays out either way.
+  Its bytes differ per machine, so machines with different files miss
+  each other's shared entries. An ignored file never selects a task
+  under `--affected` on its own, as in Nx (only what git sees does); `vx
+watch` re-runs it on an edit there.
 - **Always-ignored** — `.git/**`, `.vx/cache/**`,
   `.vx/projects.lock.json`, `vx.lock.json`, `*.bun-build`, and Bun's cross-compile extraction
   directory `.<16 hex>-<8 hex>.tmp/**`, and vx's own restore temp
@@ -892,8 +839,10 @@ Always applied to every glob pass (regardless of what you wrote):
   itself via its own output. A path an output `!` entry takes back is
   no output, so it stays an input (A-44). Another task's outputs are
   not excluded for you: an input glob that can match them is refused
-  while `rules.upfrontKeys` is on (X-54). Write the exclusion,
-  `['**/*', '!dist/**']`. An input entry the task's OWN outputs take
+  (X-54), unless git ignores them whole, or the producer is a
+  dependency the key does not fold (see Inputs over outputs in §
+  Settings). Write the exclusion,
+  `['**/*', '!dist/**']`, or ignore `dist/`. An input entry the task's OWN outputs take
   back whole is always refused (X-55): vx removes outputs before a run,
   so a formatter declaring `src/**` as both would delete its sources. A
   task that rewrites files in place declares no outputs.
@@ -908,8 +857,9 @@ Workspace-root-relative globs — the Turbo `$TURBO_ROOT$` / Nx
 `{workspaceRoot}` equivalent, for inputs that live outside the project
 dir (a root `tsconfig.base.json`, shared codegen output, …). Same
 syntax as `files` (`!` negation subtracts, in any order), same git-aware
-resolution (tracked + untracked-not-ignored; gitignored files are
-invisible), and the resolved paths join the same cache-key file list.
+resolution (tracked + untracked-not-ignored; a gitignored file only when
+named outright, as in `files`), and the resolved paths join the same
+cache-key file list.
 
 ```ts
 inputs: {
@@ -1133,6 +1083,92 @@ task's outputs. Typical case: an integration-test task `dependsOn`s
 `build` for ordering, but its inputs are only the test source — so
 `inputs.tasks: []` to keep `build` from invalidating it.
 
+### `cache` (optional)
+
+```ts
+interface CacheConfig {
+  outputs: CacheOutputs // required when `cache` is provided
+  inputStability?: InputStability // optional
+}
+
+interface InputStability {
+  strategy?: 'immutable' | 'mutable' | 'unchecked' // default 'immutable'
+  severity?: 'warn' | 'error' // default 'warn'
+}
+```
+
+`inputStability` says what a write to an input while the command runs
+means. `strategy` says which writes count:
+
+- `'immutable'` (the default, on CI too): any write. An edit undone
+  mid-run, or another task changing the file and putting it back, cannot
+  be told from no edit.
+- `'mutable'`: a file rewritten to the bytes the key folded counts as
+  unchanged, for a task that rewrites its own input identically
+  (tsdown's `package.json`); different bytes still count, and so does
+  any write while another task that may write the file was running (one
+  of the same project, or one whose sandbox grants writes elsewhere in
+  the workspace; a server `vx watch` keeps from an earlier run counts),
+  since it may have changed the file and put it back.
+  The line names that task; order the two with `dependsOn` to save.
+- `'unchecked'`: none. The entry is saved under the key taken before the
+  command, whatever the command did to its inputs; `severity` is ignored.
+  A key that no longer held before the command started still withholds
+  it.
+
+A write that counts withholds the entry, and `severity` says what else
+happens: `'warn'` (the default) keeps the result, says why on the status
+line, and the run goes on; `'error'` fails the task, so the run fails,
+and its label names the file: `failed (src/a.ts changed during the run, exit 1)`
+(`inputMoved` in `vx last --format json`).
+Either way, every task that ran over the task's outputs, down the graph,
+withholds its save too, and a task of any project that declares the
+moved file as an input withholds its own.
+
+Each field is resolved on its own, highest first:
+
+1. `VX_CACHE_INPUT_STABILITY_STRATEGY` (`immutable`, `mutable`,
+   `unchecked`) and `VX_CACHE_INPUT_STABILITY_SEVERITY` (`warn`, `error`), for the whole run
+   (a CI job that wants `error` sets it without editing configs); any
+   other value is refused before a task runs;
+2. the task's own `cache.inputStability`;
+3. the workspace's `inputStability` (`.vx/workspace.ts`);
+4. the default, `'immutable'` and `'warn'`.
+
+Never folded into a cache key.
+
+```ts
+import { defineProject } from '@vzn/vx/config'
+
+export default defineProject({
+  tasks: {
+    build: {
+      // tsdown rewrites package.json with the same bytes on every build;
+      // different bytes fail the run rather than rebuild next time.
+      exec: { command: 'tsdown' },
+      inputs: { files: ['src/**', 'package.json'] },
+      cache: {
+        outputs: { files: ['dist/**'] },
+        inputStability: { strategy: 'mutable', severity: 'error' },
+      },
+    },
+  },
+})
+```
+
+**Caching is opt-in.** Omit `cache` and the task always runs (no read,
+no write). Provide it and caching is active for that task. The
+project loader requires `exec`, the task's `inputs` and `cache.outputs`
+when `cache` is set: declaring "what does this read?" and "what does
+it produce?" is a deliberate, conscious choice, and a task with no
+command produces nothing to cache.
+
+**Why opt-in?** Defaulting caching to ON with implicit "all files / no
+outputs" silently produces stale builds the moment a user forgets
+to revisit the config. The cost of a single forgotten cache miss
+(re-run a task) is much less than the cost of a stale cache hit
+(ship broken artifacts).
+
 #### `CacheOutputs`
 
 ```ts
@@ -1261,7 +1297,9 @@ uses, so `dist` collides with `dist/app.js` (item 442). A whole subtree
 collides with any glob whose literal head lies inside it: `dist/**` with
 `dist/extra/**` or `dist/*.js` (item 941). Two globs a path built from
 either one matches are one too: `**/*` and `**/dist/**` both match
-`x/dist/x`. Globs that only _might_
+`x/dist/x`. A pair is no overlap where one task's `!` output entry
+takes the other's glob back whole: `['**/dist', '!types/**']` beside
+`types/**` (a `!` entry is never cleaned or captured). Globs that only _might_
 overlap (`dist/*` and `dist/sub/**`) are let through; there, last
 restore wins. A workspace output is also compared with every other
 project's `files` outputs, read from the root: `packages/b/dist/a.txt`
@@ -1468,7 +1506,7 @@ shares (L-41): `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.azure`, `~/.kube`,
 `~/.codex/auth.json`.
 What it grants from there is the union of the read grants and, on Linux,
 the DIRECTORY holding each file-shaped write grant (above).
-Nothing is inherited from `cache` — `cache.inputs` says what INVALIDATES a task, `sandbox.allow`
+Nothing is inherited from `cache` — `inputs` says what INVALIDATES a task, `sandbox.allow`
 says what it may TOUCH, and deriving one from the other made a
 declaration added for caching silently widen the sandbox. The one grant
 vx makes for you is dependencies: `node_modules` and, through it, the
@@ -1482,7 +1520,7 @@ past its `allow.read`.
 
 A task that declares `cache` gets a linked workspace package only when
 its key already answers for it: some task of that package is folded into
-the key through `dependsOn` (as `cache.inputs.tasks` selects it, groups
+the key through `dependsOn` (as `inputs.tasks` selects it, groups
 passing everything through). Every other link inside the workspace root
 is withheld, and a read through one fails the task with the denial plus
 one line naming the package and the edge that would key it. Declaring
@@ -1574,17 +1612,16 @@ dependant's `^build`, by `vx run build --all` — and runs nothing. A
 project with no `build` gets a keyed one (above), which a bare name
 does not select.
 
-A group with `cache` is a **keyed group**: its `cache.inputs` are a key
+A group with `inputs` is a **keyed group**: its `inputs` are a key
 and nothing runs. A task that depends on it folds that key, so an edit
-to those inputs re-runs the dependant, and `--affected` reaches it. Its
-`cache.outputs` must be `{ files: [] }` (a group writes nothing), and it
-needs no `dependsOn`. It spawns nothing, writes no cache entry, and the
+to those inputs re-runs the dependant, and `--affected` reaches it. It
+takes no `cache` (a group writes nothing), and it needs no `dependsOn`. It spawns nothing, writes no cache entry, and the
 run summary does not count it. `@vzn/vx-migrate` writes one for each
 Nx `^production`-style input and each Turbo transit node.
 
 ```ts
 // `test` re-runs when a file under fixtures/ changes; nothing spawns for it
-fixtures: { cache: { inputs: { files: ['fixtures/**'] }, outputs: { files: [] } } },
+fixtures: { inputs: { files: ['fixtures/**'] } },
 test: { exec: { command: 'bun test' }, dependsOn: ['fixtures'], cache: { /* … */ } },
 ```
 
@@ -1622,8 +1659,8 @@ Group tasks:
 
 The loader rejects:
 
-- A task with no `exec`, no `dependsOn` and no `cache` (literal no-op).
-- A group whose `cache.outputs` names a file (a group writes nothing).
+- A task with no `exec`, no `dependsOn` and no `inputs` (literal no-op).
+- A group with `cache` (a group writes nothing).
 
 ## Workspace config (`.vx/workspace.ts`)
 
@@ -1644,12 +1681,8 @@ export default defineWorkspace({
     affectedBase: 'origin/main',
     schedule: 'most-work',
     continue: 'deps-ok',
-    killGrace: '2s',
-    teardownTimeout: '3s',
-    readyNotice: '10s',
     rules: {
       exclusiveOutputs: true,
-      upfrontKeys: true,
       dependencies: [{ from: 'tag:lib', deny: ['tag:app'] }],
     },
   },
@@ -1661,6 +1694,7 @@ export default defineWorkspace({
     scope: 'main',
     inputStability: { strategy: 'immutable', severity: 'warn' },
     outputs: { clean: true },
+    upload: { failures: 'ci' },
   },
   lock: { reviewFiles: true },
   watch: { poll: false },
@@ -1687,36 +1721,33 @@ default and where it came from.
 
 <!-- settings table: generated by tests/settings.test.ts -->
 
-| Setting                                        | Variable                            | Flag                 | Value                                                                   | Default                                    | What it does                                                                                                                                        |
-| ---------------------------------------------- | ----------------------------------- | -------------------- | ----------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `run.concurrency`                              | `VX_RUN_CONCURRENCY`                | `--concurrency`      | a positive integer, or a share of the cores like '50%'                  | the cores this process may use             | Tasks at once: a positive integer, or a share of the cores (`'50%'`).                                                                               |
-| `run.schedule`                                 | `VX_RUN_SCHEDULE`                   | `--schedule`         | one of 'most-work', 'critical-path', 'direct-dependents', 'ready-order' | most-work                                  | Which ready task starts first when there are more than workers.                                                                                     |
-| `run.affectedBase`                             | `VX_RUN_AFFECTED_BASE`              | —                    | a non-blank string                                                      | origin/HEAD, then the trunk, else HEAD~1   | The git ref a bare `--affected` compares with.                                                                                                      |
-| `run.branch` (variable or flag only)           | `VX_RUN_BRANCH`                     | `--branch`           | a non-blank string                                                      | git's branch, then the CI provider's       | The branch a run records in its history and forecasts from. Flag and env only: a committed branch would be wrong on every other branch.             |
-| `run.timeout`                                  | `VX_RUN_TIMEOUT`                    | `--timeout`          | a duration like '500ms', '30s' or '5m', at most 24 days                 | none                                       | A task's time limit, for tasks without their own `exec.timeout` (`'30m'`). A task's own `exec.timeout` beats it.                                    |
-| `run.retries`                                  | `VX_RUN_RETRIES`                    | `--retries`          | a non-negative integer                                                  | 0                                          | Re-runs of a failed task, for tasks without their own `exec.retries`. A task's own `exec.retries` beats it.                                         |
-| `run.continue`                                 | `VX_RUN_CONTINUE`                   | `--continue`         | one of 'never', 'deps-ok', 'always'                                     | deps-ok                                    | What a failed task takes down: `never` stops the run, `deps-ok` skips its dependents, `always` runs them too.                                       |
-| `run.outputLogs` (variable or flag only)       | `VX_RUN_OUTPUT_LOGS`                | `--output-logs`      | one of 'full', 'errors-only', 'hash-only', 'none'                       | `full` on CI, else by what the run selects | Which task output the run prints. Chosen before the workspace loads, so flag and env only.                                                          |
-| `run.killGrace`                                | `VX_RUN_KILL_GRACE`                 | `--kill-grace`       | a duration like '500ms', '30s' or '5m', at most 24 days                 | 2s                                         | How long a task that ignores SIGTERM gets before SIGKILL.                                                                                           |
-| `run.teardownTimeout`                          | `VX_RUN_TEARDOWN_TIMEOUT`           | `--teardown-timeout` | a duration like '500ms', '30s' or '5m', at most 24 days                 | 3s                                         | The bound on each plugin's end-of-run flush and teardown.                                                                                           |
-| `run.readyNotice`                              | `VX_RUN_READY_NOTICE`               | `--ready-notice`     | a duration like '500ms', '30s' or '5m', at most 24 days                 | 10s                                        | How long a persistent task may take to match `readyWhen` before vx says it waits.                                                                   |
-| `run.rules.exclusiveOutputs`                   | `VX_RUN_RULES_EXCLUSIVE_OUTPUTS`    | —                    | true or false                                                           | true                                       | Refuse two tasks whose outputs overlap even when an edge orders them.                                                                               |
-| `run.rules.upfrontKeys`                        | `VX_RUN_RULES_UPFRONT_KEYS`         | —                    | true or false                                                           | true                                       | Refuse a task whose inputs can match another task's outputs.                                                                                        |
-| `cache.dir`                                    | `VX_CACHE_DIR`                      | `--cache-dir`        | a non-blank string                                                      | .vx/cache, entries in ~/.vx/<repo>/cache   | Where the cache lives, relative to the workspace root; named, it holds the whole cache.                                                             |
-| `cache.retention.maxSize`                      | `VX_CACHE_RETENTION_MAX_SIZE`       | —                    | a size like '500MB' or '10GB'                                           | none                                       | Evict least-recently-used entries at each run's end until the cache is under this (`'10GB'`).                                                       |
-| `cache.retention.olderThan`                    | `VX_CACHE_RETENTION_OLDER_THAN`     | —                    | a duration like '45s', '12h' or '30d'                                   | none                                       | Evict entries unused for this long at each run's end (`'30d'`).                                                                                     |
-| `cache.policy`                                 | `VX_CACHE_POLICY`                   | `--cache-policy`     | a non-blank string                                                      | every layer reads and writes               | Which layers a run reads and writes (`'local:rw,remote:r'`); `--no-cache` and `--force` apply on top.                                               |
-| `cache.scope`                                  | `VX_CACHE_SCOPE`                    | `--cache-scope`      | a non-blank string                                                      | none (the default keys)                    | Where cache writes land (`'pr-123'`): reads try the default key, then the scope's.                                                                  |
-| `cache.download`                               | `VX_CACHE_DOWNLOAD`                 | `--cache-download`   | one of 'all', 'toplevel', 'none'                                        | all                                        | Which remote hits land on disk: every one, only the requested tasks, or none.                                                                       |
-| `cache.inputStability.strategy`                | `VX_CACHE_INPUT_STABILITY_STRATEGY` | —                    | one of 'immutable', 'mutable', 'unchecked'                              | immutable                                  | What a write to an input during the command means for the save, for tasks without their own. A task's own `cache.inputStability.strategy` beats it. |
-| `cache.inputStability.severity`                | `VX_CACHE_INPUT_STABILITY_SEVERITY` | —                    | one of 'warn', 'error'                                                  | warn                                       | Whether a skipped save warns or fails the task, for tasks without their own. A task's own `cache.inputStability.severity` beats it.                 |
-| `cache.outputs.clean`                          | —                                   | —                    | true or false                                                           | true                                       | Remove a task's declared outputs before it runs on a miss, for tasks without their own. A task's own `cache.outputs.clean` beats it.                |
-| `lock.reviewFiles`                             | `VX_LOCK_REVIEW_FILES`              | —                    | true or false                                                           | true                                       | `vx lock` writes each project's resolved config, pretty, to `vx.lock.json` beside its `vx.config`, for review; vx never reads it.                   |
-| `watch.poll`                                   | `VX_WATCH_POLL`                     | `vx watch --poll`    | true or false                                                           | false                                      | Poll for changes from the start instead of the OS watcher.                                                                                          |
-| `config.workerTimeout` (variable or flag only) | `VX_CONFIG_WORKER_TIMEOUT`          | —                    | a duration like '500ms', '30s' or '5m', at most 24 days                 | 30s                                        | How long one config evaluation may take.                                                                                                            |
-| `debug.timing` (variable or flag only)         | `VX_DEBUG_TIMING`                   | —                    | true or false                                                           | false                                      | Print the run's stage timings to stderr.                                                                                                            |
-| `debug.watch` (variable or flag only)          | `VX_DEBUG_WATCH`                    | —                    | true or false                                                           | false                                      | `vx watch`: say on stderr each time the loop arms, with the projects it watches.                                                                    |
-| `debug.dumpable` (variable or flag only)       | `VX_DEBUG_DUMPABLE`                 | —                    | true or false                                                           | false                                      | Linux: keep vx dumpable, so strace or a debugger can read its memory and `/proc/<pid>/fd`, and an unsandboxed task its env.                         |
+| Setting                                        | Variable                            | Flag               | Value                                                                   | Default                                    | What it does                                                                                                                                        |
+| ---------------------------------------------- | ----------------------------------- | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `run.concurrency`                              | `VX_RUN_CONCURRENCY`                | `--concurrency`    | a positive integer, or a share of the cores like '50%'                  | the cores this process may use             | Tasks at once: a positive integer, or a share of the cores (`'50%'`).                                                                               |
+| `run.schedule`                                 | `VX_RUN_SCHEDULE`                   | `--schedule`       | one of 'most-work', 'critical-path', 'direct-dependents', 'ready-order' | most-work                                  | Which ready task starts first when there are more than workers.                                                                                     |
+| `run.affectedBase`                             | `VX_RUN_AFFECTED_BASE`              | —                  | a non-blank string                                                      | origin/HEAD, then the trunk, else HEAD~1   | The git ref a bare `--affected` compares with.                                                                                                      |
+| `run.branch` (variable or flag only)           | `VX_RUN_BRANCH`                     | `--branch`         | a non-blank string                                                      | git's branch, then the CI provider's       | The branch a run records in its history and forecasts from. Flag and env only: a committed branch would be wrong on every other branch.             |
+| `run.timeout`                                  | `VX_RUN_TIMEOUT`                    | `--timeout`        | a duration like '500ms', '30s' or '5m', at most 24 days                 | none                                       | A task's time limit, for tasks without their own `exec.timeout` (`'30m'`). A task's own `exec.timeout` beats it.                                    |
+| `run.retries`                                  | `VX_RUN_RETRIES`                    | `--retries`        | a non-negative integer                                                  | 0                                          | Re-runs of a failed task, for tasks without their own `exec.retries`. A task's own `exec.retries` beats it.                                         |
+| `run.continue`                                 | `VX_RUN_CONTINUE`                   | `--continue`       | one of 'never', 'deps-ok', 'always'                                     | deps-ok                                    | What a failed task takes down: `never` stops the run, `deps-ok` skips its dependents, `always` runs them too.                                       |
+| `run.outputLogs` (variable or flag only)       | `VX_RUN_OUTPUT_LOGS`                | `--output-logs`    | one of 'full', 'errors-only', 'hash-only', 'none'                       | `full` on CI, else by what the run selects | Which task output the run prints. Chosen before the workspace loads, so flag and env only.                                                          |
+| `run.rules.exclusiveOutputs`                   | `VX_RUN_RULES_EXCLUSIVE_OUTPUTS`    | —                  | true or false                                                           | true                                       | Refuse two tasks whose outputs overlap even when an edge orders them.                                                                               |
+| `cache.dir`                                    | `VX_CACHE_DIR`                      | `--cache-dir`      | a non-blank string                                                      | .vx/cache, entries in ~/.vx/<repo>/cache   | Where the cache lives, relative to the workspace root; named, it holds the whole cache.                                                             |
+| `cache.retention.maxSize`                      | `VX_CACHE_RETENTION_MAX_SIZE`       | —                  | a size like '500MB' or '10GB'                                           | none                                       | Evict least-recently-used entries at each run's end until the cache is under this (`'10GB'`).                                                       |
+| `cache.retention.olderThan`                    | `VX_CACHE_RETENTION_OLDER_THAN`     | —                  | a duration like '45s', '12h' or '30d'                                   | none                                       | Evict entries unused for this long at each run's end (`'30d'`).                                                                                     |
+| `cache.policy`                                 | `VX_CACHE_POLICY`                   | `--cache-policy`   | a non-blank string                                                      | every layer reads and writes               | Which layers a run reads and writes (`'local:rw,remote:r'`); `--no-cache` and `--force` apply on top.                                               |
+| `cache.scope`                                  | `VX_CACHE_SCOPE`                    | `--cache-scope`    | a non-blank string                                                      | none (the default keys)                    | Where cache writes land (`'pr-123'`): reads try the default key, then the scope's.                                                                  |
+| `cache.download`                               | `VX_CACHE_DOWNLOAD`                 | `--cache-download` | one of 'all', 'toplevel', 'none'                                        | all                                        | Which remote hits land on disk: every one, only the requested tasks, or none.                                                                       |
+| `cache.inputStability.strategy`                | `VX_CACHE_INPUT_STABILITY_STRATEGY` | —                  | one of 'immutable', 'mutable', 'unchecked'                              | immutable                                  | What a write to an input during the command means for the save, for tasks without their own. A task's own `cache.inputStability.strategy` beats it. |
+| `cache.inputStability.severity`                | `VX_CACHE_INPUT_STABILITY_SEVERITY` | —                  | one of 'warn', 'error'                                                  | warn                                       | Whether a skipped save warns or fails the task, for tasks without their own. A task's own `cache.inputStability.severity` beats it.                 |
+| `cache.outputs.clean`                          | —                                   | —                  | true or false                                                           | true                                       | Remove a task's declared outputs before it runs on a miss, for tasks without their own. A task's own `cache.outputs.clean` beats it.                |
+| `cache.upload.failures`                        | —                                   | —                  | one of 'ci', 'local', 'always'                                          | ci                                         | Where a failed task's log and outputs are kept in the remote: CI runs, local runs, or both.                                                         |
+| `lock.reviewFiles`                             | `VX_LOCK_REVIEW_FILES`              | —                  | true or false                                                           | true                                       | `vx lock` writes each project's resolved config, pretty, to `vx.lock.json` beside its `vx.config`, for review; vx never reads it.                   |
+| `watch.poll`                                   | `VX_WATCH_POLL`                     | `vx watch --poll`  | true or false                                                           | false                                      | Poll for changes from the start instead of the OS watcher.                                                                                          |
+| `config.workerTimeout` (variable or flag only) | `VX_CONFIG_WORKER_TIMEOUT`          | —                  | a duration like '500ms', '30s' or '5m', at most 24 days                 | 30s                                        | How long one config evaluation may take.                                                                                                            |
+| `debug.timing` (variable or flag only)         | `VX_DEBUG_TIMING`                   | —                  | true or false                                                           | false                                      | Print the run's stage timings to stderr.                                                                                                            |
+| `debug.watch` (variable or flag only)          | `VX_DEBUG_WATCH`                    | —                  | true or false                                                           | false                                      | `vx watch`: say on stderr each time the loop arms, with the projects it watches.                                                                    |
+| `debug.dumpable` (variable or flag only)       | `VX_DEBUG_DUMPABLE`                 | —                  | true or false                                                           | false                                      | Linux: keep vx dumpable, so strace or a debugger can read its memory and `/proc/<pid>/fd`, and an unsandboxed task its env.                         |
 
 <!-- /settings table -->
 
@@ -1737,11 +1768,8 @@ interface RunSettings {
   timeout?: Duration
   retries?: number
   continue?: 'never' | 'deps-ok' | 'always'
-  killGrace?: Duration
-  teardownTimeout?: Duration
-  readyNotice?: Duration
   /** Graph rules `vx lock` checks, never a run; each on unless set to false. */
-  rules?: { exclusiveOutputs?: boolean; upfrontKeys?: boolean; dependencies?: DependencyRule[] }
+  rules?: { exclusiveOutputs?: boolean; dependencies?: DependencyRule[] }
 }
 
 /** `run.rules.dependencies`, checked by `vx lock` only. */
@@ -1760,6 +1788,7 @@ interface CacheSettings {
   download?: 'all' | 'toplevel' | 'none'
   inputStability?: InputStability
   outputs?: { clean?: boolean }
+  upload?: { failures?: 'ci' | 'local' | 'always' }
 }
 ```
 
@@ -1777,11 +1806,6 @@ interface CacheSettings {
 - **`run.continue`** — what a failed task takes down: `never` stops
   dispatch, `deps-ok` (the default) skips its dependents, `always` runs
   them (`docs/cli.md` § Failure propagation).
-- **`run.killGrace`**, **`run.teardownTimeout`**, **`run.readyNotice`**
-  — the SIGTERM → SIGKILL grace (2 s), the bound on each plugin's
-  end-of-run flush and teardown (3 s; there is no "no limit"), and how
-  long a persistent task may wait for `readyWhen` before vx says what it
-  waits for (10 s).
 - **`run.rules`** — checked by `vx lock` and `vx lock --check` only;
   no run checks them.
 - **`cache.dir`** — unset, the workspace keeps its index and history in
@@ -1847,6 +1871,13 @@ interface CacheSettings {
 - **`cache.download`** — which remote hits land on this machine:
   `all` (the default), only the requested tasks' (`toplevel`), or
   `none` (`docs/cli.md` § `--cache-download`).
+- **`cache.upload.failures`** — which runs keep a failed task's log and
+  the files its outputs left in the remote: CI runs (`'ci'`, the
+  default), runs off CI (`'local'`), or both (`'always'`). Only a run
+  whose policy writes a remote keeps any, and it always keeps the log of
+  a task that saved no entry. `ctx.cache.getRun` reads them
+  (`docs/modules/plugin.md` § Run report and run bytes).
+
 - **`cache.scope`** — where this run's cache writes land (2026-10-14).
   Omitted, a run reads and writes the default keys. A name (`'pr-123'`;
   letters, digits, `. _ - / @`, at most 128) reads the default key first,
@@ -1892,24 +1923,6 @@ own output path, or set run.rules.exclusiveOutputs: false in
     Off, the dependant adds to its upstream's tree (item 588;
     `caching.md` § Additive outputs). Two overlapping tasks with no
     edge are refused either way.
-  - **`upfrontKeys`** (X-54) — a cached task whose `inputs.files` can
-    match a same-project task's `outputs.files`, or whose
-    `inputs.workspaceFiles` can match any task's `outputs.workspaceFiles`
-    or another project's `outputs.files` read from the root, or whose
-    `inputs.files` can match another task's `outputs.workspaceFiles`
-    landing in its project (X-135), is refused,
-    edge or no edge: `<reader> reads "<glob>" in cache.inputs.<field>,
-which matches <writer>'s output "<glob>" … Exclude it: add "!<glob>"
-to <reader>'s cache.inputs.<field>, or set run.rules.upfrontKeys:
-false in .vx/workspace.ts to let it wait for its producer.` Such a key
-    reads what the producer writes this run, so vx cannot know it before
-    the producer ran: it is not probed, prefetched or restored ahead of
-    the schedule (`caching.md` § Local restore tier). The upstream's key
-    already reaches the reader through `dependsOn`. A `!` entry that
-    takes the whole output back clears it, and an output the reader's
-    `!` entries take back no longer holds its key back either. A task's
-    own outputs, a task with no `cache`, and a group are exempt. Off,
-    the key waits for its producer, as before.
   - **`dependencies`** — which workspace projects a project may depend
     on, checked by `vx lock` and `vx lock --check` only, over each
     project's direct dependencies (its `package.json` buckets and its
@@ -1925,6 +1938,41 @@ false in .vx/workspace.ts to let it wait for its producer.` Such a key
     `lib depends on app, which run.rules.dependencies[0] (from 'tag:lib') denies`,
     every broken edge on its own line. A rule with neither `allow` nor
     `deny` is refused.
+- **Inputs over outputs** (X-54, always checked, no setting) — a cached task whose `inputs.files` can
+  match a same-project task's `outputs.files`, or whose
+  `inputs.workspaceFiles` can match any task's `outputs.workspaceFiles`
+  or another project's `outputs.files` read from the root, or whose
+  `inputs.files` can match another task's `outputs.workspaceFiles`
+  landing in its project (X-135), is refused by `vx lock` unless one of
+  the exceptions below applies: `<reader> reads "<glob>" in inputs.<field>,
+which matches <writer>'s output "<glob>" … Exclude it: add "!<glob>"
+to <reader>'s inputs.<field>, or depend on <writer> and leave it out of
+<reader>'s inputs.tasks, so its key hashes those bytes instead.` Such a key
+  reads what the producer writes this run, so vx cannot know it before
+  the producer ran: it is not probed, prefetched or restored ahead of
+  the schedule (`caching.md` § Local restore tier). The upstream's key
+  already reaches the reader through `dependsOn`. A `!` entry that
+  takes the whole output back clears it, and an output the reader's
+  `!` entries take back no longer holds its key back either. Nor does
+  an output git ignores whole: a key reads only what git lists, so
+  `**/*` beside a gitignored `**/dist/**` passes and keys up front,
+  unless the reader's entry starts in the ignored path (`dist/**`):
+  naming it reads it, so the check applies. A reader may read the
+  outputs of a task in its `dependsOn` closure that its key does not
+  fold: it sets `inputs.tasks` and leaves the producer out, also
+  through the tasks it does fold (a producer folded by a folded task
+  counts as folded). Its key then waits for the producer and hashes
+  the bytes it wrote, so a producer rerun with identical output still
+  hits. `vx lock` checks all of it; a run reads only the lock. Git
+  is asked, never a `.gitignore` read: `git check-ignore` on the
+  output's directory (for `**/dist/**`, `dist/` and a fresh
+  `__vx_probe__/dist/`), and no tracked or listed file may match it,
+  so a tracked output is still refused. A glob no few paths stand for
+  (`*.js`) is refused as before. `vx lock` asks once for every
+  overlapped output; a run asks once beside its git walk for the
+  stability gate, so a rule changed after the lock keys the reader
+  late until the next `vx lock` refuses it. A task's
+  own outputs, a task with no `cache`, and a group are exempt.
 - **`plugins`** — the run-level extension points. Optional: core
   applies no plugin by default, and the local executor and the local
   cache are its floor — the tail of every executor list, and the first
@@ -1968,8 +2016,8 @@ malformed input.
 
 There are no workspace-level `globalInputs` / task-default fields:
 root-anchored file inputs are declared per task via
-`cache.inputs.workspaceFiles`, root-anchored probes via
-`cache.inputs.workspaceRuntime`, and shared task shapes compose
+`inputs.workspaceFiles`, root-anchored probes via
+`inputs.workspaceRuntime`, and shared task shapes compose
 through plain TypeScript (import a preset and spread it) — the
 language replaces Nx-style `namedInputs` / `targetDefaults` schema
 machinery by design.
@@ -2019,11 +2067,11 @@ export default defineProject({
       // too — the exec env is isolated, not inherited.
       exec: { command: 'tsc -b', env: { passThrough: ['NODE_ENV'] } },
       dependsOn: ['^build'],
+      inputs: {
+        files: ['src/**', '!**/*.test.ts', 'tsconfig.json'],
+        env: ['NODE_ENV'],
+      },
       cache: {
-        inputs: {
-          files: ['src/**', '!**/*.test.ts', 'tsconfig.json'],
-          env: ['NODE_ENV'],
-        },
         outputs: { files: ['dist/**'] },
       },
     },
@@ -2034,8 +2082,8 @@ export default defineProject({
       description: 'run unit tests',
       exec: { command: 'bun test', env: { passThrough: ['CI'] } },
       dependsOn: ['build'],
+      inputs: { files: ['src/**', 'tests/**'] },
       cache: {
-        inputs: { files: ['src/**', 'tests/**'] },
         outputs: { files: [] },
       },
     },
@@ -2046,11 +2094,11 @@ export default defineProject({
       description: 'pack the npm tarball',
       exec: { command: 'rm -rf pkg && npm pack --pack-destination ./pkg' },
       dependsOn: ['build', 'test', '^build'],
+      inputs: {
+        files: ['package.json'],
+        tasks: ['build', '^build'], // hash these upstream too
+      },
       cache: {
-        inputs: {
-          files: ['package.json'],
-          tasks: ['build', '^build'], // hash these upstream too
-        },
         outputs: { files: ['pkg/*.tgz'] },
       },
     },
@@ -2080,12 +2128,14 @@ export default defineProject({
     lint: {
       description: 'oxlint',
       exec: { command: 'oxlint .' },
-      cache: { inputs: { files: ['src/**', '.oxlintrc.json'] }, outputs: { files: [] } },
+      inputs: { files: ['src/**', '.oxlintrc.json'] },
+      cache: { outputs: { files: [] } },
     },
     'format-check': {
       description: 'oxfmt --check',
       exec: { command: 'oxfmt --check .' },
-      cache: { inputs: { files: ['src/**', '.oxfmtrc.json'] }, outputs: { files: [] } },
+      inputs: { files: ['src/**', '.oxfmtrc.json'] },
+      cache: { outputs: { files: [] } },
     },
 
     // Pure group task — `vx run ci` fans out, the group itself is
@@ -2134,12 +2184,12 @@ export default defineProject({
           weakerWhenNested: false,
         },
       },
+      inputs: {
+        files: ['e2e/**'],
+        runtime: ['npx playwright --version'],
+        workspaceRuntime: ['node -v'],
+      },
       cache: {
-        inputs: {
-          files: ['e2e/**'],
-          runtime: ['npx playwright --version'],
-          workspaceRuntime: ['node -v'],
-        },
         outputs: { files: ['test-results/**'] },
       },
     },
@@ -2164,11 +2214,13 @@ export default defineProject({
   tasks: {
     build: {
       exec: { command: 'tsc' },
-      cache: { inputs: { files: srcInputs }, outputs: { files: ['dist/**'] } },
+      inputs: { files: srcInputs },
+      cache: { outputs: { files: ['dist/**'] } },
     },
     test: {
       exec: { command: 'bun test' },
-      cache: { inputs: { files: [...srcInputs, 'tests/**'] }, outputs: { files: [] } },
+      inputs: { files: [...srcInputs, 'tests/**'] },
+      cache: { outputs: { files: [] } },
     },
   },
 })
@@ -2186,8 +2238,8 @@ export function tsBuild(opts?: { tsconfig?: string }): TaskConfig {
   return {
     description: 'compile TypeScript',
     exec: { command: `tsc -b ${opts?.tsconfig ?? ''}`.trim() },
+    inputs: { files: ['src/**', opts?.tsconfig ?? 'tsconfig.json'] },
     cache: {
-      inputs: { files: ['src/**', opts?.tsconfig ?? 'tsconfig.json'] },
       outputs: { files: ['dist/**'] },
     },
   }
@@ -2205,7 +2257,8 @@ export default defineProject({
     test: {
       exec: { command: 'bun test' },
       dependsOn: ['build'],
-      cache: { inputs: { files: ['src/**'] }, outputs: { files: [] } },
+      inputs: { files: ['src/**'] },
+      cache: { outputs: { files: [] } },
     },
   },
 })
@@ -2216,7 +2269,7 @@ to `.ts` source — see
 [`architecture.md` § Config-time imports](./architecture.md#config-time-imports--the-bootstrap-problem)
 for the bootstrap-cycle tradeoff.
 
-### When to use `cache.inputs.tasks: []`
+### When to use `inputs.tasks: []`
 
 When a `dependsOn` exists for ordering only, and the upstream's
 output doesn't influence this task's output. Common case: an
@@ -2227,11 +2280,11 @@ own inputs are just the test source.
 e2e: {
   dependsOn: ['dev'],
   exec: { command: 'playwright test' },
+  inputs: {
+    files: ['e2e/**'],
+    tasks: [],   // dev's hash does not affect e2e's cache identity
+  },
   cache: {
-    inputs: {
-      files: ['e2e/**'],
-      tasks: [],   // dev's hash does not affect e2e's cache identity
-    },
     outputs: { files: ['playwright-report/**'] },
   },
 }
@@ -2306,27 +2359,27 @@ a user meets most:
 | `sandbox is not allowed on an interactive task`                                                                                       | interactive + sandbox combined.                                                                                                                                                                                                |
 | `persistent.readyWhen is not allowed on an interactive task`                                                                          | vx reads none of an interactive task's output.                                                                                                                                                                                 |
 | `a task with no exec must declare dependsOn`                                                                                          | Group task with no edges.                                                                                                                                                                                                      |
-| `a task with no exec writes nothing`                                                                                                  | Group task with `cache.outputs` that names a file.                                                                                                                                                                             |
+| `cache needs exec — a task with no command produces nothing to cache`                                                                 | `cache` on a group: a task with no command writes nothing to cache.                                                                                                                                                            |
 | `dependsOn must be an array of strings`                                                                                               | Wrong shape.                                                                                                                                                                                                                   |
-| `cache.inputs is required when cache is set`                                                                                          | Forgot `inputs`.                                                                                                                                                                                                               |
-| `cache.inputs must be an object`                                                                                                      | Present but not an object: a string (`outputs: 'dist'`). An array is the row above.                                                                                                                                            |
-| `cache.inputs.files must be an array`                                                                                                 | Wrong shape.                                                                                                                                                                                                                   |
-| `cache.inputs.runtime must be an array of non-empty shell command strings with no NUL`                                                | Non-string / blank entry (whitespace alone runs as a no-op), or one holding a NUL.                                                                                                                                             |
-| `cache.inputs.workspaceRuntime must be an array of non-empty shell command strings with no NUL`                                       | Non-string / blank entry (whitespace alone runs as a no-op), or one holding a NUL.                                                                                                                                             |
-| `cache.inputs.tasks must be an array of non-empty strings`                                                                            | Non-string / empty entry, or a bare string.                                                                                                                                                                                    |
-| `cache.inputs.tasks: "<name>" names no task in <task>.dependsOn`                                                                      | An exact entry no `dependsOn` entry of its form names.                                                                                                                                                                         |
+| `cache needs inputs — the key is the task's inputs`                                                                                   | Forgot `inputs` on a cached task.                                                                                                                                                                                              |
+| `inputs must be an object`                                                                                                            | Present but not an object: a string (`outputs: 'dist'`). An array is the row above.                                                                                                                                            |
+| `inputs.files must be an array`                                                                                                       | Wrong shape.                                                                                                                                                                                                                   |
+| `inputs.runtime must be an array of non-empty shell command strings with no NUL`                                                      | Non-string / blank entry (whitespace alone runs as a no-op), or one holding a NUL.                                                                                                                                             |
+| `inputs.workspaceRuntime must be an array of non-empty shell command strings with no NUL`                                             | Non-string / blank entry (whitespace alone runs as a no-op), or one holding a NUL.                                                                                                                                             |
+| `inputs.tasks must be an array of non-empty strings`                                                                                  | Non-string / empty entry, or a bare string.                                                                                                                                                                                    |
+| `inputs.tasks: "<name>" names no task in <task>.dependsOn`                                                                            | An exact entry no `dependsOn` entry of its form names.                                                                                                                                                                         |
 | `cache.outputs is required when cache is set`                                                                                         | Forgot `outputs`.                                                                                                                                                                                                              |
 | `cache.inputStability must be an object`                                                                                              | A bare string (`inputStability: 'mutable'`).                                                                                                                                                                                   |
 | `cache.inputStability.strategy must be 'immutable', 'mutable' or 'unchecked'`                                                         | Any other value (`'content'`, `false`).                                                                                                                                                                                        |
 | `cache.inputStability.severity must be 'warn' or 'error'`                                                                             | Any other value (`'fail'`, `true`).                                                                                                                                                                                            |
 | `cache.outputs must be an object`                                                                                                     | Present but not an object: a string (`outputs: 'dist'`). An array is the row above.                                                                                                                                            |
 | `cache.outputs.files must be an array`                                                                                                | Wrong shape.                                                                                                                                                                                                                   |
-| `cache.inputs.files: every entry is a negation, which selects NOTHING`                                                                | Only `!` globs — nothing to subtract from.                                                                                                                                                                                     |
-| `cache.inputs.files: "<file>" is taken back by "!<glob>"`                                                                             | A literal input a `!` entry covers: the negation subtracts wherever it sits, so the file never entered the key.                                                                                                                |
+| `inputs.files: every entry is a negation, which selects NOTHING`                                                                      | Only `!` globs — nothing to subtract from.                                                                                                                                                                                     |
+| `inputs.files: "<file>" is taken back by "!<glob>"`                                                                                   | A literal input a `!` entry covers: the negation subtracts wherever it sits, so the file never entered the key.                                                                                                                |
 | `cache.outputs.files: every entry is a negation, which selects NOTHING`                                                               | Only `!` globs: a `!` entry only takes back what a positive glob selected (A-44).                                                                                                                                              |
 | `cache.outputs.files: "<glob>" covers the project's own <file>`                                                                       | An output glob that matches the project's own `vx.config.*` (`**`, `*.ts`): the clean before a run would delete it. A `!` entry that takes the file back (`!vx.config.ts`) lets it load.                                       |
 | `cache.outputs.files: "<glob>" is under workspace-outputs/`                                                                           | A project output named into the artifact's namespace for `outputs.workspaceFiles`: every hit read it back as a workspace output.                                                                                               |
-| `cache.inputs.files: '!!' is not a double negation`                                                                                   | `!!x` inverts the set — it folds only `x`.                                                                                                                                                                                     |
+| `inputs.files: '!!' is not a double negation`                                                                                         | `!!x` inverts the set — it folds only `x`.                                                                                                                                                                                     |
 | `exec.timeout of <value> exceeds the maximum timer delay`                                                                             | Past 2^31-1 ms a timer fires at once, not never.                                                                                                                                                                               |
 | `description must be a string`                                                                                                        | Non-string description.                                                                                                                                                                                                        |
 | `tag "<tag>" <why> — --filter tag:<name> could not name it`                                                                           | A tag with surrounding whitespace or a `*`, or one ending in `...` or `[<ref>]`, which a filter reads as a pattern, a dependency walk or a git range.                                                                          |
@@ -2334,7 +2387,7 @@ a user meets most:
 **Unknown fields are rejected**, not ignored, at every object level —
 the project's top level (`tasks`), the task itself, `exec`, `exec.env`,
 `exec.persistent`, `exec.sandbox` and its `allow` /
-`deny` / `ignore` blocks, `cache`, `cache.inputs`, and `cache.outputs`
+`deny` / `ignore` blocks, `cache`, `inputs`, and `cache.outputs`
 (`tests/schema-unknown-keys.test.ts` walks every one) — and at the top
 of `.vx/workspace.ts`,
 where `plugin:` (singular) would otherwise declare no plugins and run