@vibe-agent-toolkit/cli 0.1.41-rc.6 → 0.1.41-rc.8

package/docs/audit.md

@@ -183,9 +183,9 @@ detection strategy doc, workstream B).
 status: success
 summary:
   filesScanned: 42
-  success: 40
-  warnings: 2
-  errors: 0
+  filesPassed: 40
+  filesWithWarnings: 2
+  filesWithErrors: 0
   marketplaces: 2
   standalonePlugins: 3
   standaloneSkills: 5
@@ -313,31 +313,57 @@ Warnings indicate potential issues but don't prevent usage:
 Structured YAML report for programmatic parsing:
 
 ```yaml
+root: /abs/path/to/scan/root   # The ONE absolute path in the document
 status: success | warning | error
 summary:
   filesScanned: number
-  success: number      # Files with no issues
-  warnings: number     # Files with warnings only
-  errors: number       # Files with errors
-issues:
-  errors: number       # Total error count across all files
-  warnings: number     # Total warning count across all files
-  info: number         # Total info count across all files
+  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
+issueCounts:                  # FINDINGS, not files — same field name and meaning
+  errors: number              #   as the `issueCounts` on each entry below
+  warnings: number
+  info: number
 duration: "123ms"
 files:
-  - path: /path/to/resource
+  - path: plugins/my-plugin            # relative to `root`
     status: success | warning | error
     type: plugin | marketplace | registry | skill
-    issues: []
+    issues:
+      - location: plugins/my-plugin/.claude-plugin/plugin.json   # relative to `root`
 ```
 
+#### One stated root, and everything relative to it
+
+`root` is the invocation scan root and the only absolute path a report contains.
+Every `path` and every issue `location` beneath it is forward-slashed and
+relative to that root, so:
+
+- `join(root, path)` and `join(root, location)` name real files — a consumer
+  never has to guess, or reimplement, the base a value was written against.
+- A `location` identifies a file uniquely across the whole document, even when a
+  run spans several projects that share internal layout (two `plugins/plugin-a`
+  directories under different parents cannot collapse to one string).
+- Nothing but `root` can leak the developer's or CI runner's home directory.
+
+The scan root is an ANCHOR, not a validation-policy boundary. Per-skill
+packaging rules still come from each skill's nearest-ancestor
+`vibe-agent-toolkit.config.yaml` (configs do not compose); that discovery has no
+say in how a path is spelled.
+
+`--user` scans three sibling directories (`plugins/`, `skills/`,
+`marketplaces/`), so its `root` is their shared Claude config dir
+(`$CLAUDE_CONFIG_DIR`, else `~/.claude`). A URL audit omits `root`: the clone
+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.
+
 ### Standard Error (stderr)
 
-Human-readable error messages and logs:
+Human-readable error messages and logs. Paths are root-relative here too:
 
 ```
 ERROR: Audit failed: 2 file(s) with errors
-ERROR: /path/to/skill.md:
+ERROR: skills/my-skill/SKILL.md:
 ERROR:   [SKILL_MISSING_NAME] name field is required in frontmatter
 ERROR:     at: line 1
 ERROR:     fix: Add 'name: skill-name' to frontmatter

package/docs/doctor.md

@@ -21,13 +21,24 @@ providing actionable suggestions for any problems found.
 7. CLI build status (when running from VAT source tree)
 
 **Options:**
-- `--verbose` - Show all checks (including passing ones)
+- `--verbose` - Show all checks (including passing and skipped ones)
+
+**Check outcomes:**
+
+| Icon | Outcome | Meaning |
+|------|---------|---------|
+| ✅ | `pass` | The check ran and the thing is fine |
+| ❌ | `fail` | The check ran and the thing is wrong — the only outcome that affects the exit code |
+| ❓ | `undetermined` | The check could not reach an answer (registry unreachable, file unreadable). **Nothing was verified** — this is not a pass |
+| ⏭️ | `skipped` | The check does not apply here (e.g. a VAT-source-tree-only check outside the source tree) |
 
 **Exit Codes:**
-- `0` - All checks passed
+- `0` - No check failed (an undetermined check is reported in the output, not fatal)
 - `1` - One or more checks failed
 
-**Output:** Human-friendly formatted text with emojis
+**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 —
+so the counts can never contradict the list above them.
 
 ## Usage Examples
 
@@ -39,17 +50,34 @@ Check all diagnostic items and show only failures:
 vat doctor
 ```
 
-Output when all checks pass:
+Output when all checks pass (the concise view prints no check blocks, and says so):
 ```
 🩺 vat doctor
 
 Running diagnostic checks...
 
-📊 Results: 7/7 checks passed
+📊 Results: 7 checks — 7 passed, 0 failed, 0 undetermined, 0 skipped
+   7 not shown (nothing to report) — re-run with --verbose to see every check.
 
 ✨ All checks passed! Your vat setup looks healthy.
 ```
 
+Output when a check could not be determined (here: the npm registry was unreachable):
+```
+🩺 vat doctor
+
+Running diagnostic checks...
+
+❓ vat version
+   Unable to check for updates: not found: npm
+
+📊 Results: 7 checks — 6 passed, 0 failed, 1 undetermined, 0 skipped
+   6 not shown (nothing to report) — re-run with --verbose to see every check.
+
+❓ Nothing failed, but 1 check(s) could not be determined — that is not the same as healthy.
+```
+Exit code is still `0` — nothing failed — but the run is *not* reported as healthy.
+
 ### Verbose Mode
 
 Show all checks including passing ones:
@@ -85,7 +113,7 @@ Running diagnostic checks...
 ✅ CLI build status
    Build is up to date (v0.1.0)
 
-📊 Results: 7/7 checks passed
+📊 Results: 7 checks — 7 passed, 0 failed, 0 undetermined, 0 skipped
 
 ✨ All checks passed! Your vat setup looks healthy.
 ```
@@ -110,7 +138,8 @@ Output:
 
 Running diagnostic checks...
 
-📊 Results: 7/7 checks passed
+📊 Results: 7 checks — 7 passed, 0 failed, 0 undetermined, 0 skipped
+   7 not shown (nothing to report) — re-run with --verbose to see every check.
 
 ✨ All checks passed! Your vat setup looks healthy.
 ```
@@ -250,14 +279,20 @@ fi
 ### VAT Version Check
 
 - **Purpose:** Inform about available updates (advisory only)
-- **Always passes:** This check never fails
+- **Never fails:** an available update is a `pass` with a suggestion
+- **Undetermined:** if the npm registry cannot be reached, the outcome is
+  `undetermined` (❓), not `pass` — doctor did not verify that you are current
 - **Suggestion:** Shows upgrade command if update available
 
 ### CLI Build Status Check
 
 - **When:** Only runs when in VAT source tree
 - **Purpose:** Ensure CLI build matches source version (for VAT developers)
-- **Skipped:** When running installed VAT globally
+- **Skipped (⏭️):** When running installed VAT globally, or when no project root
+  was detected — the check does not apply
+- **Undetermined (❓):** When the version files exist but cannot be read or
+  parsed. Doctor cannot tell whether the build is stale, which is different from
+  the check not applying
 - **Fix:** Run `bun run build` in VAT source directory
 
 ## Requirements
@@ -278,4 +313,5 @@ for terminology.
 - Run `vat doctor` before reporting issues to verify environment
 - Use `--verbose` flag when debugging to see all check details
 - Doctor checks can be run from any subdirectory in your project
-- Exit code 0 means all checks passed (useful for scripts)
+- Exit code 0 means no check *failed*; read the counts line to see whether any
+  check was undetermined (useful for scripts)

package/docs/index.md

@@ -102,7 +102,7 @@ Diagnose vat setup and environment health
 
 **Exit codes:**
 
-- `0` - All checks passed
+- `0` - No check failed (a check that could not be determined is reported as ❓, not fatal)
 - `1` - One or more checks failed
 
 **Creates/modifies:** None (read-only diagnostics)

package/docs/rag.md

@@ -36,10 +36,15 @@ vat rag clear
 5. Supports incremental updates (skips files with unchanged content)
 
 **Path Argument Behavior:**
-- `[path]` specifies the **base directory** to start crawling from
-- Recursively finds all `*.md` files under that directory (default pattern: `**/*.md`)
-- When path is specified, **config patterns are ignored** (to avoid pattern conflicts)
-- To use config patterns, run without path argument: `vat rag index`
+- `[path]` restricts the crawl to that subtree of the project
+- Recursively finds all `*.md` / `*.html` files under that directory
+- The path **replaces** the config's `resources.include` patterns
+- The config's `resources.exclude` patterns **still apply**, so a path run never
+  indexes build output or vendored trees the project excluded
+- If the path lies outside the project root the config's patterns cannot apply;
+  they are dropped and a warning is printed
+- To index the project's full configured set, run without a path argument:
+  `vat rag index`
 
 **Options:**
 - `[path]` - Base directory to crawl (defaults to current directory)

package/docs/resources.md

@@ -18,14 +18,19 @@ including link integrity checking and anchor validation.
 4. Exits 0 always (informational only)
 
 **Path Argument:**
-- `[path]` specifies the **base directory** to start crawling from
-- Recursively finds all `*.md` files under that directory (default pattern: `**/*.md`)
-- When path is specified, **config patterns are ignored** (to avoid pattern conflicts)
-- To use config patterns, run without path argument: `vat resources scan`
+- `[path]` restricts the scan to that subtree of the project
+- Recursively finds all `*.md` / `*.html` files under that directory
+- The path **replaces** the config's `resources.include` patterns
+- The config's `resources.exclude` patterns **still apply** — a path run never
+  scans build output, vendored trees, or test fixtures the project excluded
+- To scan the project's full configured set, run without a path argument:
+  `vat resources scan`
 
 **Options:**
 - `[path]` - Base directory to crawl (defaults to current directory)
 - `--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)
 
 **Exit Codes:**
 - `0` - Always (scan is informational)
@@ -33,23 +38,28 @@ including link integrity checking and anchor validation.
 
 **Output:** YAML on stdout, logs on stderr
 
+`root` is stated once and is the only absolute path in the document; every
+`path` beneath it is relative to it.
+
 **Example:**
 ```bash
 # Recursively scan all *.md files under docs/
-vat resources scan docs/
+vat resources scan docs/ --verbose
 # Equivalent to: find all files matching docs/**/*.md pattern
 
 # Output:
 # ---
 # status: success
+# root: /home/you/my-project
 # filesScanned: 12
 # linksFound: 47
 # anchorsFound: 23
+# durationSecs: 0.234
 # files:
 #   - path: docs/README.md
 #     links: 5
 #     anchors: 3
-# duration: 234ms
+#     checksum: 47dd7b50af765df240fe2514f029fc697c907fc37a3267e22060f2f9f611975c
 # ---
 ```
 
@@ -78,14 +88,21 @@ for the loud-cwd fallback policy and the projectRoot discovery ladder.
 4. Exits 0 if valid, 1 if errors found
 
 **Path Argument:**
-- `[path]` specifies the **base directory** to start crawling from
-- Recursively finds all `*.md` files under that directory (default pattern: `**/*.md`)
-- When path is specified, **config patterns are ignored** (to avoid pattern conflicts)
-- To use config patterns, run without path argument: `vat resources validate`
+- `[path]` restricts the scan to that subtree of the project
+- Recursively finds all `*.md` / `*.html` files under that directory
+- The path **replaces** the config's `resources.include` patterns
+- The config's `resources.exclude` patterns **still apply** — a path run never
+  scans build output, vendored trees, or test fixtures the project excluded
+- To scan the project's full configured set, run without a path argument:
+  `vat resources validate`
 
 **Options:**
 - `[path]` - Base directory to crawl (defaults to current directory)
 - `--debug` - Enable debug logging
+- `-v, --verbose` - Show all scanned resources, including those without issues. By
+  default `issues` carries one counts-only row per file with findings
+  (`{file, errors?, warnings?, info?, codes}`); `--verbose` replaces each row with
+  its per-issue detail. Every other output field is identical in both modes.
 - `--no-check-frontmatter-links` - Skip frontmatter URI-reference link validation across all collections (default: enabled)
 
 **Exit Codes:**
@@ -108,8 +125,7 @@ vat resources validate docs/
 # status: success
 # filesScanned: 12
 # linksChecked: 47
-# anchorsChecked: 23
-# duration: 456ms
+# durationSecs: 0.456
 # ---
 ```
 
@@ -117,21 +133,26 @@ vat resources validate docs/
 ```bash
 vat resources validate docs/
 
-# stderr:
-# docs/README.md:15:25: Link target not found: ./missing.md
-# docs/guide.md:42:10: Broken anchor: #non-existent-section
+# stderr:  (file:line:column: severity: message — only `error` fails the run)
+# docs/README.md:15:25: error: Link target not found: ./missing.md
+# docs/guide.md:42:10: error: Broken anchor: #non-existent-section
 
 # stdout:
 # ---
-# status: failed
+# status: error
 # errorsFound: 2
-# errors:
+# filesWithErrors: 2
+# issueCounts: { errors: 2, warnings: 0, info: 0 }
+# issueSummary: { LINK_BROKEN_FILE: 1, LINK_BROKEN_ANCHOR: 1 }
+# issues:
 #   - file: docs/README.md
-#     line: 15
-#     column: 25
-#     type: broken-link
-#     message: Link target not found: ./missing.md
-# duration: 456ms
+#     issues:
+#       - line: 15
+#         column: 25
+#         code: LINK_BROKEN_FILE
+#         severity: error
+#         message: Link target not found: ./missing.md
+# durationSecs: 0.456
 # ---
 ```
 
@@ -182,6 +203,17 @@ resources:
       FRONTMATTER_SCHEMA_ERROR: error
 ```
 
+**Dot-directories are scanned.** `**` traverses path segments beginning with a
+dot, so the default `**/*.md` reaches `.claude/`, `.github/` and the like — as do
+your own patterns. Visibility is decided by git and by `exclude`, never by a
+leading dot. To keep a dotted tree out of the scan, exclude it by name:
+
+```yaml
+resources:
+  exclude:
+    - ".claude/worktrees/**"
+```
+
 ## Integration with vibe-validate
 
 The test-format error output (stderr) integrates seamlessly with vibe-validate:

package/docs/skills.md

@@ -22,9 +22,9 @@ skills:
           LINK_TO_NAVIGATION_FILE: ignore   # this skill links to READMEs on purpose
           ALLOW_EXPIRED: error              # zero-tolerance expiry
         allow:
-          PACKAGED_UNREFERENCED_FILE:
+          LINK_TO_GITIGNORED_FILE:
             - paths: ["templates/runtime.json"]
-              reason: "consumed programmatically at runtime"
+              reason: "generated at install time, deliberately untracked"
               expires: "2026-09-30"
           SKILL_LENGTH_EXCEEDS_RECOMMENDED:
             - reason: "whole-skill concern; paths defaults to ['**/*']"
@@ -362,11 +362,14 @@ to override (single-skill sources only).
 | `windsurf` | `~/.codeium/windsurf/skills/` | `.windsurf/skills/` |
 | `agents` | `~/.agents/skills/` | `.agents/skills/` |
 
-These paths were last reviewed against vendor conventions on 2026-04-08 and are
-not verified at build or test time — the tests assert the table's shape, never
-that a path is where a platform actually looks. If a vendor moves its convention,
-installs land somewhere unread and every VAT check still passes. Re-check the
-vendor's documentation before relying on a non-`claude` target.
+These paths were last reviewed against each platform's own published docs on
+2026-07-30 (all fourteen unchanged) and are not verified at build or test time.
+The tests derive their expectations from the table and assert invariants of it —
+every target present, both scopes relative and forward-slash only, and that the
+resolver composes base + relative path. No test can check that a path is where a
+platform actually looks. If a vendor moves its convention, installs land
+somewhere unread and every VAT check still passes. Re-check the vendor's
+documentation before relying on a non-`claude` target.
 
 **Visibility:** VAT's own inspection commands are Claude-scoped — `vat skills
 list --user` and `vat audit --user` read `~/.claude` only. A skill installed to
@@ -495,6 +498,7 @@ only when the `SKILL.md` declares none.
 **Output Format:**
 ```yaml
 status: success
+root: /abs/path/to/project
 context: project | user
 skillsFound: 3
 skills:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/cli",
-  "version": "0.1.41-rc.6",
+  "version": "0.1.41-rc.8",
   "description": "Command-line interface for vibe-agent-toolkit",
   "type": "module",
   "bin": {
@@ -41,16 +41,16 @@
   "//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.1.41-rc.6",
-    "@vibe-agent-toolkit/agent-schema": "0.1.41-rc.6",
-    "@vibe-agent-toolkit/agent-skills": "0.1.41-rc.6",
-    "@vibe-agent-toolkit/claude-marketplace": "0.1.41-rc.6",
-    "@vibe-agent-toolkit/discovery": "0.1.41-rc.6",
-    "@vibe-agent-toolkit/gateway-mcp": "0.1.41-rc.6",
-    "@vibe-agent-toolkit/rag": "0.1.41-rc.6",
-    "@vibe-agent-toolkit/rag-lancedb": "0.1.41-rc.6",
-    "@vibe-agent-toolkit/resources": "0.1.41-rc.6",
-    "@vibe-agent-toolkit/utils": "0.1.41-rc.6",
+    "@vibe-agent-toolkit/agent-config": "0.1.41-rc.8",
+    "@vibe-agent-toolkit/agent-schema": "0.1.41-rc.8",
+    "@vibe-agent-toolkit/agent-skills": "0.1.41-rc.8",
+    "@vibe-agent-toolkit/claude-marketplace": "0.1.41-rc.8",
+    "@vibe-agent-toolkit/discovery": "0.1.41-rc.8",
+    "@vibe-agent-toolkit/gateway-mcp": "0.1.41-rc.8",
+    "@vibe-agent-toolkit/rag": "0.1.41-rc.8",
+    "@vibe-agent-toolkit/rag-lancedb": "0.1.41-rc.8",
+    "@vibe-agent-toolkit/resources": "0.1.41-rc.8",
+    "@vibe-agent-toolkit/utils": "0.1.41-rc.8",
     "adm-zip": "^0.6.0",
     "commander": "^12.1.0",
     "picomatch": "^4.0.3",
@@ -65,7 +65,7 @@
     "@types/picomatch": "^4.0.2",
     "@types/semver": "^7.7.1",
     "@types/tar": "^6.1.13",
-    "@vibe-agent-toolkit/dev-tools": "0.1.41-rc.6",
+    "@vibe-agent-toolkit/dev-tools": "0.1.41-rc.8",
     "rimraf": "^6.0.1",
     "typescript": "^5.7.3",
     "vitest": "^3.2.4"