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

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/resources.md

@@ -117,20 +117,25 @@ 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
 # 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
+#     issues:
+#       - line: 15
+#         column: 25
+#         code: LINK_BROKEN_FILE
+#         severity: error
+#         message: Link target not found: ./missing.md
 # duration: 456ms
 # ---
 ```
@@ -182,6 +187,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 ['**/*']"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/cli",
-  "version": "0.1.41-rc.6",
+  "version": "0.1.41-rc.7",
   "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.7",
+    "@vibe-agent-toolkit/agent-schema": "0.1.41-rc.7",
+    "@vibe-agent-toolkit/agent-skills": "0.1.41-rc.7",
+    "@vibe-agent-toolkit/claude-marketplace": "0.1.41-rc.7",
+    "@vibe-agent-toolkit/discovery": "0.1.41-rc.7",
+    "@vibe-agent-toolkit/gateway-mcp": "0.1.41-rc.7",
+    "@vibe-agent-toolkit/rag": "0.1.41-rc.7",
+    "@vibe-agent-toolkit/rag-lancedb": "0.1.41-rc.7",
+    "@vibe-agent-toolkit/resources": "0.1.41-rc.7",
+    "@vibe-agent-toolkit/utils": "0.1.41-rc.7",
     "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.7",
     "rimraf": "^6.0.1",
     "typescript": "^5.7.3",
     "vitest": "^3.2.4"