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

package/dist/commands/audit.js

@@ -4,17 +4,20 @@
  */
 import * as fs from 'node:fs';
 import { existsSync as fsExistsSync } from 'node:fs';
-import { detectDeclaredButMissing, detectMarketplacePluginSourceMissing, detectPresentButUndeclared, detectReferenceTargetMissing, detectResourceFormat, enumerateSurfaces, validate, validateMarketplace, validateSkill, validateSkillForPackaging, } from '@vibe-agent-toolkit/agent-skills';
-import { analyzeCompatibility, checkSettingsCompatibility, detectSkillClaudePluginNameMismatch, extractClaudeMarketplaceInventory, extractClaudePluginInventory, getClaudeUserPaths, readEffectiveSettings, validatePlugin, } from '@vibe-agent-toolkit/claude-marketplace';
+import { calculateValidationStatus, countBySeverity, } from '@vibe-agent-toolkit/agent-schema';
+import { crawlAndResolveRegistry, detectDeclaredButMissing, detectMarketplacePluginSourceMissing, resetPackagingRegistryCache, detectPresentButUndeclared, detectReferenceTargetMissing, detectResourceFormat, enumerateSurfaces, validate, validateMarketplace, validateSkill, validateSkillForPackaging, } from '@vibe-agent-toolkit/agent-skills';
+import { analyzeCompatibility, checkSettingsCompatibility, detectSkillClaudePluginNameMismatch, crawlSkillLinkRegistry, extractClaudeMarketplaceInventory, extractClaudePluginInventory, getClaudeUserPaths, readEffectiveSettings, validatePlugin, } from '@vibe-agent-toolkit/claude-marketplace';
 import { detectFormat } from '@vibe-agent-toolkit/discovery';
-import { findProjectRoot, gitFindRoot, GitTracker, isAbsolutePath, isGitUrl, parseGitUrl, resetProjectRootCaches, safePath, } from '@vibe-agent-toolkit/utils';
+import { findProjectRoot, gitFindRoot, GitTracker, isAbsolutePath, isGitUrl, issueLocation, parseGitUrl, resetProjectRootCaches, safePath, } from '@vibe-agent-toolkit/utils';
 import { Command } from 'commander';
 import picomatch from 'picomatch';
-import { resetSkillDiscoveryCache, resolveSkillPackagingConfig, stripValidationAllowForDisplay, } from '../skill-resolution/packaging-config.js';
+import { resetSkillDiscoveryCache, resolveProjectDeclaredEvalSuites, resolveSkillPackagingConfig, stripValidationAllowForDisplay, } from '../skill-resolution/packaging-config.js';
 import { handleCommandError } from '../utils/command-error.js';
 import { ConfigLoadError, loadConfig, resetLoadedConfigCache, } from '../utils/config-loader.js';
+import { formatIssueLines, formatSeverityBreakdown, issuesToRenderAtVerbosity, } from '../utils/issue-rendering.js';
 import { createLogger } from '../utils/logger.js';
 import { writeYamlOutput } from '../utils/output.js';
+import { relativizePathEntries } from '../utils/relativize-paths.js';
 import { mergeSkillPackagingConfig } from '../utils/skill-packaging-config.js';
 import { renderSkillQualityFooter } from '../utils/skill-quality-footer.js';
 import { computeConfigVerdicts } from '../utils/verdict-helpers.js';
@@ -87,33 +90,53 @@ async function buildVATProjectContext(scanRoot, logger) {
  * Compat verdicts (COMPAT_TARGET_*) are computed from the result's observations
  * and the config-level targets, then merged into the issue list.
  */
-function packagingResultToValidationResult(skillPath, result, configTargets) {
+/**
+ * The one-line human summary of a severity distribution.
+ *
+ * Every result that carries findings renders its counts the same way, so a reader
+ * comparing two entries is comparing the same sentence.
+ */
+function formatCountsSummary(counts) {
+    return `${counts.errors} errors, ${counts.warnings} warnings, ${counts.info} info`;
+}
+/**
+ * Append findings to a result and re-derive everything that describes them.
+ *
+ * The audit pipeline appends detector findings AFTER the primary validator has
+ * already published a status, a counts block and a summary line. Pushing into
+ * `issues` alone left all three describing the pre-append issue list — a plugin
+ * with a warning reported `status: success`, `issueCounts: {0,0,0}` and
+ * `summary: Valid plugin` in the very document that listed the warning.
+ *
+ * Mutates in place, because the audit pipeline hands these results around by
+ * reference and there is no single place a rebuilt copy could be swapped in.
+ */
+function appendIssues(result, issues) {
+    if (issues.length === 0) {
+        return;
+    }
+    result.issues.push(...issues);
+    const counts = countBySeverity(result.issues);
+    result.status = calculateValidationStatus(result.issues);
+    result.issueCounts = counts;
+    result.summary = formatCountsSummary(counts);
+}
+function packagingResultToValidationResult(skillPath, result, configTargets, locationRoot) {
     // allErrors contains all emitted issues (errors + warnings) after severity resolution
     // but without allow suppression — exactly what audit wants. Verdicts are
     // computed from the observations carried on the result.
-    const verdictIssues = computeConfigVerdicts(result.observations, configTargets, skillPath);
+    const verdictIssues = computeConfigVerdicts(result.observations, configTargets, skillPath, locationRoot);
     const issues = verdictIssues.length > 0
         ? [...result.allErrors, ...verdictIssues]
         : result.allErrors;
-    const errorCount = issues.filter(i => i.severity === 'error').length;
-    const warningCount = issues.filter(i => i.severity === 'warning').length;
-    const infoCount = issues.filter(i => i.severity === 'info').length;
-    let status;
-    if (errorCount > 0) {
-        status = 'error';
-    }
-    else if (warningCount > 0) {
-        status = 'warning';
-    }
-    else {
-        status = 'success';
-    }
+    const issueCounts = countBySeverity(issues);
     const out = {
         path: skillPath,
         type: RESOURCE_TYPE_AGENT_SKILL,
-        status,
-        summary: `${errorCount} errors, ${warningCount} warnings, ${infoCount} info`,
+        status: calculateValidationStatus(issues),
+        summary: formatCountsSummary(issueCounts),
         issues,
+        issueCounts,
         metadata: {
             lineCount: result.metadata.skillLines,
             name: result.skillName,
@@ -128,7 +151,7 @@ function packagingResultToValidationResult(skillPath, result, configTargets) {
  * Validate a single SKILL.md file, using config-aware validation if available.
  * Used for direct SKILL.md and vat-agent paths passed to `vat audit`.
  */
-async function validateSingleSkill(skillPath, options, logger, isVATGenerated) {
+async function validateSingleSkill(skillPath, options, logger, locationRoot, isVATGenerated) {
     // Try config-aware validation: walk UP to the skill's nearest-ancestor
     // vibe-agent-toolkit.config.yaml and apply the skill's packaging block. A
     // broken governing config is tolerated here (audit is a bulk linter): log it
@@ -146,13 +169,28 @@ async function validateSingleSkill(skillPath, options, logger, isVATGenerated) {
     const skillConfig = fullConfig === null ? null : stripValidationAllowForDisplay(fullConfig);
     if (skillConfig !== null) {
         logger.debug(`  Using config-aware validation for: ${skillPath}`);
-        const { gitTracker } = await resolveScanContext(safePath.resolve(skillPath));
-        const sharedCtx = gitTracker === null ? undefined : { gitTracker };
+        const { gitTracker } = await resolveScanContext(safePath.resolve(skillPath), locationRoot, logger);
+        // Key the shared registry on the same project root the validator derives,
+        // so every skill under one root parses the corpus once for the whole run
+        // instead of once each.
+        const skillDir = safePath.resolve(skillPath, '..');
+        const projectRoot = findProjectRoot(skillDir) ?? skillDir;
+        // The project's declared eval suites, memoized per config root, so this lane
+        // predicts the same bundle the packager produces: no skill's report counts a
+        // SIBLING skill's eval suite as an ordinary bundled file.
+        const sharedCtx = {
+            registry: await crawlAndResolveRegistry(projectRoot),
+            locationRoot,
+            projectSkills: await resolveProjectDeclaredEvalSuites(skillPath),
+        };
+        if (gitTracker !== null) {
+            sharedCtx.gitTracker = gitTracker;
+        }
         const packagingResult = await validateSkillForPackaging(skillPath, skillConfig, 'source', sharedCtx);
-        return packagingResultToValidationResult(skillPath, packagingResult, skillConfig.targets);
+        return packagingResultToValidationResult(skillPath, packagingResult, skillConfig.targets, locationRoot);
     }
     // Fallback: basic validation
-    const validateOptions = { skillPath };
+    const validateOptions = { skillPath, locationRoot };
     if (options.warnUnreferencedFiles) {
         validateOptions.checkUnreferencedFiles = true;
     }
@@ -175,7 +213,7 @@ export function createAuditCommand() {
     const audit = new Command('audit');
     audit
         .description('Audit Claude plugins, marketplaces, registries, and skills')
-        .argument('[git-url-or-path]', 'Path or git URL to audit. URL forms: https://host/owner/repo.git[#ref[:subpath]], git@host:owner/repo.git, ssh://..., owner/repo (GitHub shorthand), or a GitHub web URL like https://github.com/owner/repo/tree/<ref>/<subpath>. Default: current directory.')
+        .argument('[git-url-or-path]', 'Path or git URL to audit. An argument that names an existing file or directory is always treated as a path. Otherwise, URL forms: https://host/owner/repo.git[#ref[:subpath]], git@host:owner/repo.git, ssh://..., owner/repo (GitHub shorthand), or a GitHub web URL like https://github.com/owner/repo/tree/<ref>/<subpath>. Default: current directory.')
         .option('--no-recursive', 'Disable recursive directory scanning (scans top level only)')
         .option('--exclude <glob>', 'Exclude paths matching glob pattern (repeatable)', collect, [])
         .option('--include-artifacts', 'Include gitignored paths (build artifacts, dependencies) that are excluded by default')
@@ -208,8 +246,12 @@ Description:
 
   Path or URL to audit: resource directory, registry file, SKILL.md file,
   scan directory, or a git URL (HTTPS, SSH, GitHub shorthand, GitHub web URL).
-  When given a URL, VAT shallow-clones to a temp directory, audits, and
-  cleans up on exit. See packages/cli/docs/audit.md for URL forms.
+  An argument naming an existing file or directory is always a path — bare
+  owner/repo shorthand only applies when nothing of that name exists
+  locally, so "vat audit plugins/arc" audits your directory and never
+  contacts the network. When given a URL, VAT shallow-clones to a temp
+  directory, audits, and cleans up on exit. See packages/cli/docs/audit.md
+  for URL forms.
   Default: current directory
   Use --user to audit user-level installation automatically
 
@@ -298,7 +340,10 @@ Examples:
  * and outputs hierarchical YAML. Calls process.exit() when done.
  */
 async function auditUserDirectories(recursive, options, startTime, logger) {
-    const { pluginsDir, skillsDir, marketplacesDir } = getClaudeUserPaths();
+    const { claudeDir, pluginsDir, skillsDir, marketplacesDir } = getClaudeUserPaths();
+    // --user scans three sibling directories; they share ONE enclosing Claude
+    // config dir, so that is the run's single stated root.
+    const scanRoot = safePath.resolve(claudeDir);
     // eslint-disable-next-line security/detect-non-literal-fs-filename -- safe: path constructed from os.homedir()
     const pluginsDirExists = fs.existsSync(pluginsDir);
     // eslint-disable-next-line security/detect-non-literal-fs-filename -- safe: path constructed from os.homedir()
@@ -316,29 +361,29 @@ async function auditUserDirectories(recursive, options, startTime, logger) {
     const results = [];
     if (pluginsDirExists) {
         logger.debug(`Auditing user-level plugins at: ${pluginsDir}`);
-        results.push(...await getValidationResults(pluginsDir, recursive, options, logger));
+        results.push(...await getValidationResults(pluginsDir, recursive, options, logger, scanRoot));
     }
     if (skillsDirExists) {
         logger.debug(`Auditing user-level skills at: ${skillsDir}`);
-        results.push(...await getValidationResults(skillsDir, recursive, options, logger));
+        results.push(...await getValidationResults(skillsDir, recursive, options, logger, scanRoot));
     }
     if (marketplacesDirExists) {
         logger.debug(`Auditing user-level marketplaces at: ${marketplacesDir}`);
-        results.push(...await getValidationResults(marketplacesDir, recursive, options, logger));
+        results.push(...await getValidationResults(marketplacesDir, recursive, options, logger, scanRoot));
     }
     // Run compatibility analysis if --compat flag is set
     const compatMap = options.compat
-        ? await runCompatAnalysis(results, logger) // --settings not supported in --user mode
+        ? await runCompatAnalysis(results, logger, scanRoot) // --settings not supported in --user mode
         : undefined;
     const verbose = options.verbose ?? false;
     const skillResults = results.filter((r) => SKILL_RESULT_TYPES.has(r.type));
-    const hierarchical = buildHierarchicalOutput(skillResults, verbose);
-    const summary = calculateHierarchicalSummary(results, hierarchical, startTime, compatMap, verbose);
+    const hierarchical = buildHierarchicalOutput(skillResults, verbose, scanRoot);
+    const summary = calculateHierarchicalSummary(results, hierarchical, startTime, compatMap, verbose, scanRoot);
     writeYamlOutput(summary);
     if (verbose) {
-        renderVerboseEvidence(results, logger);
+        renderVerboseEvidence(results, scanRoot, logger);
     }
-    logHierarchicalSummary(results, hierarchical, logger);
+    logHierarchicalSummary(results, logger);
 }
 /**
  * Apply severity filtering to validation results.
@@ -358,6 +403,30 @@ async function auditUserDirectories(recursive, options, startTime, logger) {
  */
 /** Skill resource types that can have per-skill validation config. */
 const SKILL_RESULT_TYPES = new Set([RESOURCE_TYPE_AGENT_SKILL, 'vat-agent']);
+/**
+ * The invocation scan root: the ONE base every `path` and `location` in a
+ * report is expressed relative to.
+ *
+ * This is an ANCHOR, not a validation-policy boundary. Deliberately NOT
+ * {@link deriveConfigRoot} — a config root is discovered per resource by
+ * walking up, and a single `vat audit` spans many of them, so using it as the
+ * anchor emits one document in many coordinate systems. The scan root is
+ * whatever the operator pointed the command at, so it is well defined even
+ * where no config or git root exists at all (auditing `~/.claude`, a plugin
+ * cache, a bare directory of skills).
+ *
+ * A file target anchors at its containing directory, so its own `path` reads as
+ * the bare filename rather than as an empty string.
+ *
+ * @internal Exported so tests and the corpus runner derive the run root the same
+ *   way the command does, instead of hand-rolling a second answer.
+ */
+export function deriveScanRoot(targetPath) {
+    const resolved = safePath.resolve(targetPath);
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved is the operator's own audit target
+    const isDirectory = fs.existsSync(resolved) && fs.statSync(resolved).isDirectory();
+    return isDirectory ? resolved : safePath.resolve(resolved, '..');
+}
 /**
  * Derive the project root directory for config loading.
  *
@@ -377,23 +446,15 @@ function deriveConfigRoot(targetPath) {
  * Build the recalculated status and summary after issues have been filtered.
  */
 function buildFilteredResult(result, filteredIssues) {
-    const errorCount = filteredIssues.filter(i => i.severity === 'error').length;
-    const warningCount = filteredIssues.filter(i => i.severity === 'warning').length;
-    const infoCount = filteredIssues.filter(i => i.severity === 'info').length;
-    let status;
-    if (errorCount > 0) {
-        status = 'error';
-    }
-    else if (warningCount > 0) {
-        status = 'warning';
-    }
-    else {
-        status = 'success';
-    }
+    const counts = countBySeverity(filteredIssues);
     return {
         ...result,
-        status,
-        summary: `${errorCount} errors, ${warningCount} warnings, ${infoCount} info`,
+        status: calculateValidationStatus(filteredIssues),
+        // Spreading `result` carried the PRE-filter `issueCounts` forward, so a
+        // `severity: ignore` config left the counts describing findings the report
+        // no longer contained. The counts are re-derived, never inherited.
+        issueCounts: counts,
+        summary: formatCountsSummary(counts),
         issues: filteredIssues,
     };
 }
@@ -459,12 +520,18 @@ async function resolveEffectiveSettings(options, scanPath, logger) {
         return undefined;
     }
 }
-async function runAuditAtPath(scanPath, options, overrides = {}) {
-    const logger = createLogger(options.debug ? { debug: true } : {});
-    const startTime = Date.now();
+/**
+ * Run the audit pipeline at `scanPath` and assemble the report document,
+ * without writing anything. The document states its coordinate system once
+ * (`root`) and every `path`/`location` beneath it is relative to that root.
+ *
+ * @internal Exported for integration testing only — not part of the public CLI API.
+ */
+export async function buildAuditReport(scanPath, options, startTime, logger) {
     const recursive = options.recursive !== false;
     logger.debug(`Auditing resources at: ${scanPath}`);
-    const rawResults = await getValidationResults(scanPath, recursive, options, logger);
+    const scanRoot = deriveScanRoot(scanPath);
+    const rawResults = await getValidationResults(scanPath, recursive, options, logger, scanRoot);
     // Load config for severity filtering (audit ignores allow; only severity matters).
     const config = loadConfig(deriveConfigRoot(scanPath));
     // Apply severity filtering: hide codes whose effective severity is 'ignore'.
@@ -477,19 +544,38 @@ async function runAuditAtPath(scanPath, options, overrides = {}) {
     const vatContextForCompat = await buildVATProjectContext(deriveConfigRoot(scanPath), logger);
     // Run compatibility analysis if --compat flag is set
     const compatMap = options.compat
-        ? await runCompatAnalysis(results, logger, effectiveSettings, vatContextForCompat)
+        ? await runCompatAnalysis(results, logger, scanRoot, effectiveSettings, vatContextForCompat)
         : undefined;
     const verbose = options.verbose ?? false;
-    const summary = calculateSummary(results, startTime, compatMap, verbose);
-    const finalSummary = overrides.tempRoot === undefined ? summary : rewritePathsInResults(summary, overrides.tempRoot);
+    return {
+        results,
+        document: calculateSummary(results, startTime, compatMap, verbose, scanRoot),
+    };
+}
+/** Strip the run root from a report whose base cannot be named as a path. */
+function withoutRoot(document) {
+    const copy = { ...document };
+    delete copy['root'];
+    return copy;
+}
+async function runAuditAtPath(scanPath, options, overrides = {}) {
+    const logger = createLogger(options.debug ? { debug: true } : {});
+    const startTime = Date.now();
+    const verbose = options.verbose ?? false;
+    const { results, document } = await buildAuditReport(scanPath, options, startTime, logger);
+    // A URL audit's run root is a random tempdir: not reproducible and useless to
+    // a reader. The provenance header states the base instead (url @ ref @ commit)
+    // and every path below is already relative to the clone, so drop `root`
+    // rather than print a path nobody can resolve.
+    const finalDocument = overrides.tempRoot === undefined ? document : rewritePathsInResults(withoutRoot(document), overrides.tempRoot);
     if (overrides.provenance) {
         process.stdout.write(renderProvenanceHeader(overrides.provenance));
     }
-    writeYamlOutput(finalSummary);
+    writeYamlOutput(finalDocument);
     if (verbose) {
-        renderVerboseEvidence(results, logger);
+        renderVerboseEvidence(results, document.root, logger);
     }
-    handleAuditResults(results, summary, logger);
+    handleAuditResults(results, document, logger, verbose);
     logger.debug(`Audit complete in ${Date.now() - startTime}ms`);
 }
 async function runUrlAudit(rawInput, options) {
@@ -509,7 +595,15 @@ export async function auditCommand(targetPath, options) {
     const startTime = Date.now();
     resetAuditCaches();
     try {
-        if (targetPath !== undefined && isGitUrl(targetPath)) {
+        // A local path always wins. `isGitUrl` accepts bare `owner/repo` GitHub
+        // shorthand, which is indistinguishable from an ordinary two-segment
+        // relative path (`plugins/arc`, `docs/guides`, `packages/cli`). Asking
+        // the URL question first meant those never got audited — the command
+        // cloned https://github.com/<that>.git instead, reaching out to the
+        // network with a name derived from the caller's own directory layout.
+        // Shorthand is a fallback for arguments that name nothing on disk.
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- targetPath is the user's own audit target; existence is the question being asked
+        if (targetPath !== undefined && !fsExistsSync(targetPath) && isGitUrl(targetPath)) {
             await runUrlAudit(targetPath, options);
             return;
         }
@@ -531,24 +625,24 @@ export async function auditCommand(targetPath, options) {
  * branch of {@link getValidationResults} focused so cognitive complexity stays
  * within the ESLint budget.
  */
-async function validateSurface(surface, options, logger) {
+async function validateSurface(surface, options, logger, locationRoot) {
     if (surface.type === RESOURCE_TYPE_AGENT_SKILL) {
-        return validateSingleSkill(surface.path, options, logger);
+        return validateSingleSkill(surface.path, options, logger, locationRoot);
     }
     if (surface.type === RESOURCE_TYPE_CLAUDE_PLUGIN) {
-        return validatePlugin(surface.path);
+        return validatePlugin(surface.path, { locationRoot });
     }
-    return validateMarketplace(surface.path);
+    return validateMarketplace(surface.path, { locationRoot });
 }
 /**
  * Validate every surface enumerated at a directory root (used when
  * `enumerateSurfaces` returns more than one — e.g., skill-claude-plugin).
  */
-async function validateMultipleSurfaces(surfaces, scanPath, options, logger) {
+async function validateMultipleSurfaces(surfaces, scanPath, options, logger, locationRoot) {
     logger.debug(`Detected ${surfaces.length.toString()} surfaces at ${scanPath}: ${surfaces.map((s) => s.type).join(', ')}`);
     const results = [];
     for (const surface of surfaces) {
-        results.push(await validateSurface(surface, options, logger));
+        results.push(await validateSurface(surface, options, logger, locationRoot));
     }
     return results;
 }
@@ -563,19 +657,19 @@ async function validateMultipleSurfaces(surfaces, scanPath, options, logger) {
  * already extracted the inventory (e.g., to surface parse errors) and the
  * extractor is not called again.
  */
-async function runInventoryDetectors(scanPath, type, prebuiltInv) {
+async function runInventoryDetectors(scanPath, type, locationRoot, prebuiltInv) {
     if (type === RESOURCE_TYPE_CLAUDE_PLUGIN) {
-        const inv = prebuiltInv?.kind === 'plugin' ? prebuiltInv : await extractClaudePluginInventory(scanPath);
+        const inv = prebuiltInv?.kind === 'plugin' ? prebuiltInv : await pluginInventoryAt(scanPath);
         return [
-            ...detectDeclaredButMissing(inv),
-            ...detectPresentButUndeclared(inv),
-            ...detectReferenceTargetMissing(inv),
-            ...(inv.vendor === 'claude-code' ? detectSkillClaudePluginNameMismatch(inv) : []),
+            ...detectDeclaredButMissing(inv, locationRoot),
+            ...detectPresentButUndeclared(inv, locationRoot),
+            ...detectReferenceTargetMissing(inv, locationRoot),
+            ...(inv.vendor === 'claude-code' ? detectSkillClaudePluginNameMismatch(inv, locationRoot) : []),
         ];
     }
     if (type === 'marketplace') {
         const inv = prebuiltInv?.kind === 'marketplace' ? prebuiltInv : await extractClaudeMarketplaceInventory(scanPath);
-        return detectMarketplacePluginSourceMissing(inv);
+        return detectMarketplacePluginSourceMissing(inv, locationRoot);
     }
     return [];
 }
@@ -590,7 +684,7 @@ async function runInventoryDetectors(scanPath, type, prebuiltInv) {
  * compared against the marketplace path itself to avoid re-auditing a
  * co-located self-source (e.g., `source: "./"`).
  */
-async function recurseIntoMarketplacePlugins(marketplaceInv, recursive, options, logger) {
+async function recurseIntoMarketplacePlugins(marketplaceInv, recursive, options, logger, locationRoot) {
     const marketplaceRoot = safePath.resolve(marketplaceInv.path);
     const seen = new Set([marketplaceRoot]);
     const results = [];
@@ -602,7 +696,8 @@ async function recurseIntoMarketplacePlugins(marketplaceInv, recursive, options,
         }
         seen.add(pluginPath);
         logger.debug(`  Recursing into marketplace path-source plugin: ${pluginPath}`);
-        const pluginResults = await getValidationResults(pluginPath, recursive, options, logger);
+        // Same run root — recursing into a co-located plugin must NOT re-anchor.
+        const pluginResults = await getValidationResults(pluginPath, recursive, options, logger, locationRoot);
         results.push(...pluginResults);
     }
     return results;
@@ -611,12 +706,12 @@ async function recurseIntoMarketplacePlugins(marketplaceInv, recursive, options,
  * Append plugin inventory findings to the matching plugin result in a
  * multi-surface result list. Mutates in place.
  */
-async function appendPluginInventoryToSurfaceResults(surfaceResults, scanPath, logger) {
-    const inventoryIssues = await runInventoryDetectors(scanPath, RESOURCE_TYPE_CLAUDE_PLUGIN);
+async function appendPluginInventoryToSurfaceResults(surfaceResults, scanPath, logger, locationRoot) {
+    const inventoryIssues = await runInventoryDetectors(scanPath, RESOURCE_TYPE_CLAUDE_PLUGIN, locationRoot);
     logger.debug(`Inventory detectors emitted ${inventoryIssues.length.toString()} issues for plugin (multi-surface) at ${scanPath}`);
     for (const r of surfaceResults) {
         if (r.type === RESOURCE_TYPE_CLAUDE_PLUGIN) {
-            r.issues.push(...inventoryIssues);
+            appendIssues(r, inventoryIssues);
             break;
         }
     }
@@ -627,35 +722,45 @@ async function appendPluginInventoryToSurfaceResults(surfaceResults, scanPath, l
  * by `validatePlugin`). Only hooks/hooks.json and .mcp.json parse errors reach
  * this helper; they are appended with error severity.
  */
-function appendInventoryParseErrors(result, inv) {
+function appendInventoryParseErrors(result, inv, locationRoot) {
     const pluginJsonSuffix = safePath.join('.claude-plugin', 'plugin.json');
+    const parseIssues = [];
     for (const err of inv.parseErrors) {
         if (err.path.endsWith(pluginJsonSuffix))
             continue;
-        result.issues.push({
+        parseIssues.push({
             severity: 'error',
             code: 'PLUGIN_INVALID_JSON',
             message: err.message,
-            location: err.path,
+            location: issueLocation(err.path, locationRoot),
         });
-        result.status = 'error';
     }
+    // Status was hand-set to 'error' here while `issueCounts` and `summary` kept
+    // describing the pre-append list. One appender derives all three.
+    appendIssues(result, parseIssues);
 }
 /**
  * @internal Exported for integration testing only — not part of the public CLI API.
+ *
+ * @param locationRoot - The invocation scan root: the ONE base every emitted
+ *   `ValidationIssue.location` in this run is expressed relative to. It is an
+ *   ANCHOR, not a validation-policy boundary — per-skill governing-config
+ *   discovery still decides packaging rules, but it must never decide how a
+ *   location reads, or a run spanning several configs emits one document in
+ *   several coordinate systems. Recursion passes it through unchanged.
  */
-export async function getValidationResults(scanPath, recursive, options, logger) {
+export async function getValidationResults(scanPath, recursive, options, logger, locationRoot) {
     const format = detectFormat(scanPath);
     // Special handling for direct SKILL.md file
     if (format === RESOURCE_TYPE_AGENT_SKILL) {
         logger.debug('Detected single Agent Skill');
-        return [await validateSingleSkill(scanPath, options, logger)];
+        return [await validateSingleSkill(scanPath, options, logger, locationRoot)];
     }
     // Special handling for VAT agent: validate its SKILL.md
     if (format === 'vat-agent') {
         const skillPath = safePath.join(scanPath, 'SKILL.md');
         logger.debug('Detected VAT agent, validating SKILL.md');
-        return [await validateSingleSkill(skillPath, options, logger, true)];
+        return [await validateSingleSkill(skillPath, options, logger, locationRoot, true)];
     }
     // Enumerate all manifest surfaces at the directory root. If multiple are
     // present (e.g., skill-claude-plugin: SKILL.md + .claude-plugin/plugin.json),
@@ -664,7 +769,7 @@ export async function getValidationResults(scanPath, recursive, options, logger)
     // swallowed by the plugin surface.
     const surfaces = await enumerateSurfaces(scanPath);
     if (surfaces.length > 1) {
-        const surfaceResults = await validateMultipleSurfaces(surfaces, scanPath, options, logger);
+        const surfaceResults = await validateMultipleSurfaces(surfaces, scanPath, options, logger, locationRoot);
         if (surfaces.some((s) => s.type === RESOURCE_TYPE_CLAUDE_PLUGIN)) {
             // Build exclusion set from skill paths already validated as surfaces, so that
             // validatePluginSkillsViaInventory does not double-count a root SKILL.md that
@@ -672,8 +777,8 @@ export async function getValidationResults(scanPath, recursive, options, logger)
             const alreadyValidated = new Set(surfaces
                 .filter((s) => s.type === RESOURCE_TYPE_AGENT_SKILL)
                 .map((s) => safePath.resolve(s.path)));
-            surfaceResults.push(...(await validatePluginSkillsViaInventory(scanPath, options, logger, alreadyValidated)));
-            await appendPluginInventoryToSurfaceResults(surfaceResults, scanPath, logger);
+            surfaceResults.push(...(await validatePluginSkillsViaInventory(scanPath, options, logger, locationRoot, alreadyValidated)));
+            await appendPluginInventoryToSurfaceResults(surfaceResults, scanPath, logger, locationRoot);
         }
         return surfaceResults;
     }
@@ -681,16 +786,16 @@ export async function getValidationResults(scanPath, recursive, options, logger)
     const resourceFormat = await detectResourceFormat(scanPath);
     if (resourceFormat.type !== 'unknown') {
         logger.debug(`Detected ${resourceFormat.type} at: ${scanPath}`);
-        const result = await validate(scanPath, { validatePlugin });
+        const result = await validate(scanPath, { validatePlugin, locationRoot });
         if (resourceFormat.type === RESOURCE_TYPE_CLAUDE_PLUGIN) {
             // Build the inventory once; reuse it for both parse-error surfacing and detectors.
-            const inv = await extractClaudePluginInventory(scanPath);
-            appendInventoryParseErrors(result, inv);
-            const pluginInventoryIssues = await runInventoryDetectors(scanPath, RESOURCE_TYPE_CLAUDE_PLUGIN, inv);
-            result.issues.push(...pluginInventoryIssues);
+            const inv = await pluginInventoryAt(scanPath);
+            appendInventoryParseErrors(result, inv, locationRoot);
+            const pluginInventoryIssues = await runInventoryDetectors(scanPath, RESOURCE_TYPE_CLAUDE_PLUGIN, locationRoot, inv);
+            appendIssues(result, pluginInventoryIssues);
             logger.debug(`Inventory detectors emitted ${pluginInventoryIssues.length.toString()} issues for plugin at ${scanPath}`);
             // Also validate every skill the plugin ships via the inventory walker.
-            const skillResults = await validatePluginSkillsViaInventory(scanPath, options, logger);
+            const skillResults = await validatePluginSkillsViaInventory(scanPath, options, logger, locationRoot);
             return [result, ...skillResults];
         }
         if (resourceFormat.type === 'marketplace') {
@@ -699,10 +804,10 @@ export async function getValidationResults(scanPath, recursive, options, logger)
             // is populated only for path sources that exist on disk (git/npm/unknown
             // sources are declarations only and stay out of scope).
             const marketplaceInv = await extractClaudeMarketplaceInventory(scanPath);
-            const marketplaceInventoryIssues = await runInventoryDetectors(scanPath, 'marketplace', marketplaceInv);
-            result.issues.push(...marketplaceInventoryIssues);
+            const marketplaceInventoryIssues = await runInventoryDetectors(scanPath, 'marketplace', locationRoot, marketplaceInv);
+            appendIssues(result, marketplaceInventoryIssues);
             logger.debug(`Inventory detectors emitted ${marketplaceInventoryIssues.length.toString()} issues for marketplace at ${scanPath}`);
-            const pluginResults = await recurseIntoMarketplacePlugins(marketplaceInv, recursive, options, logger);
+            const pluginResults = await recurseIntoMarketplacePlugins(marketplaceInv, recursive, options, logger, locationRoot);
             return [result, ...pluginResults];
         }
         return [result];
@@ -713,14 +818,11 @@ export async function getValidationResults(scanPath, recursive, options, logger)
         const stat = await fsp.stat(scanPath);
         if (stat.isDirectory()) {
             logger.debug('Scanning directory for resources');
-            // Merge resources.exclude from config with --exclude CLI flag patterns.
-            // Both use the same picomatch semantics. Do NOT mutate options.
-            const config = loadConfig(deriveConfigRoot(scanPath));
-            const configExcludes = config?.resources?.exclude ?? [];
-            const mergedOptions = configExcludes.length > 0
-                ? { ...options, exclude: [...(options.exclude ?? []), ...configExcludes] }
-                : options;
-            return scanDirectory(scanPath, recursive, mergedOptions, logger);
+            // The project's `resources.exclude` is applied by the scan context,
+            // on the project-root basis its globs were written against — NOT
+            // merged into `options.exclude`, whose patterns are relative to the
+            // directory the operator named. See resolveProjectExcludes.
+            return scanDirectory(scanPath, recursive, options, logger, await resolveScanContext(scanPath, locationRoot, logger));
         }
     }
     catch {
@@ -728,7 +830,7 @@ export async function getValidationResults(scanPath, recursive, options, logger)
     }
     // Unknown resource type - use unified validator which will return appropriate error
     logger.debug(`Unknown resource type at: ${scanPath}`);
-    const result = await validate(scanPath);
+    const result = await validate(scanPath, { locationRoot });
     return [result];
 }
 /**
@@ -740,8 +842,8 @@ export async function getValidationResults(scanPath, recursive, options, logger)
  *   multi-surface branch to avoid double-counting a root SKILL.md that
  *   `validateMultipleSurfaces` already validated as an `agent-skill` surface.
  */
-async function validatePluginSkillsViaInventory(scanPath, options, logger, excludeSkillPaths = new Set()) {
-    const inv = await extractClaudePluginInventory(scanPath);
+async function validatePluginSkillsViaInventory(scanPath, options, logger, locationRoot, excludeSkillPaths = new Set()) {
+    const inv = await pluginInventoryAt(scanPath);
     const results = [];
     for (const skill of inv.discovered.skills) {
         const resolvedPath = safePath.resolve(skill.files.skillMd);
@@ -750,7 +852,7 @@ async function validatePluginSkillsViaInventory(scanPath, options, logger, exclu
             continue;
         }
         logger.debug(`  Validating plugin-bundled skill (inventory): ${skill.files.skillMd}`);
-        results.push(await validateSingleSkill(skill.files.skillMd, options, logger));
+        results.push(await validateSingleSkill(skill.files.skillMd, options, logger, locationRoot));
     }
     return results;
 }
@@ -795,6 +897,11 @@ function resolveConfigTargetsForPlugin(pluginDir, vatContext) {
  * Non-plugin results are skipped silently.
  * When effectiveSettings is provided, also runs settings conflict detection.
  *
+ * `locationRoot` is the invocation scan root: the ONE base every emitted
+ * evidence `location.file` is relative to. One audit run spans many plugin
+ * directories, so anchoring evidence at each plugin would mix coordinate
+ * systems in a single document.
+ *
  * When vatContext is provided, config-layer `targets` declarations are
  * threaded through to the analyzer so `vat audit .` inside a VAT project
  * matches `vat skills validate` verdicts. See
@@ -802,7 +909,7 @@ function resolveConfigTargetsForPlugin(pluginDir, vatContext) {
  *
  * @internal Exported for integration testing only — not part of the public CLI API.
  */
-export async function runCompatAnalysis(results, logger, effectiveSettings, vatContext = null) {
+export async function runCompatAnalysis(results, logger, locationRoot, effectiveSettings, vatContext = null) {
     const compatMap = new Map();
     for (const result of results) {
         if (result.type !== RESOURCE_TYPE_CLAUDE_PLUGIN)
@@ -813,7 +920,7 @@ export async function runCompatAnalysis(results, logger, effectiveSettings, vatC
             const analyzeOptions = configTargets === undefined
                 ? undefined
                 : { configTargets };
-            const compat = await analyzeCompatibility(result.path, analyzeOptions);
+            const compat = await analyzeCompatibility(result.path, locationRoot, analyzeOptions);
             // Settings conflict detection (when --settings flag is used)
             if (effectiveSettings === undefined) {
                 compatMap.set(result.path, compat);
@@ -893,12 +1000,23 @@ function applyVerboseFilter(results, verbose) {
         return stripped;
     });
 }
-function calculateSummary(results, startTime, compatMap, verbose) {
-    const base = buildBaseSummary(results, startTime);
-    const withCompat = applyCompatMap(results, compatMap);
+/**
+ * Nested carriers inside a file entry that publish their own `path`.
+ *
+ * `linkedFiles[].path` sat absolute in every document while every sibling
+ * `path` and `location` beside it was root-relative — 532 of them in a single
+ * `vat audit --user` run. Naming the carrier here is what re-bases it; a new
+ * carrier that is not named keeps shipping absolute paths.
+ */
+const NESTED_PATH_CARRIERS = ['linkedFiles'];
+function calculateSummary(results, startTime, compatMap, verbose, root) {
+    const { entries, ...base } = buildBaseSummary(results, startTime);
+    const withCompat = applyCompatMap(entries, compatMap);
     return {
+        // Stated once, first, and the only absolute path in the document.
+        root,
         ...base,
-        files: applyVerboseFilter(withCompat, verbose),
+        files: relativizePathEntries(applyVerboseFilter(withCompat, verbose), root, NESTED_PATH_CARRIERS),
     };
 }
 /**
@@ -948,7 +1066,7 @@ function renderIssueEvidence(issue, evidenceSources, logger) {
  * result itself (per-file SKILL evidence) and from any attached
  * `compatibility.evidence` (plugin-level scanner output).
  */
-function renderVerboseEvidence(results, logger) {
+function renderVerboseEvidence(results, root, logger) {
     for (const result of results) {
         const capabilityIssues = (result.issues ?? []).filter((i) => i.code.startsWith('CAPABILITY_'));
         if (capabilityIssues.length === 0)
@@ -959,14 +1077,14 @@ function renderVerboseEvidence(results, logger) {
         ];
         if (evidenceSources.length === 0)
             continue;
-        logger.info(`\n${result.path} — supporting evidence:`);
+        logger.info(`\n${issueLocation(result.path, root)} — supporting evidence:`);
         for (const issue of capabilityIssues) {
             renderIssueEvidence(issue, evidenceSources, logger);
         }
     }
 }
-function handleAuditResults(results, summary, logger) {
-    const { errors: errorCount, warnings: warningCount, success: successCount } = summary.summary;
+function handleAuditResults(results, summary, logger, verbose) {
+    const { filesWithErrors: errorCount, filesWithWarnings: warningCount, filesPassed: successCount, } = summary.summary;
     // Report settings conflicts (advisory, non-blocking)
     const totalSettingsConflicts = (summary.files ?? []).reduce((sum, f) => {
         return sum + (f.compatibility?.settingsConflicts?.length ?? 0);
@@ -977,13 +1095,20 @@ function handleAuditResults(results, summary, logger) {
     // Audit is advisory only — always exit 0 for validation results.
     // Use vat skills validate for gated validation (exit 1 on errors).
     if (errorCount > 0) {
-        logErrors(results, errorCount, logger);
+        logger.error(`Audit failed: ${errorCount} file(s) with errors`);
+        logFindingsForStatus(results, 'error', summary.root, logger.error.bind(logger), verbose);
     }
     else if (warningCount > 0) {
-        logWarnings(results, warningCount, logger);
+        logger.info(`Audit passed with warnings: ${warningCount} file(s)`);
+        logFindingsForStatus(results, 'warning', summary.root, logger.info.bind(logger), verbose);
     }
     else {
-        logger.info(`Audit successful: ${successCount} file(s) passed`);
+        // `success` means "nothing actionable", NOT "nothing to see" — name the
+        // informational findings or the YAML and the stderr line disagree.
+        const withFindings = countResultsWithFindings(results);
+        logger.info(withFindings > 0
+            ? `Audit successful: ${successCount} file(s) passed (${withFindings} with informational findings)`
+            : `Audit successful: ${successCount} file(s) passed`);
     }
     renderAuditFooter(results, logger);
     process.exit(0);
@@ -1007,33 +1132,62 @@ function renderAuditFooter(results, logger) {
     }
     renderSkillQualityFooter(logger, hasSkillFindings, emittedCodes);
 }
-function logErrors(results, errorCount, logger) {
-    logger.error(`Audit failed: ${errorCount} file(s) with errors`);
-    const errorResults = results.filter((r) => r.status === 'error');
-    for (const result of errorResults) {
-        logger.error(`\n${result.path}:`);
-        const errorIssues = result.issues.filter((i) => i.severity === 'error');
-        logIssues(errorIssues, logger.error.bind(logger));
+/**
+ * The stderr findings report for a set of audit results — the HUMAN channel.
+ *
+ * Deliberately NOT the YAML document. `vat audit` publishes a machine-readable
+ * report on stdout that CI and tooling parse, and that document carries every
+ * finding at every verbosity; this stream is read by a person, and on a 90-skill
+ * corpus it printed 26,480 lines, 3,480 of them occurrences of a single
+ * high-cardinality warning code. The two channels answer different questions, so
+ * only this one collapses.
+ *
+ * Which findings render in full is not decided here — it is
+ * {@link issuesToRenderAtVerbosity}, shared with the other findings-reporting
+ * verbs so `vat audit`, `vat skills validate` and `vat skills build` cannot drift
+ * onto three answers again. Errors always render; warnings and info collapse
+ * unless `verbose`; allow-listed findings never render.
+ *
+ * The severity breakdown on each file's heading is load-bearing, not decoration.
+ * For a warning-only file at default verbosity that heading is the ENTIRE report
+ * for that file, so dropping the counts would turn the collapse into silence —
+ * the failure direction `issue-rendering.ts` exists to prevent. The trailing
+ * line names the collapsed total and both ways to see it, for the same reason.
+ *
+ * Pure: takes results, returns lines. It reads `issues` and never rewrites it,
+ * because `runAuditAtPath` builds the YAML document from the very same array.
+ *
+ * @internal Exported for unit testing only — not part of the public CLI API.
+ */
+export function formatAuditFindingsLines(results, root, verbose) {
+    const lines = [];
+    let collapsed = 0;
+    for (const result of results) {
+        const rendered = issuesToRenderAtVerbosity(result.issues, verbose);
+        // What --verbose WOULD show, minus what this verbosity shows. Derived from
+        // the policy rather than re-stating it, so the count cannot contradict it.
+        collapsed += issuesToRenderAtVerbosity(result.issues, true).length - rendered.length;
+        lines.push(`\n${issueLocation(result.path, root)} — ${formatSeverityBreakdown(countBySeverity(result.issues))}:`);
+        for (const issue of rendered) {
+            lines.push(...formatIssueLines(issue, '  '));
+        }
     }
-}
-function logWarnings(results, warningCount, logger) {
-    logger.info(`Audit passed with warnings: ${warningCount} file(s)`);
-    const warningResults = results.filter((r) => r.status === 'warning');
-    for (const result of warningResults) {
-        logger.info(`\n${result.path}:`);
-        const warningIssues = result.issues.filter((i) => i.severity === 'warning');
-        logIssues(warningIssues, logger.info.bind(logger));
+    if (collapsed > 0) {
+        lines.push(`\n${collapsed} warning/info finding(s) not shown — re-run with --verbose, ` +
+            'or read the YAML report on stdout, which always lists every finding.');
     }
+    return lines;
 }
-function logIssues(issues, logFn) {
-    for (const issue of issues) {
-        logFn(`  [${issue.code}] ${issue.message}`);
-        if (issue.location) {
-            logFn(`    at: ${issue.location}`);
-        }
-        if (issue.fix) {
-            logFn(`    fix: ${issue.fix}`);
-        }
+/**
+ * Write one status class's findings to stderr beneath the run banner.
+ *
+ * The banner counts FILES and the blocks below count FINDINGS; both are needed,
+ * and `logFn` picks the channel the calling branch already established.
+ */
+function logFindingsForStatus(results, status, root, logFn, verbose) {
+    const selected = results.filter((r) => r.status === status);
+    for (const line of formatAuditFindingsLines(selected, root, verbose)) {
+        logFn(line);
     }
 }
 /**
@@ -1051,10 +1205,11 @@ function isExcludedPath(isMatch, relativePath, isDirectory) {
  * Handle file entry during directory scan
  */
 async function handleFileEntry(entry, fullPath, options, logger, scanCtx) {
+    const { locationRoot } = scanCtx;
     // Check for registry files
     if (entry.name === 'installed_plugins.json' || entry.name === 'known_marketplaces.json') {
         logger.debug(`Validating registry: ${fullPath}`);
-        return validate(fullPath);
+        return validate(fullPath, { locationRoot });
     }
     // Check for SKILL.md
     if (entry.name === 'SKILL.md') {
@@ -1068,12 +1223,17 @@ async function handleFileEntry(entry, fullPath, options, logger, scanCtx) {
             logger.debug(`  Using config-aware validation for: ${fullPath}`);
             // Thread the per-scan tracker into packaging validation so gitignore
             // checks in the link-graph walk stay O(1).
-            const sharedCtx = scanCtx.gitTracker === null ? undefined : { gitTracker: scanCtx.gitTracker };
+            // `projectSkills`: same project-wide test-input rule as the lane above,
+            // resolved through the same per-config-root memo.
+            const projectSkills = await resolveProjectDeclaredEvalSuites(fullPath);
+            const sharedCtx = scanCtx.gitTracker === null
+                ? { locationRoot, projectSkills }
+                : { gitTracker: scanCtx.gitTracker, locationRoot, projectSkills };
             const packagingResult = await validateSkillForPackaging(fullPath, skillConfig, 'source', sharedCtx);
-            return packagingResultToValidationResult(fullPath, packagingResult, skillConfig.targets);
+            return packagingResultToValidationResult(fullPath, packagingResult, skillConfig.targets, locationRoot);
         }
         // Wild mode: basic validation
-        const validateOptions = { skillPath: fullPath };
+        const validateOptions = { skillPath: fullPath, locationRoot };
         if (options.warnUnreferencedFiles) {
             validateOptions.checkUnreferencedFiles = true;
         }
@@ -1086,26 +1246,120 @@ async function handleFileEntry(entry, fullPath, options, logger, scanCtx) {
  */
 async function handleDirectoryEntry(fullPath, recursive, options, logger, baseDir, scanCtx, nestedConfigLog) {
     const fs = await import('node:fs/promises');
+    const { locationRoot } = scanCtx;
     const results = [];
     // Check if directory contains a plugin or marketplace
     const claudePluginDir = safePath.join(fullPath, '.claude-plugin');
     const hasClaudePlugin = await fs.access(claudePluginDir).then(() => true).catch(() => false);
     if (hasClaudePlugin) {
         logger.debug(`Validating resource directory: ${fullPath}`);
-        const result = await validate(fullPath, { validatePlugin });
-        const inv = await extractClaudePluginInventory(fullPath);
-        appendInventoryParseErrors(result, inv);
+        const result = await validate(fullPath, { validatePlugin, locationRoot });
+        const inv = await pluginInventoryAt(fullPath);
+        appendInventoryParseErrors(result, inv, locationRoot);
         results.push(result);
     }
     // Recurse into subdirectories (both plugin/marketplace dirs and regular dirs)
     if (recursive) {
-        const subResults = await scanDirectory(fullPath, recursive, options, logger, baseDir, scanCtx, nestedConfigLog);
+        const subResults = await scanDirectory(fullPath, recursive, options, logger, scanCtx, baseDir, nestedConfigLog);
         results.push(...subResults);
     }
     return results;
 }
+/**
+ * Compile the governing project's `resources.exclude` for a scan.
+ *
+ * The config is found by walking UP from the scan directory ({@link findProjectRoot}),
+ * not by looking in it. Looking only in the scan directory is how a path argument
+ * silently voided every exclude the project had declared: `vat audit
+ * packages/x/resources/skills/` found no config there, so a package that excludes
+ * its deliberately-broken eval fixtures had them audited as production skills the
+ * moment anyone named a subdirectory. Commit 8a466b0c fixed the same defect for
+ * `vat resources validate|scan` and `vat rag index`; this is the lane it missed.
+ * The rule is the same one that commit established: a path argument says WHICH
+ * tree to audit, and `exclude` applies either way.
+ *
+ * With one deliberate exception, mirroring the gitignore rule in
+ * {@link resolveScanContext}: when the operator points the scan AT an excluded
+ * tree, their explicit intent wins and the excludes are dropped for that run.
+ * Otherwise naming an excluded directory would report `filesScanned: 0,
+ * status: success` — a green run that scanned nothing.
+ */
+function resolveProjectExcludes(scanDir, logger) {
+    const projectRoot = findProjectRoot(scanDir);
+    if (projectRoot === null)
+        return null;
+    let patterns;
+    try {
+        patterns = loadConfig(projectRoot)?.resources?.exclude ?? [];
+    }
+    catch (err) {
+        // Audit is a bulk linter over trees it does not own; a broken governing
+        // config must not abort the scan. Say so rather than dropping it silently.
+        logger.debug(`Ignoring unreadable config at ${projectRoot}: ${String(err)}`);
+        return null;
+    }
+    if (patterns.length === 0)
+        return null;
+    // dot:true so excludes like `**/.cache/*` match through dotfile dirs;
+    // without it the exclude silently never fires.
+    const isMatch = picomatch([...patterns], { dot: true });
+    const scanRelToProject = safePath.relative(projectRoot, safePath.resolve(scanDir)).replaceAll('\\', '/');
+    if (scanRelToProject !== '' && isExcludedPath(isMatch, scanRelToProject, true)) {
+        logger.debug(`Scan root ${scanRelToProject} is excluded by the config at ${projectRoot}; ` +
+            'auditing it anyway because it was named explicitly');
+        return null;
+    }
+    return { isMatch, base: projectRoot, label: 'excluded by config' };
+}
 /** Cache of (gitRoot → initialized GitTracker) to avoid re-spawning ls-files. */
 const gitTrackerCache = new Map();
+/**
+ * Cache of (projectRoot → registry for the *inventory* link walk).
+ *
+ * Deliberately separate from the validator's own registry memo (which now lives
+ * beside `crawlAndResolveRegistry`, so this lane no longer keeps a second copy of
+ * that cache): the validator's registry crawls markdown AND HTML, while the
+ * inventory walk has always been markdown-only. Sharing one registry between them
+ * would quietly widen the link graph `files.linked` is computed from, which is a
+ * behaviour change and not this fix's business. Two crawls per project root is
+ * still two, not two per skill.
+ */
+const inventoryRegistryCache = new Map();
+/** Build (once per run, per root) the registry the plugin inventory link walk needs. */
+async function getOrCreateInventoryRegistry(projectRoot) {
+    const cached = inventoryRegistryCache.get(projectRoot);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const pending = crawlSkillLinkRegistry(projectRoot);
+    inventoryRegistryCache.set(projectRoot, pending);
+    return pending;
+}
+/**
+ * `extractClaudePluginInventory` for a plugin directory, handing it the shared
+ * inventory registry so each skill it walks does not re-parse the corpus.
+ *
+ * A PROVIDER, not an awaited registry, and only when there is a project root — the same
+ * two rules `vat inventory`'s `linkRegistryProviderFor` follows, for the same two reasons:
+ *
+ * 1. **Unresolved.** `extractClaudePluginInventory` promises "never throws — all failures
+ *    surface via parseErrors[]", and that promise holds only while the crawl runs inside
+ *    `walkLinkedFiles`'s try/catch. Awaiting it here moved the crawl outside that catch,
+ *    so one unreadable markdown file anywhere under the root aborted the WHOLE audit with
+ *    `status: error` and exit code 2 instead of degrading three link walks. The extractor
+ *    memoizes the provider and caches even a rejection, so the failed crawl is still
+ *    attempted once, not once per skill.
+ * 2. **Only a project root.** Reuse is gated on exact `registry.baseDir === projectRoot`
+ *    equality against the root `walkLinkedFiles` derives per skill
+ *    (`findProjectRoot(dirname(skillMd)) ?? dirname(skillMd)`). With no project root that
+ *    per-skill fallback is each skill's OWN directory, so a registry rooted at the plugin
+ *    matches nothing: it would be crawled, compared, discarded, and re-crawled per skill.
+ *    No root, no provider.
+ */
+async function pluginInventoryAt(dir) {
+    const projectRoot = findProjectRoot(dir);
+    return extractClaudePluginInventory(dir, projectRoot === null ? undefined : () => getOrCreateInventoryRegistry(projectRoot));
+}
 /**
  * Reset all module-level audit caches. Must be called at the start of every
  * independent audit invocation so in-process callers (CLI entrypoint AND
@@ -1114,6 +1368,8 @@ const gitTrackerCache = new Map();
  */
 export function resetAuditCaches() {
     gitTrackerCache.clear();
+    resetPackagingRegistryCache();
+    inventoryRegistryCache.clear();
     resetProjectRootCaches();
     resetLoadedConfigCache();
     resetSkillDiscoveryCache();
@@ -1138,18 +1394,19 @@ async function getOrCreateGitTracker(gitRoot) {
  * `dist/`), returns `{ gitRoot: null, gitTracker: null }` to disable gitignore
  * filtering — the user's explicit intent takes precedence over .gitignore.
  */
-async function resolveScanContext(dirPath) {
+async function resolveScanContext(dirPath, locationRoot, logger) {
+    const projectExcludes = resolveProjectExcludes(dirPath, logger);
     const detectedRoot = gitFindRoot(dirPath);
     if (detectedRoot === null) {
-        return { gitRoot: null, gitTracker: null };
+        return { gitRoot: null, gitTracker: null, locationRoot, projectExcludes };
     }
     const tracker = await getOrCreateGitTracker(detectedRoot);
     // If the scan root itself is gitignored (e.g. user targeted `dist/`), disable
     // gitignore filtering so the user's explicit intent wins.
     if (tracker.isIgnoredByActiveSet(dirPath)) {
-        return { gitRoot: null, gitTracker: null };
+        return { gitRoot: null, gitTracker: null, locationRoot, projectExcludes };
     }
-    return { gitRoot: detectedRoot, gitTracker: tracker };
+    return { gitRoot: detectedRoot, gitTracker: tracker, locationRoot, projectExcludes };
 }
 /**
  * Build the gitignore exclusion map for a set of entry paths.
@@ -1170,7 +1427,7 @@ function buildGitIgnoreMap(entryPaths, gitTracker, includeArtifacts) {
  * Check whether a directory entry should be skipped during scanning.
  * Returns a reason string for debug logging, or null if the entry should be kept.
  */
-function getSkipReason(entry, fullPath, resolvedBaseDir, gitIgnoredMap, isMatch) {
+function getSkipReason(entry, fullPath, gitIgnoredMap, excludeMatchers) {
     // Always skip .git directory (not reported by git check-ignore)
     if (entry.isDirectory() && entry.name === '.git') {
         return '.git';
@@ -1179,23 +1436,23 @@ function getSkipReason(entry, fullPath, resolvedBaseDir, gitIgnoredMap, isMatch)
     if (gitIgnoredMap !== null && gitIgnoredMap.get(fullPath) === true) {
         return `gitignored: ${entry.name}`;
     }
-    // Check user-supplied --exclude patterns
-    if (isMatch !== null) {
-        const relativePath = safePath.relative(resolvedBaseDir, fullPath).replaceAll('\\', '/');
-        if (isExcludedPath(isMatch, relativePath, entry.isDirectory())) {
-            return `excluded: ${relativePath}`;
+    // Each matcher answers against ITS OWN base — see {@link ExcludeMatcher}.
+    for (const matcher of excludeMatchers) {
+        const relativePath = safePath.relative(matcher.base, fullPath).replaceAll('\\', '/');
+        if (isExcludedPath(matcher.isMatch, relativePath, entry.isDirectory())) {
+            return `${matcher.label}: ${relativePath}`;
         }
     }
     return null;
 }
-async function scanDirectory(dirPath, recursive, options, logger, baseDir, scanCtx, nestedConfigLog) {
+async function scanDirectory(dirPath, recursive, options, logger, scanCtx, baseDir, nestedConfigLog) {
     const fs = await import('node:fs/promises');
     const results = [];
     const userExcludes = options.exclude ?? [];
     const resolvedBaseDir = baseDir ?? dirPath;
-    // First call in this scan: build the git context (root + tracker) once; every
-    // subsequent recursion reuses them.
-    const resolvedScanCtx = scanCtx ?? (await resolveScanContext(dirPath));
+    // The git context (root + tracker) and the run's anchor base are built once by
+    // the caller; every recursion reuses them unchanged.
+    const resolvedScanCtx = scanCtx;
     const resolvedNestedLog = nestedConfigLog ?? new Set();
     // Top-down pre-warm of findProjectRoot's walk-up cache (spec §8). The first
     // call here drives a single ancestor walk; every subsequent recursion is a
@@ -1216,14 +1473,26 @@ async function scanDirectory(dirPath, recursive, options, logger, baseDir, scanC
     // Compile picomatch for user-supplied --exclude patterns.
     // dot:true so excludes like `**/private/*` match through dotfile dirs
     // (`.claude/.../private/x`); without it the exclude silently never fires.
-    const isMatch = userExcludes.length > 0 ? picomatch(userExcludes, { dot: true }) : null;
+    // These are relative to the scan base; the config's excludes carry their own
+    // (project-root) base on the matcher — see {@link ExcludeMatcher}.
+    const excludeMatchers = [];
+    if (userExcludes.length > 0) {
+        excludeMatchers.push({
+            isMatch: picomatch(userExcludes, { dot: true }),
+            base: resolvedBaseDir,
+            label: 'excluded',
+        });
+    }
+    if (resolvedScanCtx.projectExcludes !== null) {
+        excludeMatchers.push(resolvedScanCtx.projectExcludes);
+    }
     const entries = await fs.readdir(dirPath, { withFileTypes: true });
     // Build full paths and batch-check gitignore status
     const entryPaths = entries.map(e => safePath.join(dirPath, e.name));
     const gitIgnoredMap = buildGitIgnoreMap(entryPaths, resolvedScanCtx.gitTracker, options.includeArtifacts ?? false);
     for (const entry of entries) {
         const fullPath = safePath.join(dirPath, entry.name);
-        const skipReason = getSkipReason(entry, fullPath, resolvedBaseDir, gitIgnoredMap, isMatch);
+        const skipReason = getSkipReason(entry, fullPath, gitIgnoredMap, excludeMatchers);
         if (skipReason !== null) {
             logger.debug(`Excluding path: ${skipReason}`);
             continue;
@@ -1256,76 +1525,76 @@ function calculateOverallStatus(results) {
     return 'success';
 }
 /**
- * Count all skills in hierarchical output
+ * How many results carry at least one finding.
+ *
+ * Counted from the results, not from the rendered hierarchy. The hierarchy is a
+ * PROJECTION of the results — in `--verbose` it contains every scanned skill,
+ * findings or not, so counting its entries reported "N with issues" equal to the
+ * number scanned. The predicate itself is the only thing that answers this.
  */
-function countAllSkills(hierarchical) {
-    let total = 0;
-    // Count marketplace skills
-    for (const marketplace of hierarchical.marketplaces) {
-        for (const plugin of marketplace.plugins) {
-            total += plugin.skills.length;
-        }
-    }
-    // Count cached plugin skills
-    for (const plugin of hierarchical.cachedPlugins) {
-        total += plugin.skills.length;
-    }
-    // Count standalone plugin skills
-    for (const plugin of hierarchical.standalonePlugins) {
-        total += plugin.skills.length;
-    }
-    // Count standalone skills
-    total += hierarchical.standaloneSkills.length;
-    return total;
+function countResultsWithFindings(results) {
+    return results.filter((r) => r.issues.length > 0).length;
 }
-/**
- * Calculate issue counts from validation results
- */
-function calculateIssueCounts(results) {
-    const successCount = results.filter((r) => r.status === 'success').length;
-    const warningCount = results.filter((r) => r.status === 'warning').length;
-    const errorCount = results.filter((r) => r.status === 'error').length;
-    const totalErrors = results.reduce((sum, r) => sum + r.issues.filter(i => i.severity === 'error').length, 0);
-    const totalWarnings = results.reduce((sum, r) => sum + r.issues.filter(i => i.severity === 'warning').length, 0);
-    const totalInfo = results.reduce((sum, r) => sum + r.issues.filter(i => i.severity === 'info').length, 0);
+/** Count files by their own status. */
+function countFilesByStatus(results) {
     return {
-        successCount,
-        warningCount,
-        errorCount,
-        totalErrors,
-        totalWarnings,
-        totalInfo,
+        filesScanned: results.length,
+        filesPassed: results.filter((r) => r.status === 'success').length,
+        filesWithWarnings: results.filter((r) => r.status === 'warning').length,
+        filesWithErrors: results.filter((r) => r.status === 'error').length,
     };
 }
 /**
- * Build base summary structure (used by both flat and hierarchical)
+ * Build base summary structure (used by both flat and hierarchical), together
+ * with the entries the document will publish.
+ *
+ * `issueCounts` is named exactly as it is on every individual file entry, and
+ * means the same thing at both levels: findings, by severity. `summary` only ever
+ * counts files.
+ *
+ * The header total and every per-file total come from ONE traversal of the
+ * final issue set, and the entries carrying those per-file totals are returned
+ * from the same pass. Before that, the header was derived from the issue
+ * records while each file's `issueCounts` was whatever its producer had
+ * published — and a producer that appends findings after publishing (or never
+ * sets the counts at all: `validatePlugin` writes `status` and `summary` but
+ * not `issueCounts`) left the two disagreeing inside one document. A real
+ * `vat audit --user` run said 55/422/504 in the header over per-file counts
+ * summing to 55/360/405, with 91 of 614 entries declaring `{0,0,0}` above the
+ * findings they listed. Re-deriving here means the header and the sum are the
+ * same arithmetic on the same array, so they cannot drift again no matter what
+ * a producer forgets.
+ *
+ * `linkedFiles[].issues` are deliberately NOT added: every linked finding is
+ * also present in its owner's `issues`, so the nested list is a VIEW of records
+ * already counted, not extra records. `audit-report-coherence.integration.test.ts`
+ * pins that subset relation, because counting once is only correct while it holds.
  */
 function buildBaseSummary(results, startTime) {
-    const counts = calculateIssueCounts(results);
-    const status = calculateOverallStatus(results);
+    const issueCounts = { errors: 0, warnings: 0, info: 0 };
+    const entries = results.map((result) => {
+        const counts = countBySeverity(result.issues);
+        issueCounts.errors += counts.errors;
+        issueCounts.warnings += counts.warnings;
+        issueCounts.info += counts.info;
+        return { ...result, issueCounts: counts };
+    });
     return {
-        status,
-        summary: {
-            filesScanned: results.length,
-            success: counts.successCount,
-            warnings: counts.warningCount,
-            errors: counts.errorCount,
-        },
-        issues: {
-            errors: counts.totalErrors,
-            warnings: counts.totalWarnings,
-            info: counts.totalInfo,
-        },
+        entries,
+        status: calculateOverallStatus(entries),
+        summary: countFilesByStatus(entries),
+        issueCounts,
         duration: `${Date.now() - startTime}ms`,
     };
 }
 /**
  * Calculate summary for hierarchical output
  */
-function calculateHierarchicalSummary(results, hierarchical, startTime, compatMap, verbose) {
-    const base = buildBaseSummary(results, startTime);
-    const withCompat = applyCompatMap(results, compatMap);
+function calculateHierarchicalSummary(results, hierarchical, startTime, compatMap, verbose, root) {
+    const { entries, ...base } = buildBaseSummary(results, startTime);
+    const withCompat = applyCompatMap(entries, compatMap);
     return {
+        root,
         ...base,
         summary: {
             ...base.summary,
@@ -1334,16 +1603,16 @@ function calculateHierarchicalSummary(results, hierarchical, startTime, compatMa
             standalonePlugins: hierarchical.standalonePlugins.length,
             standaloneSkills: hierarchical.standaloneSkills.length,
         },
-        files: applyVerboseFilter(withCompat, verbose),
+        files: relativizePathEntries(applyVerboseFilter(withCompat, verbose), root, NESTED_PATH_CARRIERS),
         hierarchical,
     };
 }
 /**
  * Log hierarchical summary to stderr
  */
-function logHierarchicalSummary(results, hierarchical, logger) {
+function logHierarchicalSummary(results, logger) {
     const status = calculateOverallStatus(results);
-    const skillsWithIssues = countAllSkills(hierarchical);
+    const skillsWithIssues = countResultsWithFindings(results);
     const totalSkills = results.length;
     // Audit is advisory only — always exit 0 for validation results.
     // Use vat skills validate for gated validation (exit 1 on errors).
@@ -1355,6 +1624,11 @@ function logHierarchicalSummary(results, hierarchical, logger) {
         const warningCount = results.filter((r) => r.status === 'warning').length;
         logger.info(`Audit passed with warnings: ${warningCount} skill(s) (${totalSkills} scanned, ${skillsWithIssues} with issues)`);
     }
+    else if (skillsWithIssues > 0) {
+        // `success` means "nothing actionable", NOT "nothing to see". Saying only
+        // "N passed" over a pile of info findings is how they stayed invisible.
+        logger.info(`Audit successful: ${totalSkills} skill(s) passed (${skillsWithIssues} with informational findings)`);
+    }
     else {
         logger.info(`Audit successful: ${totalSkills} skill(s) passed`);
     }