@visulima/vis 2.0.0 → 2.0.1

package/dist/config/index.d.ts

@@ -2,14 +2,14 @@ import { TargetConfiguration, TaskResult, Task, FingerprintContributor, Constrai
 export type { FingerprintContributor } from '@visulima/task-runner';
 import { VisReleaseConfig } from "../release/types.js";
 /**
-* One family of upstream-coupled packages.
-*
-* `members` is an exact-match list. `prefixes` accept any dep whose
-* name starts with the prefix — useful for monorepos that ship many
-* subpackages under one scope (e.g. `@babel/`, `@storybook/`,
-* `@nx/`). A family can use either or both; a dep matching either
-* list belongs to the family.
-*/
+ * One family of upstream-coupled packages.
+ *
+ * `members` is an exact-match list. `prefixes` accept any dep whose
+ * name starts with the prefix — useful for monorepos that ship many
+ * subpackages under one scope (e.g. `@babel/`, `@storybook/`,
+ * `@nx/`). A family can use either or both; a dep matching either
+ * list belongs to the family.
+ */
 interface SimilarDepFamily {
   /** Stable id; used in report output and config overrides. */
   id: string;
@@ -25,28 +25,28 @@ type FmtAdapterId = "biome" | "deno-fmt" | "dprint" | "oxfmt" | "prettier" | "ru
 /** Adapter IDs that can lint (adapter `kind` is `"lint"` or `"both"`). */
 type LintAdapterId = "biome" | "deno-lint" | "eslint" | "markdownlint" | "oxlint" | "ruff-check" | "shellcheck" | "stylelint";
 /**
-* Runtime adapter contract for the cross-runtime multi-tool (see
-* `rfc/design-runtime-multitool.md`). Phase 0 defines the identity +
-* detection metadata; Phase 1 extends adapters with the spawn-building
-* methods (`runFile` / `runScript` / `install` / `exec`) that route through
-* `pm-runner`. Deno is a planned third adapter — deliberately not a
-* `RuntimeId` yet (it carries permission + no-`node_modules` semantics that
-* the first cut omits).
-*/
+ * Runtime adapter contract for the cross-runtime multi-tool (see
+ * `rfc/design-runtime-multitool.md`). Phase 0 defines the identity +
+ * detection metadata; Phase 1 extends adapters with the spawn-building
+ * methods (`runFile` / `runScript` / `install` / `exec`) that route through
+ * `pm-runner`. Deno is a planned third adapter — deliberately not a
+ * `RuntimeId` yet (it carries permission + no-`node_modules` semantics that
+ * the first cut omits).
+ */
 /** JS runtimes vis can target today. `"deno"` is deferred. */
 type RuntimeId = "bun" | "node";
 type VersionManagerName = "asdf" | "corepack" | "fnm" | "mise" | "none" | "nvm" | "proto" | "self-activate" | "volta";
 type RuntimeTool = "aube" | "bun" | "deno" | "go" | "node" | "npm" | "pnpm" | "python" | "ruby" | "rust" | "yarn";
 interface ToolchainConfig {
   /**
-  * When a tool pin doesn't match the running version, try to fix it
-  * automatically before `vis run` / `vis ci` proceed. Defaults to
-  * `true` when {@link findInstalledManagers} reports at least one
-  * installed manager, `false` otherwise.
-  *
-  * Set to `false` to keep the doctor-style warning behaviour and
-  * make users run `vis toolchain install` themselves.
-  */
+   * When a tool pin doesn't match the running version, try to fix it
+   * automatically before `vis run` / `vis ci` proceed. Defaults to
+   * `true` when {@link findInstalledManagers} reports at least one
+   * installed manager, `false` otherwise.
+   *
+   * Set to `false` to keep the doctor-style warning behaviour and
+   * make users run `vis toolchain install` themselves.
+   */
   readonly autoInstall?: boolean;
   /** Explicit manager override, useful in CI. */
   readonly preferredManager?: VersionManagerName;
@@ -54,90 +54,90 @@ interface ToolchainConfig {
   readonly tools?: Partial<Record<RuntimeTool, string>>;
 }
 /**
-* Custom task form — `{ title, task }` — analogous to lint-staged's
-* listr-style task objects. `task` receives the matched absolute paths
-* and returns a promise that resolves on success or rejects on failure.
-*/
+ * Custom task form — `{ title, task }` — analogous to lint-staged's
+ * listr-style task objects. `task` receives the matched absolute paths
+ * and returns a promise that resolves on success or rejects on failure.
+ */
 interface CustomTask {
   readonly task: (files: string[]) => unknown;
   readonly title: string;
 }
 /**
-* Object form of a command task. Unlike a bare command string it carries
-* execution options:
-*
-* - `perPackage` runs the command once per workspace package that owns the
-*   matched files, with `cwd` set to that package's directory and file paths
-*   made relative to it. Use it for tools that resolve their config or
-*   plugins from the nearest `package.json` — e.g. eslint with a
-*   cwd-sensitive shareable config. Files that sit under no workspace
-*   package fall back to a single run from the workspace root.
-* - `cwd` pins the command to a fixed directory (relative to the workspace
-*   root, or absolute) and passes the matched files as absolute paths so
-*   they resolve regardless of where the command runs. Ignored when
-*   `perPackage` is set — that derives the cwd per package instead.
-*
-* A command task is distinguished from {@link CustomTask} by carrying a
-* `command` string and no `task` function.
-*/
+ * Object form of a command task. Unlike a bare command string it carries
+ * execution options:
+ *
+ * - `perPackage` runs the command once per workspace package that owns the
+ *   matched files, with `cwd` set to that package's directory and file paths
+ *   made relative to it. Use it for tools that resolve their config or
+ *   plugins from the nearest `package.json` — e.g. eslint with a
+ *   cwd-sensitive shareable config. Files that sit under no workspace
+ *   package fall back to a single run from the workspace root.
+ * - `cwd` pins the command to a fixed directory (relative to the workspace
+ *   root, or absolute) and passes the matched files as absolute paths so
+ *   they resolve regardless of where the command runs. Ignored when
+ *   `perPackage` is set — that derives the cwd per package instead.
+ *
+ * A command task is distinguished from {@link CustomTask} by carrying a
+ * `command` string and no `task` function.
+ */
 interface CommandTask {
   readonly command: string;
   readonly cwd?: string;
   readonly perPackage?: boolean;
 }
 /**
-* A task value as authored by the user. Command strings are split into
-* argv and invoked with the matched file paths appended. `{ command, … }`
-* objects do the same with per-task execution options (cwd / perPackage).
-* Arrays run serially. Functions receive the matched paths and return
-* further task values (possibly async). `{ title, task }` objects run
-* `task` directly with no argv construction.
-*/
+ * A task value as authored by the user. Command strings are split into
+ * argv and invoked with the matched file paths appended. `{ command, … }`
+ * objects do the same with per-task execution options (cwd / perPackage).
+ * Arrays run serially. Functions receive the matched paths and return
+ * further task values (possibly async). `{ title, task }` objects run
+ * `task` directly with no argv construction.
+ */
 type StagedTask = CommandTask | CustomTask | StagedTaskFunction | string | ReadonlyArray<CommandTask | CustomTask | StagedTaskFunction | string>;
 type StagedTaskFunction = (files: string[]) => Promise<StagedTaskResult> | StagedTaskResult;
 type StagedTaskResult = CommandTask | CustomTask | string | ReadonlyArray<CommandTask | CustomTask | string>;
 /**
-* Config object mapping glob patterns (basename or path-style) to tasks.
-* A top-level function form lets the user generate the entire config
-* from the staged file list.
-*/
+ * Config object mapping glob patterns (basename or path-style) to tasks.
+ * A top-level function form lets the user generate the entire config
+ * from the staged file list.
+ */
 type StagedConfig = Readonly<Record<string, StagedTask>> | StagedConfigFunction;
 type StagedConfigFunction = (files: string[]) => Promise<Record<string, StagedTask>> | Record<string, StagedTask>;
 /**
-* Configuration block declared on a target to mark it as a long-lived
-* "service" — eligible to be started/stopped via `vis service` and
-* auto-attached when other tasks depend on it.
-*
-* Targets must also carry `preset: "server"` (or the equivalent
-* `persistent: true`) for the service-mode lifecycle to apply.
-*/
+ * Configuration block declared on a target to mark it as a long-lived
+ * "service" — eligible to be started/stopped via `vis service` and
+ * auto-attached when other tasks depend on it.
+ *
+ * Targets must also carry `preset: "server"` (or the equivalent
+ * `persistent: true`) for the service-mode lifecycle to apply.
+ */
 interface ServiceConfig {
   /**
-  * Env vars to expose to dependent tasks when this service is
-  * registered. Merged into the dependent task's env after the task's
-  * own envFile and before the task's explicit `env` overrides — the
-  * dependent task wins on key collisions.
-  *
-  * Note: only this `env` map propagates to dependents. The service
-  * target's own `envFile` is loaded into the **service process** at
-  * start time but is *not* forwarded — dependents must declare any
-  * shared values they need either here or in their own envFile. This
-  * boundary is intentional: envFiles often contain operator-only
-  * secrets (deploy keys, admin tokens) that should not leak into
-  * downstream test commands.
-  */
+   * Env vars to expose to dependent tasks when this service is
+   * registered. Merged into the dependent task's env after the task's
+   * own envFile and before the task's explicit `env` overrides — the
+   * dependent task wins on key collisions.
+   *
+   * Note: only this `env` map propagates to dependents. The service
+   * target's own `envFile` is loaded into the **service process** at
+   * start time but is *not* forwarded — dependents must declare any
+   * shared values they need either here or in their own envFile. This
+   * boundary is intentional: envFiles often contain operator-only
+   * secrets (deploy keys, admin tokens) that should not leak into
+   * downstream test commands.
+   */
   env?: Record<string, string>;
   /**
-  * Grace period in milliseconds between SIGTERM and SIGKILL when the
-  * service is stopped.
-  * @default 5000
-  */
+   * Grace period in milliseconds between SIGTERM and SIGKILL when the
+   * service is stopped.
+   * @default 5000
+   */
   killGracePeriodMs?: number;
   /**
-  * Optional port the service listens on. Used as the default for
-  * `readiness.tcp.port` when no explicit probe is configured, and
-  * surfaced by `vis service list`.
-  */
+   * Optional port the service listens on. Used as the default for
+   * `readiness.tcp.port` when no explicit probe is configured, and
+   * surfaced by `vis service list`.
+   */
   port?: number;
   /** Readiness probe configuration. v1 supports TCP only. */
   readiness?: {
@@ -149,9 +149,9 @@ interface ServiceConfig {
   };
 }
 /**
-* Persisted registry entry. One JSON file per running service in
-* `~/.vis-services/&lt;workspaceHash>/&lt;slug>.json`.
-*/
+ * Persisted registry entry. One JSON file per running service in
+ * `~/.vis-services/&lt;workspaceHash>/&lt;slug>.json`.
+ */
 interface ServiceEntry {
   /** Resolved command actually spawned. Used for stale-PID detection. */
   command: string;
@@ -159,10 +159,10 @@ interface ServiceEntry {
   config: ServiceConfig;
   cwd: string;
   /**
-  * Env vars to forward to dependents. Resolved at start time —
-  * defaults to `config.env`, but a future `--env-from` flag could
-  * extend this without touching the registry consumer.
-  */
+   * Env vars to forward to dependents. Resolved at start time —
+   * defaults to `config.env`, but a future `--env-from` flag could
+   * extend this without touching the registry consumer.
+   */
   env: Record<string, string>;
   /** Target id, e.g. `apps/api:db`. */
   id: string;
@@ -170,28 +170,28 @@ interface ServiceEntry {
   logFile: string;
   pid: number;
   /**
-  * Filesystem-safe slug of `id`. `apps/api:db` → `apps_api__db`.
-  * Used as the entry's filename so registry reads can map slug → entry.
-  */
+   * Filesystem-safe slug of `id`. `apps/api:db` → `apps_api__db`.
+   * Used as the entry's filename so registry reads can map slug → entry.
+   */
   slug: string;
   /** ISO 8601 timestamp of when the service was started. */
   startedAt: string;
   /**
-  * vis version that started this service. Auto-attach refuses entries
-  * from a mismatched version — protects against schema drift.
-  */
+   * vis version that started this service. Auto-attach refuses entries
+   * from a mismatched version — protects against schema drift.
+   */
   visVersion: string;
 }
 /**
-* First-class task arguments: a declarative schema per target that lets a
-* task define its named/positional arguments, validate what the user passes
-* on the CLI, and render a per-task `--help`. The validated values are also
-* exposed to the command as `VIS_ARG_&lt;NAME>` environment variables so the
-* underlying script can read them without re-parsing argv.
-*
-* This module is intentionally pure (no IO) so it is trivially unit-testable;
-* the run handler wires it to the forwarded-args vector and the task env.
-*/
+ * First-class task arguments: a declarative schema per target that lets a
+ * task define its named/positional arguments, validate what the user passes
+ * on the CLI, and render a per-task `--help`. The validated values are also
+ * exposed to the command as `VIS_ARG_&lt;NAME>` environment variables so the
+ * underlying script can read them without re-parsing argv.
+ *
+ * This module is intentionally pure (no IO) so it is trivially unit-testable;
+ * the run handler wires it to the forwarded-args vector and the task env.
+ */
 /** Value type a {@link TaskArgument} coerces to and validates against. */
 type TaskArgumentType = "boolean" | "enum" | "number" | "string";
 /** A coerced task-argument value. */
@@ -199,31 +199,31 @@ type TaskArgumentValue = boolean | number | string;
 /** A single declared argument for a task target. */
 interface TaskArgument {
   /**
-  * Short single-character alias (e.g. `r` for `--reporter`, used as `-r`).
-  * Must be exactly one character — enforced at run time by
-  * {@link validateArgumentSchema}.
-  */
+   * Short single-character alias (e.g. `r` for `--reporter`, used as `-r`).
+   * Must be exactly one character — enforced at run time by
+   * {@link validateArgumentSchema}.
+   */
   alias?: string;
   /**
-  * Allowed values when {@link TaskArgument.type} is `"enum"`. Must be
-  * non-empty (and is required) for `enum` — enforced at run time by
-  * {@link validateArgumentSchema}.
-  */
+   * Allowed values when {@link TaskArgument.type} is `"enum"`. Must be
+   * non-empty (and is required) for `enum` — enforced at run time by
+   * {@link validateArgumentSchema}.
+   */
   choices?: string[];
   /** Value applied when the argument is omitted. Skips the required check. */
   default?: TaskArgumentValue;
   /** One-line help text surfaced by per-task `--help`. */
   description?: string;
   /**
-  * Canonical name, without the leading `--` (kebab-case by convention).
-  * Must start with a letter and contain only letters, digits, `-`, `_` —
-  * enforced at run time by {@link validateArgumentSchema}.
-  */
+   * Canonical name, without the leading `--` (kebab-case by convention).
+   * Must start with a letter and contain only letters, digits, `-`, `_` —
+   * enforced at run time by {@link validateArgumentSchema}.
+   */
   name: string;
   /**
-  * Consume the value from the next free positional argument instead of a
-  * `--flag`. Positional args are filled in declaration order.
-  */
+   * Consume the value from the next free positional argument instead of a
+   * `--flag`. Positional args are filled in declaration order.
+   */
   positional?: boolean;
   /** Fail the task when the argument is absent and has no `default`. */
   required?: boolean;
@@ -231,269 +231,269 @@ interface TaskArgument {
   type?: TaskArgumentType;
 }
 /**
-* Semantic classification for a target.
-* - `build`: Generates one or more artifacts; cached by default.
-* - `test`: Validation task (lint, typecheck, unit test). Default type.
-* - `run`: One-off or long-running process. Not cached by default.
-*/
+ * Semantic classification for a target.
+ * - `build`: Generates one or more artifacts; cached by default.
+ * - `test`: Validation task (lint, typecheck, unit test). Default type.
+ * - `run`: One-off or long-running process. Not cached by default.
+ */
 type TargetType = "build" | "run" | "test";
 /**
-* Preset bundles of target options.
-* - `server`: Long-running local dev server — caching off, not in CI,
-*   interactive, persistent.
-* - `utility`: Short-lived helper — caching off, not in CI.
-*/
+ * Preset bundles of target options.
+ * - `server`: Long-running local dev server — caching off, not in CI,
+ *   interactive, persistent.
+ * - `utility`: Short-lived helper — caching off, not in CI.
+ */
 type TargetPreset = "server" | "utility";
 /**
-* Controls whether a target runs in CI.
-* - `true` (default): Always run.
-* - `false`: Never run in CI (local-only).
-* - `"affected"`: Only when the project is affected by the current change set.
-* - `"always"`: Always run, even if unaffected.
-*/
+ * Controls whether a target runs in CI.
+ * - `true` (default): Always run.
+ * - `false`: Never run in CI (local-only).
+ * - `"affected"`: Only when the project is affected by the current change set.
+ * - `"always"`: Always run, even if unaffected.
+ */
 type RunInCI = "affected" | "always" | boolean;
 /**
-* Controls how affected files are forwarded to a task.
-* - `false` (default): Do not forward.
-* - `"args"`: Append affected paths as additional command arguments.
-* - `"env"`: Expose them via `VIS_AFFECTED_FILES` environment variable.
-* - `"both"`: Both of the above.
-*/
+ * Controls how affected files are forwarded to a task.
+ * - `false` (default): Do not forward.
+ * - `"args"`: Append affected paths as additional command arguments.
+ * - `"env"`: Expose them via `VIS_AFFECTED_FILES` environment variable.
+ * - `"both"`: Both of the above.
+ */
 type AffectedFilesMode = "args" | "both" | "env" | false;
 /**
-* Vis-specific target options that extend the task-runner's
-* base `TargetConfiguration`. These live under `target.options` and are
-* interpreted by vis before handing the task off to task-runner.
-*
-* Conditional execution (`when:`) and finally tasks (`always:`) live at
-* the target top level, not under `options` — they're handled by the
-* task-runner orchestrator. See `@visulima/task-runner`'s `WhenCondition`.
-*/
+ * Vis-specific target options that extend the task-runner's
+ * base `TargetConfiguration`. These live under `target.options` and are
+ * interpreted by vis before handing the task off to task-runner.
+ *
+ * Conditional execution (`when:`) and finally tasks (`always:`) live at
+ * the target top level, not under `options` — they're handled by the
+ * task-runner orchestrator. See `@visulima/task-runner`'s `WhenCondition`.
+ */
 interface VisTargetOptions {
   /**
-  * How to forward affected files to the task process.
-  * Only used when invoked via `vis affected &lt;target>`.
-  * @default false
-  */
+   * How to forward affected files to the task process.
+   * Only used when invoked via `vis affected &lt;target>`.
+   * @default false
+   */
   affectedFiles?: AffectedFilesMode;
   /**
-  * Load environment variables from dotenv file(s) before running.
-  * - `string`: a single file path (relative to project root).
-  * - `string[]`: multiple files — later entries override earlier ones,
-  *   so put more-specific files last (e.g. `[".env", ".env.local"]`).
-  * - `true`: auto-cascade in the Next/Vite order:
-  *   `.env` → `.env.{NODE_ENV}` → `.env.local` → `.env.{NODE_ENV}.local`.
-  *   Skips `.env.local` when NODE_ENV is `test`, matching Next.js.
-  */
+   * Load environment variables from dotenv file(s) before running.
+   * - `string`: a single file path (relative to project root).
+   * - `string[]`: multiple files — later entries override earlier ones,
+   *   so put more-specific files last (e.g. `[".env", ".env.local"]`).
+   * - `true`: auto-cascade in the Next/Vite order:
+   *   `.env` → `.env.{NODE_ENV}` → `.env.local` → `.env.{NODE_ENV}.local`.
+   *   Skips `.env.local` when NODE_ENV is `test`, matching Next.js.
+   */
   envFile?: boolean | string | string[];
   /**
-  * When true, the task is serialized with respect to parallel execution
-  * and must be run on the main process (claims stdin). Used for commands
-  * that read from the terminal.
-  * @default false
-  */
+   * When true, the task is serialized with respect to parallel execution
+   * and must be run on the main process (claims stdin). Used for commands
+   * that read from the terminal.
+   * @default false
+   */
   interactive?: boolean;
   /**
-  * When true, the task is hidden from CLI listings and can only be invoked
-  * as a dependency of another task.
-  * @default false
-  */
+   * When true, the task is hidden from CLI listings and can only be invoked
+   * as a dependency of another task.
+   * @default false
+   */
   internal?: boolean;
   /**
-  * Milliseconds the timeout watchdog waits between sending SIGTERM
-  * and SIGKILL when the `timeout` budget fires. Tasks that ignore
-  * SIGTERM (e.g. test runners holding open child processes) get
-  * force-killed after this grace window so a stuck task can't outlive
-  * its budget.
-  *
-  * Set to `0` to skip escalation and rely on SIGTERM only.
-  * @default 5000
-  */
+   * Milliseconds the timeout watchdog waits between sending SIGTERM
+   * and SIGKILL when the `timeout` budget fires. Tasks that ignore
+   * SIGTERM (e.g. test runners holding open child processes) get
+   * force-killed after this grace window so a stuck task can't outlive
+   * its budget.
+   *
+   * Set to `0` to skip escalation and rely on SIGTERM only.
+   * @default 5000
+   */
   killGracePeriodMs?: number;
   /**
-  * Serializes all tasks that share the same mutex name. Useful for tasks
-  * that contend on a shared resource (e.g., a database migration).
-  */
+   * Serializes all tasks that share the same mutex name. Useful for tasks
+   * that contend on a shared resource (e.g., a database migration).
+   */
   mutex?: string;
   /**
-  * Per-target output verbosity. Overrides the global `--output-style`
-  * flag for this specific target.
-  *
-  * - `"normal"` (default): print every task's terminal output
-  * - `"quiet"`: only print output when the task fails. Successful
-  *   and cached tasks contribute their status line and timing, but
-  *   their captured stdout/stderr is suppressed.
-  *
-  * Useful when a routinely-noisy task (a linter or test runner with
-  * verbose progress output) should stay quiet during green builds
-  * but reveal everything when it fails.
-  */
+   * Per-target output verbosity. Overrides the global `--output-style`
+   * flag for this specific target.
+   *
+   * - `"normal"` (default): print every task's terminal output
+   * - `"quiet"`: only print output when the task fails. Successful
+   *   and cached tasks contribute their status line and timing, but
+   *   their captured stdout/stderr is suppressed.
+   *
+   * Useful when a routinely-noisy task (a linter or test runner with
+   * verbose progress output) should stay quiet during green builds
+   * but reveal everything when it fails.
+   */
   outputStyle?: "normal" | "quiet";
   /**
-  * When true, the task is a long-running / never-ending process.
-  * Persistent tasks are scheduled last, execute after all cacheable
-  * tasks complete, and are never cached.
-  * @default false
-  */
+   * When true, the task is a long-running / never-ending process.
+   * Persistent tasks are scheduled last, execute after all cacheable
+   * tasks complete, and are never cached.
+   * @default false
+   */
   persistent?: boolean;
   /**
-  * A preset that pre-fills a common bundle of options.
-  * User-provided fields always take precedence over the preset.
-  */
+   * A preset that pre-fills a common bundle of options.
+   * User-provided fields always take precedence over the preset.
+   */
   preset?: TargetPreset;
   /**
-  * Run the task through a pseudo-terminal so color-aware tools
-  * (vitest, eslint, biome, …) render as if attached to a real TTY
-  * instead of a pipe. Output is captured via task-runner's
-  * `TerminalBuffer` so ANSI escapes are normalized into the final
-  * rendered state before reaching the reporter.
-  *
-  * Forces cache to off — PTY output can include timing-dependent
-  * frames (spinners) that aren't safe to replay from a cache.
-  * @default false
-  */
+   * Run the task through a pseudo-terminal so color-aware tools
+   * (vitest, eslint, biome, …) render as if attached to a real TTY
+   * instead of a pipe. Output is captured via task-runner's
+   * `TerminalBuffer` so ANSI escapes are normalized into the final
+   * rendered state before reaching the reporter.
+   *
+   * Forces cache to off — PTY output can include timing-dependent
+   * frames (spinners) that aren't safe to replay from a cache.
+   * @default false
+   */
   pty?: boolean;
   /**
-  * Number of times to retry the task on failure. Uses an exponential
-  * backoff by default (1s, 2s, 4s, ...).
-  * @default 0
-  */
+   * Number of times to retry the task on failure. Uses an exponential
+   * backoff by default (1s, 2s, 4s, ...).
+   * @default 0
+   */
   retryCount?: number;
   /**
-  * Delay between retry attempts in milliseconds, or `"exponential"`
-  * for 2^attempt * 1000 ms.
-  * @default "exponential"
-  */
+   * Delay between retry attempts in milliseconds, or `"exponential"`
+   * for 2^attempt * 1000 ms.
+   * @default "exponential"
+   */
   retryDelay?: number | "exponential";
   /**
-  * When true, the command executes with the workspace root as CWD
-  * instead of the project root.
-  * @default false
-  */
+   * When true, the command executes with the workspace root as CWD
+   * instead of the project root.
+   * @default false
+   */
   runFromWorkspaceRoot?: boolean;
   /**
-  * Controls whether the task runs in CI environments.
-  * @default true
-  */
+   * Controls whether the task runs in CI environments.
+   * @default true
+   */
   runInCI?: RunInCI;
   /**
-  * Capability tags that gate this task to runners advertising the
-  * same tag. The CLI's `--runner-tags=gpu,slow` flag (or
-  * `VIS_RUNNER_TAGS` env var) tells vis what the current runner
-  * supports; tasks whose `runnerTags` share at least one tag with
-  * the runner set are eligible. Untagged tasks (no `runnerTags` or
-  * an empty array) are general-purpose and always run.
-  *
-  * Use this for special-purpose CI lanes — e.g. a GPU runner that
-  * should only pick up visual-regression suites, or a nightly job
-  * that runs `slow` integration tests. When neither flag nor env
-  * is set, the filter is inactive and every task runs.
-  */
+   * Capability tags that gate this task to runners advertising the
+   * same tag. The CLI's `--runner-tags=gpu,slow` flag (or
+   * `VIS_RUNNER_TAGS` env var) tells vis what the current runner
+   * supports; tasks whose `runnerTags` share at least one tag with
+   * the runner set are eligible. Untagged tasks (no `runnerTags` or
+   * an empty array) are general-purpose and always run.
+   *
+   * Use this for special-purpose CI lanes — e.g. a GPU runner that
+   * should only pick up visual-regression suites, or a nightly job
+   * that runs `slow` integration tests. When neither flag nor env
+   * is set, the filter is inactive and every task runs.
+   */
   runnerTags?: string[];
   /**
-  * Marks this target as a long-lived service that can be started via
-  * `vis service start &lt;id>` and auto-attached when other tasks declare
-  * it in `dependsOn`. Implies persistent + non-cacheable behaviour
-  * (set `preset: "server"` to inherit the rest of the bundle).
-  *
-  * The presence of this block — not `preset: "server"` alone — is
-  * what makes a target eligible for the cross-invocation registry.
-  * `preset: "server"` without `service` keeps today's in-run-only
-  * behaviour.
-  */
+   * Marks this target as a long-lived service that can be started via
+   * `vis service start &lt;id>` and auto-attached when other tasks declare
+   * it in `dependsOn`. Implies persistent + non-cacheable behaviour
+   * (set `preset: "server"` to inherit the rest of the bundle).
+   *
+   * The presence of this block — not `preset: "server"` alone — is
+   * what makes a target eligible for the cross-invocation registry.
+   * `preset: "server"` without `service` keeps today's in-run-only
+   * behaviour.
+   */
   service?: ServiceConfig;
   /**
-  * Per-target shell override. When set, the command runs through this
-  * shell instead of the platform default.
-  */
+   * Per-target shell override. When set, the command runs through this
+   * shell instead of the platform default.
+   */
   shell?: string;
   /**
-  * Arguments passed to the per-target shell/interpreter before the command
-  * string. Defaults to `["-c"]` (POSIX shells, pwsh). Set this to run the
-  * command under an interpreter that uses a different flag — e.g.
-  * `shell: "node", shellArgs: ["-e"]` runs the command as inline JS
-  * ("script mode"), or `shellArgs: ["-lc"]` for a login shell. Only applies
-  * when `shell`/`unixShell`/`windowsShell` resolves to a custom shell.
-  *
-  * Must be non-empty when set — an empty array would drop the interpreter
-  * flag entirely, so the runtime falls back to `-c` defensively.
-  */
+   * Arguments passed to the per-target shell/interpreter before the command
+   * string. Defaults to `["-c"]` (POSIX shells, pwsh). Set this to run the
+   * command under an interpreter that uses a different flag — e.g.
+   * `shell: "node", shellArgs: ["-e"]` runs the command as inline JS
+   * ("script mode"), or `shellArgs: ["-lc"]` for a login shell. Only applies
+   * when `shell`/`unixShell`/`windowsShell` resolves to a custom shell.
+   *
+   * Must be non-empty when set — an empty array would drop the interpreter
+   * flag entirely, so the runtime falls back to `-c` defensively.
+   */
   shellArgs?: string[];
   /**
-  * Override the workspace `strictEnv` setting for this target. When
-  * truthy, the target fails if its command references an env var
-  * that resolves to neither the task's effective env nor
-  * `process.env`. When `false`, the target opts out of a workspace
-  * `strictEnv: true` (e.g. for a one-off command that legitimately
-  * tolerates an unset variable).
-  * @see VisConfig.strictEnv
-  */
+   * Override the workspace `strictEnv` setting for this target. When
+   * truthy, the target fails if its command references an env var
+   * that resolves to neither the task's effective env nor
+   * `process.env`. When `false`, the target opts out of a workspace
+   * `strictEnv: true` (e.g. for a one-off command that legitimately
+   * tolerates an unset variable).
+   * @see VisConfig.strictEnv
+   */
   strictEnv?: boolean;
   /**
-  * Maximum wall-clock milliseconds a single task run is allowed to
-  * take before being killed. `0` / `undefined` means no timeout.
-  *
-  * When the timeout fires the task is sent SIGTERM and, if it has
-  * not exited within `killGracePeriodMs`, SIGKILL. The task exits
-  * with a failure status carrying the `[timeout]` marker in
-  * `terminalOutput`. Retries count per-attempt, not cumulatively.
-  *
-  * Use this to prevent runaway tasks from eating CI wall-clock time
-  * up to the job-level cutoff.
-  */
+   * Maximum wall-clock milliseconds a single task run is allowed to
+   * take before being killed. `0` / `undefined` means no timeout.
+   *
+   * When the timeout fires the task is sent SIGTERM and, if it has
+   * not exited within `killGracePeriodMs`, SIGKILL. The task exits
+   * with a failure status carrying the `[timeout]` marker in
+   * `terminalOutput`. Retries count per-attempt, not cumulatively.
+   *
+   * Use this to prevent runaway tasks from eating CI wall-clock time
+   * up to the job-level cutoff.
+   */
   timeout?: number;
   /**
-  * Per-target unix shell override, used on Linux and macOS.
-  * Takes precedence over `shell` on unix-like systems.
-  */
+   * Per-target unix shell override, used on Linux and macOS.
+   * Takes precedence over `shell` on unix-like systems.
+   */
   unixShell?: string;
   /**
-  * Per-target windows shell override, used on Windows.
-  * Takes precedence over `shell` on Windows.
-  */
+   * Per-target windows shell override, used on Windows.
+   * Takes precedence over `shell` on Windows.
+   */
   windowsShell?: string;
 }
 /**
-* An extended target configuration that adds the vis-specific options
-* on top of task-runner's `TargetConfiguration`.
-*/
+ * An extended target configuration that adds the vis-specific options
+ * on top of task-runner's `TargetConfiguration`.
+ */
 interface VisTargetConfiguration extends Omit<TargetConfiguration, "options"> {
   /**
-  * Alternate names that resolve to this target on the CLI. Useful
-  * for shortening long canonical names (`test` ↔ `t`) or for
-  * offering migration-friendly aliases when renaming targets.
-  * Aliases must be globally unique within the workspace.
-  */
+   * Alternate names that resolve to this target on the CLI. Useful
+   * for shortening long canonical names (`test` ↔ `t`) or for
+   * offering migration-friendly aliases when renaming targets.
+   * Aliases must be globally unique within the workspace.
+   */
   aliases?: string[];
   /**
-  * Declarative argument schema for this target. Forwarded CLI args
-  * (`vis run &lt;target> -- --flag value`) are validated against it, surfaced
-  * by per-task `--help`, and exposed to the command as `VIS_ARG_&lt;NAME>`
-  * environment variables.
-  */
+   * Declarative argument schema for this target. Forwarded CLI args
+   * (`vis run &lt;target> -- --flag value`) are validated against it, surfaced
+   * by per-task `--help`, and exposed to the command as `VIS_ARG_&lt;NAME>`
+   * environment variables.
+   */
   arguments?: TaskArgument[];
   /**
-  * One-line description surfaced by `vis list` and per-task `--help`.
-  * Kept short — longer docs belong in project READMEs or
-  * vis.config.ts comments.
-  */
+   * One-line description surfaced by `vis list` and per-task `--help`.
+   * Kept short — longer docs belong in project READMEs or
+   * vis.config.ts comments.
+   */
   description?: string;
   /**
-  * True when the target was synthesized by a Project Crystal-style
-  * detector (see {@link ../inference}) rather than declared by a
-  * package.json script, project.json, or vis.task.ts file. Surfaced
-  * by `vis list --inferred` and used by tooling to distinguish
-  * implicit defaults from explicit user intent.
-  */
+   * True when the target was synthesized by a Project Crystal-style
+   * detector (see {@link ../inference}) rather than declared by a
+   * package.json script, project.json, or vis.task.ts file. Surfaced
+   * by `vis list --inferred` and used by tooling to distinguish
+   * implicit defaults from explicit user intent.
+   */
   inferred?: boolean;
   /** Vis-specific target options. */
   options?: VisTargetOptions;
   /** Preset applied before user-specified options. */
   preset?: TargetPreset;
   /**
-  * Semantic task type. Affects caching defaults and CI filtering.
-  * @default "test"
-  */
+   * Semantic task type. Affects caching defaults and CI filtering.
+   * @default "test"
+   */
   type?: TargetType;
 }
 type HookCallback = (...arguments_: any) => Promise<void> | void;
@@ -504,20 +504,20 @@ type DeprecatedHook<T> = {
 };
 type ValueOf<C> = C extends Record<any, any> ? C[keyof C] : never;
 type Strings<T> = Exclude<keyof T, number | symbol>;
-type KnownKeys<T> = keyof { [K in keyof T as string extends K ? never : number extends K ? never : K]: never };
+type KnownKeys<T> = keyof { [K in keyof T as string extends K ? never : number extends K ? never : K]: never; };
 type StripGeneric<T> = Pick<T, KnownKeys<T> extends keyof T ? KnownKeys<T> : never>;
 type OnlyGeneric<T> = Omit<T, KnownKeys<T> extends keyof T ? KnownKeys<T> : never>;
-type Namespaces<T> = ValueOf<{ [key in Strings<T>]: key extends `${infer Namespace}:${string}` ? Namespace : never }>;
-type BareHooks<T> = ValueOf<{ [key in Strings<T>]: key extends `${string}:${string}` ? never : key }>;
-type HooksInNamespace<T, Namespace extends string> = ValueOf<{ [key in Strings<T>]: key extends `${Namespace}:${infer HookName}` ? HookName : never }>;
-type WithoutNamespace<T, Namespace extends string> = { [key in HooksInNamespace<T, Namespace>]: `${Namespace}:${key}` extends keyof T ? T[`${Namespace}:${key}`] : never };
-type NestedHooks<T> = (Partial<StripGeneric<T>> | Partial<OnlyGeneric<T>>) & Partial<{ [key in Namespaces<StripGeneric<T>>]: NestedHooks<WithoutNamespace<T, key>> }> & Partial<{ [key in BareHooks<StripGeneric<T>>]: T[key] }>;
+type Namespaces<T> = ValueOf<{ [key in Strings<T>]: key extends `${infer Namespace}:${string}` ? Namespace : never; }>;
+type BareHooks<T> = ValueOf<{ [key in Strings<T>]: key extends `${string}:${string}` ? never : key; }>;
+type HooksInNamespace<T, Namespace extends string> = ValueOf<{ [key in Strings<T>]: key extends `${Namespace}:${infer HookName}` ? HookName : never; }>;
+type WithoutNamespace<T, Namespace extends string> = { [key in HooksInNamespace<T, Namespace>]: `${Namespace}:${key}` extends keyof T ? T[`${Namespace}:${key}`] : never; };
+type NestedHooks<T> = (Partial<StripGeneric<T>> | Partial<OnlyGeneric<T>>) & Partial<{ [key in Namespaces<StripGeneric<T>>]: NestedHooks<WithoutNamespace<T, key>>; }> & Partial<{ [key in BareHooks<StripGeneric<T>>]: T[key]; }>;
 type InferCallback<HT, HN extends keyof HT> = HT[HN] extends HookCallback ? HT[HN] : never;
 type InferSpyEvent<HT extends Record<string, any>> = { [key in keyof HT]: {
   name: key;
   args: Parameters<HT[key]>;
   context: Record<string, any>;
-} }[keyof HT];
+}; }[keyof HT];
 declare class Hookable<HooksT extends Record<string, any> = Record<string, HookCallback>, HookNameT extends HookKeys<HooksT> = HookKeys<HooksT>> {
   private _hooks;
   private _before?;
@@ -550,172 +550,171 @@ declare global {
     createTask?: CreateTask;
   }
 }
-/** @deprecated */
 /**
-* Typed hook surface exposed to vis plugins.
-*
-* Plugins subscribe via `hooks.hook(name, handler)` — handlers are
-* awaited sequentially in registration order. Returning a promise
-* delays the next hook firing until it resolves, so plugins can
-* safely perform async setup/teardown.
-*
-* Naming deliberately mirrors vite-task / webpack-style verbs:
-*   before/after for boundaries, on&lt;Event> for passive observation.
-*/
+ * Typed hook surface exposed to vis plugins.
+ *
+ * Plugins subscribe via `hooks.hook(name, handler)` — handlers are
+ * awaited sequentially in registration order. Returning a promise
+ * delays the next hook firing until it resolves, so plugins can
+ * safely perform async setup/teardown.
+ *
+ * Naming deliberately mirrors vite-task / webpack-style verbs:
+ *   before/after for boundaries, on&lt;Event> for passive observation.
+ */
 interface VisHooks {
   /**
-  * Fired after the entire task graph completes (including any
-  * failures). `results` maps task ID → {@link TaskResult}.
-  */
+   * Fired after the entire task graph completes (including any
+   * failures). `results` maps task ID → {@link TaskResult}.
+   */
   "run:after": (results: Map<string, TaskResult>) => Promise<void> | void;
   /**
-  * Fired once before any task in the graph starts, after workspace
-  * discovery and graph construction. Throwing aborts the run.
-  */
+   * Fired once before any task in the graph starts, after workspace
+   * discovery and graph construction. Throwing aborts the run.
+   */
   "run:before": (context: {
     tasks: Task[];
     workspaceRoot: string;
   }) => Promise<void> | void;
   /**
-  * Fired after `vis run` auto-attaches to one or more registered
-  * services. `taskIds` lists the in-graph dependents that consumed
-  * the service's `env` block; an empty array means the service was
-  * registered but no kept task depended on it.
-  */
+   * Fired after `vis run` auto-attaches to one or more registered
+   * services. `taskIds` lists the in-graph dependents that consumed
+   * the service's `env` block; an empty array means the service was
+   * registered but no kept task depended on it.
+   */
   "service:attach": (entry: ServiceEntry, taskIds: ReadonlyArray<string>) => Promise<void> | void;
   /**
-  * Fired after a service is registered and its readiness probe
-  * succeeds. Sourced from both `vis service start` (and `restart`'s
-  * post-start phase) and any future programmatic call sites.
-  */
+   * Fired after a service is registered and its readiness probe
+   * succeeds. Sourced from both `vis service start` (and `restart`'s
+   * post-start phase) and any future programmatic call sites.
+   */
   "service:start": (entry: ServiceEntry) => Promise<void> | void;
   /**
-  * Fired after a registered service is stopped (SIGTERM/SIGKILL
-  * acknowledged, registry entry deleted). Not fired when stop is
-  * called against an unknown id — only when there was an alive
-  * entry to terminate.
-  */
+   * Fired after a registered service is stopped (SIGTERM/SIGKILL
+   * acknowledged, registry entry deleted). Not fired when stop is
+   * called against an unknown id — only when there was an alive
+   * entry to terminate.
+   */
   "service:stop": (entry: ServiceEntry) => Promise<void> | void;
   /**
-  * Fired after a task completes (success, failure, or cache hit).
-  * Receives the final {@link TaskResult}.
-  */
+   * Fired after a task completes (success, failure, or cache hit).
+   * Receives the final {@link TaskResult}.
+   */
   "task:after": (task: Task, result: TaskResult) => Promise<void> | void;
   /**
-  * Fired before each task begins execution — after scheduling, before
-  * the executor runs the command. Throwing aborts that single task.
-  */
+   * Fired before each task begins execution — after scheduling, before
+   * the executor runs the command. Throwing aborts that single task.
+   */
   "task:before": (task: Task) => Promise<void> | void;
   /** Fired when a task hit the local or remote cache. */
   "task:cacheHit": (task: Task, result: TaskResult) => Promise<void> | void;
   /**
-  * Fired when auto-fingerprint cache diagnostics reports a miss,
-  * carrying the human-readable reason string.
-  */
+   * Fired when auto-fingerprint cache diagnostics reports a miss,
+   * carrying the human-readable reason string.
+   */
   "task:cacheMiss": (task: Task, reasons: string) => Promise<void> | void;
   /** Fired when a task exits non-zero. */
   "task:failure": (task: Task, result: TaskResult) => Promise<void> | void;
   /**
-  * Fired during fingerprint construction, after built-in inputs are
-  * gathered and before the hash is sealed. Plugins call
-  * `contributor.contribute(key, value)` to mix arbitrary strings
-  * into the task hash — the hasher namespaces and sorts contributions
-  * deterministically so call order doesn't change the result.
-  *
-  * Throwing aborts hashing for the offending task and surfaces as a
-  * task failure before any cache lookup runs. Use this to guarantee
-  * a buggy plugin can't quietly poison cache state.
-  */
+   * Fired during fingerprint construction, after built-in inputs are
+   * gathered and before the hash is sealed. Plugins call
+   * `contributor.contribute(key, value)` to mix arbitrary strings
+   * into the task hash — the hasher namespaces and sorts contributions
+   * deterministically so call order doesn't change the result.
+   *
+   * Throwing aborts hashing for the offending task and surfaces as a
+   * task failure before any cache lookup runs. Use this to guarantee
+   * a buggy plugin can't quietly poison cache state.
+   */
   "task:fingerprint": (task: Task, contributor: FingerprintContributor) => Promise<void> | void;
   /**
-  * Fired right before a failed task is re-spawned by the retry
-  * controller. `attempt` is 1-indexed and counts the retry that's
-  * about to start (so the original failed run was attempt 0).
-  * `prevExitCode` is the failing exit status that triggered the
-  * retry (the full TaskResult isn't materialized at the retry
-  * boundary — only the per-attempt close event is available).
-  *
-  * Throwing aborts the retry; the previous failure becomes the final
-  * result.
-  */
+   * Fired right before a failed task is re-spawned by the retry
+   * controller. `attempt` is 1-indexed and counts the retry that's
+   * about to start (so the original failed run was attempt 0).
+   * `prevExitCode` is the failing exit status that triggered the
+   * retry (the full TaskResult isn't materialized at the retry
+   * boundary — only the per-attempt close event is available).
+   *
+   * Throwing aborts the retry; the previous failure becomes the final
+   * result.
+   */
   "task:retry": (task: Task, attempt: number, prevExitCode: number) => Promise<void> | void;
   /**
-  * Fired with a stderr chunk as a running task emits it. Plugins
-  * that ship logs live (Slack, Datadog) should prefer this over
-  * `task:after` so they don't wait for the full buffer.
-  */
+   * Fired with a stderr chunk as a running task emits it. Plugins
+   * that ship logs live (Slack, Datadog) should prefer this over
+   * `task:after` so they don't wait for the full buffer.
+   */
   "task:stderr": (task: Task, chunk: string) => Promise<void> | void;
   /**
-  * Fired with a stdout chunk as a running task emits it. See
-  * `task:stderr` for semantics.
-  */
+   * Fired with a stdout chunk as a running task emits it. See
+   * `task:stderr` for semantics.
+   */
   "task:stdout": (task: Task, chunk: string) => Promise<void> | void;
 }
 /**
-* Public plugin contract. Implementations register handlers by
-* returning a partial {@link VisHooks} map from `hooks`, or by
-* mutating the Hookable instance directly via `setup(hooks)` for
-* advanced cases (dynamic registration, removeHook, etc.).
-*
-* Plugins are loaded in the order they appear in `visConfig.plugins`.
-* Handler execution order within a hook follows registration order,
-* so earlier plugins see events first.
-*/
+ * Public plugin contract. Implementations register handlers by
+ * returning a partial {@link VisHooks} map from `hooks`, or by
+ * mutating the Hookable instance directly via `setup(hooks)` for
+ * advanced cases (dynamic registration, removeHook, etc.).
+ *
+ * Plugins are loaded in the order they appear in `visConfig.plugins`.
+ * Handler execution order within a hook follows registration order,
+ * so earlier plugins see events first.
+ */
 interface VisPlugin {
   /**
-  * Declarative handlers — the common shape. One entry per hook
-  * name; pass a function or an array of functions (all run serially
-  * in order).
-  */
-  hooks?: Partial<{ [K in keyof VisHooks]: VisHooks[K] | VisHooks[K][] }>;
+   * Declarative handlers — the common shape. One entry per hook
+   * name; pass a function or an array of functions (all run serially
+   * in order).
+   */
+  hooks?: Partial<{ [K in keyof VisHooks]: VisHooks[K] | VisHooks[K][]; }>;
   /** Plugin name — surfaced in debug logs. */
   name: string;
   /**
-  * Imperative setup — receives the shared Hookable instance so the
-  * plugin can register hooks conditionally, unregister later, or
-  * use advanced APIs like `hookOnce`/`beforeEach`/`afterEach`.
-  */
+   * Imperative setup — receives the shared Hookable instance so the
+   * plugin can register hooks conditionally, unregister later, or
+   * use advanced APIs like `hookOnce`/`beforeEach`/`afterEach`.
+   */
   setup?: (hooks: Hookable<VisHooks>) => Promise<void> | void;
 }
 /**
-* Per-adapter override applied by `vis lint` / `vis fmt`. Keyed by
-* adapter id under `lint.adapters` / `fmt.adapters`. Every field is
-* optional — set only what you need to change.
-*/
+ * Per-adapter override applied by `vis lint` / `vis fmt`. Keyed by
+ * adapter id under `lint.adapters` / `fmt.adapters`. Every field is
+ * optional — set only what you need to change.
+ */
 interface LintFmtAdapterOverride {
   /**
-  * Set to `false` to skip this adapter even when its config file or
-  * package.json entry is detected. Defaults to `true` (run when
-  * detected).
-  */
+   * Set to `false` to skip this adapter even when its config file or
+   * package.json entry is detected. Defaults to `true` (run when
+   * detected).
+   */
   enabled?: boolean;
   /**
-  * Extra arguments appended verbatim to every invocation of this
-  * adapter. Useful for tool-specific flags vis doesn't expose
-  * directly (e.g. `eslint --rulesdir`).
-  */
+   * Extra arguments appended verbatim to every invocation of this
+   * adapter. Useful for tool-specific flags vis doesn't expose
+   * directly (e.g. `eslint --rulesdir`).
+   */
   extraArgs?: string[];
 }
 /**
-* The 8 Socket.dev-style supply-chain policies. Used in `security.policies`
-* and `security.acceptedRisks[*].policies`. Kept as a const tuple so callers
-* can import the runtime array (`POLICY_NAMES`) for iteration without
-* drifting from the union type.
-*/
+ * The 8 Socket.dev-style supply-chain policies. Used in `security.policies`
+ * and `security.acceptedRisks[*].policies`. Kept as a const tuple so callers
+ * can import the runtime array (`POLICY_NAMES`) for iteration without
+ * drifting from the union type.
+ */
 declare const POLICY_NAMES: readonly ["firstSeen", "installScripts", "license", "malware", "publisherChange", "score", "unexpectedDeps", "vulnerability"];
 type PolicyName = (typeof POLICY_NAMES)[number];
 /**
-* Recognised input sources for the codeowners aggregator.
-*
-* - `project-json` — owners declared on each project's `project.json`.
-*   Canonical source; takes precedence over the other two on path conflicts.
-* - `nested-codeowners` — `CODEOWNERS` files placed at arbitrary depth
-*   in the workspace tree (excluding the generated root file).
-* - `package-json-maintainers` — fallback that reads each project's
-*   `package.json#maintainers` and emits one entry per project root for
-*   projects with no `project.json owners`. GitHub handles are extracted
-*   from each maintainer's `url` (e.g. `https://github.com/&lt;handle&gt;`).
-*/
+ * Recognised input sources for the codeowners aggregator.
+ *
+ * - `project-json` — owners declared on each project's `project.json`.
+ *   Canonical source; takes precedence over the other two on path conflicts.
+ * - `nested-codeowners` — `CODEOWNERS` files placed at arbitrary depth
+ *   in the workspace tree (excluding the generated root file).
+ * - `package-json-maintainers` — fallback that reads each project's
+ *   `package.json#maintainers` and emits one entry per project root for
+ *   projects with no `project.json owners`. GitHub handles are extracted
+ *   from each maintainer's `url` (e.g. `https://github.com/&lt;handle&gt;`).
+ */
 type CodeownersSource = "nested-codeowners" | "package-json-maintainers" | "project-json";
 interface CodeownersConfig {
   /** Markers that bracket the generated block when `preserveBlock` is set. */
@@ -730,52 +729,52 @@ interface CodeownersConfig {
   /** Sort order for generated entries — mirrors moon's `orderBy`. */
   orderBy?: "file-source" | "project-id";
   /**
-  * When set, the generated content is spliced between
-  * {@link CodeownersConfig.blockMarker} markers in the existing file
-  * (markers are appended if missing) instead of overwriting the file.
-  */
+   * When set, the generated content is spliced between
+   * {@link CodeownersConfig.blockMarker} markers in the existing file
+   * (markers are appended if missing) instead of overwriting the file.
+   */
   preserveBlock?: boolean;
   /** Provider determines whether `channel` is emitted (GitHub supports it via comment). */
   provider?: "bitbucket" | "github" | "gitlab" | "other";
   /**
-  * Header instruction shown to reviewers. Replaces the default
-  * "Update each project's project.json `owners` field…" line. Useful
-  * when the canonical regenerate path is a custom script.
-  */
+   * Header instruction shown to reviewers. Replaces the default
+   * "Update each project's project.json `owners` field…" line. Useful
+   * when the canonical regenerate path is a custom script.
+   */
   regenerationCommand?: string;
   /** Enabled input sources. Defaults to `["project-json"]`. */
   sources?: CodeownersSource[];
 }
 /**
-* One user-declared customTypes entry. See `policy.customTypes.extraTypes`
-* for the full contract — this is just the row shape.
-*/
+ * One user-declared customTypes entry. See `policy.customTypes.extraTypes`
+ * for the full contract — this is just the row shape.
+ */
 interface ExtraCustomType {
   /**
-  * Required when `strategy === "string"`. The dep-cluster key the bare
-  * version string at `path` should be associated with.
-  */
+   * Required when `strategy === "string"`. The dep-cluster key the bare
+   * version string at `path` should be associated with.
+   */
   depName?: string;
   /**
-  * Display name for this customType. Used as the cluster key prefix in
-  * lint output and JSON. Must not collide with the built-in names.
-  */
+   * Display name for this customType. Used as the cluster key prefix in
+   * lint output and JSON. Must not collide with the built-in names.
+   */
   name: string;
   /** Dot-separated walk into package.json (e.g. `pnpm.overrides`, `myTool.runtime`). */
   path: string;
   /**
-  * How to interpret the JSON found at `path`.
-  * - `name@version` — single string `pnpm@9.0.0` (with optional `+sha512.…` hash).
-  * - `name~version` — single string `node~20.0.0`, mirrors syncpack's tilde form.
-  * - `string` — bare version literal (requires `depName`).
-  * - `versionsByName` — `{ name: version }` object such as `engines`.
-  */
+   * How to interpret the JSON found at `path`.
+   * - `name@version` — single string `pnpm@9.0.0` (with optional `+sha512.…` hash).
+   * - `name~version` — single string `node~20.0.0`, mirrors syncpack's tilde form.
+   * - `string` — bare version literal (requires `depName`).
+   * - `versionsByName` — `{ name: version }` object such as `engines`.
+   */
   strategy: "name@version" | "name~version" | "string" | "versionsByName";
 }
 /**
-* Declared code-owner assignment for a path glob within a project.
-* Mirrors moon's `owners` shape so migrations can round-trip cleanly.
-*/
+ * Declared code-owner assignment for a path glob within a project.
+ * Mirrors moon's `owners` shape so migrations can round-trip cleanly.
+ */
 interface OwnersEntry {
   /** Optional notification channel (e.g. Slack, Teams). */
   channel?: string;
@@ -785,38 +784,47 @@ interface OwnersEntry {
   path: string;
 }
 /**
-* Per-project TypeScript overlay loaded from `vis.task.ts`. Adds a
-* dynamic, type-safe layer for target overrides on top of `project.json`,
-* which stays the canonical home for static metadata (`tags`, `layer`,
-* `stack`, `language`, `owners`, `projectType`, `sourceRoot`,
-* `implicitDependencies`).
-*
-* `vis.task.ts` is opt-in. A package without one behaves identically to
-* before its introduction. Targets defined here merge over `project.json`'s
-* `targets` block — see `design-config-layering.md` for the full
-* precedence stack.
-*/
+ * Per-project TypeScript overlay loaded from `vis.task.ts`. Adds a
+ * dynamic, type-safe layer for target overrides on top of `project.json`,
+ * which stays the canonical home for static metadata (`tags`, `layer`,
+ * `stack`, `language`, `owners`, `projectType`, `sourceRoot`,
+ * `implicitDependencies`).
+ *
+ * `vis.task.ts` is opt-in. A package without one behaves identically to
+ * before its introduction. Targets defined here merge over `project.json`'s
+ * `targets` block — see `design-config-layering.md` for the full
+ * precedence stack.
+ */
 interface VisTaskConfig {
   /** Per-target overrides — same shape as `project.json#targets`. */
   tasks?: Record<string, VisTargetConfiguration>;
 }
 /**
-* Per-project metadata surfaced by `project.json`. Extended beyond the
-* minimal `projectType` / `tags` / `sourceRoot` fields we historically
-* parsed to include targets, owners, and layer/stack classification.
-*/
+ * Per-project metadata surfaced by `project.json`. Extended beyond the
+ * minimal `projectType` / `tags` / `sourceRoot` fields we historically
+ * parsed to include targets, owners, and layer/stack classification.
+ */
 interface ProjectJson {
   /** Implicit dependencies on other projects. */
   implicitDependencies?: string[];
   /** Primary language — informational and query-able. */
   language?: string;
-  /** Project layer, used for constraint inheritance and query filtering. */
+  /**
+   * Architectural layer this project sits in. Purely declarative — set
+   * it here in `project.json` and nothing infers it, which is why the
+   * `Layer` column in `vis list` reads `—` until you do.
+   *
+   * Once set it becomes queryable (`--query "layer=library"`) and feeds
+   * `constraints`, where it is the natural way to express rules like
+   * "nothing in `library` may depend on an `application`".
+   * @example "library"
+   */
   layer?: "application" | "automation" | "configuration" | "library" | "scaffolding" | "tool";
   /**
-  * Project name. When set, takes precedence over `package.json#name`
-  * as the project's identity in the workspace graph and CLI filters.
-  * Falls back to `package.json#name` when omitted.
-  */
+   * Project name. When set, takes precedence over `package.json#name`
+   * as the project's identity in the workspace graph and CLI filters.
+   * Falls back to `package.json#name` when omitted.
+   */
   name?: string;
   /** Code owners for paths inside this project. */
   owners?: OwnersEntry[];
@@ -829,19 +837,19 @@ interface ProjectJson {
     title?: string;
   };
   /**
-  * Project type — `library`, `application`, `service`, or `tool`.
-  *
-  * - `library` — reusable code consumed by other workspace projects.
-  * - `application` — end-user-facing build target (web app, mobile app).
-  * - `service` — long-running HTTP / worker process deployed independently.
-  * - `tool` — CLI or developer tooling shipped as an executable.
-  */
+   * Project type — `library`, `application`, `service`, or `tool`.
+   *
+   * - `library` — reusable code consumed by other workspace projects.
+   * - `application` — end-user-facing build target (web app, mobile app).
+   * - `service` — long-running HTTP / worker process deployed independently.
+   * - `tool` — CLI or developer tooling shipped as an executable.
+   */
   projectType?: "application" | "library" | "service" | "tool";
   /**
-  * Marks the project as write-restricted. Consumed by
-  * `vis sync codeowners --write-guard` to scope the generated
-  * Write Guard workflow to this project's paths.
-  */
+   * Marks the project as write-restricted. Consumed by
+   * `vis sync codeowners --write-guard` to scope the generated
+   * Write Guard workflow to this project's paths.
+   */
   restricted?: boolean;
   /** Source root, used for display and language inference. */
   sourceRoot?: string;
@@ -853,9 +861,9 @@ interface ProjectJson {
   targets?: Record<string, VisTargetConfiguration>;
 }
 /**
-* A predicate used by {@link VisConfig.scopedTasks}.
-* All listed constraints must match for the block to apply.
-*/
+ * A predicate used by {@link VisConfig.scopedTasks}.
+ * All listed constraints must match for the block to apply.
+ */
 interface ScopedTasksMatch {
   /** Match on primary language. */
   language?: string | string[];
@@ -869,9 +877,9 @@ interface ScopedTasksMatch {
   tags?: string[];
 }
 /**
-* A single scoped-tasks block — a set of task defaults gated by an
-* optional match predicate.
-*/
+ * A single scoped-tasks block — a set of task defaults gated by an
+ * optional match predicate.
+ */
 interface ScopedTasksBlock {
   /** Optional match predicate; if omitted, the block applies universally. */
   match?: ScopedTasksMatch;
@@ -889,422 +897,422 @@ interface VisConfig {
     provider?: string;
   };
   /**
-  * Scope the task-runner cache directory by the current git branch.
-  * When `true`, caches are stored under `&lt;cacheDir>/branches/&lt;slug>`
-  * so `main` and feature branches stop thrashing each other —
-  * generated artefacts (schemas, `.d.ts` snapshots) that legitimately
-  * differ across branches no longer oscillate the cache contents.
-  *
-  * Falls back to the unscoped path on detached HEAD, non-git
-  * workspaces, or when git isn't available.
-  * @default false
-  */
+   * Scope the task-runner cache directory by the current git branch.
+   * When `true`, caches are stored under `&lt;cacheDir>/branches/&lt;slug>`
+   * so `main` and feature branches stop thrashing each other —
+   * generated artefacts (schemas, `.d.ts` snapshots) that legitimately
+   * differ across branches no longer oscillate the cache contents.
+   *
+   * Falls back to the unscoped path on detached HEAD, non-git
+   * workspaces, or when git isn't available.
+   * @default false
+   */
   branchScopedCache?: boolean;
   /**
-  * Code ownership configuration. Controls how `vis sync codeowners`
-  * renders the generated CODEOWNERS file.
-  */
+   * Code ownership configuration. Controls how `vis sync codeowners`
+   * renders the generated CODEOWNERS file.
+   */
   codeowners?: CodeownersConfig;
   /**
-  * Project dependency constraints.
-  * Enforced after building the project graph, before running tasks.
-  */
+   * Project dependency constraints.
+   * Enforced after building the project graph, before running tasks.
+   */
   constraints?: ConstraintsConfig;
   /**
-  * Configuration for the `vis create` scaffolding command.
-  * Controls template downloads (via giget), default options, and
-  * post-creation behavior.
-  */
+   * Configuration for the `vis create` scaffolding command.
+   * Controls template downloads (via giget), default options, and
+   * post-creation behavior.
+   */
   create?: {
     /**
-    * Authorization token for downloading private repository templates.
-    * Passed as Bearer token to the git host API.
-    * Can also be set via GIGET_AUTH, GITHUB_TOKEN, or GH_TOKEN environment variables.
-    */
+     * Authorization token for downloading private repository templates.
+     * Passed as Bearer token to the git host API.
+     * Can also be set via GIGET_AUTH, GITHUB_TOKEN, or GH_TOKEN environment variables.
+     */
     auth?: string;
     /**
-    * Default editor to configure after scaffolding.
-    * When set, `vis create` automatically generates editor config files.
-    * @example "vscode"
-    */
+     * Default editor to configure after scaffolding.
+     * When set, `vis create` automatically generates editor config files.
+     * @example "vscode"
+     */
     defaultEditor?: "vscode";
     /**
-    * Default package manager for new standalone projects.
-    * When set, skips the PM selection prompt in interactive mode.
-    */
+     * Default package manager for new standalone projects.
+     * When set, skips the PM selection prompt in interactive mode.
+     */
     defaultPm?: "bun" | "npm" | "pnpm" | "yarn";
     /**
-    * Default giget provider for `owner/repo` shorthand inputs.
-    * @default "github"
-    */
+     * Default giget provider for `owner/repo` shorthand inputs.
+     * @default "github"
+     */
     defaultProvider?: "bitbucket" | "github" | "gitlab" | "sourcehut";
     /**
-    * Initialize a git repository after scaffolding standalone projects.
-    * @default false
-    */
+     * Initialize a git repository after scaffolding standalone projects.
+     * @default false
+     */
     gitInit?: boolean;
     /**
-    * Install dependencies automatically after scaffolding.
-    * @default true
-    */
+     * Install dependencies automatically after scaffolding.
+     * @default true
+     */
     install?: boolean;
     /**
-    * Prefer locally cached templates over re-downloading.
-    * Useful for offline development or slow connections.
-    * @default false
-    */
+     * Prefer locally cached templates over re-downloading.
+     * Useful for offline development or slow connections.
+     * @default false
+     */
     preferOffline?: boolean;
     /**
-    * Custom template registry URL.
-    * When set, giget checks this registry for template metadata
-    * before falling back to direct provider resolution.
-    * Set to `false` to disable registry lookup entirely.
-    * @see https://github.com/unjs/giget#custom-registry
-    */
+     * Custom template registry URL.
+     * When set, giget checks this registry for template metadata
+     * before falling back to direct provider resolution.
+     * Set to `false` to disable registry lookup entirely.
+     * @see https://github.com/unjs/giget#custom-registry
+     */
     registry?: false | string;
     /**
-    * Named template aliases for quick access.
-    * Maps short names to full giget source strings.
-    * @example
-    * ```
-    * templates: {
-    *   "react": "github:vitejs/vite/packages/create-vite/template-react-ts",
-    *   "lib": "github:my-org/lib-template",
-    *   "internal": "gitlab:company/templates/node-service",
-    * }
-    * ```
-    */
+     * Named template aliases for quick access.
+     * Maps short names to full giget source strings.
+     * @example
+     * ```
+     * templates: {
+     *   "react": "github:vitejs/vite/packages/create-vite/template-react-ts",
+     *   "lib": "github:my-org/lib-template",
+     *   "internal": "gitlab:company/templates/node-service",
+     * }
+     * ```
+     */
     templates?: Record<string, string>;
   };
   /**
-  * Default base branch used by `vis affected`, `vis ci`, and `vis run --affected`
-  * when no explicit `--base` is passed and no CI smart-resolver fires.
-  *
-  * Resolved as `origin/&lt;defaultBase>` against the local clone; should be a
-  * branch name (not a fully-qualified ref) such as `main`, `master`, or `trunk`.
-  * Falls back to `main` when omitted.
-  *
-  * Migrated automatically from `nx.json#affected.defaultBase` /
-  * `nx.json#defaultBase` by `vis migrate nx`.
-  * @default "main"
-  */
+   * Default base branch used by `vis affected`, `vis ci`, and `vis run --affected`
+   * when no explicit `--base` is passed and no CI smart-resolver fires.
+   *
+   * Resolved as `origin/&lt;defaultBase>` against the local clone; should be a
+   * branch name (not a fully-qualified ref) such as `main`, `master`, or `trunk`.
+   * Falls back to `main` when omitted.
+   *
+   * Migrated automatically from `nx.json#affected.defaultBase` /
+   * `nx.json#defaultBase` by `vis migrate nx`.
+   * @default "main"
+   */
   defaultBase?: string;
   /**
-  * Discover `.editorconfig` for indent / line-ending defaults during
-  * file transformations (sort-package-json, migrate, hook, pm overrides,
-  * workspace catalog rewrites). Per-command flags can still override.
-  * @default true
-  */
+   * Discover `.editorconfig` for indent / line-ending defaults during
+   * file transformations (sort-package-json, migrate, hook, pm overrides,
+   * workspace catalog rewrites). Per-command flags can still override.
+   * @default true
+   */
   editorconfig?: boolean;
   /**
-  * Inherit configuration from one or more parent configs. Entries are
-  * resolved left-to-right (later wins) and the consumer's own values
-  * always override anything pulled in from `extends`.
-  *
-  * Each entry is either:
-  * - a relative path (`./shared.config.ts`, `../shared.config.ts`) —
-  *   resolved against the file declaring `extends`;
-  * - an npm package name (`@acme/vis-preset`) — resolved via Node.js
-  *   module resolution from the consumer file.
-  *
-  * Absolute paths are rejected — they break across machines and CI.
-  * Cycles raise `VisConfigCycleError` during load.
-  * @example
-  * ```
-  * extends: ["@acme/vis-preset", "./shared/security.config.ts"]
-  * ```
-  */
+   * Inherit configuration from one or more parent configs. Entries are
+   * resolved left-to-right (later wins) and the consumer's own values
+   * always override anything pulled in from `extends`.
+   *
+   * Each entry is either:
+   * - a relative path (`./shared.config.ts`, `../shared.config.ts`) —
+   *   resolved against the file declaring `extends`;
+   * - an npm package name (`@acme/vis-preset`) — resolved via Node.js
+   *   module resolution from the consumer file.
+   *
+   * Absolute paths are rejected — they break across machines and CI.
+   * Cycles raise `VisConfigCycleError` during load.
+   * @example
+   * ```
+   * extends: ["@acme/vis-preset", "./shared/security.config.ts"]
+   * ```
+   */
   extends?: string | string[];
   /**
-  * Named file-group patterns, reusable from target `inputs` via the
-  * `@filegroup:&lt;name>` token. File groups are resolved relative to each
-  * project root at discovery time.
-  * @example
-  * ```
-  * fileGroups: {
-  *   sources: ["src/**\/*.ts", "!src/**\/*.test.ts"],
-  *   tests: ["**\/*.test.ts"],
-  * }
-  * ```
-  */
+   * Named file-group patterns, reusable from target `inputs` via the
+   * `@filegroup:&lt;name>` token. File groups are resolved relative to each
+   * project root at discovery time.
+   * @example
+   * ```
+   * fileGroups: {
+   *   sources: ["src/**\/*.ts", "!src/**\/*.test.ts"],
+   *   tests: ["**\/*.test.ts"],
+   * }
+   * ```
+   */
   fileGroups?: Record<string, string[]>;
   /**
-  * Configuration for `vis fmt` — the formatter orchestrator.
-  *
-  * Tunes adapter detection precedence, per-extension routing, and
-  * per-adapter overrides. Flags on the CLI always win over config.
-  *
-  * The default fmt precedence is `oxfmt → biome → dprint → prettier
-  * → deno-fmt`. When multiple adapters claim the same extension,
-  * the first in this order owns it unless overridden here.
-  * @example
-  * ```
-  * fmt: {
-  *   order: ["biome", "prettier"],
-  *   extensionOverrides: { md: "dprint" },
-  *   adapters: { "deno-fmt": { enabled: false } },
-  * }
-  * ```
-  */
+   * Configuration for `vis fmt` — the formatter orchestrator.
+   *
+   * Tunes adapter detection precedence, per-extension routing, and
+   * per-adapter overrides. Flags on the CLI always win over config.
+   *
+   * The default fmt precedence is `oxfmt → biome → dprint → prettier
+   * → deno-fmt`. When multiple adapters claim the same extension,
+   * the first in this order owns it unless overridden here.
+   * @example
+   * ```
+   * fmt: {
+   *   order: ["biome", "prettier"],
+   *   extensionOverrides: { md: "dprint" },
+   *   adapters: { "deno-fmt": { enabled: false } },
+   * }
+   * ```
+   */
   fmt?: {
     /**
-    * Per-adapter overrides. Keyed by `AdapterId`. Set
-    * `enabled: false` to skip an adapter even when detected, or
-    * `extraArgs` to append flags verbatim.
-    */
+     * Per-adapter overrides. Keyed by `AdapterId`. Set
+     * `enabled: false` to skip an adapter even when detected, or
+     * `extraArgs` to append flags verbatim.
+     */
     adapters?: Partial<Record<FmtAdapterId, LintFmtAdapterOverride>>;
     /**
-    * Pin a file extension (without the leading dot) to a specific
-    * adapter, overriding the registry's "first detected adapter
-    * wins" routing. Use to e.g. send `.md` to `dprint` even when
-    * both prettier and dprint are present.
-    */
+     * Pin a file extension (without the leading dot) to a specific
+     * adapter, overriding the registry's "first detected adapter
+     * wins" routing. Use to e.g. send `.md` to `dprint` even when
+     * both prettier and dprint are present.
+     */
     extensionOverrides?: Record<string, FmtAdapterId>;
     /**
-    * Override the adapter precedence order. Adapters omitted from
-    * this list still run (appended at the end in registry order),
-    * but those listed earlier get priority for extension routing.
-    */
+     * Override the adapter precedence order. Adapters omitted from
+     * this list still run (appended at the end in registry order),
+     * but those listed earlier get priority for extension routing.
+     */
     order?: FmtAdapterId[];
   };
   /**
-  * Configuration for the `vis generate` in-repo scaffolding command.
-  * Points at additional template directories beyond the defaults
-  * (`.vis/templates/` and `.moon/templates/`).
-  */
+   * Configuration for the `vis generate` in-repo scaffolding command.
+   * Points at additional template directories beyond the defaults
+   * (`.vis/templates/` and `.moon/templates/`).
+   */
   generator?: {
     /**
-    * Authorization token forwarded to giget when fetching
-    * `git://`/`npm://` remote templates. Falls back to
-    * `GIGET_AUTH` / `GITHUB_TOKEN` / `GH_TOKEN` env vars.
-    */
+     * Authorization token forwarded to giget when fetching
+     * `git://`/`npm://` remote templates. Falls back to
+     * `GIGET_AUTH` / `GITHUB_TOKEN` / `GH_TOKEN` env vars.
+     */
     auth?: string;
     /**
-    * Prefer locally cached remote templates over re-downloading.
-    * Overridable per invocation via `--prefer-offline`.
-    * @default false
-    */
+     * Prefer locally cached remote templates over re-downloading.
+     * Overridable per invocation via `--prefer-offline`.
+     * @default false
+     */
     preferOffline?: boolean;
     /**
-    * Extra directories to scan for templates. Each directory is
-    * checked for both native templates (`&lt;name>.ts`) and
-    * moon-format directories (containing `template.yml`).
-    * @example
-    * ```
-    * generator: {
-    *   templates: ["./tools/generators", "./packages/scaffolding/templates"],
-    * }
-    * ```
-    */
+     * Extra directories to scan for templates. Each directory is
+     * checked for both native templates (`&lt;name>.ts`) and
+     * moon-format directories (containing `template.yml`).
+     * @example
+     * ```
+     * generator: {
+     *   templates: ["./tools/generators", "./packages/scaffolding/templates"],
+     * }
+     * ```
+     */
     templates?: string[];
   };
   /**
-  * Auto-create targets from detected config files (Project Crystal-style).
-  * On by default; set `false` to disable entirely, or use the object
-  * form to disable individual detectors.
-  *
-  * Inferred targets sit *below* explicit ones — the command from
-  * `package.json#scripts`, `project.json#targets`, or `vis.task.ts`
-  * always wins per-key, so opting in never changes what runs. As a
-  * caching aid, when a `package.json` script's command *is* a
-  * detector's command (optionally with extra flags, no shell
-  * chaining) and the script declares no `inputs`/`outputs`, the
-  * detector's `inputs`/`outputs` are adopted so the script target can
-  * cache precisely and restore its artifacts. Customised/compound
-  * scripts are left untouched.
-  *
-  * Built-in detectors and the targets they synthesize:
-  *
-  * - **App frameworks** — `nuxt` (build/dev/preview/generate),
-  *   `next` (build/dev/start), `remix` (build/dev/start), `astro`
-  *   (build/dev), `gatsby` (build/develop/serve), `docusaurus`
-  *   (build/start/serve).
-  * - **Bundlers** — `vite` (build/dev/preview), `rolldown` (build),
-  *   `tsdown` (build), `tsup` (build), `packem` (build), `rollup`
-  *   (build), `webpack` (build).
-  * - **Docs sites** — `vitepress` (docs:build/docs:dev/docs:preview),
-  *   `typedoc` (docs).
-  * - **Server frameworks** — `nest` (build/start/start:dev).
-  * - **Test runners** — `vitest` (test/test:watch), `jest`
-  *   (test/test:watch), `bun` (test), `playwright` (test:e2e),
-  *   `cypress` (test:e2e/cypress:open).
-  * - **Stories** — `storybook` (storybook/build-storybook).
-  * - **Type checking** — `typescript` (typecheck via `tsc --noEmit`).
-  * - **Lint / format** — `eslint` (lint), `prettier` (format /
-  *   format:check), `biome` (lint, format), `oxlint` (lint),
-  *   `oxfmt` (format / format:check), `stylelint` (lint:css),
-  *   `knip` (knip).
-  * - **Runtimes** — `deno` (test/lint/fmt/check).
-  * - **Database tooling** — `prisma` (db:generate/db:migrate/
-  *   db:push/db:studio), `drizzle` (db:generate/db:migrate/
-  *   db:push/db:studio).
-  * - **Codegen / release** — `graphql-codegen` (codegen),
-  *   `api-extractor` (api-extract), `changeset` (changeset:version /
-  *   changeset:publish / changeset:status).
-  *
-  * Trigger: presence of any matching config file in the project root.
-  * Most detectors additionally match when their framework appears in
-  * `dependencies` / `devDependencies` / `peerDependencies` /
-  * `optionalDependencies` — covering convention-only setups (e.g.
-  * vitest with default config). Detectors that intentionally require
-  * a config file (because the package frequently appears transitively
-  * and a dep-only match would synthesize broken commands): `vite`,
-  * `rolldown`, `rollup`, `webpack`, `storybook`, `nest`, `remix`,
-  * `vitepress`, `bun`, `deno`, `changeset`.
-  *
-  * Conflict resolution: detectors are evaluated in registration order
-  * (see `BUILT_IN_DETECTORS`) and the first to claim a target name
-  * wins. Per-name priorities: `build` → nuxt > next > remix > astro
-  * > gatsby > docusaurus > vite > nest > rolldown > tsdown > tsup >
-  * packem > rollup > webpack; `test` → vitest > jest > bun > deno;
-  * `test:e2e` → playwright > cypress; `lint` → eslint > biome >
-  * oxlint > deno; `format` → prettier > biome > oxfmt; `db:*` →
-  * prisma > drizzle.
-  *
-  * Also accepts an object form (`{ vite: false, vitest: true }`) to
-  * opt individual detectors in or out by name. Detectors omitted from
-  * the object run at their default (enabled). Useful when one
-  * detector misfires for a given workspace without disabling the rest.
-  * @default true
-  */
+   * Auto-create targets from detected config files (Project Crystal-style).
+   * On by default; set `false` to disable entirely, or use the object
+   * form to disable individual detectors.
+   *
+   * Inferred targets sit *below* explicit ones — the command from
+   * `package.json#scripts`, `project.json#targets`, or `vis.task.ts`
+   * always wins per-key, so opting in never changes what runs. As a
+   * caching aid, when a `package.json` script's command *is* a
+   * detector's command (optionally with extra flags, no shell
+   * chaining) and the script declares no `inputs`/`outputs`, the
+   * detector's `inputs`/`outputs` are adopted so the script target can
+   * cache precisely and restore its artifacts. Customised/compound
+   * scripts are left untouched.
+   *
+   * Built-in detectors and the targets they synthesize:
+   *
+   * - **App frameworks** — `nuxt` (build/dev/preview/generate),
+   *   `next` (build/dev/start), `remix` (build/dev/start), `astro`
+   *   (build/dev), `gatsby` (build/develop/serve), `docusaurus`
+   *   (build/start/serve).
+   * - **Bundlers** — `vite` (build/dev/preview), `rolldown` (build),
+   *   `tsdown` (build), `tsup` (build), `packem` (build), `rollup`
+   *   (build), `webpack` (build).
+   * - **Docs sites** — `vitepress` (docs:build/docs:dev/docs:preview),
+   *   `typedoc` (docs).
+   * - **Server frameworks** — `nest` (build/start/start:dev).
+   * - **Test runners** — `vitest` (test/test:watch), `jest`
+   *   (test/test:watch), `bun` (test), `playwright` (test:e2e),
+   *   `cypress` (test:e2e/cypress:open).
+   * - **Stories** — `storybook` (storybook/build-storybook).
+   * - **Type checking** — `typescript` (typecheck via `tsc --noEmit`).
+   * - **Lint / format** — `eslint` (lint), `prettier` (format /
+   *   format:check), `biome` (lint, format), `oxlint` (lint),
+   *   `oxfmt` (format / format:check), `stylelint` (lint:css),
+   *   `knip` (knip).
+   * - **Runtimes** — `deno` (test/lint/fmt/check).
+   * - **Database tooling** — `prisma` (db:generate/db:migrate/
+   *   db:push/db:studio), `drizzle` (db:generate/db:migrate/
+   *   db:push/db:studio).
+   * - **Codegen / release** — `graphql-codegen` (codegen),
+   *   `api-extractor` (api-extract), `changeset` (changeset:version /
+   *   changeset:publish / changeset:status).
+   *
+   * Trigger: presence of any matching config file in the project root.
+   * Most detectors additionally match when their framework appears in
+   * `dependencies` / `devDependencies` / `peerDependencies` /
+   * `optionalDependencies` — covering convention-only setups (e.g.
+   * vitest with default config). Detectors that intentionally require
+   * a config file (because the package frequently appears transitively
+   * and a dep-only match would synthesize broken commands): `vite`,
+   * `rolldown`, `rollup`, `webpack`, `storybook`, `nest`, `remix`,
+   * `vitepress`, `bun`, `deno`, `changeset`.
+   *
+   * Conflict resolution: detectors are evaluated in registration order
+   * (see `BUILT_IN_DETECTORS`) and the first to claim a target name
+   * wins. Per-name priorities: `build` → nuxt > next > remix > astro
+   * > gatsby > docusaurus > vite > nest > rolldown > tsdown > tsup >
+   * packem > rollup > webpack; `test` → vitest > jest > bun > deno;
+   * `test:e2e` → playwright > cypress; `lint` → eslint > biome >
+   * oxlint > deno; `format` → prettier > biome > oxfmt; `db:*` →
+   * prisma > drizzle.
+   *
+   * Also accepts an object form (`{ vite: false, vitest: true }`) to
+   * opt individual detectors in or out by name. Detectors omitted from
+   * the object run at their default (enabled). Useful when one
+   * detector misfires for a given workspace without disabling the rest.
+   * @default true
+   */
   inferTargets?: Record<string, boolean> | boolean;
   /**
-  * Installer backend selection for `vis install` / `vis add` /
-  * `vis remove` / `vis update` / `vis ci`.
-  *
-  * Lets users opt into [aube](https://github.com/endevco/aube) — a
-  * Rust-native package manager that reads/writes pnpm/npm/yarn/bun
-  * lockfiles in place — as the default installer, while keeping a
-  * single switch to fall back to the conventional PM detected from
-  * the lockfile.
-  *
-  * Resolution precedence (highest first):
-  * 1. CLI flag (`--installer &lt;name>` / `--no-aube`)
-  * 2. Env var `VIS_INSTALLER`
-  * 3. This config field
-  * 4. Auto-detect (the default)
-  *
-  * Aube must be installed separately — `vis` does not bundle it.
-  * Install via npm (`@endevco/aube`), `mise use -g aube`, or
-  * `brew install endevco/tap/aube`.
-  */
+   * Installer backend selection for `vis install` / `vis add` /
+   * `vis remove` / `vis update` / `vis ci`.
+   *
+   * Lets users opt into [aube](https://github.com/endevco/aube) — a
+   * Rust-native package manager that reads/writes pnpm/npm/yarn/bun
+   * lockfiles in place — as the default installer, while keeping a
+   * single switch to fall back to the conventional PM detected from
+   * the lockfile.
+   *
+   * Resolution precedence (highest first):
+   * 1. CLI flag (`--installer &lt;name>` / `--no-aube`)
+   * 2. Env var `VIS_INSTALLER`
+   * 3. This config field
+   * 4. Auto-detect (the default)
+   *
+   * Aube must be installed separately — `vis` does not bundle it.
+   * Install via npm (`@endevco/aube`), `mise use -g aube`, or
+   * `brew install endevco/tap/aube`.
+   */
   install?: {
     /**
-    * Which package manager performs install/add/remove/etc.
-    * - `auto` (default): use `aube` when it is on PATH; otherwise
-    *   fall back to the lockfile-detected PM.
-    * - explicit name: always use that PM. Errors when the named
-    *   binary is missing rather than silently falling back.
-    * @default "auto"
-    */
+     * Which package manager performs install/add/remove/etc.
+     * - `auto` (default): use `aube` when it is on PATH; otherwise
+     *   fall back to the lockfile-detected PM.
+     * - explicit name: always use that PM. Errors when the named
+     *   binary is missing rather than silently falling back.
+     * @default "auto"
+     */
     backend?: "aube" | "auto" | "bun" | "npm" | "pnpm" | "yarn";
     /**
-    * Whether to dispatch PM invocations through `corepack`.
-    * - `"auto"` (default): use corepack only when the workspace
-    *   pins a PM via the `packageManager` field AND `corepack` is
-    *   on PATH AND the PM is one corepack manages (pnpm/yarn/npm).
-    * - `true`: always prefix `corepack` when the binary is on PATH
-    *   and the PM is corepack-managed (errors loudly otherwise).
-    * - `false`: never go through corepack — invoke the PM directly.
-    *
-    * Mirrors nypm's `corepack: true` flag. Bun, deno, and aube are
-    * never wrapped — corepack does not manage them.
-    * @default "auto"
-    */
+     * Whether to dispatch PM invocations through `corepack`.
+     * - `"auto"` (default): use corepack only when the workspace
+     *   pins a PM via the `packageManager` field AND `corepack` is
+     *   on PATH AND the PM is one corepack manages (pnpm/yarn/npm).
+     * - `true`: always prefix `corepack` when the binary is on PATH
+     *   and the PM is corepack-managed (errors loudly otherwise).
+     * - `false`: never go through corepack — invoke the PM directly.
+     *
+     * Mirrors nypm's `corepack: true` flag. Bun, deno, and aube are
+     * never wrapped — corepack does not manage them.
+     * @default "auto"
+     */
     corepack?: "auto" | boolean;
   };
   /**
-  * Configuration for `vis lint` — the linter orchestrator.
-  *
-  * Tunes adapter detection precedence and per-adapter overrides.
-  * Flags on the CLI always win over config.
-  *
-  * The default lint precedence is `oxlint → biome → eslint →
-  * stylelint → deno-lint`. Override with `order` to e.g. let biome
-  * fire before oxlint when the workspace standardises on biome.
-  * @example
-  * ```
-  * lint: {
-  *   order: ["biome", "eslint"],
-  *   adapters: { "deno-lint": { enabled: false } },
-  * }
-  * ```
-  */
+   * Configuration for `vis lint` — the linter orchestrator.
+   *
+   * Tunes adapter detection precedence and per-adapter overrides.
+   * Flags on the CLI always win over config.
+   *
+   * The default lint precedence is `oxlint → biome → eslint →
+   * stylelint → deno-lint`. Override with `order` to e.g. let biome
+   * fire before oxlint when the workspace standardises on biome.
+   * @example
+   * ```
+   * lint: {
+   *   order: ["biome", "eslint"],
+   *   adapters: { "deno-lint": { enabled: false } },
+   * }
+   * ```
+   */
   lint?: {
     /**
-    * Per-adapter overrides. Keyed by `AdapterId`. Set
-    * `enabled: false` to skip an adapter even when detected, or
-    * `extraArgs` to append flags verbatim.
-    */
+     * Per-adapter overrides. Keyed by `AdapterId`. Set
+     * `enabled: false` to skip an adapter even when detected, or
+     * `extraArgs` to append flags verbatim.
+     */
     adapters?: Partial<Record<LintAdapterId, LintFmtAdapterOverride>>;
     /**
-    * Override the adapter precedence order. Adapters omitted from
-    * this list still run (appended at the end in registry order)
-    * unless explicitly disabled under `adapters[id].enabled`.
-    */
+     * Override the adapter precedence order. Adapters omitted from
+     * this list still run (appended at the end in registry order)
+     * unless explicitly disabled under `adapters[id].enabled`.
+     */
     order?: LintAdapterId[];
   };
   /**
-  * `vis-mcp` promotion notice shown after successful commands when an
-  * AI CLI (Claude Code, Cursor, Windsurf, Continue, Zed, Cline) is
-  * installed but `@visulima/vis-mcp` is not wired into its config.
-  *
-  * Shown at most once every 14 days; skipped in CI, non-TTY shells,
-  * during `--help`/`--version`/`ai`/`mcp` invocations, and when
-  * `VIS_NO_MCP_PROMOTE=1` is set. Set `enabled: false` to silence
-  * permanently for this workspace.
-  * @example
-  * ```
-  * mcpPromote: { enabled: false }
-  * ```
-  */
+   * `vis-mcp` promotion notice shown after successful commands when an
+   * AI CLI (Claude Code, Cursor, Windsurf, Continue, Zed, Cline) is
+   * installed but `@visulima/vis-mcp` is not wired into its config.
+   *
+   * Shown at most once every 14 days; skipped in CI, non-TTY shells,
+   * during `--help`/`--version`/`ai`/`mcp` invocations, and when
+   * `VIS_NO_MCP_PROMOTE=1` is set. Set `enabled: false` to silence
+   * permanently for this workspace.
+   * @example
+   * ```
+   * mcpPromote: { enabled: false }
+   * ```
+   */
   mcpPromote?: {
     /**
-    * Show the vis-mcp promotion notice on successful command completion.
-    * @default true
-    */
+     * Show the vis-mcp promotion notice on successful command completion.
+     * @default true
+     */
     enabled?: boolean;
   };
   /**
-  * Named input patterns inherited by every project target. Equivalent
-  * to task-runner's `namedInputs` but configurable from the vis config.
-  */
+   * Named input patterns inherited by every project target. Equivalent
+   * to task-runner's `namedInputs` but configurable from the vis config.
+   */
   namedInputs?: NamedInputs;
   /** Package override mappings applied during migration (e.g., `{ "lodash": "lodash-es" }`) */
   overrides?: Record<string, string>;
   /**
-  * Plugins — each plugin registers typed hooks that fire at run /
-  * task / cache boundaries. See {@link VisPlugin} for the contract.
-  * Prefer plugins over per-target shell hooks when behaviour needs
-  * access to task metadata, results, or cache state.
-  */
+   * Plugins — each plugin registers typed hooks that fire at run /
+   * task / cache boundaries. See {@link VisPlugin} for the contract.
+   * Prefer plugins over per-target shell hooks when behaviour needs
+   * access to task metadata, results, or cache state.
+   */
   plugins?: VisPlugin[];
   /**
-  * Workspace dep-policy lints exposed via `vis lint`. Each block opts in
-  * to a single rule; the command flags (`--workspace-protocol`,
-  * `--no-redefine-root`, `--banned-deps`) toggle them per-run.
-  */
+   * Workspace dep-policy lints exposed via `vis lint`. Each block opts in
+   * to a single rule; the command flags (`--workspace-protocol`,
+   * `--no-redefine-root`, `--banned-deps`) toggle them per-run.
+   */
   policy?: {
     /**
-    * Map of dep names or globs → reason (or `{ reason, replacement, packages?, paths? }`).
-    * Internal/workspace deps are never flagged here; the
-    * workspace-protocol lint owns those.
-    *
-    * Optional `packages` (globs over the declaring package's `name`) and
-    * `paths` (globs over the workspace-relative `packageDir`) narrow where
-    * the rule applies. With both set, either match is enough. Omit both
-    * to ban anywhere — the default.
-    * @example
-    * ```
-    * bannedDeps: {
-    *   request: "deprecated; use undici",
-    *   moment: { reason: "huge bundle, frozen upstream", replacement: "date-fns" },
-    *   "@radix-ui/*": "we standardized on shadcn",
-    *   react: { reason: "no react in shared libs", paths: ["packages/shared/*"] },
-    *   "next": { reason: "apps only", packages: ["@app/*"] },
-    * }
-    * ```
-    */
+     * Map of dep names or globs → reason (or `{ reason, replacement, packages?, paths? }`).
+     * Internal/workspace deps are never flagged here; the
+     * workspace-protocol lint owns those.
+     *
+     * Optional `packages` (globs over the declaring package's `name`) and
+     * `paths` (globs over the workspace-relative `packageDir`) narrow where
+     * the rule applies. With both set, either match is enough. Omit both
+     * to ban anywhere — the default.
+     * @example
+     * ```
+     * bannedDeps: {
+     *   request: "deprecated; use undici",
+     *   moment: { reason: "huge bundle, frozen upstream", replacement: "date-fns" },
+     *   "@radix-ui/*": "we standardized on shadcn",
+     *   react: { reason: "no react in shared libs", paths: ["packages/shared/*"] },
+     *   "next": { reason: "apps only", packages: ["@app/*"] },
+     * }
+     * ```
+     */
     bannedDeps?: Record<string, string | {
       packages?: string[];
       paths?: string[];
@@ -1312,364 +1320,364 @@ interface VisConfig {
       replacement?: string;
     }>;
     /**
-    * Tweak the custom-types lint that flags drift in `engines.{node,pnpm,...}`,
-    * `packageManager`, `volta.{node,pnpm,yarn}`, and the proposed
-    * `devEngines.{runtime,packageManager}` array form.
-    *
-    * Each (customType × name) cluster is tracked independently —
-    * `engines.node` and `volta.node` don't cross-couple here. Use a
-    * versionGroup once that lands if you need to enforce they agree.
-    */
+     * Tweak the custom-types lint that flags drift in `engines.{node,pnpm,...}`,
+     * `packageManager`, `volta.{node,pnpm,yarn}`, and the proposed
+     * `devEngines.{runtime,packageManager}` array form.
+     *
+     * Each (customType × name) cluster is tracked independently —
+     * `engines.node` and `volta.node` don't cross-couple here. Use a
+     * versionGroup once that lands if you need to enforce they agree.
+     */
     customTypes?: {
       /**
-      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
-      * for the contract — same semantics, applied to drift rewrites
-      * across engines / packageManager / volta / devEngines.
-      *
-      * Note: `--fix` strips any `+sha512.&lt;hash&gt;` suffix from
-      * `packageManager` on bump — content-integrity hashes are tied
-      * to a specific package, not a version, so users must regenerate
-      * via their PM (`pnpm install` re-pins; `corepack use pnpm@X` etc.).
-      * @default true
-      */
+       * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+       * for the contract — same semantics, applied to drift rewrites
+       * across engines / packageManager / volta / devEngines.
+       *
+       * Note: `--fix` strips any `+sha512.&lt;hash&gt;` suffix from
+       * `packageManager` on bump — content-integrity hashes are tied
+       * to a specific package, not a version, so users must regenerate
+       * via their PM (`pnpm install` re-pins; `corepack use pnpm@X` etc.).
+       * @default true
+       */
       autofix?: "prompt" | boolean;
       /**
-      * User-defined custom-type pin locations. Each entry tells the
-      * customTypes lint to read additional version pins from a
-      * non-standard JSON path inside every workspace package.json,
-      * cluster them by `(name × depName)` like the built-in types,
-      * and rewrite them with `--fix`.
-      *
-      * The original built-ins (`engines`, `volta`, `packageManager`,
-      * `devEngines.runtime`, `devEngines.packageManager`) keep
-      * running unconditionally — these layer on top.
-      *
-      * Strategies:
-      * - `versionsByName`: the JSON at `path` is `{ [depName]: version }`
-      *   (like `engines` or `pnpm.overrides`).
-      * - `name@version`: the JSON at `path` is a string of the form
-      *   `name@version` (like `packageManager`). The leading `name@`
-      *   is preserved; only the version segment is rewritten.
-      * - `string`: the JSON at `path` is a bare version string. The
-      *   `depName` field is required and identifies the dep cluster.
-      *
-      * `name` must not collide with a built-in type name. `path` is
-      * a dot-separated walk into the package.json (e.g. `pnpm.overrides`).
-      * @example
-      * ```ts
-      * extraTypes: [
-      *   { name: "pnpmOverridesLegacy", path: "pnpm.overrides", strategy: "versionsByName" },
-      *   { name: "myToolPin",           path: "myTool.runtime", strategy: "name@version" },
-      *   { name: "minNode",             path: "config.minNode", strategy: "string", depName: "node" },
-      * ]
-      * ```
-      */
+       * User-defined custom-type pin locations. Each entry tells the
+       * customTypes lint to read additional version pins from a
+       * non-standard JSON path inside every workspace package.json,
+       * cluster them by `(name × depName)` like the built-in types,
+       * and rewrite them with `--fix`.
+       *
+       * The original built-ins (`engines`, `volta`, `packageManager`,
+       * `devEngines.runtime`, `devEngines.packageManager`) keep
+       * running unconditionally — these layer on top.
+       *
+       * Strategies:
+       * - `versionsByName`: the JSON at `path` is `{ [depName]: version }`
+       *   (like `engines` or `pnpm.overrides`).
+       * - `name@version`: the JSON at `path` is a string of the form
+       *   `name@version` (like `packageManager`). The leading `name@`
+       *   is preserved; only the version segment is rewritten.
+       * - `string`: the JSON at `path` is a bare version string. The
+       *   `depName` field is required and identifies the dep cluster.
+       *
+       * `name` must not collide with a built-in type name. `path` is
+       * a dot-separated walk into the package.json (e.g. `pnpm.overrides`).
+       * @example
+       * ```ts
+       * extraTypes: [
+       *   { name: "pnpmOverridesLegacy", path: "pnpm.overrides", strategy: "versionsByName" },
+       *   { name: "myToolPin",           path: "myTool.runtime", strategy: "name@version" },
+       *   { name: "minNode",             path: "config.minNode", strategy: "string", depName: "node" },
+       * ]
+       * ```
+       */
       extraTypes?: ExtraCustomType[];
       /**
-      * Dep names exempt from the drift check (exact match against the
-      * field name within the block — e.g. `node`, `pnpm`).
-      */
+       * Dep names exempt from the drift check (exact match against the
+       * field name within the block — e.g. `node`, `pnpm`).
+       */
       ignore?: string[];
       /**
-      * Resolution strategy used when `--fix` runs.
-      * - `highest` (default): align every drifting instance to the
-      *   highest declared version.
-      * - `lowest`: align to the lowest.
-      * @default "highest"
-      */
+       * Resolution strategy used when `--fix` runs.
+       * - `highest` (default): align every drifting instance to the
+       *   highest declared version.
+       * - `lowest`: align to the lowest.
+       * @default "highest"
+       */
       resolve?: "highest" | "lowest";
     };
     /**
-    * Tweak the dead-workspace-patterns lint that flags entries in
-    * `pnpm-workspace.yaml#packages` / `package.json#workspaces` which
-    * resolve to zero on-disk directories.
-    */
+     * Tweak the dead-workspace-patterns lint that flags entries in
+     * `pnpm-workspace.yaml#packages` / `package.json#workspaces` which
+     * resolve to zero on-disk directories.
+     */
     deadWorkspacePatterns?: {
       /**
-      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
-      * for the contract — applied here to dropping unmatched patterns
-      * from the workspace config file.
-      * @default true
-      */
+       * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+       * for the contract — applied here to dropping unmatched patterns
+       * from the workspace config file.
+       * @default true
+       */
       autofix?: "prompt" | boolean;
     };
     /**
-    * Tweak the empty-deps lint that flags empty `dependencies` /
-    * `devDependencies` / `peerDependencies` / `optionalDependencies`
-    * blocks across the workspace.
-    */
+     * Tweak the empty-deps lint that flags empty `dependencies` /
+     * `devDependencies` / `peerDependencies` / `optionalDependencies`
+     * blocks across the workspace.
+     */
     emptyDeps?: {
       /**
-      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
-      * for the contract — applied here to removing the empty key.
-      * @default true
-      */
+       * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+       * for the contract — applied here to removing the empty key.
+       * @default true
+       */
       autofix?: "prompt" | boolean;
       /**
-      * Block names exempt from the rule (e.g. `["peerDependencies"]`
-      * to keep the key around as a marker even when empty).
-      */
+       * Block names exempt from the rule (e.g. `["peerDependencies"]`
+       * to keep the key around as a marker even when empty).
+       */
       ignoreBlocks?: ("dependencies" | "devDependencies" | "optionalDependencies" | "peerDependencies")[];
     };
     /**
-    * Tweak the redefine-root lint that flags non-root packages duplicating
-    * deps already pinned at the workspace root.
-    */
+     * Tweak the redefine-root lint that flags non-root packages duplicating
+     * deps already pinned at the workspace root.
+     */
     redefineRoot?: {
       /** Dep names that are exempt from the redefine-root rule (exact match). */
       ignore?: string[];
     };
     /**
-    * Tweak the root-deps lint that flags runtime `dependencies` declared
-    * on the private workspace root (they should live in `devDependencies`).
-    */
+     * Tweak the root-deps lint that flags runtime `dependencies` declared
+     * on the private workspace root (they should live in `devDependencies`).
+     */
     rootDeps?: {
       /**
-      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
-      * for the contract — applied here to moving entries from
-      * `dependencies` to `devDependencies` on the root package.json.
-      * @default true
-      */
+       * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+       * for the contract — applied here to moving entries from
+       * `dependencies` to `devDependencies` on the root package.json.
+       * @default true
+       */
       autofix?: "prompt" | boolean;
     };
     /**
-    * Tweak the root-package-manager lint that flags a missing or
-    * malformed `packageManager` field on the workspace root.
-    */
+     * Tweak the root-package-manager lint that flags a missing or
+     * malformed `packageManager` field on the workspace root.
+     */
     rootPackageManager?: {
       /**
-      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
-      * for the contract. `--fix` only writes when `suggested` is set —
-      * a missing `packageManager` field has no canonical default.
-      * @default true
-      */
+       * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+       * for the contract. `--fix` only writes when `suggested` is set —
+       * a missing `packageManager` field has no canonical default.
+       * @default true
+       */
       autofix?: "prompt" | boolean;
       /**
-      * Canonical specifier (`name@version`) to write when `--fix` runs
-      * and the field is absent. Required to enable autofix —
-      * vis won't guess the workspace's preferred manager.
-      * @example "pnpm@10.32.1"
-      */
+       * Canonical specifier (`name@version`) to write when `--fix` runs
+       * and the field is absent. Required to enable autofix —
+       * vis won't guess the workspace's preferred manager.
+       * @example "pnpm@10.32.1"
+       */
       suggested?: string;
     };
     /**
-    * Tweak the root-private lint that flags a workspace root package.json
-    * missing `"private": true`. Only fires when the root looks like a
-    * workspace (npm/yarn/bun `workspaces` field or `pnpm-workspace.yaml`).
-    */
+     * Tweak the root-private lint that flags a workspace root package.json
+     * missing `"private": true`. Only fires when the root looks like a
+     * workspace (npm/yarn/bun `workspaces` field or `pnpm-workspace.yaml`).
+     */
     rootPrivate?: {
       /**
-      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
-      * for the contract — applied here to inserting `"private": true`.
-      * @default true
-      */
+       * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+       * for the contract — applied here to inserting `"private": true`.
+       * @default true
+       */
       autofix?: "prompt" | boolean;
     };
     /**
-    * Tweak the similar-deps lint that flags drift across related dep
-    * families (e.g. `react` and `react-dom`, all of `@babel/*`).
-    *
-    * The lint is report-only — aligning a family requires picking a
-    * single canonical specifier across heterogeneous range syntaxes
-    * (`^`, `~`, exact), which is too lossy without user input.
-    */
+     * Tweak the similar-deps lint that flags drift across related dep
+     * families (e.g. `react` and `react-dom`, all of `@babel/*`).
+     *
+     * The lint is report-only — aligning a family requires picking a
+     * single canonical specifier across heterogeneous range syntaxes
+     * (`^`, `~`, exact), which is too lossy without user input.
+     */
     similarDeps?: {
       /**
-      * Additional families merged with the built-ins. Same `id` wins
-      * → user override fully replaces the built-in entry.
-      * @example
-      * ```
-      * extraFamilies: [
-      *   { id: "vue", label: "Vue", members: ["vue", "vue-router", "pinia"] },
-      * ]
-      * ```
-      */
+       * Additional families merged with the built-ins. Same `id` wins
+       * → user override fully replaces the built-in entry.
+       * @example
+       * ```
+       * extraFamilies: [
+       *   { id: "vue", label: "Vue", members: ["vue", "vue-router", "pinia"] },
+       * ]
+       * ```
+       */
       extraFamilies?: SimilarDepFamily[];
       /** Family ids to skip entirely (matches `SimilarDepFamily.id`). */
       ignoreFamilies?: string[];
     };
     /**
-    * Tweak the types-in-deps lint that flags `@types/*` declared in
-    * `dependencies` on a private package (they belong in
-    * `devDependencies` since the package never ships).
-    */
+     * Tweak the types-in-deps lint that flags `@types/*` declared in
+     * `dependencies` on a private package (they belong in
+     * `devDependencies` since the package never ships).
+     */
     typesInDeps?: {
       /**
-      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
-      * for the contract — applied here to moving the entry to
-      * `devDependencies`. Existing dev pins are preserved on conflict.
-      * @default true
-      */
+       * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+       * for the contract — applied here to moving the entry to
+       * `devDependencies`. Existing dev pins are preserved on conflict.
+       * @default true
+       */
       autofix?: "prompt" | boolean;
       /** Dep names exempt from the rule (exact match, e.g. `@types/node`). */
       ignore?: string[];
     };
     /**
-    * Tweak the workspace-protocol lint that flags internal deps not
-    * using the `workspace:` protocol.
-    */
+     * Tweak the workspace-protocol lint that flags internal deps not
+     * using the `workspace:` protocol.
+     */
     workspaceProtocol?: {
       /**
-      * Three-state autofix opt-out. Some workspaces want detection
-      * without rewrite (e.g. dual-licensed packages where `workspace:*`
-      * is unsafe).
-      * - `true` (default): `--fix` rewrites the specifier.
-      * - `false`: never rewrite — report the violation only.
-      * - `"prompt"`: ask before each rewrite. Falls back to report-only
-      *   when stdin isn't a TTY (CI). Reserved; not yet implemented.
-      *
-      * Note: when `false` (or `"prompt"`), `--fix` still **fails CI** on
-      * detected violations — the rule is "report only", not "ignore".
-      * Drop the rule from the lint selection if you want a clean exit.
-      * @default true
-      * @example
-      * ```
-      * policy: {
-      *   workspaceProtocol: { autofix: false },
-      * }
-      * ```
-      */
+       * Three-state autofix opt-out. Some workspaces want detection
+       * without rewrite (e.g. dual-licensed packages where `workspace:*`
+       * is unsafe).
+       * - `true` (default): `--fix` rewrites the specifier.
+       * - `false`: never rewrite — report the violation only.
+       * - `"prompt"`: ask before each rewrite. Falls back to report-only
+       *   when stdin isn't a TTY (CI). Reserved; not yet implemented.
+       *
+       * Note: when `false` (or `"prompt"`), `--fix` still **fails CI** on
+       * detected violations — the rule is "report only", not "ignore".
+       * Drop the rule from the lint selection if you want a clean exit.
+       * @default true
+       * @example
+       * ```
+       * policy: {
+       *   workspaceProtocol: { autofix: false },
+       * }
+       * ```
+       */
       autofix?: "prompt" | boolean;
     };
     /**
-    * Tweak the workspace-versions lint that flags external deps declared
-    * at inconsistent versions across the workspace.
-    */
+     * Tweak the workspace-versions lint that flags external deps declared
+     * at inconsistent versions across the workspace.
+     */
     workspaceVersions?: {
       /**
-      * Three-state autofix opt-out. See `workspaceProtocol.autofix`
-      * for the contract — same semantics, applied to drift rewrites.
-      *
-      * Also gates the `--propose-min` catalog suggestion writer:
-      * when `false` / `"prompt"`, `--fix --propose-min` reports the
-      * proposed catalog entries but does not write
-      * `pnpm-workspace.yaml`. Same "report only, still fails CI"
-      * note applies as on `workspaceProtocol.autofix`.
-      * @default true
-      */
+       * Three-state autofix opt-out. See `workspaceProtocol.autofix`
+       * for the contract — same semantics, applied to drift rewrites.
+       *
+       * Also gates the `--propose-min` catalog suggestion writer:
+       * when `false` / `"prompt"`, `--fix --propose-min` reports the
+       * proposed catalog entries but does not write
+       * `pnpm-workspace.yaml`. Same "report only, still fails CI"
+       * note applies as on `workspaceProtocol.autofix`.
+       * @default true
+       */
       autofix?: "prompt" | boolean;
       /** Dep names exempt from the version-drift check (exact match). */
       ignore?: string[];
       /**
-      * Resolution strategy used when `--fix` runs.
-      * - `highest` (default): rewrite every drifting instance to the
-      *   highest sibling specifier.
-      * - `lowest`: rewrite to the lowest.
-      * - `catalog`: rewrite any dep already pinned in a workspace catalog
-      *   to `catalog:` / `catalog:&lt;name>`. Catalog must exist; this lint
-      *   does not create the catalog (see `vis lint --resolve catalog --propose`).
-      * @default "highest"
-      */
+       * Resolution strategy used when `--fix` runs.
+       * - `highest` (default): rewrite every drifting instance to the
+       *   highest sibling specifier.
+       * - `lowest`: rewrite to the lowest.
+       * - `catalog`: rewrite any dep already pinned in a workspace catalog
+       *   to `catalog:` / `catalog:&lt;name>`. Catalog must exist; this lint
+       *   does not create the catalog (see `vis lint --resolve catalog --propose`).
+       * @default "highest"
+       */
       resolve?: "catalog" | "highest" | "lowest";
     };
   };
   /**
-  * Pre-flight checks fired before `vis run` starts the orchestrator.
-  * Each check is opt-out (`false`) — defaults are sensible for the
-  * common monorepo case.
-  */
+   * Pre-flight checks fired before `vis run` starts the orchestrator.
+   * Each check is opt-out (`false`) — defaults are sensible for the
+   * common monorepo case.
+   */
   preflight?: {
     /**
-    * Detect "lockfile changed but `node_modules` is stale" before
-    * running tasks. Compares lockfile mtime against the
-    * package-manager-specific install marker
-    * (`node_modules/.modules.yaml` for pnpm, `.package-lock.json`
-    * for npm, etc.). Warns in TTY, hard-fails in CI.
-    * @default true
-    */
+     * Detect "lockfile changed but `node_modules` is stale" before
+     * running tasks. Compares lockfile mtime against the
+     * package-manager-specific install marker
+     * (`node_modules/.modules.yaml` for pnpm, `.package-lock.json`
+     * for npm, etc.). Warns in TTY, hard-fails in CI.
+     * @default true
+     */
     lockfile?: boolean;
   };
   /**
-  * Configuration for the `vis release` subsystem. Controls change-file
-  * authoring, version computation, channel routing, publish behavior,
-  * and CI integration. See `packages/tooling/vis/rfc/design-release-manager.md`.
-  */
+   * Configuration for the `vis release` subsystem. Controls change-file
+   * authoring, version computation, channel routing, publish behavior,
+   * and CI integration. See `packages/tooling/vis/rfc/design-release-manager.md`.
+   */
   release?: VisReleaseConfig;
   /**
-  * Behavior of `vis run` when invoked tasks declare service dependencies
-  * that aren't running in the workspace registry. CLI `--services=&lt;mode>`
-  * overrides this block.
-  */
+   * Behavior of `vis run` when invoked tasks declare service dependencies
+   * that aren't running in the workspace registry. CLI `--services=&lt;mode>`
+   * overrides this block.
+   */
   run?: {
     /**
-    * Wrap each task's CI log block in collapsible groups so users
-    * can fold/unfold per-task output in the host CI's web UI.
-    * Failed tasks always render expanded so the failure is visible
-    * without an extra click.
-    *
-    * - `auto` (default): pick the format from the detected runner —
-    *   `GITHUB_ACTIONS=true` → `github` (`::group::`),
-    *   `GITLAB_CI=true` → `gitlab` (`section_start:` ANSI sequences),
-    *   `BUILDKITE=true` → `buildkite` (`---` collapsed headers),
-    *   `TF_BUILD=True` → `azure` (`##[group]`),
-    *   no grouping otherwise.
-    * - `off`: never group (raw separators only — useful when
-    *   piping through tools that mangle the directives).
-    * - `azure` / `buildkite` / `github` / `gitlab`: force the format
-    *   regardless of detected environment (useful for self-hosted
-    *   runners that don't set the standard env vars).
-    *
-    * CircleCI is intentionally not auto-detected: its 2.0+ format
-    * has no inline grouping directive — steps auto-group in the
-    * web UI without any markup from the runner.
-    */
+     * Wrap each task's CI log block in collapsible groups so users
+     * can fold/unfold per-task output in the host CI's web UI.
+     * Failed tasks always render expanded so the failure is visible
+     * without an extra click.
+     *
+     * - `auto` (default): pick the format from the detected runner —
+     *   `GITHUB_ACTIONS=true` → `github` (`::group::`),
+     *   `GITLAB_CI=true` → `gitlab` (`section_start:` ANSI sequences),
+     *   `BUILDKITE=true` → `buildkite` (`---` collapsed headers),
+     *   `TF_BUILD=True` → `azure` (`##[group]`),
+     *   no grouping otherwise.
+     * - `off`: never group (raw separators only — useful when
+     *   piping through tools that mangle the directives).
+     * - `azure` / `buildkite` / `github` / `gitlab`: force the format
+     *   regardless of detected environment (useful for self-hosted
+     *   runners that don't set the standard env vars).
+     *
+     * CircleCI is intentionally not auto-detected: its 2.0+ format
+     * has no inline grouping directive — steps auto-group in the
+     * web UI without any markup from the runner.
+     */
     ciGrouping?: "auto" | "azure" | "buildkite" | "github" | "gitlab" | "off";
     /**
-    * Stay quiet when a run succeeds. When enabled:
-    * - non-interactive output suppresses successful and cached tasks
-    *   and prints only failures (failed tasks always render in full —
-    *   in CI as expanded log blocks), equivalent to
-    *   `--output-style=quiet`; and
-    * - the interactive TUI auto-closes a few seconds after a clean run
-    *   via a countdown dialog. A run with any failure stays open so the
-    *   user can inspect it.
-    *
-    * The explicit `--output-style` CLI flag overrides the output side,
-    * a per-target `options.outputStyle` overrides both, and
-    * `tui.autoExit` overrides the auto-close countdown.
-    *
-    * Default: `false` — every task's output is echoed and the TUI waits
-    * for the user. Set to `true` to opt into quiet, auto-closing runs.
-    */
+     * Stay quiet when a run succeeds. When enabled:
+     * - non-interactive output suppresses successful and cached tasks
+     *   and prints only failures (failed tasks always render in full —
+     *   in CI as expanded log blocks), equivalent to
+     *   `--output-style=quiet`; and
+     * - the interactive TUI auto-closes a few seconds after a clean run
+     *   via a countdown dialog. A run with any failure stays open so the
+     *   user can inspect it.
+     *
+     * The explicit `--output-style` CLI flag overrides the output side,
+     * a per-target `options.outputStyle` overrides both, and
+     * `tui.autoExit` overrides the auto-close countdown.
+     *
+     * Default: `false` — every task's output is echoed and the TUI waits
+     * for the user. Set to `true` to opt into quiet, auto-closing runs.
+     */
     quietOnSuccess?: boolean;
     /**
-    * One knob controlling auto-start of missing service deps.
-    * - `auto` (default in TTY): pick by task — `dev` → ephemeral,
-    *   others → persistent.
-    * - `ephemeral`: services die with the run (no registry entry).
-    * - `persistent`: services persist across runs in the registry.
-    * - `off` (default in CI / non-TTY): print diagnostics and abort.
-    */
+     * One knob controlling auto-start of missing service deps.
+     * - `auto` (default in TTY): pick by task — `dev` → ephemeral,
+     *   others → persistent.
+     * - `ephemeral`: services die with the run (no registry entry).
+     * - `persistent`: services persist across runs in the registry.
+     * - `off` (default in CI / non-TTY): print diagnostics and abort.
+     */
     services?: "auto" | "ephemeral" | "off" | "persistent";
   };
   /**
-  * Target JS runtime for this workspace/project — `"node"` (default) or
-  * `"bun"`. Overridden by the `--runtime` flag and the `VIS_RUNTIME` env
-  * var; falls back to lockfile detection when unset. Part of the
-  * cross-runtime multi-tool (see `rfc/design-runtime-multitool.md`).
-  */
+   * Target JS runtime for this workspace/project — `"node"` (default) or
+   * `"bun"`. Overridden by the `--runtime` flag and the `VIS_RUNTIME` env
+   * var; falls back to lockfile detection when unset. Part of the
+   * cross-runtime multi-tool (see `rfc/design-runtime-multitool.md`).
+   */
   runtime?: RuntimeId;
   /**
-  * Cascading scoped-task blocks. Each block may narrow its tasks to a
-  * subset of projects via `match`. Blocks are evaluated in order; later
-  * blocks override earlier ones when the same field is set.
-  *
-  * Match predicates are additive — if `match` is omitted, the block applies
-  * to every project.
-  * @example
-  * ```
-  * scopedTasks: [
-  *   { match: { tags: ["frontend"] }, tasks: { build: { cache: true } } },
-  *   { match: { projectType: "library" }, tasks: { lint: { cache: true } } },
-  * ]
-  * ```
-  */
+   * Cascading scoped-task blocks. Each block may narrow its tasks to a
+   * subset of projects via `match`. Blocks are evaluated in order; later
+   * blocks override earlier ones when the same field is set.
+   *
+   * Match predicates are additive — if `match` is omitted, the block applies
+   * to every project.
+   * @example
+   * ```
+   * scopedTasks: [
+   *   { match: { tags: ["frontend"] }, tasks: { build: { cache: true } } },
+   *   { match: { projectType: "library" }, tasks: { lint: { cache: true } } },
+   * ]
+   * ```
+   */
   scopedTasks?: ScopedTasksBlock[];
   /**
-  * Default options for `vis secrets`. CLI flags always take precedence;
-  * this block provides workspace-wide defaults so teams can commit config
-  * once and every invocation picks it up.
-  */
+   * Default options for `vis secrets`. CLI flags always take precedence;
+   * this block provides workspace-wide defaults so teams can commit config
+   * once and every invocation picks it up.
+   */
   secrets?: {
     /** Path to a baseline of previously-triaged findings (relative to workspace root). */
     baseline?: string;
@@ -1702,13 +1710,13 @@ interface VisConfig {
     /** Walker / filesystem traversal. */
     walk?: {
       /**
-      * Paths to additional `.gitignore`-syntax files (e.g. `.secretsignore`).
-      */
+       * Paths to additional `.gitignore`-syntax files (e.g. `.secretsignore`).
+       */
       excludeFromFiles?: string[];
       /**
-      * Gitignore-syntax patterns (supports negation, directory markers, leading `/`).
-      * Applied on top of `.gitignore`.
-      */
+       * Gitignore-syntax patterns (supports negation, directory markers, leading `/`).
+       * Applied on top of `.gitignore`.
+       */
       excludePatterns?: string[];
       /** Respect `.gitignore`. Default: `true`. */
       gitignore?: boolean;
@@ -1719,182 +1727,182 @@ interface VisConfig {
     };
   };
   /**
-  * Supply chain security settings.
-  * These settings are inspired by pnpm's security features and are applied
-  * universally across all package managers (pnpm, npm, yarn, bun).
-  *
-  * For pnpm users: these map directly to pnpm-workspace.yaml settings.
-  * For npm/yarn/bun users: vis enforces these at the vis layer since
-  * those package managers lack native support.
-  */
+   * Supply chain security settings.
+   * These settings are inspired by pnpm's security features and are applied
+   * universally across all package managers (pnpm, npm, yarn, bun).
+   *
+   * For pnpm users: these map directly to pnpm-workspace.yaml settings.
+   * For npm/yarn/bun users: vis enforces these at the vis layer since
+   * those package managers lack native support.
+   */
   security?: {
     /**
-    * Packages whose policy findings have been reviewed and explicitly
-    * accepted. Matched against every policy unless `policies` narrows the
-    * scope. Replaces the legacy `security.socket.acceptedRisks` map.
-    *
-    * Key format: package name (`"lodash"`), name@version
-    * (`"lodash@4.17.21"`), or glob (`"@myorg/*"`). Unversioned keys match
-    * all versions of that package.
-    * @example
-    * ```
-    * acceptedRisks: {
-    *   "some-risky-pkg": {
-    *     reason: "Internal fork, low score expected",
-    *     acceptedAt: "2026-03-15T10:00:00Z",
-    *     acceptedScore: 0.25,
-    *     policies: ["score"],
-    *     expiresAt: "2026-12-31",
-    *   },
-    * }
-    * ```
-    */
+     * Packages whose policy findings have been reviewed and explicitly
+     * accepted. Matched against every policy unless `policies` narrows the
+     * scope. Replaces the legacy `security.socket.acceptedRisks` map.
+     *
+     * Key format: package name (`"lodash"`), name@version
+     * (`"lodash@4.17.21"`), or glob (`"@myorg/*"`). Unversioned keys match
+     * all versions of that package.
+     * @example
+     * ```
+     * acceptedRisks: {
+     *   "some-risky-pkg": {
+     *     reason: "Internal fork, low score expected",
+     *     acceptedAt: "2026-03-15T10:00:00Z",
+     *     acceptedScore: 0.25,
+     *     policies: ["score"],
+     *     expiresAt: "2026-12-31",
+     *   },
+     * }
+     * ```
+     */
     acceptedRisks?: Record<string, {
       /** ISO 8601 timestamp when the risk was accepted. */
       acceptedAt: string;
       /**
-      * The overall Socket.dev score at the time of acceptance,
-      * in the range `[0, 1]` (mirrors `policies.score.minimum`).
-      * Only relevant for the `score` policy; ignored elsewhere.
-      */
+       * The overall Socket.dev score at the time of acceptance,
+       * in the range `[0, 1]` (mirrors `policies.score.minimum`).
+       * Only relevant for the `score` policy; ignored elsewhere.
+       */
       acceptedScore?: number;
       /**
-      * ISO 8601 date (or datetime). After this point the acceptance
-      * stops applying and vis emits a warning. Leave undefined for
-      * non-expiring entries. Values that fail to parse as a Date
-      * are rejected by the loader rather than silently treated as
-      * "always expired".
-      */
+       * ISO 8601 date (or datetime). After this point the acceptance
+       * stops applying and vis emits a warning. Leave undefined for
+       * non-expiring entries. Values that fail to parse as a Date
+       * are rejected by the loader rather than silently treated as
+       * "always expired".
+       */
       expiresAt?: string;
       /**
-      * Which policies this acceptance covers. When undefined the
-      * acceptance applies to every policy finding on this package.
-      */
+       * Which policies this acceptance covers. When undefined the
+       * acceptance applies to every policy finding on this package.
+       */
       policies?: PolicyName[];
       /** User-provided reason for accepting the risk. */
       reason: string;
     }>;
     /**
-    * Map of bin names (or `pkg#bin` qualifiers) blessed for shadowing.
-    * When two installed packages expose the same bin name, vis flags
-    * the collision in `vis security list` and the post-install drift
-    * report — set the bin (or `pkg#bin`) to `true` here to suppress
-    * the warning once you've reviewed the conflict.
-    *
-    * Port of LavaMoat allow-scripts' experimental `allowBins`.
-    * Bare names match any conflicting bin with that name; the
-    * `pkg#bin` form scopes the approval to a single package's bin.
-    * @example
-    * ```
-    * allowBins: {
-    *   tsc: true,                // bless any 'tsc' bin
-    *   "typescript#tsc": true,   // bless only typescript's 'tsc'
-    * }
-    * ```
-    */
+     * Map of bin names (or `pkg#bin` qualifiers) blessed for shadowing.
+     * When two installed packages expose the same bin name, vis flags
+     * the collision in `vis security list` and the post-install drift
+     * report — set the bin (or `pkg#bin`) to `true` here to suppress
+     * the warning once you've reviewed the conflict.
+     *
+     * Port of LavaMoat allow-scripts' experimental `allowBins`.
+     * Bare names match any conflicting bin with that name; the
+     * `pkg#bin` form scopes the approval to a single package's bin.
+     * @example
+     * ```
+     * allowBins: {
+     *   tsc: true,                // bless any 'tsc' bin
+     *   "typescript#tsc": true,   // bless only typescript's 'tsc'
+     * }
+     * ```
+     */
     allowBins?: Record<string, boolean>;
     /**
-    * Offline OSV advisory + `vis audit` configuration.
-    *
-    * Controls `vis audit --offline` and `vis advisories sync` behavior:
-    * - `audit.advisories.source` is the OSV mirror to download from. It
-    *   must be `https://` and resolve to a host in `allowedHosts` (or one
-    *   of the built-in defaults).
-    * - `audit.offlineByDefault` flips the default of `--offline`.
-    *
-    * Vulnerability severity gating and reachability filtering live under
-    * `policies.vulnerability` (see below).
-    */
+     * Offline OSV advisory + `vis audit` configuration.
+     *
+     * Controls `vis audit --offline` and `vis advisories sync` behavior:
+     * - `audit.advisories.source` is the OSV mirror to download from. It
+     *   must be `https://` and resolve to a host in `allowedHosts` (or one
+     *   of the built-in defaults).
+     * - `audit.offlineByDefault` flips the default of `--offline`.
+     *
+     * Vulnerability severity gating and reachability filtering live under
+     * `policies.vulnerability` (see below).
+     */
     audit?: {
       /**
-      * Offline advisory cache settings.
-      */
+       * Offline advisory cache settings.
+       */
       advisories?: {
         /**
-        * Extra hosts permitted as `audit.advisories.source`. The
-        * built-in allowlist is enforced even if this field is
-        * omitted; entries here add to it.
-        * @example ["mirror.corp.example.com"]
-        */
+         * Extra hosts permitted as `audit.advisories.source`. The
+         * built-in allowlist is enforced even if this field is
+         * omitted; entries here add to it.
+         * @example ["mirror.corp.example.com"]
+         */
         allowedHosts?: string[];
         /**
-        * Bloom-filter prefilter for OSV `MAL-*` (malicious-package)
-        * advisories. Probes a ~380 KB filter fetched from
-        * `endevco/osv-bloom` and escalates hits to the existing
-        * advisory query path for `(name, version)` confirmation.
-        *
-        * Cost: ~380 KB on the wire, refreshed every 10 minutes
-        * upstream. False-positive rate is ~0.1%, so a typical
-        * 1000-package lockfile triggers zero or one extra
-        * round trip per audit.
-        *
-        * Independent of `audit.advisories.source` / `verify` —
-        * those control the full OSV ingest. The bloom is
-        * MAL-* only and aimed at cold-start preflight and
-        * ephemeral CI runners that haven't synced the full DB.
-        */
+         * Bloom-filter prefilter for OSV `MAL-*` (malicious-package)
+         * advisories. Probes a ~380 KB filter fetched from
+         * `endevco/osv-bloom` and escalates hits to the existing
+         * advisory query path for `(name, version)` confirmation.
+         *
+         * Cost: ~380 KB on the wire, refreshed every 10 minutes
+         * upstream. False-positive rate is ~0.1%, so a typical
+         * 1000-package lockfile triggers zero or one extra
+         * round trip per audit.
+         *
+         * Independent of `audit.advisories.source` / `verify` —
+         * those control the full OSV ingest. The bloom is
+         * MAL-* only and aimed at cold-start preflight and
+         * ephemeral CI runners that haven't synced the full DB.
+         */
         bloom?: {
           /**
-          * Extra hosts permitted as `bloom.source`. The
-          * built-in allowlist (`endevco.github.io`) is enforced
-          * even if this field is omitted; entries here add to it.
-          */
+           * Extra hosts permitted as `bloom.source`. The
+           * built-in allowlist (`endevco.github.io`) is enforced
+           * even if this field is omitted; entries here add to it.
+           */
           allowedHosts?: string[];
           /**
-          * Prefilter mode:
-          * - `off`: never run the bloom check.
-          * - `on`: run when a local filter is cached; on
-          *   fetch failure, fall back to the cached filter or
-          *   skip the prefilter (audit continues against the
-          *   non-bloom path).
-          * - `required`: hard-fail the audit when the bloom
-          *   refresh fails or the local cache is missing.
-          *   Use in hardened CI together with
-          *   `audit.advisories.source`.
-          * @default "off"
-          */
+           * Prefilter mode:
+           * - `off`: never run the bloom check.
+           * - `on`: run when a local filter is cached; on
+           *   fetch failure, fall back to the cached filter or
+           *   skip the prefilter (audit continues against the
+           *   non-bloom path).
+           * - `required`: hard-fail the audit when the bloom
+           *   refresh fails or the local cache is missing.
+           *   Use in hardened CI together with
+           *   `audit.advisories.source`.
+           * @default "off"
+           */
           mode?: "off" | "on" | "required";
           /**
-          * Bloom mirror base URL (no trailing slash). Defaults
-          * to the public `endevco/osv-bloom` GH Pages site.
-          * Override only if you mirror the bloom artifacts
-          * internally; the hostname must appear in
-          * `allowedHosts`.
-          * @default "https://endevco.github.io/osv-bloom"
-          */
+           * Bloom mirror base URL (no trailing slash). Defaults
+           * to the public `endevco/osv-bloom` GH Pages site.
+           * Override only if you mirror the bloom artifacts
+           * internally; the hostname must appear in
+           * `allowedHosts`.
+           * @default "https://endevco.github.io/osv-bloom"
+           */
           source?: string;
         };
         /**
-        * Number of hours after `lastSyncIso` before `vis audit`
-        * prints a "your advisory cache may be stale" notice.
-        * `vis audit` never auto-syncs — the user runs
-        * `vis advisories sync` themselves.
-        * @default 24
-        */
+         * Number of hours after `lastSyncIso` before `vis audit`
+         * prints a "your advisory cache may be stale" notice.
+         * `vis audit` never auto-syncs — the user runs
+         * `vis advisories sync` themselves.
+         * @default 24
+         */
         refreshIntervalHours?: number;
         /**
-        * OSV mirror base URL (no trailing slash). Defaults to the
-        * public Google Cloud Storage bucket. Override to point at a
-        * corporate mirror; the hostname must appear in `allowedHosts`
-        * (or one of the built-in defaults) and the scheme must be
-        * `https://`.
-        * @default "https://osv-vulnerabilities.storage.googleapis.com"
-        */
+         * OSV mirror base URL (no trailing slash). Defaults to the
+         * public Google Cloud Storage bucket. Override to point at a
+         * corporate mirror; the hostname must appear in `allowedHosts`
+         * (or one of the built-in defaults) and the scheme must be
+         * `https://`.
+         * @default "https://osv-vulnerabilities.storage.googleapis.com"
+         */
         source?: string;
         /**
-        * Sigstore signature verification for the OSV dump.
-        * Requires the native binding to be built with the
-        * `verify-signatures` Cargo feature (default in the release
-        * build). Off by default — the upstream OSV bucket does not
-        * ship signatures today.
-        */
+         * Sigstore signature verification for the OSV dump.
+         * Requires the native binding to be built with the
+         * `verify-signatures` Cargo feature (default in the release
+         * build). Off by default — the upstream OSV bucket does not
+         * ship signatures today.
+         */
         verify?: {
           /**
-          * Enable signature verification. The sync flow downloads
-          * `&lt;eco>/all.zip.sig` next to the zip and aborts if it
-          * cannot verify against `expectedIssuer` / `expectedSubject`.
-          * @default false
-          */
+           * Enable signature verification. The sync flow downloads
+           * `&lt;eco>/all.zip.sig` next to the zip and aborts if it
+           * cannot verify against `expectedIssuer` / `expectedSubject`.
+           * @default false
+           */
           enabled?: boolean;
           /** OIDC issuer that signed the bundle. */
           expectedIssuer?: string;
@@ -1903,111 +1911,111 @@ interface VisConfig {
         };
       };
       /**
-      * Gates for the auto-fix flow (`vis audit --fix` /
-      * `--fix-transitive`). The CLI prompts outside CI; inside CI
-      * the flags refuse to run unless `--yes` is set and, for
-      * transitives, `apply.transitive.enabled = true`.
-      */
+       * Gates for the auto-fix flow (`vis audit --fix` /
+       * `--fix-transitive`). The CLI prompts outside CI; inside CI
+       * the flags refuse to run unless `--yes` is set and, for
+       * transitives, `apply.transitive.enabled = true`.
+       */
       apply?: {
         /**
-        * Gates for `vis audit --fix-transitive`. Two-lock: the
-        * CLI requires `--yes` AND this flag set to `true` before
-        * it will rewrite override entries in CI.
-        */
+         * Gates for `vis audit --fix-transitive`. Two-lock: the
+         * CLI requires `--yes` AND this flag set to `true` before
+         * it will rewrite override entries in CI.
+         */
         transitive?: {
           /**
-          * When true, allows `--fix-transitive` to run in CI
-          * environments. Defaults to false because rewriting
-          * overrides is a higher blast radius than bumping a
-          * direct dep.
-          * @default false
-          */
+           * When true, allows `--fix-transitive` to run in CI
+           * environments. Defaults to false because rewriting
+           * overrides is a higher blast radius than bumping a
+           * direct dep.
+           * @default false
+           */
           enabled?: boolean;
         };
       };
       /**
-      * Vulnerability scanner backend.
-      *
-      * - `auto` (default): delegate to `aube audit` when aube is the
-      *   active installer (its scanner reads the same lockfile and
-      *   produces equivalent severity ratings); otherwise run vis's
-      *   own OSV/Socket scanner.
-      * - `aube`: always delegate to `aube audit`. Errors if `aube` is
-      *   not on PATH.
-      * - `vis`: always use vis's built-in scanner — never delegate.
-      *
-      * Delegation avoids redundant work (aube already has a
-      * full-fidelity audit pass that respects its own exclusions
-      * via `aube-workspace.yaml::auditConfig`) and lets users get
-      * a single, consistent result regardless of which entry point
-      * they invoke.
-      * @default "auto"
-      */
+       * Vulnerability scanner backend.
+       *
+       * - `auto` (default): delegate to `aube audit` when aube is the
+       *   active installer (its scanner reads the same lockfile and
+       *   produces equivalent severity ratings); otherwise run vis's
+       *   own OSV/Socket scanner.
+       * - `aube`: always delegate to `aube audit`. Errors if `aube` is
+       *   not on PATH.
+       * - `vis`: always use vis's built-in scanner — never delegate.
+       *
+       * Delegation avoids redundant work (aube already has a
+       * full-fidelity audit pass that respects its own exclusions
+       * via `aube-workspace.yaml::auditConfig`) and lets users get
+       * a single, consistent result regardless of which entry point
+       * they invoke.
+       * @default "auto"
+       */
       backend?: "aube" | "auto" | "vis";
       /**
-      * When true, `vis audit` skips network calls and queries the
-      * offline cache. Equivalent to the CLI `--offline` flag.
-      * @default false
-      */
+       * When true, `vis audit` skips network calls and queries the
+       * offline cache. Equivalent to the CLI `--offline` flag.
+       * @default false
+       */
       offlineByDefault?: boolean;
     };
     /**
-    * When true, prevents transitive dependencies from using exotic sources
-    * (git repositories, direct tarball URLs). Only direct dependencies may
-    * use such sources. Equivalent to pnpm's `blockExoticSubdeps`.
-    * @default false
-    */
+     * When true, prevents transitive dependencies from using exotic sources
+     * (git repositories, direct tarball URLs). Only direct dependencies may
+     * use such sources. Equivalent to pnpm's `blockExoticSubdeps`.
+     * @default false
+     */
     blockExoticSubdeps?: boolean;
     /**
-    * deps.dev (Google Open Source Insights) data-source configuration.
-    * Public, unauthenticated; pulls Scorecard data + advisories from
-    * `api.deps.dev`. Complements or replaces Socket.dev. Heavily cached.
-    * @see https://docs.deps.dev/api/v3/
-    */
+     * deps.dev (Google Open Source Insights) data-source configuration.
+     * Public, unauthenticated; pulls Scorecard data + advisories from
+     * `api.deps.dev`. Complements or replaces Socket.dev. Heavily cached.
+     * @see https://docs.deps.dev/api/v3/
+     */
     depsDev?: {
       /**
-      * Cache TTL for advisory entries (immutable once published). 7 days.
-      * @default 604800000
-      */
+       * Cache TTL for advisory entries (immutable once published). 7 days.
+       * @default 604800000
+       */
       advisoryCacheTtlMs?: number;
       /**
-      * Enable deps.dev scanning on install/update/check/audit commands.
-      * @default false
-      */
+       * Enable deps.dev scanning on install/update/check/audit commands.
+       * @default false
+       */
       enabled?: boolean;
       /**
-      * Cache TTL for OpenSSF Scorecard project data (refreshes weekly). 24 hours.
-      * @default 86400000
-      */
+       * Cache TTL for OpenSSF Scorecard project data (refreshes weekly). 24 hours.
+       * @default 86400000
+       */
       projectCacheTtlMs?: number;
       /**
-      * Request timeout in milliseconds.
-      * @default 15000
-      */
+       * Request timeout in milliseconds.
+       * @default 15000
+       */
       timeoutMs?: number;
       /**
-      * Cache TTL for npm version metadata (immutable). 7 days.
-      * @default 604800000
-      */
+       * Cache TTL for npm version metadata (immutable). 7 days.
+       * @default 604800000
+       */
       versionCacheTtlMs?: number;
     };
     /**
-    * Package names exempted from the `blockExoticSubdeps` check.
-    * Bare names and a trailing `*` glob (`@scope/*`) are supported.
-    * Use for an internal package legitimately published as a git or
-    * tarball dependency.
-    * @example ["@myorg/legacy", "internal-*"]
-    */
+     * Package names exempted from the `blockExoticSubdeps` check.
+     * Bare names and a trailing `*` glob (`@scope/*`) are supported.
+     * Use for an internal package legitimately published as a git or
+     * tarball dependency.
+     * @example ["@myorg/legacy", "internal-*"]
+     */
     exoticSubdepsAllow?: string[];
     /**
-    * Pre-install marshall pipeline — packument-derived supply-chain
-    * gates (author, provenance, s1ngularity, new-bin, metadata,
-    * downloads, expired-domains, signatures, archived-repo) that run before
-    * `vis add` / `vis install &lt;pkg>` / `vis update &lt;pkg>` hand off to
-    * the underlying package manager. Every entry is optional; omit a
-    * key and the marshall runs with defaults. Set `enabled: false`
-    * on a specific marshall to skip it without touching env vars.
-    */
+     * Pre-install marshall pipeline — packument-derived supply-chain
+     * gates (author, provenance, s1ngularity, new-bin, metadata,
+     * downloads, expired-domains, signatures, archived-repo) that run before
+     * `vis add` / `vis install &lt;pkg>` / `vis update &lt;pkg>` hand off to
+     * the underlying package manager. Every entry is optional; omit a
+     * key and the marshall runs with defaults. Set `enabled: false`
+     * on a specific marshall to skip it without touching env vars.
+     */
     marshalls?: {
       /** Archived-repo marshall (GitHub repository status). */
       archivedRepo?: {
@@ -2020,11 +2028,13 @@ interface VisConfig {
       };
       /** Author / publisher heuristics. */
       author?: {
-        allowlist?: string[]; /** Days since the publisher's last release before flagging as error. */
+        allowlist?: string[];
+        /** Days since the publisher's last release before flagging as error. */
         dormantErrorDays?: number;
         /** Days since the publisher's last release before flagging as warning. */
         dormantWarnDays?: number;
-        enabled?: boolean; /** Window for the "new publisher on an established package" check. */
+        enabled?: boolean;
+        /** Window for the "new publisher on an established package" check. */
         newPublisherWindowDays?: number;
         /** Days since the resolved version was published — error threshold. */
         recentVersionErrorDays?: number;
@@ -2039,7 +2049,8 @@ interface VisConfig {
       /** Monthly download-count floor. */
       downloads?: {
         allowlist?: string[];
-        enabled?: boolean; /** Below this monthly count → error (default: 20). */
+        enabled?: boolean;
+        /** Below this monthly count → error (default: 20). */
         errorThreshold?: number;
         /** Below this monthly count → warning (default: 1000). */
         warnThreshold?: number;
@@ -2048,14 +2059,17 @@ interface VisConfig {
       expiredDomains?: {
         /** Domains exempted from the check (legacy / internal). */
         allowDomains?: string[];
-        allowlist?: string[]; /** DNS resolvers to query (default: system). */
+        allowlist?: string[];
+        /** DNS resolvers to query (default: system). */
         dnsServers?: string[];
-        enabled?: boolean; /** Per-domain DNS timeout (default: 5000). */
+        enabled?: boolean;
+        /** Per-domain DNS timeout (default: 5000). */
         timeoutMs?: number;
       };
       /** README / license / repository presence checks. */
       metadata?: {
-        allowlist?: string[]; /** Subset of checks to run. Default: all three. */
+        allowlist?: string[];
+        /** Subset of checks to run. Default: all three. */
         checks?: ("license" | "readme" | "repo")[];
         enabled?: boolean;
       };
@@ -2067,7 +2081,8 @@ interface VisConfig {
       /** Whole-package age heuristics (newly created / unmaintained). */
       packageAge?: {
         allowlist?: string[];
-        enabled?: boolean; /** Package created fewer than this many days ago → error. Default 22. */
+        enabled?: boolean;
+        /** Package created fewer than this many days ago → error. Default 22. */
         newPackageDays?: number;
         /** No publish within this many days → warning. Default 365. */
         unmaintainedDays?: number;
@@ -2078,22 +2093,23 @@ interface VisConfig {
         enabled?: boolean;
       };
       /**
-      * Composite "compromised-publish shape" detector — flags a single
-      * version that simultaneously introduced/changed an install hook
-      * AND dropped the provenance attestation a prior stable version
-      * carried (the August 2025 s1ngularity / Nx fingerprint).
-      */
+       * Composite "compromised-publish shape" detector — flags a single
+       * version that simultaneously introduced/changed an install hook
+       * AND dropped the provenance attestation a prior stable version
+       * carried (the August 2025 s1ngularity / Nx fingerprint).
+       */
       s1ngularity?: {
         allowlist?: string[];
         enabled?: boolean;
       };
       /**
-      * ECDSA P-256 verification against npm's signing keys. Disabled
-      * by default because npm coverage still has gaps that produce
-      * noisy warnings on legitimate packages.
-      */
+       * ECDSA P-256 verification against npm's signing keys. Disabled
+       * by default because npm coverage still has gaps that produce
+       * noisy warnings on legitimate packages.
+       */
       signatures?: {
-        allowlist?: string[]; /** Default: marshall is *off*. Set true to enable. */
+        allowlist?: string[];
+        /** Default: marshall is *off*. Set true to enable. */
         enabled?: boolean;
         /** Override the keys endpoint (default: npm registry). */
         keysUrl?: string;
@@ -2102,313 +2118,313 @@ interface VisConfig {
       };
     };
     /**
-    * When true, `security.policies.installScripts.allow` keys are matched
-    * as `name@version`. A version bump on an approved package drops it from
-    * the allowlist until the new version is explicitly re-approved (port
-    * of LavaMoat allow-scripts' version-aware policy matcher).
-    *
-    * After a version bump, run `vis approve-builds` or `vis security list`
-    * — both surface a "Version drift" block with the suggested new key
-    * (`old-key  →  new-key`) so you can update `vis.config.ts` by hand.
-    * @default false
-    */
+     * When true, `security.policies.installScripts.allow` keys are matched
+     * as `name@version`. A version bump on an approved package drops it from
+     * the allowlist until the new version is explicitly re-approved (port
+     * of LavaMoat allow-scripts' version-aware policy matcher).
+     *
+     * After a version bump, run `vis approve-builds` or `vis security list`
+     * — both surface a "Version drift" block with the suggested new key
+     * (`old-key  →  new-key`) so you can update `vis.config.ts` by hand.
+     * @default false
+     */
     pinVersions?: boolean;
     /**
-    * Supply-chain policy gates. Each sub-block enables one policy and
-    * configures its behavior. When a sub-block is omitted the policy is
-    * inactive. `acceptedRisks` (above) silences specific packages without
-    * disabling a policy globally.
-    *
-    * The 8 policies are inspired by Socket.dev's classification:
-    * - `malware`            — Socket-flagged malicious packages
-    * - `firstSeen`         — packages published less than N minutes ago
-    * - `unexpectedDeps`    — packages outside an allow-list / baseline
-    * - `publisherChange`   — maintainer set changed between installs
-    * - `installScripts`    — preinstall/install/postinstall scripts
-    * - `score`              — Socket overall score below threshold
-    * - `vulnerability`      — OSV vulnerability findings
-    * - `license`            — SPDX allow / deny lists
-    */
+     * Supply-chain policy gates. Each sub-block enables one policy and
+     * configures its behavior. When a sub-block is omitted the policy is
+     * inactive. `acceptedRisks` (above) silences specific packages without
+     * disabling a policy globally.
+     *
+     * The 8 policies are inspired by Socket.dev's classification:
+     * - `malware`            — Socket-flagged malicious packages
+     * - `firstSeen`         — packages published less than N minutes ago
+     * - `unexpectedDeps`    — packages outside an allow-list / baseline
+     * - `publisherChange`   — maintainer set changed between installs
+     * - `installScripts`    — preinstall/install/postinstall scripts
+     * - `score`              — Socket overall score below threshold
+     * - `vulnerability`      — OSV vulnerability findings
+     * - `license`            — SPDX allow / deny lists
+     */
     policies?: {
       /**
-      * Minimum number of minutes that must pass after a version is
-      * published before vis will allow installation. Migrated from
-      * the legacy `security.minimumReleaseAge` field. Equivalent to
-      * pnpm's `minimumReleaseAge`.
-      * @default 0
-      * @example { minutes: 1440, exclude: ["@myorg/*"] } // 24 hours
-      */
+       * Minimum number of minutes that must pass after a version is
+       * published before vis will allow installation. Migrated from
+       * the legacy `security.minimumReleaseAge` field. Equivalent to
+       * pnpm's `minimumReleaseAge`.
+       * @default 0
+       * @example { minutes: 1440, exclude: ["@myorg/*"] } // 24 hours
+       */
       firstSeen?: {
         /**
-        * Package names/patterns excluded from the firstSeen check.
-        * Equivalent to pnpm's `minimumReleaseAgeExclude`.
-        * @example ["webpack", "react", "@myorg/*"]
-        */
+         * Package names/patterns excluded from the firstSeen check.
+         * Equivalent to pnpm's `minimumReleaseAgeExclude`.
+         * @example ["webpack", "react", "@myorg/*"]
+         */
         exclude?: string[];
         /** Minutes after publish before install is allowed. */
         minutes?: number;
       };
       /**
-      * Build-script (pre/install/postinstall/prepare) controls.
-      * Migrated from the legacy `security.allowBuilds` /
-      * `security.strictDepBuilds` fields.
-      * @example { allow: { esbuild: true }, strict: true }
-      */
+       * Build-script (pre/install/postinstall/prepare) controls.
+       * Migrated from the legacy `security.allowBuilds` /
+       * `security.strictDepBuilds` fields.
+       * @example { allow: { esbuild: true }, strict: true }
+       */
       installScripts?: {
         /**
-        * Map of package names/patterns to allow (true) or deny
-        * (false) build scripts. Packages not listed are denied
-        * by default. Equivalent to pnpm's `allowBuilds`.
-        */
+         * Map of package names/patterns to allow (true) or deny
+         * (false) build scripts. Packages not listed are denied
+         * by default. Equivalent to pnpm's `allowBuilds`.
+         */
         allow?: Record<string, boolean>;
         /**
-        * When true, installation will fail (exit non-zero) if any
-        * dependencies have unreviewed build scripts. Equivalent to
-        * pnpm's `strictDepBuilds`.
-        * @default false
-        */
+         * When true, installation will fail (exit non-zero) if any
+         * dependencies have unreviewed build scripts. Equivalent to
+         * pnpm's `strictDepBuilds`.
+         * @default false
+         */
         strict?: boolean;
       };
       /**
-      * SPDX license allow / deny lists. Deny wins on any sub-license
-      * match in SPDX expressions (`(MIT OR GPL-3.0)` against
-      * `deny: ["GPL-3.0"]` is blocked). Packages with no declared
-      * license are flagged when `allow` is set.
-      * @example
-      * ```
-      * license: {
-      *   allow: ["MIT", "Apache-2.0", "BSD-3-Clause"],
-      *   deny: ["GPL-3.0", "AGPL-3.0"],
-      * }
-      * ```
-      */
+       * SPDX license allow / deny lists. Deny wins on any sub-license
+       * match in SPDX expressions (`(MIT OR GPL-3.0)` against
+       * `deny: ["GPL-3.0"]` is blocked). Packages with no declared
+       * license are flagged when `allow` is set.
+       * @example
+       * ```
+       * license: {
+       *   allow: ["MIT", "Apache-2.0", "BSD-3-Clause"],
+       *   deny: ["GPL-3.0", "AGPL-3.0"],
+       * }
+       * ```
+       */
       license?: {
         /**
-        * SPDX identifiers that are explicitly permitted. When set,
-        * any package whose declared license is not on this list is
-        * blocked.
-        */
+         * SPDX identifiers that are explicitly permitted. When set,
+         * any package whose declared license is not on this list is
+         * blocked.
+         */
         allow?: string[];
         /**
-        * SPDX identifiers that are explicitly forbidden. Always
-        * wins over `allow` when both reference the same identifier.
-        */
+         * SPDX identifiers that are explicitly forbidden. Always
+         * wins over `allow` when both reference the same identifier.
+         */
         deny?: string[];
       };
       /**
-      * Behavior when the Socket.dev feed flags a package as malicious
-      * (`alerts[].type === "Malware"`).
-      *
-      * The default is cross-field: `{ mode: "block" }` whenever
-      * `security.socket.enabled !== false` (the engine cannot evaluate
-      * malware without Socket data), and `"off"` otherwise. Consumers
-      * resolve this default at evaluation time.
-      */
+       * Behavior when the Socket.dev feed flags a package as malicious
+       * (`alerts[].type === "Malware"`).
+       *
+       * The default is cross-field: `{ mode: "block" }` whenever
+       * `security.socket.enabled !== false` (the engine cannot evaluate
+       * malware without Socket data), and `"off"` otherwise. Consumers
+       * resolve this default at evaluation time.
+       */
       malware?: {
         /**
-        * - `"block"` — emit a block decision.
-        * - `"warn"`  — surface as a warning; do not gate exit code.
-        * - `"off"`   — disable the policy entirely.
-        */
+         * - `"block"` — emit a block decision.
+         * - `"warn"`  — surface as a warning; do not gate exit code.
+         * - `"off"`   — disable the policy entirely.
+         */
         mode?: "block" | "off" | "warn";
       };
       /**
-      * Trust-level checking for package publishing. Migrated from the
-      * legacy `security.trustPolicy*` fields. Equivalent to pnpm's
-      * `trustPolicy`.
-      * @example { mode: "no-downgrade", ignoreAfter: 43200 } // 30 days
-      */
+       * Trust-level checking for package publishing. Migrated from the
+       * legacy `security.trustPolicy*` fields. Equivalent to pnpm's
+       * `trustPolicy`.
+       * @example { mode: "no-downgrade", ignoreAfter: 43200 } // 30 days
+       */
       publisherChange?: {
         /**
-        * Package selectors excluded from the check.
-        * Equivalent to pnpm's `trustPolicyExclude`.
-        * @example ["chokidar@4.0.3"]
-        */
+         * Package selectors excluded from the check.
+         * Equivalent to pnpm's `trustPolicyExclude`.
+         * @example ["chokidar@4.0.3"]
+         */
         exclude?: string[];
         /**
-        * Ignore packages published more than N minutes ago. Useful
-        * for older packages that pre-date provenance support.
-        * Equivalent to pnpm's `trustPolicyIgnoreAfter`.
-        */
+         * Ignore packages published more than N minutes ago. Useful
+         * for older packages that pre-date provenance support.
+         * Equivalent to pnpm's `trustPolicyIgnoreAfter`.
+         */
         ignoreAfter?: number;
         /**
-        * - `"off"`           — no trust checking (default).
-        * - `"no-downgrade"`  — block when a package's trust level
-        *   has decreased compared to previous releases (e.g., was
-        *   published by trusted publisher, now only has provenance).
-        */
+         * - `"off"`           — no trust checking (default).
+         * - `"no-downgrade"`  — block when a package's trust level
+         *   has decreased compared to previous releases (e.g., was
+         *   published by trusted publisher, now only has provenance).
+         */
         mode?: "no-downgrade" | "off";
       };
       /**
-      * Socket.dev overall-score threshold. Packages scoring below
-      * `minimum` trigger a block decision (or interactive prompt
-      * during `vis add`). Migrated from the legacy
-      * `security.socket.minimumScore` field.
-      * @example { minimum: 0.4 }
-      */
+       * Socket.dev overall-score threshold. Packages scoring below
+       * `minimum` trigger a block decision (or interactive prompt
+       * during `vis add`). Migrated from the legacy
+       * `security.socket.minimumScore` field.
+       * @example { minimum: 0.4 }
+       */
       score?: {
         /**
-        * Minimum overall Socket.dev score (0–1). Set to 0 to
-        * disable the gate while keeping Socket data fetched.
-        *
-        * Consulted by `vis add`, `audit`, `doctor`, `check`, and
-        * `update`; resolved once in `buildSocketOptions`, then
-        * threaded through every consumer. Falls back to
-        * `DEFAULT_LOW_SCORE_THRESHOLD` (`0.4`) when unset.
-        */
+         * Minimum overall Socket.dev score (0–1). Set to 0 to
+         * disable the gate while keeping Socket data fetched.
+         *
+         * Consulted by `vis add`, `audit`, `doctor`, `check`, and
+         * `update`; resolved once in `buildSocketOptions`, then
+         * threaded through every consumer. Falls back to
+         * `DEFAULT_LOW_SCORE_THRESHOLD` (`0.4`) when unset.
+         */
         minimum?: number;
       };
       /**
-      * Net-new transitive dependency detection. Either provide a
-      * static allow-list, a baseline lockfile path (recommended), or
-      * both — the intersection is enforced.
-      * @example { baselineLockfile: "./security/lockfile.baseline.yaml" }
-      */
+       * Net-new transitive dependency detection. Either provide a
+       * static allow-list, a baseline lockfile path (recommended), or
+       * both — the intersection is enforced.
+       * @example { baselineLockfile: "./security/lockfile.baseline.yaml" }
+       */
       unexpectedDeps?: {
         /**
-        * Allow-list of dependency names that may appear in the
-        * resolved package set. Glob patterns are supported.
-        * @example ["lodash", "axios", "@myorg/*"]
-        */
+         * Allow-list of dependency names that may appear in the
+         * resolved package set. Glob patterns are supported.
+         * @example ["lodash", "axios", "@myorg/*"]
+         */
         allow?: string[];
         /**
-        * Path (absolute or relative to the workspace root) to a
-        * baseline lockfile snapshot. The policy diffs the current
-        * lockfile against this baseline and flags any package that
-        * didn't exist before.
-        * @example "./security/lockfile.baseline.yaml"
-        */
+         * Path (absolute or relative to the workspace root) to a
+         * baseline lockfile snapshot. The policy diffs the current
+         * lockfile against this baseline and flags any package that
+         * didn't exist before.
+         * @example "./security/lockfile.baseline.yaml"
+         */
         baselineLockfile?: string;
       };
       /**
-      * OSV vulnerability gating. Migrated from the legacy
-      * `security.audit.failOn` + `security.audit.usage` fields.
-      */
+       * OSV vulnerability gating. Migrated from the legacy
+       * `security.audit.failOn` + `security.audit.usage` fields.
+       */
       vulnerability?: {
         /**
-        * Severity threshold that makes `vis audit` exit non-zero.
-        * Equivalent to the CLI `--fail-on` flag.
-        * @example "high"
-        */
+         * Severity threshold that makes `vis audit` exit non-zero.
+         * Equivalent to the CLI `--fail-on` flag.
+         * @example "high"
+         */
         failOn?: "critical" | "high" | "low" | "medium";
         /**
-        * Reachability filter — only report vulnerabilities in
-        * packages the workspace statically imports.
-        */
+         * Reachability filter — only report vulnerabilities in
+         * packages the workspace statically imports.
+         */
         usage?: {
           /**
-          * Packages to always treat as reachable even if no
-          * static import is found.
-          * @example ["esbuild", "webpack-cli"]
-          */
+           * Packages to always treat as reachable even if no
+           * static import is found.
+           * @example ["esbuild", "webpack-cli"]
+           */
           alwaysAssumeUsed?: string[];
           /**
-          * Enable the reachability filter by default. Equivalent
-          * to `--usage` on the CLI; `--no-usage` disables.
-          * @default false
-          */
+           * Enable the reachability filter by default. Equivalent
+           * to `--usage` on the CLI; `--no-usage` disables.
+           * @default false
+           */
           enabled?: boolean;
         };
       };
     };
     /**
-    * Which provider wins merge conflicts when multiple are enabled (e.g.
-    * both Socket.dev and deps.dev return data for the same package). The
-    * primary provider's `score` is kept; alerts from secondaries are
-    * appended and deduped by `key`. Defaults to whichever provider is
-    * enabled first in this order: socket → deps-dev → snyk.
-    */
+     * Which provider wins merge conflicts when multiple are enabled (e.g.
+     * both Socket.dev and deps.dev return data for the same package). The
+     * primary provider's `score` is kept; alerts from secondaries are
+     * appended and deduped by `key`. Defaults to whichever provider is
+     * enabled first in this order: socket → deps-dev → snyk.
+     */
     primaryProvider?: "deps-dev" | "snyk" | "socket";
     /**
-    * Snyk data-source configuration. Snyk only contributes vulnerability
-    * data (no maintenance / quality / supply-chain / license signal);
-    * those axes stay neutral. Requires both an org id and an API token —
-    * if either is missing the provider is skipped.
-    * @see https://docs.snyk.io/snyk-api/using-specific-snyk-apis/issues-list-issues-for-a-package
-    */
+     * Snyk data-source configuration. Snyk only contributes vulnerability
+     * data (no maintenance / quality / supply-chain / license signal);
+     * those axes stay neutral. Requires both an org id and an API token —
+     * if either is missing the provider is skipped.
+     * @see https://docs.snyk.io/snyk-api/using-specific-snyk-apis/issues-list-issues-for-a-package
+     */
     snyk?: {
       /**
-      * Snyk API token. Set via VIS_SNYK_TOKEN environment variable or
-      * here.
-      */
+       * Snyk API token. Set via VIS_SNYK_TOKEN environment variable or
+       * here.
+       */
       apiToken?: string;
       /**
-      * Snyk REST API version date sent as the `version` query param.
-      * @default "2024-10-15"
-      */
+       * Snyk REST API version date sent as the `version` query param.
+       * @default "2024-10-15"
+       */
       apiVersion?: string;
       /**
-      * Cache TTL in milliseconds for Snyk issue lookups. 6 hours.
-      * @default 21600000
-      */
+       * Cache TTL in milliseconds for Snyk issue lookups. 6 hours.
+       * @default 21600000
+       */
       cacheTtlMs?: number;
       /**
-      * Enable Snyk security scanning on install/update/check/audit
-      * commands.
-      * @default false
-      */
+       * Enable Snyk security scanning on install/update/check/audit
+       * commands.
+       * @default false
+       */
       enabled?: boolean;
       /**
-      * Snyk organization id (the REST endpoint is org-scoped). Set via
-      * VIS_SNYK_ORG environment variable or here.
-      */
+       * Snyk organization id (the REST endpoint is org-scoped). Set via
+       * VIS_SNYK_ORG environment variable or here.
+       */
       orgId?: string;
       /**
-      * Request timeout in milliseconds for the Snyk API. 15 seconds.
-      * @default 15000
-      */
+       * Request timeout in milliseconds for the Snyk API. 15 seconds.
+       * @default 15000
+       */
       timeoutMs?: number;
     };
     /**
-    * Socket.dev data-source configuration. Connection knobs only — score
-    * thresholds and accepted-risk overrides moved to `policies.score` and
-    * `security.acceptedRisks` respectively.
-    * @see https://socket.dev
-    */
+     * Socket.dev data-source configuration. Connection knobs only — score
+     * thresholds and accepted-risk overrides moved to `policies.score` and
+     * `security.acceptedRisks` respectively.
+     * @see https://socket.dev
+     */
     socket?: {
       /**
-      * Custom Socket.dev API token. Falls back to the public API token.
-      * Set via VIS_SOCKET_TOKEN environment variable or here.
-      */
+       * Custom Socket.dev API token. Falls back to the public API token.
+       * Set via VIS_SOCKET_TOKEN environment variable or here.
+       */
       apiToken?: string;
       /**
-      * Cache TTL in milliseconds for Socket.dev reports. 1 hour.
-      * @default 3600000
-      */
+       * Cache TTL in milliseconds for Socket.dev reports. 1 hour.
+       * @default 3600000
+       */
       cacheTtlMs?: number;
       /**
-      * Enable Socket.dev security scanning on install/update/check commands.
-      * @default false
-      */
+       * Enable Socket.dev security scanning on install/update/check commands.
+       * @default false
+       */
       enabled?: boolean;
       /**
-      * Request timeout in milliseconds for the Socket.dev API. 15 seconds.
-      * @default 15000
-      */
+       * Request timeout in milliseconds for the Socket.dev API. 15 seconds.
+       * @default 15000
+       */
       timeoutMs?: number;
     };
     /**
-    * Package names to skip during typosquat detection.
-    * Use this for internal packages or known-safe names that happen to
-    * look similar to popular packages.
-    * @example ["my-internal-axois", "@myorg/recat"]
-    */
+     * Package names to skip during typosquat detection.
+     * Use this for internal packages or known-safe names that happen to
+     * look similar to popular packages.
+     * @example ["my-internal-axois", "@myorg/recat"]
+     */
     typosquatAllowlist?: string[];
   };
   /**
-  * Share the cache between sibling git worktrees. When the workspace is a
-  * linked worktree (created with `git worktree add`), the cache root is
-  * relocated from `&lt;linkedRoot>/node_modules/.cache/vis` to the *main*
-  * worktree's `node_modules/.cache/vis`. Multiple parallel agents working in
-  * sibling worktrees then share a single cache instead of rebuilding the
-  * same hash N times.
-  *
-  * Single-checkout repos (where `.git` is a directory) are unaffected.
-  *
-  * Set to `false` to opt out — useful when worktrees deliberately need
-  * independent caches, e.g. for hermetic experiments.
-  * @default true
-  */
+   * Share the cache between sibling git worktrees. When the workspace is a
+   * linked worktree (created with `git worktree add`), the cache root is
+   * relocated from `&lt;linkedRoot>/node_modules/.cache/vis` to the *main*
+   * worktree's `node_modules/.cache/vis`. Multiple parallel agents working in
+   * sibling worktrees then share a single cache instead of rebuilding the
+   * same hash N times.
+   *
+   * Single-checkout repos (where `.git` is a directory) are unaffected.
+   *
+   * Set to `false` to opt out — useful when worktrees deliberately need
+   * independent caches, e.g. for hermetic experiments.
+   * @default true
+   */
   sharedWorktreeCache?: boolean;
   /** sort-package-json command defaults */
   sortPackageJson?: {
@@ -2424,55 +2440,55 @@ interface VisConfig {
     sortScripts?: boolean;
   };
   /**
-  * Sponsorship notice shown after successful commands.
-  *
-  * vis prints a one-line "consider sponsoring visulima" notice at most
-  * once every 14 days (skipped in CI, non-TTY, and when
-  * `VIS_NO_SPONSOR=1` is set). Set `enabled: false` to silence it
-  * permanently for this workspace.
-  * @example
-  * ```
-  * sponsor: { enabled: false }
-  * ```
-  */
+   * Sponsorship notice shown after successful commands.
+   *
+   * vis prints a one-line "consider sponsoring visulima" notice at most
+   * once every 14 days (skipped in CI, non-TTY, and when
+   * `VIS_NO_SPONSOR=1` is set). Set `enabled: false` to silence it
+   * permanently for this workspace.
+   * @example
+   * ```
+   * sponsor: { enabled: false }
+   * ```
+   */
   sponsor?: {
     /**
-    * Show the sponsor notice on successful command completion.
-    * @default true
-    */
+     * Show the sponsor notice on successful command completion.
+     * @default true
+     */
     enabled?: boolean;
   };
   /**
-  * Staged file patterns and commands (replaces lint-staged).
-  *
-  * Accepts all lint-staged config forms:
-  * - `string` or `string[]` commands
-  * - Sync/async functions returning `string | string[]`
-  * - `{ title, task }` objects for named side-effect tasks
-  * - `{ command, perPackage }` to run a command once per owning workspace package (cwd = that package dir), and `{ command, cwd }` to pin a command to a fixed directory
-  * - Mixed arrays of strings and functions
-  * - A top-level generate-task function
-  */
+   * Staged file patterns and commands (replaces lint-staged).
+   *
+   * Accepts all lint-staged config forms:
+   * - `string` or `string[]` commands
+   * - Sync/async functions returning `string | string[]`
+   * - `{ title, task }` objects for named side-effect tasks
+   * - `{ command, perPackage }` to run a command once per owning workspace package (cwd = that package dir), and `{ command, cwd }` to pin a command to a fixed directory
+   * - Mixed arrays of strings and functions
+   * - A top-level generate-task function
+   */
   staged?: StagedConfig;
   /**
-  * When `true`, every task command is scanned for `${VAR}` / `$VAR`
-  * references before spawn. If a referenced var is unset in the
-  * task's effective env (envFile + service env + per-task `env` +
-  * `process.env`), the task fails with an actionable error
-  * naming the missing variable, instead of letting the shell
-  * silently substitute an empty string.
-  *
-  * Override per run with `--strict-env` / `--no-strict-env`.
-  * Override per target with `options.strictEnv`.
-  * @default false
-  */
+   * When `true`, every task command is scanned for `${VAR}` / `$VAR`
+   * references before spawn. If a referenced var is unset in the
+   * task's effective env (envFile + service env + per-task `env` +
+   * `process.env`), the task fails with an actionable error
+   * naming the missing variable, instead of letting the shell
+   * silently substitute an empty string.
+   *
+   * Override per run with `--strict-env` / `--no-strict-env`.
+   * Override per target with `options.strictEnv`.
+   * @default false
+   */
   strictEnv?: boolean;
   /**
-  * Named bundles of target dependencies, referenceable from any task's
-  * `dependsOn`. `dependsOn: [{ group: "lint" }]` expands to every entry
-  * in the named group; nested groups are resolved recursively and a
-  * cycle raises during discovery.
-  */
+   * Named bundles of target dependencies, referenceable from any task's
+   * `dependsOn`. `dependsOn: [{ group: "lint" }]` expands to every entry
+   * in the named group; nested groups are resolved recursively and a
+   * cycle raises during discovery.
+   */
   taskGroups?: Record<string, (string | {
     dependencies?: boolean;
     projects?: string | string[];
@@ -2481,130 +2497,130 @@ interface VisConfig {
     group: string;
   })[]>;
   /**
-  * Task runner options forwarded verbatim to `defaultTaskRunner`.
-  *
-  * Includes `remoteCache` (HTTP or REAPI gRPC backend), `cacheDirectory`,
-  * `parallel`, `globalEnv`, `globalInputs`, etc.
-  * See `TaskRunnerOptions` for the full surface.
-  */
+   * Task runner options forwarded verbatim to `defaultTaskRunner`.
+   *
+   * Includes `remoteCache` (HTTP or REAPI gRPC backend), `cacheDirectory`,
+   * `parallel`, `globalEnv`, `globalInputs`, etc.
+   * See `TaskRunnerOptions` for the full surface.
+   */
   taskRunner?: Partial<TaskRunnerOptions>;
   /**
-  * Workspace-wide task defaults keyed by target name. Applied universally
-  * to every project that exposes a matching target. Use `scopedTasks` when
-  * defaults should only apply to a subset of projects.
-  */
+   * Workspace-wide task defaults keyed by target name. Applied universally
+   * to every project that exposes a matching target. Use `scopedTasks` when
+   * defaults should only apply to a subset of projects.
+   */
   tasks?: Record<string, Partial<VisTargetConfiguration>>;
   /**
-  * Toolchain (Node / pnpm / python / rust / ...) management. vis
-  * delegates to whichever version manager (proto, mise, fnm, volta,
-  * asdf, nvm, corepack) the developer already has — it does not ship
-  * its own.
-  *
-  * Re-exported from `./toolchain` so the public config type stays
-  * in lockstep with the resolver implementation. `self-activate` is
-  * narrowed out of `preferredManager` here — it's auto-resolved for
-  * pnpm/yarn `packageManager` pins and isn't meaningful as an
-  * override.
-  */
+   * Toolchain (Node / pnpm / python / rust / ...) management. vis
+   * delegates to whichever version manager (proto, mise, fnm, volta,
+   * asdf, nvm, corepack) the developer already has — it does not ship
+   * its own.
+   *
+   * Re-exported from `./toolchain` so the public config type stays
+   * in lockstep with the resolver implementation. `self-activate` is
+   * narrowed out of `preferredManager` here — it's auto-resolved for
+   * pnpm/yarn `packageManager` pins and isn't meaningful as an
+   * override.
+   */
   toolchain?: Omit<ToolchainConfig, "preferredManager"> & {
     readonly preferredManager?: Exclude<VersionManagerName, "self-activate">;
   };
   /** Terminal UI configuration */
   tui?: {
     /**
-    * Auto-exit the TUI after tasks complete.
-    * - `false`: Stay open until the user presses `q` (default)
-    * - `true`: Show quit dialog with 3-second countdown after completion
-    * - `number`: Show quit dialog with custom countdown in seconds
-    */
+     * Auto-exit the TUI after tasks complete.
+     * - `false`: Stay open until the user presses `q` (default)
+     * - `true`: Show quit dialog with 3-second countdown after completion
+     * - `number`: Show quit dialog with custom countdown in seconds
+     */
     autoExit?: boolean | number;
   };
   /** Update command defaults */
   update?: {
     /**
-    * Dependency fields to scan for outdated packages.
-    * Beyond the standard fields, supports:
-    * - `"overrides"` (npm)
-    * - `"resolutions"` (yarn)
-    * - `"pnpm.overrides"`
-    * @default ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]
-    */
+     * Dependency fields to scan for outdated packages.
+     * Beyond the standard fields, supports:
+     * - `"overrides"` (npm)
+     * - `"resolutions"` (yarn)
+     * - `"pnpm.overrides"`
+     * @default ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]
+     */
     depFields?: string[];
     exclude?: string[];
     format?: "json" | "minimal" | "table";
     /**
-    * Package names or glob patterns to permanently ignore during updates.
-    * Ignored packages are skipped and listed in the output so you know
-    * they were not checked.
-    * @example ["eslint", "@types/*"]
-    */
+     * Package names or glob patterns to permanently ignore during updates.
+     * Ignored packages are skipped and listed in the output so you know
+     * they were not checked.
+     * @example ["eslint", "@types/*"]
+     */
     ignore?: string[];
     include?: string[];
     /**
-    * Include packages with pinned/exact versions (no `^` or `~` prefix).
-    * By default, pinned versions are skipped during update checks.
-    * @default false
-    */
+     * Include packages with pinned/exact versions (no `^` or `~` prefix).
+     * By default, pinned versions are skipped during update checks.
+     * @default false
+     */
     includeLocked?: boolean;
     install?: boolean;
     /**
-    * Maximum number of concurrent registry requests during outdated checks.
-    * Higher values speed up large workspaces but risk hitting registry rate
-    * limits or self-hosted Verdaccio caps.
-    * @default 8
-    */
+     * Maximum number of concurrent registry requests during outdated checks.
+     * Higher values speed up large workspaces but risk hitting registry rate
+     * limits or self-hosted Verdaccio caps.
+     * @default 8
+     */
     maxConcurrentRequests?: number;
     /**
-    * Minimum number of minutes since a version was published before
-    * vis will consider it for updates. This mirrors pnpm's
-    * `minimumReleaseAge` — a single setting that applies to both
-    * install and update.
-    *
-    * Not set by default. If your package manager config
-    * (`pnpm-workspace.yaml`) has `minimumReleaseAge`, vis will
-    * read it from there as a fallback.
-    * @example 1440 // 24 hours
-    */
+     * Minimum number of minutes since a version was published before
+     * vis will consider it for updates. This mirrors pnpm's
+     * `minimumReleaseAge` — a single setting that applies to both
+     * install and update.
+     *
+     * Not set by default. If your package manager config
+     * (`pnpm-workspace.yaml`) has `minimumReleaseAge`, vis will
+     * read it from there as a fallback.
+     * @example 1440 // 24 hours
+     */
     minimumReleaseAge?: number;
     /**
-    * Package names/patterns excluded from the minimumReleaseAge check.
-    * @example ["webpack", "@myorg/*"]
-    */
+     * Package names/patterns excluded from the minimumReleaseAge check.
+     * @example ["webpack", "@myorg/*"]
+     */
     minimumReleaseAgeExclude?: string[];
     /**
-    * Per-package or per-pattern update target overrides.
-    * Keys are exact package names, glob patterns, or regex patterns
-    * wrapped in `/` (e.g., `/^@vue/`).
-    * Values are `"latest"`, `"minor"`, or `"patch"`.
-    * @example { "typescript": "minor", "/^@vue/": "patch" }
-    */
+     * Per-package or per-pattern update target overrides.
+     * Keys are exact package names, glob patterns, or regex patterns
+     * wrapped in `/` (e.g., `/^@vue/`).
+     * Values are `"latest"`, `"minor"`, or `"patch"`.
+     * @example { "typescript": "minor", "/^@vue/": "patch" }
+     */
     packageMode?: Record<string, "latest" | "minor" | "patch">;
     prerelease?: boolean;
     /**
-    * Which release channels to consider when picking the target version.
-    * - `"stable"` (default) — only ship stable releases (no prereleases).
-    * - `"same"` — match the prerelease channel of the *current* range:
-    *   if you're on `react@19.0.0-rc.1`, only `rc.*` candidates qualify;
-    *   if you're on a stable, only stable candidates. Prevents
-    *   accidentally promoting a prerelease pin to a stable major bump.
-    * - `"any"` — equivalent to `--prerelease`. Any channel is fair game.
-    *
-    * `--release-channel` on the CLI overrides this. If `prerelease: true`
-    * is set without `releaseChannel`, vis treats it as `"any"`.
-    * @default "stable"
-    */
+     * Which release channels to consider when picking the target version.
+     * - `"stable"` (default) — only ship stable releases (no prereleases).
+     * - `"same"` — match the prerelease channel of the *current* range:
+     *   if you're on `react@19.0.0-rc.1`, only `rc.*` candidates qualify;
+     *   if you're on a stable, only stable candidates. Prevents
+     *   accidentally promoting a prerelease pin to a stable major bump.
+     * - `"any"` — equivalent to `--prerelease`. Any channel is fair game.
+     *
+     * `--release-channel` on the CLI overrides this. If `prerelease: true`
+     * is set without `releaseChannel`, vis treats it as `"any"`.
+     * @default "stable"
+     */
     releaseChannel?: "any" | "same" | "stable";
     security?: boolean;
     target?: "latest" | "minor" | "patch";
   };
   /**
-  * Minimum vis CLI version required by this workspace. When the
-  * running vis binary is older than this constraint, vis exits with
-  * an actionable error before executing any command.
-  *
-  * Accepts a semver range string (e.g. `">=1.0.0"`, `"^1.2.0"`).
-  * @example ">=1.0.0"
-  */
+   * Minimum vis CLI version required by this workspace. When the
+   * running vis binary is older than this constraint, vis exits with
+   * an actionable error before executing any command.
+   *
+   * Accepts a semver range string (e.g. `">=1.0.0"`, `"^1.2.0"`).
+   * @example ">=1.0.0"
+   */
   versionConstraint?: string;
 }
 /**
@@ -2830,7 +2846,7 @@ declare enum SpanStatusCode {
   /**
    * The operation contains an error.
    */
-  ERROR = 2,
+  ERROR = 2
 }
 /**
  * A pointer from the current {@link Span} to another span in the same trace or
@@ -3009,7 +3025,7 @@ declare enum SpanKind {
    * broker. Unlike client and server, there is no direct critical path latency
    * relationship between producer and consumer spans.
    */
-  CONSUMER = 4,
+  CONSUMER = 4
 }
 /**
  * Options needed for span creation
@@ -3102,175 +3118,165 @@ interface Tracer {
 }
 interface OtelPluginOptions {
   /**
-  * Rename incoming `project:target` IDs before they become OTel
-  * span names. Defaults to passing the id through unchanged.
-  */
+   * Rename incoming `project:target` IDs before they become OTel
+   * span names. Defaults to passing the id through unchanged.
+   */
   renameSpan?: (task: Task) => string;
   /** Tracer used to emit spans. Pass the one from `@opentelemetry/api`'s `trace.getTracer("vis")`. */
   tracer: Tracer;
 }
 /**
-* Reference plugin that maps vis hook lifecycle events to OTel spans.
-*
-* Emits:
-* - one **root span** named `vis.run` spanning `run:before` → `run:after`
-* - one **child span** per task spanning `task:before` → `task:after`
-*   with attributes `vis.task.id`, `vis.task.project`, `vis.task.target`,
-*   `vis.task.cache_status`, `vis.task.exit_code`
-* - `task:failure` sets span status to ERROR and records the exit code
-*
-* Streaming stdout/stderr events are intentionally **not** emitted as
-* span events — high-frequency chunks would blow up OTel backends. Use
-* a log exporter if you need stream-level visibility.
-* @example
-* ```ts
-* import { trace } from "@opentelemetry/api";
-* import { defineConfig } from "@visulima/vis/config";
-* import { otelPlugin } from "@visulima/vis/plugins/otel";
-*
-* const tracer = trace.getTracer("vis", "1.0.0");
-*
-* export default defineConfig({
-*     plugins: [otelPlugin({ tracer })],
-* });
-* ```
-*/
+ * Reference plugin that maps vis hook lifecycle events to OTel spans.
+ *
+ * Emits:
+ * - one **root span** named `vis.run` spanning `run:before` → `run:after`
+ * - one **child span** per task spanning `task:before` → `task:after`
+ *   with attributes `vis.task.id`, `vis.task.project`, `vis.task.target`,
+ *   `vis.task.cache_status`, `vis.task.exit_code`
+ * - `task:failure` sets span status to ERROR and records the exit code
+ *
+ * Streaming stdout/stderr events are intentionally **not** emitted as
+ * span events — high-frequency chunks would blow up OTel backends. Use
+ * a log exporter if you need stream-level visibility.
+ * @example
+ * ```ts
+ * import { trace } from "@opentelemetry/api";
+ * import { defineConfig } from "@visulima/vis/config";
+ * import { otelPlugin } from "@visulima/vis/plugins/otel";
+ *
+ * const tracer = trace.getTracer("vis", "1.0.0");
+ *
+ * export default defineConfig({
+ *     plugins: [otelPlugin({ tracer })],
+ * });
+ * ```
+ */
 declare const otelPlugin: (options: OtelPluginOptions) => VisPlugin;
 /**
-* Type-safe helper for defining a vis plugin. Pure identity — exists
-* only so plugin authors get inference from the `VisPlugin` contract
-* without needing a `satisfies` annotation.
-*
-* Lives in its own module so plugins can import it without going
-* through `config.ts`, which re-exports plugins like `otelPlugin` and
-* would otherwise form an import cycle.
-*/
+ * Type-safe helper for defining a vis plugin. Pure identity — exists
+ * only so plugin authors get inference from the `VisPlugin` contract
+ * without needing a `satisfies` annotation.
+ *
+ * Lives in its own module so plugins can import it without going
+ * through `config.ts`, which re-exports plugins like `otelPlugin` and
+ * would otherwise form an import cycle.
+ */
 declare const definePlugin: (plugin: VisPlugin) => VisPlugin;
 /** Supported config file names, checked in priority order. */
 declare const CONFIG_FILES: string[];
 /** Per-package overlay file names, checked in priority order. */
 declare const TASK_CONFIG_FILES: string[];
 /**
-* Default `security.policies.firstSeen.minutes` applied by `vis init`.
-* 2 days — long enough to filter out most rage-published malware while
-* staying short enough that genuine fixes still land in a working week.
-*
-* Note: this is NOT merged into `SECURITY_DEFAULTS` — leaving it undefined
-* preserves the "no opinion" semantics that downstream drift checks rely
-* on. `vis init` writes the value explicitly into the generated config.
-*/
-
-/**
-* Secure-by-default security settings based on npm supply chain best practices.
-*
-* Applied automatically when using `defineConfig()` or `loadVisConfig()`.
-* Users can override any value — their settings always take precedence.
-* @see https://github.com/lirantal/awesome-npm-security-best-practices
-*/
+ * Secure-by-default security settings based on npm supply chain best practices.
+ *
+ * Applied automatically when using `defineConfig()` or `loadVisConfig()`.
+ * Users can override any value — their settings always take precedence.
+ * @see https://github.com/lirantal/awesome-npm-security-best-practices
+ */
 declare const SECURITY_DEFAULTS: NonNullable<VisConfig["security"]>;
 /**
-* Apply secure defaults to a raw config object.
-* Merges `SECURITY_DEFAULTS` into `config.security`, preserving all user overrides.
-*/
+ * Apply secure defaults to a raw config object.
+ * Merges `SECURITY_DEFAULTS` into `config.security`, preserving all user overrides.
+ */
 declare const applyDefaults: (config: VisConfig) => VisConfig;
 /**
-* Find the vis config file in a directory.
-*
-* Reads the directory listing once and intersects it with the known
-* config filenames rather than `stat`-ing each candidate — one syscall
-* instead of up to six. Priority order is preserved via
-* `CONFIG_FILES` so `.ts` still wins over `.mjs` when both exist.
-* @param directory The directory to search in.
-* @returns The absolute path to the config file, or `undefined` if not found.
-*/
+ * Find the vis config file in a directory.
+ *
+ * Reads the directory listing once and intersects it with the known
+ * config filenames rather than `stat`-ing each candidate — one syscall
+ * instead of up to six. Priority order is preserved via
+ * `CONFIG_FILES` so `.ts` still wins over `.mjs` when both exist.
+ * @param directory The directory to search in.
+ * @returns The absolute path to the config file, or `undefined` if not found.
+ */
 declare const findVisConfigFile: (directory: string) => string | undefined;
 /**
-* Find the per-package `vis.task.ts` overlay in a project directory.
-* Same single-readdir lookup pattern as {@link findVisConfigFile}.
-*/
+ * Find the per-package `vis.task.ts` overlay in a project directory.
+ * Same single-readdir lookup pattern as {@link findVisConfigFile}.
+ */
 declare const findVisTaskConfigFile: (projectDirectory: string) => string | undefined;
 /**
-* Load the vis configuration from a `vis.config.ts` (or `.js`, `.mjs`, `.cjs`, `.mts`, `.cts`) file.
-*
-* Resolves the entire `extends` chain, post-order, and folds it into a
-* single merged config (extends first, root last — child wins). The
-* cache key covers every file in the chain, so editing any extended
-* file invalidates the cache.
-*
-* Falls back to secure defaults if no config file is found.
-* @param workspaceRoot The workspace root directory to search for the config file.
-* @param options Optional loader options.
-* @param options.explicitConfigPath Overrides discovery — used by the
-* global `--config` flag so users can point at any file regardless of
-* cwd. The path must exist; otherwise an error is thrown so the
-* config-loader plugin can surface it to the user.
-* @returns The loaded and resolved configuration with secure defaults applied.
-*/
+ * Load the vis configuration from a `vis.config.ts` (or `.js`, `.mjs`, `.cjs`, `.mts`, `.cts`) file.
+ *
+ * Resolves the entire `extends` chain, post-order, and folds it into a
+ * single merged config (extends first, root last — child wins). The
+ * cache key covers every file in the chain, so editing any extended
+ * file invalidates the cache.
+ *
+ * Falls back to secure defaults if no config file is found.
+ * @param workspaceRoot The workspace root directory to search for the config file.
+ * @param options Optional loader options.
+ * @param options.explicitConfigPath Overrides discovery — used by the
+ * global `--config` flag so users can point at any file regardless of
+ * cwd. The path must exist; otherwise an error is thrown so the
+ * config-loader plugin can surface it to the user.
+ * @returns The loaded and resolved configuration with secure defaults applied.
+ */
 declare const loadVisConfig: (workspaceRoot: string, options?: {
   explicitConfigPath?: string;
 }) => Promise<VisConfig>;
 /**
-* Load the per-package `vis.task.ts` overlay for a project, if any.
-*
-* Returns `undefined` when no overlay file exists. Otherwise compiles
-* the file via the oxc TS loader and caches the result under
-* `node_modules/.cache/vis/task-configs/&lt;project>.json`, keyed by the
-* file's content hash. Editing one project's overlay does not invalidate
-* the root config cache.
-*
-* Errors thrown by the file are wrapped in `VisConfigLoadError` so the
-* source path is reported instead of an opaque workspace.ts failure.
-* @param workspaceRoot Absolute workspace root path (cache scope).
-* @param projectDirectory Absolute path of the project to probe.
-* @param projectName Project identifier — used to scope the cache file.
-*/
+ * Load the per-package `vis.task.ts` overlay for a project, if any.
+ *
+ * Returns `undefined` when no overlay file exists. Otherwise compiles
+ * the file via the oxc TS loader and caches the result under
+ * `node_modules/.cache/vis/task-configs/&lt;project>.json`, keyed by the
+ * file's content hash. Editing one project's overlay does not invalidate
+ * the root config cache.
+ *
+ * Errors thrown by the file are wrapped in `VisConfigLoadError` so the
+ * source path is reported instead of an opaque workspace.ts failure.
+ * @param workspaceRoot Absolute workspace root path (cache scope).
+ * @param projectDirectory Absolute path of the project to probe.
+ * @param projectName Project identifier — used to scope the cache file.
+ */
 declare const loadVisTaskConfig: (workspaceRoot: string, projectDirectory: string, projectName: string) => Promise<VisTaskConfig | undefined>;
 /**
-* Type-safe helper for defining a per-package `vis.task.ts` overlay.
-* Pure identity — exists only so users get type inference and
-* autocomplete from the `VisTaskConfig` shape.
-* @example
-* ```typescript
-* // packages/api/crud/vis.task.ts
-* import { defineTaskConfig } from "@visulima/vis/config";
-*
-* export default defineTaskConfig({
-*     targets: {
-*         build: {
-*             inputs: ["@inherit", "src/proto/**\/*.proto"],
-*             outputs: ["dist/**\/*"],
-*         },
-*     },
-* });
-* ```
-*/
+ * Type-safe helper for defining a per-package `vis.task.ts` overlay.
+ * Pure identity — exists only so users get type inference and
+ * autocomplete from the `VisTaskConfig` shape.
+ * @example
+ * ```typescript
+ * // packages/api/crud/vis.task.ts
+ * import { defineTaskConfig } from "@visulima/vis/config";
+ *
+ * export default defineTaskConfig({
+ *     targets: {
+ *         build: {
+ *             inputs: ["@inherit", "src/proto/**\/*.proto"],
+ *             outputs: ["dist/**\/*"],
+ *         },
+ *     },
+ * });
+ * ```
+ */
 declare const defineTaskConfig: (config: VisTaskConfig) => VisTaskConfig;
 /**
-* Type-safe helper for defining vis configuration.
-*
-* Pure typed-identity — returns its argument unchanged. The point is purely
-* editor autocomplete and structural type-checking on the literal you pass
-* in. Secure defaults are applied by `loadVisConfig` at load time, not here,
-* so wrapping vs. using `satisfies VisConfig` produces the exact same
-* runtime behavior. To see the active defaults, run `vis check --security-config`.
-* @example
-* ```typescript
-* // vis.config.ts — minimal config, fully secured by defaults
-* import { defineConfig } from "@visulima/vis/config";
-*
-* export default defineConfig({
-*     security: {
-*         policies: {
-*             installScripts: {
-*                 allow: {
-*                     esbuild: true,
-*                     "@prisma/client": true,
-*                 },
-*             },
-*         },
-*     },
-* });
-* ```
-*/
+ * Type-safe helper for defining vis configuration.
+ *
+ * Pure typed-identity — returns its argument unchanged. The point is purely
+ * editor autocomplete and structural type-checking on the literal you pass
+ * in. Secure defaults are applied by `loadVisConfig` at load time, not here,
+ * so wrapping vs. using `satisfies VisConfig` produces the exact same
+ * runtime behavior. To see the active defaults, run `vis check --security-config`.
+ * @example
+ * ```typescript
+ * // vis.config.ts — minimal config, fully secured by defaults
+ * import { defineConfig } from "@visulima/vis/config";
+ *
+ * export default defineConfig({
+ *     security: {
+ *         policies: {
+ *             installScripts: {
+ *                 allow: {
+ *                     esbuild: true,
+ *                     "@prisma/client": true,
+ *                 },
+ *             },
+ *         },
+ *     },
+ * });
+ * ```
+ */
 declare const defineConfig: (config: VisConfig) => VisConfig;
 export { CONFIG_FILES, type OtelPluginOptions, SECURITY_DEFAULTS, TASK_CONFIG_FILES, type VisConfig, type VisHooks, type VisPlugin, type VisTaskConfig, applyDefaults, defineConfig, definePlugin, defineTaskConfig, findVisConfigFile, findVisTaskConfigFile, loadVisConfig, loadVisTaskConfig, otelPlugin };