@vzn/vx 0.0.638 → 0.0.639

package/docs/execution.md

@@ -24,7 +24,7 @@ terminal and a task succeeding or failing. Read it alongside
  │       PROCESS — always. (A whole-run `backend` seam existed until
  │       2026-08; it moved the scheduler server-side, which is why it
  │       went. Per-task placement is the `executor` capability.)
- │       --dry / --graph short-circuit into planRun instead.
+ │       --dry short-circuits into planRun instead.
  │
  ├─ Prepare (src/orchestrator/prepare.ts:prepareRun — shared with planRun)
  │    1. findWorkspaceRoot(cwd) — the directory of the nearest
@@ -155,7 +155,7 @@ terminal and a task succeeding or failing. Read it alongside
  │                signal, forward it (SIGHUP as SIGTERM) to everything
  │                in liveChildren + persistentRegistry (and kill any
  │                running cache.inputs.runtime probe, C-65), wait
- │                VX_RUN_KILL_GRACE (2 s) for their groups, SIGKILL
+ │                2 s for their groups, SIGKILL
  │                what is still there, let the run finish its own
  │                end (flush, teardown, cache close), then
  │                die of the signal (SIGINT → 130, SIGTERM → 143,
@@ -303,11 +303,10 @@ terminal and a task succeeding or failing. Read it alongside
     2. Run summary footer (projects / tasks / cache meters + info +
        time + result) — counts only real tasks (with `exec`); group tasks
        don't pollute the totals; failure frames replay just above it.
-    3. Optional --summarize JSON (default <cacheDir>/runs/<run_id>.json)
-       and --profile Chrome-trace JSON (default profile.json).
+    3. Optional --profile Chrome-trace JSON (default profile.json).
     4. recordRunBundle — one transaction writing a `runs` row per real
        task plus the `invocations` header row (command, git/CI/host
-       context, tags, counts). Group + aborted tasks skipped; a run
+       context, counts). Group + aborted tasks skipped; a run
        a signal stopped records nothing.
     5. Telemetry: emit the RunSummaryRecord to every active sink +
        await their flush (crash-isolated; skipped when no sink).
@@ -325,11 +324,7 @@ terminal and a task succeeding or failing. Read it alongside
        alive, Ctrl-C reaps the process group. That first exit ends the
        session: the others are torn down (SIGTERM, grace, SIGKILL) and
        a non-zero exit makes the run exit 1, so a script's `vx run dev`
-       fails when the server it started fell over. That server then reads
-       `failed` with its own exit in the rewritten `--summarize` and in the
-       report `--report-file` writes; one a Ctrl-C stopped does not. The
-       stdout `--report` prints above the footer, so it reads as the
-       footer does, before the wait. Under
+       fails when the server it started fell over. Under
        `holdPersistent` (the watch loop) run() instead returns them on
        `RunSummary.persistent`, still running, for the caller to stop;
        one that dies on its own after that is said, its `stop()` is not.
@@ -543,21 +538,20 @@ Every surface uses one outcome vocabulary: task axis `success` /
 `failed` / `skipped` / `aborted` (+ `running` live), cache axis
 `miss` / `up-to-date` (fresh) / `local` / `remote`. The `--verbosity 1`
 table spells the combinations out as `success` / `restored-local` /
-`restored-remote` / `up-to-date`; `--report` keeps the two axes as its
-Status and Cache columns.
+`restored-remote` / `up-to-date`.
 
 The colors / framing modules:
 
 - `util/colors.ts` — ANSI truecolor (`ansi-16m`), gated by
   `NO_COLOR` / `FORCE_COLOR` / `isTTY`. Programmatic-logger callers
   always see plain text.
-- `orchestrator/framed-output.ts` — the `┌─` frames, the glyph grid
+- `report/framed-output.ts` — the `┌─` frames, the glyph grid
   (`formatTaskRow`), one-liners, persistent markers.
-- `orchestrator/status-line.ts` — the serialized writer + the worker
+- `report/status-line.ts` — the serialized writer + the worker
   region.
-- `orchestrator/logger.ts` — composes them; resolves the output view
+- `report/logger.ts` — composes them; resolves the output view
   and applies the per-flow visibility policy.
-- `orchestrator/summary.ts` — the closing footer (wordmark rule,
+- `report/summary.ts` — the closing footer (wordmark rule,
   projects/tasks/cache meters, info and time rows).
 
 ## Concurrency
@@ -617,9 +611,9 @@ snapshot is clean). `--cache-policy=<spec>` gives per-layer control. Full
 semantics: [`cli.md` § Cache control](./cli.md#cache-control---cache-policy---no-cache---force)
 and [`caching.md` § Cache policy](./caching.md#cache-policy-readwrite-axes).
 
-## Planning paths (`--dry`, `--graph`)
+## Planning path (`--dry`)
 
-Both short-circuit execution. The planner (`orchestrator/plan.ts`)
+`--dry` short-circuits execution. The planner (`orchestrator/plan.ts`)
 runs the same setup steps — workspace discovery, config load, package
 graph, task graph — and the same per-task hash derivation, then
 probes the cache. The probe is read-only; against a remote layer it
@@ -628,8 +622,6 @@ deliberate side effect: `cache.inputs.runtime` / `workspaceRuntime`
 probe commands DO run, because predicting a key requires resolving
 them — keep runtime inputs side-effect-free.
 
-The two flags differ only in output format:
-
 - `--dry[=text|json]` → text (default) or JSON list of predicted
   outcomes per task: `hit-local`, `hit-remote`, `miss`, `no-cache`,
   `group`. Formatter: `cli/plan-format.ts:formatPlanText` /
@@ -639,36 +631,19 @@ The two flags differ only in output format:
   executors is a plugin-factory call, the same class the cache capability
   already makes at plan time; a plugin that throws costs the label, never
   the plan.
-- `--graph[=<path>]` → Graphviz DOT, colored by predicted status.
-  Pipe to `dot` for SVG/PNG render. Formatter:
-  `formatGraphDot`.
-
-Mutually exclusive: `--dry` and `--graph` together is a parse error.
-Combining either with `--summarize`, `--profile`, `--report` or
-`--report-file` is a parse error (those need a real run; the last two
-were accepted and wrote nothing until item 992).
+  Combining it with `--profile` is a parse error (the profile needs a
+  real run).
 
 ## Run artifacts
 
-- **`--summarize[=<path>]`** — per-run JSON to
-  `<cacheDir>/runs/<run_id>.json` by default (or the explicit path).
-  Mirrors the `runs` table shape — one task entry per real task, hits
-  included, with status, hash, duration, cpu_ms, peak RSS, hrtime spans
-  (bigint serialized as strings to preserve ns precision).
 - **`--profile[=<path>]`** — Chrome-trace JSON of every task's
   wallclock span. Default path: `profile.json` (cwd-relative). One
   `tid` per project so concurrent tasks render on distinct lanes.
   Open with `chrome://tracing` or https://ui.perfetto.dev.
-- **`--report[=markdown]`** — a markdown table to stdout
-  above the footer (CI step summaries), through `RunOptions.beforeFooter`.
-- **`--report-file <path>`** — the same report APPENDED to `<path>`
-  (`$GITHUB_STEP_SUMMARY`).
-
-Writers live in `orchestrator/run-artifacts.ts:writeRunSummary` /
-`writeRunProfile` and `orchestrator/run-report.ts`. A `--summarize` or
-`--profile` write error is surfaced via `log.status`, a `--report-file`
-one on stderr (`cli/run.ts`); neither changes the run's exit code — the
-run already happened.
+
+The writer is `orchestrator/run-artifacts.ts:writeRunProfile`. A write error is surfaced via `log.status` and does
+not change the run's exit code — the run already happened. A CI job
+summary is `@vzn/vx-ci`'s.
 
 ## Why each rule
 

package/docs/features.md

@@ -26,7 +26,7 @@ config key or an environment variable is missing here.
 - **Task picker** — `vx run` with no task in a terminal lists tasks to pick. [page](https://vznjs.github.io/vx/features/task-picker/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
 - **Typo hints** — an unknown task, project or filter suggests the nearest name. [page](https://vznjs.github.io/vx/features/filter-hints/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
 - **Turbo and Nx spellings** (`-t`, `-p`, `--exclude`, `--parallel`, `--base`, `--dry-run`, `--skip-nx-cache`) — accepted, or refused naming the vx spelling. [page](https://vznjs.github.io/vx/features/turbo-nx-flags/) · post: [Flags you already know](https://vznjs.github.io/vx/blog/flags-you-already-know/)
-- **Ctrl-C leaves nothing running** (`--kill-grace`, `--teardown-timeout`, `run.killGrace`, `run.teardownTimeout`, `VX_RUN_KILL_GRACE`, `VX_RUN_TEARDOWN_TIMEOUT`) — the whole process tree stops, then teardown runs. [page](https://vznjs.github.io/vx/features/ctrl-c/) · post: [Ctrl-C leaves nothing running](https://vznjs.github.io/vx/blog/ctrl-c/)
+- **Ctrl-C leaves nothing running** — the whole process tree stops, then teardown runs. [page](https://vznjs.github.io/vx/features/ctrl-c/) · post: [Ctrl-C leaves nothing running](https://vznjs.github.io/vx/blog/ctrl-c/)
 - **Longest chain first** — the scheduler starts the critical path first; `@vzn/vx-schedule-history` learns it from past runs. [page](https://vznjs.github.io/vx/features/critical-path/) · post: [Bitsets, popcount, and a scheduler tick](https://vznjs.github.io/vx/blog/bitsets-and-the-scheduler/)
 - **Schedule strategy** (`--schedule`, `run.schedule`, `VX_RUN_SCHEDULE`) — pick the order with no timings: most work waiting (default), longest chain, most direct dependents, or ready order; plugins still lead. [page](https://vznjs.github.io/vx/features/critical-path/) · post: [Which task runs first?](https://vznjs.github.io/vx/blog/scheduling-strategies/#pick-the-guess)
 - **No daemon** — every run starts cold and still answers in milliseconds. [page](https://vznjs.github.io/vx/features/no-daemon/) · post: [No daemon, on purpose](https://vznjs.github.io/vx/blog/no-daemon/)
@@ -47,23 +47,20 @@ config key or an environment variable is missing here.
 - **Run summary** — one block: projects, tasks, cache, time; nothing prints below it. [page](https://vznjs.github.io/vx/features/run-summary/) · post: [A run you can read](https://vznjs.github.io/vx/blog/a-run-you-can-read/)
 - **Per-task table** (`--verbosity`) — a per-task summary after the run. [page](https://vznjs.github.io/vx/features/per-task-table/) · post: [One failure, and exactly what it takes down](https://vznjs.github.io/vx/blog/when-a-build-fails/)
 - **Failed output kept for agents** — a failure's full log is saved and pointed to. [page](https://vznjs.github.io/vx/features/failed-output-kept/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
-- **Markdown report** (`--report`, `--report-file`) — a run report for a PR or `$GITHUB_STEP_SUMMARY`. [page](https://vznjs.github.io/vx/features/markdown-report/) · post: [Output that fits the run](https://vznjs.github.io/vx/blog/output-that-fits-the-run/)
-- **Run JSON** (`--summarize`) — per-run JSON for scripts, with the time the cache saved (`savedMs`). [page](https://vznjs.github.io/vx/features/run-json/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
 - **Trace profile** (`--profile`) — Chrome-trace JSON of the run. [page](https://vznjs.github.io/vx/features/profile/) · post: [Output that fits the run](https://vznjs.github.io/vx/blog/output-that-fits-the-run/)
 - **Run branch** (`--branch`, `VX_RUN_BRANCH`) — name the branch a run records in its history and forecasts from; unset, git's branch, then the CI provider's. no post
-- **Run tags** (`--tag`) — label a run; recorded in history. [page](https://vznjs.github.io/vx/features/run-tags/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
 - **Stage timing** (`VX_DEBUG_TIMING`) — vx's own stage table, for performance work. [page](https://vznjs.github.io/vx/features/stage-timing/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
 - **Output flows** — what is printed follows the run's intent (focused, broad or CI); a truthy `CI` wins. [page](https://vznjs.github.io/vx/features/output-flows/) · post: [Output that fits the run](https://vznjs.github.io/vx/blog/output-that-fits-the-run/)
 - **Cache-aware glyphs** — each task line's glyph shows ran, fresh, restored locally or remotely, failed, skipped or persistent. [page](https://vznjs.github.io/vx/features/cache-glyphs/) · post: [Output that fits the run](https://vznjs.github.io/vx/blog/output-that-fits-the-run/)
 - **GitHub Actions log groups** — on Actions, each task's block folds in a `::group::` with its outcome and time. [page](https://vznjs.github.io/vx/features/actions-log-groups/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
-- **Colors** (`NO_COLOR`, `FORCE_COLOR`) — truecolor output, forced on or off by env. [page](https://vznjs.github.io/vx/features/colors/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
+- **Colors** (`NO_COLOR`, `FORCE_COLOR`) — truecolor output, forced on or off by env; `TERM=dumb` prints plain, with no live region. [page](https://vznjs.github.io/vx/features/colors/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
 - **Signal-named exits** — a failure reads `exit 137, 128 + SIGKILL`. [page](https://vznjs.github.io/vx/features/signal-exits/) · post: [When a task misbehaves](https://vznjs.github.io/vx/blog/tasks-that-misbehave/)
+- **vx's own steps as rows** — on a terminal, what vx does around the tasks (`vx:uploads`, `<plugin>:teardown`) shows as a running row once it passes 150 ms, then a list row; never counted as a task. no post
 - **Plain output off a TTY** — no live region, and a missing task lists tasks instead of opening the picker. [page](https://vznjs.github.io/vx/features/plain-off-tty/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
 
 ## Plan and explain
 
 - **Dry run** (`--dry`) — the task graph and the predicted hits and misses, text or JSON (with the predicted wall time and its critical path), nothing runs. [page](https://vznjs.github.io/vx/features/dry-run/) · post: [See the plan before you run it](https://vznjs.github.io/vx/blog/dry-run/)
-- **Graph** (`--graph`) — the task graph as Graphviz DOT. [page](https://vznjs.github.io/vx/features/task-graph/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
 - **vx why** (`vx why`, `--run`) — why a task re-ran, down to the file, env var or config that changed, and the task that wrote a moved input. [page](https://vznjs.github.io/vx/features/vx-why/) · post: [Why did this re-run?](https://vznjs.github.io/vx/blog/why-did-this-rerun/)
 - **vx show** (`vx show`) — every project, a project's or a task's resolved config, read from the lock as a run reads it. [page](https://vznjs.github.io/vx/features/vx-show/) · post: [See what a task really is](https://vznjs.github.io/vx/blog/vx-show/)
 - **vx last** (`vx last`, `--list`, `--failed`, `--log`, `--stats`, `--branch`) — replay a recorded run's summary, list recent runs, print one task's output, or per-task history stats (p50 as the live estimate forecasts it on a branch, p99, pass and hit rate, failure mode, peak RSS). [page](https://vznjs.github.io/vx/features/vx-last/) · post: [The last run, on request](https://vznjs.github.io/vx/blog/vx-last/)
@@ -91,7 +88,7 @@ config key or an environment variable is missing here.
 - **Lockfile-aware keys** (`@vzn/vx-lockfile`: `pnpm()`, `bun()`, `npm()`, `yarn()`) — a bump re-keys only the projects whose closure changed; each also adds every member with a `package.json` as a project named by its `name`, gives vx the project edges the lockfile records (core reads no `package.json`), keys each package's `package.json` as an input and folds its manager's install settings (`.npmrc`, `bunfig.toml`, `pnpm-workspace.yaml`, `.yarnrc.yml`) into every task. Core keys no package file, so without one an install re-keys nothing; `npm()` reads `npm-shrinkwrap.json` first, and `bun()` refuses a lone `bun.lockb`. [page](https://vznjs.github.io/vx/features/lockfile-keys/) · post: [A lockfile bump should re-key two tasks](https://vznjs.github.io/vx/blog/lockfile-aware-keys/)
 - **Upfront keys** (`run.rules.upfrontKeys`, `VX_RUN_RULES_UPFRONT_KEYS`) — refuses an input glob a same-project task's outputs could match, so every key is known before anything runs. [page](https://vznjs.github.io/vx/features/upfront-keys/) · post: [Cascade through dependencies by folding input keys, never outputs](https://vznjs.github.io/vx/blog/cascade-through-inputs/)
 - **Dependency rules** (`run.rules.dependencies`) — `vx lock` refuses a project depending on one a tag or name rule denies or does not allow, every broken edge named (`VX_E_DEPENDENCY_RULE`). [schema](https://vznjs.github.io/vx/schema/) · post: [Say which projects may depend on which](https://vznjs.github.io/vx/blog/dependency-rules/)
-- **Cache controls** (`--no-cache`, `--force`, `--cache-policy`, `--cache-policy`, `VX_CACHE_POLICY`, `cache.policy`) — off, refresh, or per-layer read/write. [page](https://vznjs.github.io/vx/features/cache-controls/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
+- **Cache controls** (`--no-cache`, `--force`, `--cache-policy`, `--cache-policy`, `VX_CACHE_POLICY`, `cache.policy`) — off, re-run past it, or per-layer read/write. [page](https://vznjs.github.io/vx/features/cache-controls/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
 - **Cache location** (`--cache-dir`, `cache.dir`, `VX_CACHE_DIR`) — where the cache lives. [page](https://vznjs.github.io/vx/features/cache-location/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
 - **Cache scope** (`cache.scope`, `VX_CACHE_SCOPE`, `--cache-scope`) — a scope reads the default entries, then its own, and writes only its own. [page](https://vznjs.github.io/vx/features/cache-scope/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
 - **Cache pruning** (`vx cache clean`, `--older-than`, `--max-size`, `--global`, `--dry-run`, `cache.retention`, `maxSize`, `olderThan`, `VX_CACHE_RETENTION_MAX_SIZE`, `VX_CACHE_RETENTION_OLDER_THAN`) — evict by age or size, LRU; with no bound, clear this repo's store (shared by its checkouts) and run history; `--global` clears every repo's store. [page](https://vznjs.github.io/vx/features/cache-prune/) · post: [One command to know your workspace](https://vznjs.github.io/vx/blog/know-your-workspace/)
@@ -101,7 +98,7 @@ config key or an environment variable is missing here.
 - **Hits replay both streams** — stdout and stderr come back in the order the run printed them. [page](https://vznjs.github.io/vx/features/both-streams/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Restore lane** — cache restores run on their own lane, up to twice `--concurrency`. [page](https://vznjs.github.io/vx/features/restore-lane/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Line-ending-correct keys** — files git filters (`eol`, `core.autocrlf`) key on the bytes the build sees. [page](https://vznjs.github.io/vx/features/line-endings/) · post: [Your cache key is already in git's index](https://vznjs.github.io/vx/blog/keys-from-git/)
-- **Background remote uploads** — remote writes drain at the end of the run and never fail the build. [page](https://vznjs.github.io/vx/features/background-uploads/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
+- **Background remote uploads** — remote writes drain at the end of the run and never fail the build; the footer counts them running (`⇡`) and failed (`✗`). [page](https://vznjs.github.io/vx/features/background-uploads/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Bring your own remote cache** (plugin `cache`) — plug any cache server in through one interface. [page](https://vznjs.github.io/vx/features/custom-remote-cache/) · post: [Extend vx in an afternoon](https://vznjs.github.io/vx/blog/extend-vx/)
 
 ## Correctness
@@ -119,11 +116,11 @@ config key or an environment variable is missing here.
 ## Daily work
 
 - **Watch mode** (`vx watch`, `--poll`, `watch.poll`, `VX_WATCH_POLL`, `VX_DEBUG_WATCH`) — re-run what a change affects, on content, not events. [page](https://vznjs.github.io/vx/features/watch/) · post: [Watch: a content gate](https://vznjs.github.io/vx/blog/watch-mode/)
-- **Dev servers in the graph** (`exec.persistent`, `readyWhen`, `--ready-notice`, `run.readyNotice`, `VX_RUN_READY_NOTICE`) — a server is a node; dependents start when it is ready. [page](https://vznjs.github.io/vx/features/dev-servers/) · post: [Dev servers as graph nodes](https://vznjs.github.io/vx/blog/dev-servers-in-the-graph/)
+- **Dev servers in the graph** (`exec.persistent`, `readyWhen`) — a server is a node; dependents start when it is ready. [page](https://vznjs.github.io/vx/features/dev-servers/) · post: [Dev servers as graph nodes](https://vznjs.github.io/vx/blog/dev-servers-in-the-graph/)
 - **Interactive tasks** (`exec.interactive`) — a task that owns the terminal. [page](https://vznjs.github.io/vx/features/interactive-tasks/) · post: [When a task misbehaves](https://vznjs.github.io/vx/blog/tasks-that-misbehave/)
 - **Shell completions** (`vx completions`) — bash, zsh, fish. [page](https://vznjs.github.io/vx/features/completions/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
 - **Project-local vx** (`VX_HANDED_OFF`) — a global vx hands every call to the project's own `@vzn/vx`. [page](https://vznjs.github.io/vx/cli/#which-vx-runs)
-- **vx upgrade** (`vx upgrade`) — upgrade vx the way it was installed: a verified binary, or its package manager. [page](https://vznjs.github.io/vx/features/upgrade/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)
+- **vx upgrade** (`vx upgrade`) — upgrade vx the way it was installed: a verified binary, or its package manager. Inside a project, the project's vx and the global vx that ran it move together. [page](https://vznjs.github.io/vx/features/upgrade/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)
 - **Help and version** (`vx help`, `vx version`) — every verb's reference. [page](https://vznjs.github.io/vx/features/help-and-version/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)
 - **Did-you-mean** — a mistyped flag or verb gets the nearest valid spelling. [page](https://vznjs.github.io/vx/features/did-you-mean/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
 - **Task typed as a verb** — `vx build app` answers with the exact `vx run` command that does it. [page](https://vznjs.github.io/vx/features/task-as-verb/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)

package/docs/patterns.md

@@ -161,19 +161,17 @@ Turbo-aware cache server can transit our blobs unchanged.
 | `--concurrency <n>`                                                                | Turbo          | `src/cli/run.ts`                    |
 | `--no-cache` (all off) / `--force` (reads off, writes on) — distinct, not synonyms | Turbo-adjacent | `src/cli/run.ts`                    |
 | `--dry` / `--dry=json` (plan output)                                               | Turbo          | `src/orchestrator/plan.ts`          |
-| `--graph[=<path>]` (DOT)                                                           | Turbo + Nx     | `src/cli/plan-format.ts`            |
-| `--summarize[=<path>]` (per-run JSON)                                              | Turbo          | `src/orchestrator/run-artifacts.ts` |
 | `--profile[=<path>]` (Chrome-trace)                                                | Turbo          | `src/orchestrator/run-artifacts.ts` |
 | `--affected[=<base>]`                                                              | Turbo + Nx     | `src/workspace/affected.ts`         |
 | `watch <task>` subcommand                                                          | Turbo + Nx     | `src/cli/watch.ts`                  |
 
 ### Output presentation
 
-| Pattern                                              | Source                                           | vx source                                           |
-| ---------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------- |
-| Framed per-task blocks (`┌─ … └─`)                   | Turbo                                            | `src/orchestrator/framed-output.ts`                 |
-| End-of-run summary footer (task/cache meters + time) | Turbo-adjacent (vx renders meters, not a banner) | `src/orchestrator/summary.ts`                       |
-| Per-task output buffered until task finishes         | Turbo                                            | `src/orchestrator/framed-output.ts` ("Turbo-style") |
+| Pattern                                              | Source                                           | vx source                                     |
+| ---------------------------------------------------- | ------------------------------------------------ | --------------------------------------------- |
+| Framed per-task blocks (`┌─ … └─`)                   | Turbo                                            | `src/report/framed-output.ts`                 |
+| End-of-run summary footer (task/cache meters + time) | Turbo-adjacent (vx renders meters, not a banner) | `src/report/summary.ts`                       |
+| Per-task output buffered until task finishes         | Turbo                                            | `src/report/framed-output.ts` ("Turbo-style") |
 
 (There is no `>>> FULL TURBO`-style all-cached banner — a fully-green
 cache meter carries the message.)

package/docs/schema.md

@@ -376,7 +376,7 @@ for it to exit. Instead it considers the task "ready":
   The trailing partial line is tested too, so prompt-style banners
   without a newline (`printf 'Listening on :3000'`) count, and so does
   output read up to 250 ms after the shell exits. A server
-  not ready after 10 s (`run.readyNotice`) is said once, naming
+  not ready after 10 s is said once, naming
   the pattern it waits for, and whether `exec.timeout` bounds the wait.
 
 ```ts
@@ -609,7 +609,7 @@ replays, the command a cache entry stores (what `vx why` prints and a
 remote cache receives), the `$ command` line, telemetry records,
 `vx show`, the hashes `vx why` gives for such a variable in
 `cache.inputs.env` (its value, unsalted: the row names it and its change), an executor's error, a plugin's warning or failure (a remote's reply; the failure masked in the error `run()` rejects with), a failed `cache.inputs` runtime probe's error (its command and output), and the run's own invocation line that `vx last` prints (a
-secret passed after `--`) and its `--tag`s. So are every string of a
+secret passed after `--`). So are every string of a
 task `vx show` prints (a runtime probe, `readyWhen`, the description),
 the description `--dry` and the task picker print, a runtime probe's
 command as the run history stores it and `vx why` names its row (two
@@ -676,8 +676,8 @@ Semantics:
   edge from a `package.json`) and the cross-project `pkg#task` edges.
   With no plugin returning `deps` the workspace has no edge source and
   a `'^name'` is refused (`VX_E_DEPENDS_ON`: "`^build` needs project
-  edges; add pnpm()/bun()/npm()/yarn() or a plugin that returns
-  `deps`"): it would resolve to nothing and fold no upstream into the
+  edges; add pnpm()/bun()/npm()/yarn() and install so its lockfile
+  exists, or a plugin that returns `deps`"): it would resolve to nothing and fold no upstream into the
   key. With one, a project with no deps is a leaf; each path stops at the first dep
   that declares the task and an edge is added to it (Turbo/Nx
   direct-deps parity). The holder's own `dependsOn` is responsible
@@ -892,8 +892,8 @@ Always applied to every glob pass (regardless of what you wrote):
   itself via its own output. A path an output `!` entry takes back is
   no output, so it stays an input (A-44). Another task's outputs are
   not excluded for you: an input glob that can match them is refused
-  while `rules.upfrontKeys` is on (X-54). Write the exclusion,
-  `['**/*', '!dist/**']`. An input entry the task's OWN outputs take
+  while `rules.upfrontKeys` is on (X-54), unless git ignores them
+  whole. Write the exclusion, `['**/*', '!dist/**']`, or ignore `dist/`. An input entry the task's OWN outputs take
   back whole is always refused (X-55): vx removes outputs before a run,
   so a formatter declaring `src/**` as both would delete its sources. A
   task that rewrites files in place declares no outputs.
@@ -1261,7 +1261,9 @@ uses, so `dist` collides with `dist/app.js` (item 442). A whole subtree
 collides with any glob whose literal head lies inside it: `dist/**` with
 `dist/extra/**` or `dist/*.js` (item 941). Two globs a path built from
 either one matches are one too: `**/*` and `**/dist/**` both match
-`x/dist/x`. Globs that only _might_
+`x/dist/x`. A pair is no overlap where one task's `!` output entry
+takes the other's glob back whole: `['**/dist', '!types/**']` beside
+`types/**` (a `!` entry is never cleaned or captured). Globs that only _might_
 overlap (`dist/*` and `dist/sub/**`) are let through; there, last
 restore wins. A workspace output is also compared with every other
 project's `files` outputs, read from the root: `packages/b/dist/a.txt`
@@ -1644,9 +1646,6 @@ export default defineWorkspace({
     affectedBase: 'origin/main',
     schedule: 'most-work',
     continue: 'deps-ok',
-    killGrace: '2s',
-    teardownTimeout: '3s',
-    readyNotice: '10s',
     rules: {
       exclusiveOutputs: true,
       upfrontKeys: true,
@@ -1687,36 +1686,33 @@ default and where it came from.
 
 <!-- settings table: generated by tests/settings.test.ts -->
 
-| Setting                                        | Variable                            | Flag                 | Value                                                                   | Default                                    | What it does                                                                                                                                        |
-| ---------------------------------------------- | ----------------------------------- | -------------------- | ----------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `run.concurrency`                              | `VX_RUN_CONCURRENCY`                | `--concurrency`      | a positive integer, or a share of the cores like '50%'                  | the cores this process may use             | Tasks at once: a positive integer, or a share of the cores (`'50%'`).                                                                               |
-| `run.schedule`                                 | `VX_RUN_SCHEDULE`                   | `--schedule`         | one of 'most-work', 'critical-path', 'direct-dependents', 'ready-order' | most-work                                  | Which ready task starts first when there are more than workers.                                                                                     |
-| `run.affectedBase`                             | `VX_RUN_AFFECTED_BASE`              | —                    | a non-blank string                                                      | origin/HEAD, then the trunk, else HEAD~1   | The git ref a bare `--affected` compares with.                                                                                                      |
-| `run.branch` (variable or flag only)           | `VX_RUN_BRANCH`                     | `--branch`           | a non-blank string                                                      | git's branch, then the CI provider's       | The branch a run records in its history and forecasts from. Flag and env only: a committed branch would be wrong on every other branch.             |
-| `run.timeout`                                  | `VX_RUN_TIMEOUT`                    | `--timeout`          | a duration like '500ms', '30s' or '5m', at most 24 days                 | none                                       | A task's time limit, for tasks without their own `exec.timeout` (`'30m'`). A task's own `exec.timeout` beats it.                                    |
-| `run.retries`                                  | `VX_RUN_RETRIES`                    | `--retries`          | a non-negative integer                                                  | 0                                          | Re-runs of a failed task, for tasks without their own `exec.retries`. A task's own `exec.retries` beats it.                                         |
-| `run.continue`                                 | `VX_RUN_CONTINUE`                   | `--continue`         | one of 'never', 'deps-ok', 'always'                                     | deps-ok                                    | What a failed task takes down: `never` stops the run, `deps-ok` skips its dependents, `always` runs them too.                                       |
-| `run.outputLogs` (variable or flag only)       | `VX_RUN_OUTPUT_LOGS`                | `--output-logs`      | one of 'full', 'errors-only', 'hash-only', 'none'                       | `full` on CI, else by what the run selects | Which task output the run prints. Chosen before the workspace loads, so flag and env only.                                                          |
-| `run.killGrace`                                | `VX_RUN_KILL_GRACE`                 | `--kill-grace`       | a duration like '500ms', '30s' or '5m', at most 24 days                 | 2s                                         | How long a task that ignores SIGTERM gets before SIGKILL.                                                                                           |
-| `run.teardownTimeout`                          | `VX_RUN_TEARDOWN_TIMEOUT`           | `--teardown-timeout` | a duration like '500ms', '30s' or '5m', at most 24 days                 | 3s                                         | The bound on each plugin's end-of-run flush and teardown.                                                                                           |
-| `run.readyNotice`                              | `VX_RUN_READY_NOTICE`               | `--ready-notice`     | a duration like '500ms', '30s' or '5m', at most 24 days                 | 10s                                        | How long a persistent task may take to match `readyWhen` before vx says it waits.                                                                   |
-| `run.rules.exclusiveOutputs`                   | `VX_RUN_RULES_EXCLUSIVE_OUTPUTS`    | —                    | true or false                                                           | true                                       | Refuse two tasks whose outputs overlap even when an edge orders them.                                                                               |
-| `run.rules.upfrontKeys`                        | `VX_RUN_RULES_UPFRONT_KEYS`         | —                    | true or false                                                           | true                                       | Refuse a task whose inputs can match another task's outputs.                                                                                        |
-| `cache.dir`                                    | `VX_CACHE_DIR`                      | `--cache-dir`        | a non-blank string                                                      | .vx/cache, entries in ~/.vx/<repo>/cache   | Where the cache lives, relative to the workspace root; named, it holds the whole cache.                                                             |
-| `cache.retention.maxSize`                      | `VX_CACHE_RETENTION_MAX_SIZE`       | —                    | a size like '500MB' or '10GB'                                           | none                                       | Evict least-recently-used entries at each run's end until the cache is under this (`'10GB'`).                                                       |
-| `cache.retention.olderThan`                    | `VX_CACHE_RETENTION_OLDER_THAN`     | —                    | a duration like '45s', '12h' or '30d'                                   | none                                       | Evict entries unused for this long at each run's end (`'30d'`).                                                                                     |
-| `cache.policy`                                 | `VX_CACHE_POLICY`                   | `--cache-policy`     | a non-blank string                                                      | every layer reads and writes               | Which layers a run reads and writes (`'local:rw,remote:r'`); `--no-cache` and `--force` apply on top.                                               |
-| `cache.scope`                                  | `VX_CACHE_SCOPE`                    | `--cache-scope`      | a non-blank string                                                      | none (the default keys)                    | Where cache writes land (`'pr-123'`): reads try the default key, then the scope's.                                                                  |
-| `cache.download`                               | `VX_CACHE_DOWNLOAD`                 | `--cache-download`   | one of 'all', 'toplevel', 'none'                                        | all                                        | Which remote hits land on disk: every one, only the requested tasks, or none.                                                                       |
-| `cache.inputStability.strategy`                | `VX_CACHE_INPUT_STABILITY_STRATEGY` | —                    | one of 'immutable', 'mutable', 'unchecked'                              | immutable                                  | What a write to an input during the command means for the save, for tasks without their own. A task's own `cache.inputStability.strategy` beats it. |
-| `cache.inputStability.severity`                | `VX_CACHE_INPUT_STABILITY_SEVERITY` | —                    | one of 'warn', 'error'                                                  | warn                                       | Whether a skipped save warns or fails the task, for tasks without their own. A task's own `cache.inputStability.severity` beats it.                 |
-| `cache.outputs.clean`                          | —                                   | —                    | true or false                                                           | true                                       | Remove a task's declared outputs before it runs on a miss, for tasks without their own. A task's own `cache.outputs.clean` beats it.                |
-| `lock.reviewFiles`                             | `VX_LOCK_REVIEW_FILES`              | —                    | true or false                                                           | true                                       | `vx lock` writes each project's resolved config, pretty, to `vx.lock.json` beside its `vx.config`, for review; vx never reads it.                   |
-| `watch.poll`                                   | `VX_WATCH_POLL`                     | `vx watch --poll`    | true or false                                                           | false                                      | Poll for changes from the start instead of the OS watcher.                                                                                          |
-| `config.workerTimeout` (variable or flag only) | `VX_CONFIG_WORKER_TIMEOUT`          | —                    | a duration like '500ms', '30s' or '5m', at most 24 days                 | 30s                                        | How long one config evaluation may take.                                                                                                            |
-| `debug.timing` (variable or flag only)         | `VX_DEBUG_TIMING`                   | —                    | true or false                                                           | false                                      | Print the run's stage timings to stderr.                                                                                                            |
-| `debug.watch` (variable or flag only)          | `VX_DEBUG_WATCH`                    | —                    | true or false                                                           | false                                      | `vx watch`: say on stderr each time the loop arms, with the projects it watches.                                                                    |
-| `debug.dumpable` (variable or flag only)       | `VX_DEBUG_DUMPABLE`                 | —                    | true or false                                                           | false                                      | Linux: keep vx dumpable, so strace or a debugger can read its memory and `/proc/<pid>/fd`, and an unsandboxed task its env.                         |
+| Setting                                        | Variable                            | Flag               | Value                                                                   | Default                                    | What it does                                                                                                                                        |
+| ---------------------------------------------- | ----------------------------------- | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `run.concurrency`                              | `VX_RUN_CONCURRENCY`                | `--concurrency`    | a positive integer, or a share of the cores like '50%'                  | the cores this process may use             | Tasks at once: a positive integer, or a share of the cores (`'50%'`).                                                                               |
+| `run.schedule`                                 | `VX_RUN_SCHEDULE`                   | `--schedule`       | one of 'most-work', 'critical-path', 'direct-dependents', 'ready-order' | most-work                                  | Which ready task starts first when there are more than workers.                                                                                     |
+| `run.affectedBase`                             | `VX_RUN_AFFECTED_BASE`              | —                  | a non-blank string                                                      | origin/HEAD, then the trunk, else HEAD~1   | The git ref a bare `--affected` compares with.                                                                                                      |
+| `run.branch` (variable or flag only)           | `VX_RUN_BRANCH`                     | `--branch`         | a non-blank string                                                      | git's branch, then the CI provider's       | The branch a run records in its history and forecasts from. Flag and env only: a committed branch would be wrong on every other branch.             |
+| `run.timeout`                                  | `VX_RUN_TIMEOUT`                    | `--timeout`        | a duration like '500ms', '30s' or '5m', at most 24 days                 | none                                       | A task's time limit, for tasks without their own `exec.timeout` (`'30m'`). A task's own `exec.timeout` beats it.                                    |
+| `run.retries`                                  | `VX_RUN_RETRIES`                    | `--retries`        | a non-negative integer                                                  | 0                                          | Re-runs of a failed task, for tasks without their own `exec.retries`. A task's own `exec.retries` beats it.                                         |
+| `run.continue`                                 | `VX_RUN_CONTINUE`                   | `--continue`       | one of 'never', 'deps-ok', 'always'                                     | deps-ok                                    | What a failed task takes down: `never` stops the run, `deps-ok` skips its dependents, `always` runs them too.                                       |
+| `run.outputLogs` (variable or flag only)       | `VX_RUN_OUTPUT_LOGS`                | `--output-logs`    | one of 'full', 'errors-only', 'hash-only', 'none'                       | `full` on CI, else by what the run selects | Which task output the run prints. Chosen before the workspace loads, so flag and env only.                                                          |
+| `run.rules.exclusiveOutputs`                   | `VX_RUN_RULES_EXCLUSIVE_OUTPUTS`    | —                  | true or false                                                           | true                                       | Refuse two tasks whose outputs overlap even when an edge orders them.                                                                               |
+| `run.rules.upfrontKeys`                        | `VX_RUN_RULES_UPFRONT_KEYS`         | —                  | true or false                                                           | true                                       | Refuse a task whose inputs can match another task's outputs.                                                                                        |
+| `cache.dir`                                    | `VX_CACHE_DIR`                      | `--cache-dir`      | a non-blank string                                                      | .vx/cache, entries in ~/.vx/<repo>/cache   | Where the cache lives, relative to the workspace root; named, it holds the whole cache.                                                             |
+| `cache.retention.maxSize`                      | `VX_CACHE_RETENTION_MAX_SIZE`       | —                  | a size like '500MB' or '10GB'                                           | none                                       | Evict least-recently-used entries at each run's end until the cache is under this (`'10GB'`).                                                       |
+| `cache.retention.olderThan`                    | `VX_CACHE_RETENTION_OLDER_THAN`     | —                  | a duration like '45s', '12h' or '30d'                                   | none                                       | Evict entries unused for this long at each run's end (`'30d'`).                                                                                     |
+| `cache.policy`                                 | `VX_CACHE_POLICY`                   | `--cache-policy`   | a non-blank string                                                      | every layer reads and writes               | Which layers a run reads and writes (`'local:rw,remote:r'`); `--no-cache` and `--force` apply on top.                                               |
+| `cache.scope`                                  | `VX_CACHE_SCOPE`                    | `--cache-scope`    | a non-blank string                                                      | none (the default keys)                    | Where cache writes land (`'pr-123'`): reads try the default key, then the scope's.                                                                  |
+| `cache.download`                               | `VX_CACHE_DOWNLOAD`                 | `--cache-download` | one of 'all', 'toplevel', 'none'                                        | all                                        | Which remote hits land on disk: every one, only the requested tasks, or none.                                                                       |
+| `cache.inputStability.strategy`                | `VX_CACHE_INPUT_STABILITY_STRATEGY` | —                  | one of 'immutable', 'mutable', 'unchecked'                              | immutable                                  | What a write to an input during the command means for the save, for tasks without their own. A task's own `cache.inputStability.strategy` beats it. |
+| `cache.inputStability.severity`                | `VX_CACHE_INPUT_STABILITY_SEVERITY` | —                  | one of 'warn', 'error'                                                  | warn                                       | Whether a skipped save warns or fails the task, for tasks without their own. A task's own `cache.inputStability.severity` beats it.                 |
+| `cache.outputs.clean`                          | —                                   | —                  | true or false                                                           | true                                       | Remove a task's declared outputs before it runs on a miss, for tasks without their own. A task's own `cache.outputs.clean` beats it.                |
+| `lock.reviewFiles`                             | `VX_LOCK_REVIEW_FILES`              | —                  | true or false                                                           | true                                       | `vx lock` writes each project's resolved config, pretty, to `vx.lock.json` beside its `vx.config`, for review; vx never reads it.                   |
+| `watch.poll`                                   | `VX_WATCH_POLL`                     | `vx watch --poll`  | true or false                                                           | false                                      | Poll for changes from the start instead of the OS watcher.                                                                                          |
+| `config.workerTimeout` (variable or flag only) | `VX_CONFIG_WORKER_TIMEOUT`          | —                  | a duration like '500ms', '30s' or '5m', at most 24 days                 | 30s                                        | How long one config evaluation may take.                                                                                                            |
+| `debug.timing` (variable or flag only)         | `VX_DEBUG_TIMING`                   | —                  | true or false                                                           | false                                      | Print the run's stage timings to stderr.                                                                                                            |
+| `debug.watch` (variable or flag only)          | `VX_DEBUG_WATCH`                    | —                  | true or false                                                           | false                                      | `vx watch`: say on stderr each time the loop arms, with the projects it watches.                                                                    |
+| `debug.dumpable` (variable or flag only)       | `VX_DEBUG_DUMPABLE`                 | —                  | true or false                                                           | false                                      | Linux: keep vx dumpable, so strace or a debugger can read its memory and `/proc/<pid>/fd`, and an unsandboxed task its env.                         |
 
 <!-- /settings table -->
 
@@ -1737,9 +1733,6 @@ interface RunSettings {
   timeout?: Duration
   retries?: number
   continue?: 'never' | 'deps-ok' | 'always'
-  killGrace?: Duration
-  teardownTimeout?: Duration
-  readyNotice?: Duration
   /** Graph rules `vx lock` checks, never a run; each on unless set to false. */
   rules?: { exclusiveOutputs?: boolean; upfrontKeys?: boolean; dependencies?: DependencyRule[] }
 }
@@ -1777,11 +1770,6 @@ interface CacheSettings {
 - **`run.continue`** — what a failed task takes down: `never` stops
   dispatch, `deps-ok` (the default) skips its dependents, `always` runs
   them (`docs/cli.md` § Failure propagation).
-- **`run.killGrace`**, **`run.teardownTimeout`**, **`run.readyNotice`**
-  — the SIGTERM → SIGKILL grace (2 s), the bound on each plugin's
-  end-of-run flush and teardown (3 s; there is no "no limit"), and how
-  long a persistent task may wait for `readyWhen` before vx says what it
-  waits for (10 s).
 - **`run.rules`** — checked by `vx lock` and `vx lock --check` only;
   no run checks them.
 - **`cache.dir`** — unset, the workspace keeps its index and history in
@@ -1907,7 +1895,17 @@ false in .vx/workspace.ts to let it wait for its producer.` Such a key
     the schedule (`caching.md` § Local restore tier). The upstream's key
     already reaches the reader through `dependsOn`. A `!` entry that
     takes the whole output back clears it, and an output the reader's
-    `!` entries take back no longer holds its key back either. A task's
+    `!` entries take back no longer holds its key back either. Nor does
+    an output git ignores whole: a key reads only what git lists, so
+    `**/*` beside a gitignored `**/dist/**` passes and keys up front. Git
+    is asked, never a `.gitignore` read: `git check-ignore` on the
+    output's directory (for `**/dist/**`, `dist/` and a fresh
+    `__vx_probe__/dist/`), and no tracked or listed file may match it,
+    so a tracked output is still refused. A glob no few paths stand for
+    (`*.js`) is refused as before. `vx lock` asks once for every
+    overlapped output; a run asks once beside its git walk for the
+    stability gate, so a rule changed after the lock keys the reader
+    late until the next `vx lock` refuses it. A task's
     own outputs, a task with no `cache`, and a group are exempt. Off,
     the key waits for its producer, as before.
   - **`dependencies`** — which workspace projects a project may depend

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.638",
+  "version": "0.0.639",
   "description": "Task orchestration you own: correct, sandboxed, extensible, with a content-addressed build cache.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.638",
-    "@vzn/vx-linux-arm64": "0.0.638",
-    "@vzn/vx-darwin-x64": "0.0.638",
-    "@vzn/vx-darwin-arm64": "0.0.638"
+    "@vzn/vx-linux-x64": "0.0.639",
+    "@vzn/vx-linux-arm64": "0.0.639",
+    "@vzn/vx-darwin-x64": "0.0.639",
+    "@vzn/vx-darwin-arm64": "0.0.639"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/schemas/last.json

@@ -107,8 +107,7 @@
         "host",
         "os",
         "arch",
-        "vxVersion",
-        "tags"
+        "vxVersion"
       ],
       "properties": {
         "runId": { "type": "string" },
@@ -146,8 +145,7 @@
         "host": { "type": ["string", "null"] },
         "os": { "type": ["string", "null"] },
         "arch": { "type": ["string", "null"] },
-        "vxVersion": { "type": "string" },
-        "tags": { "type": "object", "additionalProperties": { "type": "string" } }
+        "vxVersion": { "type": "string" }
       }
     },
     "task": {
@@ -174,6 +172,7 @@
         "timedOut",
         "sandboxViolations",
         "notReady",
+        "remoteError",
         "forwarded"
       ],
       "properties": {
@@ -209,6 +208,10 @@
         "timedOut": { "type": ["boolean", "null"] },
         "sandboxViolations": { "type": ["integer", "null"] },
         "notReady": { "enum": ["timeout", "exited", "spawn", null] },
+        "remoteError": {
+          "type": ["string", "null"],
+          "description": "each failed remote read or write of the key, `; `-joined"
+        },
         "forwarded": { "type": "boolean" },
         "output": {
           "type": "string",

package/skills/vx/SKILL.md

@@ -15,13 +15,13 @@ dependencies.
 vx run build --all                  # a task in every project that declares it
 vx run test --affected=origin/main  # only what the diff since origin/main reaches
 vx run app#build                    # one project's task (and what it depends on)
-vx run build --all --format json    # the result as JSON on stdout; logs go to stderr
+vx last --format json               # the last run's result as JSON
 ```
 
 The exit code is the verdict: `0` every task passed or hit the cache, `1` a
-task failed or was skipped, or the command was refused. `--format json`
-prints `schemas/summary.json` (`runId`, `ok`, `exitCode`, a row per task).
-A refusal under `--format json` is one line on stdout,
+task failed or was skipped, or the command was refused. `vx last --format
+json` prints the run as JSON afterwards, a row per task. A refusal under
+`--format json` (or `--dry=json`) is one line on stdout,
 `{"ok":false,"error":{"code","message","docs"}}`: branch on `code`;
 `docs` (or `vx docs <code>` offline) says what to do.
 Without a TTY a missing task name never prompts: vx exits 1 and lists the
@@ -108,3 +108,5 @@ vx info --format json   # vx and Bun versions, projects, config errors, plugins,
 `npx skills add vznjs/vx` installs this skill. To match the vx a workspace
 has installed, copy it from there instead:
 `cp node_modules/@vzn/vx/skills/vx/SKILL.md .claude/skills/vx/`.
+`vx upgrade` inside a workspace moves the project's `@vzn/vx` and the
+global vx that ran it to the same version.