@jacebenson/jsn 4.3.13-dev.73.1 → 4.3.13-dev.75.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.13-dev.73.1",
+  "version": "4.3.13-dev.75.1",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/skills/servicenow/SKILL.md

@@ -14,7 +14,7 @@ compatibility: |
   Works with Claude Code, OpenCode, Cursor, and agentskills-compatible tools.
 metadata:
   author: jacebenson
-  version: "4.3.9"
+  version: "4.3.11"
   repository: https://github.com/jacebenson/jsn
 ---
 
@@ -42,10 +42,9 @@ All `list` subcommands use a paginated interactive picker in TTY mode:
 
 1. **Output modes** — `--json` when parsing data; text when presenting to humans
 2. **Use sys_id for updates** — All update/delete operations require sys_id
-3. **Check auth first** — Run `jsn auth status` before operations
-4. **Verify the intended instance** — Use `--profile <name>` for explicit targeting; never assume the default is right. `jsn auth switch <name>` changes the default.
-5. **Eval safety** — Prefer purpose-built or `records` commands. Never use `eval` to bypass a blocked business rule, ACL, or other ServiceNow protection. If eval is genuinely needed, explain why and obtain explicit user approval.
-6. **CONFIRM before destructive operations** — Show what will be created/updated/deleted and ask for approval.
+3. **Verify the intended instance** — Use `--profile <name>` for explicit targeting; never assume the default is right. `jsn auth switch <name>` changes the default.
+4. **Eval safety** — Prefer purpose-built or `records` commands. Never use `eval` to bypass a blocked business rule, ACL, or other ServiceNow protection. If eval is genuinely needed, explain why and obtain explicit user approval.
+5. **CONFIRM before destructive operations** — Show what will be created/updated/deleted and ask for approval.
 
 ## Command Hierarchy
 
@@ -74,41 +73,17 @@ Pick the most specific tool for the job. **Never default to eval** — it's the
 
 ### Customization evidence
 
+Use `jsn customizations --help` to discover bounded read-only capture and offline
+review/comparison. For example:
+
 ```sh
 jsn customizations capture --label review --customer-scope x_acme_app --json
-jsn customizations list --json
-jsn customizations show <run_id> --get data.categories
-jsn customizations show <run_id> --get data.triage
-jsn customizations html <run_id> [--out review.html]
-jsn customizations compare <baseline_id> <new_id> --json
+jsn customizations show <run_id> --json
 ```
 
-Capture performs bounded GET-only table reads and saves local reports. It never
-evals or creates, updates or deletes instance records. Standard authentication
-may refresh OAuth tokens, store refreshed credentials locally and bootstrap a
-session/GCK using authentication POSTs. List/show/compare are offline.
-Declare customer ownership with repeatable `--customer-scope` values or sys_ids;
-never infer customer ownership from a non-global scope. The declaration is
-caller evidence, not independent publisher verification. OOTB findings reflect
-historical upgrade skips, not a current verified baseline deviation. The upgrade
-history is read server-side for the skip dispositions and every observed skipped
-`file_name` is resolved against `sys_metadata` by chunked
-`sys_update_nameIN<chunk>` lookups, so the OOTB inventory covers the observed
-skipped artifacts; the broad `sys_metadata` read is an arbitrary `sys_id`-ordered
-slice and is reported as a bounded sample, not an inventory, describing only the
-unclassified and declared-customer categories. Unresolved skipped names and
-failed lookup chunks stay explicit rather than becoming absent artifacts, and a
-resolved artifact can lack a scope name when its scope record was outside the
-bounded `sys_scope` read. Missing
-ACL access, pagination limits and unmatched evidence remain explicit. All
-reports are incomplete; no findings is not proof of no customizations.
-Comparisons cover captured metadata/evidence, not source payloads. Removals mean
-no longer observed, not proven deletion. Reversion impact and dependencies
-remain unknown until separately investigated. Never recommend automatic reversion.
-
-Upgrade history joins `file_name` to metadata `sys_update_name`. Raw disposition
-`4` or `104` is skipped-customization evidence; resolution `reviewed_reverted`
-excludes that history row. Use raw values, not display labels or other skip reasons.
+Read the CLI's interpretation, coverage and per-artifact triage before drawing
+conclusions. Verify ownership and current behavior before proposing changes;
+never recommend automatic reversion.
 
 ### Complete an update set
 

package/src/auth-recovery.js

@@ -1,4 +1,4 @@
-import { errAPI } from './errors.js';
+import { errAPI, errAuth } from './errors.js';
 import { canUsePicker, quoteShellArg } from './helpers.js';
 import { confirm } from './prompts.js';
 
@@ -34,6 +34,15 @@ export function createAuthRecovery({ app, session, argv = () => app._authArgv ||
   let recoveryAttempt;
   const provider = {
     error: failure(),
+    credentialError(cause) {
+      // Local validation can fail before any HTTP response. Keep its precise
+      // reason, but target recovery to this invocation rather than the default.
+      const error = errAuth(`${cause.message} (${label}).`);
+      error.profile = profileName || null;
+      error.recovery = `jsn auth login ${target}`;
+      error.hint = `Run: ${error.recovery}`;
+      return error;
+    },
     async recover({ status }) {
       if (status !== 401) return false;
       return recoveryAttempt ??= recoverOnce();

package/src/commands/customizations.js

@@ -4,6 +4,7 @@ import { canUsePicker } from '../helpers.js';
 import { paginatedSearch } from '../paginated-search.js';
 import { captureReport, listReports, getReport, compareReports, formatReport, formatReportList, formatReportComparison } from '../customizations.js';
 import { buildActionableReport, writeCustomizationHtml } from '../customizations-report.js';
+import { customizationGuidance, formatCustomizationGuidance } from '../customization-guidance.js';
 
 // Only capture needs an instance. Saved reports never need network access.
 declareCapabilities('customizations', { noInstance: true, skipDailyChecks: true, mutationSubcommands: [] });
@@ -25,7 +26,7 @@ async function pickReport(app, argv, exclude = null, message = 'Select a customi
 function show(app, report, options = {}) {
   const actionable = buildActionableReport(report);
   const triage = actionable.artifacts.map(({ category, category_label, identity, triage: classification }) => ({ category, category_label, identity, ...classification }));
-  app.ok({ ...report, triage, _formatted: formatReport(report, options) }, { summary: `Customization capture ${report.run_id}: ${report.status}`, breadcrumbs: [listHint, showHint(report.run_id), compareHint(report.run_id)] });
+  app.ok({ ...report, interpretation: customizationGuidance(), triage, _formatted: formatReport(report, options) }, { summary: `Customization capture ${report.run_id}: ${report.status}`, breadcrumbs: [listHint, showHint(report.run_id), compareHint(report.run_id)] });
 }
 export function customizationsCmd(wrap) {
   return {
@@ -36,7 +37,8 @@ export function customizationsCmd(wrap) {
         builder: b => b.option('label', { type: 'string', describe: 'Label for this capture' })
           .option('customer-scope', { type: 'string', array: true, default: [], describe: 'Declared customer-owned scope value or sys_id, repeatable; ownership is not inferred' })
           .option('page-size', { type: 'number', default: 100, describe: 'Records per table page, 1..1000' })
-          .option('max-pages', { type: 'number', default: 10, describe: 'Maximum pages per source, 1..100' }),
+          .option('max-pages', { type: 'number', default: 10, describe: 'Maximum pages per source, 1..100' })
+          .epilogue(`${customizationGuidance().capture}\n${formatCustomizationGuidance()}\nExample: jsn customizations capture --label review --customer-scope x_acme_app --json`),
         handler: wrap(async (argv, app) => {
           app.requireInstance();
           if (!Number.isInteger(argv.pageSize) || argv.pageSize < 1 || argv.pageSize > 1000 || !Number.isInteger(argv.maxPages) || argv.maxPages < 1 || argv.maxPages > 100) throw errUsage('page-size must be 1..1000 and max-pages 1..100');
@@ -55,18 +57,21 @@ export function customizationsCmd(wrap) {
       })
       .command({ command: 'show [run_id]', describe: 'Review a saved capture offline', builder: b => b
         .option('group-by', { type: 'string', choices: ['type', 'scope', 'updated-by'], default: 'type', describe: 'Group summary by file type, scope or last updater' })
-        .option('filter', { type: 'string', describe: 'Expand a group shown in the summary (friendly or table name for file types)' }), handler: wrap(async (argv, app) => {
+        .option('filter', { type: 'string', describe: 'Expand a group shown in the summary (friendly or table name for file types)' })
+        .epilogue(`Offline review: inspect coverage, interpretation and triage in --json output.\n${formatCustomizationGuidance()}\nExample: jsn customizations show <run_id> --get data.triage`), handler: wrap(async (argv, app) => {
         const report = argv.run_id ? requireReport(argv.run_id) : await pickReport(app, argv);
         if (report) show(app, report, { groupBy: argv.groupBy, filter: argv.filter || '' });
       }) })
       .command({ command: 'html [run_id]', describe: 'Write a searchable, self-contained HTML review of a saved capture', builder: b => b
-        .option('out', { type: 'string', describe: 'Output HTML path (must not already exist)' }), handler: wrap(async (argv, app) => {
+        .option('out', { type: 'string', describe: 'Output HTML path (must not already exist)' })
+        .epilogue('Offline review with the same interpretation and coverage as show; writes a local file without changing instance records.\nExample: jsn customizations html <run_id> --out review.html'), handler: wrap(async (argv, app) => {
         const report = argv.run_id ? requireReport(argv.run_id) : await pickReport(app, argv);
         if (!report) return;
         const file = writeCustomizationHtml(report, { out: argv.out });
-        app.ok({ run_id: report.run_id, file, artifacts: Object.values(report.categories).reduce((total, items) => total + items.length, 0) }, { summary: `Wrote offline customization review: ${file}`, breadcrumbs: [listHint, showHint(report.run_id)] });
+        app.ok({ run_id: report.run_id, file, artifacts: Object.values(report.categories).reduce((total, items) => total + items.length, 0), interpretation: customizationGuidance() }, { summary: `Wrote offline customization review: ${file}`, breadcrumbs: [listHint, showHint(report.run_id)] });
       }) })
-      .command({ command: 'compare [baseline] [new]', describe: 'Compare two saved captures from the same instance', handler: wrap(async (argv, app) => {
+      .command({ command: 'compare [baseline] [new]', describe: 'Compare two saved captures from the same instance',
+        builder: b => b.epilogue(`Offline metadata/evidence comparison; inspect both captures' coverage before interpreting changes.\n${formatCustomizationGuidance()}\nExample: jsn customizations compare <baseline_id> <new_id> --json`), handler: wrap(async (argv, app) => {
         if (!!argv.baseline !== !!argv.new) throw errUsage('Compare requires exactly two report IDs');
         if (argv.baseline && argv.baseline === argv.new) throw errUsage('Compare requires two different report IDs');
         const baseline = argv.baseline ? requireReport(argv.baseline) : await pickReport(app, argv, null, 'Select the baseline capture');
@@ -76,7 +81,8 @@ export function customizationsCmd(wrap) {
         if (baseline.instance !== newer.instance) throw errUsage('Customization reports must describe the same instance');
         const result = compareReports(baseline, newer);
         app.ok({ ...result, _formatted: formatReportComparison(result) }, { summary: `Customization comparison: ${result.status}`, breadcrumbs: [listHint, showHint(baseline.run_id), showHint(newer.run_id)] });
-      }) }),
+      }) })
+      .epilogue(`${customizationGuidance().capture}\n${formatCustomizationGuidance()}\nStart: jsn customizations capture --help\nReview: jsn customizations show --help\nCompare: jsn customizations compare --help`),
     handler: wrap(async (_argv, app) => app.ok({ command: 'customizations', subcommands: ['capture', 'list', 'show', 'html', 'compare'] }, { summary: 'Use `jsn customizations <subcommand> --help` for details.' })),
   };
 }

package/src/customization-guidance.js

@@ -0,0 +1,31 @@
+// Shared interpretation for CLI help, saved-report views and comparisons.
+// Keep this independent of capture/storage so older captures remain readable.
+export function customizationGuidance() {
+  return {
+    capture: 'Capture uses bounded GET-only table reads and saves reports locally. Authentication may refresh OAuth credentials locally or bootstrap a session/GCK with authentication POSTs. Saved list/show/compare/html operations are offline.',
+    evidence: {
+      upgrade_skips: 'Raw upgrade dispositions 4 and 104 are historical skipped-customization evidence; reviewed_reverted rows are excluded. Display labels and other skip reasons are not equivalent. A skip does not prove a current OOTB baseline deviation.',
+      ownership: 'Customer scopes must be declared explicitly. Matching a scope verifies its identity, not customer or publisher ownership. Non-global scope and updater names do not establish ownership.',
+      metadata: 'The broad sys_metadata read is an arbitrary sys_id-ordered bounded sample, not an inventory. Declared-customer and unclassified categories are not complete inventories; they can include sampled artifacts and artifacts found by skipped-history lookups.',
+      resolution: 'Every observed skipped file_name is resolved by chunked sys_metadata.sys_update_name lookups. Unresolved names and failed lookup chunks remain coverage gaps. A resolved artifact may lack a scope name when its scope was outside the bounded sys_scope read.',
+    },
+    limitations: [
+      'All captures are incomplete. No findings is not proof of no customizations; ACLs, pagination limits, unmatched evidence and concurrent changes can hide artifacts.',
+      'Current baseline, full source payloads, runtime reversion impact and dependencies are not established. An empty dependency list does not prove none exist.',
+    ],
+    comparison: 'Comparisons cover captured metadata and evidence only. Added/removed means newly observed/no longer observed, not proven creation/deletion. Changed declarations or coverage can change categories without an artifact change.',
+    next_steps: [
+      'Review coverage, evidence and per-artifact confidence before drawing conclusions.',
+      'Verify ownership and compare with a trusted baseline for the exact release; investigate dependencies and test in non-production before changing records. Never recommend automatic reversion.',
+    ],
+    automated_remediation: false,
+  };
+}
+
+export function formatCustomizationGuidance() {
+  const guidance = customizationGuidance();
+  return [
+    ...Object.values(guidance.evidence), ...guidance.limitations,
+    guidance.comparison, ...guidance.next_steps.map(step => `Next: ${step}`),
+  ].join('\n');
+}

package/src/customizations-report.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { customizationGuidance, formatCustomizationGuidance } from './customization-guidance.js';
 
 const CLASSIFICATIONS = {
   ootb_modifications: {
@@ -94,6 +95,7 @@ export function buildActionableReport(report) {
     start_time: report.start_time,
     artifacts,
     coverage: report.coverage,
+    interpretation: customizationGuidance(),
   };
 }
 
@@ -119,6 +121,7 @@ export function renderCustomizationHtml(report) {
 <section class="toolbar" aria-label="Report filters"><label class="control grow">Search artifacts<input id="search" type="search" placeholder="Name, table, scope, updater, evidence"></label><label class="control">Classification<select id="category"><option value="">All classifications</option>${categoryOptions}</select></label><label class="control">Group by<select id="group-by"><option value="type">File type</option><option value="scope">Scope</option><option value="updated_by">Updated by</option></select></label></section>
 <section id="results" aria-live="polite"></section>
 <details class="coverage"><summary>Capture coverage and limitations</summary><div id="coverage-content"></div></details>
+<details class="coverage"><summary>How to interpret this evidence</summary>${formatCustomizationGuidance().split('\n').map(line => `<p>${escapeHtml(line)}</p>`).join('')}</details>
 <script id="report-data" type="application/json">${data}</script>
 <script>
 'use strict';
@@ -146,6 +149,9 @@ function render(){
 for(const [categoryName,items] of Object.entries(report.artifacts.reduce((groups,item)=>{groups[item.category]=(groups[item.category]||0)+1;return groups;},{})))document.getElementById('stats').append(el('span',categoryName.replaceAll('_',' ')+': '+items,'stat'));
 search.addEventListener('input',render);category.addEventListener('change',render);groupBy.addEventListener('change',render);render();
 const coverage=document.getElementById('coverage-content');const ul=el('ul');for(const [source,details] of Object.entries(report.coverage.sources||{})){ul.append(el('li',source+': '+details.status+', '+details.fetched+'/'+(details.available??'unknown')+' rows. '+details.reason));}coverage.append(ul);for(const note of report.coverage.limitations||[])coverage.append(el('p',note));
+coverage.append(el('p','Unmatched upgrade history records: '+(report.coverage.unmatched_upgrade_records??'unknown')));
+if(report.coverage.unmatched_customer_scopes?.length)coverage.append(el('p','Unmatched customer declarations: '+report.coverage.unmatched_customer_scopes.join(', ')));
+const upgrade=report.coverage.upgrade_evidence;if(upgrade){coverage.append(el('p','Observed skipped rows: '+upgrade.skipped_rows_observed+'; update names: '+upgrade.update_names_observed+'; resolved by lookup: '+upgrade.resolved_by_lookup+'; failed lookup chunks: '+upgrade.lookup_failures));if(upgrade.unresolved_update_names?.length)coverage.append(el('p','Unresolved skipped update names: '+upgrade.unresolved_update_names.join(', ')));}
 </script>
 </main></body></html>\n`;
 }

package/src/customizations.js

@@ -6,6 +6,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { getVersion } from './commands/version.js';
 import { classifyCustomization } from './customizations-report.js';
+import { customizationGuidance, formatCustomizationGuidance } from './customization-guidance.js';
 
 // Raw provider choices: 4 = Skipped, 104 = Skipped (second pass). Other skip
 // dispositions do not establish a preserved customization, so the upgrade
@@ -290,22 +291,28 @@ export function compareReports(baseline, newer) {
   const unknowns = ['Additions/removals mean newly observed/no longer observed, not proven creation/deletion. ACLs, limits and concurrent changes can affect visibility.', 'Only captured metadata and evidence are compared, not full artifact content or OOTB baselines.', 'Ownership declarations, scope visibility and evidence coverage can cause category changes without an artifact change.'];
   if (unreliable) unknowns.push(`Unavailable or empty sources make observed additions/removals unreliable: baseline [${impaired.baseline.join(', ') || 'none'}], new [${impaired.new.join(', ') || 'none'}]. They may reflect missing coverage rather than a real change and must not be read as mass creation or deletion.`);
   return { baseline_run_id: baseline.run_id, new_run_id: newer.run_id, instance: baseline.instance, status: unreliable ? 'unreliable' : 'incomplete', additions, removals, changes,
-    impaired_sources: impaired,
+    impaired_sources: impaired, interpretation: customizationGuidance(),
     coverage: { baseline: baseline.coverage, new: newer.coverage },
     unknowns };
 }
 
-function formatReportDetailed(report) {
-  const lines = [`Customization capture ${report.run_id}${report.label ? ` (${report.label})` : ''}`, `Instance: ${report.instance}`, `Status: ${report.status}`, '', 'COVERAGE'];
-  for (const [source, coverage] of Object.entries(report.coverage.sources)) lines.push(`${source}${coverage.kind ? ` [${coverage.kind}]` : ''}: ${coverage.status}, ${coverage.fetched} fetched of ${coverage.available === null || coverage.available === undefined ? 'unknown' : coverage.available} available. ${coverage.reason}`);
-  for (const limitation of report.coverage.limitations) lines.push(`Unknown: ${limitation}`);
-  if (report.coverage.unmatched_customer_scopes.length) lines.push(`Unmatched customer declarations: ${report.coverage.unmatched_customer_scopes.join(', ')}`);
+function coverageLines(report) {
+  const lines = [];
+  for (const [source, coverage] of Object.entries(report.coverage.sources || {})) lines.push(`${source}${coverage.kind ? ` [${coverage.kind}]` : ''}: ${coverage.status}, ${coverage.fetched} fetched of ${coverage.available === null || coverage.available === undefined ? 'unknown' : coverage.available} available. ${coverage.reason}`);
+  for (const limitation of report.coverage.limitations || []) lines.push(`Unknown: ${limitation}`);
+  if (report.coverage.unmatched_customer_scopes?.length) lines.push(`Unmatched customer declarations: ${report.coverage.unmatched_customer_scopes.join(', ')}`);
   const upgrade = report.coverage.upgrade_evidence;
   if (upgrade) {
-    lines.push(`Observed skipped upgrade rows: ${upgrade.skipped_rows_observed}; distinct update names: ${upgrade.update_names_observed}; resolved by direct name lookup: ${upgrade.resolved_by_lookup}; unresolved: ${upgrade.unresolved_update_names.length}${upgrade.lookup_failures ? `; failed lookup chunks: ${upgrade.lookup_failures}` : ''}`);
-    if (upgrade.unresolved_update_names.length) lines.push(`Unresolved skipped update names (not visible in sys_metadata): ${upgrade.unresolved_update_names.slice(0, 20).join(', ')}${upgrade.unresolved_update_names.length > 20 ? `, ... and ${upgrade.unresolved_update_names.length - 20} more` : ''}`);
+    const unresolved = upgrade.unresolved_update_names;
+    lines.push(`Observed skipped upgrade rows: ${upgrade.skipped_rows_observed}; distinct update names: ${upgrade.update_names_observed}; resolved by direct name lookup: ${upgrade.resolved_by_lookup}; unresolved: ${unresolved?.length ?? 'unknown'}${upgrade.lookup_failures ? `; failed lookup chunks: ${upgrade.lookup_failures}` : ''}`);
+    if (unresolved?.length) lines.push(`Unresolved skipped update names (not visible in sys_metadata): ${unresolved.slice(0, 20).join(', ')}${unresolved.length > 20 ? `, ... and ${unresolved.length - 20} more` : ''}`);
   }
-  lines.push(`Unmatched upgrade history records: ${report.coverage.unmatched_upgrade_records}`);
+  lines.push(`Unmatched upgrade history records: ${report.coverage.unmatched_upgrade_records ?? 'unknown'}`);
+  return lines;
+}
+
+function formatReportDetailed(report) {
+  const lines = [`Customization capture ${report.run_id}${report.label ? ` (${report.label})` : ''}`, `Instance: ${report.instance}`, `Status: ${report.status}`, '', 'COVERAGE', ...coverageLines(report), '', 'INTERPRETATION', formatCustomizationGuidance()];
   for (const [category, items] of Object.entries(report.categories)) {
     lines.push('', `${category.toUpperCase()} (${items.length})`);
     for (const item of items) {
@@ -357,8 +364,13 @@ export function formatReport(report, { groupBy = 'type', filter = '' } = {}) {
   }
   lines.push('', 'Expand a group with --filter <group-name>. File-type filters accept the friendly label or table name. Regroup with --group-by scope or --group-by updated-by.', 'Examples:', `  jsn customizations show ${report.run_id} --filter "Script Include"`, `  jsn customizations show ${report.run_id} --group-by scope`, `  jsn customizations show ${report.run_id} --group-by updated-by`);
   lines.push('', 'Coverage and limitations are shared across these artifacts.');
-  for (const [source, coverage] of Object.entries(report.coverage.sources)) lines.push(`${source}: ${coverage.status}, ${coverage.fetched}/${coverage.available ?? 'unknown'} rows${coverage.kind ? ` (${coverage.kind})` : ''}`);
-  lines.push('Limits: metadata is a bounded sample; skipped-upgrade evidence is historical, not proof of a current OOTB difference. Scope and updater are clues, not proof of ownership.');
+  lines.push(...coverageLines(report), '', 'INTERPRETATION', formatCustomizationGuidance());
+  for (const [category, records] of Object.entries(report.categories)) {
+    if (!records.length) continue;
+    const triage = classifyCustomization(category);
+    lines.push(`${triage.label}: ${triage.confidence}. ${triage.summary}`);
+    for (const step of triage.next_steps) lines.push(`Next: ${step}`);
+  }
   return lines.join('\n') + '\n';
 }
 
@@ -395,18 +407,21 @@ function fieldChanges(before, after) {
 function describeComparedItem(item) {
   const identity = item?.identity || {};
   const scope = item?.scope || {};
+  const triage = classifyCustomization(item?.category);
   return [
     `Artifact: ${identity.table || 'unknown'}:${identity.sys_id || 'unknown'} "${identity.name || identity.update_name || 'unnamed'}"`,
     `Category: ${item?.category || 'unknown'}`,
     `Scope: ${scope.scope || scope.sys_id || 'unknown'}${scope.name ? ` (${scope.name})` : ''}`,
     `Evidence: ${(item?.evidence || []).map(evidence => `${evidence.source}:${evidence.sys_id}`).join(', ') || 'none captured'}`,
     `Risk: ${item?.risk?.rating || 'unknown'}`,
+    `Triage: ${triage.label} (${triage.confidence}). ${triage.summary}`,
+    ...triage.next_steps.map(step => `Next: ${step}`),
     `Recommendation: ${item?.recommendation || 'not recorded'}`,
   ];
 }
 
 export function formatReportComparison(result) {
-  const lines = [`Customization comparison: ${result.status}`, `Baseline: ${result.baseline_run_id}`, `New: ${result.new_run_id}`, ...result.unknowns];
+  const lines = [`Customization comparison: ${result.status}`, `Baseline: ${result.baseline_run_id}`, `New: ${result.new_run_id}`, ...result.unknowns, '', 'INTERPRETATION', formatCustomizationGuidance()];
   const impaired = result.impaired_sources || { baseline: [], new: [] };
   if (impaired.baseline.length) lines.push(`Unreliable baseline sources: ${impaired.baseline.join(', ')}`);
   if (impaired.new.length) lines.push(`Unreliable new sources: ${impaired.new.join(', ')}`);
@@ -511,7 +526,7 @@ export async function captureCustomizations({ sdk, customerScopes = [], pageSize
       },
       unmatched_upgrade_records: data.sys_upgrade_history_log.filter(row => !visibleNames.has(text(row.file_name))).length,
       unmatched_customer_scopes: customerScopes.filter(id => !data.sys_scope.some(row => text(row.sys_id) === id || text(row.scope) === id)),
-      limitations: ['Inventory covers visible sys_metadata and upgrade history only, not every customization mechanism.', `Upgrade history is read server-side for raw dispositions ${SKIP_DISPOSITIONS.join(' and ')} only; unmatched upgrade counts describe that filtered population, not all upgrade history.`, 'Coverage compares rows fetched with the Stats API count for the same query; a short page never implies exhaustion and an unavailable count leaves completeness unknown.', `The broad sys_metadata source is a bounded sample of an arbitrary sys_id-ordered slice, not an inventory, so unclassified and declared-customer categories only describe sampled artifacts. Skipped-upgrade artifacts are separate: they are resolved by the update names the filtered history read observed (${RESOLUTION_SOURCE}).`, 'Name resolution only looks up artifacts with skipped-upgrade evidence, so customizations with no upgrade-skip history are not discovered by it.', 'A resolved artifact can show a scope sys_id without a scope name when that scope record was outside the bounded sys_scope read.', 'Row/field ACL filtering and concurrent changes cannot be ruled out.', 'No current baseline, source payloads or dependency graph captured. Comparisons detect captured metadata/evidence changes only.', 'OOTB category means historical skipped-upgrade evidence, not a verified current deviation. Customer scopes are caller declarations.'],
+      limitations: ['Inventory covers visible sys_metadata and upgrade history only, not every customization mechanism.', `Upgrade history is read server-side for raw dispositions ${SKIP_DISPOSITIONS.join(' and ')} only; unmatched upgrade counts describe that filtered population, not all upgrade history.`, 'Coverage compares rows fetched with the Stats API count for the same query; a short page never implies exhaustion and an unavailable count leaves completeness unknown.', `The broad sys_metadata source is a bounded sample of an arbitrary sys_id-ordered slice, not an inventory, so unclassified and declared-customer categories are not complete inventories; they can include sampled artifacts and artifacts resolved by skipped-history lookups. Skipped-upgrade artifacts are separate: they are resolved by the update names the filtered history read observed (${RESOLUTION_SOURCE}).`, 'Name resolution only looks up artifacts with skipped-upgrade evidence, so customizations with no upgrade-skip history are not discovered by it.', 'A resolved artifact can show a scope sys_id without a scope name when that scope record was outside the bounded sys_scope read.', 'Row/field ACL filtering and concurrent changes cannot be ruled out.', 'No current baseline, source payloads or dependency graph captured. Comparisons detect captured metadata/evidence changes only.', 'OOTB category means historical skipped-upgrade evidence, not a verified current deviation. Customer scopes are caller declarations.'],
     },
   };
 }

package/src/sdk.js

@@ -1,7 +1,7 @@
 // ServiceNow REST API client
 
 import { gunzipSync } from 'node:zlib';
-import { errAuth, errAPI, errNetwork } from './errors.js';
+import { CodeAuth, errAuth, errAPI, errNetwork } from './errors.js';
 import { getStringField } from './helpers.js';
 import { getAction, getStepTypes, createAction, updateAction, testAction } from './processflow-actions.js';
 import { readSkippedBaseline, revertSkippedUpdate } from './skipped-update-provider.js';
@@ -59,7 +59,13 @@ export class SDKClient {
     if (!this.authProvider) {
       throw errAuth('No authentication configured');
     }
-    const creds = await this.authProvider.getCredentials();
+    let creds;
+    try {
+      creds = await this.authProvider.getCredentials();
+    } catch (error) {
+      if (error.code === CodeAuth && this.recovery?.credentialError) throw this.recovery.credentialError(error);
+      throw error;
+    }
     if (!creds) {
       throw errAuth('No valid credentials');
     }