@vzn/vx 0.0.632 → 0.0.634

package/src/cache/chained-cache.ts

@@ -12,6 +12,7 @@
 // (item 1020). A save that fails in EVERY layer still throws, so the
 // caller's own "cache save failed" line stays the one word on it.
 
+import { statSync } from 'node:fs'
 import type {
   Cache,
   CacheEntry,
@@ -248,6 +249,14 @@ export class ChainedCache implements CacheLayer {
     return this.owner(hash).outputsPath(hash)
   }
 
+  /** A layer that cannot say keeps a file at `outputsPath`, or nothing. */
+  artifactSize(hash: string): number | undefined {
+    const owner = this.owner(hash)
+    return owner.artifactSize !== undefined
+      ? owner.artifactSize(hash)
+      : statSync(owner.outputsPath(hash), { throwIfNoEntry: false })?.size
+  }
+
   prune(options: PruneOptions): Promise<PruneResult> {
     return this.layers[0]!.prune(options)
   }

package/src/cache/inputs.ts

@@ -92,6 +92,11 @@ const ALWAYS_IGNORE = [
   // extracts the downloaded runtime into, `<cwd>/.<16 hex>-<8 hex>.tmp/`,
   // 60 MB mid-write under the same race (2026-09-29).
   '**/.????????????????-????????.tmp/**',
+  // vx's own restore temp (archive.ts), live only while an artifact lands
+  // beside its target. A key taken meanwhile listed it, the rename removed
+  // it, and every task reading that directory was withheld its save
+  // (withastro/astro: 25 of 33 builds re-ran on a restore, X-209).
+  '**/.vx-tmp-*',
 ]
 
 const DEFAULT_FILE_GLOBS: readonly string[] = ['**/*']
@@ -214,7 +219,7 @@ export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedIn
     // Dedupe: when the project dir IS the workspace root (or a glob
     // overlaps), the same absolute path can arrive via both lists —
     // it must contribute to the key exactly once.
-    if (wsFiles.length > 0) files = [...new Set([...projectFiles, ...wsFiles])].sort()
+    if (wsFiles.length > 0) files = mergeSorted(projectFiles, wsFiles)
   }
   // Two awaited empty resolutions per task were ~3 ms of a 1000-task warm
   // run (profiled 2026-09-09); a task declaring neither skips the fan-out.
@@ -280,7 +285,6 @@ function resolveWorkspaceFiles(args: {
   }
   if (positive.length === 0) return undefined
 
-  const isExcluded = anyTaskGlob([...ALWAYS_IGNORE, ...asTrees(negative)])
   // A path the task's own outputs take back with `!` is no output, so it
   // stays an input (A-44).
   const ownOutput = outputMatcher(args.ownWorkspaceOutputs)
@@ -305,40 +309,44 @@ function resolveWorkspaceFiles(args: {
   // The memo is valid for the snapshot it was computed over: a task that
   // wrote workspace outputs mid-run replaces the partition, and the next
   // caller sees a different array and scans again.
-  const memoKey =
-    args.memo === undefined
-      ? undefined
-      : JSON.stringify([
-          positive,
-          negative,
-          args.ownWorkspaceOutputs,
-          args.ownOutputs,
-          args.projectRel,
-        ])
+  let isExcluded: ((rel: string) => boolean) | undefined
   let isPositive: ((rel: string) => boolean) | undefined
-  const excluded = (rel: string): boolean => isExcluded(rel) || ownOutput(rel) || ownProject(rel)
+  const excludedByDeclaration = (rel: string): boolean =>
+    (isExcluded ??= anyTaskGlob([...ALWAYS_IGNORE, ...asTrees(negative)]))(rel)
+  const own = (rel: string): boolean => ownOutput(rel) || ownProject(rel)
   const listing: InputListing = {
     root: args.workspaceRoot,
     listed: gitFiles,
-    isInput: (rel) => (isPositive ??= anyTaskGlob(asTrees(positive)))(rel) && !excluded(rel),
+    isInput: (rel) =>
+      (isPositive ??= anyTaskGlob(asTrees(positive)))(rel) &&
+      !excludedByDeclaration(rel) &&
+      !own(rel),
     nested: () => false,
     ...reachOf(positive),
   }
-  if (memoKey !== undefined) {
-    const hit = args.memo!.get(memoKey)
-    if (hit !== undefined && hit.snapshot === gitFiles) return { files: hit.result, listing }
+  // Two levels: the declaration's files over the snapshot, shared by every
+  // task that declares it, then the task's own outputs taken out. A
+  // Turbo-mapped repo gives two thousand tasks one 400-entry list, and a
+  // memo keyed by the project too scanned, resolved and sorted the 4,000
+  // files it matched once per task (astro, 2026-10-09).
+  const declared = JSON.stringify([positive, negative])
+  let base: Promise<string[]> | undefined
+  const hit = args.memo?.get(declared)
+  if (hit !== undefined && hit.snapshot === gitFiles) base = hit.result
+  if (base === undefined) {
+    isPositive ??= anyTaskGlob(asTrees(positive))
+    base = resolveWorkspaceFilesOver(args, gitFiles, positive, isPositive, excludedByDeclaration)
+    args.memo?.set(declared, { snapshot: gitFiles, result: base })
   }
-  isPositive ??= anyTaskGlob(asTrees(positive))
-  const result = resolveWorkspaceFilesOver(
-    args,
-    gitFiles,
-    positive,
-    isPositive,
-    excluded,
-    undecodable,
-  )
-  if (memoKey !== undefined) args.memo!.set(memoKey, { snapshot: gitFiles, result })
-  return { files: result, listing }
+  const ownsAny =
+    splitNegations(args.ownWorkspaceOutputs).positive.length > 0 ||
+    splitNegations(args.ownOutputs).positive.length > 0
+  const files = base.then((all) => {
+    const kept = ownsAny ? all.filter((abs) => !own(relPosix(args.workspaceRoot, abs))) : all
+    refuseUndecodable(kept, undecodable, args.workspaceRoot, 'workspaceFiles')
+    return kept
+  })
+  return { files, listing }
 }
 
 async function resolveWorkspaceFilesOver(
@@ -347,7 +355,6 @@ async function resolveWorkspaceFilesOver(
   positive: readonly string[],
   isPositive: (rel: string) => boolean,
   excluded: (rel: string) => boolean,
-  undecodable: ReadonlySet<string> | undefined,
 ): Promise<string[]> {
   // Second call site of the literal-input guard. `resolveWorkspaceFiles`
   // carries its own copy of the filter-over-git-set design, so the same
@@ -366,13 +373,47 @@ async function resolveWorkspaceFilesOver(
   if (unmatchedLiterals.size > 0) {
     await assertNoInvisibleLiteralInputs(unmatchedLiterals, args.workspaceRoot, 'workspaceFiles')
   }
-  refuseUndecodable(candidates, undecodable, args.workspaceRoot, 'workspaceFiles')
   // Same OID-trust shortcut as project files: a clean-per-status
   // tracked file necessarily exists on disk.
   const oids = args.gitFilesCache?.oidsFor(args.workspaceRoot)
   return candidates.filter((abs) => oids?.has(abs) === true || isInputOnDisk(abs)).sort()
 }
 
+/**
+ * The sorted union of two path lists, each once. Both sides arrive sorted
+ * and distinct, so one merge does what a Set and a sort of the
+ * concatenation did: 3.7 s of an astro plan, where 2,000 tasks each joined
+ * a few project files to the same 4,000 workspace files (2026-10-09). A
+ * side out of order takes the general path.
+ */
+function mergeSorted(a: readonly string[], b: readonly string[]): string[] {
+  if (a.length === 0 && isStrictlySorted(b)) return b as string[]
+  if (!isStrictlySorted(a) || !isStrictlySorted(b)) return [...new Set([...a, ...b])].sort()
+  const out: string[] = []
+  let i = 0
+  let j = 0
+  while (i < a.length && j < b.length) {
+    const x = a[i]!
+    const y = b[j]!
+    if (x <= y) {
+      out.push(x)
+      i++
+      if (x === y) j++
+    } else {
+      out.push(y)
+      j++
+    }
+  }
+  while (i < a.length) out.push(a[i++]!)
+  while (j < b.length) out.push(b[j++]!)
+  return out
+}
+
+function isStrictlySorted(list: readonly string[]): boolean {
+  for (let i = 1; i < list.length; i++) if (!(list[i - 1]! < list[i]!)) return false
+  return true
+}
+
 /** A project-relative matcher asked of root-relative paths: false outside the project. */
 function underProject(
   projectRel: string,

package/src/cache/layer.ts

@@ -267,7 +267,7 @@ export interface InvocationRecord {
 }
 
 /**
- * One cache-key component row for the `entry_inputs` table — keyed by
+ * One cache-key component of an `entry_inputs` row (v34: one row per entry) — keyed by
  * the cache-entry HASH it belongs to, not a run. Written inside the
  * entry-save transaction (`writeArtifactAndIndex`) on a miss/save; a
  * cache HIT does not save, so it persists nothing (warm runs are free).
@@ -730,12 +730,16 @@ export interface CacheLayer {
    */
   hashFile(filePath: string): Promise<string>
   /**
-   * Absolute path to the on-disk outputs artifact for a hash —
+   * Absolute path a file-backed artifact for a hash has —
    * `<cacheDir>/<hash>.tar.zst`. Returns the path whether or
-   * not the artifact exists. Exposed for telemetry / dashboards;
-   * `restoreOutputs` is the canonical way to materialize the bytes.
+   * not the artifact exists: a small artifact lives in the index, not
+   * in a file (`artifactSize` is its size). Exposed for telemetry /
+   * dashboards; `restoreOutputs` is the canonical way to materialize
+   * the bytes.
    */
   outputsPath(hash: string): string
+  /** The stored artifact's compressed size, wherever it lives; undefined when none is stored. */
+  artifactSize?(hash: string): number | undefined
   prune(options: PruneOptions): Promise<PruneResult>
   close(): void
 }

package/src/cache/layered-cache.ts

@@ -529,6 +529,10 @@ export class LayeredCache implements CacheLayer {
     return this.local.outputsPath(hash)
   }
 
+  artifactSize(hash: string): number | undefined {
+    return this.local.artifactSize(hash)
+  }
+
   hashFile(filePath: string): Promise<string> {
     return this.local.hashFile(filePath)
   }

package/src/cache/schema.ts

@@ -1,7 +1,8 @@
 // The index's tables, one concern: what a cache.db holds. `Cache` opens the
 // file, checks `SCHEMA_VERSION` and creates these; every statement against
 // them lives in the store that owns the table (file-hashes, config-evals,
-// output-index, history) or in cache.ts for `entries` and `entry_inputs`.
+// output-index, history) or in cache.ts for `entries`, `entry_inputs` and
+// `artifacts`.
 
 import type { Database, SQLQueryBindings } from 'bun:sqlite'
 
@@ -255,22 +256,18 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
     CREATE INDEX IF NOT EXISTS main.invocations_started ON invocations(started_at);
     CREATE INDEX IF NOT EXISTS main.invocations_branch  ON invocations(branch);
     CREATE INDEX IF NOT EXISTS main.invocations_ci      ON invocations(ci);
-    -- v22 (Tier 3): the input-fingerprint moat. One row per cache-key
-    -- component, keyed by the cache-ENTRY hash it belongs to (NOT a
-    -- run id). Written inside the entry-save transaction — only on a
-    -- miss/save, never on a hit — so a warm all-cache-hit run writes
-    -- nothing here (the warm path does zero extra work). The
-    -- why-did-this-re-run diff reads two entry hashes (this run's
-    -- runs.hash and the previous run's) and anti-joins their rows in
-    -- SQL over (kind,name,hash); a JSON blob would force an app-side
-    -- parse + compare on every probe. ON DELETE CASCADE keeps these
-    -- rows in sync with entries (a prune sweeps them automatically).
+    -- v22 (Tier 3): the input-fingerprint moat: each cache ENTRY's key
+    -- components (NOT a run's). Written inside the entry-save transaction,
+    -- only on a miss/save, so a warm all-cache-hit run writes nothing
+    -- here. v34: one row per entry, the components a JSON array of
+    -- [kind, name, hash] in (kind, name) code-unit order. A row per
+    -- component cost a b-tree insert each, and a task with 50 input
+    -- files spent ~0.5 ms a save on them; every reader loads the whole
+    -- set by entry hash and diffs it app-side anyway. ON DELETE CASCADE
+    -- keeps it in sync with entries (a prune sweeps it automatically).
     CREATE TABLE IF NOT EXISTS ${store}.entry_inputs (
-      entry_hash TEXT NOT NULL,
-      kind       TEXT NOT NULL,
-      name       TEXT NOT NULL,
-      hash       TEXT NOT NULL,
-      PRIMARY KEY (entry_hash, kind, name),
+      entry_hash TEXT PRIMARY KEY,
+      components TEXT NOT NULL,
       FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
     );
     -- v32: what belongs to the entries rather than to one workspace: the
@@ -280,9 +277,38 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       key   TEXT PRIMARY KEY,
       value TEXT NOT NULL
     );
+    ${artifactTables(store)}
   `)
 }
 
+/**
+ * v33: an artifact of at most `INLINE_MAX` compressed bytes lives here, its
+ * exact `<hash>.tar.zst` bytes, written in the transaction that writes its
+ * rows. No foreign key and outside every drop a `SCHEMA_VERSION` reset makes:
+ * the artifact is the record and the entries only its inventory, so a reset
+ * drops the rows and keeps these, as it keeps the files. `artifacts_meta`
+ * holds the table's own layout version (`'layout'`), the one thing that may
+ * drop it. `at` is the last use a row-less sweep judges, as a file's mtime;
+ * it sits before `bytes` so reading it never walks a blob's overflow pages.
+ */
+export function createArtifactTables(db: Database, store: 'main' | 'store'): void {
+  db.exec(artifactTables(store))
+}
+
+// In the entry tables' exec, so an open runs no statement more for them.
+function artifactTables(store: 'main' | 'store'): string {
+  return `
+    CREATE TABLE IF NOT EXISTS ${store}.artifacts (
+      hash  TEXT PRIMARY KEY,
+      at    INTEGER NOT NULL,
+      bytes BLOB NOT NULL
+    ) WITHOUT ROWID;
+    CREATE TABLE IF NOT EXISTS ${store}.artifacts_meta (
+      key   TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );`
+}
+
 /**
  * A `WHERE <column> …` test against many hashes, as one statement whatever
  * their number. A list of `?` is a new statement per length, compiled each

package/src/cli/docs-corpus.ts

@@ -0,0 +1,21 @@
+// The pages `vx docs` searches: core's reference, imported as text so the
+// compiled binary carries them and an npm install reads them from the
+// package (package.json `files`). Loaded only by `vx docs`.
+import caching from '../../docs/caching.md' with { type: 'text' }
+import cli from '../../docs/cli.md' with { type: 'text' }
+import execution from '../../docs/execution.md' with { type: 'text' }
+import features from '../../docs/features.md' with { type: 'text' }
+import patterns from '../../docs/patterns.md' with { type: 'text' }
+import schema from '../../docs/schema.md' with { type: 'text' }
+import security from '../../docs/security.md' with { type: 'text' }
+
+/** Page name (its file, no `.md`) → markdown. */
+export const PAGES: Readonly<Record<string, string>> = {
+  cli,
+  schema,
+  caching,
+  execution,
+  patterns,
+  security,
+  features,
+}

package/src/cli/docs-text.d.ts

@@ -0,0 +1,5 @@
+// A markdown page imported `with { type: 'text' }` is its text (docs-corpus.ts).
+declare module '*.md' {
+  const text: string
+  export default text
+}

package/src/cli/docs.ts

@@ -0,0 +1,173 @@
+// `vx docs <query> [--limit N] [--format pretty|json]` — search vx's
+// reference offline, for an agent that cannot reach the site: each page is
+// cut at its headings, and the sections holding every query word print
+// whole, best first.
+
+import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
+
+const SITE = 'https://vznjs.github.io/vx/'
+const DEFAULT_LIMIT = 3
+
+interface DocsArgs {
+  terms: string[]
+  limit: number
+  json: boolean
+  error?: string
+}
+
+function parseDocsArgs(args: readonly string[]): DocsArgs {
+  const out: DocsArgs = { terms: [], limit: DEFAULT_LIMIT, json: false }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!
+    if (a === '--format' || a.startsWith('--format=')) {
+      const fv = formatValue(a === '--format' ? args[++i] : a.slice('--format='.length), 'docs')
+      if (typeof fv === 'object') return { ...out, error: fv.error }
+      out.json = fv === 'json'
+    } else if (a === '--limit' || a.startsWith('--limit=')) {
+      const v = a === '--limit' ? args[++i] : a.slice('--limit='.length)
+      const n = Number(v)
+      if (!Number.isInteger(n) || n < 1) {
+        return {
+          ...out,
+          error: `--limit takes a whole number above 0 (got ${v ?? 'nothing'})${seeHelp('docs')}`,
+        }
+      }
+      out.limit = n
+    } else if (a.startsWith('-')) {
+      return { ...out, error: `${refusedWord(a)}: ${a}${flagHint('docs', a)}${seeHelp('docs')}` }
+    } else out.terms.push(...words(a))
+  }
+  return out
+}
+
+export interface DocsHit {
+  page: string
+  heading: string
+  url: string
+  text: string
+}
+
+function words(s: string): string[] {
+  return s.toLowerCase().match(/[a-z0-9][a-z0-9_.-]*/g) ?? []
+}
+
+/** GitHub's heading anchor, which Starlight shares: lowercase, punctuation dropped, spaces to `-`. */
+function anchor(heading: string): string {
+  return heading
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N} _-]/gu, '')
+    .replace(/ /g, '-')
+}
+
+/** A page's URL on the site; `features.md` is served as `all-features/`. */
+function pageUrl(page: string): string {
+  return `${SITE}${page === 'features' ? 'all-features' : page}/`
+}
+
+interface Section {
+  page: string
+  heading: string
+  text: string
+}
+
+/** Cut a page at its headings (outside code fences); the text before the first is the page's own. */
+function sections(page: string, md: string): Section[] {
+  const out: Section[] = []
+  let heading = ''
+  let lines: string[] = []
+  let fence = false
+  const flush = () => {
+    const text = lines.join('\n').trim()
+    if (text !== '') out.push({ page, heading, text })
+  }
+  for (const line of md.split('\n')) {
+    if (/^\s*(```|~~~)/.test(line)) fence = !fence
+    const h = fence ? null : /^#{1,4} (.+)$/.exec(line)
+    if (h !== null) {
+      flush()
+      heading = h[1]!.replace(/`/g, '').trim()
+      lines = [line]
+    } else lines.push(line)
+  }
+  flush()
+  return out
+}
+
+function count(hay: string, term: string): number {
+  let n = 0
+  for (let i = hay.indexOf(term); i !== -1; i = hay.indexOf(term, i + term.length)) n++
+  return n
+}
+
+/**
+ * The sections holding every term, best first: a term in the heading
+ * outweighs any count in the text. A section titled by the one word asked
+ * (an error code) is the answer alone.
+ */
+export function searchDocs(
+  pages: Readonly<Record<string, string>>,
+  terms: readonly string[],
+  limit: number,
+): DocsHit[] {
+  const scored: { s: Section; score: number; order: number }[] = []
+  let order = 0
+  for (const [page, md] of Object.entries(pages)) {
+    for (const s of sections(page, md)) {
+      order++
+      const head = s.heading.toLowerCase()
+      const body = s.text.toLowerCase()
+      let score = 0
+      let all = true
+      for (const t of terms) {
+        const inBody = count(body, t)
+        if (inBody === 0) all = false
+        score += (head.includes(t) ? 10 : 0) + Math.min(inBody, 5)
+      }
+      if (all) scored.push({ s, score, order })
+    }
+  }
+  scored.sort((a, b) => b.score - a.score || a.order - b.order)
+  const exact =
+    terms.length === 1 ? scored.filter(({ s }) => words(s.heading).join(' ') === terms[0]) : []
+  return (exact.length > 0 ? exact : scored).slice(0, limit).map(({ s }) => ({
+    page: s.page,
+    heading: s.heading,
+    url: s.heading === '' ? pageUrl(s.page) : `${pageUrl(s.page)}#${anchor(s.heading)}`,
+    text: s.text,
+  }))
+}
+
+export async function docsCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseDocsArgs(args)
+  if (parsed.error) return refuse('docs', args, parsed.error, 'VX_E_USAGE')
+  if (parsed.terms.length === 0) {
+    return refuse(
+      'docs',
+      args,
+      `name what to look for, as in \`vx docs cache inputs\`${seeHelp('docs')}`,
+      'VX_E_USAGE',
+    )
+  }
+  const { PAGES } = await import('./docs-corpus.js')
+  const hits = searchDocs(PAGES, parsed.terms, parsed.limit)
+  const query = parsed.terms.join(' ')
+  if (parsed.json) {
+    process.stdout.write(`${JSON.stringify({ query, hits })}\n`)
+    return 0
+  }
+  if (hits.length === 0) {
+    process.stdout.write(
+      `vx docs: no section of ${Object.keys(PAGES).join(', ')} holds every word of "${query}"; try fewer words, or ${SITE}llms.txt\n`,
+    )
+    return 0
+  }
+  process.stdout.write(
+    hits
+      .map(
+        (h) =>
+          `── ${h.page}.md${h.heading === '' ? '' : ` § ${h.heading}`} · ${h.url}\n\n${h.text}\n`,
+      )
+      .join('\n'),
+  )
+  return 0
+}

package/src/cli/help.ts

@@ -108,13 +108,14 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx run [OPTIONS] [TASK | PKG#TASK ...] [-- forwarded-args...]',
     '  vx watch [OPTIONS] TASK [-- forwarded-args...]',
     '  vx cache prune [--older-than <duration>] [--max-size <size>] [--dry-run] [--format pretty|json] [--cache-dir <path>]',
-    '  vx lock [--check]',
-    '  vx init [--dry] [--force] [--mjs] [--native|--keep] [--plugin <seam>]',
+    '  vx lock [--check] [--format pretty|json]',
+    '  vx init [--dry [--format pretty|json]] [--force] [--mjs] [--native|--keep] [--plugin <seam>]',
     '  vx upgrade [TAG]',
     '  vx show [PROJECT[#TASK] | TASK] [--filter <pattern>] [--affected[=<ref>]] [--format pretty|json]',
     '  vx info [--format pretty|json] [--cache-dir <path>]',
     '  vx why (TASK | PKG#TASK) [--run RUNID] [--format pretty|json] [--cache-dir <path>]',
     '  vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--format pretty|json] [--cache-dir <path>]',
+    '  vx docs <query> [--limit N] [--format pretty|json]',
     '  vx completions bash|zsh|fish',
     '  vx help [VERB]',
     '  vx version',
@@ -241,6 +242,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       TODO(vx-migrate) comments. Beside turbo.json or nx.json:',
     '                       runs @vzn/vx-migrate, which asks native or keep.',
     '      --dry            Print the generated files instead of writing them.',
+    '      --format json    With --dry: the plan as one JSON document (schemas/init.json).',
     '      --force          Overwrite existing vx.config.* files.',
     '      --mjs            Write .mjs files (no type import) instead of .ts.',
     '      --native         Turbo or Nx: write a vx.config.ts per package (no question).',
@@ -256,6 +258,14 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                           every flag of each. `eval "$(vx completions bash)"`,',
     '                           or write it where the shell loads completions from.',
     '',
+    'Docs:',
+    '  vx docs <query>      Search the reference offline (cli, schema, caching, execution,',
+    '                       patterns, security, features): the sections holding every',
+    '                       word of the query print whole, best first, with their URL;',
+    '                       an error code (vx docs VX_E_CYCLE) prints its fix alone.',
+    '      --limit N        How many sections (default 3).',
+    '      --format json    {query, hits: [{page, heading, url, text}]}.',
+    '',
     'Config lock:',
     '  vx lock              Evaluate every vx.config in the current environment and',
     '                       freeze the resolved objects into vx-lock.json. Plain runs',
@@ -264,7 +274,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx lock --check      Audit the lock: file-changed hash report PLUS a full',
     '                       re-evaluation compared against the frozen objects. Exits 1',
     '                       on drift (e.g. configs that read env vars). Run it before',
-    '                       `vx run --frozen` in CI.',
+    '                       `vx run --frozen` in CI. With --format json it prints',
+    '                       {upToDate, audited, notAudited, problems}.',
     '',
     ...(pluginCommands.length > 0 ? ['Plugin commands:', ...pluginCommands, ''] : []),
   ].join('\n')

package/src/cli/index.ts

@@ -109,6 +109,8 @@ export async function run(argv: readonly string[]): Promise<number> {
       return await (await import('./cache.js')).cacheCmd(rest)
     case 'lock':
       return await (await import('./lock.js')).lockCmd(rest)
+    case 'docs':
+      return await (await import('./docs.js')).docsCmd(rest)
     case 'init':
       return await (await import('./init.js')).initCmd(rest)
     case 'upgrade':