@vibe-agent-toolkit/cli 0.2.0-rc.11 → 0.2.0-rc.12

package/dist/commands/audit-settings.d.ts

@@ -2,13 +2,19 @@
  * `vat audit settings` subcommand
  *
  * Shows effective merged Claude settings with provenance, or validates a specific file.
+ * Every mode publishes the report envelope through the one writer: `data.mode`
+ * says which mode ran, `findings` carry what is wrong (each with a registered
+ * `SETTINGS_*` code and the settings file as `location`), and `examined`
+ * counts the settings documents read.
  */
-import { type ProvenanceValue, type RuleConflict, type SettingsFinding, type SettingsPathEntry } from '@vibe-agent-toolkit/claude-marketplace';
+import { type ProvenanceValue, type RuleConflict, type SettingsPathEntry } from '@vibe-agent-toolkit/claude-marketplace';
+import { type Finding } from '@vibe-agent-toolkit/schema';
 import { Command } from 'commander';
+import type { AuditSettingsData } from './audit-settings-schema.js';
 export interface AuditSettingsOptions {
     showPaths?: boolean;
     file?: string;
-    type?: 'managed' | 'user' | 'project';
+    type?: string;
     debug?: boolean;
 }
 /** A formatted provenance value; `overrode` recurses down the whole chain. */
@@ -27,27 +33,40 @@ export interface FormattedProvenanceValue {
  * layer made a project override look like the only value ever declared — the
  * merger builds the linked list and this formatter used to throw it away.
  */
-export declare function formatProvenanceValue(pv: ProvenanceValue<unknown>): FormattedProvenanceValue;
+export declare function formatProvenanceValue(pv: ProvenanceValue<unknown>, root: string): FormattedProvenanceValue;
+/** One `data.paths[]` entry of `--show-paths`. */
+type FormattedPathEntry = Extract<AuditSettingsData, {
+    mode: 'paths';
+}>['paths'][number];
 /**
- * Format a resolved settings path for YAML output.
+ * Format a resolved settings path for the report's `data`.
  *
  * `exists`/`readable` are passed through verbatim, including the
  * `'undetermined'` value — a probe that could not run must not be rendered as a
- * confident `false`.
+ * confident `false`. A legacy path's error is the report's
+ * `SETTINGS_PATH_DEPRECATED` finding, never a `status` inside `data`: that
+ * would be a second status beside the envelope's.
  */
-export declare function formatSettingsPathEntry(p: SettingsPathEntry): Record<string, unknown>;
+export declare function formatSettingsPathEntry(p: SettingsPathEntry, root: string): FormattedPathEntry;
+/** A marketplace that cannot authenticate, and the settings file that registered it. */
+interface MarketplaceWarning {
+    message: string;
+    file: string;
+}
 /**
  * The findings an effective-settings audit produced.
  *
  * A shadowed rule and a marketplace that cannot authenticate are things the
  * reader must act on, so they are warnings — the run used to publish
- * `status: 'success'` with the conflicts listed underneath it, which is the
- * "warnings read as passed" collapse this command is being fixed for.
+ * a clean status with the conflicts listed underneath it, which is the
+ * "warnings read as passed" collapse this command is being fixed for. Each
+ * names the settings file to open, relative to `root`.
  */
-export declare function settingsAuditFindings(conflicts: readonly RuleConflict[], marketplaceWarnings: readonly string[]): SettingsFinding[];
+export declare function settingsAuditFindings(conflicts: readonly RuleConflict[], marketplaceWarnings: readonly MarketplaceWarning[], root: string): Finding[];
 export declare function runAuditSettings(options: AuditSettingsOptions): Promise<void>;
 /**
  * Create the `vat audit settings` subcommand.
  */
 export declare function createAuditSettingsCommand(): Command;
+export {};
 //# sourceMappingURL=audit-settings.d.ts.map

package/dist/commands/audit-settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit-settings.d.ts","sourceRoot":"","sources":["../../src/commands/audit-settings.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAQL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACvB,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAID,8EAA8E;AAC9E,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,wBAAwB,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,eAAe,CAAC,OAAO,CAAC,GAC3B,wBAAwB,CAQ1B;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYrF;AA6LD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,SAAS,YAAY,EAAE,EAClC,mBAAmB,EAAE,SAAS,MAAM,EAAE,GACrC,eAAe,EAAE,CAcnB;AA8DD,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CA8DpD"}
+{"version":3,"file":"audit-settings.d.ts","sourceRoot":"","sources":["../../src/commands/audit-settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACvB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAKL,KAAK,OAAO,EAGb,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,OAAO,KAAK,EAAE,iBAAiB,EAAuB,MAAM,4BAA4B,CAAC;AAEzF,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAYD,8EAA8E;AAC9E,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,wBAAwB,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,eAAe,CAAC,OAAO,CAAC,EAC5B,IAAI,EAAE,MAAM,GACX,wBAAwB,CAQ1B;AAED,kDAAkD;AAClD,KAAK,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,EAAE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzF;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAS9F;AAmJD,wFAAwF;AACxF,UAAU,kBAAkB;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAgFD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,SAAS,YAAY,EAAE,EAClC,mBAAmB,EAAE,SAAS,kBAAkB,EAAE,EAClD,IAAI,EAAE,MAAM,GACX,OAAO,EAAE,CAmBX;AAsED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAmEpD"}

package/dist/commands/audit-settings.js

@@ -2,13 +2,24 @@
  * `vat audit settings` subcommand
  *
  * Shows effective merged Claude settings with provenance, or validates a specific file.
+ * Every mode publishes the report envelope through the one writer: `data.mode`
+ * says which mode ran, `findings` carry what is wrong (each with a registered
+ * `SETTINGS_*` code and the settings file as `location`), and `examined`
+ * counts the settings documents read.
  */
-import { analyzeRuleConflicts, auditSettings, getSettingsFileFields, resolveSettingsPaths, summarizeSettingsFindings, validateSettingsFile, } from '@vibe-agent-toolkit/claude-marketplace';
-import { ExitCode } from '@vibe-agent-toolkit/schema';
+import { analyzeRuleConflicts, auditSettings, getSettingsFileFields, resolveSettingsPaths, validateSettingsFile, } from '@vibe-agent-toolkit/claude-marketplace';
+import { buildReport, countBySeverity, createRegistryIssue, toFindings, } from '@vibe-agent-toolkit/schema';
+import { isAbsoluteAnyPlatform, safePath, toForwardSlash } from '@vibe-agent-toolkit/utils';
 import { Command } from 'commander';
-import { handleCommandError } from '../utils/command-error.js';
+import { CommandRefusalError, refusalCodeOf } from '../utils/command-refusal.js';
+import { endWithRefusal, endWithReport, NOTHING_FINISHED } from '../utils/document-writer.js';
 import { createLogger } from '../utils/logger.js';
-import { writeYamlOutput } from '../utils/output.js';
+import { classifyInputFault } from '../utils/project-root-policy.js';
+import { relativizePath } from '../utils/relativize-paths.js';
+/** `vat audit settings` has no `--strict`: warnings never move its exit code. */
+const SETTINGS_GATE = { strict: false };
+/** The types `--type` accepts. */
+const SETTINGS_TYPES = ['managed', 'user', 'project'];
 /**
  * Format an EffectiveSettings value for YAML output, INCLUDING what it overrode.
  *
@@ -17,121 +28,158 @@ import { writeYamlOutput } from '../utils/output.js';
  * layer made a project override look like the only value ever declared — the
  * merger builds the linked list and this formatter used to throw it away.
  */
-export function formatProvenanceValue(pv) {
+export function formatProvenanceValue(pv, root) {
     return {
         value: pv.value,
-        source: pv.provenance.file,
+        source: spell(pv.provenance.file, root),
         level: pv.provenance.level,
         ...(pv.provenance.level === 'managed' ? { locked: true } : {}),
-        ...(pv.overrode ? { overrode: formatProvenanceValue(pv.overrode) } : {}),
+        ...(pv.overrode ? { overrode: formatProvenanceValue(pv.overrode, root) } : {}),
     };
 }
 /**
- * Format a resolved settings path for YAML output.
+ * Format a resolved settings path for the report's `data`.
  *
  * `exists`/`readable` are passed through verbatim, including the
  * `'undetermined'` value — a probe that could not run must not be rendered as a
- * confident `false`.
+ * confident `false`. A legacy path's error is the report's
+ * `SETTINGS_PATH_DEPRECATED` finding, never a `status` inside `data`: that
+ * would be a second status beside the envelope's.
  */
-export function formatSettingsPathEntry(p) {
+export function formatSettingsPathEntry(p, root) {
     return {
         label: p.label,
-        path: p.path,
+        path: spell(p.path, root),
         exists: p.exists,
         readable: p.readable,
         level: p.level,
         ...(p.accessError === undefined ? {} : { accessError: p.accessError }),
-        ...(p.status === 'error' && p.exists !== false
-            ? { status: 'error', message: p.message }
-            : {}),
     };
 }
-async function runShowPaths(startTime, logger) {
-    const cwd = process.cwd();
-    const result = await resolveSettingsPaths(cwd);
-    const findings = [];
+/**
+ * A settings path in this document's ONE coordinate system: forward-slashed and
+ * relative to `data.root`, the directory the command ran in — a user or managed
+ * file outside it reads `../…`, never the absolute path with `$HOME` in it. The
+ * one exception is a file on another Windows drive, which has no relative
+ * spelling: it is published as the absolute path rather than dropped.
+ */
+function spell(file, root) {
+    return relativizePath(safePath.resolve(root, file), root);
+}
+/**
+ * `issue` located at `file`, relative to `root`. A finding's `location` must be
+ * relative, so a file with no relative spelling (another Windows drive) leads
+ * the message instead — it is said, never silently dropped.
+ *
+ * The `SETTINGS_*` findings carry their severity from their emit site: this
+ * verb reads Claude settings, never a project's `validation:` config, so no
+ * override exists to resolve and none of them is a `validation.severity` key.
+ */
+function locatedAt(issue, file, root) {
+    if (file === '')
+        return issue;
+    const spelled = spell(file, root);
+    return isAbsoluteAnyPlatform(spelled)
+        ? { ...issue, message: `${spelled}: ${issue.message}` }
+        : { ...issue, location: spelled };
+}
+async function runShowPaths(root, logger) {
+    const result = await resolveSettingsPaths(root);
+    const issues = [];
     for (const p of result.paths) {
         if (p.status === 'error' && p.exists !== false) {
-            findings.push({
-                path: p.path,
-                message: p.message ?? 'Deprecated settings path is present',
+            issues.push(locatedAt({
+                code: 'SETTINGS_PATH_DEPRECATED',
                 severity: 'error',
-            });
+                message: p.message ?? 'Deprecated settings path is present',
+                fix: 'Move the managed settings file to the current managed-settings path (vat audit settings --show-paths lists it) and remove the legacy file.',
+            }, p.path, root));
         }
         if (p.exists === 'undetermined' || p.readable === 'undetermined') {
-            findings.push({
-                path: p.path,
-                message: `Could not determine access (${p.accessError ?? 'unknown error'}) — this path was not checked`,
-                severity: 'warning',
-            });
+            issues.push(locatedAt(createRegistryIssue('SCAN_PATH_UNREADABLE', `Could not determine access to ${p.path} (${p.accessError ?? 'unknown error'}) — this path was not checked`), p.path, root));
         }
     }
-    const { status, issueCounts } = summarizeSettingsFindings(findings);
-    writeYamlOutput({
-        status,
-        issueCounts,
-        paths: result.paths.map(formatSettingsPathEntry),
-        duration: `${Date.now() - startTime}ms`,
-    });
-    if (issueCounts.errors > 0) {
+    const { errors, warnings } = countBySeverity(issues);
+    if (errors > 0)
         logger.error('Legacy managed-settings.json path detected — IT admin must migrate.');
-        process.exit(ExitCode.FINDINGS);
+    if (warnings > 0)
+        logger.warn(`${warnings} settings path(s) could not be checked.`);
+    return buildReport({
+        // A path whose existence was determined was examined — absent is an answer; undetermined is not.
+        examined: result.paths.filter((p) => p.exists !== 'undetermined').length,
+        findings: toFindings(issues),
+        data: { mode: 'paths', root, paths: result.paths.map((p) => formatSettingsPathEntry(p, root)) },
+        gate: SETTINGS_GATE,
+    });
+}
+/** The `--type` the operator passed, or a `USAGE_INVALID` refusal for one the command does not know. */
+function declaredType(type) {
+    if (type === undefined)
+        return undefined;
+    if (SETTINGS_TYPES.includes(type))
+        return type;
+    throw new CommandRefusalError('USAGE_INVALID', `--type must be one of ${SETTINGS_TYPES.join(', ')} (got '${type}')`);
+}
+/**
+ * A read of the `--file` settings file, or the refusal that says why nothing
+ * was read: `USAGE_INVALID` for a path that names nothing (the same ending
+ * `vat audit <missing>` gives), a classified fault on the argument for one the OS
+ * refuses. Neither is a finding about the file — a finding needs a file that was read.
+ */
+async function readSettingsFile(filePath, read) {
+    try {
+        return await read();
     }
-    if (issueCounts.warnings > 0) {
-        logger.warn(`${issueCounts.warnings} settings path(s) could not be checked.`);
+    catch (error) {
+        throw classifyInputFault(filePath, error, { origin: 'argument', message: `Settings file does not exist: ${filePath}` });
     }
-    process.exit(ExitCode.OK);
 }
-async function runValidateFile(options, startTime, logger) {
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guarded by caller
-    const filePath = options.file;
-    const result = await validateSettingsFile(filePath, options.type);
-    // `null` means the fields could not be read — distinct from "no fields", and
-    // emitted as `fields: null` rather than as an empty list.
-    const fields = await getSettingsFileFields(filePath);
-    const duration = `${Date.now() - startTime}ms`;
-    writeYamlOutput({
-        status: result.status,
-        issueCounts: result.issueCounts,
-        file: filePath,
-        detectedType: result.detectedType,
-        typeConfidence: result.typeConfidence,
-        fields,
-        ...(result.findings.length > 0 ? { findings: result.findings } : {}),
-        duration,
-    });
-    if (result.issueCounts.errors > 0) {
-        logger.error(`Settings file is invalid: ${result.issueCounts.errors} error(s)`);
-        process.exit(ExitCode.FINDINGS);
+async function runValidateFile(filePath, type, root, logger) {
+    const settingsType = declaredType(type);
+    const result = await readSettingsFile(filePath, () => validateSettingsFile(filePath, settingsType));
+    // `null` means the file is not a JSON object — distinct from "no fields", and
+    // published as `fields: null` rather than as an empty list.
+    const fields = await readSettingsFile(filePath, () => getSettingsFileFields(filePath));
+    const issues = result.findings.map((finding) => locatedAt(finding, filePath, root));
+    if (result.summary.errors > 0) {
+        logger.error(`Settings file is invalid: ${result.summary.errors} error(s)`);
     }
-    logger.info(`Settings file is valid (${result.detectedType}, type ${result.typeConfidence})`);
-    process.exit(ExitCode.OK);
+    else {
+        logger.info(`Settings file is valid (${result.detectedType}, type ${result.typeConfidence})`);
+    }
+    return buildReport({
+        // The one document named — whether it parses is a finding about it.
+        examined: 1,
+        findings: toFindings(issues),
+        data: { mode: 'file', root, file: spell(filePath, root), detectedType: result.detectedType, typeConfidence: result.typeConfidence, fields },
+        gate: SETTINGS_GATE,
+    });
 }
-function buildPermissionsSummary(permissions) {
+function buildPermissionsSummary(permissions, root) {
     const summary = {};
     if (permissions.deny.length > 0) {
         summary['deny'] = permissions.deny.map(r => ({
             rule: r.rule,
-            source: r.provenance.file,
+            source: spell(r.provenance.file, root),
             level: r.provenance.level,
         }));
     }
     if (permissions.allow.length > 0) {
         summary['allow'] = permissions.allow.map(r => ({
             rule: r.rule,
-            source: r.provenance.file,
+            source: spell(r.provenance.file, root),
             level: r.provenance.level,
         }));
     }
     if (permissions.ask.length > 0) {
         summary['ask'] = permissions.ask.map(r => ({
             rule: r.rule,
-            source: r.provenance.file,
+            source: spell(r.provenance.file, root),
             level: r.provenance.level,
         }));
     }
     if (permissions.defaultMode) {
-        summary['defaultMode'] = formatProvenanceValue(permissions.defaultMode);
+        summary['defaultMode'] = formatProvenanceValue(permissions.defaultMode, root);
     }
     return summary;
 }
@@ -152,12 +200,12 @@ function buildMarketplacesSummary(effective) {
         // Check for GitHub repos without GITHUB_TOKEN
         for (const [name, entry] of Object.entries(pv.value)) {
             if (entry.source.source === 'github' && !process.env['GITHUB_TOKEN']) {
-                marketplaceWarnings.push(`Marketplace '${name}' sources from a private GitHub repo but GITHUB_TOKEN is not set`);
+                marketplaceWarnings.push({
+                    message: `Marketplace '${name}' sources from a private GitHub repo but GITHUB_TOKEN is not set`,
+                    file: pv.provenance.file,
+                });
             }
         }
-        if (marketplaceWarnings.length > 0) {
-            summary['warnings'] = marketplaceWarnings;
-        }
     }
     if (effective.enabledPlugins) {
         const pv = effective.enabledPlugins;
@@ -177,15 +225,15 @@ function buildMarketplacesSummary(effective) {
     }
     return { summary, warnings: marketplaceWarnings };
 }
-function formatConflicts(conflicts) {
+function formatConflicts(conflicts, root) {
     return conflicts.map(c => ({
         kind: c.kind,
         rule: c.rule.rule,
-        ruleSource: c.rule.provenance.file,
+        ruleSource: spell(c.rule.provenance.file, root),
         ruleLevel: c.rule.provenance.level,
         ruleList: getRuleList(c.kind),
         shadowedBy: c.shadowedBy.rule,
-        shadowedBySource: c.shadowedBy.provenance.file,
+        shadowedBySource: spell(c.shadowedBy.provenance.file, root),
         shadowedByLevel: c.shadowedBy.provenance.level,
         shadowedByList: getShadowedByList(c.kind),
     }));
@@ -209,46 +257,52 @@ function getShadowedByList(kind) {
  *
  * A shadowed rule and a marketplace that cannot authenticate are things the
  * reader must act on, so they are warnings — the run used to publish
- * `status: 'success'` with the conflicts listed underneath it, which is the
- * "warnings read as passed" collapse this command is being fixed for.
+ * a clean status with the conflicts listed underneath it, which is the
+ * "warnings read as passed" collapse this command is being fixed for. Each
+ * names the settings file to open, relative to `root`.
  */
-export function settingsAuditFindings(conflicts, marketplaceWarnings) {
-    const findings = conflicts.map(c => ({
-        path: c.rule.provenance.file,
+export function settingsAuditFindings(conflicts, marketplaceWarnings, root) {
+    const issues = conflicts.map(c => locatedAt({
+        code: 'SETTINGS_RULE_SHADOWED',
+        severity: 'warning',
         message: `Rule "${c.rule.rule}" (${c.rule.provenance.level}, ${getRuleList(c.kind)}) is shadowed by ` +
             `"${c.shadowedBy.rule}" (${c.shadowedBy.provenance.level}, ${getShadowedByList(c.kind)}) — ${c.kind}.`,
-        severity: 'warning',
-    }));
+        fix: 'Remove the shadowed rule, or narrow the rule that shadows it.',
+    }, c.rule.provenance.file, root));
     for (const warning of marketplaceWarnings) {
-        findings.push({ path: '', message: warning, severity: 'warning' });
+        issues.push(locatedAt({
+            code: 'SETTINGS_MARKETPLACE_TOKEN_MISSING',
+            severity: 'warning',
+            message: warning.message,
+            fix: 'Set GITHUB_TOKEN in the environment Claude Code runs in, or register the marketplace from a public source.',
+        }, warning.file, root));
     }
-    return findings;
+    return toFindings(issues);
 }
-async function runShowEffective(startTime, logger) {
-    const cwd = process.cwd();
-    const { effective, layers } = await auditSettings({ projectDir: cwd });
-    const duration = `${Date.now() - startTime}ms`;
-    const layersSummary = layers.map(l => ({ level: l.level, file: l.file, readable: true }));
-    const effectiveSummary = {};
-    if (effective.model)
-        effectiveSummary['model'] = formatProvenanceValue(effective.model);
-    if (effective.availableModels)
-        effectiveSummary['availableModels'] = formatProvenanceValue(effective.availableModels);
-    if (effective.forceLoginMethod)
-        effectiveSummary['forceLoginMethod'] = formatProvenanceValue(effective.forceLoginMethod);
-    if (effective.apiKeyHelper)
-        effectiveSummary['apiKeyHelper'] = formatProvenanceValue(effective.apiKeyHelper);
-    if (effective.autoUpdatesChannel)
-        effectiveSummary['autoUpdatesChannel'] = formatProvenanceValue(effective.autoUpdatesChannel);
-    if (effective.disableAllHooks)
-        effectiveSummary['disableAllHooks'] = formatProvenanceValue(effective.disableAllHooks);
-    if (effective.allowManagedHooksOnly)
-        effectiveSummary['allowManagedHooksOnly'] = formatProvenanceValue(effective.allowManagedHooksOnly);
-    if (effective.outputStyle)
-        effectiveSummary['outputStyle'] = formatProvenanceValue(effective.outputStyle);
-    if (effective.language)
-        effectiveSummary['language'] = formatProvenanceValue(effective.language);
-    const permissionsSummary = buildPermissionsSummary(effective.permissions);
+/** The merged value of every scalar setting the report shows, with its override chain. */
+function effectiveScalars(effective, root) {
+    const scalars = [
+        ['model', effective.model],
+        ['availableModels', effective.availableModels],
+        ['forceLoginMethod', effective.forceLoginMethod],
+        ['apiKeyHelper', effective.apiKeyHelper],
+        ['autoUpdatesChannel', effective.autoUpdatesChannel],
+        ['disableAllHooks', effective.disableAllHooks],
+        ['allowManagedHooksOnly', effective.allowManagedHooksOnly],
+        ['outputStyle', effective.outputStyle],
+        ['language', effective.language],
+    ];
+    const summary = {};
+    for (const [key, value] of scalars) {
+        if (value)
+            summary[key] = formatProvenanceValue(value, root);
+    }
+    return summary;
+}
+async function runShowEffective(root, logger) {
+    const { effective, layers } = await auditSettings({ projectDir: root });
+    const effectiveSummary = effectiveScalars(effective, root);
+    const permissionsSummary = buildPermissionsSummary(effective.permissions, root);
     if (Object.keys(permissionsSummary).length > 0) {
         effectiveSummary['permissions'] = permissionsSummary;
     }
@@ -257,41 +311,46 @@ async function runShowEffective(startTime, logger) {
         effectiveSummary['marketplaces'] = marketplaces.summary;
     }
     const conflicts = analyzeRuleConflicts(effective);
-    const { status, issueCounts } = summarizeSettingsFindings(settingsAuditFindings(conflicts, marketplaces.warnings));
-    const output = {
-        status,
-        issueCounts,
-        layers: layersSummary,
-        effectiveSettings: effectiveSummary,
-        duration,
-    };
-    if (conflicts.length > 0) {
-        output['conflicts'] = formatConflicts(conflicts);
-    }
-    writeYamlOutput(output);
+    const findings = settingsAuditFindings(conflicts, marketplaces.warnings, root);
     if (layers.length === 0) {
         logger.info('No settings files found');
     }
     else {
         logger.info(`Loaded ${layers.length} settings layer(s)`);
     }
-    if (issueCounts.warnings > 0) {
-        logger.warn(`${issueCounts.warnings} warning(s): see conflicts / marketplaces.warnings in the output.`);
+    const { warnings } = countBySeverity(findings);
+    if (warnings > 0) {
+        logger.warn(`${warnings} warning(s): see findings and data.conflicts in the output.`);
     }
-    process.exit(ExitCode.OK);
+    return buildReport({
+        examined: layers.length,
+        findings,
+        data: {
+            mode: 'effective',
+            root,
+            layers: layers.map(l => ({ level: l.level, file: spell(l.file, root) })),
+            effectiveSettings: effectiveSummary,
+            conflicts: formatConflicts(conflicts, root),
+        },
+        gate: SETTINGS_GATE,
+    });
+}
+/** Run the mode the options name. */
+function runMode(options, root, logger) {
+    if (options.showPaths)
+        return runShowPaths(root, logger);
+    if (options.file !== undefined)
+        return runValidateFile(options.file, options.type, root, logger);
+    return runShowEffective(root, logger);
 }
 export async function runAuditSettings(options) {
     const logger = createLogger(options.debug ? { debug: true } : {});
-    const startTime = Date.now();
     try {
-        if (options.showPaths)
-            return await runShowPaths(startTime, logger);
-        if (options.file)
-            return await runValidateFile(options, startTime, logger);
-        await runShowEffective(startTime, logger);
+        // The report's one stated root: every path in it is relative to where it ran.
+        endWithReport('audit settings', await runMode(options, toForwardSlash(process.cwd()), logger), 'yaml');
     }
     catch (error) {
-        handleCommandError(error, logger, startTime, 'AuditSettings');
+        endWithRefusal('audit settings', refusalCodeOf(error), error, 'yaml', SETTINGS_GATE, NOTHING_FINISHED);
     }
 }
 /**
@@ -321,29 +380,34 @@ Description:
   redundant rules within the same bucket.
 
 Output:
-  - status: worst actionable severity (success | warning | error)
-  - issueCounts: errors / warnings / info counts, published beside the status
-  - layers: all loaded settings files in precedence order (highest first)
-  - effectiveSettings: merged values with source file and level for each field;
-      each value carries an "overrode" chain naming every value it replaced,
-      down to the lowest-precedence layer
-  - permissions: accumulated allow/deny/ask rules from all layers
-  - conflicts: rules that are unreachable or redundant (omitted if none)
-
-  With --file, "typeConfidence" states how the settings type was determined:
-  declared (you passed --type), inferred (a managed-only field settled it),
-  ambiguous (user and project share one schema, so it could be either), or
-  undetermined (the file could not be read). "fields: null" means the fields
-  could not be read at all, as distinct from "fields: []" (none declared).
-
-  With --show-paths, "exists"/"readable" may be the string "undetermined" when
-  the probe itself failed (e.g. a permission error on a parent directory) —
-  that is not the same answer as false.
+  The report envelope every report verb publishes (YAML on stdout):
+  - status: ok (no findings) | findings (at least one) | error (did not finish)
+  - examined: settings documents read; summary: findings by severity
+  - findings: SETTINGS_* codes, each with the settings file as 'location'
+      and the key path as 'field'
+  - data.root: the directory it ran in — the one absolute path; every other
+      path (location, layers[].file, sources, paths[].path) is relative to it
+  - data.mode: effective (default) | file (--file) | paths (--show-paths)
+  - data (effective): layers (highest precedence first), effectiveSettings
+      (each value with its source and an "overrode" chain down to the
+      lowest-precedence layer), conflicts (unreachable or redundant rules)
+  - data (file): detectedType, typeConfidence — declared (--type), inferred
+      (a managed-only field settled it), ambiguous (user and project share one
+      schema) or undetermined (not JSON) — and fields ("fields: null" means the
+      file is not a JSON object, as distinct from "fields: []"); an absent or
+      unreadable --file is refused (exit 2), never reported
+  - data (paths): every settings path; "exists"/"readable" may be the string
+      "undetermined" when the probe itself failed — not the same answer as false
 
 Exit Codes:
-  0 - No errors (warnings are reported in issueCounts, not in the exit code)
-  1 - Invalid settings file (--file mode) or legacy Windows path detected
-  2 - System error
+  0 - No finding at error severity (warnings are in the report, not the exit code)
+  1 - An error-severity finding (an invalid settings file, a legacy managed
+      path), or no settings document could be read at all
+  2 - Did not finish ('status: error'): USAGE_INVALID for a --file that does
+      not exist or a --type the command does not know, INPUT_UNREADABLE for a
+      --file the OS will not let it read, or (default mode) for a discovered
+      settings layer the OS refuses, that does not parse, or that fails its
+      schema
 
 Example:
   $ cd ~/my-project && vat audit settings       # What can Claude do here?