@vzn/vx 0.0.636 → 0.0.638

package/docs/cli.md

@@ -8,7 +8,8 @@ in `src/cli/index.ts` dispatches to per-subcommand handlers under
 so existing Turbo users can swap in with minimal muscle-memory churn.
 
 ```sh
-# Standalone binary via npm (no Bun required on target):
+# Standalone binary via npm (no Bun required on target); inside a project
+# that installs @vzn/vx, it runs that one (§ Which vx runs):
 npm install -g @vzn/vx
 
 # From source (Bun ≥ 1.4):
@@ -28,15 +29,15 @@ released binary carries its own Bun and the row never says it.
 ```
 # Core
 vx run [OPTIONS] [TASK | PKG#TASK ...] [-- forwarded-args...]
-vx watch [OPTIONS] TASK [-- forwarded-args...]
-vx cache prune [--older-than <duration>] [--max-size <size>] [--dry-run] [--format pretty|json] [--cache-dir <path>]
+vx watch [OPTIONS] [--poll] TASK [-- forwarded-args...]
+vx cache clean [--older-than <duration>] [--max-size <size>] [--global] [--dry-run] [--format pretty|json] [--cache-dir <path>]
 vx lock [--check] [--format pretty|json]
 vx init [--dry [--format pretty|json]] [--force] [--mjs] [--native|--keep] [--plugin <seam>]
 vx show [PROJECT[#TASK] | TASK] [--filter <pattern>] [--affected[=<ref>]] [--format pretty|json]
 vx info [--format pretty|json] [--cache-dir <path>]
 vx why (TASK | PKG#TASK) [--run RUNID] [--format pretty|json] [--cache-dir <path>]
-vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--format pretty|json] [--cache-dir <path>]
-vx upgrade [TAG]      # self-update a compiled binary
+vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--stats [<task>] [--branch <name>]] [--format pretty|json] [--cache-dir <path>]
+vx upgrade [TAG]      # upgrade vx the way it was installed
 vx docs <query> [--limit N] [--format pretty|json]
 vx completions bash|zsh|fish
 
@@ -68,7 +69,8 @@ declare task(s): <name>.` on stderr, a run and `--dry` / `--graph` alike
 declared task (or, for `pkg#task`, a runnable spec) is within two edits,
 and with no name that near, what exists: `Tasks: build, test.`, `No
 project is named zzz; projects: a, b.`, or `a's tasks: build, test.`
-(M-56),
+(M-56), each followed by ``A run reads the lock: after editing a
+vx.config, run `vx lock`.`` (a task just added is not in the lock yet),
 and with `Only projects outside the selection declare <name> — pass
 --all, or --filter to pick them.` when the run was scoped (the cwd's
 project, a `--filter`) and a project outside the scope declares it
@@ -128,11 +130,11 @@ If no task name is given:
 
 Exit codes:
 
-| Code                  | When                                                                                                                                                                                                                                                                                                                                                                                        |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `0`                   | Every task finished `success` or `cache-hit` (local or remote); or `--affected` left no project that declares the task.                                                                                                                                                                                                                                                                     |
-| `1`                   | At least one task ended `failed` or `skipped`; a persistent task exited non-zero after it was ready; a task name no project declares; or parse/setup error.                                                                                                                                                                                                                                 |
-| `130` / `143` / `129` | Interrupted (SIGINT / SIGTERM / SIGHUP): each task's process group (the task and what it forked) gets vx's signal once (a SIGHUP as a SIGTERM), `VX_KILL_GRACE_MS` (2 s) to go, then SIGKILL; a second signal skips the grace. vx then dies of the signal, so a shell script running it stops too (a run that handed a task the terminal exits with the code, so the terminal is restored). |
+| Code                  | When                                                                                                                                                                                                                                                                                                                                                                                     |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0`                   | Every task finished `success` or `cache-hit` (local or remote); or `--affected` left no project that declares the task.                                                                                                                                                                                                                                                                  |
+| `1`                   | At least one task ended `failed` or `skipped`; a persistent task exited non-zero after it was ready; a task name no project declares; or parse/setup error.                                                                                                                                                                                                                              |
+| `130` / `143` / `129` | Interrupted (SIGINT / SIGTERM / SIGHUP): each task's process group (the task and what it forked) gets vx's signal once (a SIGHUP as a SIGTERM), `run.killGrace` (2 s) to go, then SIGKILL; a second signal skips the grace. vx then dies of the signal, so a shell script running it stops too (a run that handed a task the terminal exits with the code, so the terminal is restored). |
 
 A task runs in its own session, so a terminal's Ctrl-C reaches vx alone,
 and each task hears it once: from vx, as SIGINT.
@@ -182,7 +184,7 @@ facing summary.
 A filter that matches nothing refuses the run (`no projects matched
 filter(s): …`) with `Did you mean <name>?` when a project name is within
 two edits, or when exactly one scoped project's name after its `/` is
-(`--filter vx-mcp` hints `@vzn/vx-mcp`), and `Projects: a, b` otherwise
+(`--filter vx-otel` hints `@vzn/vx-otel`), and `Projects: a, b` otherwise
 (M-56). A list names eight, then a count. An unmatched `tag:` filter
 hints the nearest tag instead (`Did you mean tag:scope:web?`), else
 lists the tags. When every pattern matched and an exclusion took back
@@ -208,19 +210,15 @@ selected: !app excluded every project the other filters matched`).
 | `!<pattern>`      | Exclude packages matching `<pattern>`, from everything the includes select, in any order.                                                                                                                                                                                                                                               |
 | `[<git-ref>]`     | Projects whose files changed since `<git-ref>` (`main`, `HEAD~5`, …).                                                                                                                                                                                                                                                                   |
 
-An edge is a `package.json` workspace dependency (`dependencies`,
-`devDependencies`, `peerDependencies`, `optionalDependencies`; a peer
-that would close a cycle counts for selection only, see
-`modules/package-graph.md`) — an entry the package manager links to a
-workspace package, not one whose key merely names it:
-`"shared": "^1.0.0"` beside a local `shared@2.0.0` is a registry
-dependency and no edge, and `"luigi": "workspace:../waluigi"` is an
-edge to `waluigi` (the rule: `modules/package-graph.md` § Which entries
-are edges) — OR a
-cross-project `dependsOn` entry (`e2e`'s `test: { dependsOn:
-['app#build'] }` makes `e2e` a dependent of `app`). The task graph knows
-both, so selection follows both: `vx run test --filter '...app'` runs
-`e2e#test` even though `e2e` has no manifest dependency on `app`. There
+An edge is one a plugin supplies — a `discover` entry's `deps` (order
+and selection) or `reach` (selection only); the lockfile plugins
+(`pnpm()`, `bun()`, `npm()`, `yarn()` from `@vzn/vx-lockfile`) supply
+what the package manager installed, and core reads no edge from a
+`package.json` — OR a cross-project `dependsOn` entry (`e2e`'s `test: {
+dependsOn: ['app#build'] }` makes `e2e` a dependent of `app`). The task
+graph knows both, so selection follows both: `vx run test --filter
+'...app'` runs `e2e#test` even though no plugin gives `e2e` an edge to
+`app`. There
 is no `implicitDependencies` field — declare the edge where the task
 needs it.
 
@@ -244,7 +242,7 @@ vx run build --filter '[origin/main]'         # projects with files changed sinc
 
 Run the task only in projects whose files changed since `<base>`.
 
-- `--affected` (no value) uses the workspace's `affectedBase` when it
+- `--affected` (no value) uses the workspace's `run.affectedBase` when it
   names one (`nx()` and `turbo()` set it from `NX_BASE` / nx.json's
   `defaultBase` and `TURBO_SCM_BASE`, `turbo()` on GitHub Actions from
   the pull request's base or the push's `before`, as Turbo does;
@@ -301,12 +299,13 @@ change seeds tasks in the projects it touches:
   (`files`, `workspaceFiles`), or a changed submodule or embedded
   repository is one its `workspaceFiles` may reach into (git reports it
   as one path; a glob whose fixed prefix is above or inside it counts);
-- every task of a project whose `package.json` or `vx.config.*`
+- every task of a project whose `vx.config.*`
   changed, or that holds a changed path no cached task of its declares
   (vx cannot prove that path re-keys nothing), or that holds a changed
   submodule or embedded repository (git reports it as one path, and no
   task's globs can say whether they reach inside), or that a lockfile
-  claim, a manifest edge at the base or a config import names;
+  claim or a config import names (a dependency an install added or
+  removed reaches here as the lockfile's change);
 - an uncached task when a changed path lies in its project or the
   project is reached whole; a root file another task of its declares
   (`workspaceFiles`) is no change there. A group seeds nothing.
@@ -354,7 +353,7 @@ change to it, and every project under it is selected, the project that
 holds it included. A repository's own request to hide submodules from a diff
 (`diff.ignoreSubmodules`, `submodule.<name>.ignore`) does not apply:
 the key sees the change whatever git is told to show.
-`vx-lock.json` is filtered out of the changed set — a `vx lock`
+`.vx/projects.lock.json` is filtered out of the changed set — a `vx lock`
 re-write never marks every project affected.
 
 **A lockfile change selects everything.** The root lockfiles,
@@ -370,7 +369,9 @@ plugin CLAIMS (`VxPlugin.fingerprint`, e.g. `pnpm-lock.yaml` under
 `@vzn/vx-lockfile`) is the exception on both sides: the key folds what the
 plugin says per project, so `--affected` asks the plugin which projects
 the change touches — given the bytes at the base ref and in the working
-tree — and selects those; only a plugin that cannot tell widens.
+tree — and selects those; only a plugin that cannot tell widens, as
+`@vzn/vx-lockfile` does for the install settings it claims (`.npmrc`,
+`bunfig.toml`, `pnpm-workspace.yaml`, `.yarnrc.yml`).
 
 **A dropped edge selects its dependent.** A package the change deleted
 (its `package.json` was there at the base and is gone) is no project
@@ -393,8 +394,7 @@ too. "New" is judged at the base: no manifest there, or one with no
 `name`.
 
 **A workspace config change selects everything.** An edit to
-`vx.workspace.*`, or to a file it imports by relative specifier, selects
-every project: the `config` and `project` stages its plugins install
+`.vx/workspace.*` selects every project: the `config` and `project` stages its plugins install
 shape every resolved config, so the edit can re-key any task, and
 selection cannot tell which. It is not in the fingerprint (a key moves
 only when a stage's output does). A root file a plugin's stages read
@@ -470,33 +470,37 @@ than run with the args unheard.
 
 ### Flags
 
-| Flag                               | Type           | Default                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| ---------------------------------- | -------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--filter <pattern>`               | repeatable     | (none)                                    | pnpm-style filter DSL (see above). `--filter=<pattern>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `--all`                            | boolean        | off                                       | Select every project that declares the task.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `--affected[=<base>]`              | optional value | off                                       | Select the tasks a change since `<base>` reaches: the ones it touches and those whose `dependsOn` closure holds one (default `affectedBase`, else `origin/HEAD`, else `main` or `master`, else `HEAD~1`); candidates are `--filter "...[<base>]"`'s.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `--exclude-dependencies[=<names>]` | optional value | off                                       | Drop `dependsOn` edges. No value = all (just the requested task runs; a group's members run as the group); comma-list = drop only those names, each of which some project must declare (a typo is refused with the nearest name, item 1026). An edge to a task the run schedules anyway (`--all` requests it) stays, so the two still run in order, and so does the order through a dropped task: with `gen` dropped from `test → gen → build` and `build` requested, `test` still waits for `build`. An empty `=` value is a parse error (ambiguous — see below). A dropped dependency does not run but is still keyed, so every key is the one a full run derives; a task keyed on one may hit but does not save (`caching.md` step 10).          |
-| `--concurrency <n>`                | int or `<n>%`  | cores, capped by the cgroup quota         | Maximum parallel tasks that EXECUTE; confirmed cache-hit restores are disk work and run on their own lane, up to twice this. `1` serializes both; `50%` is half the CPUs (rounded, never below 1; over 100% is allowed for I/O-bound work). `--concurrency=<n>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `--no-cache`                       | boolean        | off                                       | Disable caching entirely (no reads, no writes); output globs are NOT cleaned.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `--force`                          | boolean        | off                                       | Re-execute everything (skip cache reads) but still REFRESH the cache (writes stay on). Output globs are cleaned (so the saved snapshot is clean).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `--cache <spec>`                   | value          | all axes on                               | Per-layer read/write control. See below. An EMPTY spec (`--cache=`) is a parse error — it applied nothing and left every axis on; pass `--no-cache` to disable them all.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `--cache-scope <name>`             | value          | `VX_CACHE_SCOPE` / workspace `cacheScope` | This run's `cacheScope` (`trusted`, `read-only`, `pr-123`), above `VX_CACHE_SCOPE`, `vx.workspace`'s and `github()`'s. A name `cacheScope` would refuse is refused. `--cache-scope=<name>` form too. Never folded into a cache key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `--cache-dir <path>`               | value          | workspace `cacheDir` / `~/.vx/<id>/cache` | Cache directory override, resolved relative to cwd (absolute paths used as-is). Beats the `defineWorkspace({ cacheDir })` field, `VX_CACHE_DIR` and the default; like them, the directory then holds the whole cache, shared through no store, for every cache the run opens — the config-evaluation cache that `--affected` owners, the picker and the watch sweep read included, so the workspace's default dir is not created beside it. A per-run knob — never folded into a cache key. `--cache-dir=<path>` form too; the space form rejects a value starting with `-`. A directory this user cannot write into fails the run before any task with `cache directory <path> is not writable (EACCES: …)` — every run records its history there. |
-| `--retry <n>`                      | value          | `0`                                       | Re-run a failed task up to `n` more times; never a persistent one. Run-level default only: a task's own `exec.retries` wins (even an explicit `0`). Never affects cache keys. `--retry=<n>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `--continue[=<mode>]`              | value          | `deps-ok`                                 | What a failed task takes down with it. `never` stops dispatch on the first failure; `deps-ok` (default) skips only its dependents; `always` (bare `--continue`) runs dependents anyway. See § Failure propagation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `--timeout <ms>`                   | positive int   | none                                      | Default per-task timeout for tasks without their own `exec.timeout`. Sits above `VX_TASK_TIMEOUT` + workspace `timeout`; per-task `exec.timeout` always wins. A runaway task is killed + `failed`. Never affects cache keys. `--timeout=<ms>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `--frozen`                         | boolean        | off                                       | Load configs from `vx-lock.json` instead of evaluating (CI) — the run's, and the ones `--affected` owners and the picker select from. See § `--frozen`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `--output-logs <mode>`             | value          | flow-derived                              | `full` \| `errors-only` \| `hash-only` \| `none` — explicit output override. See § `--output-logs`. `--output-logs=<mode>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `--download <mode>`                | value          | `all`                                     | `all` \| `toplevel` \| `none` — where a REMOTELY-executed task's outputs land. `none` leaves them in the remote CAS and fetches lazily, only when a locally-placed task needs them. Never affects cache keys. See § `--download`. `--download=<mode>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `--verbosity <n>`                  | int (0+)       | `0`                                       | `1` or more prints a per-task table (groups left out) after the framed blocks, above the footer. `--verbosity=<n>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `--dry[=text\|json]`               | optional value | off                                       | Print the task graph + predicted cache hit/miss; skip execution. `VX_TIMING=1` prints the stage table here as it does for a run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `--graph[=<path>]`                 | optional value | off                                       | Emit Graphviz DOT (stdout if no path, its directory made if missing); skip execution. A path it cannot write is one line and exit 1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `--format <fmt>`                   | value          | `pretty`                                  | `json` prints the `--summarize` document on stdout when the run ends and moves every other line to stderr ([Machine-readable output](#machine-readable-output)). `--format=<fmt>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `--summarize[=<path>]`             | optional value | off                                       | Write per-run JSON to `<cacheDir>/runs/<run_id>.json` (or the explicit path).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `--profile[=<path>]`               | optional value | off (`profile.json` when set)             | Write Chrome-trace JSON of the run's wallclock spans.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `--tag <k=v>`                      | repeatable     | (none)                                    | Label this invocation. Recorded on the run's `invocations` row so dashboards can filter runs. `--tag=k=v` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `--report[=markdown]`              | optional value | off                                       | At the end of the run, print a markdown run report to stdout, above the footer. Only `markdown` is supported (`json` is reserved).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `--report-file <path>`             | value          | off                                       | After the run, APPEND the same markdown report to `<path>`, making its directory as the other output paths do. Use this for `$GITHUB_STEP_SUMMARY` — redirecting stdout captures the whole run log too. `--report-file=<path>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Flag                                       | Type           | Default                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ------------------------------------------ | -------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--filter <pattern>`                       | repeatable     | (none)                                                     | pnpm-style filter DSL (see above). `--filter=<pattern>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `--all`                                    | boolean        | off                                                        | Select every project that declares the task.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `--affected[=<base>]`                      | optional value | off                                                        | Select the tasks a change since `<base>` reaches: the ones it touches and those whose `dependsOn` closure holds one (default `run.affectedBase`, else `origin/HEAD`, else `main` or `master`, else `HEAD~1`); candidates are `--filter "...[<base>]"`'s.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `--exclude-dependencies[=<names>]`         | optional value | off                                                        | Drop `dependsOn` edges. No value = all (just the requested task runs; a group's members run as the group); comma-list = drop only those names, each of which some project must declare (a typo is refused with the nearest name, item 1026). An edge to a task the run schedules anyway (`--all` requests it) stays, so the two still run in order, and so does the order through a dropped task: with `gen` dropped from `test → gen → build` and `build` requested, `test` still waits for `build`. An empty `=` value is a parse error (ambiguous — see below). A dropped dependency does not run but is still keyed, so every key is the one a full run derives; a task keyed on one may hit but does not save (`caching.md` step 10). |
+| `--concurrency <n>`                        | int or `<n>%`  | `run.concurrency`, else the cores (cgroup-capped)          | Maximum parallel tasks that EXECUTE; confirmed cache-hit restores are disk work and run on their own lane, up to twice this. `1` serializes both; `50%` is half the CPUs (rounded, never below 1; over 100% is allowed for I/O-bound work). `--concurrency=<n>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `--schedule <rule>`                        | value          | `run.schedule`, else `most-work`                           | Which ready task starts first when more are ready than workers: `most-work`, `critical-path`, `direct-dependents`, `ready-order` (`docs/schema.md` § `run.schedule`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `--branch <name>`                          | value          | `VX_RUN_BRANCH`, else git's branch, then the CI provider's | The branch the run records in its history and forecasts from. No config key: a committed branch would mislabel every other branch's runs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `--no-cache`                               | boolean        | off                                                        | Disable caching entirely (no reads, no writes); output globs are NOT cleaned.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `--force`                                  | boolean        | off                                                        | Re-execute everything (skip cache reads) but still REFRESH the cache (writes stay on). Output globs are cleaned (so the saved snapshot is clean).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `--cache-policy <spec>` (`--cache-policy`) | value          | `VX_CACHE_POLICY` / `cache.policy`                         | Per-layer read/write control. See below. An EMPTY spec (`--cache-policy=`) is a parse error — it applied nothing and left every axis on; pass `--no-cache` to disable them all.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `--cache-scope <name>`                     | value          | `VX_CACHE_SCOPE` / workspace `cache.scope`                 | This run's `cache.scope` (`pr-123`), above `VX_CACHE_SCOPE`, `.vx/workspace`'s and `github()`'s. A name `cache.scope` would refuse is refused. `--cache-scope=<name>` form too. Never folded into a cache key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `--cache-dir <path>`                       | value          | `VX_CACHE_DIR` / `cache.dir` / `~/.vx/<id>/cache`          | Cache directory override, resolved relative to cwd (absolute paths used as-is). Beats `VX_CACHE_DIR`, the workspace's `cache.dir` and the default; like them, the directory then holds the whole cache, shared through no store, for every cache the run opens, so the workspace's default dir is not created beside it. A per-run knob — never folded into a cache key. `--cache-dir=<path>` form too; the space form rejects a value starting with `-`. A directory this user cannot write into fails the run before any task with `cache directory <path> is not writable (EACCES: …)` — every run records its history there.                                                                                                           |
+| `--retries <n>`                            | value          | `run.retries`, else `0`                                    | Re-run a failed task up to `n` more times; never a persistent one. A task's own `exec.retries` wins (even an explicit `0`). Never affects cache keys. `--retries=<n>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `--continue[=<mode>]`                      | value          | `deps-ok`                                                  | What a failed task takes down with it. `never` stops dispatch on the first failure; `deps-ok` (default) skips only its dependents; `always` (bare `--continue`) runs dependents anyway. See § Failure propagation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `--timeout <duration>`                     | duration       | `run.timeout`, else none                                   | A task's time limit (`30s`, `10m`), for tasks without their own `exec.timeout`, which always wins. A runaway task is killed + `failed`. A bare number is refused naming the forms with units. Never affects cache keys. `--timeout=<duration>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `--kill-grace <duration>`                  | duration       | `run.killGrace`, else `2s`                                 | How long a task that ignores SIGTERM gets before SIGKILL: on a timeout, on a signal, and at the end-of-run shutdown of persistent tasks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `--teardown-timeout <duration>`            | duration       | `run.teardownTimeout`, else `3s`                           | The bound on each plugin's end-of-run flush or teardown, and on its `telemetry()` setup, so a third party's I/O cannot hold the run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `--ready-notice <duration>`                | duration       | `run.readyNotice`, else `10s`                              | How long a persistent task may take to match `readyWhen` before vx says once what it waits for.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `--output-logs <mode>`                     | value          | `VX_RUN_OUTPUT_LOGS`, else flow-derived                    | `full` \| `errors-only` \| `hash-only` \| `none` — explicit output override. See § `--output-logs`. `--output-logs=<mode>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `--cache-download <mode>`                  | value          | `cache.download`, else `all`                               | `all` \| `toplevel` \| `none` — where a REMOTELY-executed task's outputs land. `none` leaves them in the remote CAS and fetches lazily, only when a locally-placed task needs them. Never affects cache keys. See § `--cache-download`. `--cache-download=<mode>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `--verbosity <n>`                          | int (0+)       | `0`                                                        | `1` or more prints a per-task table (groups left out) after the framed blocks, above the footer. `--verbosity=<n>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `--dry[=text\|json]`                       | optional value | off                                                        | Print the task graph + predicted cache hit/miss; skip execution. `VX_DEBUG_TIMING=1` prints the stage table here as it does for a run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `--graph[=<path>]`                         | optional value | off                                                        | Emit Graphviz DOT (stdout if no path, its directory made if missing); skip execution. A path it cannot write is one line and exit 1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `--format <fmt>`                           | value          | `pretty`                                                   | `json` prints the `--summarize` document on stdout when the run ends and moves every other line to stderr ([Machine-readable output](#machine-readable-output)). `--format=<fmt>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `--summarize[=<path>]`                     | optional value | off                                                        | Write per-run JSON to `<cacheDir>/runs/<run_id>.json` (or the explicit path).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `--profile[=<path>]`                       | optional value | off (`profile.json` when set)                              | Write Chrome-trace JSON of the run's wallclock spans.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `--tag <k=v>`                              | repeatable     | (none)                                                     | Label this invocation. Recorded on the run's `invocations` row so dashboards can filter runs. `--tag=k=v` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `--report[=markdown]`                      | optional value | off                                                        | At the end of the run, print a markdown run report to stdout, above the footer. Only `markdown` is supported (`json` is reserved).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `--report-file <path>`                     | value          | off                                                        | After the run, APPEND the same markdown report to `<path>`, making its directory as the other output paths do. Use this for `$GITHUB_STEP_SUMMARY` — redirecting stdout captures the whole run log too. `--report-file=<path>` form too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
 Mutual exclusion:
 
@@ -551,11 +555,13 @@ shell variable), never a path or task id. Use the `=` form for a literal
 leading dash.
 
 **Numeric flags take a plain decimal integer.** `--concurrency`,
-`--timeout`, `--retry` and `--verbosity` reject hex (`0x10`), exponent
-(`1e3`), fractional (`2.7`), signed (`+4`) and space-padded forms, plus
-anything past `2^53` (it would parse to a number you did not type).
-These all used to be silently reinterpreted — `--concurrency 0x10` ran
-16 workers.
+`--retries` and `--verbosity` reject hex (`0x10`), exponent (`1e3`),
+fractional (`2.7`), signed (`+4`) and space-padded forms, plus anything
+past `2^53` (it would parse to a number you did not type). These all
+used to be silently reinterpreted — `--concurrency 0x10` ran 16
+workers. A duration flag (`--timeout`, `--kill-grace`,
+`--teardown-timeout`, `--ready-notice`) takes its unit (`500ms`, `30s`,
+`10m`): a bare `500` is refused, naming both readings.
 
 An empty `=` value means "no value" on four flags, which then act like
 their bare forms: `--profile=` writes `profile.json`, `--summarize=`
@@ -563,26 +569,34 @@ writes `<cacheDir>/runs/<run_id>.json`, `--graph=` prints to stdout and
 `--affected=` uses the default base. Every other flag refuses an empty
 value: `--dry=`, `--report=`, `--continue=` and
 `--exclude-dependencies=` as well as the ones with no bare form
-(`--retry=`, `--timeout=`, `--cache-dir=`, `--filter=`, `--cache=`).
+(`--retries=`, `--timeout=`, `--cache-dir=`, `--filter=`, `--cache-policy=`).
 
-#### Cache control: `--cache`, `--no-cache`, `--force`
+#### Cache control: `--cache-policy`, `--no-cache`, `--force`
 
 The cache has four independent axes — **localRead**, **localWrite**,
 **remoteRead**, **remoteWrite** — and the three flags above resolve
 them in this precedence order:
 
 1. Start with every axis **on** (the default).
-2. Apply each `--cache=<spec>` segment (the base), or, with no
-   `--cache`, the `VX_CACHE` environment variable's spec.
+2. Apply each `--cache-policy=<spec>` segment (the base), or, with no
+   `--cache-policy`, the `VX_CACHE_POLICY` environment variable's spec, or, with
+   neither, `.vx/workspace`'s `cache.policy` (`docs/schema.md`).
 3. If `--no-cache` was passed, force **all four off**.
 4. If `--force` was passed, force **both reads off** (writes stay
-   whatever the base / `--cache` left them).
+   whatever the base / `--cache-policy` left them).
+5. Off CI (`CI` unset, `0` or `false`), unless `--cache-policy`,
+   `VX_CACHE_POLICY` or `cache.policy` names the remote, force
+   **remoteWrite off**: a key holds only declared inputs, so a laptop's
+   write could replay on CI. `cache.scope` never changes an axis.
 
 A spec that names a remote axis (`remote:r`, `remote:w`, `remote:rw`)
 in a workspace whose plugins supply no remote layer gets one status
 line saying so — the axes are inert without a layer to serve them, and
 a CI job that believes it is filling a shared cache should be told.
 
+Whatever the axes, a lookup asks the local cache first, then each
+remote in the order the plugins declare them.
+
 So `--no-cache` always wins over `--force`. The common cases:
 
 - `--no-cache` → nothing reads, nothing writes, and declared output
@@ -593,29 +607,30 @@ So `--no-cache` always wins over `--force`. The common cases:
   before each task so the saved snapshot is clean. This is the "rebuild
   and refresh the cache" flag.
 
-`--cache=<spec>` is a comma-separated list of `<layer>:<flags>`
+`--cache-policy=<spec>` is a comma-separated list of `<layer>:<flags>`
 segments. `layer` is `local` or `remote`; `flags` is any subset of `r`
 (read) and `w` (write), order-independent and possibly empty. A
 **mentioned** layer is set EXACTLY to its flags; an **unmentioned**
-layer keeps its current value. Both `--cache=<spec>` and the space form
-`--cache <spec>` are accepted.
+layer keeps its current value. Both `--cache-policy=<spec>` and the space form
+`--cache-policy <spec>` are accepted.
 
-| Spec                        | Effect                                                  |
-| --------------------------- | ------------------------------------------------------- |
-| `--cache=local:rw,remote:r` | remote read-only (won't upload); local full             |
-| `--cache=local:r`           | local read-only; remote untouched (still full)          |
-| `--cache=remote:`           | remote fully off; local untouched                       |
-| `--cache=local:,remote:rw`  | don't touch the local cache, but still upload to remote |
+| Spec                               | Effect                                                  |
+| ---------------------------------- | ------------------------------------------------------- |
+| `--cache-policy=local:rw,remote:r` | remote read-only (won't upload); local full             |
+| `--cache-policy=local:r`           | local read-only; remote untouched (still full)          |
+| `--cache-policy=remote:`           | remote fully off; local untouched                       |
+| `--cache-policy=local:,remote:rw`  | don't touch the local cache, but still upload to remote |
 
 `local:` means "don't serve hits out of the pre-existing local cache" —
 a remote hit is still delivered (the artifact has to land on disk to be
 extracted), it just never short-circuits the remote read.
 
 Combine with `--force` for "re-execute and refresh only the remote":
-`--cache=local: --force` (local off, reads off, remote write-only).
+`--cache-policy=local: --force` (local off, reads off, remote write-only).
 
 Invalid layers/flags are a parse error
-(`invalid --cache layer 'disk'`, `invalid --cache flag 'x'`, …).
+(`--cache-policy: invalid layer 'disk'`, `--cache-policy: invalid flag 'x'`, …);
+`VX_CACHE_POLICY` and `cache.policy` say their own name instead.
 
 ### Output
 
@@ -731,7 +746,7 @@ tracks the run live. Top to bottom:
    persistent tasks it depends on, until it — or, with several, the
    first of them — exits (one kept only as a dependency that exits 0,
    a daemon that forked and returned, does not end it); the rest still up are then torn
-   down (SIGTERM, `VX_KILL_GRACE_MS`, SIGKILL), one status line names
+   down (SIGTERM, `run.killGrace`, SIGKILL), one status line names
    the task and its code (`vx: app#dev exited with code 1; stopping 1
 other persistent task`), and a non-zero exit makes the run exit 1
    and is what `vx last` records.
@@ -744,15 +759,18 @@ other persistent task`), and a non-zero exit makes the run exit 1
    each one's id (`app#dev │ Local: http://localhost:5173`), except
    under `--output-logs errors-only`, `hash-only` or `none`; a single
    requested server in the focused flow streams raw from its frame.
-3. **Worker rows** — one per worker slot (sized
+3. **Worker rows** — one per worker slot that has been busy (at most
    `min(concurrency, 10)`), no glyph and no spinner: the live ticking
    elapsed time leads (`     568ms running  <id>`). A task stays in
-   its row for its whole life; idle rows hold their place dimmed, so
-   nothing ever jumps; overflow shows as `+k more`. A second in, a row
+   its row for its whole life; a row whose task ended holds its place
+   dimmed (`idle`), so nothing ever jumps; overflow shows as `+k more`. A second in, a row
    says what waits on it: `critical path` (yellow) on the running task
    the longest unfinished chain waits on, by the same p50s as the
    forecast below and only while two or more run, and a dim
-   `blocks N`, its unfinished dependents direct and transitive.
+   `blocks N`, its unfinished dependents direct and transitive. Where
+   local history knows the task, its row also shows its usual duration
+   (its executed p50) in the cache column, fixed while the elapsed time
+   counts up toward it (`3.33s running ~5.2s  solid-js#types`).
 4. **The live summary section** — the SAME meters the final footer
    prints (`tasks` + `cache` bars with legends, `time`), filling in as
    the run progresses, under a bare `vx` wordmark rule. A second in,
@@ -762,7 +780,10 @@ other persistent task`), and a non-zero exit makes the run exit 1
    workers, a running task's spent time taken off its own. It says
    nothing when history knows none of what is left, or once a running
    task is 25% past its p50. A run that ends inside the second never
-   reads history for it, and the final summary never shows it.
+   reads history for it, and the final summary never shows it. A p50
+   here is the median of the task's last five timings on this branch,
+   else on any branch; the timings are shared by every worktree of the
+   repo, so a new one has a forecast on its first run.
 
 In a terminal known to read them, the region also sends zero-width
 escapes: tab or taskbar progress (OSC 9;4: Ghostty, iTerm2 3.6+,
@@ -783,7 +804,8 @@ text is the task's output unchanged; a successful task's frame is never
 linked.
 
 The region is redrawn in place (cursor-up + clear; not a TUI — no
-alternate screen) and erased before the final summary prints. In the
+alternate screen) and erased before the final summary prints. On a
+terminal shorter than the region, it shows only the rows that fit. In the
 focused flow it only lives while dependencies run; it disappears for
 good the moment the requested task starts streaming.
 
@@ -850,7 +872,7 @@ down with it:
 The mode is the local scheduler's: a task a plugin executor runs
 elsewhere is one dispatch, failed or not, like any other.
 
-### `--download <mode>`
+### `--cache-download <mode>`
 
 Where a **remotely-executed** task's outputs land. `all` (default)
 downloads every task's outputs to this machine as it completes —
@@ -864,7 +886,7 @@ bytes"). A CI job that only wants the verdict moves no output bytes at
 all.
 
 Locally-executed tasks always write in place and ignore the flag, and
-`exec.remote: 'only'` still means never — `--download` cannot override
+`exec.remote: 'only'` still means never — `--cache-download` cannot override
 it in either direction. **It never affects a cache key**: transfer
 tuning cannot change what a command produces.
 
@@ -976,8 +998,11 @@ $ vx run build lint --affected=main --dry
 ```
 
 `kind` is `input` (a changed `file` is a declared input), `project` (its
-project changed and the task reads it whole: an uncached task, or no
-single `file` for a lockfile claim, a manifest edge or a config import),
+project changed and the task reads it whole: an uncached task, or a changed
+`file` no cached task of the project declares, often an output git does not
+ignore; no `file` for a config import), `workspace` (a workspace-wide
+`file` changed: the workspace config, or a root file a plugin claims such
+as a lockfile, reached every task of the project),
 `package` (a `^` edge passes a changed `project` with no such task),
 `named` (`pkg#task` beside a bare task) or `selected` (another filter
 selected its project). `via` is the `dependsOn` chain, nearest first, to
@@ -1089,7 +1114,7 @@ outcome bucket or `total`, but they make the run red, so they are
 listed separately and counted as `summary.aborted`.
 
 **`noCache: true`** marks a task no cache answered for: it declares no
-`cache` block (it executes every run by design), or the run's `--cache`
+`cache` block (it executes every run by design), or the run's `--cache-policy`
 read and wrote nothing (`--no-cache`), so a hit rate should leave it out
 of the denominator. The key is present only when true; every other row is
 unchanged. Its `hash` is still set: dependents fold it.
@@ -1192,14 +1217,14 @@ or a timeout's reason, `failed (timed out, exit 143)`, a persistent
 task's `never ready: …`, or a sandboxed task's violation count, or
 `skipped`, naming what blocked it: `skipped (blocked by lib#build)`);
 `Cache` is its provenance (`miss` / `no-cache` for a task no cache
-answered for — no `cache` block, or a `--no-cache` / `--cache=local:` run —
+answered for — no `cache` block, or a `--no-cache` / `--cache-policy=local:` run —
 which never consulted one / `local` / `remote` / `up-to-date` /
 `—`). A stopped run (a Ctrl-C teardown) reads `## vx run — interrupted`,
 and its tasks keep the terminal's words: one the signal killed is
 `aborted` with its time so far, one the stop reached before it ran is
-`not run` with no time. Neither joins the counts; the header names them
-after the total, `not counted: 1 aborted, 1 not run`, so a red report
-with no failing row still says why. Group tasks (no `exec`) get neither — they are not
+`not run` with no time. Both count in the header's task total, listed
+as `1 aborted · 1 not run`, so a red report with no failing row still
+says why. Group tasks (no `exec`) get neither — they are not
 work, and the header's counts match the terminal summary and
 `--summarize` exactly.
 
@@ -1321,7 +1346,7 @@ sandbox run as usual, and the failure's dependents follow `--continue`.
 ## `vx watch`
 
 ```
-vx watch [OPTIONS] TASK [-- forwarded-args...]
+vx watch [OPTIONS] [--poll] TASK [-- forwarded-args...]
 ```
 
 Run the named task, then re-run it on every filesystem change in the
@@ -1347,11 +1372,11 @@ run...` precedes it.
    `dependsOn` edges included — is watched recursively, less any project
    nested inside it, with a config or not (a root project's key leaves a nested
    project's files out, so an edit there is no cycle; X-42, X-57). The workspace root is
-   watched (non-recursively) for lockfile / `pnpm-workspace.yaml`
-   changes and for an edit to `vx.workspace.*` — the one root file that
+   watched (non-recursively) for a claimed file (a lockfile), for
+   `.vx/projects.lock.json` and for an edit to `.vx/workspace.*` — the one root file that
    shapes a run (plugins, `config` stage, concurrency) without being any
    task's input; the cycle after it re-evaluates the file. A `.gitignore`
-   there or in a package glob's directory is a cycle too: inputs are
+   there or in a project's parent directory is a cycle too: inputs are
    gitignore-aware, so it changes what keys read (X-136). A file a
    config imports by relative path from outside the watched projects (a
    shared preset) is watched too, and its edit is a cycle that re-reads
@@ -1359,20 +1384,23 @@ run...` precedes it.
    config's own edit does (WD-14). A file the workspace config imports is loaded once per
    process, so its edit is named with the restart it needs rather than
    run stale (item 949). An import whose file is gone stays on the list
-   by the name it would have, so its return is a cycle (X-133). The directory
-   each `<dir>/*` package glob names (`packages/` for `packages/*`) is
-   watched for members coming and going: a package added while the watch
-   runs is a cycle that runs it, and its directory is watched from before
-   that cycle runs, so an edit made during it queues (X-138); a removed one is dropped. An edit to the glob list itself (the
-   root `package.json`'s `workspaces`, `pnpm-workspace.yaml`) re-reads
-   the set, so a glob added there is watched from the cycle it triggers
-   (item 1018). A base, or a directory a config imports from, removed and made
-   again (a checkout that restores `packages/`) is heard from its nearest directory that exists, and a
-   watch whose directory was replaced is armed again (an OS watch holds
-   the deleted one; `watch-recreated-dirs.test.ts`). Under `--filter` or `--affected` the scope is the one
-   resolved at start, and a new package joins it only as a dependency of
-   it; a glob of another shape (`apps/**`) has no such directory, so a
-   package added under it waits for a restart. A task's own declared outputs (`cache.outputs.files`,
+   by the name it would have, so its return is a cycle (X-133). The
+   projects are the lock's: a new `.vx/projects.lock.json` is the
+   event that adds or drops one, and its directory is watched
+   from before that cycle runs, so an edit made during it queues
+   (X-138). A config added and not locked is no project yet. With no
+   lock at start the first cycle fails saying so, and the watch waits
+   for one. A project directory, or one a config imports from,
+   removed and made again (a checkout that restores `packages/`) is
+   heard from its nearest directory that exists and each one above it,
+   and a watch whose
+   directory was replaced is armed again (an OS watch holds the deleted
+   one; `watch-recreated-dirs.test.ts`). There, a project directory
+   that is still the same one starts no cycle: a task writing at its
+   top level moved its mtime, which macOS reports to the parent
+   (`watch-project-dir-write.test.ts`). Under `--filter` or
+   `--affected` the scope is the one resolved at start, and a new
+   project joins it only as a dependency of it. A task's own declared outputs (`cache.outputs.files`,
    `outputs.workspaceFiles`; a plugin's `project` stage counts, as in
    a run) never trigger a re-run — a cycle that writes `dist/` is not
    an edit, nor is the `dist` directory itself coming and going (a
@@ -1410,7 +1438,10 @@ run...` precedes it.
    starts a cycle, since no cache key can see it (a user's edit to one
    still does in a project with a task that has a command and no cache,
    which reads what it likes, item 947, outside any project nested
-   in it) — or declared an
+   in it; a write the last cycle made is not, read off the later of
+   its mtime and ctime, so an output a cache hit restores with its
+   saved mtime is the run's, and so is the restore's own `.vx-tmp-*`
+   file, `watch-restored-output.test.ts`) — or declared an
    output, or the loop re-runs on it; after three such cycles in a row
    watch names the path and the remedy, once, and keeps going. A dev
    server the last cycle left running counts as that cycle for as long
@@ -1427,7 +1458,8 @@ run...` precedes it.
    at the root, a `coverage/` or `.turbo/` tree, an editor's scratch
    file are dropped before the trigger — so `vx watch … > build.log`
    inside the repo settles instead of feeding itself a cycle per line
-   of its own output. `vx watch: watching …` is
+   of its own output. The opening line, `watching N projects · M tasks`
+   (after the initial run's rows), is
    printed only after every watcher has reported a probe file written
    under it (`.vx-watch-probe`, re-written on a short backoff until its
    event arrives, then removed): on macOS a directory watcher can return
@@ -1439,10 +1471,16 @@ run...` precedes it.
    watcher whose probe is not heard within 2 s is replaced by a poller
    that checks every 250 ms, with the notice `vx watch: <dir>: no OS
 watch events within 2000 ms; polling every 250 ms instead`.
-3. **On change.** The triggering path is logged
-   (`vx watch: <project> <relpath>; re-running...`): the first changed
-   path that still exists, so an editor's temporary file renamed away
-   names nothing; a deletion names the cycle when nothing else changed. The
+3. **On change.** A cycle opens with a blank line and
+   `changed <project> <relpath>`, plus ` (+N more)` when more paths
+   changed, then its task rows as `vx run` prints them, with no footer.
+   The named path is the first changed one that still exists, so an
+   editor's temporary file renamed away names nothing; a deletion names
+   the cycle when nothing else changed. The `watching` line is said
+   once: a cycle that re-reads the watched set (a member came or went,
+   the lock or a plugin changed) says nothing more; `VX_DEBUG_WATCH=1`
+   says each arm on stderr as `vx watch: armed N projects`. Errors and
+   refusals go to stderr. The
    orchestrator is invoked again with the same options, save one: the
    `--affected` diff is read once, for the initial run. A later cycle
    runs the requested task in every project of the scope fixed at start,
@@ -1457,15 +1495,16 @@ watch events within 2000 ms; polling every 250 ms instead`.
 
 Always ignored (no re-trigger):
 
-- `node_modules/`, `.git/`, `.vx/` anywhere in the path.
+- `node_modules/`, `.git/`, `.vx/cache/` anywhere in the path.
 - A path git ignores (`git check-ignore`, asked once per debounce
   window, never per event): invisible to every cache key — inputs are
   tracked + untracked-not-ignored — so a cycle it started could change
   nothing. A tracked file that matches a pattern is not ignored, by
   git's own rule; outside a repository nothing is.
-- Files ending in `.tsbuildinfo` or `~` (editor swap files).
-- The run's **resolved cache directory**, wherever it is. `.vx/` covers the
-  default, but `defineWorkspace({ cacheDir })` and `--cache-dir` can put it
+- Files ending in `~` (editor swap files), and a restore's own
+  `.vx-tmp-*` file.
+- The run's **resolved cache directory**, wherever it is. `.vx/cache/` covers the
+  default, but `defineWorkspace({ cache: { dir } })` and `--cache-dir` can put it
   anywhere; watching it would let vx's own cache writes trigger the next
   cycle, which writes again — a loop that never settles.
 
@@ -1494,19 +1533,20 @@ It samples each file's later clock of mtime and ctime, so a replacement
 that carries the old file's mtime (`cp -p`, `rsync -a`, a `mv`) is an
 edit to it as it is to the OS watcher.
 
-### Workspace fingerprint changes
-
-Edits to a lockfile (`pnpm-lock.yaml`, `bun.lock`, …) or
-`pnpm-workspace.yaml` at the root invalidate every task's cache key
-via the [workspace fingerprint](./caching.md#cache-key-derivation).
-Watch mode hears those because it watches the workspace root
-(non-recursively). A lockfile a plugin claims still triggers a cycle,
-and so does any other root file a plugin claims (`turbo.json` under
-`turbo()`, item 961), a plugin added to the workspace config mid-watch
-included from the cycle that loads it; the keys then decide which
-projects actually re-run. Under `vx watch --frozen` every cycle's configs come from
-`vx-lock.json`, so a config edit alone changes no command, and a re-lock
-(`vx lock`) is a cycle that re-reads the watched set (item 971).
+### Claimed root file changes
+
+A root file a plugin claims — a lockfile or install setting under
+`@vzn/vx-lockfile` (`pnpm-lock.yaml`, `bun.lock`, `.npmrc`, …),
+`turbo.json` under `turbo()` (item 961) — triggers a cycle, and so does
+`.vx/projects.lock.json`. Watch mode hears them because it watches the
+workspace root (non-recursively); a plugin added to the workspace
+config mid-watch counts from the cycle that loads it. The keys then
+decide which projects actually re-run: core keys no package file, so a
+lockfile edit re-keys only through its claimant
+([cache key derivation](./caching.md#cache-key-derivation)). Every
+cycle's configs come from `.vx/projects.lock.json`, so a config edit
+alone changes no command, and a re-lock (`vx lock`) is a cycle that
+re-reads the watched set (item 971).
 
 ### Constraints
 
@@ -1541,7 +1581,7 @@ re-runs itself and what it depends on.
 - `0` — clean Ctrl+C / SIGTERM exit. A cycle in flight is torn down
   first — its children, and the dev server held between cycles, get the
   signal watch received (a Ctrl-C as SIGINT; a SIGTERM or SIGHUP as SIGTERM),
-  `VX_KILL_GRACE_MS` (2 s), then SIGKILL — and the process leaves only
+  `run.killGrace` (2 s), then SIGKILL — and the process leaves only
   once it has returned, so a CI cancellation never orphans a task.
   Also `0`, with no watch, when `--affected` selects nothing: watch
   prints `vx watch: nothing affected since <ref>` and exits as `vx run`
@@ -1560,32 +1600,34 @@ the watch loop — a failed cycle just prints the framed FAILED block
 and waits for the next change. This matches `turbo watch` / `nx
 watch`.
 
-## `vx cache prune`
+## `vx cache clean`
 
 Evict old or oversized cache entries. Operates on the entries and
 `<hash>.tar.zst` artifacts of the store the workspace's index records
 (`~/.vx/<id>/cache`, shared by every checkout of the repository), or of
-`<cacheDir>` itself when the workspace names one (`cacheDir`,
+`<cacheDir>` itself when the workspace names one (`cache.dir`,
 `VX_CACHE_DIR`, `--cache-dir`).
 
-`prune` is the only `vx cache` subcommand: the statistics other runners
+`clean` is the only `vx cache` subcommand: the statistics other runners
 put under a `cache` verb — the directory, the entry count, the size —
 are part of [`vx info`](#vx-info), and `vx cache stats`, `list`, `ls`,
-`clean`, `gc`, `purge` and their neighbours say so (`list` also names
-`vx last --list`) rather than printing a bare "unknown subcommand".
+`gc` and their neighbours say so (`list` also names `vx last --list`;
+`clear`, `purge`, `reset` and `wipe` name a bare `vx cache clean`) rather than printing a bare "unknown subcommand".
 
 ```
-vx cache prune --older-than <duration>     # Drop entries last used before now - duration (up to 1h slack).
-vx cache prune --max-size <size>            # After age-based pruning, evict LRU until under <size>.
-vx cache prune ... --dry-run                # Say what either policy would reap; delete nothing.
-vx cache prune ... --format json            # { dryRun, evicted, bytesFreed, orphans, orphanBytes }
-vx cache prune ... --cache-dir <path>       # The cache a run with the same flag uses.
+vx cache clean --older-than <duration>     # Drop entries last used before now - duration (up to 1h slack).
+vx cache clean --max-size <size>            # After age-based pruning, evict LRU until under <size>.
+vx cache clean ... --dry-run                # Say what either policy would reap; delete nothing.
+vx cache clean ... --format json            # { dryRun, evicted, bytesFreed, orphans, orphanBytes }
+vx cache clean ... --cache-dir <path>       # The cache a run with the same flag uses.
+vx cache clean                              # No bound: clear the whole cache (below).
+vx cache clean --global                     # Also clear every other repository's store.
 ```
 
-At least one of `--older-than` / `--max-size` is required. Both may
-be combined: age-based eviction runs first, then LRU eviction if the
+With no bound it clears the cache ([below](#with-no-bound-clear-the-cache)).
+Both bounds may be combined: age-based eviction runs first, then LRU eviction if the
 total is still over the size cap. The same policy runs unattended at
-the end of every run when `vx.workspace.ts` declares
+the end of every run when `.vx/workspace.ts` declares
 `cacheRetention: { olderThan, maxSize }` (same spellings; see
 [schema](./schema.md)).
 
@@ -1601,7 +1643,7 @@ vx version sharing the store may still use it. A temp goes once it is an
 hour old; nothing younger than an hour is taken. Only the names vx writes are taken:
 `<hash>` is the key's 16 lowercase hex digits and the temp suffix is
 the one a save makes, so a `release.tar.zst` beside the index in a
-`cacheDir` you share is never touched (item 968). The converse, an
+`cache.dir` you share is never touched (item 968). The converse, an
 index row whose artifact is gone (deleted by hand), is dropped by the
 same prune, and its bytes count toward neither `--max-size` nor the
 evicted total: they are on no disk, and counting them evicted real
@@ -1609,7 +1651,7 @@ entries to make room for them (item 975). A row used within the hour
 is kept until a later prune, but its bytes are left out all the same
 (item 1081). The sweep runs on every prune, under
 either flag, and reports separately from the policy's evictions. A
-workspace's `cacheRetention` runs it too, at the end of a run, at most
+workspace's `cache.retention` runs it too, at the end of a run, at most
 once an hour even when nothing the index holds is due (the policy sums
 index rows, so orphans alone never make it due).
 
@@ -1626,23 +1668,24 @@ write `10G`, or `10B` when bytes really are the unit.
 
 **A zero bound is rejected.** `--max-size 0` and `--older-than 0d` would
 evict every entry in the cache, which is far more often a
-computed-to-zero retention than an intent — and no flag combination
-expresses "wipe the cache" (running with neither flag is an error, not a
-full prune). Delete the cache store `vx info` names when that is really
-what you want: the entries live there, not in the workspace's `.vx`.
+computed-to-zero retention than an intent. `vx cache clean` with no
+bound clears the whole cache when that is really what you want.
 
 ```
-$ vx cache prune --older-than 30d
-Pruned 42 entries (1.3 GB freed)
+$ vx cache clean --older-than 30d
+✓ vx cache clean  freed 1.3 GB
+
+  42 entries
 
-$ vx cache prune --older-than 7d --max-size 500M
-Pruned 18 entries (320 MB freed)
+$ vx cache clean --older-than 30d      # after a SCHEMA_VERSION bump
+✓ vx cache clean  freed 1.3 GB
 
-$ vx cache prune --older-than 30d      # after a SCHEMA_VERSION bump
-Pruned 0 entries (0 B freed), reaped 42 orphaned artifacts (1.3 GB)
+  42 orphaned artifacts
 
-$ vx cache prune --older-than 30d --dry-run
-Would prune 42 entries (1.3 GB), would reap 3 orphaned artifacts (12 MB)
+$ vx cache clean --older-than 30d --dry-run
+› vx cache clean  would free 1.3 GB (dry run)
+
+  42 entries · 3 orphaned artifacts
 ```
 
 `--dry-run` picks the victims under the same policy and counts the
@@ -1666,53 +1709,134 @@ artifact that vanishes before its restore is a miss, and the task runs
 Exit codes:
 
 - `0` — pruning completed (zero or more entries evicted). A workspace
-  that never ran has no cache: `Pruned 0 entries (0 B freed)`, and
-  nothing is created.
+  that never ran has no cache: `› vx cache clean  nothing to free`,
+  and nothing is created.
 - `1` — parse error, missing policy, or workspace-discovery error.
 
-`vx cache prune` resolves the workspace root from cwd and honors a
-`defineWorkspace({ cacheDir })` override — it prunes the same
+`vx cache clean` resolves the workspace root from cwd and honors a
+`defineWorkspace({ cache: { dir } })` override — it prunes the same
 directory a run would use. `--cache-dir <path>` (cwd-relative, as on
 `vx run`) names another one, so a run that wrote elsewhere can be
 pruned there.
 
-## `--frozen` (run flag)
-
-`vx run ... --frozen` loads configs from the committed `vx-lock.json`
-instead of evaluating them — CI reproducibility mode. Plain `vx run`
-always evaluates live (a byte hash can't see a config's import
-closure, so silently consuming the lock locally would risk stale
-freezes). `--frozen` errors only when no lock exists or a project
-is missing from it — it performs NO staleness checks of its own:
-run `vx lock --check` first in the pipeline; that audit re-evaluates
-everything, making any per-run re-check redundant.
+### With no bound: clear the cache
+
+`vx cache clean` with neither `--older-than` nor `--max-size` clears
+the whole cache: the cache directory (`.vx/cache`, or `cache.dir` /
+`--cache-dir`: the index and this workspace's run history, so `vx last`
+and `vx why` start over) and the store its index names, where the
+entries live (`~/.vx/<id>/cache`, shared by this repository's
+checkouts, so their entries go too). `--global` also clears every other
+repository's store under `~/.vx` (`~/.vx/*/cache`); it takes no bound
+and no `--cache-dir`. `.vx/workspace.ts`, the lock and `.vx/.gitignore`
+sit outside them and stay; a `cache.dir` that holds them (`.vx`, the
+workspace root) is refused. A `cache.dir` you named may be shared
+(`build/`, `~/.cache`), so there only what vx wrote goes (the index,
+its artifacts, run history, its `*` `.gitignore`); your own files stay,
+and the directory goes only if that empties it. A directory with no
+`cache.db` is not a vx cache and is left alone, and the store an index
+names goes only if it is one (`.vx/<id>/cache` holding a `store.db`): the
+index is a file in the checkout, which a commit or a restored CI cache
+could point at any directory. A workspace that never ran says
+`› vx cache clean  nothing to free`. The next run misses every task once
+and saves again.
+
+```
+$ vx cache clean
+✓ vx cache clean  freed 1.4 GB
+
+  .vx/cache
+  /home/me/.vx/3f2a9c01b4d5e6f7/cache
+
+$ vx cache clean --global --dry-run
+› vx cache clean  would free 3.1 GB (dry run)
+
+  .vx/cache
+  /home/me/.vx/3f2a9c01b4d5e6f7/cache
+  /home/me/.vx/9b8e7d6c5a4f3e2d/cache
+```
+
+It waits for a `vx run` on this workspace to finish first (the run's
+lock), as a trim does. With `--format json` it prints
+`{ dryRun, cleared, bytesFreed }` (`schemas/cache.json`), `cleared`
+listing the directories.
+
+## Runs read the lock
+
+Every run, `vx watch` cycle, `--affected` selection and the picker takes
+its projects and their configs only from the committed
+`.vx/projects.lock.json` (owner, 2026-10-14). A run never walks for
+configs, never evaluates one, never checks the graph rules
+(`run.rules`) and never writes the lock: only `vx lock` does. With no
+lock, a run fails with `no lock: run \`vx lock\``. A run trusts the
+lock: it performs NO staleness check, so after adding or editing a
+config, run `vx lock`. In a pipeline, `vx lock --check` first re-evaluates every
+config and checks the rules.
 
 ## `vx lock`
 
-Freeze every project's **resolved** config into `vx-lock.json` at the
-workspace root. Configs are programs; `vx lock` evaluates them in the
-current environment and stores the post-evaluation objects plus a
-content hash of each config file. "Every project" is the set a run
-sees, a plugin's `discover` stage included (X-143).
-
-```
-vx lock              # Evaluate all vx.config.* now; write vx-lock.json.
-vx lock --check      # Audit: hash checks + full re-evaluation vs the lock. Exit 1 on drift.
+Find every project, and freeze each one's **resolved** config into
+`.vx/projects.lock.json` at the workspace root. A project is a directory
+holding a `vx.config.*`, in any language: `vx lock` lists them with git
+(`git ls-files`, tracked and untracked, git's ignore rules applied; a
+nested repository's own configs too), or walks the tree outside git,
+and leaves out any under a nested `.vx/workspace.*`. Configs are
+programs; `vx lock` evaluates them in the current environment and
+stores the post-evaluation objects, by directory (version 3; a lock an
+earlier vx wrote is refused, "re-run `vx lock`"). A project is named by
+its config's `name`, else by a plugin's `discover` stage (vx-lockfile
+gives `package.json`'s `name`), else by its root-relative path (`//` for
+the root); two projects of one name are refused naming both
+directories. The plugin `discover` stage runs here as in a run, and may
+add directories (X-143). Before writing, it
+builds the graph of every task the workspace declares, `graph` stage
+included, and checks the graph rules (`run.rules`), which no run
+checks, `dependencies` (which projects a project may depend on,
+`VX_E_DEPENDENCY_RULE`) among them: a broken one prints `✗ vx lock  lock not written`
+with the rule's refusal under it and writes nothing.
+
+```
+vx lock              # Evaluate all vx.config.* now; write .vx/projects.lock.json.
+vx lock --check      # Audit: full re-evaluation vs the lock. Exit 1 on drift.
 vx lock --check --format json   # The audit as {upToDate, audited, notAudited, problems}.
 ```
 
-Plain runs ALWAYS evaluate live — the lock's existence changes
-nothing. Only `vx run --frozen` consumes it: configs come from the
-lock with no evaluation and no staleness checks of its own (frozen-env
+**When to run it.** Run `vx lock` and commit `.vx/projects.lock.json` after
+editing any `vx.config.*` or `.vx/workspace.*`, after updating
+dependencies or plugins, and after changing a file a config imports.
+Runs read their configs from the lock, so until then they keep the old
+ones. `vx lock --check` as CI's first step fails a stale lock.
+The full workflow: the site's CI guide and `examples/ci`.
+
+`.vx/projects.lock.json` is minified: it is the one file vx reads, and it loads
+faster that way (10,000 projects: 15.6 ms against 22.5 ms pretty). For
+review, `vx lock` also writes each project's resolved config (plugins
+applied), pretty, to `vx.lock.json` beside its `vx.config`; vx never reads
+it, it is no task's input, and `lock.reviewFiles: false`
+(`VX_LOCK_REVIEW_FILES`) turns it off. `vx lock` also writes
+`.vx/.gitattributes` (`projects.lock.json linguist-generated=true`) when it is
+missing, so GitHub collapses the machine lock in a diff; `vx init` does
+too, and an existing one is never edited.
+
+Every run consumes it: configs come from the
+lock with no evaluation, no staleness check and no schema validation
+of its entries, which `vx lock` validated when it wrote them (frozen-env
 semantics: env reads in a config keep their lock-time values; a
-project absent from the lock, a locked project whose config file is
-gone (X-144) or a missing lock is a hard error).
-
-`--check` is the audit: it reports changed config files via the
-stored hashes AND re-evaluates every config in the current
-environment, `Bun.deepEquals`-comparing against the frozen objects —
-catching eval-time env and import-closure drift that byte hashes
-cannot see. The CI recipe is `vx lock --check && vx run … --frozen`.
+locked directory whose config file is gone (X-144) or that this user
+may not search (EACCES, named as such), or a missing lock, is a hard error; a config added since the lock is no project until
+`vx lock`). An entry edited by
+hand into a shape `vx lock` could not write fails the run with
+`.vx/projects.lock.json is invalid, run \`vx lock\``, checked only once
+something has crashed, so a normal run pays nothing for it.
+
+`--check` is the audit: it re-evaluates every config in the current
+environment and `Bun.deepEquals`-compares it with the frozen object. A
+project that differs gets one message, whether its config, a file it
+imports or the environment it reads changed. A lock an earlier vx wrote
+fails the shape check and asks for `vx lock`. It also checks the graph rules over the configs as they
+evaluate now, and that each `vx.lock.json` is what its project resolves to
+here, and that none is left beside a deleted `vx.config` (delete that one
+yourself: vx never deletes a committed file), unless `lock.reviewFiles` is off. The CI recipe is `vx lock --check && vx run …`.
 `--format json` prints the audit as one document
 (`schemas/lock.json`, exit code unchanged; a missing lock is one of
 its `problems`); it answers `--check` only.
@@ -1722,18 +1846,18 @@ Full design: `docs/design/config-lock-2026-06.md`. A lock written by a
 A project with no `vx.config.*` — its tasks from a plugin's `project`
 stage (`turbo()` from `@vzn/vx-migrate`), or none at all — has nothing
 to freeze: the lock records nothing for it, `--check` does not audit
-it, and `--frozen` still loads its tasks live. Both verbs say how many
-such projects the workspace has (`locked 0 project configs →
-vx-lock.json (2 projects have no vx.config; their tasks are never
-frozen)`), so an empty lock on a plugin-only workspace never reads like
-an audit.
+it, and a run still loads its tasks live. Both verbs name such
+projects that have tasks (`0 project configs → .vx/projects.lock.json (no
+vx.config, so not locked: app, lib)`, five names then `and N more`),
+so an empty lock on a plugin-only workspace never reads like an audit.
+One with no task (core's default `build` aside) is not named.
 
 The lock is committed, so `vx lock` refuses to write one that holds a
 secret: a config that evaluated to the value of a secret-named variable
 (or one a task lists in `exec.env.secret`), say
 `` `--token ${process.env.API_TOKEN}` ``. It names each place
 (`a: tasks.deploy.exec.command holds $API_TOKEN`) and writes nothing.
-Masking it instead would freeze a `***` that `--frozen` runs. Let the
+Masking it instead would freeze a `***` that every run runs. Let the
 shell expand it: `$API_TOKEN` in the command, the name in
 `exec.env.passThrough` (L-42).
 
@@ -1824,8 +1948,8 @@ One-time setup, per package, on npmjs.com → package → Settings →
 Trusted Publisher → GitHub Actions: owner `vznjs`, repository `vx`,
 workflow `npm.yml`, environment left blank. Do this for `@vzn/vx`,
 `@vzn/vx-darwin-x64`, `@vzn/vx-darwin-arm64`, `@vzn/vx-linux-x64`,
-`@vzn/vx-linux-arm64` and the seven plugins: `@vzn/vx-ci`,
-`@vzn/vx-lockfile`, `@vzn/vx-mcp`, `@vzn/vx-migrate`, `@vzn/vx-otel`,
+`@vzn/vx-linux-arm64` and the six plugins: `@vzn/vx-ci`,
+`@vzn/vx-lockfile`, `@vzn/vx-migrate`, `@vzn/vx-otel`,
 `@vzn/vx-reapi` and `@vzn/vx-schedule-history`.
 
 Each platform package carries `LICENSE` and `THIRD_PARTY_NOTICES.txt`:
@@ -1854,308 +1978,180 @@ direct publishing (the `E401 token is invalid` that stopped v0.0.17).
 Every `uses:` in both workflows is pinned to a commit SHA with the
 version in a comment; bump the SHA and the comment together.
 
+## The workspace root
+
+Every verb works on one workspace: the directory whose `.vx` holds the
+nearest `.vx/workspace.ts` (or `.mts`, `.js`, `.mjs`, `.cts`, `.cjs`) from
+the working directory up. vx never looks above the git top-level (a
+worktree is its own; a submodule looks on into its superproject), and
+outside git it looks up to `/`. Nothing else marks the root: not a
+`package.json`, `pnpm-workspace.yaml` or a lockfile (owner, 2026-10-13).
+Without one, every verb but `vx init` stops with `VX_E_NO_WORKSPACE`;
+`vx init` writes one (`@vzn/vx-migrate` at the package manager's root,
+in a nested workspace the outer one does not list too). A project inside the
+root is a directory holding a `vx.config.*`, which `vx lock` finds
+(see [`vx lock`](#vx-lock)); a `discover` plugin adds others.
+
+## Which vx runs
+
+A global vx (installed with a package manager, or a compiled binary
+installed by hand) hands every call to the project's own `@vzn/vx` when
+there is one, so a project runs the version its lockfile pins (owner,
+2026-10-13). There is no opt-out. The workspace root's
+`node_modules/@vzn/vx` runs, through its
+`node_modules/.bin/vx`. One hop: the receiving vx sees `VX_HANDED_OFF`
+and does not look again. A vx never hands off to itself (the same
+package, a pnpm symlink included), nor to a `.bin/vx` another user owns
+(one planted above your checkout would run as you). An npm install's launcher does the
+walk in the shell, a test per level and no fork, and `exec`s the local
+vx; the compiled binary checks one path per level before it loads
+anything, then runs the local vx with its stdio, passes on a signal sent
+to it alone, and exits with its code. From source (`bun src/bin.ts`) vx
+never hands off.
+
+`vx --version` says when it was handed the call (`vx 0.0.640
+(/repo/node_modules/@vzn/vx-linux-x64/vx, handed off from
+/usr/local/bin/vx)`), and `vx info` shows the file that ran and who handed off
+(`vxPath`, `handedOffFrom`).
+
 ## `vx upgrade`
 
-Self-update the compiled binary in place: asks the GitHub release API
-for this platform's asset and the SHA-256 digest it publishes,
-downloads the asset, verifies the digest, and atomically replaces the
-running executable (`vx upgrade TAG` pins a specific release; default
-latest; a second tag is refused, not dropped). A download that does not match the digest replaces nothing —
-`the download did not match the release's SHA-256 … nothing replaced` —
-and a release that publishes no digest for the asset is refused before
-the download. The digest comes from the same API as the asset, so it
-proves the transfer, not who built the bytes: every release binary also
-carries a Sigstore-signed build-provenance attestation, checked with
-`gh attestation verify vx-<target> --repo vznjs/vx`. Named
-`upgrade` per CLI convention (`bun upgrade`, `deno upgrade`). Refuses
-when running from source — use `git pull` — and when the binary is
-npm's: an npm install runs the platform package's compiled binary
-under `node_modules`, and a rename over that file lasts until the next
-`npm install` puts the version npm knows back, so `vx upgrade` there
-says `this vx was installed by npm … Update with: npm install -g
-@vzn/vx@latest`. A host it cannot reach (no route, a proxy that is
-down) is one line — `could not reach api.github.com to read the
-release (…) — check the network or the proxy and re-run` — never a
-stack; so is a release document cut after the headers arrived or not
-JSON (a captive portal's page served with a 200): `could not read the
-release from api.github.com (…) — nothing replaced; …`, and an asset
-download cut the same way: `could not download the release asset from
-github.com (…) — nothing replaced; …`. A binary whose directory this
-user cannot write (a root-owned `/usr/local/bin`) is refused before the
+Brings vx to a newer release (`vx upgrade TAG` pins one, `v0.4.0` or
+`0.4.0`; default latest; a second tag is refused, not dropped), the way
+it was installed. Named `upgrade` per CLI convention (`bun upgrade`,
+`deno upgrade`). Refuses when running from source: use `git pull`.
+
+**A compiled binary installed by hand** replaces itself. It reads its
+platform package (`@vzn/vx-<os>-<arch>`) from the npm registry and
+checks npm's registry signature over `<name>@<version>:<integrity>`
+against npm's signing key, pinned in vx (key id
+`SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U`), then the
+tarball's SHA-512 against that signed integrity, and only then extracts
+`package/vx`, stages it in a fresh directory beside the binary and
+renames it over. The host that serves the tarball cannot make that
+signature, so a swapped tarball, or a document with a swapped integrity,
+is refused: `the npm registry signature for … is not valid — refusing
+to install; nothing replaced`, or `the download did not match the
+integrity npm signed … nothing replaced`. A release signed with a key
+id vx does not pin says so: `… is signed with an npm key this vx does
+not know (…) — if npm rotated its signing key, this vx's installer
+needs updating`. A release with no signature or no integrity is refused
+before the download. Every refusal comes before anything is written.
+There is no fallback to GitHub's release digest: when the registry is
+unreachable, the upgrade is refused.
+
+A host it cannot reach (no route, a proxy that is down) is one line,
+`could not reach registry.npmjs.org to read the release (…) — check the
+network or the proxy and re-run`, never a stack; so is a document cut
+after the headers or not JSON (a captive portal's page served with a
+200), and a tarball cut the same way. A binary whose directory this user
+cannot write (a root-owned `/usr/local/bin`) is refused before the
 download: `cannot write to <dir> (EACCES), where this vx lives — nothing
-downloaded; re-run as a user who can (sudo vx upgrade), …`. The new binary
-keeps the old one's mode (and, as root, its owner), and must answer
-`--version` before the upgrade reports it installed: one that does not
-start on this machine — or does not answer within 10 s — is swapped back
-for the previous vx, and the command exits 1 saying so (item 1097). On the version it already is
-it says `already at <version>` and downloads nothing; a second tag is
-refused rather than ignored; and GitHub's hourly API limit for an
-unauthenticated address is named, with its reset time, instead of a
-bare `(403)` (item 1098).
-
-Exit codes: `0` the new binary installed, or already at that version;
-`1` anything refused or swapped back: from source, from npm, a host it
-cannot reach, a directory it cannot write, a digest that does not match,
-a binary that does not start.
+downloaded; re-run as a user who can (sudo vx upgrade), …`. The new
+binary keeps the old one's mode (and, as root, its owner), and must
+answer `--version` before the upgrade reports it installed: one that
+does not start on this machine, or does not answer within 10 s, is
+swapped back for the previous vx, and the command exits 1 saying so
+(item 1097): `✓ vx upgrade  installed 0.0.2`. On the version it
+already is it says `› vx upgrade  already at <version>` and downloads
+nothing.
+
+**A vx a package manager installed** (the npm package's launcher runs
+`…/node_modules/@vzn/vx-<os>-<arch>/vx`) is upgraded by that package
+manager, never by a rename over its file, which the next install would
+undo. The path names the install:
+
+| Install                | Detected by                           | Runs                          |
+| ---------------------- | ------------------------------------- | ----------------------------- |
+| npm global             | `<prefix>/lib/node_modules`           | `npm install -g @vzn/vx@<v>`  |
+| pnpm global            | `…/pnpm/global/…`                     | `pnpm add -g @vzn/vx@<v>`     |
+| bun global             | `~/.bun/install/global`               | `bun add -g @vzn/vx@<v>`      |
+| yarn global            | `…/yarn/global/…`                     | `yarn global add @vzn/vx@<v>` |
+| a project's dependency | the package.json that lists `@vzn/vx` | its manager's add, same field |
+
+A project's package.json is the tree's root, or for a hoisted workspace
+the nearest one above the current directory that lists `@vzn/vx`. Its
+manager is its lockfile (`pnpm-lock.yaml`, `bun.lock`, `yarn.lock`,
+`package-lock.json`), else `packageManager`, else npm; the field it is
+listed in is kept (`--save-dev`, `--dev`, …), and pnpm at a workspace
+root adds `--workspace-root`. The lockfile is updated by that manager.
+Run inside a project that installs `@vzn/vx`, a global vx hands
+`vx upgrade` to the project's own (§ Which vx runs), so the project's
+dependency is what moves.
+vx prints what it runs, runs it there, and exits with an error if it
+fails:
+
+```
+› vx upgrade  0.0.1 → 0.0.2
+
+  bun add @vzn/vx@0.0.2 in /repo
+```
+
+vx never installs Node or a package manager: one not on `PATH` is refused with the command to run. A vx run from an npx or
+bunx cache has nothing installed to upgrade, and says to ask for
+`@vzn/vx@latest` instead.
+
+Exit codes: `0` installed, or already at that version; `1` anything
+refused or swapped back: from source, a cache install, a host it cannot
+reach, a directory it cannot write, a signature or integrity that does
+not verify, a binary that does not start, a package manager that failed
+or is missing.
 
 ## `vx init`
 
-In a Turbo or Nx repo (a `turbo.json`, `turbo.jsonc` or `nx.json` at
-the root) it runs `@vzn/vx-migrate`, so `vx init` is the one command
-(owner, 2026-10-08): the installed one, else this vx's version through
-`bun x` (`BUN_BE_BUN=1` makes the compiled binary that runtime). It asks a
-terminal native (a `vx.config.ts` per package, the default) or keep;
-`--native` or `--keep` answer it, and without a terminal it is native.
-`--dry`, `--format`, `--force` and `--mjs` pass through.
-
-`vx init --dry --format json` prints the plan as one JSON document
-(`schemas/init.json`), nothing written: `files` (each path and its
-whole text), `kept`, `replaced`, `todos` (a reason and its tasks),
-`notes` and `next`. In a Turbo or Nx repo it is `@vzn/vx-migrate`'s
-plan. `--format json` without `--dry`, or with `--plugin`, is refused
-(`VX_E_USAGE`).
-Run again after the native migration (a workspace file that declares
-neither `turbo()` nor `nx()`, and project configs), it says vx is already
-set up and prints the next step, exit 0, without starting
-`@vzn/vx-migrate`; `--force` regenerates the files.
-
-`vx init --keep` writes `vx.workspace.ts` declaring `turbo()` or `nx()`
-from `@vzn/vx-migrate` and nothing else: those read the repo's own
-config live, so no task is copied — a temporary start until
-`vx init --native` writes native config. `--native` or `--keep` in any
-other repo is refused. The `next:` line is one command:
-install what the file imports and is missing, with the manager the
-lockfile names (at the workspace root: pnpm's `-w`, Yarn 1's `-W`,
-which Yarn Berry lacks), then run the config's `build` (else its first task).
-An existing workspace file is kept and named unless it already
-declares the plugin; `--force` replaces it. When the repo shows a remote
-cache — turbo.json's `remoteCache`, a `.turbo/config.json` naming a
-team or token (`turbo link` writes it), or a line setting `TURBO_TOKEN` /
-`NX_SELF_HOSTED_REMOTE_CACHE_SERVER` (`NAME:` or `NAME=`, not a comment)
-in `.github/workflows/*`, `.gitlab-ci.yml` or `.circleci/config.yml`,
-and turbo.json does not say `remoteCache.enabled: false` — it
-declares `turboCache()` / `nxCache()` beside the runner and names the
-file that showed it (a kept file lacking it is told to add it); the
-plugin is inert where its variable is unset. An nx.json that connects
-Nx Cloud (`nxCloudId`, `nxCloudAccessToken`, the `nx-cloud` runner) is
-named instead: vx does not speak its wire, so runs cache locally.
-
-Anywhere else it scaffolds a workspace that comes from nowhere: one `vx.config.ts` per
-package from its `package.json` scripts, plus a `vx.workspace.ts` of
-`{ plugins: [] }`: running and caching here are the floor, so it
-declares no executor or cache, and the file carries no comment (it is
-the user's). `@vzn/vx-migrate` takes the
-same `--dry` / `--force` flags but reads a runner's config (turbo, nx);
-package.json scripts are `init`'s. A workspace with no scripts at
-all still gets the workspace file, a printed example config, and the
-next command to run. A root
-`package.json` with no `workspaces` field is single-project mode, and
-when `packages/*/package.json` files sit below it unreached, both
-`init` and a run that finds no config say so instead ("package.json
-declares no workspaces … Add "workspaces": ["packages/*"] to
-package.json and re-run") rather than "no scripts" or "run vx init". A
-workspace whose globs match no `package.json` gets a note naming them
-(M-42); a nameless member, or two sharing a name, is matched and
-named on its own line instead (M-46). When such skipped scripts are all there
-is, the report opens `no package.json scripts became tasks.` rather than
-saying there are none (M-59). When `pnpm-workspace.yaml` lists the
-members and the root `package.json`'s `workspaces` lists other globs,
-the note names the unread list (M-51): pnpm reads only the yaml, while
-bun, npm and yarn read `package.json`. With
-no `package.json` here or above, `init` says to create one (`bun init` or
-`npm init -y`) first. Every
-generated config is typed for the editor through
-`import type { ProjectConfig } from '@vzn/vx/config'` and `satisfies
-ProjectConfig` — a type-only import Bun erases, so the file loads in a
-workspace that runs the `vx` binary without the package installed. The
-workspace file takes the same form (`satisfies WorkspaceConfig`). A
-runtime `import { defineWorkspace } from '@vzn/vx'` costs nothing extra
-since 2026-09-10: the running `vx` serves its own core to that
-specifier (bin.ts registers the alias), so a config or a plugin package
-never loads a second copy, and a workspace that runs the binary needs
-no `@vzn/vx` installed for it — the type-only form is still what the
-scaffold writes, because it types the same with no import to resolve
-in an editor without the package. A workspace that imports a PLUGIN
-package at runtime without having installed it is told so, and to
-install its dependencies. `--mjs` writes the same objects as `vx.config.mjs` and
-`vx.workspace.mjs`, with no type import and no `satisfies`: a package whose
-own `tsconfig` includes every `.ts` under it compiles a `vx.config.ts`
-into its dist (TanStack/query's `tsc --build`, 2026-09-11), and an
-`.mjs` is outside that include. `@vzn/vx-migrate` takes the same flag.
-A file it writes that `.gitignore` drops (vueuse ignores
-`packages/**/*.mjs`) gets a `note:` naming it and the `!vx.config.mjs`
-line that keeps it, since a commit would leave it behind unnoticed.
-
-Each script becomes a task with its command verbatim. `build` gets
-`dependsOn: ['^build']` (a `build` that only delegates, `pnpm run
-compile`, is a group, and the edge goes on the script that does the
-work) and **no cache block** — under a
-`TODO(vx-migrate)` showing the block to add with the package's real
-inputs and outputs, and the same block commented as the task's first
-line: set the real globs and delete the `// `. A task without a cache block always runs; a block
-with EMPTY outputs is not "uncached" but a no-output task that hits on
-unchanged inputs and skips the build with nothing to restore (a deleted
-`dist` stays deleted under a green `up-to-date` run — what `init`
-generated until 2026-09-04), and a guessed `dist/**` would restore the
-wrong tree for every package that writes elsewhere. The block the TODO
-shows names `dist/**`, or the default output of the framework the command
-runs: `.next/**` minus `!.next/cache/**` for `next build`, `.output/**`
-for Nuxt, `build/**` for Remix, React Router, Create React App and
-Docusaurus, `public/**` for Gatsby, `storybook-static/**` for Storybook;
-for any other command, the directory it names with `--outDir` / `--out-dir`
-/ `-d`, else the ones it cleans first (`del-cli distribution`, `rimraf lib
-types`), unless it makes one again with `mkdir` (D-90).
-A package in a cycle of builds (nuxt's `@nuxt/nitro-server` devDepends
-on `nuxt`, which depends on it; pnpm sorts it away) gets, instead of
-`^build`, an edge to each build outside its cycle that `^build` would
-reach, and a TODO to order the cycle: `^build` there refuses the run.
-`test` / `typecheck` wait for
-`build` when the package has one (`lint` reads sources and gets no
-edge); `dev` / `start` / `serve` / `watch` /
-`preview` become persistent tasks, with a TODO to add `readyWhen` when
-another task depends on one, and so does a watcher: a `watch` segment in the script's name (`build:watch`),
-a `--watch` flag, `tsc -w` / `rollup -w`, or nodemon (D-40), and a server:
-`serve <dir>`, `http-server`, bare `vite`, a tool's `dev` / `serve` /
-`start` / `preview` verb (`next start`, `netlify dev`), or a script that
-runs such a script of its package by name (`cross-env X=1 pnpm start`) or
-through a runner (`run-p web api`, `concurrently "npm:web" "npm:api"`, D-113),
-outside quotes and not sent to the background with `&` (D-91), read past
-a launcher's `--package <name>` / `-p <name>` (`pnpm dlx --package
-netlify-cli netlify dev`, D-112). A
-script whose name no task may carry (`lint#fix`, `^up`; the schema's
-rule, item 1000) is left out with a TODO rather than written into a
-config every later command refuses, and a `__proto__` script is written
-as a computed key, since a literal `__proto__:` sets the prototype. An
-existing `vx.workspace.*` in any extension the loader reads (`.mts`
-included) is kept, and `--force` REPLACES a package's config of another
-extension (`replaced:` in the report) rather than writing a second one
-the loader would choose between by its order (item 1033). Without
-`--force`, `init` never overwrites: a package that already has a vx
-config keeps it, untouched, the rest get theirs, and the report lists
-the kept ones under `kept`, so a half-adopted workspace adopts the rest
-(M-52). `@vzn/vx-migrate` still refuses an existing config.
-
-A missing `vx.workspace.*` is not an error. A run where no package has
-a config fails before any task, exit 1:
-``vx run: no projects declare task(s): build. No package declares a vx.config — run `vx init` to write one per package from its package.json scripts.``
-
-Two npm conventions are mapped rather than copied, because copying them
-loses behaviour. `pre<x>` / `post<x>` hooks, which npm runs around `x`
-without being named, are folded into `x`'s command in that order, each
-in its own subshell, so the chain stops at the first that fails whatever
-a part holds (a `;`, an `exit`), and forwarded `--` args reach `x` alone,
-as npm hands them to the script and not its hooks (item 905), appended
-as text, so no part sees them as `$1` (X-60). The
-command is a small shell function, `vx_script`, around the three parts;
-it carries a TODO saying so; a `pre<x>` with no `x` stays a task of its own, and
-npm's lifecycle hooks (`prepack`, `prepublishOnly`, …) are never tasks.
-A member with no script to run (none, or only lifecycle hooks: a
-types-only or config package) gets no `vx.config.ts` and is named in
-the report; it is still a project, and a task declared in its own
-`vx.config.ts` runs. A package with no `build` script whose `prepack`, `prepublishOnly`,
-`prepublish` or `prepare` runs a builder (`bob build`, `tsc`, `tsup`, …)
-is named in the report, which says to add a `build` script running it
-(react-navigation's twelve packages, whose root `build` is `lerna run
-prepack`, mapped with no build at all).
-Where the package's manager runs no such hooks every `pre<x>` and
-`post<x>` is a task of its own: Yarn 2+ (the nearest `packageManager:
-yarn@2+`, or a Berry `yarn.lock`, D-31; a `packageManager` naming none of npm,
-pnpm, yarn or bun defers to the lockfile, D-96), npm under `ignore-scripts=true`
-in the `.npmrc` beside its lockfile, pnpm under
-`enable-pre-post-scripts=false` there or `enablePrePostScripts: false` in
-`pnpm-workspace.yaml` (D-33). Bun and Yarn 1 run them whatever those say.
-Under Yarn 2+ a segment's `run <script>`, Yarn's shell builtin, is written
-`yarn run <script>`: vx's shell has no `run` (D-92).
-A Yarn 2+ repo on Plug'n'Play (no `nodeLinker: node-modules` or `pnpm` in
-`.yarnrc.yml`) keeps its bins in `.pnp.cjs`, where vx's PATH finds none;
-the report says so and names `nodeLinker: node-modules` or `yarn exec
-'<command>'` (D-108).
-A script reading `$npm_package_version`, `$npm_package_name` or
-`$npm_lifecycle_event`, which every manager sets and vx does not, gets
-them under `exec.env.define`, the first two read from an imported
-`package.json` so a version bump reaches them; any other `$npm_*` it
-reads gets a TODO (D-34). Among several packages, a workspace root
-script that runs the members (`pnpm -r build`, `--filter`, `-C`, pnpm's `pn` alias
-included (D-97), Yarn's
-`--cwd` and `yarn workspace <name>`, npm's `--prefix`, npm's
-and Yarn's workspace flags, a `cd` into or above a member, turbo, nx, lerna, `vp run`, vx itself) is not mapped
-(a flag counts on the package manager, or after `node <bin> run`, and not on the program it
-runs: berry's `yarn node -r ./setup.ts` is node's `--require`, D-81; bun's
-`cd test && …` enters no member, D-83),
-nor is one that runs such a script by name (vite's `ci-docs`: `pnpm build &&
-pnpm docs-build`; through `run-s` / `run-p` / `npm-run-all` or `concurrently
-"npm:x"` too, lexical's `ci-check`, D-95), and neither is one whose name a member's task carries, so `--all` never runs
-a check twice (D-45). The rest check the whole repo (`lint: oxlint .`,
-`test: vitest`) and become the root's own tasks in a root vx.config, when
-the root has a `"name"` (vx skips a nameless root's config) and no config
-of its own; one already there, hand-written or from an earlier
-`vx init`, stays as written, `--force` included, and is listed under
-`kept`. The report names each script left out and why
-(a `pre` / `post` hook goes with its script, D-85), its examples of running
-the members spelled by the repo's manager (`--workspaces` under npm, `yarn
-workspaces foreach` under Yarn 2+), and says which;
-with nothing mapped it names the root whenever it has a script, a member
-or not (pnpm's root is not), and why: its scripts run the workspace, or
-share a member's task name (listed), or both; it tells a root with no `"name"` to add one
-first (vuejs/core), naming the scripts that would then map (react, D-87), and a root whose
-`"name"` a member also carries to rename it, since a root config would make the
-workspace refuse every run for the duplicate (insomnia, D-129). A single-package repo's root is its project and maps.
-A lone root beside a `lerna.json` (Lerna-classic: packages listed there, not
-in `workspaces`) gets a note naming the `workspaces` globs to add, Lerna's
-`packages/*` default when it lists none (D-111).
-A member whose package.json has no `name` is no project; one with a
-script is named in the report, to be given a name (remix's
-`packages/component/bench`, D-106).
-A member's script that runs another member's work (`pnpm -C ../pinia
-run build`, `yarn workspace <name>`, `-r` / `--filter`, a `cd` or `-C`
-/ `--cwd` / `--prefix` into another member) keeps its command and gets a
-TODO naming that part: the graph runs that member's task once, so name it
-under `dependsOn` and drop it from the command (pinia). A directory inside
-the member or the root is no other member.
-A script that is nothing but `npm run <other>` (`pnpm <other>`, `yarn
-<other>`, `bun run <other>`, `npm test`, `npm start`) becomes a **group**
-over `<other>` — `dependsOn` and no command — so the graph runs and
-caches the target instead of a package-manager subprocess it cannot
-see. When `build` is such a group, the task it reaches that runs a
-command takes `^build` and the cache TODO, since a group has nothing
-to cache; it and the groups on the way drop the wait on `build` a
-`typecheck` or `test` would carry, since they are the build (D-16). Bare, a package manager's own command is not a script: `bun test`
-is Bun's test runner, `bun build` its bundler, `pnpm install` and `yarn
-add` the managers' verbs, so each stays a command (item 908), and so do
-the names each manager reserves or hands on: `pnpm docs` and `pnpm
-version` (npm's), `bun deploy`, `yarn check` (D-32); `pnpm test`, `yarn
-test` and `bun lint` do run the script. Arguments, flags or a `&&`
-chain make it a real command again and
-it is left verbatim, and so is one whose target becomes no task (a
-lifecycle script, or a hook folded into another script): a group over
-it would name a task nothing defines (D-12). A verbatim chain whose
-parts run this package's own scripts (`check: pnpm run build && pnpm run
-lint`) gets a TODO naming those parts: each ran again inside the command,
-beside its own task, so `vx run check` built twice (M-41). So does a
-part that runs them through `run-s`, `run-p` or `npm-run-all`
-(`build: run-p build:*`), unless the task is persistent (M-48). Its
-order may matter, so it is not made a group.
-
-The report lists each TODO once per reason: tasks that share one are
-named together (the first five, then a count; the files carry each),
-and when no task caches it says uncommenting a TODO task's cache line
-makes the second run a hit. Its `next:` line is a command the user can type: the
-runner that started vx (`npx`, `pnpm`, `yarn`, `bunx`, read from
-`npm_config_user_agent`) with the installed `vx` bin, else the
-`@vzn/vx` package (`npx` under Yarn 1, which has no `dlx`); with no
-runner, a bare `vx`. Outside a git work tree it starts with
-`git init`, and with no script mapped with declaring a task, since the
-run would refuse without either. It runs `build`, else the first task that
-neither serves (`persistent`) nor changes the repo (`clean`, `release`,
-`publish`, `deploy`, `version`, `format`, `fix`, …), else the first task
-(react-navigation was told `vx run clean --all`).
+`vx init` reads no `package.json` (M, 2026-10-14). When the directory it
+runs in, or one above it up to the git top-level, holds a
+`package.json`, `pnpm-workspace.yaml`, `turbo.json`, `turbo.jsonc` or
+`nx.json`, it runs `@vzn/vx-migrate` there, so `vx init` is the one
+command (owner, 2026-10-08): the installed one (the nearest
+`node_modules/@vzn/vx-migrate` up from the working directory), else
+this vx's version through `bun x` (`BUN_BE_BUN=1` makes the compiled
+binary that runtime). `--dry`, `--format`, `--force`, `--mjs`,
+`--native` and `--keep` pass through, and the exit is vx-migrate's.
+vx-migrate maps a Turbo, Nx or Vite Task repo, else the `package.json`
+scripts, one `vx.config.ts` per package; writes the workspace file with
+the plugins the repo calls for (the lockfile's, a remote cache the repo
+shows); installs them; and ends with `vx lock`. Its README holds the
+rules; [`bunx @vzn/vx-migrate`](#bunx-vznvx-migrate) below sums them up.
+
+With none of those files, it writes a workspace whose one project is
+the root, at the nearest workspace root up from the working directory,
+else there:
+
+```ts
+// .vx/workspace.ts
+import { defineWorkspace } from '@vzn/vx'
+
+export default defineWorkspace({ plugins: [] })
+```
+
+```ts
+// vx.config.ts
+import { defineProject } from '@vzn/vx'
+
+export default defineProject({ tasks: {} })
+```
+
+plus `.vx/.gitignore` and `.vx/.gitattributes`. It then runs `vx lock`'s
+step, and `next:` says to declare a task and run `vx lock && vx run
+<task>`, preceded by `git init` outside a git work tree. The `@vzn/vx`
+import needs no install: the running vx serves its own core to that
+specifier (bin.ts registers the alias). A file already there is kept
+and named under `kept`; `--force` replaces it, a file of another
+extension included (`replaced`). `--mjs` writes `.vx/workspace.mjs` and
+`vx.config.mjs`. `--dry` prints the files and writes nothing;
+`--dry --format json` prints the plan as one JSON document
+(`schemas/init.json`): `files` (each path and its whole text), `kept`,
+`replaced`, `todos`, `notes` and `next`. `--native` and `--keep` answer
+a Turbo or Nx repo's question, so they are refused here. `--format json`
+without `--dry`, or with `--plugin`, is refused (`VX_E_USAGE`).
 
 `vx init --plugin <seam>` writes a plugin instead: `plugins/<seam>.ts`,
 a small runnable plugin for that seam (`executor`, `cache`,
 `telemetry`, `schedule`, `admit`, `commands`, `project`, `graph`,
 `key`), and `plugins/<seam>.test.ts`, which drives it through `run()`
 (`bun test`, with `@vzn/vx` installed). It prints the line that
-declares it in the workspace file a run reads (`vx.workspace.ts` when
+declares it in the workspace file a run reads (`.vx/workspace.ts` when
 there is none). The templates are TypeScript, so `--mjs` with
 `--plugin` is refused. An existing file is refused without
 `--force`; `--dry` names the files and writes nothing. The two files are
@@ -2163,25 +2159,35 @@ there is none). The templates are TypeScript, so `--mjs` with
 core (`src/cli/plugin-templates.ts`) and held equal by
 `tests/plugin-templates.unsafe.test.ts` (H-21).
 
-Exit codes: `0` the files written (or, with `--dry`, printed); `1` no
-`package.json` here or in a parent, a file it would write already there
-without `--force`, or a parse error (`--mjs` with `--plugin` among them).
+Exit codes: `0` the files written (or, with `--dry`, printed); `1` a
+refused flag, a parse error (`--mjs` with `--plugin` among them), or a
+plugin file already there without `--force`. Handed to
+`@vzn/vx-migrate`, the exit is its own.
 
-## `vx migrate`
+## `bunx @vzn/vx-migrate`
 
-Moved out of core on 2026-09-10: the Turbo and Nx mappers are
-`@vzn/vx-migrate`, their own package, run without a workspace file —
+Mapping a repo's own config to vx is `@vzn/vx-migrate`, its own
+package, run before a workspace file exists (it writes one); `vx init`
+runs it in any repo with a `package.json` —
 
 ```
-bunx @vzn/vx-migrate           # turbo.json, an Nx graph or vite-plus run.tasks → vx.config.ts
+bunx @vzn/vx-migrate           # turbo.json, an Nx graph, vite-plus run.tasks, else package.json scripts → vx.config.ts
 bunx @vzn/vx-migrate --dry     # print the generated files instead of writing
 bunx @vzn/vx-migrate --force   # overwrite existing vx.config.* / vx-preset.ts
-bunx @vzn/vx-migrate --from nx # disambiguate when both runners are checked in
-```
-
-— and `package.json` scripts are `vx init` (above). Typing `vx migrate`
-prints that pointer and exits 1. What the package writes reads exactly
-like what `vx init` writes: both hand a plan to core's migration seam
+bunx @vzn/vx-migrate --from nx # disambiguate when several sources are checked in (turbo, nx, vite-task, scripts)
+```
+
+— In a Turbo or Nx repo it asks a terminal native (a `vx.config.ts`
+per package, the default) or keep (a workspace file declaring `turbo()`
+or `nx()`, which read the repo's config live); `--native` or `--keep`
+answer it, and without a terminal it is native. Both declare
+`turboCache()` / `nxCache()` when the repo shows a remote cache
+(turbo.json's `remoteCache`, a `turbo link`ed `.turbo/config.json`, or
+a CI file setting `TURBO_TOKEN` / `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`),
+and name Nx Cloud, whose wire vx does not speak. Elsewhere each
+package's `package.json` scripts become its tasks, and the workspace
+file declares the `@vzn/vx-lockfile` plugin for the root's lockfile.
+What the package writes goes through core's migration seam
 (`applyMigration`, exported from `@vzn/vx`), which renders, guards
 against overwriting, writes and reports. The mapping rules live in the
 package's README.
@@ -2196,7 +2202,7 @@ none is dropped in silence. An Nx flag's camelCase spelling (`--nxBail`,
 kebab-case row. A `[=<bool>]` row takes `=true` (the flag bare) and `=false` (left out), as Turbo's and Nx's parsers do. `vx run-many` and `vx affected` name the
 `vx run` that does the same, and the other verbs a hand types from
 either tool name what does it here: `graph` (`--graph`), `ls`
-(`vx show`), `query` (`--dry=json`), `reset` (`vx cache prune`), and
+(`vx show`), `query` (`--dry=json`), `reset` (`vx cache clean`), and
 `daemon`, `login`, `logout`, `link` and `unlink`, which vx has no use
 for. Nx's `project:target` (`vx run web:build`,
 when `web` declares `build`) is answered with `vx run web#build`: from
@@ -2222,8 +2228,8 @@ copy to the source.
 | turbo  | `--summarize[=<bool>]`                            | same    | `--summarize[=<path>]`                                                                                                                            |
 | turbo  | `--output-logs=new-only`                          | refuse  | use `--output-logs=full` (a hit replays its log) or `errors-only`                                                                                 |
 | turbo  | `--output-logs <v>`                               | same    | `--output-logs full\|errors-only\|hash-only\|none`                                                                                                |
-| turbo  | `--no-cache`                                      | same    | `--no-cache` reads nothing either; Turbo's (reads, no writes) is `--cache local:r,remote:r`                                                       |
-| turbo  | `--cache <v>`                                     | same    | `--cache local:rw,remote:r`                                                                                                                       |
+| turbo  | `--no-cache`                                      | same    | `--no-cache` reads nothing either; Turbo's (reads, no writes) is `--cache-policy local:r,remote:r`                                                |
+| turbo  | `--cache <v>`                                     | alias   | `--cache-policy`, the same spec (`local:rw,remote:r`)                                                                                             |
 | turbo  | `--cache-dir <v>`                                 | same    | `--cache-dir <path>`                                                                                                                              |
 | turbo  | `--profile`                                       | same    | `--profile[=<path>]` (Chrome trace)                                                                                                               |
 | turbo  | `--only`                                          | alias   | `--exclude-dependencies`                                                                                                                          |
@@ -2234,13 +2240,13 @@ copy to the source.
 | turbo  | `--no-update-notifier`                            | refuse  | vx prints no update notice: drop it                                                                                                               |
 | turbo  | `--skip-infer`                                    | refuse  | vx runs the binary it is: drop it                                                                                                                 |
 | turbo  | `--root-turbo-json <v>`                           | refuse  | `turbo()` reads the `turbo.json` at the workspace root: move it there                                                                             |
-| turbo  | `--experimental-otel-*`                           | refuse  | telemetry is a plugin: `otel()` from @vzn/vx-otel in vx.workspace.ts                                                                              |
+| turbo  | `--experimental-otel-*`                           | refuse  | telemetry is a plugin: `otel()` from @vzn/vx-otel in .vx/workspace.ts                                                                             |
 | nx     | `--parallel <n>`                                  | alias   | `--concurrency <n>` (`--parallel=false` is 1)                                                                                                     |
 | turbo  | `--parallel`                                      | refuse  | vx always honours `dependsOn`; `--concurrency <n>` sets how many run at once                                                                      |
 | turbo  | `--scope <v>`                                     | refuse  | use `--filter <pkg>`                                                                                                                              |
 | turbo  | `--since <v>`                                     | refuse  | use `--filter '[<ref>]'` or `--affected=<ref>`                                                                                                    |
-| turbo  | `--remote-only[=<bool>]`                          | refuse  | use `--cache local:,remote:rw`                                                                                                                    |
-| turbo  | `--remote-cache-read-only[=<bool>]`               | refuse  | use `--cache local:rw,remote:r`                                                                                                                   |
+| turbo  | `--remote-only[=<bool>]`                          | refuse  | use `--cache-policy local:,remote:rw`                                                                                                             |
+| turbo  | `--remote-cache-read-only[=<bool>]`               | refuse  | use `--cache-policy local:rw,remote:r`                                                                                                            |
 | turbo  | `--anon-profile`                                  | refuse  | use `--profile[=<path>]`; vx has no redacting variant, so read it before sharing it                                                               |
 | turbo  | `--cache-workers <v>`                             | refuse  | vx sizes its own cache I/O: drop it                                                                                                               |
 | turbo  | `--cwd <v>`                                       | refuse  | run vx from that directory: `cd <dir> && vx run …`                                                                                                |
@@ -2253,7 +2259,7 @@ copy to the source.
 | turbo  | `--preflight`                                     | refuse  | set `turboCache({ preflight: true })` or `TURBO_PREFLIGHT=1`                                                                                      |
 | turbo  | `--remote-cache-timeout <v>`                      | refuse  | set `turboCache({ timeoutMs })` or `TURBO_REMOTE_CACHE_TIMEOUT`                                                                                   |
 | turbo  | `--single-package`                                | refuse  | a repo with no workspaces is one project already: drop it                                                                                         |
-| turbo  | `--token <v>`, `--team <v>`, `--api <v>`          | refuse  | a remote cache is a plugin: `turboCache()` from @vzn/vx-migrate in vx.workspace.ts reads TURBO_TOKEN / TURBO_TEAM / TURBO_API                     |
+| turbo  | `--token <v>`, `--team <v>`, `--api <v>`          | refuse  | a remote cache is a plugin: `turboCache()` from @vzn/vx-migrate in .vx/workspace.ts reads TURBO_TOKEN / TURBO_TEAM / TURBO_API                    |
 | turbo  | `--no-daemon`, `--daemon`                         | refuse  | vx has no daemon: drop it                                                                                                                         |
 | turbo  | `--ui <v>`, `--log-order <v>`, `--log-prefix <v>` | refuse  | vx frames each task’s output: `--output-logs <mode>` sets how much                                                                                |
 | nx     | `-t <v>`, `--targets <v>`, `--target <v>`         | alias   | the task names, positional: `vx run build test`                                                                                                   |
@@ -2270,13 +2276,13 @@ copy to the source.
 | nx     | `--uncommitted`, `--untracked`                    | refuse  | use `--affected=HEAD` (the working tree against the last commit)                                                                                  |
 | nx     | `--max-parallel <v>`                              | alias   | `--concurrency <n>`                                                                                                                               |
 | nx     | `--exclude-task-dependencies[=<bool>]`            | alias   | `--exclude-dependencies`                                                                                                                          |
-| nx     | `--skip-remote-cache[=<bool>]`                    | alias   | `--cache local:rw,remote:`                                                                                                                        |
+| nx     | `--skip-remote-cache[=<bool>]`                    | alias   | `--cache-policy local:rw,remote:`                                                                                                                 |
 | nx     | `--verbose`                                       | refuse  | use `--verbosity <n>` (1 adds the summary table)                                                                                                  |
 | nx     | `--files <v>`                                     | refuse  | vx asks git what changed: `--affected=<base>`                                                                                                     |
 | nx     | `--batch`                                         | refuse  | vx runs one command per task: drop it                                                                                                             |
 | nx     | `--dte`, `--use-agents`                           | refuse  | vx distributes nothing: drop it                                                                                                                   |
 | nx     | `--nx-ignore-cycles`                              | refuse  | vx refuses a task cycle by name: break it                                                                                                         |
-| nx     | `--runner <v>`                                    | refuse  | a remote cache is a plugin: `nxCache()` from @vzn/vx-migrate in vx.workspace.ts                                                                   |
+| nx     | `--runner <v>`                                    | refuse  | a remote cache is a plugin: `nxCache()` from @vzn/vx-migrate in .vx/workspace.ts                                                                  |
 | nx     | `--skip-sync`                                     | refuse  | vx never runs sync generators: drop it                                                                                                            |
 | nx     | `--tui`, `--no-tui`, `--tui-auto-exit`            | refuse  | vx frames each task’s output: `--output-logs <mode>` sets how much                                                                                |
 | nx     | `--no-cloud`                                      | refuse  | vx has no cloud: drop it                                                                                                                          |
@@ -2290,8 +2296,9 @@ copy to the source.
 
 ## Machine-readable output
 
-`vx show`, `vx info`, `vx why`, `vx last` and `vx cache prune` take
-`--format json`. Each prints one JSON document whose shape is a
+`vx show`, `vx info`, `vx why`, `vx last` and `vx cache clean` take
+`--format json`. Each prints one JSON document on one line, as
+`vx run --format json` does, whose shape is a
 checked-in JSON Schema (draft 2020-12) shipped with the package:
 `schemas/show.json`, `schemas/info.json`, `schemas/why.json`,
 `schemas/last.json`, `schemas/cache.json`
@@ -2323,27 +2330,30 @@ prose on stderr do not change. Branch on the code; the message may change.
 
 #### `VX_E_USAGE`
 
-A flag, argument or selection the verb does not take. The message names
-it, and a close spelling the verb does take when there is one;
+A flag, argument, selection or `VX_*` environment value the verb does
+not take. The message names it, and a close spelling the verb does take when there is one;
 `vx <verb> --help` lists every flag.
 
 #### `VX_E_UNKNOWN_COMMAND`
 
 No verb of that name here, core's or a declared plugin's. `vx --help`
 lists core's verbs. A plugin's verb exists once its plugin is in
-`vx.workspace.ts` `plugins`; a task runs as `vx run <task>`.
+`.vx/workspace.ts` `plugins`; a task runs as `vx run <task>`.
 
 #### `VX_E_UNKNOWN_TASK`
 
 No project in scope declares a requested task. The message lists the
 tasks it found; `vx show --format json` lists each project's. Check the
 spelling, and the scope: `--filter`, `--all`, or the project the working
-directory is in.
+directory is in. A run reads its configs from the lock, so a task
+added to a `vx.config` since the last `vx lock` is not there yet: run
+`vx lock`.
 
 #### `VX_E_UNKNOWN_PROJECT`
 
 `vx show` names a project the workspace does not have. A project is named
-by its `package.json` `name`; `vx show --format json` lists them.
+by its config's `name`, else by a plugin (a lockfile plugin names it from
+its `package.json`), else by its directory; `vx show --format json` lists them.
 
 #### `VX_E_NO_HISTORY`
 
@@ -2357,20 +2367,24 @@ the task once (`vx run <task>`); history is this checkout's own.
 
 #### `VX_E_CONFIG`
 
-A `vx.config.*` or `vx.workspace.*` that does not load or is refused. The
+A `vx.config.*` or `.vx/workspace.*` that does not load or is refused. The
 message names the file and the field; fix that field
 (`vx docs <field>` prints its reference). `vx info --format json` lists
-every config error at once.
+every config error at once. A project config's refusal is `vx lock`'s,
+not a run's: a run never evaluates one.
 
 #### `VX_E_CYCLE`
 
 The task graph has a cycle. The message names the loop; drop one of its
 `dependsOn` edges.
+`vx lock` refuses it, not a run: a run trusts the graph the lock holds.
 
 #### `VX_E_NO_WORKSPACE`
 
-No workspace root above the working directory. Run vx inside the repo,
-or create a `package.json` and run `vx init`.
+No `.vx/workspace.*` in the working directory or a parent, up to the git
+top-level (a file above the checkout never counts). The file marks the
+workspace root, so run `vx init` to create one. Outside git, one another
+user owns does not count (`security.md`); the message names it.
 
 #### `VX_E_CACHE_VERSION`
 
@@ -2387,7 +2401,7 @@ message is that plugin's or check's: do what it says.
 #### `VX_E_FS`
 
 The file system refused a write: permissions, a full disk. The message
-names the path. Free space (`vx cache prune --max-size <size>` trims the
+names the path. Free space (`vx cache clean --max-size <size>` trims the
 cache) or grant the write, then re-run.
 
 #### `VX_E_FDS`
@@ -2416,12 +2430,22 @@ A task's `dependsOn` names a task or project that is not declared, or uses
 a form vx does not take (a bare wildcard, a negation, a pattern in
 `pkg#task`). The message names the task and the entry: declare the
 target, fix its spelling, or drop the entry.
+`vx lock` refuses it, not a run: a run trusts the graph the lock holds.
+
+A `^task` with no edge source is refused too: ``<id>: ^build needs
+project edges; add pnpm()/bun()/npm()/yarn() or a plugin that returns
+`deps` ``. Core reads no edge from a manifest, so with no plugin
+returning `deps` every `^` would resolve to nothing and fold no
+upstream into the key. Declare the lockfile plugin in
+`.vx/workspace.ts` (or a plugin of your own that returns `deps`); a run
+refuses it as well when the plugin left the workspace after the lock.
 
 #### `VX_E_OUTPUT_OVERLAP`
 
 Two tasks declare overlapping outputs with no `dependsOn` edge between
 them, so whichever runs second deletes the other's files. Give each task
 its own output path, or make one depend on the other.
+`vx lock` refuses it, not a run: a run trusts the graph the lock holds.
 
 #### `VX_E_INPUT_IS_OUTPUT`
 
@@ -2430,6 +2454,13 @@ a run, so it would delete its sources) or another task's (its key must
 not read them; `dependsOn` already cascades). Exclude the outputs from
 the inputs with a `!` glob, as the message shows, or declare no outputs
 for a task that rewrites files in place.
+`vx lock` refuses it, not a run: a run trusts the graph the lock holds.
+
+#### `VX_E_DEPENDENCY_RULE`
+
+`vx lock` found a project depending on one a `run.rules.dependencies`
+rule denies or does not allow. A header counts the broken edges and
+each indented line under it names both projects and the rule. Drop the dependency, or change the project's tags or the rule.
 
 #### `VX_E_INTERNAL`
 
@@ -2449,14 +2480,13 @@ product verb to it under a notice.
 
 ## `vx show`
 
-Introspect the workspace's **live resolved configs** — what a run
-would see right now. Configs load through the same path a run uses,
-plugin `config` and `project` stages included, so a package a plugin
-gives tasks to (`turbo()` or `nx()` from `@vzn/vx-migrate`, a
-temporary start toward native config) shows them; cached
-evaluations are served from the local cache like a run's. `vx show`
-never reads `vx-lock.json` (the lock is already the frozen JSON — open
-it directly if you want the frozen view).
+Introspect the workspace's **resolved configs** — what a run would see
+right now. Configs load through the same path a run uses: from
+`.vx/projects.lock.json`, plugin `config` and `project` stages applied,
+so a package a plugin gives tasks to (`turbo()` or `nx()` from
+`@vzn/vx-migrate`, a temporary start toward native config) shows them.
+`vx show` evaluates no config: an edit shows after `vx lock`, and with
+no lock it refuses as a run does (`no lock: run \`vx lock\``).
 
 ```
 vx show                          # list every project
@@ -2484,23 +2514,25 @@ Nx's spellings name these: `vx show projects` (when no project or task
 has that name) and `vx show project <name>` say `vx show` and
 `vx show <name>`.
 
-No target: one line per project — name, root-relative dir, task count,
-and a `(no vx config)` marker for config-less packages; one whose
-tasks all come from plugins reads `N tasks (no vx config; from
-plugins)`, and one a configured project depends on reads `1 task (no
-vx config; default build)`: a run loads it for that dependant's
-`^build` (X-48). A project's `tags` follow in brackets. With `--format json`
+No target: a table, one row per project — name, root-relative dir,
+task count, and `no vx config` for config-less packages; one whose
+tasks all come from plugins reads `N tasks from plugins (no vx
+config)`, and one a configured project depends on reads `1 task,
+default build (no vx config)`: a run loads it for that dependant's
+`^build` (X-48). A `tags` column appears when any project has tags. With `--format json`
 it's an array of `{ name, dir, tags: string[], tasks: string[] }`.
 
 ```
 $ vx show
-app   packages/app   3 tasks  [scope:web]
-bare  packages/bare  (no vx config)
+  project  dir            tasks         tags
+  app      packages/app   3 tasks       scope:web
+  bare     packages/bare  no vx config
 ```
 
-Under its header `vx show <project>` prints its `tags`.
-`vx show <project>` prints a block per task with every field the run
-reads: description, command (`(group)` for group tasks), `dependsOn`,
+A report naming the project opens it: its `dir`, its `tags`, and
+`config  none` for a package with no config file. Then
+`vx show <project>` prints a block per task, headed by its
+`project#task`, with every field the run reads: description, command (`(group)` for group tasks), `dependsOn`,
 `timeout`, `retries`, `env.passThrough` / `env.define` / `env.secret`,
 `remote`, `sandbox`, `persistent`, `interactive` (`yes` / `no`), and the
 cache block
@@ -2518,15 +2550,15 @@ list and `vx show <project>`, but `vx show build`, like
 
 ```
 $ vx show app#build
-app — packages/app
 
-build
-  description:   compile the app
-  command:       tsc -b
-  dependsOn:     ^build
-  inputs.files:  src/**
-  inputs.env:    NODE_ENV
-  outputs.files: dist/**
+─ app#build ──────────────────────────────────────────────────
+  dir            packages/app
+  description    compile the app
+  command        tsc -b
+  dependsOn      ^build
+  inputs.files   src/**
+  inputs.env     NODE_ENV
+  outputs.files  dist/**
 ```
 
 Unknown project / task names exit `1` with the same near-miss hint
@@ -2551,7 +2583,7 @@ share `TMPDIR`: a `nix develop` shell sets its own.
 Every verb: a path vx must write that this user cannot (`EACCES`,
 `EPERM`, `EROFS` — a read-only checkout, another user's files) or that
 the disk has no room for (`ENOSPC`, `EDQUOT`) exits 1 with one line
-naming the path, `vx: EACCES: permission denied, open '…/vx-lock.json'
+naming the path, `vx: EACCES: permission denied, open '…/.vx/projects.lock.json'
 — a path vx must write is not writable by this user` (or `— the disk
 that path is on is full`), never a stack. Inside a run the task's line
 says the same. A process out of file descriptors (`EMFILE`, `ENFILE`;
@@ -2562,38 +2594,36 @@ is out of file descriptors; raise the limit (ulimit -n 4096) and re-run`.
 
 Workspace doctor — one screen of facts for bug reports and sanity
 checks. The task count and the sandbox row's declared count come from
-the same load a run uses, plugin stages included; a config that fails
-to load counts as zero in both rather than failing the doctor, every
-other project still counts as a run loads it, and the broken one is
-named (`12 (34 tasks · 1 config did not load)`, then a `config errors`
-row per config with the message `vx run` stops on):
+the same load a run uses: the lock, plugin stages included. `vx info`
+evaluates no config; with no lock, or one a run would refuse, both
+counts are zero and `projects lock` says `no` — a broken config is
+`vx lock`'s to report:
 
 ```
 $ vx info
-vx:               0.0.0
-bun:              1.4.2
-git:              2.53.0
-git status cache: core.fsmonitor, core.untrackedCache off
-workspace root:   /work/repo
-projects:         12 (34 tasks)
-plugins:          2 — @vzn/vx-reapi (executor, cache); @vzn/vx-otel (telemetry)
-workers:          2 — cgroup CPU quota 2 of 8 cores
-memory:           13 GB usable — cgroup limit; the machine has 16 GB
-cache dir:        /work/repo/.vx/cache
-cache store:      /home/me/.vx/3f2a9c1e7b4d5a60/cache
-cache versions:   keys vx-cache-v42 · index schema v34
-cache entries:    42 (1.3 GB)
-orphans:          3 artifacts (12 MB) the index does not know — `vx cache prune` reaps them
-task runs (24h):  7 (5 cache hits)
-flaky tasks:      1 — web#test (3 of 11 runs failed on unchanged inputs)
-sandbox:          available (9 tasks declare exec.sandbox)
-vx-lock.json:     yes
-```
-
-- `git` shows `(not found)` when the binary is missing; a broken
-  project config contributes zero tasks instead of failing the
-  printout, and the `config errors` row (present only then) names it
-  with the loader's message — the same line `vx run` would stop on.
+
+─ vx info ────────────────────────────────────────────────────
+  vx                0.0.0
+  bun               1.4.2
+  git               2.53.0
+  git status cache  core.fsmonitor, core.untrackedCache off
+  workspace root    /work/repo
+  projects          12 (34 tasks)
+  plugins           2 — @vzn/vx-reapi (executor, cache); @vzn/vx-otel (telemetry)
+  workers           2 — cgroup CPU quota 2 of 8 cores
+  memory            13 GB usable — cgroup limit; the machine has 16 GB
+  cache dir         /work/repo/.vx/cache (8.2 MB, this workspace's run history)
+  cache store       /home/me/.vx/3f2a9c1e7b4d5a60/cache (1.3 GB, shared by this repo's checkouts)
+  cache versions    keys vx-cache-v43 · index schema v38
+  cache entries     42 (1.3 GB)
+  orphans           3 artifacts (12 MB) the index does not know — `vx cache clean` reaps them
+  task runs (24h)   7 (5 cache hits)
+  flaky tasks       1 — web#test (3 of 11 runs failed on unchanged inputs)
+  sandbox           available (9 tasks declare exec.sandbox)
+  projects lock     yes
+```
+
+- `git` shows `(not found)` when the binary is missing.
 - `git status cache`: vx runs ONE `git status` per run to find dirty
   and untracked files, and on a large tree that walk is the warm run's
   critical path. git's `core.fsmonitor` (a daemon that watches the
@@ -2613,13 +2643,13 @@ exec.sandbox and will fail` says it first: root inside a container
 unreported`: the sandbox still enforces, but a task that tolerates a
   denied read passes and caches with no word of it. The `--format json` fact is
   `sandbox.untraced`, the reason or `null`.
-- `plugins` names every plugin `vx.workspace.*` declares and the seams
+- `plugins` names every plugin `.vx/workspace.*` declares and the seams
   each fills, in pipeline order (`config`, `discover`, `project`, `graph`, `key`,
   `fingerprint`, `schedule`, `admit`, `executor`, `cache`, `telemetry`,
-  `setup`, `commands`), or `none`. It reads the declarations: a plugin
+  `output`, `setup`, `commands`), or `none`. It reads the declarations: a plugin
   that declines a task at run time still lists its seam here.
 - `workers` is the count a run defaults to and where it comes from:
-  `vx.workspace.ts`'s `concurrency` when set, else the cores this
+  `.vx/workspace.ts`'s `run.concurrency` when set, else the cores this
   process may use — the CPU count, capped by the cgroup CPU quota a
   container runs under (`8 — the CPU count`, `2 — cgroup CPU quota 2 of
 8 cores`). `memory` is what a memory-packing policy budgets
@@ -2640,15 +2670,22 @@ unreported`: the sandbox still enforces, but a task that tolerates a
   the hits are a share of it: three `vx run` of two tasks are six. An
   invocation is what `vx last` calls a run; `vx last --list` counts
   those.
-- `cache store` is where the entries and their artifacts live: the
-  store every workspace of this user shares (`docs/caching.md`), or
-  `none: the cache dir holds the entries` when the workspace names its
-  cache dir. Before a first run it is the store a run would open.
+- `cache dir` holds the index and this workspace's run history; its size
+  is on disk. `cache store` is where the entries and their artifacts
+  live: the store shared by this repo's checkouts (`docs/caching.md`),
+  with its size on disk, or `none: the cache dir holds the entries` when
+  the workspace names its cache dir. Before a first run it is the store a
+  run would open. A bare `vx cache clean` frees both sizes.
 - `cache entries` counts the entries and their size; with a
   `cacheRetention.maxSize` it reads against it (`812 (3.0 GB of 10 GB,
 30%)`), and a `cache retention` row says what each run's end evicts.
   Paths under the home directory print as `~/…`; the JSON keeps them
   absolute.
+- `cache policy` is the policy a `vx run` takes when no flag names one,
+  and where it comes from (`VX_CACHE_POLICY`, `.vx/workspace`'s `cache.policy`,
+  or the default, every layer on, remote writes off off CI); `cache scope`
+  is the same for the scope (`VX_CACHE_SCOPE`, `cache.scope`, which
+  `github()` may set, or none: the default keys).
 - `cache versions` are the two constants a bug report needs and the
   reset notice names: the key prefix (`CACHE_VERSION`; a bump orphans
   every entry) and the index schema (`SCHEMA_VERSION`; a mismatch drops
@@ -2657,19 +2694,23 @@ unreported`: the sandbox still enforces, but a task that tolerates a
   save temps the index has no row for, older than an hour (what a
   `SCHEMA_VERSION` reset leaves behind; a fresh one is a save in
   flight). A task that asks for one's key again indexes it and hits;
-  the rest only `vx cache prune` reclaims, so the doctor says so.
+  the rest only `vx cache clean` reclaims, so the doctor says so.
 - `--format json` prints the same facts as one typed object, for a
-  script or a bug-report template: `vx`, `bun`, `bunSupported` (false
+  script or a bug-report template: `vx`, `vxPath` (the file that ran),
+  `handedOffFrom` (the vx that handed the call to the project's own, else
+  null), `bun`, `bunSupported` (false
   below Bun 1.4.0), `git` (null when not
   found), `gitStatusCache` (`{ fsmonitor, untrackedCache }`, null when
   git could not answer), `workspaceRoot`, `projects`, `tasks`,
-  `configErrors` (`[{ path, message }]`, the configs that did not load,
-  empty when all did), `plugins` (`[{ name, seams }]`), `workers` (`{ count, source, cores,
+  `plugins` (`[{ name, seams }]`), `workers` (`{ count, source, cores,
 cpuQuota }`, the source one of `workspace` / `cgroup` / `cores`,
   `cpuQuota` in cores or null), `memory` (`{ usableBytes, totalBytes,
-cgroupLimitBytes }`, the limit null when none binds), `cacheDir`, `cacheStore`
-  (null when the cache dir holds the entries), `cacheVersion`,
-  `schemaVersion`, `cacheEntries`, `cacheBytes`, `cacheRetention`
+cgroupLimitBytes }`, the limit null when none binds), `cacheDir`, `cacheDirBytes`
+  (on disk: the index and run history), `cacheStore` (null when the cache
+  dir holds the entries), `cacheStoreBytes` (on disk, null with no store), `cacheVersion`,
+  `schemaVersion`, `cacheEntries`, `cacheBytes`, `settings` (every
+  setting by path, `{ value, source }`, `source` one of `env` /
+  `workspace` / `default`, `value` null for the default), `cacheRetention`
   (`{ olderThan, maxSize, maxBytes }`, each only when set, null when none is declared),
   `orphans` (`{ artifacts, bytes }`, always present), `runs24h`, `hits24h` (task
   runs, as the row), `restored24h` (of those hits, the ones that restored
@@ -2680,10 +2721,10 @@ declared, untraced }`, `declared` the count of tasks with `exec.sandbox`,
   pretty rows render this object;
   there is no second source.
 - `--cache-dir <path>` reads the cache a run with the same flag uses, as
-  `vx why`, `vx last` and `vx cache prune` do.
+  `vx why`, `vx last` and `vx cache clean` do.
 
-Exit codes: `0` the facts printed, a config that did not load included;
-`1` no workspace here or above, or a parse error.
+Exit codes: `0` the facts printed, with no lock included; `1` no
+workspace here or above, or a parse error.
 
 ## `vx why`
 
@@ -2721,7 +2762,7 @@ cache (nothing re-ran), it re-executed on the same key, or it recorded
 no cache outcome at all, in which case vx says so instead of guessing.
 A re-execution names its cause when the index shows one: the previous
 run on the key failed and saved nothing, the run did not read the cache
-(`--force`, or a `--cache` without read), no entry for the key was
+(`--force`, or a `--cache-policy` without read), no entry for the key was
 there when it ran (pruned or evicted), the previous run was not saved
 because it ran beside a failed task (a task run past a failed dependency
 under `--continue` is never cached; said ahead of a prune, and as
@@ -2767,6 +2808,18 @@ which names the `vx why` to run next; a `config` line names the
 `vx show` that prints the task's config now. `--format json` carries
 the walk as `roots` (`chain`, `entries`).
 
+A moved input file whose last change fell inside a recorded task's run
+window names that task: a task that writes a file another key reads (a
+build rewriting a translation file in another package) re-keys that key
+on every run, so the miss is right and only moving the write ends it.
+`--format json` carries these as `writers` (`taskId`, `file`,
+`writers`); an edit made outside a run names none.
+
+```
+  changed during a run:
+    packages/lib/src/gen.txt  while app#build ran
+```
+
 A hit's line is `cache-hit · key …` (or `cache-hit-remote`): the status
 names the hit and its tier, so only an executed run carries the word.
 A skipped task never ran and derived no key: its line is `skipped · no key`.
@@ -2774,11 +2827,10 @@ A row's kind is what the key folded: `file` (an input file, by blob
 id), `env` (a declared variable, by digest), `runtime` and
 `ws-runtime` (a declared command's output, `inputs.runtime` and
 `inputs.workspaceRuntime`), `forward` (the argv forwarded after `--`),
-`package` (the project's own `package.json`), `workspace` (the
-fingerprint: the lockfile and the other root manifests), `config` (the
-evaluated task config), `upstream` (a dependency's input key — a
-lockfile change moves it too, so that row rides with the
-fingerprint's), `plugin` (a `key` plugin's material, by name) and
+`config` (the evaluated task config), `upstream` (a dependency's input
+key — a lockfile change moves it too, so that row rides with the
+lockfile plugin's), `plugin` (a `key` plugin's material, by name; a
+lockfile plugin's dependency closure) and
 `format` (the key format vx itself folds: it moves only with an
 upgrade, and re-keys every task once, X-142).
 The component-level rows come from the `entry_inputs` input
@@ -2791,39 +2843,13 @@ task with no `cache` block derives a key too — it is what dependents
 fold — but saves no entry, so for it the verb can only report the key
 change and says so.
 `--format json` emits one machine-readable object (`{ taskId, runId,
-why, diff, roots }`); when the task's recorded runs predate run ids, `{ taskId,
+why, diff, roots, writers }`); when the task's recorded runs predate run ids, `{ taskId,
 why, diff, explanation }`, `why` and `diff` null and `explanation` the
 latest cache entry's key.
 
 Exit codes: `0` the task's run explained; `1` no recorded run of the
 task, a `--run` with no row for it, or a parse error.
 
-## `vx prune`
-
-```
-vx prune <project...> [--out-dir <dir>] [--docker] [--production]
-```
-
-A plugin verb of `@vzn/vx-lockfile`: declaring `pnpm()`, `bun()`,
-`npm()` or `yarn()` adds it. It copies the named projects, their
-transitive workspace dependencies, the root manifests (workspace lists
-rewritten to the subset), the vx configs and each lockfile pruned to what
-the subset installs into `--out-dir` (default `out/`), so a Docker build
-installs it with a frozen lockfile; `--docker` splits `json/` (the
-install layer) from `full/`; `--production` leaves out a workspace
-package only a dev dependency reaches and strikes it from the kept
-manifests and lockfiles. `turbo prune`. Reference:
-`packages/vx-lockfile/README.md` § `vx prune`. Without the plugin, typing
-`vx prune` says where it comes from and exits 1. History: core verb
-2026-08-25, `@vzn/vx-prune` 2026-09-10, removed 2026-09-11 (it copied the
-lockfile unpruned), back in `@vzn/vx-lockfile` 2026-10-03.
-
-## `vx stats`
-
-Removed (H-19). It was an alias of `vx info`, which absorbed it, and
-warned on every use. Typing `vx stats` points at `vx info` and exits 1 —
-unless a declared plugin claims the verb through the `commands` seam.
-
 ## `vx last`
 
 Replay a recorded run's summary from the local history — no
@@ -2833,7 +2859,7 @@ surface. A run a Ctrl-C (or SIGTERM, SIGHUP) stopped records nothing,
 so `vx last` still shows the run before it.
 
 ```
-vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--format pretty|json] [--cache-dir <path>]
+vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--stats [<task>] [--branch <name>]] [--format pretty|json] [--cache-dir <path>]
 ```
 
 Bare `vx last` replays the most recent run: a header (verdict, command,
@@ -2875,7 +2901,12 @@ passed, so a replayed failure that is already fixed says so. A
 sandboxed task's row adds `sandboxFix`, the `exec.sandbox.allow`
 entries (`read`, `write`, `network`, `systemInfo`) that would have
 granted its denials, the same grants the terminal prints as `fix:`;
-`withheld` lists the credential paths it denied and left out. They live in `<cacheDir>/failures/<runId>.json`, the
+`withheld` lists the credential paths it denied and left out (a `.env` file, or a store under home the sandbox denies, `security.md`), and, for
+a cached task, `inputs` the reads of its project no `cache.inputs.files`
+glob matches (the terminal's `and, if the output depends on them, …`
+line). A task
+failed by `inputStability.severity: 'error'` adds `inputMoved`, the
+input that changed during the run. They live in `<cacheDir>/failures/<runId>.json`, the
 newest 50 failed runs; past those, or when the write was refused, a
 failed row reads `output: ''` and `locations: []`. `--log <task>`
 prints one task's output instead of the summary: in the latest run that
@@ -2886,12 +2917,28 @@ or in the run that saved it. An uncached task that passed, or a skip,
 kept none: stdout is empty and stderr says so, exit 0. With
 `--format json` it is `{ runId, taskId, status, source, output }`,
 `source` `'failure'`, `'cache'` or `null`. A task no run recorded is
-refused, exit 1; `--log` does not combine with `--list` or `--failed`. `--list --format json`
+refused, exit 1; `--log` does not combine with `--list` or `--failed`.
+`vx last app#build --log` reads the same as `--log app#build`: a `--log`
+with no value takes the positional as its task.
+`--stats [<task>]` prints per-task numbers over the last 50 runs, the
+window the scheduler and `--dry` learn from: runs, p50 (the forecast a
+run shows: the median of the task's last five timings on the branch,
+else on any branch), p99 of the executed successes, pass and hit rate, failure mode (`stable`,
+`flaky-recoverable`, `flaky-fatal`), the largest peak RSS and CPU
+parallelism (a hit counts what its producing run used), one table row
+per task. A task id narrows to that task, a task name to it in every
+project; one the window has no run of is refused, exit 1. The branch is
+`--branch`, else `VX_RUN_BRANCH`, else git's, then the CI provider's, as
+a run's. With `--format json` it is `{ window, branch, stats }`, each row `{ taskId, runs,
+p50DurationMs, p99DurationMs, successRate, hitRate, failureMode,
+maxPeakRssBytes, maxCpuParallelism }`, `null` where nothing was
+measured. `--stats` does not combine with `--list`, `--failed` or
+`--log`; `--branch` combines only with `--stats`. `--list --format json`
 an array of the same `invocation` objects, newest first. An unknown run id fails
 loud and points at `--list`. Before any run, every form says so
-(`vx last: no recorded runs yet — run something first`, exit 1; `--list`
-prints `no recorded runs`, exit 0), and past green runs only,
-`--list --failed` prints `no recorded run failed`. A run id may be typed as a unique prefix; a
+(`› vx last  no runs yet` with `fix  vx run`, exit 1; `--list` prints
+`› vx last  no runs yet`, exit 0), and past green runs only,
+`--list --failed` prints `› vx last  no failed runs`. A run id may be typed as a unique prefix; a
 prefix several runs share fails and lists them. A replayed run with
 failures ends with the command that re-runs them (`re-run what failed:
 vx run app#test -- …`, with the arguments the run forwarded to the
@@ -2900,14 +2947,14 @@ line of its own without them, X-140). The
 replayed `$ vx run …` or `$ vx watch …` line and that one keep each
 argument shell-quoted (`-- 'a b'`), so either pastes back as it ran (X-49).
 
-`vx why`, `vx last`, `vx info` and `vx cache prune` all read the cache
+`vx why`, `vx last`, `vx info` and `vx cache clean` all read the cache
 a run wrote, so each takes `--cache-dir <path>` with `vx run`'s rules
 (cwd-relative, absolute used as-is): a run that wrote its history
 elsewhere is replayed, explained, reported on and pruned there. Without
-the flag they open the workspace's cache (`defineWorkspace({ cacheDir })`
+the flag they open the workspace's cache (`defineWorkspace({ cache: { dir } })`
 or `.vx/cache`). A `--cache-dir` that is not there is refused by name
 (`--cache-dir .vx/cahce: no such directory`). In a workspace that never
-ran, `vx why`, `vx last`, `vx info`, `vx show` and `vx cache prune`
+ran, `vx why`, `vx last`, `vx info`, `vx show` and `vx cache clean`
 (dry or not) read it as empty and create nothing (item 900, E-7, E-38).
 
 Exit codes: `0` the run (or the list) printed, `--list` with no runs
@@ -2949,10 +2996,10 @@ of each verb, read from the same help text `vx <verb> --help` prints:
 the verb's own Usage line, and for `run` and `watch` the run option
 lines, less the ones `watch` refuses. So a flag cannot be documented
 and not completed, nor completed and then refused: a flag another
-verb's line names in passing (`vx lock --check` beside `--frozen`) is
+verb's line names in passing (`--check` in a line about `vx lock`) is
 not one. After a flag with a fixed value set the script offers that
 set: `--format` pretty or json, `--output-logs` full, errors-only,
-hash-only or none, `--download` all, toplevel or none — each value one
+hash-only or none, `--cache-download` all, toplevel or none — each value one
 the flag's parser takes (`tests/completions.test.ts` holds it). A plugin verb completes `--help` only. Task and project
 names are not completed (they are the workspace's, and a completion
 that evaluates configs on every Tab is the wrong price). The zsh script
@@ -2967,7 +3014,7 @@ Exit codes: `0` the script printed; `1` an unknown shell or flag.
 
 ## Plugin commands
 
-A plugin declared in `vx.workspace.ts` can add verbs:
+A plugin declared in `.vx/workspace.ts` can add verbs:
 
 ```ts
 import { definePlugin, type VxPlugin } from '@vzn/vx'
@@ -2978,7 +3025,7 @@ export function mcp(): VxPlugin {
       mcp: {
         description: 'serve the run history to an AI agent over stdio',
         async run(argv, ctx) {
-          // ctx.workspaceRoot, ctx.cacheDir, ctx.concurrency, ctx.warn(...)
+          // ctx.workspaceRoot, ctx.cacheDir, ctx.concurrency, ctx.cache, ctx.warn(...)
           return 0 // the process exit code
         },
       },
@@ -2989,19 +3036,19 @@ export function mcp(): VxPlugin {
 
 The plugin's name is its package name, which `definePlugin` reads from
 `import.meta`; a plain object is refused when the workspace loads.
+`ctx.cache` reads the plugin's own entries as `setup` writes them (the
+local store, then each remote the workspace's cache plugins supply,
+under the run's scope), read-only, opened on first use.
 
-(`@vzn/vx-mcp` ships exactly this: declare `mcp()` and `vx mcp` serves
-six read-only tools to AI agents — four over the cache database, one
-over the resolved task catalog, one the workspace doctor's facts.
-`@vzn/vx-schedule-history` adds `vx history`: what it learned per task
-and the reservation its `admit` hook packs.) The dispatcher tries core's verbs
+(`@vzn/vx-schedule-history` ships exactly this: `vx history`, what it
+learned per task and the reservation its `admit` hook packs.) The dispatcher tries core's verbs
 first and consults plugins only for a word core does not know, loading
 the workspace config from the cwd to find them (outside a workspace the
 verb is simply unknown). A plugin verb that names a core verb, or one
 plugins of two packages both declare, is refused when the workspace
 loads — such a verb could never run, or would hide the other plugin's.
-Plugins of one package are one owner (`bun()` and `pnpm()` both carry
-`prune`): the first declared runs. A plugin verb's
+Plugins of one package are one owner (two of its plugins may carry the
+same verb): the first declared runs. A plugin verb's
 return value is the exit code, an integer 0–255 (anything else — nothing,
 a fraction, 256, which the OS would keep as 0 — fails naming the plugin
 and the verb), and a thrown `UserError` prints as
@@ -3013,33 +3060,62 @@ An unknown verb is answered with what this workspace knows: the "did you
 mean" set is core's verbs AND the ones its plugins declare (the lookup
 that just failed already loaded them, so it costs nothing), and when
 nothing is close enough to guess, a second line says where a verb can
-come from — the verbs declared here, or that `vx.workspace.ts` is what
+come from — the verbs declared here, or that `.vx/workspace.ts` is what
 would declare one, or that there is no workspace here at all. Core still
 names no package: it lists what the workspace itself declares.
 
 ## Environment variables vx reads
 
-The variables core reads. Each is read where it applies, per call, so a
-value set for one invocation is that invocation's. A plugin's own (the
-REAPI endpoints, the GitHub token) are in its README; what a TASK sees
-is `exec.env` in `docs/schema.md`, and the two markers vx sets on every
-task are the last row.
-
-| Var                               | Value                               | Default     | Effect                                                                                                                                                                                                                                                                                                                  |
-| --------------------------------- | ----------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `VX_TIMING`                       | any non-empty                       | off         | Print the stage table to stderr after a run, a `--dry`, or each `vx watch` cycle (`docs/modules/timing.md`).                                                                                                                                                                                                            |
-| `VX_TASK_TIMEOUT`                 | positive integer (ms)               | none        | The default timeout for tasks without their own `exec.timeout`, one rung below `--timeout` / `RunOptions.timeout` and one above the workspace `timeout`. Empty, non-integer or non-positive is ignored; a value past the largest timer (~24.8 days) is clamped to it, never refused.                                    |
-| `VX_CACHE_DIR`                    | a path                              | none        | The workspace's cache dir, relative to the workspace root, below `--cache-dir` and `vx.workspace`'s `cacheDir`. A named cache dir holds the whole cache and shares nothing; unset, entries live in the user's shared store (`docs/caching.md`). Empty is ignored; whitespace alone is refused, as `cacheDir` is.        |
-| `VX_CACHE`                        | a `--cache` spec                    | all axes on | The run's cache policy when no `--cache` is passed (`local:rw,remote:r`); `--no-cache` and `--force` still apply on top. Empty is ignored; a bad spec is refused before any task.                                                                                                                                       |
-| `VX_CACHE_SCOPE`                  | a `cacheScope` value                | none        | The run's `cacheScope` (`trusted`, `read-only`, `pr-123`), above `vx.workspace`'s and `github()`'s; `--cache-scope` beats it. Empty is ignored; a value `cacheScope` would refuse is refused before any task.                                                                                                           |
-| `VX_INPUT_STABILITY`              | `immutable`, `mutable`, `unchecked` | `immutable` | The `inputStability.strategy` of every task, over its own and the workspace's, for the run: which writes to an input during the command withhold the save. `mutable` lets a rewrite to the bytes the key folded through, `unchecked` skips the check. Any other value is refused before a task runs (`docs/schema.md`). |
-| `VX_INPUT_STABILITY_SEVERITY`     | `warn`, `error`                     | `warn`      | The `inputStability.severity` of every task, over its own and the workspace's, for the run: `error` fails a task whose save a moved input withheld, so the run fails. Any other value is refused before a task runs.                                                                                                    |
-| `VX_KILL_GRACE_MS`                | positive integer (ms)               | 2000        | The SIGTERM → SIGKILL grace a child that ignores SIGTERM gets: on a timeout, on a signal, and at the end-of-run shutdown of persistent tasks. Out of range falls back to the default.                                                                                                                                   |
-| `VX_READY_NOTICE_MS`              | positive integer (ms)               | 10000       | How long a persistent task may take to match `readyWhen` before vx says once what it waits for. Out of range falls back to the default.                                                                                                                                                                                 |
-| `VX_TEARDOWN_TIMEOUT_MS`          | integer (ms)                        | 3000        | The bound on one plugin's end-of-run flush or teardown, and on its `telemetry()` setup, so a third party's I/O cannot hold the run. Out of range falls back to the default, never clamps: a bound of 24.8 days is no bound.                                                                                             |
-| `VX_CONFIG_WORKER_TIMEOUT_MS`     | integer (ms)                        | 30000       | How long one `vx.config.ts` evaluation may take, in process or in its worker, before the load fails naming the config (a real evaluation is ~10 ms). A synchronous loop on a first load holds the thread the deadline needs, so it hangs until killed. Out of range falls back to the default.                          |
-| `VX_WATCH_POLL`                   | any non-empty                       | off         | `vx watch` polls every 250 ms from the start instead of probing the OS watcher (§ `vx watch` › How changes are seen).                                                                                                                                                                                                   |
-| `VX_RUN_WORKSPACE`, `VX_RUN_TASK` | set by vx                           | —           | Set on every task's environment (the workspace root; `project#task`). Read back by a `vx run` a task starts: one in the same workspace is refused, since a nested run is invisible to the outer graph and a loop back to its own task forks without bound (`docs/schema.md` § `env`).                                   |
+Every setting has a variable derived from its path (`run.killGrace` →
+`VX_RUN_KILL_GRACE`), beating `.vx/workspace` and beaten by the flag; the
+table in `docs/schema.md` § Settings gives each value's form and
+default. Each is checked once before any verb runs: an empty one is
+unset, a value its kind does not take is refused naming the form, and a
+variable vx does not read is ignored. A
+plugin's own (the REAPI endpoints, the GitHub token) are in its README;
+what a TASK sees is `exec.env` in `docs/schema.md`.
+
+<!-- variables table: generated by tests/settings.test.ts -->
+
+| Variable                            | Setting                                               | What it does                                                                                                                                                |
+| ----------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `VX_RUN_CONCURRENCY`                | [`run.concurrency`](schema.md#settings)               | Tasks at once: a positive integer, or a share of the cores (`'50%'`).                                                                                       |
+| `VX_RUN_SCHEDULE`                   | [`run.schedule`](schema.md#settings)                  | Which ready task starts first when there are more than workers.                                                                                             |
+| `VX_RUN_AFFECTED_BASE`              | [`run.affectedBase`](schema.md#settings)              | The git ref a bare `--affected` compares with.                                                                                                              |
+| `VX_RUN_BRANCH`                     | [`run.branch`](schema.md#settings)                    | 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.                     |
+| `VX_RUN_TIMEOUT`                    | [`run.timeout`](schema.md#settings)                   | A task's time limit, for tasks without their own `exec.timeout` (`'30m'`).                                                                                  |
+| `VX_RUN_RETRIES`                    | [`run.retries`](schema.md#settings)                   | Re-runs of a failed task, for tasks without their own `exec.retries`.                                                                                       |
+| `VX_RUN_CONTINUE`                   | [`run.continue`](schema.md#settings)                  | What a failed task takes down: `never` stops the run, `deps-ok` skips its dependents, `always` runs them too.                                               |
+| `VX_RUN_OUTPUT_LOGS`                | [`run.outputLogs`](schema.md#settings)                | Which task output the run prints. Chosen before the workspace loads, so flag and env only.                                                                  |
+| `VX_RUN_KILL_GRACE`                 | [`run.killGrace`](schema.md#settings)                 | How long a task that ignores SIGTERM gets before SIGKILL.                                                                                                   |
+| `VX_RUN_TEARDOWN_TIMEOUT`           | [`run.teardownTimeout`](schema.md#settings)           | The bound on each plugin's end-of-run flush and teardown.                                                                                                   |
+| `VX_RUN_READY_NOTICE`               | [`run.readyNotice`](schema.md#settings)               | How long a persistent task may take to match `readyWhen` before vx says it waits.                                                                           |
+| `VX_RUN_RULES_EXCLUSIVE_OUTPUTS`    | [`run.rules.exclusiveOutputs`](schema.md#settings)    | Refuse two tasks whose outputs overlap even when an edge orders them.                                                                                       |
+| `VX_RUN_RULES_UPFRONT_KEYS`         | [`run.rules.upfrontKeys`](schema.md#settings)         | Refuse a task whose inputs can match another task's outputs.                                                                                                |
+| `VX_CACHE_DIR`                      | [`cache.dir`](schema.md#settings)                     | Where the cache lives, relative to the workspace root; named, it holds the whole cache.                                                                     |
+| `VX_CACHE_RETENTION_MAX_SIZE`       | [`cache.retention.maxSize`](schema.md#settings)       | Evict least-recently-used entries at each run's end until the cache is under this (`'10GB'`).                                                               |
+| `VX_CACHE_RETENTION_OLDER_THAN`     | [`cache.retention.olderThan`](schema.md#settings)     | Evict entries unused for this long at each run's end (`'30d'`).                                                                                             |
+| `VX_CACHE_POLICY`                   | [`cache.policy`](schema.md#settings)                  | Which layers a run reads and writes (`'local:rw,remote:r'`); `--no-cache` and `--force` apply on top.                                                       |
+| `VX_CACHE_SCOPE`                    | [`cache.scope`](schema.md#settings)                   | Where cache writes land (`'pr-123'`): reads try the default key, then the scope's.                                                                          |
+| `VX_CACHE_DOWNLOAD`                 | [`cache.download`](schema.md#settings)                | Which remote hits land on disk: every one, only the requested tasks, or none.                                                                               |
+| `VX_CACHE_INPUT_STABILITY_STRATEGY` | [`cache.inputStability.strategy`](schema.md#settings) | What a write to an input during the command means for the save, for tasks without their own.                                                                |
+| `VX_CACHE_INPUT_STABILITY_SEVERITY` | [`cache.inputStability.severity`](schema.md#settings) | Whether a skipped save warns or fails the task, for tasks without their own.                                                                                |
+| `VX_LOCK_REVIEW_FILES`              | [`lock.reviewFiles`](schema.md#settings)              | `vx lock` writes each project's resolved config, pretty, to `vx.lock.json` beside its `vx.config`, for review; vx never reads it.                           |
+| `VX_WATCH_POLL`                     | [`watch.poll`](schema.md#settings)                    | Poll for changes from the start instead of the OS watcher.                                                                                                  |
+| `VX_CONFIG_WORKER_TIMEOUT`          | [`config.workerTimeout`](schema.md#settings)          | How long one config evaluation may take.                                                                                                                    |
+| `VX_DEBUG_TIMING`                   | [`debug.timing`](schema.md#settings)                  | Print the run's stage timings to stderr.                                                                                                                    |
+| `VX_DEBUG_WATCH`                    | [`debug.watch`](schema.md#settings)                   | `vx watch`: say on stderr each time the loop arms, with the projects it watches.                                                                            |
+| `VX_DEBUG_DUMPABLE`                 | [`debug.dumpable`](schema.md#settings)                | Linux: keep vx dumpable, so strace or a debugger can read its memory and `/proc/<pid>/fd`, and an unsandboxed task its env.                                 |
+| `VX_HANDED_OFF`                     | —                                                     | Set by a global vx that hands the call to the project's own (§ Which vx runs): the path of the vx that handed off, so the receiver does not hand off again. |
+| `VX_RUN_WORKSPACE`, `VX_RUN_TASK`   | —                                                     | Set by vx on every task (below); a `vx run` a task starts reads them back.                                                                                  |
+
+<!-- /variables table -->
+
+vx sets two variables on every task's environment: `VX_RUN_WORKSPACE`
+(the workspace root) and `VX_RUN_TASK` (`project#task`). A `vx run` a
+task starts reads them back: one in the same workspace is refused, since
+a nested run is invisible to the outer graph and a loop back to its own
+task forks without bound (`docs/schema.md` § `env`).
 
 Colors are the two conventions in § Output format › Colors (`NO_COLOR`,
 `FORCE_COLOR`). A truthy `CI` picks the CI output flow and
@@ -3109,7 +3185,9 @@ marked with a cyan `▸` after `┌─`/`└─`, and its close reads `running`
 died on its own before the run stopped it.
 
 There is **no top-of-run banner** — the run context lives in the
-footer. A broad run looks like:
+footer. The task log opens with one blank line before its first row,
+on a terminal or not; a note vx prints before it is not part of it.
+A broad run looks like:
 
 ```
  ⇢     4ms success local    @vzn/vx#format-check
@@ -3117,30 +3195,37 @@ footer. A broad run looks like:
 
 ─ vx 0.0.0 ───────────────────────────────────────────────────
   projects  ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱
-            1 in run · 3 total
+            1 affected · 3 total
   tasks     ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
             2 success · 2 total
   cache     ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
-            1 miss · 1 local
+            local 1↓ 1↑
 
   info      8 workers · local cache
-  time      5.34s · max 5.20s · avg 5.20s · min 5.20s
-  result    2 tasks · 1 cached (50%) · 900ms saved · 5.34s
+  time      5.34s · 900ms saved
 ```
 
 The three bars are meters: `projects` is what the run covered against
 the workspace, `tasks` is failed / success / skipped, `cache` is miss /
 no-cache / up-to-date / local / remote (a skipped task rides it too, so
-the two legends sum alike). The `time` spread counts executed tasks
-only — a hit's restore time never enters it — which is why one executed
-task reads as its own max, avg and min. The `result` row is the run in
-one line, last: tasks, cached (every hit, local or remote, over every
-task with a cache that ran or hit; a skipped task asked no cache) and the wall time — `3 tasks · all cached · 40ms`
-when nothing that could hit ran, with `N failed` after the count on a
-red run. A task with no `cache` block, or any task of a run whose
-`--cache` reads and writes nothing (`--no-cache`), could never hit, so it
-is counted apart (`1 task · 1 no-cache · 37ms` for `vx run dev`), as
-`--dry` labels it. A test renders this run and
+the two bars fill alike; its count is on the tasks legend only). Its
+legend reads per layer: `local 1● 1○ 2↓ 4↑ · remote 3↓ 4↑`.
+`●` is a fresh hit (outputs already on disk, whichever layer answered,
+so it counts under local), `○` a task with no cache, `↓` is restored
+from that layer and `↑` saved to it (local `↑` counts only tasks that ran here; remote `↑` counts
+uploads that landed). A layer shows only when the run's
+`--cache-policy` uses it. `N not saved` (ran, succeeded, saved nothing),
+`N not downloaded` (outputs left in the remote store) and `N ↑ failed`
+show only when non-zero. The
+`time` row is the wall time, then what the cache saved (the hits' stored
+exec times, never the restore), then the spread over executed tasks
+only — a hit's restore time never enters it. The footer never says a
+fact twice: a spread value already on the row is left out, so one
+executed task shows no spread, and there is no closing `result` row
+repeating the tasks, cache and time rows. A task with no `cache` block,
+or any task of a run whose `--cache-policy` reads and writes nothing
+(`--no-cache`), could never hit, so it is counted apart (`1 no-cache`
+for `vx run dev`), as `--dry` labels it. A test renders this run and
 checks it against this page, byte for byte.
 
 Group tasks emit no framed block by design (they aren't real tasks);
@@ -3151,8 +3236,8 @@ What a run has to say about one task rides that task's row; what it
 says about the run (a server that died, outputs left remote, a file
 `--summarize` / `--profile` wrote, a history, upload, plugin or sandbox
 warning) prints above the footer: it prints once the run's closing work
-is done, the `VX_TIMING=1` table included. Cache housekeeping
-(`cacheRetention`) prints nothing. Only a kept server's own output
+is done, the `VX_DEBUG_TIMING=1` table included. Cache housekeeping
+(`cache.retention`) prints nothing. Only a kept server's own output
 follows it.
 
 **Skipped rows.** A red run lists every task that never started as a
@@ -3179,9 +3264,9 @@ what it reached first (`not run`). Neither reached the cache:
  ◌         not run          web#test
 ```
 
-The tasks legend names them outside the total, which history and
-telemetry share: `2 success · 2 total · not counted: 1 aborted, 2 not
-run`. A framed task (focused or `full`) that
+The tasks legend counts them in the total, each state its own segment
+of the bar: `2 success · 1 aborted · 2 not run · 5 total`. The total is
+always last on its line. A framed task (focused or `full`) that
 printed while it stopped shows its frame instead of a row.
 
 **Flaky rows.** A task the run just proved nondeterministic says so
@@ -3195,7 +3280,7 @@ run history alone, no service:
 
 A task is flaky when its exact cache key FAILED AFTER IT HAD PASSED
 (this run counted; a cache hit is a pass, it replayed one), or when it
-needed a retry (`exec.retries` / `--retry`) this run. A failure on a
+needed a retry (`exec.retries` / `--retries`) this run. A failure on a
 key that never passed is a break and carries no note — a changed input
 that fails is what a red run usually means — and the first pass after
 only failures is a recovery (a missing tool installed), not a flake.
@@ -3241,7 +3326,7 @@ Only a run's own output (`vx run`, `vx watch`) is painted, and the
 help on a terminal: headings bold, `vx <verb>` and each flag or example
 in cyan; `NO_COLOR` or `FORCE_COLOR=0` turns it off
 (`tests/help-colors.test.ts`). Every other verb (`show`, `info`, `why`,
-`last`, a `--dry` plan, `--graph`, `cache prune`), and the help off a
+`last`, a `--dry` plan, `--graph`, `cache clean`), and the help off a
 terminal, prints plain text whatever `FORCE_COLOR` says, so a script
 that forces colour for a run's log still parses them
 (`tests/cli-colors-e2e.test.ts`).
@@ -3249,8 +3334,9 @@ that forces colour for a run's log still parses them
 ## Remote cache (plugin-driven)
 
 Core ships **no remote-cache wire client** — the remote cache is a
-plugin concern. A `cache` plugin composes core's `LayeredCache` over a
-wire client; `@vzn/vx-reapi` provides one for any Bazel REAPI server
+plugin concern. A `cache` plugin returns a wire client (a
+`RemoteCacheLayer`) and core layers it over the local cache;
+`@vzn/vx-reapi` provides one for any Bazel REAPI server
 (ActionCache + CAS).
 
 Reads try local first, then remote (hydrating local on remote hit),
@@ -3264,7 +3350,7 @@ implement core's `RemoteCacheLayer` interface in a plugin's `cache`
 capability — the recipe lives in the plugins guide. Embedders
 holding a wire client can inject it per-run via
 `RunOptions.remoteCache` (explicit injection wins over the plugin
-consult). The retired `VX_REMOTE_CACHE_*` env vars are gone.
+consult).
 
 ## Run analytics