@vzn/vx 0.0.638 → 0.0.640

package/docs/cli.md

@@ -64,7 +64,7 @@ included.
 
 **Every requested name must resolve.** If any positional matches no
 project in scope, the run refuses to start — `vx run: no projects
-declare task(s): <name>.` on stderr, a run and `--dry` / `--graph` alike
+declare task(s): <name>.` on stderr, a run and `--dry` alike
 (a run printed it to stdout until 2026-10-03), exit 1, with `Did you mean <task>?` when a
 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
@@ -124,20 +124,21 @@ If no task name is given:
   `missing task name (stdin is not a TTY, so no picker; tasks here: build, test)`,
   naming the cwd project's tasks, else every project's (twelve, then
   `and N more`); outside a workspace it reads `vx run <task>, e.g. vx run build`.
-- **Under `--format json` or `--dry=json`**, on a terminal too — the
+- **Under `--dry=json`**, on a terminal too — the
   same refusal (`a JSON answer opens no picker; …`), with the
   `VX_E_USAGE` error document on stdout: a program cannot pick.
 
 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), `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). |
+| 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), a 2 s grace 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.
+and each task hears it once: from vx, as SIGINT. A stop starts no more remote
+cache uploads and does not wait on one in flight.
 
 Installed from npm, `vx` is a sh launcher that execs the platform
 binary, so every signal reaches vx directly and no Node starts first
@@ -300,13 +301,13 @@ change seeds tasks in the projects it touches:
   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 `vx.config.*`
-  changed, or that holds a changed path no cached task of its declares
+  changed, or that holds a changed path no 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 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
+- a task with no `inputs` 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.
 
@@ -353,6 +354,14 @@ 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.
+A symlinked input keys what it points to, so a link whose target
+changed (a file the diff names, or one under a linked directory) is a
+changed path of its project, and a link to a target git cannot diff
+(outside the workspace, or git-ignored) is one on every run.
+A gitignored file a task's inputs name outright (`.env.local`,
+`dist/**`) never selects the task on its own, as in Nx: `--affected`
+reflects only what git sees. The key still hashes it, so a run of the
+task misses when it changed.
 `.vx/projects.lock.json` is filtered out of the changed set — a `vx lock`
 re-write never marks every project affected.
 
@@ -480,34 +489,23 @@ than run with the args unheard.
 | `--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).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `--force`                                  | boolean        | off                                                        | Re-execute everything (skip cache reads); writes stay on. A key already stored is kept, and a remote that holds it is not sent it again. 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:
 
-- `--dry` and `--graph` — both skip execution; pick one.
-- `--dry` or `--graph` with `--summarize`, `--profile`, `--report` or
-  `--report-file` — each needs a real run to write about. `--report` and
-  `--report-file` were accepted and silently wrote nothing until item 992.
+- `--dry` with `--profile` — the profile needs a real run to write
+  about.
 
 Unknown flags are a parse error (`unknown flag: --foo`), naming the
 nearest flag the verb accepts when one is within two edits
@@ -531,13 +529,10 @@ name is the verb, and would change what `vx build` means the day one
 was declared.
 
 **Optional-value flags take their value with `=` only.** `--affected`,
-`--exclude-dependencies`, `--dry`, `--graph`, `--summarize`, `--profile`,
-and `--report` are all valid bare, so a following word is
-read as a task name (a `--graph` word ending `.svg`, `.png`, `.json`
-and the like is refused, see § Turbo and Nx flags) — `vx run --affected build` means "run
-`build`, affected scope", and there is no way to tell that apart from
-"`build` is the git base". Write `--graph=out.dot` or
-`--affected=origin/main`. Getting it wrong is loud, not silent: the value
+`--exclude-dependencies`, `--dry` and `--profile` are all valid bare,
+so a following word is read as a task name — `vx run --affected build`
+means "run `build`, affected scope", and there is no way to tell that
+apart from "`build` is the git base". Write `--affected=origin/main`. Getting it wrong is loud, not silent: the value
 becomes a positional that matches no project, so the run refuses to
 start (see "Every requested name must resolve" above).
 
@@ -547,9 +542,9 @@ Pass bare `--exclude-dependencies` for the first, omit the flag for the
 second.
 
 Value flags (`--filter`, `--concurrency`, `--output-logs`,
-`--verbosity`, `--cache-dir`, `--report-file`, …)
+`--verbosity`, `--cache-dir`, …)
 accept both `--flag value` and `--flag=value`. In the space form,
-`--cache-dir` and `--report-file` reject a value
+`--cache-dir` rejects a value
 starting with `-`: that is always a swallowed flag (an unquoted empty
 shell variable), never a path or task id. Use the `=` form for a literal
 leading dash.
@@ -559,15 +554,13 @@ leading dash.
 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`,
+workers. A duration flag (`--timeout`) 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=`
-writes `<cacheDir>/runs/<run_id>.json`, `--graph=` prints to stdout and
+An empty `=` value means "no value" on two flags, which then act like
+their bare forms: `--profile=` writes `profile.json` and
 `--affected=` uses the default base. Every other flag refuses an empty
-value: `--dry=`, `--report=`, `--continue=` and
+value: `--dry=`, `--continue=` and
 `--exclude-dependencies=` as well as the ones with no bare form
 (`--retries=`, `--timeout=`, `--cache-dir=`, `--filter=`, `--cache-policy=`).
 
@@ -602,10 +595,13 @@ So `--no-cache` always wins over `--force`. The common cases:
 - `--no-cache` → nothing reads, nothing writes, and declared output
   globs are left untouched (you're debugging; vx won't manage your
   tree).
-- `--force` → re-execute every task (reads off) but still write fresh
-  artifacts to both layers (writes on). Output globs ARE cleaned
-  before each task so the saved snapshot is clean. This is the "rebuild
-  and refresh the cache" flag.
+- `--force` → re-execute every task (reads off) with writes on. An
+  entry is immutable: a key the local cache already holds is kept, and
+  each remote that can batch (`hasMany`) is asked once, in the
+  background, which keys it holds; one that cannot is asked `has` per
+  key before its upload. Held keys are not uploaded again (a probe that
+  fails uploads, as before). Output globs ARE cleaned before each task,
+  so the disk holds this run's outputs.
 
 `--cache-policy=<spec>` is a comma-separated list of `<layer>:<flags>`
 segments. `layer` is `local` or `remote`; `flags` is any subset of `r`
@@ -625,8 +621,9 @@ layer keeps its current value. Both `--cache-policy=<spec>` and the space form
 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-policy=local: --force` (local off, reads off, remote write-only).
+Combine with `--force` for "re-execute and fill only the remote":
+`--cache-policy=local: --force` (local off, reads off, remote write-only;
+keys the remote already holds are not sent).
 
 Invalid layers/flags are a parse error
 (`--cache-policy: invalid layer 'disk'`, `--cache-policy: invalid flag 'x'`, …);
@@ -691,8 +688,7 @@ What the shapes mean in each column:
   everything, the blocker included (`⊘ skipped app#deploy • blocked by
 lib#build`; a fail-fast skip, which nothing blocked, carries no
   suffix). Every view that lists tasks prints it, a dependency's
-  included: nothing prints below the footer. `--report` reads the same fact into the status cell,
-  `skipped (blocked by lib#build)`.
+  included: nothing prints below the footer.
 - **`frame, or one-liner if quiet`** — a cache hit with stored stdout is
   worth a frame (the output is the point); a hit with nothing to replay
   compresses to one line, which is what keeps a 2000-task warm run
@@ -746,7 +742,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, `run.killGrace`, SIGKILL), one status line names
+   down (SIGTERM, a 2 s grace, 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.
@@ -762,16 +758,43 @@ other persistent task`), and a non-zero exit makes the run exit 1
 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; 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
+   its row for its whole life, so nothing jumps; overflow shows as
+   `+k more`. A second in, an idle worker row holds a task an
+   unfinished dependency blocks, one per row, in the order the
+   scheduler starts them (most dependents first):
+   `blocked  solid-js#build  by solid-js#types` (dim `blocked`, the id,
+   then the running task that holds it back). The task starts in the
+   row that held it. A row with no blocked task left to hold leaves the
+   region and the rows below close up; blocked tasks only dwindle, so
+   it never comes back. A running 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. 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
+4. **vx's own steps** — what vx does around the tasks that the run
+   waits on, before its first task starts or before it ends, as rows of
+   their own below the worker rows: `vx:load` (configs and graph from
+   the lock), `vx:run-lock`, `<plugin>:setup`, `vx:keys` (keys and local
+   probes), `<plugin>:schedule`, then after the graph `vx:uploads`,
+   `vx:history`, `<plugin>:telemetry`, `<plugin>:teardown`,
+   `vx:snapshots`, `vx:retention`, `vx:close` and `vx:sandbox`. A step
+   shows once it has run 150 ms, ticking like a task
+   (`     1.2s running internal vx:uploads`); no worker slot or
+   `--concurrency` holds it back. When it ends it leaves a list row
+   like a task's, `internal` in the cache column
+   (`⏺︎ 4.60s success internal vx:uploads`); a quicker one shows
+   nowhere. A step that runs beside the tasks, `vx:prefetch` (a
+   remote's downloads), never shows: `vx last` lists it. `:` is no task
+   id's separator, so a step never reads as a task: a project named
+   `vx` keeps `vx#build`. No step is a task: no count, bar, history
+   row, forecast, flaky verdict or telemetry record holds one;
+   `--profile` and `VX_DEBUG_TIMING` time vx's stages their own way.
+   Steps show only beside a live region; a log (CI, a pipe) prints
+   none.
+5. **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,
    the `time` row adds what is left (`time  1.41s · ~3s left`): each
@@ -814,11 +837,11 @@ redraws within 30 ms of the last draw coalesce into a single
 trailing draw when the floor expires (the final state always lands).
 On a 3,270-task warm run this cuts ~6.7 MB of redraw ANSI to ~20 KB.
 
-Identity coloring: every `project#task` renders its project half in
-a stable hue hashed from the project name (same project = same color
-in every run and every surface) and its task half in a fixed pink —
-both deliberately outside the status palette, so an id can never
-read as an outcome.
+Identity coloring: each half of a `project#task` renders in a stable
+hue hashed from its own name (same project = same color, same target
+name = same color, in every run and every surface: every `#build`
+matches), with a dim `#` between, all outside the status palette, so
+an id can never read as an outcome.
 
 On GitHub Actions (`GITHUB_ACTIONS` truthy, full output mode), each
 task's block is wrapped in `::group::<id> (<outcome> <duration>)` /
@@ -890,22 +913,22 @@ Locally-executed tasks always write in place and ignore the flag, and
 it in either direction. **It never affects a cache key**: transfer
 tuning cannot change what a command produces.
 
-One safety gate: a task whose outputs another task's `cache.inputs`
+One safety gate: a task whose outputs another task's `inputs`
 globs could read on disk is silently kept eager, because deferring it
 would make that key depend on whether the bytes arrived. A task with no
 `cache` that a cached task depends on counts as reading its whole
 project (C-16). `--dry` reports
 how many tasks would keep their outputs remote and names each downgrade,
 so a run that defers nothing says why. A run in which any task declares a
-`cache.inputs.runtime` / `workspaceRuntime` command defers **nothing**:
+`inputs.runtime` / `workspaceRuntime` command defers **nothing**:
 a shell command's reads cannot be bounded, so vx cannot prove it will
 not read a deferred output (the same reason vx refuses to infer inputs
 by tracing). When bytes are fetched later, vx saves an ordinary
 cache entry for them, so the next run is a plain local hit.
 
-## Planning mode (`--dry`, `--graph`)
+## Planning mode (`--dry`)
 
-Both flags short-circuit execution. They build the full task graph,
+`--dry` short-circuits execution. It builds the full task graph,
 compute every task's cache key, and probe the cache to predict the
 hit/miss outcome. Against a remote cache the probe is a lightweight
 existence check — planning never downloads or ingests artifacts.
@@ -913,8 +936,8 @@ existence check — planning never downloads or ingests artifacts.
 ```
 $ vx run ci --dry
 would run:
-  ◉  @vzn/vx#format-check  cache hit (local)         02bfe8a9
-  ◉  @vzn/vx#lint          cache hit (local)         d66cfed2
+  ✓  @vzn/vx#format-check  cache hit (local)         02bfe8a9
+  ✓  @vzn/vx#lint          cache hit (local)         d66cfed2
   ▶  @vzn/vx#test          cache miss — would exec   68595e49  ~72.64s
 
 3 task(s) planned, 2 cache hits (2 local), 1 would run.
@@ -947,11 +970,11 @@ Status legend:
 
 | Symbol | Meaning                                                                                    |
 | ------ | ------------------------------------------------------------------------------------------ |
-| `◉`    | cache hit (local) — entry already in `<cacheDir>/`                                         |
+| `✓`    | cache hit (local) — entry already in `<cacheDir>/`                                         |
 | `↓`    | cache hit (remote) — entry would be fetched from the layer                                 |
 | `▶`    | cache miss — task would execute (under `--force` too: nothing is read, what runs is saved) |
-| `·`    | no-cache — task opts out (no `cache` block, or `--no-cache`)                               |
-| `∅`    | `@noop` — task would not run anywhere                                                      |
+| `∅`    | no-cache — task opts out (no `cache` block, or `--no-cache`)                               |
+| `·`    | `@noop` — task would not run anywhere                                                      |
 | `−`    | not started — a server you did not request whose every dependant restores a local hit      |
 | `○`    | group task (suppressed in human view; in DOT + JSON)                                       |
 
@@ -998,8 +1021,8 @@ $ 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 a changed
-`file` no cached task of the project declares, often an output git does not
+project changed and the task reads it whole: a task with no `inputs`, or a
+changed `file` no 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),
@@ -1013,150 +1036,12 @@ against: a bare `--affected` guesses it (`origin/HEAD`, a trunk branch,
 else `HEAD~1`), so a reason that names no file may come from a commit
 the base reaches, a root `package.json` edit among them.
 
-### Task graph (`--graph`)
+## Run artifacts (`--profile`)
 
-`--graph` prints Graphviz DOT (stdout by default; `--graph=path`
-writes a file):
-
-```
-vx run ci --graph | dot -Tsvg > graph.svg
-vx run ci --graph=graph.dot
-```
-
-Node `fillcolor` varies by predicted status (green = local hit,
-sky-blue = remote hit, orange = miss, gray = no-cache, fuchsia =
-group, white = not started). Edges are unstyled.
-
-## Run artifacts (`--summarize`, `--profile`)
-
-Both flags add a side-effect after a real run completes. Errors
+`--profile` adds a side-effect after a real run completes. Errors
 writing the artifact are surfaced via `vx: failed to write …` but
 don't change the run's exit code — the run already happened.
 
-### `--summarize[=<path>]`
-
-Writes a per-run JSON file; `schemas/summary.json` is its JSON Schema:
-
-```json
-{
-  "runId": "01a0e3ef-206c-708d-95bf-c2b07211adf6",
-  "ok": true,
-  "exitCode": 0,
-  "startedAt": "2026-09-27T17:34:54.572Z",
-  "endedAt": "2026-09-27T17:34:54.586Z",
-  "totalMs": 14.123643,
-  "savedMs": 9,
-  "tasks": [
-    {
-      "id": "a#build",
-      "project": "a",
-      "task": "build",
-      "status": "cache-hit",
-      "exitCode": 0,
-      "durationMs": 3,
-      "hash": "48007ccadd42ed7d",
-      "storedDurationMs": 9,
-      "storedCpuMs": 2.059,
-      "wallclockStartNs": "9456491",
-      "wallclockEndNs": "12902888"
-    }
-  ],
-  "aborted": [],
-  "summary": {
-    "successful": 1,
-    "failed": 0,
-    "skipped": 0,
-    "cachedLocal": 1,
-    "restoredLocal": 0,
-    "restoredRemote": 0,
-    "upToDate": 1,
-    "cachedRemote": 0,
-    "aborted": 0,
-    "total": 1
-  }
-}
-```
-
-`runId` is a UUIDv7. Default path: `<cacheDir>/runs/<run_id>.json`. hrtime fields are
-strings (bigints serialized as strings) to preserve ns precision
-through JSON. `cpuMs` / `peakRssBytes` are what the task's own
-execution used and appear on executed rows only (`peakRssBytes` only
-when the task's peak rose above vx's own footprint — a lighter task's
-figure would be vx's, handed back by the kernel; a Linux sandboxed task
-reports neither, since what bwrap's pid namespace used never reaches vx);
-`restored` appears on a hit only: `true` when its outputs were restored,
-`false` when they were already up to date. A hit's `durationMs`
-is the restore it cost, and what the PRODUCING execution used rides the
-artifact and appears under its own keys, `storedDurationMs` /
-`storedCpuMs` / `storedPeakRssBytes` (the work the hit skipped) — a
-remote worker's peak is never presented as this run's. `savedMs` is
-their sum over the hits, the footer's `saved` as a number. `admissionHeldMs` appears on a row
-only when an `admit` policy (a plugin's — `@vzn/vx-schedule-history`
-packs learned reservations) refused the task while a worker was free:
-the wait from that first refusal to its dispatch, the plugin's hand on
-the run. The footer's `info` row sums the waits, task-seconds:
-`admit held 3 tasks, 4.2s in all` (85 held tasks can read 4783s beside
-a 160 s run).
-
-**`ok` / `exitCode`** are the run's verdict — the same value the CLI
-exits with: a stopping signal's code (130 for Ctrl-C), and with a kept
-server, its exit (the file is written again when the server ends). Gate on these rather than re-deriving a pass from the
-buckets: a run can be red without a single failed task (see `aborted`).
-
-**`tasks[]` and `summary` describe the same population**, so
-`tasks.length === summary.total` always holds. Group tasks (no `exec`)
-are in neither — they do no work.
-
-**`aborted[]`** lists tasks whose attempt ended while the run was
-stopping (Ctrl-C, a signal to vx), with their exit code, and tasks the stop reached before they started, with
-exit 1, `durationMs: 0` and no `wallclockStartNs`. Neither joins an
-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-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.
-
-**`notReady`** is present only on a failed persistent task: why it never
-became ready — `timeout` (the readiness deadline fired; `exitCode` is
-the kill's, 143 or 137 after the grace, and 143 for a server that
-traps the TERM and exits 0, as an ordinary timeout's),
-`exited` (the child exited first; `exitCode` is then its own) or `spawn`
-(the spawn itself failed). Every label reads it, `failed (never ready:
-timed out, exit 143)`. A server the run's stop (a Ctrl-C) killed while it started is
-`aborted`, not failed, as any task the stop kills; so is one that
-became ready only after the stop.
-
-**`sandboxViolations`** is present only on a sandboxed task with a
-SANDBOX VIOLATIONS section — the count of its denials (vx's own notes
-there count none), and the reason the task failed (its exit is forced to 1
-when it was 0); every label counts it, `failed (exit 1, 2 sandbox
-violations)`.
-
-**`timedOut: true`** is present only on a `failed` row vx's own
-`timeout` killed: its exit is the shell's 143, and every label reads
-`failed (timed out, exit 143)` rather than a signal.
-
-**`blockedBy`** is present only on a `skipped` row: the id of the failed
-(or aborted) task at the root of what blocked it, through any chain of
-skips between — what the skipped row prints, for a script.
-A fail-fast skip has none.
-
-**`flaky: { passes, failures, attempts }`** is present only on a task
-this run proved flaky (its row's `flaky` note, typed): `passes` and
-`failures` count the outcomes on record for this exact `hash`, this run
-included, and `attempts` is what this run took. A consumer gating on
-`status: "failed"` can tell a break (no `flaky` key) from a flake
-without reading the history. Every other row is byte-identical.
-
-**`durationMs` is always what THIS run spent on the task.** For a cache
-hit that is the probe + restore, not the exec time the entry was stored
-with — so it is small even for an expensive task. The work a hit
-_skipped_ is a different number; `--report`'s "N saved" is the surface
-that reports it.
-
 ### `--profile[=<path>]`
 
 Writes a Chrome-trace JSON of every task's wallclock span. Open in
@@ -1192,91 +1077,6 @@ from the per-task `hrtime.bigint()` spans the runner captures.
 
 Default path: `profile.json` (cwd-relative).
 
-### `--report[=markdown]`
-
-At the end of a real run, prints a markdown run report to **stdout**,
-just above the footer: nothing prints below the footer. The report
-itself is machine-clean. One header line of
-totals plus a table, one row per task:
-
-```markdown
-## vx run — passed
-
-**3 tasks** · 3 success · 0 failed · 2 cached (1 up-to-date, 1 restored) · 1.23s total · 2.65s saved
-
-| Task      | Status  | Cache      | Duration |
-| --------- | ------- | ---------- | -------- |
-| web#build | success | miss       | 1.23s    |
-| web#test  | success | local      | 5ms      |
-| api#test  | success | up-to-date | 3ms      |
-```
-
-`Status` is the task outcome (`success` / `failed (exit N)`, with the
-signal an exit above 128 stands for, `failed (exit 137, 128 + SIGKILL)`,
-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-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. 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.
-
-The two durations in the header mean different things, and the
-distinction is the point:
-
-- **`N total`** sums `Duration` over the tasks that actually EXECUTED,
-  an aborted task's time so far included — the time this run spent.
-- **`N saved`** sums the exec times the cache hits SKIPPED, read from
-  each entry as it was stored (above, 2.01s and 640ms). It is
-  deliberately not the hits' `Duration` column, which is the restore
-  they cost this run: summing that reported a task taking 2.01s cold
-  as "6ms saved".
-
-Only `markdown` is supported today (`json` is reserved; a bad value is a
-parse error). Built purely from the run's outcomes after it returns — it
-adds zero cost when both flags are absent.
-
-### `--report-file <path>`
-
-Writes the same markdown report to a file instead of (or as well as)
-stdout, and is the form to use for a CI step summary:
-
-```sh
-vx run ci --report-file="$GITHUB_STEP_SUMMARY"
-```
-
-**Do not redirect stdout for this.** The report itself is machine-clean,
-but stdout is not vx's alone — the status logger writes frames, meter
-bars and `::group::` workflow commands to the same stream, so
-`--report=markdown >> "$GITHUB_STEP_SUMMARY"` puts the entire run log
-into the step summary above the table.
-
-The report is **appended**, never truncated: `$GITHUB_STEP_SUMMARY` is a
-shared, append-only file that other steps in the same job also write to,
-so overwriting it would silently discard their content. Passing both
-flags writes the report to stdout AND appends it to the file. A run
-stopped by Ctrl-C or SIGTERM still writes both, its stopped tasks
-`aborted`. A write
-failure is reported (`vx: failed to write report to …`) but does not
-change the exit code — the run already happened, the same contract
-`--summarize` and `--profile` follow.
-
-### `--tag <k=v>`
-
-Labels the invocation. Repeatable; `--tag=k=v` form too. The pair is
-split on the **first** `=`, so values may contain `=` (e.g. a URL). An
-empty key is a parse error. Tags are recorded on the run's
-`invocations` row so dashboards can filter runs by label, and reach
-telemetry as `vx.tag.<key>`; a secret value in one is masked there as
-in the task's output (see [Masking](./schema.md)).
-
 ## Sandbox
 
 Sandbox isolation is opt-in **per task** via an `exec.sandbox` block in
@@ -1298,7 +1098,8 @@ export default {
           },
         },
       },
-      cache: { inputs: { files: ['src/**'] }, outputs: { files: ['dist/**'] } },
+      inputs: { files: ['src/**'] },
+      cache: { outputs: { files: ['dist/**'] } },
     },
   },
 }
@@ -1322,7 +1123,7 @@ task's `SANDBOX VIOLATIONS` section ends with a dimmed `fix:` line,
 the grants that would have allowed each denial, project-relative:
 `fix: exec.sandbox.allow: { read: ['tsconfig.json'], write: ['dist/'] }`.
 A write grants the top directory it landed in, so the next file there
-passes too, unless `cache.inputs.files` reads that directory: then it
+passes too, unless `inputs.files` reads that directory: then it
 grants the file alone, so the task cannot write its own inputs; a read the output depends on is a key input as well, and
 the line says so, since a grant never adds one. A credential path
 (`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.kube`, `~/.config/gh`,
@@ -1417,8 +1218,10 @@ run...` precedes it.
    not change since the loop last saw it is not an edit (a `chmod` is one,
    as the key reads the executable bit), nor is a directory
    whose entries (names and sizes) did not, nor a path that stayed
-   gone; a symlink is its target string, as the key folds it, so a
-   retarget is an edit; a path the loop has never judged is an edit only if it was
+   gone; a symlink is its target string and what it points to, as the
+   key folds them, so a retarget is an edit, and so is an edit behind
+   it: watch arms each link's target, wherever it lies, and names the
+   link; a path the loop has never judged is an edit only if it was
    modified after the watchers went live (macOS delivers the initial
    run's own writes after the arm; the later of the path's mtime and
    ctime says which side of it a path belongs to, so a file moved in
@@ -1449,7 +1252,7 @@ run...` precedes it.
    `.gitignore` as the remedy (a persistent task declares no outputs;
    item 948). A file git tracks is never blamed on the server: three
    saves of a source file are the user's (WD-7). When any project's config declares
-   `cache.inputs.workspaceFiles`, the per-project watchers are swapped
+   `inputs.workspaceFiles`, the per-project watchers are swapped
    for ONE recursive root watcher (boundaries are off for those globs,
    so a root-relative glob can name a file anywhere). That watcher
    hears every write in the tree and keeps only the ones a key can
@@ -1497,7 +1300,8 @@ Always ignored (no re-trigger):
 
 - `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
+  window, never per event), unless a task's inputs name it outright
+  (`.env.local`, `dist/**`): invisible to every other 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.
@@ -1509,7 +1313,7 @@ Always ignored (no re-trigger):
   cycle, which writes again — a loop that never settles.
 
 Everything else triggers a cycle. We deliberately don't filter events
-against per-task `cache.inputs.files` — the cache hash is the source
+against per-task `inputs.files` — the cache hash is the source
 of truth. A change to an irrelevant file produces a cache-hit run
 (typically tens of ms); the cost is much smaller than the engineering
 cost of a per-event glob match.
@@ -1553,10 +1357,10 @@ re-reads the watched set (item 971).
 The following flags are rejected (parser exits 1 before the initial
 run):
 
-- `--dry` / `--graph` — those skip execution; nothing to watch.
-- `--summarize` / `--profile` — would overwrite their target per cycle.
-- `--report` / `--report-file` / `--verbosity <n>` (n > 0) / `--format json` — all
-  format ONE run's result; a watch loop has no single run to report. (`--verbosity 0`
+- `--dry` — it skips execution; nothing to watch.
+- `--profile` — would overwrite its target per cycle.
+- `--verbosity <n>` (n > 0) — formats
+  ONE run's result; a watch loop has no single run to report. (`--verbosity 0`
   is accepted: it asks for what watch already prints.)
 
 A requested persistent task (`exec.persistent`, a dev server) starts
@@ -1581,7 +1385,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),
-  `run.killGrace` (2 s), then SIGKILL — and the process leaves only
+  a 2 s grace, 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`
@@ -2075,11 +1879,16 @@ 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:
+Every `@vzn/vx-*` plugin the same package.json lists from the registry
+moves in the same install, to the same release, since every @vzn
+package releases together: `pnpm add @vzn/vx@0.0.2 @vzn/vx-otel@0.0.2
+--save-dev`. A plugin left behind is installed even when core is
+already at the release (`› vx upgrade  plugins → 0.0.2`); a plugin in
+another field than core is refused, so no install moves a dependency's
+field. The versions are pinned, so pnpm's `minimumReleaseAge` refuses a
+release too young rather than mixing releases, and the error names
+`minimumReleaseAgeExclude`. vx prints what it runs, runs it there, and
+exits with an error if it fails:
 
 ```
 › vx upgrade  0.0.1 → 0.0.2
@@ -2087,6 +1896,28 @@ fails:
   bun add @vzn/vx@0.0.2 in /repo
 ```
 
+**Inside a project with its own vx**, a global vx hands `vx upgrade` to
+the project's (§ Which vx runs), and one run moves both to the same
+version (`TAG`, or latest): first the project's dependency, then the
+global vx that started the run, each the way it was installed. Each
+line names its install, and a refusal names the one that failed
+(`vx upgrade: global vx /usr/local/bin/vx: cannot write to …`); a
+project that fails leaves the global as it was. The project's vx run
+directly (a package script, `node_modules/.bin/vx`) has no global behind it, so only
+the project moves.
+
+```
+› vx upgrade  project 0.0.1 → 0.0.2
+
+  bun add @vzn/vx@0.0.2 in /repo
+
+› vx upgrade  global 0.0.1 → 0.0.2
+
+  /usr/local/bin/vx
+
+✓ vx upgrade  global installed 0.0.2
+```
+
 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.
@@ -2103,9 +1934,11 @@ or is missing.
 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
+command (owner, 2026-10-08): the latest release through `bun x`,
+never an installed one, so init always installs the latest `@vzn/vx`
+and moves every `@vzn/vx-*` plugin the root lists to it (M,
+2026-10-16; a source checkout runs the nearest installed
+`node_modules/@vzn/vx-migrate` instead) (`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`
@@ -2201,8 +2034,8 @@ none is dropped in silence. An Nx flag's camelCase spelling (`--nxBail`,
 `--skipNxCache`), which Nx's parser takes and its docs print, is its
 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 clean`), and
+either tool name what does it here: `graph` and `query` (`--dry=json`), `ls`
+(`vx show`), `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
@@ -2221,11 +2054,10 @@ copy to the source.
 | turbo  | `--continue=dependencies-successful`              | alias   | `--continue=deps-ok`                                                                                                                              |
 | turbo  | `--continue`                                      | same    | `--continue[=never\|deps-ok\|always]`                                                                                                             |
 | turbo  | `--dry-run`                                       | alias   | `--dry[=text\|json]`                                                                                                                              |
-| turbo  | `--graph=<file>.svg\|png\|json\|html\|…`          | refuse  | vx writes Graphviz DOT only: `--graph=<file>.dot`, then `dot -Tsvg`                                                                               |
-| turbo  | `--graph`                                         | same    | `--graph[=<file>.dot]`                                                                                                                            |
+| turbo  | `--graph`                                         | refuse  | `--dry=json` prints the planned task graph, each task with its deps                                                                               |
 | turbo  | `--force[=<bool>]`                                | same    | `--force`: skip cache reads, keep writes                                                                                                          |
 | turbo  | `--affected`                                      | same    | `--affected[=<base>]`                                                                                                                             |
-| turbo  | `--summarize[=<bool>]`                            | same    | `--summarize[=<path>]`                                                                                                                            |
+| turbo  | `--summarize`                                     | refuse  | use `vx last --format json` for the run's JSON record                                                                                             |
 | 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-policy local:r,remote:r`                                                |
@@ -2253,9 +2085,9 @@ copy to the source.
 | turbo  | `--dangerously-disable-package-manager-check`     | refuse  | vx reads no `packageManager` field: drop it                                                                                                       |
 | turbo  | `--env-mode <v>`                                  | refuse  | vx passes only the variables a task declares (strict): list the rest in `exec.env.passThrough`                                                    |
 | turbo  | `--framework-inference <v>`                       | refuse  | under `turbo()` inference is Turbo's; take a name back with a `!` entry in the task's `env`                                                       |
-| turbo  | `--global-deps <v>`                               | refuse  | declare them in `cache.inputs.workspaceFiles` (under `turbo()`, turbo.json's `globalDependencies`)                                                |
-| turbo  | `--json`                                          | refuse  | use `--format json` for the run's result on stdout, `--dry=json` for the plan                                                                     |
-| turbo  | `--log-file`                                      | refuse  | use `--summarize[=<path>]` for the run's JSON record                                                                                              |
+| turbo  | `--global-deps <v>`                               | refuse  | declare them in `inputs.workspaceFiles` (under `turbo()`, turbo.json's `globalDependencies`)                                                      |
+| turbo  | `--json`                                          | refuse  | use `vx last --format json` for the run's result, `--dry=json` for the plan                                                                       |
+| turbo  | `--log-file`                                      | refuse  | use `vx last --format json` for the run's JSON record                                                                                             |
 | 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                                                                                         |
@@ -2297,9 +2129,8 @@ copy to the source.
 ## Machine-readable output
 
 `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:
+`--format json`. Each prints one JSON document on one line, 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`
 (`node_modules/@vzn/vx/schemas/` in an install). Every object closes its
@@ -2311,13 +2142,9 @@ schemas: each `{ … }` a verb's section shows is an object its schema
 closes with those keys, each object the verb prints whole is shown, and
 `vx info`'s field list is its schema's top level.
 
-`vx run --format json` prints, when the run ends, the `--summarize`
-document (`schemas/summary.json`: `runId`, `ok`, `exitCode`, one row per
-task with its status, exit code and key). Everything else the run writes,
-the frame and the tasks' output with it, goes to stderr, so
-`vx run build --all --format json | jq .ok` reads only the result. It
-refuses `--dry` (use `--dry=json`), a bare `--graph` and
-`--report=markdown`, which print on stdout too.
+A run's result as JSON is `vx last --format json`, read after the run
+from the run history: one row per task with its status, key and cache
+result. `vx run --dry=json` prints the plan.
 
 ### Error codes
 
@@ -2433,8 +2260,9 @@ 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
+project edges; add pnpm()/bun()/npm()/yarn() and install so its
+lockfile exists, or a plugin that returns `deps` ``. A lockfile plugin
+whose lockfile is absent gives no edges. 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
@@ -2449,7 +2277,7 @@ its own output path, or make one depend on the other.
 
 #### `VX_E_INPUT_IS_OUTPUT`
 
-A task's `cache.inputs` match outputs: its own (vx cleans outputs before
+A task's `inputs` match outputs: its own (vx cleans outputs before
 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
@@ -2470,12 +2298,11 @@ https://github.com/vznjs/vx/issues.
 A plugin can give its refusal a code: `new UserError(message, 'MY_CODE')`.
 
 **Streams.** A verb whose stdout is a product (a `--format json`
-document, `--dry` / `--dry=json`, `--graph`'s DOT, a completion
+document, `--dry` / `--dry=json`, a completion
 script) writes that product alone there; a notice or warning it meets
 on the way (a cache index from another vx version, a plugin's warning) goes
 to stderr, as every refusal does. `vx run`'s stdout is the run's frame,
-the tasks' output it carries, except under `--format json`, where that
-moves to stderr. `tests/cli-streams.test.ts` holds each
+the tasks' output it carries. `tests/cli-streams.test.ts` holds each
 product verb to it under a notice.
 
 ## `vx show`
@@ -2571,6 +2398,9 @@ or `; projects and tasks: …` (M-57).
 
 An empty target (`vx show ''`) is refused: omit it to list every project.
 
+In a workspace with no project, the list is empty and `vx show` says so
+on stderr (`no projects`) and names `vx init`.
+
 Exit codes: `0` success; `1` parse error or unknown target.
 
 Two runs on one workspace take turns: the second waits for the first's
@@ -2614,7 +2444,7 @@ $ vx info
   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 versions    keys vx-cache-v43 · index schema v40
   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)
@@ -2783,7 +2613,7 @@ app#build — run 01a1193a-7b39-75a9-870b-5c03e26d7104
     changed file  packages/app/src/input.txt  78981922613b2afb6025042ff6bd878ac1994e85 → 61780798228d17af2d34fce4cfbdf35556832472
 
   what to do:
-    file  an edit re-runs by design; a file the task does not read belongs out of cache.inputs.files
+    file  an edit re-runs by design; a file the task does not read belongs out of inputs.files
 ```
 
 A changed key's verdict names what moved, kind and name, three at most
@@ -2824,7 +2654,7 @@ 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`.
 A row's kind is what the key folded: `file` (an input file, by blob
-id), `env` (a declared variable, by digest), `runtime` and
+id), `linked` (the content behind a `file` that is a symlink), `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 `--`),
 `config` (the evaluated task config), `upstream` (a dependency's input
@@ -2839,9 +2669,9 @@ is gone (pruned, or the run failed and never saved one) the verb still
 names the hash change and says the component diff is unavailable. When
 only the previous run failed, the diff is taken against the last run
 that saved an entry instead, and the detail line names that run. A
-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.
+task with `inputs` and 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, writers }`); when the task's recorded runs predate run ids, `{ taskId,
 why, diff, explanation }`, `why` and `diff` null and `explanation` the
@@ -2875,12 +2705,19 @@ command that exits 137 on its own reads the same). Where the run's
 footer gave a reason, the row ends with it instead: `timed out`,
 `never ready: exited`, `2 sandbox violations`, and for a skipped task
 `after lib#build failed` (the v27 columns; rows older than them read
-as before). Rows run failures first, then what executed or was
+as before). A task whose key met a remote failure ends with it, read or
+write alike: `remote ✗ download: connection refused; upload: 503` (the
+v40 column, `remoteError` in `--format json`). Rows run failures first, then what executed or was
 skipped, then hits; past sixteen hits the rest fold into one line with
 their count (`… +980 more cache hits`) — a thousand-task warm run is a
 thousand rows otherwise, with the one failure a screen above the
 prompt — and the sixteen shown are the slowest restores, the one thing
 a hit's row tells. `--format json` lists every row.
+Below the tasks, the steps the run did not wait on (`vx:prefetch`, a
+remote's downloads beside the tasks), which its own output never shows:
+`success  vx:prefetch  1.20s  internal`. They are kept per run, the
+newest 50, in `<cache dir>/steps/<run id>.json`, written only by a run
+that had one; `--format json` adds them as `steps`.
 `vx last --list` prints the N most recent runs (default 10), one per
 line in aligned columns (verdict, start, run id, counts, duration,
 command), each run id cut to the shortest prefix no other run shares, 13 characters at least (`--list 5`
@@ -2902,7 +2739,7 @@ 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 (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`
+a cached task, `inputs` the reads of its project no `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
@@ -3066,8 +2903,8 @@ names no package: it lists what the workspace itself declares.
 
 ## Environment variables vx reads
 
-Every setting has a variable derived from its path (`run.killGrace` →
-`VX_RUN_KILL_GRACE`), beating `.vx/workspace` and beaten by the flag; the
+Every setting has a variable derived from its path (`run.timeout` →
+`VX_RUN_TIMEOUT`), 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
@@ -3087,11 +2924,7 @@ what a TASK sees is `exec.env` in `docs/schema.md`.
 | `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'`).                                                                                             |
@@ -3121,9 +2954,8 @@ Colors are the two conventions in § Output format › Colors (`NO_COLOR`,
 `FORCE_COLOR`). A truthy `CI` picks the CI output flow and
 `GITHUB_ACTIONS` its `::group::` framing (§ Output); the run's
 `invocations` row records the provider, the first truthy of
-`GITHUB_ACTIONS`, `GITLAB_CI`, `BUILDKITE`, `CIRCLECI`, then `CI`. Core never reads `GITHUB_STEP_SUMMARY`: `--report`
-prints to stdout, and `--report-file=<path>` appends to a file, so on
-Actions pass `--report-file="$GITHUB_STEP_SUMMARY"`. A sandboxed
+`GITHUB_ACTIONS`, `GITLAB_CI`, `BUILDKITE`, `CIRCLECI`, then `CI`. Core never reads `GITHUB_STEP_SUMMARY`; the job summary is
+`@vzn/vx-ci`'s. A sandboxed
 task's temp dir sits under `CLAUDE_CODE_TMPDIR` (else `CLAUDE_TMPDIR`,
 else `/tmp/claude`), the sandbox runtime's own convention
 (`docs/modules/sandbox-runtime.md`).
@@ -3158,8 +2990,8 @@ write ../shared/notes.txt
 Every section is conditional: the `$ <command>` line only for an
 executed task (success or failed — a hit replays its stored output and
 shows none), `OUTPUT` only when the task wrote something,
-`SANDBOX VIOLATIONS (N)` only when the sandbox recorded some or vx
-has a note on a failure. The
+`SANDBOX VIOLATIONS (N)` only when the sandbox recorded some (`N`
+counts them) or `SANDBOX` when vx has only a note on a failure. The
 header carries the outcome (`restored-local • abc12345`, `failed (exit
 N)`, …) and the footer repeats it after the duration. A test renders
 this block and checks it against this page, byte for byte.
@@ -3206,17 +3038,27 @@ A broad run looks like:
 ```
 
 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 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
+the workspace, `tasks` is failed / success / skipped, `cache` has a
+segment per legend state (a skipped task rides it too, so the two bars
+fill alike; its count is on the tasks legend only). Its legend reads
+per layer: `local 1✓ 1∅ 2↓ 1↑ · remote 3↓ 4↑ 2✗ 1⇡`. `✓` 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, `✗` a task a remote read or write failed
+for, and `⇡` an upload still running (live only, always last). The
+region stays through vx's closing steps, worker rows gone, and the
+final footer replaces it in place. Each task counts once, under its strongest state: a
+failed remote read or write, then an upload running, then saved to a
+remote, then saved here, then restored, then fresh, then no cache; so
+a task saved here and uploaded is a remote `↑`. A key the remote already
+held is not sent, so it is no remote `↑`. Each count is painted
+in its segment's colour, number and glyph alike: `✓` green, `∅` dim,
+local blue, remote dark blue, `✗` and a miss red, `⇡` cyan; the
+`local` and `remote` words are dim. 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
+every count show only when non-zero. `vx last` names each remote
+failure on its task's row. 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
@@ -3234,12 +3076,22 @@ running a group focused surfaces its real member tasks instead.
 **Nothing below the footer.** The footer is the run's last word.
 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
+`--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_DEBUG_TIMING=1` table included. Cache housekeeping
 (`cache.retention`) prints nothing. Only a kept server's own output
 follows it.
 
+**Narrow terminals.** The footer is 62 columns: its rule and 50-cell
+bars. On a terminal narrower than that the bars shrink and the rule
+with them, as do a frame's section rules, so none wraps onto a second
+row. Off a terminal they keep their width.
+
+**Warnings on stderr.** A run's warnings, such as `[vx] app#build:
+cache.outputs matched no files …` or a plugin's, go to stderr. Stdout
+carries only the rows, the frames and the footer, so `vx run build >
+log.txt` keeps them out of the log.
+
 **Skipped rows.** A red run lists every task that never started as a
 row naming the failure that blocked it, so the footer's `1 skipped`
 always has a name above it:
@@ -3301,6 +3153,7 @@ ANSI truecolor (`ansi-16m`) sequences, gated by env:
 | `FORCE_COLOR=0` / `=false`  | Force off, on a TTY too.                                 |
 | `FORCE_COLOR=…` (any other) | Force on — `1`, `true`, `2`, `3`, the empty string, etc. |
 | (neither)                   | On iff `stdout.isTTY`.                                   |
+| `TERM=dumb`                 | Off unless `FORCE_COLOR` forces it, and no live region.  |
 
 `0` and `false` are `FORCE_COLOR`'s "off" by the convention
 supports-color, chalk and Node follow; until 2026-09-24 vx read every
@@ -3326,7 +3179,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 clean`), and the help off a
+`last`, a `--dry` plan, `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`).
@@ -3343,7 +3196,7 @@ Reads try local first, then remote (hydrating local on remote hit),
 with a background prefetch pass overlapping remote GETs with
 execution. Writes go to local immediately; the remote upload is a
 fire-and-forget background task drained at end of run — failures are
-logged via `onRemoteError` but never fail the build.
+warned but never fail the build.
 
 For any OTHER cache server (a Turbo-wire deployment, S3-direct, …),
 implement core's `RemoteCacheLayer` interface in a plugin's `cache`
@@ -3358,7 +3211,7 @@ consult).
 size, runs + hits in the last 24 h). For anything deeper, vx records
 every task to a `runs` table in `cache.db` (UUIDv7 `run_id`, hrtime
 wallclock spans, cpu_ms, peak RSS, status, cache_hit flag) plus one
-`invocations` header row per run (command, git/CI context, tags,
+`invocations` header row per run (command, git/CI context,
 counts). The SQLite file IS the API:
 
 ```sh
@@ -3407,7 +3260,7 @@ Surface:
 
 - `run(options)` — execute. Returns `Promise<RunSummary>`.
 - `planRun(options)` — predict, no execute. Returns
-  `Promise<RunPlan>`. Used by `--dry` / `--graph`.
+  `Promise<RunPlan>`. Used by `--dry`.
 - `prepareRun(options, log)` — the shared setup (discovery → configs →
   graph → cache). What an embedder builds on.
 - `defineProject` / `defineWorkspace` — identity helpers for type