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

package/dist/commands/audit.js

@@ -4,15 +4,17 @@
  */
 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 { handleCommandError } from '../utils/command-error.js';
 import { ConfigLoadError, loadConfig, resetLoadedConfigCache, } from '../utils/config-loader.js';
+import { formatIssueAnchor } from '../utils/issue-anchor.js';
 import { createLogger } from '../utils/logger.js';
 import { writeYamlOutput } from '../utils/output.js';
 import { mergeSkillPackagingConfig } from '../utils/skill-packaging-config.js';
@@ -87,33 +89,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 +150,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 +168,24 @@ 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);
+        // 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;
+        const sharedCtx = {
+            registry: await crawlAndResolveRegistry(projectRoot),
+            locationRoot,
+        };
+        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 +208,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 +241,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 +335,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,15 +356,15 @@ 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
@@ -332,13 +372,13 @@ async function auditUserDirectories(recursive, options, startTime, logger) {
         : 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 +398,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 +441,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 +515,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'.
@@ -480,16 +542,35 @@ async function runAuditAtPath(scanPath, options, overrides = {}) {
         ? await runCompatAnalysis(results, logger, 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);
     logger.debug(`Audit complete in ${Date.now() - startTime}ms`);
 }
 async function runUrlAudit(rawInput, options) {
@@ -509,7 +590,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 +620,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 +652,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 +679,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 +691,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 +701,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 +717,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 +764,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 +772,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 +781,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 +799,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];
@@ -720,7 +820,7 @@ export async function getValidationResults(scanPath, recursive, options, logger)
             const mergedOptions = configExcludes.length > 0
                 ? { ...options, exclude: [...(options.exclude ?? []), ...configExcludes] }
                 : options;
-            return scanDirectory(scanPath, recursive, mergedOptions, logger);
+            return scanDirectory(scanPath, recursive, mergedOptions, logger, await resolveScanContext(scanPath, locationRoot));
         }
     }
     catch {
@@ -728,7 +828,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 +840,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 +850,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;
 }
@@ -893,12 +993,35 @@ function applyVerboseFilter(results, verbose) {
         return stripped;
     });
 }
-function calculateSummary(results, startTime, compatMap, verbose) {
+/**
+ * Re-base each emitted file entry's `path` onto the run root.
+ *
+ * `ValidationResult.path` stays ABSOLUTE inside the pipeline on purpose: it is
+ * the identity every internal map keys on (compat results, visited-path
+ * de-duplication, registry caches), and unlike `location` it is trivially
+ * recoverable — an absolute path plus the known root yields the relative form.
+ * `location` is the opposite: it cannot be re-based here because a relative
+ * string whose base was never stated is not recoverable, which is exactly why
+ * the base is threaded down to the producers instead.
+ */
+function relativizeFileEntries(entries, root) {
+    return entries.map((entry) => {
+        const relative = issueLocation(entry.path, root);
+        // Pointing audit AT a single resource makes that resource the root, which
+        // relativizes to the empty string. Spell it `.` — the POSIX name for "the
+        // root itself" — so no consumer has to special-case an empty path, and
+        // `join(root, path)` still resolves.
+        return { ...entry, path: relative === '' ? '.' : relative };
+    });
+}
+function calculateSummary(results, startTime, compatMap, verbose, root) {
     const base = buildBaseSummary(results, startTime);
     const withCompat = applyCompatMap(results, compatMap);
     return {
+        // Stated once, first, and the only absolute path in the document.
+        root,
         ...base,
-        files: applyVerboseFilter(withCompat, verbose),
+        files: relativizeFileEntries(applyVerboseFilter(withCompat, verbose), root),
     };
 }
 /**
@@ -948,7 +1071,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 +1082,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;
+    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 +1100,18 @@ 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);
+        logErrors(results, errorCount, summary.root, logger);
     }
     else if (warningCount > 0) {
-        logWarnings(results, warningCount, logger);
+        logWarnings(results, warningCount, summary.root, logger);
     }
     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,20 +1135,20 @@ function renderAuditFooter(results, logger) {
     }
     renderSkillQualityFooter(logger, hasSkillFindings, emittedCodes);
 }
-function logErrors(results, errorCount, logger) {
+function logErrors(results, errorCount, root, 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}:`);
+        logger.error(`\n${issueLocation(result.path, root)}:`);
         const errorIssues = result.issues.filter((i) => i.severity === 'error');
         logIssues(errorIssues, logger.error.bind(logger));
     }
 }
-function logWarnings(results, warningCount, logger) {
+function logWarnings(results, warningCount, root, 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}:`);
+        logger.info(`\n${issueLocation(result.path, root)}:`);
         const warningIssues = result.issues.filter((i) => i.severity === 'warning');
         logIssues(warningIssues, logger.info.bind(logger));
     }
@@ -1028,8 +1156,9 @@ function logWarnings(results, warningCount, logger) {
 function logIssues(issues, logFn) {
     for (const issue of issues) {
         logFn(`  [${issue.code}] ${issue.message}`);
-        if (issue.location) {
-            logFn(`    at: ${issue.location}`);
+        const anchor = formatIssueAnchor(issue);
+        if (anchor !== undefined) {
+            logFn(`    at: ${anchor}`);
         }
         if (issue.fix) {
             logFn(`    fix: ${issue.fix}`);
@@ -1051,10 +1180,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 +1198,14 @@ 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 };
+            const sharedCtx = scanCtx.gitTracker === null
+                ? { locationRoot }
+                : { gitTracker: scanCtx.gitTracker, locationRoot };
             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 +1218,57 @@ 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;
 }
 /** 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.
+ */
+async function pluginInventoryAt(dir) {
+    const root = findProjectRoot(dir) ?? dir;
+    return extractClaudePluginInventory(dir, await getOrCreateInventoryRegistry(root));
+}
 /**
  * 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 +1277,8 @@ const gitTrackerCache = new Map();
  */
 export function resetAuditCaches() {
     gitTrackerCache.clear();
+    resetPackagingRegistryCache();
+    inventoryRegistryCache.clear();
     resetProjectRootCaches();
     resetLoadedConfigCache();
     resetSkillDiscoveryCache();
@@ -1138,18 +1303,18 @@ 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) {
     const detectedRoot = gitFindRoot(dirPath);
     if (detectedRoot === null) {
-        return { gitRoot: null, gitTracker: null };
+        return { gitRoot: null, gitTracker: null, locationRoot };
     }
     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 };
     }
-    return { gitRoot: detectedRoot, gitTracker: tracker };
+    return { gitRoot: detectedRoot, gitTracker: tracker, locationRoot };
 }
 /**
  * Build the gitignore exclusion map for a set of entry paths.
@@ -1188,14 +1353,14 @@ function getSkipReason(entry, fullPath, resolvedBaseDir, gitIgnoredMap, isMatch)
     }
     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
@@ -1256,76 +1421,48 @@ 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)
+ *
+ * `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.
  */
 function buildBaseSummary(results, startTime) {
-    const counts = calculateIssueCounts(results);
-    const status = calculateOverallStatus(results);
     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,
-        },
+        status: calculateOverallStatus(results),
+        summary: countFilesByStatus(results),
+        issueCounts: countBySeverity(results.flatMap((r) => r.issues)),
         duration: `${Date.now() - startTime}ms`,
     };
 }
 /**
  * Calculate summary for hierarchical output
  */
-function calculateHierarchicalSummary(results, hierarchical, startTime, compatMap, verbose) {
+function calculateHierarchicalSummary(results, hierarchical, startTime, compatMap, verbose, root) {
     const base = buildBaseSummary(results, startTime);
     const withCompat = applyCompatMap(results, compatMap);
     return {
+        root,
         ...base,
         summary: {
             ...base.summary,
@@ -1334,16 +1471,16 @@ function calculateHierarchicalSummary(results, hierarchical, startTime, compatMa
             standalonePlugins: hierarchical.standalonePlugins.length,
             standaloneSkills: hierarchical.standaloneSkills.length,
         },
-        files: applyVerboseFilter(withCompat, verbose),
+        files: relativizeFileEntries(applyVerboseFilter(withCompat, verbose), root),
         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 +1492,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`);
     }