@jacebenson/jsn 4.3.13-dev.72.1 → 4.3.13-dev.74.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.13-dev.72.1",
+  "version": "4.3.13-dev.74.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.6"
+  version: "4.3.10"
   repository: https://github.com/jacebenson/jsn
 ---
 
@@ -43,10 +43,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. **NEVER logout** — Only run `jsn auth logout` if the user explicitly asks
-5. **Use `--profile <name>`** to target a specific instance, or `jsn auth switch <name>` to change the default
-6. **Before using `eval` or `rest`** — Ask: *"Is there a more specific jsn command?"* Prefer specific over generic over escape hatch over eval.
-7. **CONFIRM before destructive operations** — Show what will be created/updated/deleted and ask for approval.
+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.
 
 ## Command Hierarchy
 
@@ -75,44 +74,26 @@ 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
 
+Before development changes, identify the intended application scope and update
+set. Keep related changes together, use the appropriate update-set or application
+deployment mechanism, and report where changes were captured. Not all changes
+are update-set tracked. Only complete a set when the human explicitly asks,
+including sets you created; completing the current set returns selection to Default.
+
 ```bash
 jsn updatesets complete "My Feature" --notes "Fixed validation" --force --json
 ```
@@ -127,18 +108,10 @@ child sets when the parent completes; their descriptions are not replaced.
 Both selected-set Description and state are read back before success. On
 verification failure, inspect the set before retrying.
 
-### Table and raw REST examples
-
-```bash
-# Query a table with the normal records command
-jsn records list --table incident --query "active=true" --limit 5 --json
-
-# Get a single record
-jsn records get --table incident --sys-id abc123... --json
+### Table and raw REST discovery
 
-# Raw endpoint access when no specific command fits
-jsn rest "/api/now/table/incident?sysparm_limit=3" --json
-```
+Use `jsn records list --help`, `jsn records get --help`, and `jsn rest --help`
+for syntax and examples. REST is blocked on read-only connections, including GET.
 
 ### `jsn docs` — offline documentation search
 

package/src/auth.js

@@ -612,7 +612,9 @@ export class AuthManager {
     if (!instance) {
       throw errAuth('No instance specified');
     }
+    const existed = !!this.credentialStore.load(instance, username);
     this.credentialStore.delete(instance, username);
+    return existed && !this.credentialStore.load(instance, username);
   }
 
   /**

package/src/commands/auth.js

@@ -1,5 +1,5 @@
 import { getEffectiveInstance, normalizeInstanceURL, saveConfig, setActiveProfile } from '../config.js';
-import { errUsage, errUsageHint } from '../errors.js';
+import { errUsage, errUsageHint, errConfirmationRequired } from '../errors.js';
 import { canUsePicker, formatCommandList, quoteShellArg } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 import process from 'node:process';
@@ -808,10 +808,33 @@ Examples:
   }
   const target = resolveTargetProfile(argv, app.config, instanceURL);
   const username = target.profile?.username ?? null;
-  if (username || canLogoutBareProfile(app, instanceURL, target.profile, !!argv.profile)) {
-    app.auth.logout(instanceURL, username);
+  if (!username && !canLogoutBareProfile(app, instanceURL, target.profile, !!target.name)) {
+    throw errUsageHint('Cannot identify which stored credentials to clear.', 'Choose an unambiguous identity with --profile <name>.');
   }
-  app.ok({ logged_out: true, instance: instanceURL }, { summary: `✓ Logged out from ${instanceURL}` });
+  const selector = target.name ? `--profile ${quoteShellArg(target.name)}` : quoteShellArg(instanceURL);
+  const rerun = `jsn auth logout ${selector}`;
+  const warning = `Clear locally stored credentials for ${target.name ? `profile "${target.name}" at ` : ''}${instanceURL}${username ? ` (user ${username})` : ''}? You will need to authenticate again. The profile is retained; environment credentials and ServiceNow/Chrome sessions are unaffected.`;
+  if (!argv.force) {
+    if (!canUsePicker(app, argv)) throw errConfirmationRequired(warning, rerun);
+    const { confirm } = await import('../prompts.js');
+    if (!await confirm({ message: warning, default: false })) {
+      app.ok({ logged_out: false, credentials_cleared: false, profile: target.name, instance: instanceURL },
+        { summary: 'Logout cancelled; stored credentials were retained.' });
+      return;
+    }
+  }
+  const cleared = app.auth.logout(instanceURL, username) === true;
+  const nextActions = cleared ? [
+    { action: 'Authenticate again', cmd: `jsn auth login ${selector}`, description: 'Restore locally stored authentication' },
+    ...(target.name ? [{ action: 'Remove retained profile', cmd: `jsn auth remove ${quoteShellArg(target.name)}`, description: 'Remove this connection if no longer needed' }] : []),
+  ] : [];
+  app.ok({ logged_out: cleared, credentials_cleared: cleared, profile: target.name, instance: instanceURL,
+    profile_retained: !!target.name, environment_credentials_affected: false, remote_session_terminated: false,
+    next_actions: nextActions }, {
+    summary: cleared ? `✓ Cleared local credentials for ${target.name || instanceURL}. Profile retained; environment credentials and ServiceNow/Chrome sessions are unaffected.`
+      : `No stored credentials were cleared for ${target.name || instanceURL}. Environment credentials and ServiceNow/Chrome sessions are unaffected.`,
+    breadcrumbs: nextActions,
+  });
 }
 
 export async function showAuthStatus(argv, app) {
@@ -1099,7 +1122,8 @@ export function authCmd(wrap) {
         })
         .command({
           command: 'logout [instance]',
-          describe: 'Clear stored credentials (keeps the instance entry — use "auth remove" to delete it)',
+          describe: 'Clear local credentials after approval; retains the profile. Unnecessary after ordinary operations; does not sign out of ServiceNow/Chrome or clear environment credentials.',
+          builder: sub => sub.option('force', { type: 'boolean', describe: 'Clear credentials only after explicit approval for this exact logout' }),
           handler: wrap(logoutProfile),
         })
         .command({

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/commands/records.js

@@ -83,7 +83,15 @@ export function recordsCmd(wrap) {
             .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { type: 'number', default: 20, describe: 'Max records' })
             .option('offset', { type: 'number', default: 0, describe: 'Offset' })
-            .option('count', { type: 'boolean', default: true, describe: 'Include the total-matching count (use --no-count to opt out)' }),
+            .option('count', { type: 'boolean', default: true, describe: 'Include the total-matching count (use --no-count to opt out)' })
+            .epilogue([
+              'In an interactive terminal with automatic output, browse a picker (10 visible items).',
+              'Use arrow keys to browse, type to search sys_id on the server, scroll to load more,',
+              'and press Enter to select or Esc to cancel. --sys-id skips the picker.',
+              'Use --json for noninteractive structured output; pipes and explicit formats also skip the picker.',
+              'Example: jsn records list --table incident --query "active=true" --limit 5 --json',
+              'Discover fields with: jsn columns --table incident',
+            ].join('\n')),
           handler: wrap(async (argv, app) => {
             const table = argv.table;
             const columns = argv.columns ? argv.columns.split(',') : getDefaultColumns(table);
@@ -187,7 +195,8 @@ export function recordsCmd(wrap) {
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
             .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
-            .option('attachments', { type: 'boolean', default: false, describe: 'Also list the record\'s attachments' }),
+            .option('attachments', { type: 'boolean', default: false, describe: 'Also list the record\'s attachments' })
+            .epilogue('Example: jsn records get --table incident --sys-id <sys_id> --json'),
           handler: wrap(async (argv, app) => {
             assertSafeExactMatch(argv['sys-id']);
             const params = new URLSearchParams();

package/src/commands/rest.js

@@ -10,6 +10,10 @@ export function restCmd(wrap) {
     describe: 'Make raw REST API calls',
     builder: (yargs) => {
       return yargs
+        .positional('endpoint', {
+          type: 'string',
+          describe: 'API path, optionally including query parameters; with --table, a record sys_id',
+        })
         .option('method', {
           alias: 'X',
           type: 'string',
@@ -34,7 +38,16 @@ export function restCmd(wrap) {
         .option('query', {
           type: 'string',
           describe: 'Query parameters string',
-        });
+        })
+        .epilogue([
+          'Prefer a specific jsn command or records for normal table operations.',
+          'Raw REST is blocked on read-only profiles for every method, including GET.',
+          'Examples:',
+          '  jsn rest "/api/now/table/incident?sysparm_limit=3" --json',
+          '  jsn rest --table incident --query "sysparm_limit=3" --json',
+          '  jsn rest /stats.do --raw',
+          'Use either query parameters in the endpoint or --query, rather than both.',
+        ].join('\n'));
     },
     handler: wrap(async (argv, app) => {
       const validMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];

package/src/commands/skill.js

@@ -119,9 +119,8 @@ function saveSkillConfig(updates) {
   fs.writeFileSync(globalConfigPath(), JSON.stringify(cfg, null, 2), { mode: 0o600 });
 }
 
-function recordSkillInstall(targetPath) {
-  const bundled = readBundledSkill();
-  const version = extractVersion(bundled) || 'unknown';
+function recordSkillInstall(targetPath, content) {
+  const version = extractVersion(content) || 'unknown';
   saveSkillConfig({
     skillLocation: targetPath,
     skillVersion: version,
@@ -260,7 +259,7 @@ export function skillCmd(wrap) {
         })
         .command({
           command: 'install [dir]',
-          describe: 'Download and save the latest skill file',
+          describe: 'Install the bundled skill matched to this CLI version',
           builder: (y) => y
             .positional('dir', {
               type: 'string',
@@ -271,9 +270,10 @@ export function skillCmd(wrap) {
               describe: 'Target agent(s): hermes, copilot, vscode, claude, cursor, agents, opencode, openclaw, codex, or "all" (comma-separated). Omit for interactive picker.',
             }),
           handler: wrap(async (argv, app) => {
-            const res = await fetch(SKILL_RAW_URL);
-            if (!res.ok) throw new Error(`Failed to fetch skill: ${res.status} ${res.statusText}`);
-            const content = await res.text();
+            const content = readBundledSkill();
+            if (!content) {
+              throw new Error('Skill file not found in package (expected at skills/servicenow/SKILL.md). Reinstall jsn to restore it.');
+            }
 
             // Resolve target directories
             let targets = [];
@@ -389,7 +389,7 @@ export function skillCmd(wrap) {
             }
 
             // Record install location so checkSkill knows where to look
-            recordSkillInstall(targets[0].path);
+            recordSkillInstall(targets[0].path, content);
 
             const installed = targets.reduce((acc, t) => { acc[t.name] = t.path; return acc; }, {});
             const summary = targets.length === 1
@@ -399,7 +399,7 @@ export function skillCmd(wrap) {
             const okOpts = {
               summary,
               breadcrumbs: [
-                { action: 'reinstall', cmd: 'jsn skill install', description: 'Re-download and reinstall to default target' },
+                { action: 'reinstall', cmd: 'jsn skill install', description: 'Reinstall the bundled skill to default target' },
               ],
             };
 
@@ -407,7 +407,7 @@ export function skillCmd(wrap) {
               okOpts.notice = 'Installed to multiple agents. Restart or reload your agent to pick up the skill.';
             }
 
-            app.ok({ installed, from: SKILL_RAW_URL }, okOpts);
+            app.ok({ installed, from: SKILL_REPO_PATH }, okOpts);
           }),
         });
     },

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.'],
     },
   };
 }