@vibe-agent-toolkit/cli 0.1.42 → 0.2.0-rc.10

package/dist/version.js

@@ -7,9 +7,7 @@ import { fileURLToPath } from 'node:url';
 import { safePath } from '@vibe-agent-toolkit/utils';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Read version from package.json at build time
-const packageJson = JSON.parse(
-// eslint-disable-next-line security/detect-non-literal-fs-filename -- path resolved from known __dirname and constant package.json name
-readFileSync(safePath.resolve(__dirname, '../package.json'), 'utf-8'));
+const packageJson = JSON.parse(readFileSync(safePath.resolve(__dirname, '../package.json'), 'utf-8'));
 export const version = packageJson.version;
 /**
  * The version line alone: `<ver>` plus whatever the cwd-derived context adds.

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAG,OAAO,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErD,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,+CAA+C;AAC/C,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK;AAC5B,wIAAwI;AACxI,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC,CACtE,CAAC;AAEF,MAAM,CAAC,MAAM,OAAO,GAAW,WAAW,CAAC,OAAO,CAAC;AAOnD;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,GAAW,EAAE,OAA8B;IACpE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,GAAG,CAAC;IACb,CAAC;IAED,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,KAAK;YACR,OAAO,GAAG,GAAG,SAAS,OAAO,CAAC,IAAI,IAAI,SAAS,GAAG,CAAC;QACrD,KAAK,OAAO;YACV,OAAO,GAAG,GAAG,YAAY,OAAO,CAAC,IAAI,IAAI,SAAS,GAAG,CAAC;QACxD,KAAK,QAAQ;YACX,OAAO,GAAG,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAW,EACX,OAA8B,EAC9B,UAAkB;IAElB,OAAO,GAAG,iBAAiB,CAAC,GAAG,EAAE,OAAO,CAAC,eAAe,UAAU,EAAE,CAAC;AACvE,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAG,OAAO,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErD,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,+CAA+C;AAC/C,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAC5B,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC,CACtE,CAAC;AAEF,MAAM,CAAC,MAAM,OAAO,GAAW,WAAW,CAAC,OAAO,CAAC;AAOnD;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,GAAW,EAAE,OAA8B;IACpE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,GAAG,CAAC;IACb,CAAC;IAED,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,KAAK;YACR,OAAO,GAAG,GAAG,SAAS,OAAO,CAAC,IAAI,IAAI,SAAS,GAAG,CAAC;QACrD,KAAK,OAAO;YACV,OAAO,GAAG,GAAG,YAAY,OAAO,CAAC,IAAI,IAAI,SAAS,GAAG,CAAC;QACxD,KAAK,QAAQ;YACX,OAAO,GAAG,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAW,EACX,OAA8B,EAC9B,UAAkB;IAElB,OAAO,GAAG,iBAAiB,CAAC,GAAG,EAAE,OAAO,CAAC,eAAe,UAAU,EAAE,CAAC;AACvE,CAAC"}

package/docs/agent.md

@@ -70,7 +70,7 @@ spec:
       type: template
 ```
 
-See `@vibe-agent-toolkit/agent-schema` for complete schema reference.
+See `@vibe-agent-toolkit/schema` for complete schema reference.
 
 ## Examples
 
@@ -120,6 +120,6 @@ for terminology.
 
 ## See Also
 
-- [@vibe-agent-toolkit/agent-schema](../../agent-schema/README.md) - Schema reference
+- [@vibe-agent-toolkit/schema](../../schema/README.md) - Schema reference
 - [agent-generator](../../vat-development-agents/agents/agent-generator/README.md) - Example agent
 - [RAG Commands](./rag.md) - Indexing documentation for RAG tools

package/docs/audit.md

@@ -28,7 +28,9 @@ vat audit [git-url-or-path] [options]
 ### Options
 
 - `--user` - Audit user-level Claude plugins installation (`~/.claude/plugins`)
-- `-r, --recursive` - Scan directories recursively for all resource types
+- `--no-recursive` - Scan the top level only (recursive scanning is the default; there is no `--recursive` flag)
+- `--compat` - Run compatibility analysis for each plugin; adds a `compatibility:` block to its entry (see [Compatibility and settings blocks](#compatibility-and-settings-blocks))
+- `--settings [file]` - Check each plugin against Claude settings (auto-discovered, or the given file); adds a `settings:` block. Requires `--compat`
 - `--debug` - Enable debug logging (outputs to stderr)
 
 ### Gitignore-aware scanning
@@ -205,25 +207,61 @@ hierarchical:
                   message: Skill exceeds recommended length
 ```
 
+## `status` and the exit code
+
+The YAML `status` describes the findings — the worst actionable severity across
+them — and the exit code follows it, exactly as in every other command of this
+CLI. `vat audit` used to be the one exception ("advisory": exit 0 over
+`status: error`), which a CI author reading the shared contract got wrong on
+exactly this verb.
+
+A run that audited **zero files** is refused, not passed. An existing directory
+with nothing auditable in it — plugins that moved, a wrong subdirectory, an
+excluded tree, files no lane recognises — used to publish `status: success`
+beside `filesScanned: 0`, which is the same document a clean tree produces. It
+now publishes `status: error` with one non-overridable `RESOURCE_CHECK_BROKEN`
+finding under a top-level `issues:` key (the claim is about the run, so it is
+not a `files[]` row and does not count toward `filesScanned`), and exits `1`.
+
+What still sets audit apart from `vat skills validate` is not the exit code but
+what it shows: audit ignores `validation.allow` (every finding is reported and
+counted) and reads `validation.severity` from three scopes. `validation.severity`
+is therefore the dial that decides what gates — set a code to `warning` and it
+stops moving the exit code; set it to `ignore` and it disappears from the report.
+
 ## Exit Codes
 
-`vat audit` is **advisory by design** — it reports every issue it detects but does not block on validation severity. Use `vat skills validate` or `vat skills build` for gated checks (those commands exit `1` on validation errors).
+The three-way contract every command shares:
 
-- **0** - Always, when the audit completes. The report may still contain errors and warnings; check `status` and `summary` in the YAML output to decide whether action is needed.
-- **2** - System error: Config invalid, path not found, permission denied, etc. The audit could not run.
+- **0** - The audit completed with nothing at error severity. Warnings and informational findings are in the report, not the exit code.
+- **1** - The audit completed and reports `status: error`: at least one error-severity finding, or zero files audited. A directory or file INSIDE the tree that the scan could not read — permission denied, a vanished mount — is `SCAN_PATH_UNREADABLE` (warning): the run is degraded, not failed, every readable sibling is still validated, and the refused path is reported under `summary.pathsUnreadable` rather than counted in `filesScanned` — so a root with nothing readable audited zero files and is refused like an empty tree. A governing `vibe-agent-toolkit.config.yaml` that cannot be loaded, or whose `skills.include` reaches a directory the crawl cannot list, is warned about once on stderr and filed as `SCAN_PATH_UNREADABLE` on the config file or the directory; the skills it governs are validated config-free rather than dropped. Degrading beats destroying, and the report says where it degraded.
+- **2** - The audit could not run at all, so there is no report to read: the path does not exist or is a file no audit lane recognises (the same ending `vat resources validate` and `vat skill review` give that argument), `--user` with no Claude config directory installed, a git URL that could not be cloned, an unknown flag, or an internal failure (a validator defect). An invalid config and a permission problem inside the tree are **not** exit 2 — they are findings, above.
 
 ## Validation Configuration
 
-Audit honors `validation.severity` from `vibe-agent-toolkit.config.yaml` for **display grouping only** — setting a code to `ignore` hides it from output, raising to `error` promotes it in the report's error count. Audit does **not** apply `validation.allow` (per-path allow entries); for that, use `vat skills validate` or `vat skills build`.
+Audit honors `validation.severity` from `vibe-agent-toolkit.config.yaml`: setting a code to `ignore` hides it from the report, and every other level is applied as written — a code raised to `error` is reported as an error, a code lowered to `warning` as a warning. It changes **which findings are reported and at what severity**, and through them the exit code — a code at `error` gates, one lowered to `warning` does not (see [`status` and the exit code](#status-and-the-exit-code)). Audit does **not** apply `validation.allow` (per-path allow entries); for that, use `vat skills validate` or `vat skills build`.
+
+Three scopes are read, least specific first — a more specific one naming the same code wins:
 
 ```yaml
 # In vibe-agent-toolkit.config.yaml
+resources:
+  validation:
+    severity:
+      LINK_MISSING_TARGET: ignore       # project-wide; the same dial
+                                        # `vat resources validate` reads
 skills:
   defaults:
     validation:
       severity:
-        LINK_TO_NAVIGATION_FILE: ignore   # hidden from audit output
-        LINK_DROPPED_BY_DEPTH: error      # elevated in the report
+        LINK_TO_NAVIGATION_FILE: ignore # project-wide: skills, plugins and
+                                        # marketplaces alike
+        LINK_DROPPED_BY_DEPTH: error    # elevated in the report
+  config:
+    my-skill:
+      validation:
+        severity:
+          LINK_DROPPED_BY_DEPTH: info   # just this skill
 ```
 
 See `docs/validation-codes.md` for the full code reference.
@@ -237,16 +275,15 @@ Errors prevent the resource from being used correctly:
 - **Missing manifests/frontmatter**: Resource structure is invalid
 - **Schema validation failures**: Manifest/frontmatter doesn't match expected format
 - **Broken links**: Links to non-existent files (Skills only)
-- **Reserved words in names**: Using reserved words like "help", "exit" (Skills only)
+- **Reserved words in names**: `anthropic` or `claude` in a skill name (`RESERVED_WORD_IN_NAME`, a warning — Claude Code rejects non-certified skills using them)
 - **XML tags in frontmatter**: XML-like tags in name/description (Skills only)
-- **Windows-style backslashes**: Path separators should be forward slashes (Skills only)
 
 ### Warnings (Should Fix)
 
 Warnings indicate potential issues but don't prevent usage:
 
 - **Skill exceeds recommended length**: Over 5000 lines (Skills only)
-- **Compat smells**: Skill requires a runtime capability that isn't available on every surface (browser auth, local shell, external CLI) — see `COMPAT_*` codes in `docs/validation-codes.md`.
+- **Capability observations**: Skill requires a runtime capability that isn't available on every surface — `CAPABILITY_BROWSER_AUTH`, `CAPABILITY_LOCAL_SHELL`, `CAPABILITY_EXTERNAL_CLI` (info); with `--compat`, the per-target verdicts `COMPAT_TARGET_INCOMPATIBLE` / `COMPAT_TARGET_NEEDS_REVIEW` (warning) and `COMPAT_TARGET_UNDECLARED` (info). See `docs/validation-codes.md`.
 
 ## Error Codes Reference
 
@@ -282,13 +319,12 @@ Warnings indicate potential issues but don't prevent usage:
 | `SKILL_MISSING_NAME` | error | `name` field missing from frontmatter | Add `name` field |
 | `SKILL_MISSING_DESCRIPTION` | error | `description` field missing from frontmatter | Add `description` field |
 | `SKILL_NAME_INVALID` | error | Name contains invalid characters | Use only letters, numbers, hyphens, underscores |
-| `SKILL_DESCRIPTION_TOO_LONG` | error | Description exceeds 500 characters | Shorten description |
+| `SKILL_DESCRIPTION_TOO_LONG` | error | Description exceeds 1024 characters (the frontmatter schema limit; `SKILL_DESCRIPTION_OVER_CLAUDE_CODE_LIMIT` warns earlier at 250, where the Claude Code `/skills` listing truncates) | Shorten description |
 | `RESERVED_WORD_IN_NAME` | warning | Name contains `anthropic` or `claude`; Claude Code rejects non-certified skills using these words | Rename the skill to avoid these words |
 | `SKILL_NAME_XML_TAGS` | error | Name contains XML-like tags | Remove XML tags from name |
 | `SKILL_DESCRIPTION_XML_TAGS` | error | Description contains XML-like tags | Remove XML tags from description |
 | `SKILL_DESCRIPTION_EMPTY` | error | Description is empty or whitespace | Provide meaningful description |
 | `SKILL_MISCONFIGURED_LOCATION` | error | Standalone skill in `~/.claude/plugins/` won't be recognized | Move to `~/.claude/skills/` for standalone skills, or add `.claude-plugin/plugin.json` for a proper plugin |
-| `PATH_STYLE_WINDOWS` | error | Windows-style backslashes in paths | Use forward slashes (/) instead |
 | `LINK_INTEGRITY_BROKEN` | error | Link to non-existent file | Fix or remove broken link |
 
 ### Skill Warnings
@@ -296,9 +332,12 @@ Warnings indicate potential issues but don't prevent usage:
 | Code | Severity | Description | Fix |
 |------|----------|-------------|-----|
 | `SKILL_TOO_LONG` | warning | Skill exceeds 5000 lines | Consider splitting into multiple skills |
-| `COMPAT_REQUIRES_BROWSER_AUTH` | warning | Skill needs browser login (MSAL, SSO, OAuth) | See `docs/validation-codes.md#compat_requires_browser_auth` |
-| `COMPAT_REQUIRES_LOCAL_SHELL` | warning | Skill needs local shell/environment tools (Bash, Edit, Write, NotebookEdit) | See `docs/validation-codes.md#compat_requires_local_shell` |
-| `COMPAT_REQUIRES_EXTERNAL_CLI` | warning | Skill invokes unbundled CLI (az, aws, gcloud, etc.) | See `docs/validation-codes.md#compat_requires_external_cli` |
+| `CAPABILITY_BROWSER_AUTH` | info | Skill needs browser login (MSAL, SSO, OAuth) | See `docs/validation-codes.md#capability_browser_auth` |
+| `CAPABILITY_LOCAL_SHELL` | info | Skill needs local shell/environment tools (Bash, Edit, Write, NotebookEdit) | See `docs/validation-codes.md#capability_local_shell` |
+| `CAPABILITY_EXTERNAL_CLI` | info | Skill invokes an unbundled CLI (az, aws, gcloud, etc.) | See `docs/validation-codes.md#capability_external_cli` |
+| `COMPAT_TARGET_INCOMPATIBLE` | warning | With `--compat`: a declared target cannot run the skill | See `docs/validation-codes.md#compat_target_incompatible` |
+| `COMPAT_TARGET_NEEDS_REVIEW` | warning | With `--compat`: a declared target may not run the skill | See `docs/validation-codes.md#compat_target_needs_review` |
+| `COMPAT_TARGET_UNDECLARED` | info | With `--compat`: the skill declares no `targets` | See `docs/validation-codes.md#compat_target_undeclared` |
 
 ### Format Detection Errors
 
@@ -316,14 +355,20 @@ Structured YAML report for programmatic parsing:
 root: /abs/path/to/scan/root   # The ONE absolute path in the document
 status: success | warning | error
 summary:
-  filesScanned: number
+  filesScanned: number        # Files the audit READ — never a path it could not
   filesPassed: number         # Files with no ACTIONABLE issues (info-only counts as passed)
   filesWithWarnings: number   # Files whose worst actionable severity is warning
   filesWithErrors: number     # Files carrying at least one error
+  pathsUnreadable: number     # `files[]` rows that are a refused path (SCAN_PATH_UNREADABLE),
+                              #   outside every count above: files.length === filesScanned + pathsUnreadable
 issueCounts:                  # FINDINGS, not files — same field name and meaning
-  errors: number              #   as the `issueCounts` on each entry below
-  warnings: number
+  errors: number              #   as the `issueCounts` on each entry below,
+  warnings: number            #   plus the run-level `issues` when present
   info: number
+issues:                       # Only when the RUN itself is refused — a run over
+  - code: RESOURCE_CHECK_BROKEN   # zero files. Not a file, so not in `files[]`.
+    severity: error
+    message: ...
 duration: "123ms"
 files:
   - path: plugins/my-plugin            # relative to `root`
@@ -357,6 +402,70 @@ say in how a path is spelled.
 lives in a random tempdir that nothing downstream can resolve, so the provenance
 header states the base instead and paths are relative to the cloned repo.
 
+#### Compatibility and settings blocks
+
+Under `--compat`, every `claude-plugin` entry carries a `compatibility:` block;
+under `--compat --settings`, a `settings:` block beside it. **Both blocks are
+always present for every plugin the run was asked about** — a lane that could
+not run says so in its block rather than leaving it out, because a plugin the
+check could not answer for must never look like one the operator never asked
+about.
+
+```yaml
+files:
+  - path: plugins/my-plugin
+    type: claude-plugin
+    compatibility:               # the analyzer's verdicts…
+      plugin: my-plugin
+      declaredTargets: [claude-code]
+      observations: [...]
+      verdicts: [...]
+      unchecked: []              # files the analysis could not read; verdicts were computed without them
+    settings:
+      compatible: false          # true ONLY when conflicts and unchecked are both empty
+      conflicts:
+        - type: tool-blocked
+          detail: Tool "Bash" in skills/deploy/SKILL.md blocked by org policy (permissions.deny)
+          blockedBy: permissions.deny
+          value: Bash
+          settingsFile: /etc/claude-code/managed-settings.json
+          settingsLevel: managed
+      unchecked:                 # present only when non-empty
+        - path: skills/locked/SKILL.md           # relative to `root`
+          reason: "EACCES: permission denied, open 'skills/locked/SKILL.md'"
+  - path: plugins/other-plugin
+    type: claude-plugin
+    compatibility:               # …or the reason there are none
+      analyzed: false
+      reason: "EACCES: permission denied, scandir 'plugins/other-plugin/skills/locked'"
+    settings:
+      compatible: false
+      conflicts: []
+      unchecked:
+        - path: plugins/other-plugin/skills/locked
+          reason: "EACCES: permission denied, scandir 'plugins/other-plugin/skills/locked'"
+```
+
+`settings.unchecked` lists every path the settings check enumerated but could
+not compare: a `SKILL.md` it could not read or whose frontmatter is not a YAML
+mapping (the same file the validator reports as `SKILL_MISSING_FRONTMATTER`), or
+a directory it could not list — in which case any skill beneath it is unseen
+and unnamed. The check follows symlinks the way the validator lane does, so a
+plugin whose `skills/` points at a shared tree is checked, not skipped.
+`compatible` is `false` whenever anything is listed here: zero conflicts over a
+skill that was never read is not compatibility. The two compat lanes are
+independent — a plugin-wide analyzer failure (no valid `plugin.json`, or a root
+that cannot be listed) does not stop the settings check. A single file the
+analyzer cannot read, list or parse is listed under `compatibility.unchecked`
+(root-relative, with the OS or parser reason) and every other file is still
+analyzed; the verdicts are computed WITHOUT the unchecked files, so an empty
+`verdicts` beside a non-empty `unchecked` is a verdict over fewer files than
+the plugin ships.
+
+Both outcomes are also said on stderr without `--debug`: a
+`Compatibility analysis could not run for <plugin>: <reason>` line, and totals
+for conflicts found and paths the settings check could not compare.
+
 ### Standard Error (stderr)
 
 Human-readable error messages and logs. Paths are root-relative here too:
@@ -416,7 +525,7 @@ This scans:
 Scan directory tree for all resources:
 
 ```bash
-vat audit ./resources --recursive
+vat audit ./resources
 ```
 
 Finds and validates:
@@ -433,21 +542,17 @@ Use in CI pipeline:
 #!/bin/bash
 set -e
 
-# Audit all resources (always exits 0 unless system error)
-vat audit --recursive > audit-report.yaml
-
-# Check YAML status field — audit itself doesn't fail on validation errors
-STATUS=$(grep '^status:' audit-report.yaml | awk '{print $2}')
-if [ "$STATUS" = "error" ]; then
-  echo "Audit report contains validation errors"
+# Audit all resources: exit 1 on an error-severity finding, 2 if the audit could not run
+if ! vat audit > audit-report.yaml; then
+  echo "Audit found errors (or could not run) — see the report"
   cat audit-report.yaml
   exit 1
 fi
 
-echo "Audit clean — no validation errors in report"
+echo "Audit clean — no error-severity findings"
 ```
 
-To gate on validation errors directly (exits `1` automatically), use `vat skills validate` instead:
+To gate with `validation.allow` honoured (audit ignores it), use `vat skills validate` instead:
 
 ```bash
 #!/bin/bash
@@ -469,7 +574,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: oven-sh/setup-bun@v1
       - run: npm install -g vibe-agent-toolkit
-      - run: vat audit --recursive
+      - run: vat audit
 ```
 
 ## Troubleshooting
@@ -488,7 +593,7 @@ jobs:
 - Ensure plugin has `.claude-plugin/plugin.json` or `.claude-plugin/marketplace.json`
 - Ensure registry files are named `installed_plugins.json` or `known_marketplaces.json`
 - Ensure skill files are named `SKILL.md`
-- Use `--recursive` to scan subdirectories
+- Scanning is recursive by default; make sure you did not pass `--no-recursive`
 
 ### "Permission denied" on Windows
 
@@ -503,7 +608,7 @@ jobs:
 **Solution**: Redirect stdout to file, only show stderr:
 
 ```bash
-vat audit --recursive > audit.yaml 2>&1
+vat audit > audit.yaml 2>&1
 if [ $? -ne 0 ]; then
   echo "Audit failed, see audit.yaml"
   exit 1
@@ -593,10 +698,10 @@ governing context rather than a single top-level `projectRoot`:
   reported as ungoverned (an audit finding, not a fatal error). This lets `vat
   audit` work on external community trees, downloaded plugin bundles, and
   monorepos with multiple sub-package configs.
-- **Config**: accept defaults. Per-skill `validation.severity` and
-  `validation.allow` overrides come from whichever
-  `vibe-agent-toolkit.config.yaml` each skill walks up to. The audit itself
-  always exits 0 (advisory) regardless of severity outcomes.
+- **Config**: accept defaults. Per-skill `validation.severity` overrides come
+  from whichever `vibe-agent-toolkit.config.yaml` each skill walks up to;
+  `validation.allow` is not applied by audit (see the config section above).
+  The exit code follows the report's `status`, like every other command.
 
 The per-skill walk-up is cached via a module-level two-layer cache and pre-warmed
 during top-down descent for efficiency on large trees.
@@ -604,11 +709,10 @@ during top-down descent for efficiency on large trees.
 See [Roots and Config — Canonical Concepts](../../../docs/concepts/roots-and-config.md)
 for the `projectRoot` ladder and the audit walk-up model. See
 [`docs/skill-quality-and-compatibility.md`](../../../docs/skill-quality-and-compatibility.md)
-for VAT's advisory-audit stance.
+for VAT's audit stance.
 
 ## Related Commands
 
-- `vat agent audit <path>` - Legacy skill-only audit (deprecated)
 - `vat doctor` - Check environment and installation health
 - `vat resources validate` - Validate markdown resources (links, anchors)
 

package/docs/doctor.md

@@ -12,7 +12,7 @@ providing actionable suggestions for any problems found.
 **Purpose:** Check environment and project setup health
 
 **What it checks:**
-1. Node.js version (>=20 required)
+1. Node.js version (>=22.13.0 required — the range comes from the CLI's own `engines.node`)
 2. Git installed and version
 3. Current directory is a git repository
 4. Configuration file exists (vibe-agent-toolkit.config.yaml)
@@ -35,6 +35,7 @@ providing actionable suggestions for any problems found.
 **Exit Codes:**
 - `0` - No check failed (an undetermined check is reported in the output, not fatal)
 - `1` - One or more checks failed
+- `2` - Doctor itself could not run (an internal failure, an unknown flag); no verdict was produced
 
 **Output:** Human-friendly formatted text with emojis. The summary always prints the
 full outcome distribution and, when the concise view hides checks, how many it hid —
@@ -96,7 +97,7 @@ Running diagnostic checks...
    Current: 0.1.0 — up to date
 
 ✅ Node.js version
-   v22.0.0 (meets requirement: >=20.0.0)
+   v22.13.0 (meets requirement: >=22.13.0)
 
 ✅ Git installed
    git version 2.43.0
@@ -148,12 +149,12 @@ Running diagnostic checks...
 
 When checks fail, doctor provides specific suggestions:
 
-### Node.js Version Too Old
+### Node.js Version Out of Range
 
 ```
 ❌ Node.js version
-   v18.0.0 is too old. Node.js 20+ required.
-   💡 Upgrade Node.js: https://nodejs.org/ or use nvm
+   v22.4.0 does not satisfy the required range. Node.js >=22.13.0 required.
+   💡 Install a Node.js version in that range: https://nodejs.org/ or use nvm
 ```
 
 ### Git Not Installed
@@ -248,7 +249,7 @@ fi
 
 ### Node.js Version Check
 
-- **Requirement:** Node.js 20 or higher
+- **Requirement:** Node.js >=22.13.0, read at runtime from the CLI's `engines.node` so this check cannot drift behind the floor. Checked against `process.version` — the interpreter running VAT — not against a spawned `node` from `PATH`, which differs under any version manager.
 - **Why:** VAT uses modern JavaScript features
 - **Fix:** Install Node.js from https://nodejs.org/ or use nvm
 

package/docs/index.md

@@ -23,6 +23,8 @@ Markdown resource scanning, link validation, and frontmatter validation (run bef
 5. **Validates frontmatter against JSON Schemas** (per-collection)
 6. Reports broken links and validation errors to stderr
 
+**Note:** External URLs are not validated (by design — avoids flaky network checks). Only internal file links and anchors are checked.
+
 **Per-collection frontmatter validation:**
 
 Define collections in `vibe-agent-toolkit.config.yaml` to validate frontmatter fields, types, and patterns using JSON Schemas. Collections support strict mode (no extra fields) or permissive mode (extra fields allowed).
@@ -92,7 +94,7 @@ Diagnose vat setup and environment health
 
 **What it does:**
 
-- Checks Node.js version (>=20 required)
+- Checks Node.js version (>=22.13.0 required)
 - Checks Git installation and repository
 - Validates configuration file exists and is valid
 - Checks vat version and available updates
@@ -104,6 +106,7 @@ Diagnose vat setup and environment health
 
 - `0` - No check failed (a check that could not be determined is reported as ❓, not fatal)
 - `1` - One or more checks failed
+- `2` - Doctor itself could not run (an internal failure; no verdict was produced)
 
 **Creates/modifies:** None (read-only diagnostics)
 
@@ -167,7 +170,7 @@ Execute agent locally for testing
 **Exit codes:**
 
 - `0` - Execution succeeded
-- `1` - Execution failed
+- `2` - Execution failed (the agent could not run, or threw)
 
 **Creates/modifies:** Depends on agent behavior
 
@@ -196,9 +199,8 @@ Run a packaged skill's eval suite in a headless, context-isolated Claude session
 **Exit codes:**
 
 - `0` - Run completed, all expectations passed
-- `1` - Harness broke (internal error, stall, timeout)
-- `2` - Preflight failure (bad config, unresolvable required companion, auth guard)
-- `3` - Bootstrap failure
+- `1` - Run completed and at least one eval failed
+- `2` - The harness could not run; a `Reason: internal | preflight | bootstrap` line on stderr says why
 - `4` - Eval failure (run completed, expectations did not all pass)
 
 **Creates/modifies:** A harness directory (removed unless `--keep`)
@@ -235,7 +237,8 @@ Create vector embeddings for semantic search over documentation
 **Exit codes:**
 
 - `0` - Indexing succeeded
-- `1` - Indexing failed
+- `1` - Indexing completed but some resources could not be indexed (the report names them)
+- `2` - Indexing could not run (no provider, unreadable config)
 
 **Creates/modifies:**
 
@@ -266,7 +269,7 @@ Search indexed documentation semantically
 **Exit codes:**
 
 - `0` - Search succeeded
-- `1` - Search failed (no index, query error)
+- `2` - Search could not run (no index, query error)
 
 **Creates/modifies:** None (read-only query)
 
@@ -286,9 +289,28 @@ vat rag search "agent deployment" --limit 5
 - `--help --verbose` - Show comprehensive help (this output)
 - `--cwd <dir>` - Change working directory before running any command
 - `--debug` - Enable debug logging
+- `--no-cache` - Disable VAT's on-disk caches for this run, including in spawned child phases
+  (equivalent to `VAT_CACHE=0`; see [Environment Variables](#vat_cache)). Clear what is already
+  stored with `vat cache clear`.
 
 ## Environment Variables
 
+### VAT_CACHE
+Set to `0` to disable VAT's on-disk caches for the run — the parse cache and the external-URL
+validation caches, which share `<tmpdir>/.vat-cache/`:
+
+```bash
+VAT_CACHE=0 vat validate
+```
+
+The root `--no-cache` flag is the same switch: it sets this variable. The variable is what makes it
+work, because `vat validate`, `vat verify` and `vat build` do their parsing in spawned child
+processes, and only the environment crosses that boundary — a flag parsed in the parent would never
+reach them.
+
+Caching is a pure optimisation: a run with it off produces identical results, only slower. Use
+`vat cache clear` to discard what is already stored.
+
 ### VAT_DEBUG
 Enable detailed wrapper diagnostics showing context detection and resolution:
 
@@ -407,7 +429,6 @@ its policy. The full matrix and rationale live in
 Place `vibe-agent-toolkit.config.yaml` at project root:
 
 ```yaml
-version: 1
 resources:
   include:
     - "docs/**/*.md"
@@ -419,9 +440,17 @@ resources:
 
 ## Exit Code Summary
 
-- `0` - Success (validation passed, scan completed, build succeeded)
-- `1` - Expected failures (validation errors, broken links, build failures)
-- `2` - System errors (invalid config, directory not found, missing dependencies)
+One contract, every command:
+
+- `0` - **OK.** The command ran and found nothing at error severity. Warnings and informational findings are in the document, not the exit code (a command that offers `--strict` promotes warnings).
+- `1` - **Findings.** The command ran to completion and what it examined failed its gate: an error-severity finding, a failed eval, a broken link, a partial index.
+- `2` - **Error.** The command could not do its job: a usage mistake (unknown flag or verb, a retired `--only`), a root path that does not exist or is not something the verb can act on, an unreadable config, a missing dependency, an internal failure (a crash anywhere in a command ends on `2`, never on Node's default `1`). Where a verb has more than one such cause it says which on stderr (`vat skill test run` prints `Reason: …`) — never in a fourth exit code. A path INSIDE a tree that the command cannot read is a finding, not an error: `vat audit` degrades it to `SCAN_PATH_UNREADABLE` and exits `0` or `1` on what it could read.
+
+A CI wrapper reads `$?` the same way for every verb:
+
+```bash
+case $? in 0) ;; 1) echo findings ;; *) echo broken; exit 1 ;; esac
+```
 
 ## Output Formats
 
@@ -456,6 +485,5 @@ vat rag search "markdown validation"
 
 ## More Information
 
-- **Agent guidance:** `docs/cli/CLAUDE.md` (strategic patterns for AI agents)
 - **Documentation:** https://github.com/jdutton/vibe-agent-toolkit
 - **Issues:** https://github.com/jdutton/vibe-agent-toolkit/issues

package/docs/mcp.md

@@ -152,8 +152,8 @@ MCP agent packages must export collections via the `/mcp-collections` entrypoint
 ### Example: `src/mcp-collections.ts`
 
 ```typescript
-import type { Agent, OneShotAgentOutput } from '@vibe-agent-toolkit/agent-schema';
-import { createSuccess } from '@vibe-agent-toolkit/agent-schema';
+import type { Agent, OneShotAgentOutput } from '@vibe-agent-toolkit/schema';
+import { createSuccess } from '@vibe-agent-toolkit/schema';
 
 export interface MCPAgentRegistration {
   name: string;

package/docs/rag.md

@@ -53,7 +53,8 @@ vat rag clear
 
 **Exit Codes:**
 - `0` - Indexing completed successfully
-- `2` - System error (config invalid, database error, etc.)
+- `1` - Indexed with errors: the run finished, `status: partial`, and `errors` names each resource whose content is NOT in the index — one the provider failed to chunk or embed, or one the crawl enumerated but could not read (a permission-denied file is reported here, never silently dropped)
+- `2` - System error (config invalid, database error, a `rag_documents` table whose columns an earlier build typed differently — the message names the columns and `vat rag clear` is the remedy, etc.)
 
 **Output:** YAML on stdout with indexing statistics
 
@@ -68,6 +69,7 @@ vat rag index docs/
 # status: success
 # resourcesIndexed: 12
 # resourcesSkipped: 0
+# resourcesEmpty: 0      # frontmatter-only or blank files: counted, not stored
 # resourcesUpdated: 0
 # chunksCreated: 48
 # chunksDeleted: 0
@@ -277,7 +279,6 @@ rebuild the database from your markdown source files.
 RAG respects the same `vibe-agent-toolkit.config.yaml` patterns as other commands:
 
 ```yaml
-version: 1
 resources:
   include:
     - "docs/**/*.md"

package/docs/resources.md

@@ -31,16 +31,23 @@ including link integrity checking and anchor validation.
 - `--debug` - Enable debug logging
 - `--verbose` - Add a `files:` list with per-file link/anchor counts and checksums
 - `--collection <id>` - Only report files in the named collection (config mode — no path argument)
+- `--format <format>` - `yaml` (default) or `json`. The same document either way
 
 **Exit Codes:**
 - `0` - Always (scan is informational)
 - `2` - System error (file access, parsing error)
 
-**Output:** YAML on stdout, logs on stderr
+**Output:** YAML on stdout (JSON with `--format json`), logs on stderr
 
 `root` is stated once and is the only absolute path in the document; every
 `path` beneath it is relative to it.
 
+`lane` names which enumerator produced the population — `walk` (the default
+crawl) or `projection` (`VAT_RESOURCES_CRAWL=projection`). Two scans of one tree
+that report different populations are only interpretable if each says which lane
+produced it, so the field is derived from the load that ran rather than read back
+from the environment.
+
 **Example:**
 ```bash
 # Recursively scan all *.md files under docs/
@@ -107,7 +114,11 @@ for the loud-cwd fallback policy and the projectRoot discovery ladder.
 
 **Exit Codes:**
 - `0` - Validation passed
-- `1` - Validation errors found
+- `1` - Validation errors found — including a run that scanned no file at all
+  (`filesScanned: 0`), which is reported as one non-overridable
+  `RESOURCE_CHECK_BROKEN` error rather than as a pass: a `--collection` that
+  matched nothing or a path with no markdown is not a verdict about anything.
+  The reason and the remedy are also printed on stderr as a warning
 - `2` - System error
 
 **Output:**
@@ -185,7 +196,6 @@ behind RFC-3986-compliant leading-`/` resolution.
 Place `vibe-agent-toolkit.config.yaml` at project root:
 
 ```yaml
-version: 1
 resources:
   include:
     - "docs/**/*.md"

package/docs/skill-test.md

@@ -161,21 +161,22 @@ The suite is never copied into anything the executor can reach. Each eval's decl
 
 ## Exit codes
 
-The harness deliberately separates "the evals failed" from "the harness broke", so
-CI can tolerate one and gate on the other.
+The same three-way contract as every other `vat` command, so a CI consumer can
+tolerate eval failures while failing closed on a harness that could not run.
 
-- `0` - Run completed, all expectations passed
-- `1` - Harness broke (internal error, stall, timeout, grader nonce failure)
-- `2` - Preflight failure (bad config, unresolvable required companion, auth guard, `build` hook failed)
-- `3` - Bootstrap failure
-- `4` - **Eval failure** — the run completed but expectations did not all pass
+- `0` - Run completed, all expectations passed (or `--allow-eval-failure` suppressed a failing verdict)
+- `1` - **Eval failure** — the run completed and produced a valid `grading.json`; expectations did not all pass
+- `2` - The harness could not run. A `Reason: <reason>` line on stderr says why:
+  - `internal` — the harness broke (executor/grader crash, stall, timeout, grader nonce failure)
+  - `preflight` — the environment or inputs need fixing (bad config, unresolvable required companion, auth guard, missing security ack, `build` hook failed)
+  - `bootstrap` — `evals.json` was absent, so VAT wrote a starter template next to the skill source; fill it in and re-run
 
 ```bash
 vat skill test run my-skill --i-understand-this-runs-skill-code
 case $? in
   0) ;;
-  4) echo "evals failed (tolerated)" ;;
-  *) exit 1 ;;    # harness broke — fail the build
+  1) echo "evals failed (tolerated)" ;;
+  *) exit 1 ;;    # harness could not run — fail the build; read Reason: on stderr
 esac
 ```