@vibe-agent-toolkit/cli 0.2.0-rc.5 → 0.2.0-rc.7

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)
@@ -96,7 +96,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 +148,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 +248,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

@@ -94,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

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

package/docs/resources.md

@@ -114,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:**

package/docs/skills.md

@@ -47,85 +47,58 @@ See `docs/validation-codes.md` for the full code reference with per-code descrip
 
 ### vat skills validate [path]
 
-**Purpose:** Validate SKILL.md files for correctness and best practices
+**Purpose:** Validate the skills a project declares, before packaging — the gate `vat validate` and `vat verify` run as their `skills` phase.
 
 **What it does:**
-1. Discovers all SKILL.md files in the target directory
-2. Validates both resource rules (links, frontmatter) and skill-specific rules
-3. Reports errors and warnings in structured format
-4. Exits 0 if valid, 1 if errors found (warnings don't fail)
-
-**Validation Modes:**
-
-**Project mode (default):**
-- Respects `vibe-agent-toolkit.config.yaml` boundaries
-- Strict filename validation - must be exactly "SKILL.md" (case-sensitive)
-- Errors on non-standard filenames (skill.md, Skill.md, etc.)
-
-**User mode (--user flag):**
-- Scans `~/.claude/plugins` and `~/.claude/skills`
-- Permissive validation - non-standard filenames generate warnings only
-- More tolerant for user-installed content
-
-**Path mode (explicit path):**
-- Scans specified directory
-- Strict filename validation like project mode
+1. Reads `vibe-agent-toolkit.config.yaml` from `[path]` (default: current directory) and discovers every file its `skills.include` / `skills.exclude` globs match
+2. Validates each with the packaging validator: frontmatter, links and link depth, size/complexity, `files:` config, compat observations — under the merged `skills.defaults` + `skills.config.<name>` validation config (`severity` + `allow`)
+3. Publishes a YAML document to stdout and a findings report to stderr
+4. Exits 0, 1 or 2 — see below
 
 **Arguments:**
-- `[path]` - Path to validate (defaults to current directory)
+- `[path]` — a directory that holds `vibe-agent-toolkit.config.yaml`. It scopes *which config is read*, not which files are scanned; the globs in that config do the scanning. A path that does not exist, is not a directory, or holds no config is refused (exit 2) rather than silently rescoping the run to nothing. There is no `--user` mode and no "scan this directory" mode.
 
 **Options:**
-- `--user` - Validate user-installed skills in ~/.claude
-- `--debug` - Enable debug logging
+- `--skill <name>` — validate one discovered skill only (narrows what is reported on, not what counts as declared test input)
+- `-v, --verbose` — publish every validated skill, findings or not, with full detail (`allErrors`, `ignoredErrors`, `observations`, `evidence`, metadata) and one block per finding on stderr
+- `-d, --debug` — debug logging
 
-**Exit Codes:**
-- `0` - All validations passed
-- `1` - Validation errors found (warnings don't fail)
-- `2` - System error (directory not found, config invalid)
+**Exit codes:**
 
-**Validation Checks:**
+| Exit | When |
+|---|---|
+| `0` | No active `error` finding (warnings and info do not fail; allowed errors do not fail) |
+| `1` | An active `error` finding on any skill, **or** the run validated no skill: `skills.include` matched nothing (typo, renamed directory, an `exclude` that swallows every match). Refused as one non-overridable `RESOURCE_CHECK_BROKEN` naming the globs — a green over zero skills is not a verdict |
+| `2` | Could not run: `[path]` refused, config invalid, `projectRoot` not found |
 
-*Resource validation:*
-- Internal file links (relative paths)
-- Anchor links within files (#heading)
-- Cross-file anchor links (file.md#heading)
-- Frontmatter schema validation
+A config with no `skills:` block at all is "nothing to validate": no document, exit 0 — declaring no skills is a choice, and both orchestrators skip the phase on that config.
 
-*Skill-specific validation:*
-- Reserved word checks (name field)
-- XML tag detection (name/description fields)
-- Console compatibility warnings
-- Required frontmatter fields (name, description)
+**What a matched file must be.** Every file the globs match is validated as a skill and counted in `skillsValidated`. A matched file with no YAML frontmatter block — or one whose block does not parse — is refused with `SKILL_MISSING_FRONTMATTER` at `error` (non-overridable), located at the file's project-relative path. So a glob that drifts onto a `README.md`, or a `SKILL.md` that lost its fence, fails the run instead of passing under its H1 as a name. A frontmatter block without a `name` is legal (agentskills.io makes `name` optional) and is not refused on that ground.
 
-*Filename validation:*
-- Must be "SKILL.md" (uppercase)
-- Strict mode: errors on skill.md, Skill.md
-- Permissive mode: warnings only
+**Output:**
+
+Default `results[]` lists only skills WITH findings — per-skill counts and a per-code tally, dominant code first; a clean skill is omitted and a zero bucket is an absent field. `skillsValidated` is the true denominator regardless. `issueCounts` always equals the sum of the per-skill rows plus `runIssueCounts` (run-level findings: `ALLOW_UNUSED` entries and the zero-skill refusal).
 
-**Output Format:**
 ```yaml
-status: success | error
-skillsValidated: 3
+status: error            # success | warning | error — worst actionable severity in the run
+issueCounts: { errors: 1, warnings: 0, info: 0 }
+runIssueCounts: { errors: 0, warnings: 0, info: 0 }
+skillsValidated: 2
 results:
-  - path: resources/skills/SKILL.md
-    status: success
-    skill:
-      name: my-skill
-      description: Skill description
-    issues: []
-durationSecs: 0.245
+  - skillName: Beta
+    status: error
+    errors: 1
+    codes:
+      SKILL_MISSING_FRONTMATTER: 1
+runIssues: []
+durationSecs: 0.31
 ```
 
-**Examples:**
-```bash
-# Validate all project skills (default)
-vat skills validate
-
-# Validate user-installed skills
-vat skills validate --user
+stderr prints the same thing as one line per skill, with every `error` finding rendered in full beneath its row (location, message, fix) at every verbosity.
 
-# Validate specific directory
-vat skills validate packages/my-agent/resources/skills
+**Example:**
+```bash
+vat skills validate packages/my-pkg/   # read packages/my-pkg/vibe-agent-toolkit.config.yaml
 ```
 
 **Requirements:**
@@ -525,6 +498,18 @@ skills:
     warning: Non-standard filename (should be SKILL.md)
 ```
 
+When the scan could not list a directory (a root-owned or quarantined directory under
+`~/.claude/plugins`, say), `status` is `warning` and the document names each such directory,
+root-relative, with the errno — `skillsFound` is then a floor, not the answer:
+
+```yaml
+status: warning
+...
+unreadable:
+  - path: plugins/locked
+    code: EACCES
+```
+
 **Examples:**
 ```bash
 # List project skills (default)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/cli",
-  "version": "0.2.0-rc.5",
+  "version": "0.2.0-rc.7",
   "description": "Command-line interface for vibe-agent-toolkit",
   "type": "module",
   "bin": {
@@ -41,20 +41,20 @@
   "author": "Jeff Dutton",
   "license": "MIT",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.13.0"
   },
   "//dependencies-note": "DO NOT add example agent packages or adopter packages here. Adopter packages (like vat-development-agents) depend on the CLI binary at build time — declaring them as deps creates a circular build dependency. They are built in a second turbo pass via package#task overrides in turbo.json.",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.71.2",
-    "@vibe-agent-toolkit/agent-config": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/agent-skills": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/claude-marketplace": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/discovery": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/gateway-mcp": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/projection-sqlite": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/resources": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/schema": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/utils": "0.2.0-rc.5",
+    "@vibe-agent-toolkit/agent-config": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/agent-skills": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/claude-marketplace": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/discovery": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/gateway-mcp": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/projection-sqlite": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/resources": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/schema": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/utils": "0.2.0-rc.7",
     "adm-zip": "^0.6.0",
     "commander": "^12.1.0",
     "picomatch": "^4.0.3",
@@ -69,12 +69,12 @@
     "@types/picomatch": "^4.0.2",
     "@types/semver": "^7.7.1",
     "@types/tar": "^6.1.13",
-    "@vibe-agent-toolkit/dev-tools": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/rag": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/rag-lancedb": "0.2.0-rc.5",
+    "@vibe-agent-toolkit/dev-tools": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/rag": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/rag-lancedb": "0.2.0-rc.7",
     "rimraf": "^6.0.1",
     "typescript": "^5.7.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11"
   },
   "publishConfig": {
     "access": "public"
@@ -83,10 +83,10 @@
     "type": "git",
     "url": "https://github.com/jdutton/vibe-agent-toolkit.git"
   },
-  "//peerDependencies-note": "The RAG backends are OPTIONAL PEERS, never optionalDependencies. `optionalDependencies` are INSTALLED BY DEFAULT by npm and pnpm alike - 'optional' there means the install may fail without failing the build, not that it is skipped - so declaring them that way shipped ~240 MB (onnxruntime-web 136 MB, a LanceDB platform binary 93 MB, a third apache-arrow, protobufjs) to every adopter, contradicting the seam in src/utils/optional-backend.ts that exists precisely to keep them out. Optional peers are NOT auto-installed, so the manifest now says what that module already says: these ship separately, and an absent one is a legible error naming the package to install. projection-sqlite is deliberately NOT in this group: it has zero third-party dependencies (only node:sqlite, which is built into Node) and a 152 KB dist, so the platform-binary argument that justifies the seam is simply false for it. It is also what `vat resources query` builds its ephemeral in-memory store from, and a query surface that works only where a backend was separately installed is the capability gate the projection design forbids.",
+  "//peerDependencies-note": "The RAG backends are OPTIONAL PEERS, never optionalDependencies. `optionalDependencies` are INSTALLED BY DEFAULT by npm and pnpm alike - 'optional' there means the install may fail without failing the build, not that it is skipped - so declaring them that way shipped ~287 MB unpacked (onnxruntime-web 137.5 MB, a LanceDB platform binary 97.8 MB, gpt-tokenizer 42.2 MB, apache-arrow 5.3 MB, protobufjs 3.0 MB; measured on darwin-arm64 against this release's pins, and the platform binary is larger on win32-x64) to every adopter, contradicting the seam in src/utils/optional-backend.ts that exists precisely to keep them out. Optional peers are NOT auto-installed, so the manifest now says what that module already says: these ship separately, and an absent one is a legible error naming the package to install. projection-sqlite is deliberately NOT in this group: it has zero third-party dependencies (only node:sqlite, which is built into Node) and a 152 KB dist, so the platform-binary argument that justifies the seam is simply false for it. It is also what `vat resources query` builds its ephemeral in-memory store from, and a query surface that works only where a backend was separately installed is the capability gate the projection design forbids.",
   "peerDependencies": {
-    "@vibe-agent-toolkit/rag": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/rag-lancedb": "0.2.0-rc.5"
+    "@vibe-agent-toolkit/rag": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/rag-lancedb": "0.2.0-rc.7"
   },
   "peerDependenciesMeta": {
     "@vibe-agent-toolkit/rag": {