@vzn/vx 0.0.636 → 0.0.637

package/docs/schema.md

@@ -1,7 +1,8 @@
 # Config schema
 
 Complete reference for every field accepted by `vx.config.{ts,mts,js,mjs,cts,cjs}`
-and the optional workspace-level `vx.workspace.{ts,mts,js,mjs,cts,cjs}`. The
+and the workspace-level `.vx/workspace.{ts,mts,js,mjs,cts,cjs}`, which is
+required: it marks the workspace root (cli.md § The workspace root). The
 authoritative TypeScript definitions live in `src/config.ts` and are
 re-exported from `@vzn/vx`.
 
@@ -9,18 +10,30 @@ re-exported from `@vzn/vx`.
 
 ```
 <workspaceRoot>/
-├── pnpm-workspace.yaml          (or: package.json with "workspaces", or bare package.json)
-├── vx.workspace.ts              (optional, workspace-wide settings)
-└── packages/
-    └── <pkg>/
-        ├── package.json
-        └── vx.config.ts         (per-package task definitions)
+├── vx.config.ts                 (optional: the root project, named `//`)
+├── .vx/
+│   ├── workspace.ts             (required: marks the root; workspace-wide settings)
+│   ├── projects.lock.json                (`vx lock`, minified; committed)
+│   ├── .gitattributes           (`projects.lock.json linguist-generated=true`; written when missing)
+│   ├── .gitignore               (`/cache`; written by `vx init` and the cache when missing)
+│   └── cache/                   (machine-local state; the only part git ignores)
+└── <any>/<dir>/
+    ├── vx.config.ts             (this directory is a project; its tasks)
+    └── vx.lock.json             (`vx lock`: its resolved config, pretty, for review)
 ```
 
-A project is discovered as a vx project by the **presence of a
-`vx.config.*` file alongside the project's `package.json`.** Projects
-without a config are visible in the workspace graph but contribute no
-tasks.
+**A project is a directory holding a `vx.config.*`**, in any language;
+core reads no `package.json` and no package-manager member list. `vx lock`
+finds them (git's tracked and unignored files; a config at or under a
+nested `.vx/workspace.*` is that workspace's) and records each by
+directory; a run takes its projects from the lock, so a config added since
+runs once `vx lock` records it. A `discover` plugin may add directories
+with no config (`@vzn/vx-lockfile` adds the package manager's members).
+
+A project's name is its config's `name`, else the name a `discover` plugin
+gives (`@vzn/vx-lockfile` gives `package.json#name`), else its
+root-relative path (`apps/web`); the root is `//`. Two projects of one
+name are refused, naming both directories.
 
 ## Project config
 
@@ -28,6 +41,7 @@ tasks.
 import { defineProject } from '@vzn/vx/config'
 
 export default defineProject({
+  name: 'web',
   tags: ['scope:web', 'type:app'],
   tasks: {
     <taskName>: TaskConfig,
@@ -38,6 +52,7 @@ export default defineProject({
 
 ```ts
 interface ProjectConfig {
+  name?: string // what `<name>#<task>`, filters and `dependsOn` address; no "#"
   tags?: readonly string[] // labels for `--filter tag:<name>`
   tasks?: Record<string, TaskConfig> // keyed by task name
 }
@@ -115,7 +130,8 @@ bare `vx run build` does not select it: run where no selected project
 declares `build`, it is refused as any undeclared name is, while
 `lib#build` names it and a dependant's `^build` reaches it. `vx show`
 and `vx info` count it; `vx show build` and the `vx build` hint, which
-name declared tasks, do not.
+name declared tasks, do not. Its `^build` needs an edge source as any
+`^` does: with no plugin returning `deps`, running it is refused.
 
 ### `description` (optional)
 
@@ -195,7 +211,7 @@ Maximum time in milliseconds before vx SIGTERMs the child. Omitted →
 no limit.
 
 ```ts
-build: { exec: { command: 'tsc -b', timeout: 120_000 } }
+build: { exec: { command: 'tsc -b', timeout: '2m' } }
 ```
 
 - For a **normal task**, `timeout` bounds the total run time, counted
@@ -221,15 +237,15 @@ limit" — the platform silently reduces it to **1 ms**, so the task would
 be killed the moment it spawns and reported `failed`. vx refuses it at
 load rather than let that happen. **Omit `timeout` entirely for no
 limit.** The same bound applies to `--timeout` and to the workspace-level
-`timeout`; the `VX_TASK_TIMEOUT` env rung is clamped to it instead of
+`run.timeout`; the `VX_RUN_TIMEOUT` env rung is clamped to it instead of
 refused, since that rung never fails a run.
 
 A task with **no** `exec.timeout` falls back to a run-level default, if
 one is set. Precedence, highest first: **per-task `exec.timeout` →
-`--timeout <ms>` / `RunOptions.timeout` → `VX_TASK_TIMEOUT` env →
-workspace `timeout`** (see workspace config below). Per-task always
+`--timeout <duration>` / `RunOptions.timeout` → `VX_RUN_TIMEOUT` →
+workspace `run.timeout`** (see workspace config below). Per-task always
 wins. The run-level defaults are threaded as run options, so — like
-`--retry` — they never touch a cache key: a `--timeout` run cache-hits a
+`--retries` — they never touch a cache key: a `--timeout` run cache-hits a
 plain run's entry.
 
 **Why no multi-step `commands: string[]`?** Per-task caching is the
@@ -272,7 +288,7 @@ test: { exec: { command: 'bun test', retries: 1 } }
 - Not allowed with `persistent` — a persistent task has no exit to
   retry (config error, like `cache` + `persistent`).
 
-The run-level default is `vx run --retry <n>` — it applies to tasks
+The run-level default is `run.retries` (`vx run --retries <n>`, `VX_RUN_RETRIES`) — it applies to tasks
 that don't declare their own `retries`, never to a persistent one (a
 server that exits before it is ready fails at once); explicit config
 always wins, including an explicit `retries: 0`. The CLI flag never
@@ -360,14 +376,14 @@ 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 (`VX_READY_NOTICE_MS`) is said once, naming
+  not ready after 10 s (`run.readyNotice`) is said once, naming
   the pattern it waits for, and whether `exec.timeout` bounds the wait.
 
 ```ts
 dev: {
   exec: {
     command: 'vite',
-    timeout: 30_000, // bound the readiness wait
+    timeout: '30s', // bound the readiness wait
     persistent: { readyWhen: 'Local:' },
   },
 }
@@ -565,7 +581,7 @@ does: npm-run-all calls that manager back and falls back to a global `npm`
 without it. It names a binary on this machine, so it is not in the key.
 
 Anything outside these three layers, the two variables vx sets for
-the run (`VX_RUN_WORKSPACE`, `VX_RUN_TASK`) and `npm_execpath`, is invisible to the child:
+the run (`VX_RUN_WORKSPACE`, `VX_RUN_TASK`) and `npm_execpath`, is absent from the child's environment:
 a host credential (`SSH_AUTH_SOCK`, `GITHUB_TOKEN`) reaches a task only
 when `passThrough` names it, held end to end by `env.test.ts` (a
 sandboxed task with a restricted network also gets the sandbox's own
@@ -579,6 +595,10 @@ matches Turbo's `passThroughEnv` semantics and exists for two reasons:
   with different `FOO=bar` set would produce different outputs and
   the user would never know why.
 
+This is hygiene, not a boundary: an unsandboxed task runs as you, so it
+can read your files. vx hides its own environment from a task
+(`modules/util-hide-env.md`), not your files. Only `exec.sandbox` keeps them out (`security.md` § What the sandbox stops).
+
 **Masking.** The value of a variable whose name holds `TOKEN`, `SECRET`,
 `KEY`, `PASSWORD`, `PASSWD` or `CREDENTIAL` (vx's own environment or a
 task's `define`, six characters or more; not a name ending `_FILE`,
@@ -588,13 +608,13 @@ shows it: the task's output and the line vx adds under a shell's 127 or
 replays, the command a cache entry stores (what `vx why` prints and a
 remote cache receives), the `$ command` line, telemetry records,
 `vx show`, the hashes `vx why` gives for such a variable in
-`cache.inputs.env` (its value, unsalted: the row names it and its change), an executor's error, a plugin's warning or failure (a remote's reply; the failure masked in the error `run()` rejects with), any error `vx mcp` answers an agent 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
+`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
 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
 probes that mask alike are numbered, `echo *** (2)`), the readiness
-notice's pattern, a sandbox violation line, `vx info`'s config errors,
+notice's pattern, a sandbox violation line,
 the error a verb ends on (a plugin's failure, a config's own throw) and
 `vx watch`'s `cycle failed` line. A multi-line value (a PEM
 key) is also masked line by line, each line of six characters or more,
@@ -622,13 +642,13 @@ Turbo/Nx-style micro-syntax — a flat array of strings:
 dependsOn?: readonly string[]
 ```
 
-| Form         | Meaning                                                            |
-| ------------ | ------------------------------------------------------------------ |
-| `'name'`     | Same-project task `name`.                                          |
-| `'^name'`    | The `name` task in the nearest workspace deps that declare it.     |
-| `'pkg#name'` | The `name` task in a specific other package (cross-project edge).  |
-| `'name.*'`   | Every OTHER same-project task matching the pattern (`*` = any).    |
-| `'^name.*'`  | All matching tasks of the nearest deps that declare any (pattern). |
+| Form         | Meaning                                                                         |
+| ------------ | ------------------------------------------------------------------------------- |
+| `'name'`     | Same-project task `name`.                                                       |
+| `'^name'`    | The `name` task in the nearest project deps (a plugin's edges) that declare it. |
+| `'pkg#name'` | The `name` task in a specific other package (cross-project edge).               |
+| `'name.*'`   | Every OTHER same-project task matching the pattern (`*` = any).                 |
+| `'^name.*'`  | All matching tasks of the nearest deps that declare any (pattern).              |
 
 Examples:
 
@@ -649,14 +669,16 @@ Semantics:
   **type-checked against this config's task keys** — a typo is a
   compile error (`'^name'` / `'pkg#name'` reference other projects
   and stay free strings).
-- **`'^name'`** — nearest-holder frontier. Walk the package dep graph
-  from this project's direct deps (`dependencies`, `devDependencies`,
-  `optionalDependencies`, and a `peerDependencies` entry on a
-  workspace sibling unless that edge would close a cycle — then the
-  consumer provides it and it orders nothing; an entry is a dep when
-  the package manager links it to the workspace package, so a range the
-  local version does not satisfy is a registry dependency, see
-  `modules/package-graph.md` § Which entries are edges); each path stops at the first dep
+- **`'^name'`** — nearest-holder frontier. Walk the project graph
+  from this project's direct deps: the edges a plugin's `discover`
+  returns as `deps` (the lockfile plugins `pnpm()` / `bun()` / `npm()` /
+  `yarn()` return what the package manager installed; core reads no
+  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
+  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
   for anything deeper — chain `'^name'` in the holder to keep the
@@ -667,8 +689,8 @@ Semantics:
   too, as long as SOME project in the workspace declares `name`: a
   preset spreads `'^build'` over packages whose deps have no `build`.
   A `'^name'` that **no project in the whole workspace declares** is a
-  hard error at graph-build time, since it can only be a typo: "Task
-  app#test depends on ^biuld but no project in the workspace declares
+  hard error at graph-build time, since it can only be a typo: "app#test:
+  dependsOn ^biuld but no project in the workspace declares
   biuld". Until 2026-09-24 it resolved to no edges and the run went
   green (Nx#32779 is the same bug). A scoped run (an anchored
   `app#test`, `--filter`, a project directory) loads only its projects
@@ -721,7 +743,12 @@ means. `strategy` says which writes count:
   be told from no edit.
 - `'mutable'`: a file rewritten to the bytes the key folded counts as
   unchanged, for a task that rewrites its own input identically
-  (tsdown's `package.json`); different bytes still count.
+  (tsdown's `package.json`); different bytes still count, and so does
+  any write while another task that may write the file was running (one
+  of the same project, or one whose sandbox grants writes elsewhere in
+  the workspace; a server `vx watch` keeps from an earlier run counts),
+  since it may have changed the file and put it back.
+  The line names that task; order the two with `dependsOn` to save.
 - `'unchecked'`: none. The entry is saved under the key taken before the
   command, whatever the command did to its inputs; `severity` is ignored.
   A key that no longer held before the command started still withholds
@@ -729,19 +756,21 @@ means. `strategy` says which writes count:
 
 A write that counts withholds the entry, and `severity` says what else
 happens: `'warn'` (the default) keeps the result, says why on the status
-line, and the run goes on; `'error'` fails the task, so the run fails.
+line, and the run goes on; `'error'` fails the task, so the run fails,
+and its label names the file: `failed (src/a.ts changed during the run, exit 1)`
+(`inputMoved` in `vx last --format json`).
 Either way, every task that ran over the task's outputs, down the graph,
 withholds its save too, and a task of any project that declares the
 moved file as an input withholds its own.
 
 Each field is resolved on its own, highest first:
 
-1. `VX_INPUT_STABILITY` (`immutable`, `mutable`, `unchecked`) and
-   `VX_INPUT_STABILITY_SEVERITY` (`warn`, `error`), for the whole run
+1. `VX_CACHE_INPUT_STABILITY_STRATEGY` (`immutable`, `mutable`,
+   `unchecked`) and `VX_CACHE_INPUT_STABILITY_SEVERITY` (`warn`, `error`), for the whole run
    (a CI job that wants `error` sets it without editing configs); any
    other value is refused before a task runs;
 2. the task's own `cache.inputStability`;
-3. the workspace's `inputStability` (`vx.workspace.ts`);
+3. the workspace's `inputStability` (`.vx/workspace.ts`);
 4. the default, `'immutable'` and `'warn'`.
 
 Never folded into a cache key.
@@ -845,15 +874,15 @@ files: ['app/[id]/**'] // a bracket is literal: the route dir `[id]`
 ```
 
 Empty array is valid — the cache key still incorporates command, env,
-upstream hashes, workspace fingerprint, and the project's
-package.json. A task with no _file_ inputs (e.g. a pure
-"download-and-verify") still cache-misses on a lockfile change.
+upstream hashes and any plugin's key material. A task with no _file_
+inputs (e.g. a pure "download-and-verify") still cache-misses on a
+lockfile change when a lockfile plugin (`@vzn/vx-lockfile`) is declared.
 
 Always applied to every glob pass (regardless of what you wrote):
 
 - **gitignore filter** — workspace-root + project `.gitignore`.
-- **Always-ignored** — `.git/**`, `.vx/**`, `*.tsbuildinfo`,
-  `vx-lock.json`, `*.bun-build`, and Bun's cross-compile extraction
+- **Always-ignored** — `.git/**`, `.vx/cache/**`, `*.tsbuildinfo`,
+  `.vx/projects.lock.json`, `vx.lock.json`, `*.bun-build`, and Bun's cross-compile extraction
   directory `.<16 hex>-<8 hex>.tmp/**`, and vx's own restore temp
   `.vx-tmp-*`, at any depth.
 - **Installs** — an untracked file under any `node_modules/` (ignored or
@@ -907,8 +936,8 @@ backslash separator (`src\**`, `src\*.ts`) or a drive (`C:\src\**`,
 `C:/src/**`). A backslash before a bracket, a brace, a `!` or a
 backslash stays an escape.
 
-Still applied: the always-ignored set (`.git/**`, `.vx/**`,
-`*.tsbuildinfo`, `vx-lock.json`, `*.bun-build`, `.<16 hex>-<8 hex>.tmp/**`, `.vx-tmp-*`),
+Still applied: the always-ignored set (`.git/**`, `.vx/cache/**`,
+`*.tsbuildinfo`, `.vx/projects.lock.json`, `vx.lock.json`, `*.bun-build`, `.<16 hex>-<8 hex>.tmp/**`, `.vx-tmp-*`),
 untracked files under `node_modules/`, and the task's own declared
 outputs, `outputs.workspaceFiles` and the `outputs.files` its globs reach
 in its own project (a task never invalidates itself).
@@ -985,8 +1014,8 @@ Semantics:
   `resolveInputs`), exactly like `inputs.env` reads host env values
   live. `vx lock` freezes the command _strings_ (they're in the
   resolved config), not their output, so the field stays correct under
-  `vx run --frozen` — the changed output of a frozen command still
-  busts the cache.
+  the lock every run reads — the changed output of a locked command
+  still busts the cache.
 - A **non-zero exit fails the run** (a hard `UserError` naming the
   command and exit code) — fail-loud, like a missing git binary. A
   flaky probe should not silently degrade to a stale hit.
@@ -1110,6 +1139,7 @@ task's outputs. Typical case: an integration-test task `dependsOn`s
 interface CacheOutputs {
   files: readonly string[] // required
   workspaceFiles?: readonly string[] // optional; workspace-root-relative
+  clean?: boolean // optional; false keeps outputs on a miss
 }
 ```
 
@@ -1143,7 +1173,7 @@ it (never following it). An output DIRECTORY that is a symlink
 (`dist -> real-out`) is followed: its target is cleaned, saved and
 restored as the output; one that resolves outside the project refuses
 the task, naming the link. A link to a directory, a dangling one, or
-one whose target is outside the project cannot be stored — the save refuses it by name and caches nothing, so
+one whose target is outside the project or, for a sandboxed task, a file its grants do not let it read cannot be stored — the save refuses it by name and caches nothing, so
 the next run executes again. A link to another output of the same task
 is stored wherever it is: `gen/latest -> v2.txt` under a
 `workspaceFiles` output caches (A-53). The clean also prunes the directories it
@@ -1154,13 +1184,21 @@ Empty `[]` is valid for tasks that produce no files (e.g. `lint`,
 `typecheck`, `test`); you still cache the no-op success so the next
 run is a no-op too.
 
+**`clean: false`** keeps the outputs on a miss instead of wiping them
+first, for a tool that reads its own last output (tsc's
+`.tsbuildinfo`). An entry still holds only what a clean run would
+leave: if the run leaves any old file unchanged, nothing is cached, and
+the next run executes again. A retry still starts clean, and a hit
+still restores bit-identically. Omitted → the workspace's
+`cache.outputs.clean`, else `true`.
+
 A **`!` entry takes a path back** from what the positive globs select
-(A-44; a tracked fixture and a scratch dir under `dist` stay out of
-the clean this way):
+(A-44; a scratch dir under `dist` stays out of the clean this way; a
+tracked file needs no `!`, below):
 
 ```ts
 outputs: {
-  files: ['dist/**', '!dist/fixture.html', '!**/*.tmp']
+  files: ['dist/**', '!**/*.tmp']
 }
 ```
 
@@ -1181,10 +1219,12 @@ positive globs, so a task with a `!` entry keeps it (A-46).
 - Before restore on a cache hit: same wipe, then files are copied
   from the cache entry into the project dir. The post-restore tree
   is the cached snapshot, byte-for-byte.
+- A file git tracks is never wiped (2026-10-14). It is still saved and
+  restored, and stays in the task's key, so an edit to it moves the key.
 
 Skipped when `cache.outputs.files` is empty (nothing declared as
 output) and when no cache-write axis is enabled (e.g. `--no-cache`,
-or a read-only `--cache=local:r`) — the user is debugging and
+or a read-only `--cache-policy=local:r`) — the user is debugging and
 managing the tree themselves. `--force` keeps writes on, so it does
 clean.
 
@@ -1225,7 +1265,7 @@ restore wins. A workspace output is also compared with every other
 project's `files` outputs, read from the root: `packages/b/dist/a.txt`
 collides with `b`'s `dist/**` (item 1088). An overlap
 between two tasks one of which depends on the other is refused too,
-unless the workspace sets `rules: { exclusiveOutputs: false }` (X-53);
+unless the workspace sets `run.rules.exclusiveOutputs: false` (X-53);
 then the dependant is additive and owns only what its run adds to the
 tree (`caching.md` § Additive outputs, item 588). Across the two namespaces
 an upstream `files` task is told the dependant's globs in its own
@@ -1348,7 +1388,7 @@ vx removes the empty file it made (it takes back any placeholder the
 task never wrote, so an unwritten one is never archived as an output).
 A grant that leaves the project through a symlink is refused: the grant
 binds the path it names, and vx follows no link out of the project. So
-is one whose bind would make `.git`, `.vx`, the cache directory or a
+is one whose bind would make `.git`, `.vx/cache`, the cache directory or a
 nested project writable:
 a file grant at a single-package workspace's root binds the root. A
 directory grant is judged as the directory, made before the judgement
@@ -1414,7 +1454,16 @@ shares (L-41): `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.azure`, `~/.kube`,
 `~/.bunfig.toml`, `~/.config/.bunfig.toml`, `~/.cargo/credentials`,
 `~/.cargo/credentials.toml`, `~/.gem/credentials`, `~/.config/hub`,
 `~/.config/containers/auth.json`, `~/.terraform.d/credentials.tfrc.json`,
-`~/.vault-token`, `~/.pgpass`.
+`~/.vault-token`, `~/.pgpass`, `~/.config/configstore/firebase-tools.json`,
+`~/.local/share/com.vercel.cli/auth.json`,
+`~/Library/Application Support/com.vercel.cli/auth.json`,
+`~/.netlify/config.json`, `~/.config/netlify/config.json`,
+`~/Library/Preferences/netlify/config.json`, `~/.wrangler/config`,
+`~/.config/.wrangler/config`, `~/Library/Preferences/.wrangler/config`,
+`~/.fly/config.yml`, `~/.supabase/access-token`, `~/.config/doctl`,
+`~/Library/Application Support/doctl`, `~/.config/stripe/config.toml`,
+`~/.config/op`, `~/.expo/state.json`, `~/.claude/.credentials.json`,
+`~/.codex/auth.json`.
 What it grants from there is the union of the read grants and, on Linux,
 the DIRECTORY holding each file-shaped write grant (above).
 Nothing is inherited from `cache` — `cache.inputs` says what INVALIDATES a task, `sandbox.allow`
@@ -1574,128 +1623,245 @@ The loader rejects:
 - A task with no `exec`, no `dependsOn` and no `cache` (literal no-op).
 - A group whose `cache.outputs` names a file (a group writes nothing).
 
-## Workspace config (`vx.workspace.ts`)
+## Workspace config (`.vx/workspace.ts`)
 
-Loaded from `vx.workspace.{ts,mts,js,mjs,cts,cjs}` at the workspace root.
-**Optional** — when missing, every field falls back to its built-in
-default.
+Loaded from `.vx/workspace.{ts,mts,js,mjs,cts,cjs}`: the directory holding
+`.vx` is the workspace root. `.vx` also holds the lock (`.vx/projects.lock.json`)
+and `.vx/cache`, the machine-local state (the cache, the workspace id),
+which is the only part git ignores: `.vx/.gitignore` says `/cache`. Every field falls back to its
+built-in default.
 
 ```ts
 import { defineWorkspace } from '@vzn/vx/config'
 import { otel } from '@vzn/vx-otel'
 
 export default defineWorkspace({
-  concurrency: 8,
-  cacheDir: 'build/.vx-cache',
-  timeout: 600_000,
-  cacheRetention: { olderThan: '30d', maxSize: '10G' },
-  affectedBase: 'origin/main',
-  cacheScope: 'trusted',
-  rules: { exclusiveOutputs: true, upfrontKeys: true },
-  schedule: 'most-work',
-  inputStability: { strategy: 'immutable', severity: 'warn' },
+  run: {
+    concurrency: 8,
+    timeout: '10m',
+    affectedBase: 'origin/main',
+    schedule: 'most-work',
+    continue: 'deps-ok',
+    killGrace: '2s',
+    teardownTimeout: '3s',
+    readyNotice: '10s',
+    rules: {
+      exclusiveOutputs: true,
+      upfrontKeys: true,
+      dependencies: [{ from: 'tag:lib', deny: ['tag:app'] }],
+    },
+  },
+  cache: {
+    dir: 'build/.vx-cache',
+    download: 'all',
+    retention: { olderThan: '30d', maxSize: '10GB' },
+    policy: 'local:rw,remote:r',
+    scope: 'main',
+    inputStability: { strategy: 'immutable', severity: 'warn' },
+    outputs: { clean: true },
+  },
+  lock: { reviewFiles: true },
+  watch: { poll: false },
   plugins: [otel()],
 })
 ```
 
+The workspace holds settings in groups (`run`, `cache`, `lock`, `watch`) and the
+`plugins`. Every setting has one path, and its environment variable and
+flag derive from it: `run.timeout` is `VX_RUN_TIMEOUT` and
+`vx run --timeout`. A flag beats its variable, which beats this file,
+which beats the built-in. A setting a task can set itself
+(`exec.timeout`, `exec.retries`, `cache.inputStability`) takes the
+task's value over all of them; the input-stability variables are the one
+exception, overriding every task for the run. A duration carries its
+unit (`'500ms'`, `'30s'`, `'10m'`, `'2h'`, `'30d'`), and a bare number is
+refused naming the forms with units; a size carries one too (`'10GB'`).
+`debug.timing`, `debug.dumpable`, `config.workerTimeout` and `run.outputLogs` are read
+before the workspace loads, so they have a variable (and a flag) only.
+None is folded into a cache key. `vx info` lists every setting not at its
+default and where it came from.
+
+### Settings
+
+<!-- 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`                          | `VX_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.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 -->
+
 ```ts
 interface WorkspaceConfig {
-  /** Maximum concurrent tasks. Defaults to the cores this process may use (the CPU count, capped by a cgroup quota). */
-  concurrency?: number
-  /** Cache directory, relative to workspace root. Named, it holds the whole cache; unset, entries live in the user's shared store. */
-  cacheDir?: string
-  /** Default per-task timeout (ms) for tasks without their own exec.timeout. */
-  timeout?: number
-  /** Evict from the local cache at the end of each run (the `vx cache prune` policy). */
-  cacheRetention?: { olderThan?: string; maxSize?: string }
-  /** The git ref a bare `--affected` compares with. */
-  affectedBase?: string
-  /** Where remote writes land: 'trusted' (default), 'read-only', or an untrusted scope name. */
-  cacheScope?: string
-  /** Graph rules checked before anything runs; each on unless set to false. */
-  rules?: WorkspaceRules
-  /** Which ready task starts first with no timings: 'most-work' (default), 'critical-path', 'direct-dependents', 'ready-order'. */
-  schedule?: 'most-work' | 'critical-path' | 'direct-dependents' | 'ready-order'
-  /** Every task's cache.inputStability default: { strategy, severity }. */
-  inputStability?: InputStability
+  run?: RunSettings
+  cache?: CacheSettings
+  lock?: LockSettings
+  watch?: { poll?: boolean }
   /** Run-level plugins (cache / executor / telemetry capabilities). */
   plugins?: readonly (Plugin | undefined | null | false)[]
 }
 
-interface WorkspaceRules {
-  /** Refuse overlapping outputs even across a dependsOn edge. Default true. */
-  exclusiveOutputs?: boolean
-  /** Refuse a task whose inputs can match another task's outputs. Default true. */
-  upfrontKeys?: boolean
+interface RunSettings {
+  concurrency?: number | `${number}%`
+  schedule?: 'most-work' | 'critical-path' | 'direct-dependents' | 'ready-order'
+  affectedBase?: string
+  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[] }
+}
+
+/** `run.rules.dependencies`, checked by `vx lock` only. */
+type DependencyRule = { from: string; allow?: string[]; deny?: string[] }
+
+interface LockSettings {
+  /** A pretty vx.lock.json beside each config, for review; on unless false. */
+  reviewFiles?: boolean
+}
+
+interface CacheSettings {
+  dir?: string
+  retention?: { olderThan?: Duration; maxSize?: string }
+  policy?: string
+  scope?: string
+  download?: 'all' | 'toplevel' | 'none'
+  inputStability?: InputStability
+  outputs?: { clean?: boolean }
 }
 ```
 
-- **`concurrency`** — used as the default cap on parallel tasks; the
-  CLI `--concurrency <n>` still wins when passed.
-- **`timeout`** — the lowest-precedence default per-task timeout (ms),
-  applied to any task that declares no `exec.timeout`. Precedence,
-  highest first: per-task `exec.timeout` → `--timeout` /
-  `RunOptions.timeout` → `VX_TASK_TIMEOUT` env → this. A runaway task's
-  process group is SIGTERMed and the task reported `failed`. Purely a safety net — never folded
-  into a cache key (a timed-out task fails and is never cached).
-- **`cacheDir`** — unset, the workspace keeps its index and history in
+- **`run.concurrency`** — the cap on parallel tasks: a positive integer,
+  or a share of the cores this process may use (`'50%'` on eight cores is
+  4, never below 1; over 100% is allowed for I/O-bound work).
+- **`run.timeout`** — a task's time limit, for any task that declares no
+  `exec.timeout` (which beats it, its flag and its variable). A runaway
+  task's process group is SIGTERMed and the task reported `failed`.
+  Purely a safety net — never folded into a cache key (a timed-out task
+  fails and is never cached).
+- **`run.retries`** — re-runs of a failed task, for tasks without their
+  own `exec.retries` (which beats it, `retries: 0` included); never a
+  persistent one.
+- **`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
   `.vx/cache` and its entries and artifacts in its repository's shared
   store (`~/.vx/<id>/cache`), where every other checkout of the
   repository hits them (`docs/caching.md`). Named here, by
   `VX_CACHE_DIR`, or by `--cache-dir`, the directory holds the whole
-  cache, shared with no other workspace.
+  cache, shared with no other workspace. `--cache-dir` beats
+  `VX_CACHE_DIR`, which beats this.
   Relative paths are resolved against the workspace
   root, `~/` against the home directory; absolute paths are used
-  as-is. The home directory itself (`~`) is refused. `vx run`, `vx cache prune`,
+  as-is. The home directory itself (`~`) is refused. `vx run`, `vx cache clean`,
   and any other reader use the same resolution
   (`src/workspace/workspace.ts:resolveCacheDir`). The cache is a
   directory of its own: a first index in one that holds a
-  `package.json` or `pnpm-workspace.yaml` (`''` and `'.'` name the
+  `package.json`, `pnpm-workspace.yaml`, a `vx.config.*` or a
+  `.vx/workspace.*` (`''` and `'.'` name the
   root), whose subdirectory does (`'packages'`), or that holds the
   workspace (`'..'`, `'/'`) is refused before anything is written, since its `*`
-  `.gitignore` would hide the sources from git and the cache keys.
-- **`cacheRetention`** — the `vx cache prune` policy, applied at the
+  `.gitignore` would hide the sources from git and the cache keys. A
+  directory other than the default `.vx/cache` gets that `*` `.gitignore`;
+  the default is ignored by `.vx/.gitignore` (`/cache`) instead, written
+  when missing and never edited.
+- **`cache.retention`** — the `vx cache clean` policy, applied at the
   end of every run: entries unused for
   `olderThan` (`30d`, `12h`, `90m`, `45s`) go first, then the
-  least-recently-used until the cache is under `maxSize` (`10G`,
+  least-recently-used until the cache is under `maxSize` (`10GB`,
   `500MB`, `64KB`; a bare number is refused as a typo, `10B` is not).
-  Either or both, and neither may be zero: each would evict what every
+  Either or both (each also from `VX_CACHE_RETENTION_OLDER_THAN` /
+  `VX_CACHE_RETENTION_MAX_SIZE`), and neither may be zero: each would evict what every
   run just saved (item 969). It runs after the run's saves
   and uploads have landed, never on a run a signal or an abort stopped
   (one stopped while it waited on the workspace lock never held it), only when something is due (a run with
   nothing to evict pays one scan of the index), and says nothing:
   housekeeping prints no line (owner, 2026-10-06). Under `olderThan` an entry the run just used is never due, but `maxSize` is least-recently-used first, so a bound below one run's outputs evicts that run's own. The prune's
   orphan sweep (artifacts no index row counts, judged by file time —
-  see `vx cache prune`) also runs on its own clock, at most once an
+  see `vx cache clean`) also runs on its own clock, at most once an
   hour, so their bytes go even when nothing the index holds is due;
   listing the directory every run would cost 0.5 ms per 1,000
   entries. Housekeeping,
   not the run's work: a failure is silent, never a failed run. Not
   folded into any cache key. Omitted → the cache grows until
-  `vx cache prune`.
-- **`affectedBase`** — the git ref a bare `--affected` compares with
+  `vx cache clean`.
+- **`run.affectedBase`** — the git ref a bare `--affected` compares with
   (`origin/develop`); `--affected=<base>` still wins. Omitted →
   `origin/HEAD`, then the first of `origin/main`, `origin/master`, `main`, `master` that is not HEAD (D-93), else `HEAD~1`. A plugin's `config` stage may set it:
   `nx()` from `NX_BASE` or nx.json's `defaultBase`, `turbo()` from
   `TURBO_SCM_BASE`, else on GitHub Actions from `GITHUB_BASE_REF` or the
   push event's `before`, as Turbo does. Not folded into any cache key.
-- **`cacheScope`** — where this run's remote cache writes land.
-  `'trusted'` reads and writes the task keys: the default branch's CI.
-  `'read-only'` reads them and writes nothing: a laptop. Omitted, `vx
-run` takes `'read-only'` off CI (`CI` unset, `0` or `false`) and
-  `'trusted'` on CI or when `--cache` names the remote; `run()` takes
-  `RunOptions.defaultCacheScope`, else `'trusted'`.
-  Any other name (`'pr-123'`; letters, digits, `. _ - / @`, at most 128) is an untrusted scope: a remote read tries the scope's key, then
-  the trusted one, and a write goes to the scope's only, so a pull request
-  never writes what the default branch reads, and two scopes never see
-  each other. A scope's key is derived from the task key, so every
-  remote wire stores it unchanged. A clamp on `--cache`, never a
-  widening. `github()` sets it on Actions: `pr-<n>`, `ref-<name>` off
+- **`cache.policy`** — which layers a run reads and writes, in
+  `--cache-policy`'s spec (`'local:rw,remote:r'`; a layer the spec leaves out
+  stays on; the grammar is in `docs/cli.md` § Cache policy). Omitted,
+  every layer reads and writes on CI, and `vx run` off CI (`CI` unset,
+  `0` or `false`) reads the remote and does not write it: a key holds
+  only declared inputs, so a laptop's write could replay on CI. The
+  policy alone decides whether a layer is written; `cache.scope` never
+  does. `VX_CACHE_POLICY` beats it and
+  `vx run --cache-policy` (or `--cache-policy`) beats both; `--no-cache` and `--force` still apply on top. A spec
+  naming the remote (`remote:rw`) asks to write it, off CI too. Parsed
+  before any task: a bad spec is refused naming `cache.policy`. Whatever
+  the policy, a lookup asks the local cache first, then each remote in
+  the order the plugins declare them. Not folded into any cache key.
+- **`cache.download`** — which remote hits land on this machine:
+  `all` (the default), only the requested tasks' (`toplevel`), or
+  `none` (`docs/cli.md` § `--cache-download`).
+- **`cache.scope`** — where this run's cache writes land (2026-10-14).
+  Omitted, a run reads and writes the default keys. A name (`'pr-123'`;
+  letters, digits, `. _ - / @`, at most 128) reads the default key first,
+  then the scope's, and writes only the scope's, so a pull request never
+  writes what the default branch reads, and two scopes never see each
+  other. A default artifact the ingest refuses falls through to the
+  scope's key. A scope's key is derived from the task key, so every
+  remote wire stores it unchanged. The rule holds for the local cache
+  as for every remote, so on one disk an entry a scope saved is a miss
+  for another scope or none, and an unscoped one serves every run. The scope never decides whether a run writes; `cache.policy`
+  does.
+  `github()` sets it on Actions: `pr-<n>`, `ref-<name>` off
   the default branch. `VX_CACHE_SCOPE` beats both, and `vx run --cache-scope` beats all three. A client-side convention, not a security
   boundary: a run holding a write credential can write any key, so only
   a cache server that scopes writes by token can refuse one
   (`docs/security.md` § Cache poisoning). Not folded into any cache key.
-- **`schedule`** — which ready task starts first when more are ready
+  The old top-level `cacheScope` is refused, naming `cache: { scope }`.
+- **`run.schedule`** — which ready task starts first when more are ready
   than workers, with no timings. `most-work` (the default): the one the
   most tasks wait on, at any depth. `critical-path`: the head of the
   longest chain of tasks below it. `direct-dependents`: the one the most
@@ -1706,19 +1872,20 @@ run` takes `'read-only'` off CI (`CI` unset, `0` or `false`) and
   their ties. The default costs what it did; another strategy is
   computed only when named. Any other value is refused. Never folded
   into a cache key.
-- **`inputStability`** — the `cache.inputStability` of every task that
+- **`cache.inputStability`** — the `cache.inputStability` of every task that
   does not set its own field, same shape (`{ strategy, severity }`, §
-  `cache`). The env vars still override it for the run. Never folded
+  `cache`). `VX_CACHE_INPUT_STABILITY_STRATEGY` and `_SEVERITY` still
+  override every task for the run. Never folded
   into a cache key.
-- **`rules`** — checks on the task graph, each on unless set to
+- **`run.rules`** — checks on the task graph, each on unless set to
   `false`. Turning one off allows a shape vx runs correctly but more
   slowly; never folded into a cache key. A value that is not a boolean,
   or a rule vx does not know, is refused.
   - **`exclusiveOutputs`** (X-53) — two tasks whose declared outputs
     overlap are refused even when a `dependsOn` edge orders them:
     `<a> and <b> both declare the output "<glob>" … Give each task its
-own output path, or set rules: { exclusiveOutputs: false } in
-vx.workspace.ts to let a dependant add to its upstream's outputs.`
+own output path, or set run.rules.exclusiveOutputs: false in
+.vx/workspace.ts to let a dependant add to its upstream's outputs.`
     Off, the dependant adds to its upstream's tree (item 588;
     `caching.md` § Additive outputs). Two overlapping tasks with no
     edge are refused either way.
@@ -1730,8 +1897,8 @@ vx.workspace.ts to let a dependant add to its upstream's outputs.`
     landing in its project (X-135), is refused,
     edge or no edge: `<reader> reads "<glob>" in cache.inputs.<field>,
 which matches <writer>'s output "<glob>" … Exclude it: add "!<glob>"
-to <reader>'s cache.inputs.<field>, or set rules: { upfrontKeys:
-false } in vx.workspace.ts to let it wait for its producer.` Such a key
+to <reader>'s cache.inputs.<field>, or set run.rules.upfrontKeys:
+false in .vx/workspace.ts to let it wait for its producer.` Such a key
     reads what the producer writes this run, so vx cannot know it before
     the producer ran: it is not probed, prefetched or restored ahead of
     the schedule (`caching.md` § Local restore tier). The upstream's key
@@ -1740,17 +1907,33 @@ false } in vx.workspace.ts to let it wait for its producer.` Such a key
     `!` entries take back no longer holds its key back either. A task's
     own outputs, a task with no `cache`, and a group are exempt. Off,
     the key waits for its producer, as before.
+  - **`dependencies`** — which workspace projects a project may depend
+    on, checked by `vx lock` and `vx lock --check` only, over each
+    project's direct dependencies (its `package.json` buckets and its
+    tasks' cross-project `dependsOn`). Each rule is
+    `{ from, allow?, deny? }`; a selector is `tag:<tag>` (a project
+    carrying the tag) or a project name, and `*` matches any characters
+    in either (`tag:scope:*`, `@acme/*`). Every rule whose `from`
+    selects a project applies: each dependency must match an `allow`
+    selector when `allow` is given, and none of `deny`, so a deny beats
+    any allow. A project no rule selects is free, and an untagged
+    dependency matches no `tag:` selector. A broken edge refuses the lock
+    with `VX_E_DEPENDENCY_RULE`:
+    `lib depends on app, which run.rules.dependencies[0] (from 'tag:lib') denies`,
+    every broken edge on its own line. A rule with neither `allow` nor
+    `deny` is refused.
 - **`plugins`** — the run-level extension points. Optional: core
   applies no plugin by default, and the local executor and the local
-  cache are its floor — the tail of every executor list and cache chain
-  — so a workspace that declares none runs and caches here.
+  cache are its floor — the tail of every executor list, and the first
+  layer of every cache chain — so a workspace that declares none runs
+  and caches here.
   Declaration order is precedence: every `executor` is consulted in
   order per task (first to accept runs it; what all decline runs
   locally); every `cache` layer is chained (lookup walks, save reaches
   all, the local store last). An `undefined`, `null` or `false` entry
   is skipped, as Vite skips one: a factory that declines (`github()` off
   Actions) or `cond && plugin()` needs no filter. Each entry is a `VxPlugin` contributing
-  any subset of the fourteen hooks, in pipeline order: `config` (edit
+  any subset of the fifteen hooks, in pipeline order: `config` (edit
   the workspace config before anything derives from it), `discover`
   (name directories to make projects beyond the members), `project`
   (edit a loaded project's tasks — inject, remove, rewrite;
@@ -1764,19 +1947,20 @@ false } in vx.workspace.ts to let it wait for its producer.` Such a key
   ready task start now beside what runs here), `executor` (return a
   `TaskExecutor` — where one task's command runs — or decline), `cache`
   (return a cache layer or decline), `telemetry` (observe-only export:
-  OTel, the GitHub job summary, a custom sink), `setup` and `teardown`
+  OTel, the GitHub job summary, a custom sink), `output` (return a
+  `Logger` that draws the run in place of vx's own, or decline), `setup`
+  and `teardown`
   around the run, and CLI `commands` (`{ verb: { description, run } }`,
   consulted for a verb core does not know). First-party plugins:
   `@vzn/vx-otel`, `@vzn/vx-ci`, `@vzn/vx-reapi`, `@vzn/vx-lockfile`,
-  `@vzn/vx-schedule-history`, `@vzn/vx-mcp`, `@vzn/vx-migrate`. A
+  `@vzn/vx-schedule-history`, `@vzn/vx-migrate`. A
   plugin that declines every capability (`otel()` with no OTLP endpoint
   configured) costs nothing — a run with no active plugin is
   byte-identical to one with none declared. Plugins observe, route and
   execute; they never change what a task is.
 
-The loader validates the shape (positive integer for `concurrency`,
-string for `cacheDir`, plugin objects with a name and at least one
-capability) and throws a `UserError` on
+The loader validates the shape (each setting by its kind, plugin objects
+with a name and at least one capability) and throws a `UserError` on
 malformed input.
 
 There are no workspace-level `globalInputs` / task-default fields:
@@ -1874,7 +2058,7 @@ export default defineProject({
       description: 'vite dev server',
       exec: {
         command: 'vite',
-        timeout: 30_000,
+        timeout: '30s',
         persistent: { readyWhen: 'Local:' },
         env: { passThrough: ['VITE_API_URL'] },
       },
@@ -2097,7 +2281,6 @@ a user meets most:
 | `tasks must be an object keyed by task name`                                                                                          | `tasks` is not an object — an ARRAY included.                                                                                                                                                                                  |
 | `<path> is <what> — a config must be JSON data, because the cache key folds its JSON`                                                 | A value JSON cannot carry, anywhere in the config: a function, a symbol, a bigint, `NaN` / `±Infinity`, `undefined` in an array, a cycle, a getter or an object that is not plain (`Date`, `Map`, `RegExp`, a class instance). |
 | `<level> has unknown field "<key>"`                                                                                                   | Typo'd / unsupported key (see below).                                                                                                                                                                                          |
-| `<level> has field "<key>", which vx <version> removed — use <replacement>`                                                           | A field an earlier release accepted (`exec.resources`, removed in 0.0.19). The message names what replaced it (`design/versioning-1.0.md` § Deprecation).                                                                      |
 | `<level> must be an object (fields: <fields>), not an array`                                                                          | An array where an object goes — `outputs: ['dist/**']` (Turbo's spelling) is `outputs: { files: ['dist/**'] }`, and the message says so.                                                                                       |
 | `cannot find '<name>' — no node_modules above the config provides it; install the workspace's dependencies first`                     | A bare import nothing installed serves — a fresh clone before its install, or a typo. Refused before the config is evaluated, so Bun never auto-installs it from the registry (it would, when no `node_modules` exists above). |
 | `cannot find '<name>' — Yarn Plug'n'Play installed the workspace's dependencies into .pnp.cjs, which Bun does not read; set <remedy>` | The same, with a `.pnp.cjs` at or above the config: the install is there and Bun cannot read it, so the remedy is `nodeLinker: node-modules` in `.yarnrc.yml` and `yarn install` (D-109).                                      |
@@ -2132,10 +2315,10 @@ a user meets most:
 | `cache.inputs.files: every entry is a negation, which selects NOTHING`                                                                | Only `!` globs — nothing to subtract from.                                                                                                                                                                                     |
 | `cache.inputs.files: "<file>" is taken back by "!<glob>"`                                                                             | A literal input a `!` entry covers: the negation subtracts wherever it sits, so the file never entered the key.                                                                                                                |
 | `cache.outputs.files: every entry is a negation, which selects NOTHING`                                                               | Only `!` globs: a `!` entry only takes back what a positive glob selected (A-44).                                                                                                                                              |
-| `cache.outputs.files: "<glob>" covers the project's own <file>`                                                                       | An output glob that matches the project's `package.json` or its own `vx.config.*` (`**`, `*.json`): the clean before a run would delete them. A `!` entry that takes the file back (`!package.json`) lets it load.             |
+| `cache.outputs.files: "<glob>" covers the project's own <file>`                                                                       | An output glob that matches the project's own `vx.config.*` (`**`, `*.ts`): the clean before a run would delete it. A `!` entry that takes the file back (`!vx.config.ts`) lets it load.                                       |
 | `cache.outputs.files: "<glob>" is under workspace-outputs/`                                                                           | A project output named into the artifact's namespace for `outputs.workspaceFiles`: every hit read it back as a workspace output.                                                                                               |
 | `cache.inputs.files: '!!' is not a double negation`                                                                                   | `!!x` inverts the set — it folds only `x`.                                                                                                                                                                                     |
-| `exec.timeout: <n> ms exceeds the maximum timer delay`                                                                                | Past 2^31-1 ms a timer fires at once, not never.                                                                                                                                                                               |
+| `exec.timeout of <value> exceeds the maximum timer delay`                                                                             | Past 2^31-1 ms a timer fires at once, not never.                                                                                                                                                                               |
 | `description must be a string`                                                                                                        | Non-string description.                                                                                                                                                                                                        |
 | `tag "<tag>" <why> — --filter tag:<name> could not name it`                                                                           | A tag with surrounding whitespace or a `*`, or one ending in `...` or `[<ref>]`, which a filter reads as a pattern, a dependency walk or a git range.                                                                          |
 
@@ -2144,7 +2327,7 @@ the project's top level (`tasks`), the task itself, `exec`, `exec.env`,
 `exec.persistent`, `exec.sandbox` and its `allow` /
 `deny` / `ignore` blocks, `cache`, `cache.inputs`, and `cache.outputs`
 (`tests/schema-unknown-keys.test.ts` walks every one) — and at the top
-of `vx.workspace.ts`,
+of `.vx/workspace.ts`,
 where `plugin:` (singular) would otherwise declare no plugins and run
 the workspace bare. A silently-dropped
 `workspaceFile` (singular) or `timeoutMs` would make the task hash as
@@ -2168,54 +2351,49 @@ ends `— vx spells it cache.outputs.files` in code quotes. A `cache` that
 is no object (Turbo's `cache: false`) and a `persistent` that is none
 (`true`) name the shape to write.
 
-Workspace-discovery errors (`src/workspace/workspace.ts`):
-
-| Symptom                                                                                                      | Cause                                                                                                                                                                                                                                                      |
-| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `failed to parse <file>: <why>`                                                                              | A `package.json` / `pnpm-workspace.yaml` is not valid.                                                                                                                                                                                                     |
-| `<file>: packages must be an array of glob strings`                                                          | `pnpm-workspace.yaml` `packages:` is a bare string, etc.                                                                                                                                                                                                   |
-| `<file>: must be a JSON object`                                                                              | A `package.json` (the root's or a member's) is `null`, a list or a scalar; it crashed with a TypeError until item 988.                                                                                                                                     |
-| `<file>: "name" must be a string with no surrounding whitespace`                                             | A `package.json` `name` is a number, an object, or has surrounding whitespace (npm refuses one too); `{"name":123}` planned `123#build` until item 988.                                                                                                    |
-| `<file>: "name" cannot hold "#" — vx addresses a task as <name>#<task>`                                      | A `package.json` `name` holds `#` (npm refuses one too): `{"name":"a#b"}` planned `a#b#build` under `--all`, but `vx run a#b#build` and a `dependsOn` split at the first `#` and found nothing.                                                            |
-| `<file>: must be a mapping (packages: and pnpm's settings)`                                                  | `pnpm-workspace.yaml` is a list or a scalar. A mapping with no `packages:`, or an empty one (pnpm 10 settings or catalogs in a single-package repo) is not an error: the root's `package.json` decides, as without the file (item 984).                    |
-| `<file>: workspaces must be an array of glob strings`                                                        | `package.json` `workspaces` holds a non-string entry.                                                                                                                                                                                                      |
-| `workspace member <dir> (<abs>) is outside the workspace root <root>: vx keeps every project under the root` | A member glob (`../ext/*`, an absolute path) reached a package outside the root. npm and pnpm take one; `--affected` asks git from the root and missed edits there. Move the root up to a directory that holds every member.                               |
-| `<file>: workspaces.packages must be an array of glob strings`                                               | The yarn-legacy `workspaces: { packages: [...] }` form holds a non-string entry.                                                                                                                                                                           |
-| `<file>: <field> entry "<glob>" is an extglob, which vx's glob engine does not read`                         | A member glob holds `!(…)`, `@(…)`, `+(…)`, `*(…)` or `?(…)`. `Bun.Glob` has no extglob (its scan widened `packages/!(x)` to include x, turborepo#3766); a whole-segment `!(a\|b)` gets its exact rewrite, `["packages/*", "!packages/a", "!packages/b"]`. |
+Project-discovery errors (`src/workspace/workspace.ts`, `src/orchestrator/projects.ts`):
+
+| Symptom                                                                                         | Cause                                                                     |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `two projects are named "<name>": <dir> and <dir> — give one another \`name\` in its vx.config` | Two directories got one name: a config's `name`, a plugin's, or the path. |
+| `<dir>: a project is named by its path unless named, and this one holds "#" …`                  | A path no task spec can address: set `name` in its config.                |
+| `<dir>: "//" names the workspace root — set another \`name\``                                   | A config away from the root says `name: '//'`.                            |
+| `.vx/projects.lock.json locks <dir>, but its <file> is gone — run \`vx lock\``                  | A locked project's config was deleted or renamed (X-144).                 |
+| `.vx/projects.lock.json locks <dir>, but its <file> is not readable by this user (<code>)`      | This user may not search the project's directory (D-132).                 |
+| `.vx/projects.lock.json has unsupported version <n> (this vx expects 3) — re-run \`vx lock\``   | A lock an earlier vx wrote (version 2 keyed by name).                     |
+| `git ls-files failed (exit <n>): <why>`                                                         | `vx lock` could not list the configs (a torn index).                      |
+
+Core reads no `package.json` or `pnpm-workspace.yaml`; the errors reading them are `@vzn/vx-migrate`'s (its README, "Errors reading the members").
 
 Workspace-config errors:
 
-| Symptom                                                                                                                                                                        | Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `concurrency must be a positive integer`                                                                                                                                       | `concurrency` is negative, zero, NaN, ...                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `timeout must be a positive integer (milliseconds)`                                                                                                                            | Workspace `timeout` is ≤ 0, NaN, or not an int.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `cacheDir must be a string`                                                                                                                                                    | Wrong shape.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `cacheDir is only whitespace — name a directory`                                                                                                                               | A `cacheDir` of spaces: it made a directory named so at the root, hidden by the cache's own `.gitignore`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `cacheDir holds a NUL, which no path can carry`                                                                                                                                | No path can hold a NUL; the cache directory's creation failed and blamed the workspace's permissions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `cacheRetention must be { olderThan?: '30d', maxSize?: '10G' }`                                                                                                                | Not an object.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `cacheRetention names neither olderThan nor maxSize`                                                                                                                           | An empty policy would evict nothing and read as one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `cacheRetention.olderThan must be a duration like '30d', '12h', '90m' or '45s'`                                                                                                | The `vx cache prune --older-than` spelling, or not a string.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `cacheRetention.maxSize must be a size like '10G', '500MB' or '64KB'`                                                                                                          | The `vx cache prune --max-size` spelling (no fractions), or not a string.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `cacheRetention.olderThan of 0 evicts every entry after every run`                                                                                                             | Every run would evict what it just saved; `vx cache prune --older-than 0` is refused too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `cacheRetention.maxSize of 0 evicts every entry after every run`                                                                                                               | The same, for the size bound.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `cacheRetention.maxSize '<n>' reads as <n> bytes — give a unit (e.g. '<n>M', '<n>G')`                                                                                          | A bare number is bytes; a cache capped at `10` bytes is a typo for `10G`. `10B` still loads.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `affectedBase must be a git ref like 'origin/main'`                                                                                                                            | Not a string, empty, holding whitespace or a NUL, or opening with `-` (git would read an option).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `cacheScope must be 'trusted', 'read-only', or a scope name of <rule>`                                                                                                         | Not a string, or a scope name holding a character outside letters, digits and `. _ - / @`, or longer than 128.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `rules must be { exclusiveOutputs?: boolean; upfrontKeys?: boolean }`                                                                                                          | Not an object.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `rules.<name> must be true or false`                                                                                                                                           | A rule set to something other than a boolean (`'off'`, `0`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `plugins must be an array of plugin objects`                                                                                                                                   | Wrong shape.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `plugins[<i>] must be an object`                                                                                                                                               | A non-object entry in `plugins`; a string (Nx's `'@nx/vite/plugin'`) adds that a plugin is what its package's function returns, not a module name (D-49).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `plugins[<i>] must come from definePlugin(import.meta, { … })`                                                                                                                 | A plain object where a plugin was expected: a plugin's name is its package name, and only `definePlugin` sets it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `plugins[<i>] is a Promise — await the factory that returns the plugin`                                                                                                        | An async plugin factory called without `await` (`plugins: [later()]`); the refusal said the plugin did not come from `definePlugin` (D-159).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `plugins[<i>].name overrides the package name`                                                                                                                                 | A `name` set over `definePlugin`'s result; drop the field.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `plugins[<i>].<capability> of plugin '<name>' must be a function`                                                                                                              | A capability key holding something that is not callable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `plugins[<i>] (plugin '<name>') must contribute at least one of config/discover/project/graph/key/fingerprint/schedule/admit/executor/cache/telemetry/setup/commands/teardown` | A plugin object with no capability.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `plugin '<name>' declares '<key>', which is no plugin hook`                                                                                                                    | A key on a plugin that names no hook (`excutor`, `setUp`): it was never called. The nearest hook is hinted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `<file> has unknown field "<key>"`                                                                                                                                             | Typo'd / unsupported top-level key (`plugin`); the hint names the nearest spelling, or where vx keeps a Turbo or Nx key (`pipeline`, `remoteCache`, `parallel`, `cacheDirectory`, `defaultBase`, `tasksRunnerOptions`, `globalPassThroughEnv`; D-38, D-49; pnpm-workspace.yaml's, Lerna's and package.json's `packages`, `workspaces`, `catalog`, `npmClient`, and `ignore`, `cache`, `remote`, `env`, D-98; in a project's vx.config, `targets`, `extends`, `implicitDependencies` and `name`, D-56; `scripts`, `pipeline`, `namedInputs`, `root`, `sourceRoot`, `projectType`, and a task's `dependsOn`, `cache`, `exec`, `inputs`, `outputs`, `env` one level too high, D-99). |
-| `plugin '<name>' declares command '<verb>', a core verb — core verbs cannot be shadowed`                                                                                       | A plugin verb the dispatcher matches first; it could never run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `plugin '<name>' declares command '<verb>', which is not a word — a verb is a letter or digit, then letters, digits, ':', '.', '_' or '-'`                                     | A verb like `--version`, `''` or `a b`: core reads a flag first, an empty word is no verb, and `vx completions` writes verbs unquoted into a shell script.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `plugins '<a>' and '<b>' both declare command '<verb>' — a verb has one owner`                                                                                                 | Two packages on one verb; the first would win and hide the second. Plugins of one package are one owner, and the first declared runs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `plugins[<i>].fingerprint of plugin '<name>' must be { files: [name, …], affected: function }`                                                                                 | A fingerprint claim without its file list or its `affected` answer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `plugin '<name>' claims fingerprint file "<file>", which is not a file name at the workspace root`                                                                             | A claim names a path, or no name: a claim is a bare file at the root (`vx watch`'s root arm is not recursive).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `plugins '<a>' and '<b>' both claim fingerprint file '<file>' — a file has one claimant`                                                                                       | Two plugins keying the same lockfile; the key would fold both and `--affected` could ask only one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `plugin '<name>' claims fingerprint file '<file>' twice (plugins[<i>] and plugins[<j>]) — a file has one claimant; declare the plugin once`                                    | One plugin package declared twice (`plugins: [bun(), bun()]`); the message named it as two plugins (D-158).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Symptom                                                                                                                                                                               | Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<setting> must be <what its kind takes> (got <value>)`                                                                                                                               | A setting of the wrong type or out of range: `run.concurrency: 0`, `cache.dir: 42`, `run.schedule: 'fastest'`. The [settings table](#settings) says what each takes; a count is a number and a switch a boolean, never a string.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `<setting> takes a duration with its unit, like '<n>ms' or '<n>s' (got <n>)`                                                                                                          | A bare number for a duration: `run.timeout: 30000`. Durations carry a unit, so `30000` cannot be read as seconds by mistake.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `<setting> of <value> exceeds the maximum timer delay`                                                                                                                                | A timer past 2^31-1 ms fires at once, not never. Omit `run.timeout` for no limit.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `<group> must be an object (fields: <fields>)`                                                                                                                                        | `run`, `watch`, `run.rules` or `cache.retention` that is not an object.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `cache must be an object like { dir, policy, scope }; a task caches through its own cache in its project's vx.config`                                                                 | Not an object: Turbo's and Nx's workspace `cache: true` is a task's own `cache` in vx.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `cache.dir holds a NUL, which no path can carry`                                                                                                                                      | No path can hold a NUL; the cache directory's error blamed the workspace's permissions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `run.affectedBase must be a git ref like 'origin/main'`                                                                                                                               | Empty, holding whitespace or a NUL, or starting with `-`, which git would read as an option.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `cache.scope must be a scope name of <rule>`                                                                                                                                          | Not a string, or a scope name holding a character a cache key cannot carry.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `cache.retention names neither olderThan nor maxSize`                                                                                                                                 | An empty policy would evict nothing and read as one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `cache.retention.olderThan of 0 evicts every entry after every run`                                                                                                                   | Every run would evict what it just saved; `vx cache clean` refuses it too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `cache.retention.maxSize of 0 evicts every entry after every run`                                                                                                                     | The same, for the size bound.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `cache.retention.maxSize '<n>' reads as <n> bytes — give a unit (e.g. '<n>MB', '<n>GB')`                                                                                              | A bare number is bytes; a cache capped at ten bytes keeps nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `plugins must be an array of plugin objects`                                                                                                                                          | Wrong shape.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `plugins[<i>] must be an object`                                                                                                                                                      | A non-object entry in `plugins`; a string (Nx's `'@nx/vite/plugin'`) adds that a plugin is what its package's function returns, not a module name (D-49).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `plugins[<i>] must come from definePlugin(import.meta, { … })`                                                                                                                        | A plain object where a plugin was expected: a plugin's name is its package name, and only `definePlugin` sets it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `plugins[<i>] is a Promise — await the factory that returns the plugin`                                                                                                               | An async plugin factory called without `await` (`plugins: [later()]`); the refusal said the plugin did not come from `definePlugin` (D-159).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `plugins[<i>].name overrides the package name`                                                                                                                                        | A `name` set over `definePlugin`'s result; drop the field.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `plugins[<i>].<capability> of plugin '<name>' must be a function`                                                                                                                     | A capability key holding something that is not callable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `plugins[<i>] (plugin '<name>') must contribute at least one of config/discover/project/graph/key/fingerprint/schedule/admit/executor/cache/telemetry/output/setup/commands/teardown` | A plugin object with no capability.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `plugin '<name>' declares '<key>', which is no plugin hook`                                                                                                                           | A key on a plugin that names no hook (`excutor`, `setUp`): it was never called. The nearest hook is hinted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `<file> has unknown field "<key>"`                                                                                                                                                    | Typo'd / unsupported top-level key (`plugin`); the hint names the nearest spelling, or where vx keeps a Turbo or Nx key (`pipeline`, `remoteCache`, `parallel`, `cacheDirectory`, `defaultBase`, `tasksRunnerOptions`, `globalPassThroughEnv`; D-38, D-49; pnpm-workspace.yaml's, Lerna's and package.json's `packages`, `workspaces`, `catalog`, `npmClient`, and `ignore`, `cache`, `remote`, `env`, D-98; in a project's vx.config, `targets`, `extends`, `implicitDependencies` and `name`, D-56; `scripts`, `pipeline`, `namedInputs`, `root`, `sourceRoot`, `projectType`, and a task's `dependsOn`, `cache`, `exec`, `inputs`, `outputs`, `env` one level too high, D-99). |
+| `plugin '<name>' declares command '<verb>', a core verb — core verbs cannot be shadowed`                                                                                              | A plugin verb the dispatcher matches first; it could never run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `plugin '<name>' declares command '<verb>', which is not a word — a verb is a letter or digit, then letters, digits, ':', '.', '_' or '-'`                                            | A verb like `--version`, `''` or `a b`: core reads a flag first, an empty word is no verb, and `vx completions` writes verbs unquoted into a shell script.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `plugins '<a>' and '<b>' both declare command '<verb>' — a verb has one owner`                                                                                                        | Two packages on one verb; the first would win and hide the second. Plugins of one package are one owner, and the first declared runs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `plugins[<i>].fingerprint of plugin '<name>' must be { files: [name, …], affected: function }`                                                                                        | A fingerprint claim without its file list or its `affected` answer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `plugin '<name>' claims fingerprint file "<file>", which is not a file name at the workspace root`                                                                                    | A claim names a path, or no name: a claim is a bare file at the root (`vx watch`'s root arm is not recursive).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `plugins '<a>' and '<b>' both claim fingerprint file '<file>' — a file has one claimant`                                                                                              | Two plugins keying the same lockfile; the key would fold both and `--affected` could ask only one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `plugin '<name>' claims fingerprint file '<file>' twice (plugins[<i>] and plugins[<j>]) — a file has one claimant; declare the plugin once`                                           | One plugin package declared twice (`plugins: [bun(), bun()]`); the message named it as two plugins (D-158).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |