@vzn/vx 0.0.636 → 0.0.638

package/README.md

@@ -38,10 +38,23 @@ Windows: run vx inside WSL2.
 In a git repo with a `package.json` workspace:
 
 ```sh
-npx vx init               # a vx.config.ts per package, from its scripts
+npm install -D @vzn/vx         # the scope matters: npm's `vx` is an unrelated package
+npx @vzn/vx init               # beside turbo.json or nx.json: migrates them; else a vx.config.ts per package
+npx @vzn/vx run build --all    # builds in dependency order and stores the results
+npx @vzn/vx run build --all    # nothing changed: every task up-to-date
 ```
 
-Give a task a cache block, what it reads and writes:
+Bun workspaces: `bun add -d @vzn/vx` and `bunx @vzn/vx` (npm refuses to run in
+a repo whose `devEngines` names Bun).
+
+Without Turbo or Nx, tasks run uncached until you declare what they read (below).
+
+`init` prints what it wrote and anything left to decide (a `TODO`). A miss you did not expect?
+`npx @vzn/vx why <task>` names the input that moved.
+
+### Without Turbo or Nx
+
+`init` writes one task per package script, uncached. Cache one by saying what it reads and writes:
 
 ```ts
 // packages/app/vx.config.ts
@@ -62,15 +75,31 @@ export default defineProject({
 ```
 
 ```sh
-npx vx run build --all    # builds, in dependency order; stores the results
-npx vx run build --all    # nothing changed: up-to-date, in milliseconds
+npx @vzn/vx run build --all    # builds, in dependency order; stores the results
+npx @vzn/vx run build --all    # nothing changed: up-to-date, in milliseconds
 rm -rf packages/*/dist
-npx vx run build --all    # restored from the cache, not rebuilt
+npx @vzn/vx run build --all    # restored from the cache, not rebuilt
 ```
 
 <img src="https://vznjs.github.io/vx/demo.svg" width="760" alt="vx run ci --all on examples/basic: cold, three tasks run; again, three up-to-date.">
 
-Starter: [`examples/basic`](examples/basic), run by CI on every commit.
+### When to run `vx lock`
+
+`init` also writes `.vx/projects.lock.json`, every project's config as it evaluated.
+Commit it. Every run reads its configs from the lock, so run
+`npx @vzn/vx lock` and commit the lock again after you:
+
+- edit any `vx.config.ts` or `.vx/workspace.ts`,
+- update dependencies or plugins,
+- change a file a config imports.
+
+Otherwise runs keep the old configs. On CI, `vx lock --check` fails a
+stale lock before any task runs.
+
+Starters: [`examples/basic`](examples/basic), and
+[`examples/ci`](examples/ci) with a GitHub Actions workflow; CI runs both
+on every commit. The [CI guide](https://vznjs.github.io/vx/guides/ci/)
+explains the workflow.
 More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
 [Configure](https://vznjs.github.io/vx/guides/configure/) ·
 [CLI](packages/vx/docs/cli.md) · [every config field](packages/vx/docs/schema.md) ·
@@ -84,13 +113,13 @@ More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
 - **Sandboxed tasks:** opt in per task; a workspace file the task did
   not declare is out of its reach, so it cannot poison the cache.
 - **Clean exits:** Ctrl-C reaps each task's process group.
-- **Plugins at every stage** (14 hooks, `commands` included): remote cache, remote execution, telemetry,
+- **Plugins at every stage** (15 hooks, `commands` included): remote cache, remote execution, telemetry,
   CLI verbs. Core ships none and needs none.
 - **Free:** MIT. No paywall, no cloud, no account.
 
 ## Plugins
 
-What vx can do, not what it is limited to. Declared in `vx.workspace.ts`; without any, vx runs and caches locally.
+What vx can do, not what it is limited to. Declared in `.vx/workspace.ts`; without any, vx runs and caches locally.
 
 | Package                                                    | What it adds                                                                  |
 | ---------------------------------------------------------- | ----------------------------------------------------------------------------- |
@@ -99,7 +128,6 @@ What vx can do, not what it is limited to. Declared in `vx.workspace.ts`; withou
 | [`@vzn/vx-lockfile`](packages/vx-lockfile)                 | Key each project on its own lockfile slice: pnpm, bun, npm, yarn              |
 | [`@vzn/vx-otel`](packages/vx-otel)                         | OpenTelemetry traces, metrics and logs, no SDK                                |
 | [`@vzn/vx-ci`](packages/vx-ci)                             | GitHub Actions job summary and Checks API                                     |
-| [`@vzn/vx-mcp`](packages/vx-mcp)                           | `vx mcp`: an MCP server for AI coding agents that also runs tasks             |
 | [`@vzn/vx-schedule-history`](packages/vx-schedule-history) | Schedule by the critical path learned from past runs                          |
 
 Write your own: [plugin guide](https://vznjs.github.io/vx/guides/plugins/) ·
@@ -107,10 +135,10 @@ Write your own: [plugin guide](https://vznjs.github.io/vx/guides/plugins/) ·
 
 ## Coming from Turbo or Nx
 
-Beside `turbo.json` or `nx.json`, `npx vx init` runs `@vzn/vx-migrate`:
+Beside `turbo.json` or `nx.json`, `npx @vzn/vx init` runs `@vzn/vx-migrate`:
 it writes a `vx.config.ts` per package from `turbo.json` or the Nx graph,
 and you keep those and delete the old config. `vx init --keep` writes only
-a `vx.workspace.ts` that maps the old config instead: a temporary start,
+a `.vx/workspace.ts` that maps the old config instead, and its lock: a temporary start,
 not a way to run the repo. The benchmark below uses native vx config.
 [Migration guide](https://vznjs.github.io/vx/guides/migrate/).