@jacebenson/jsn 4.3.8 → 4.3.9

package/README.md

@@ -44,6 +44,106 @@ private files and offers a foreground console, not native service registration.
 See [direct MID installation](docs/mid-direct-install.md) for security boundaries,
 lifecycle commands and the untested Windows host phases. Docker remains available.
 
+## Customization reports
+
+```sh
+jsn customizations capture --label before-upgrade --customer-scope x_acme_app
+jsn customizations list
+jsn customizations show <run_id>
+jsn customizations html <run_id>                 # writes customizations-<run_id>.html
+jsn customizations html <run_id> --out review.html
+jsn customizations compare <baseline_id> <new_id> --json
+jsn customizations show <run_id> --get data.coverage
+jsn customizations show <run_id> --get data.triage
+```
+
+Capture data access uses Table API GET requests only. Captures never run
+background scripts or create, update or delete instance records. Standard
+authentication still applies, including OAuth refresh, local refreshed-credential
+storage and session/GCK bootstrap, which can make authentication POST requests.
+Expired credentials without a usable refresh token require login. Reports are private local JSON files in
+`$JSN_DATA_HOME/customizations`, defaulting to `~/.jsn/customizations`. List,
+show and compare work offline. Interactive terminals offer local report pickers;
+pass explicit IDs with JSON, pipes or `--get`.
+
+The bounded inventory joins visible `sys_metadata`, `sys_scope` and
+`sys_upgrade_history_log` records. `ootb_modifications` contains artifacts
+with historical skipped-upgrade evidence, not a verified current OOTB diff.
+Because the broad `sys_metadata` read is an arbitrary `sys_id`-ordered slice
+(994 of 621972 rows on a large instance), it is reported as a **bounded sample,
+not an inventory**: it only ever describes the rows the page budget reached.
+The skipped-upgrade artifacts are inventoried separately and completely for the
+observed history: after the filtered upgrade-history read, every observed
+`sys_update_name` is resolved with chunked GET-only
+`sys_update_nameIN<chunk of names>` lookups on `sys_metadata`, so an artifact
+with skipped-upgrade evidence appears in `ootb_modifications` even when it falls
+far outside the sample. `coverage.upgrade_evidence` reports the skipped rows
+observed, the distinct update names, how many resolved by direct lookup, the
+unresolved name list and any failed lookup chunks.
+`customer_app_artifacts` contains only scopes explicitly declared with repeatable
+`--customer-scope` values or sys_ids. The instance verifies the scope identity,
+not its ownership. Installed/vendor scopes are never automatically called
+customer-built. Other visible artifacts remain `unclassified`, and both those
+categories cover only what the bounded sample read.
+
+Each item reports identity, scope, evidence, unknown risk with rationale and a
+review recommendation. Historical OOTB findings include the known skipped-upgrade
+impact and explicit unknown baseline, runtime impact and dependencies. No
+reversion is performed or recommended as safe without further investigation.
+
+`show` adds a computed `data.triage` view with evidence confidence, the reason for
+the classification and concrete review steps; it does not alter saved captures or
+pretend to score risk. `html` exports a self-contained offline report with search,
+classification filters, grouping, evidence, coverage and links back to records.
+The default output is `customizations-<run_id>.html`; existing files are never
+overwritten. The report does not change ServiceNow records.
+
+Defaults are 100 records per page and 10 pages per source. Adjust `--page-size`
+and `--max-pages` within the documented limits. Source coverage compares the rows
+fetched with the Stats API count for the same query and reports both. A page
+shorter than the requested size never implies exhaustion; `exhausted` is reported
+only when the fetched rows account for the available total, and an unavailable
+count is reported as unknown rather than implied completeness. Other statuses
+distinguish missing fields, unstable pagination and read failures. Both the count
+and the rows reflect visible ACL-filtered records, so hidden rows cannot be ruled
+out and reports remain `incomplete`. An empty category does not prove that no
+customizations exist. A 2xx table body without a `result` array is treated as an
+unavailable source, never as an empty table.
+
+Comparisons show newly observed, no-longer-observed and changed metadata/evidence.
+They ignore local capture IDs, labels, timestamps and enumeration order.
+They do not prove record creation/deletion or detect source-body changes without
+captured metadata changes. Changed entries render the concrete before/after field
+values, and additions/removals list the artifact's name, table, scope, category
+and evidence basis. When either report has an unavailable or empty source, the
+comparison status is `unreliable` and those differences are labelled as missing
+coverage instead of mass creation or deletion. Compare only reports from the same
+instance.
+
+Provider contract: [ServiceNow Customizations Unchanged](https://www.servicenow.com/docs/r/xanadu/platform-administration/customizations-unchanged-related-list.html)
+explains that the `Skipped` disposition preserves customizations. Other skip
+reasons are not treated as equivalent evidence. This command cannot establish a
+trusted baseline from that history alone.
+
+The verified provider join is `sys_upgrade_history_log.file_name` to
+`sys_metadata.sys_update_name`, not the log's nonexistent `name` field. Capture
+uses raw values from `sysparm_display_value=all`: disposition `4` or `104`
+means Skipped or Skipped (second pass). Resolution `reviewed_reverted` excludes
+that history row; a present empty resolution is distinct from a missing field.
+The upgrade-history read is filtered server-side to those dispositions so a
+bounded capture spends its pages on preserved-customization evidence instead of
+arbitrary history rows, and `unmatched_upgrade_records` counts only that filtered
+population, not all upgrade history. The filtered history is the unit of the
+inventory claim: every observed `file_name` is then resolved against visible
+`sys_metadata` with chunked GET-only `sys_update_nameIN<chunk>` lookups, so
+skipped artifacts are inventoried from the history instead of from the arbitrary
+`sys_id`-ordered metadata sample. `unmatched_upgrade_records` and
+`coverage.upgrade_evidence.unresolved_update_names` describe only names no
+visible metadata row matched; a failed lookup chunk is reported rather than
+treated as an absent artifact.
+These values were checked against the PDI dictionary, choices and actual joined
+rows. Display labels are not used for classification.
+
 ## Quick Start
 
 ```bash
@@ -107,6 +207,26 @@ jsn snippets run open-inc
 jsn logs follow --level error --tail 10
 ```
 
+### Update set completion
+
+```bash
+jsn updatesets complete                         # Current set, opens a notes editor in a human terminal
+jsn updatesets complete "My Feature" --notes "Fixed validation" --force --json
+```
+
+`complete [name]` saves concise bullet-list notes in the selected set's Description
+and marks it complete. Omit the name to use the current set. Explicit names
+must be unique; for duplicate names, select the intended set with `updatesets set`
+and complete it without a name. ServiceNow's normal batch completion rules still
+apply: completing a parent can complete its children. Notes are not copied to children.
+
+Existing Description text is preserved exactly. The command shows it and asks
+before appending notes, unless `--force` or the profile's `skip_confirmations`
+policy explicitly allows the append. Scripts and JSON output must supply
+nonempty `--notes`; they never open prompts. Separate multiple notes with real
+newlines. Success requires readback of both Description and state. If verification
+fails, inspect the set before retrying because the write may have partially succeeded.
+
 ### Flow Designer actions
 
 `actions` and `action` are the same command. `list`, `show`, and explicit
@@ -324,6 +444,8 @@ Run `jsn` for the full grouped list. Commands are organized by ServiceNow domain
 
 **Automation** — `flows`, `actions`, `rules`, `scrapi`, `updatesets`, `eval`, `rest`
 
+**Upgrade review** — [`skipped-updates`](docs/skipped-updates.md) discovers existing unresolved skips, reviews current/base field changes and known dependencies, and processes only explicitly selected actions after an exact batch preview and one confirmation.
+
 **Access** — `acls`, `roles`, `scopes`, `properties`, `privileges`
 
 **User Experience** — `forms`, `lists`, `clientscripts`, `uipolicies`, `uiactions`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.8",
+  "version": "4.3.9",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "main": "src/cli.js",
   "scripts": {
-    "test": "node --experimental-test-module-mocks --test --test-concurrency=1 $(find test -name '*.test.js')",
+    "test": "node --experimental-test-module-mocks --test --test-concurrency=4 $(find test -name '*.test.js')",
+    "test:mutation": "stryker run",
     "lint": "npx eslint src/ bin/ test/",
     "start": "node bin/jsn.js",
     "docs": "npm --prefix docs run build",
@@ -35,6 +36,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@stryker-mutator/core": "^10.0.0",
     "globals": "^17.6.0"
   },
   "files": [

package/skills/servicenow/SKILL.md

@@ -73,6 +73,60 @@ Pick the most specific tool for the job. **Never default to eval** — it's the
 | **Docs** | `docs sync`, `docs status`, `docs search`, `docs serve` |
 | **Developer** | `eval`, `rest`, `skill`, `version` |
 
+### Customization evidence
+
+```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
+```
+
+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.
+
+### Complete an update set
+
+```bash
+jsn updatesets complete "My Feature" --notes "Fixed validation" --force --json
+```
+
+`complete [name]` defaults to the current set when the name is omitted. Explicit
+names must be unique. Supply nonempty `--notes` in automation; real newlines
+separate bullets. A human terminal opens a notes editor when `--notes` is absent.
+Existing Description text is preserved and appended after confirmation. Use
+`--force` only after approval, or the profile's `skip_confirmations` policy.
+Notes apply only to the selected set. ServiceNow's normal batch rules can complete
+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

package/src/cli.js

@@ -9,6 +9,7 @@ import { App } from './app.js';
 import { resolveSession, applySession } from './session.js';
 import { renderHelp } from './help.js';
 import { isMutationCommand, refreshMutationCommands } from './mutations.js';
+import { skippedUpdatesCmd } from './commands/skipped-updates.js';
 import { noInstanceCommands, dailyCheckSkipCommands } from './capabilities.js';
 import { guardExit, exitWithError, AppError, CodeUsage } from './errors.js';
 import { formatCommandList } from './helpers.js';
@@ -70,6 +71,7 @@ import { b4rulesCmd } from './commands/b4rules.js';
 import { atfCmd } from './commands/atf.js';
 import { approvalsCmd } from './commands/approvals.js';
 import { perfCmd } from './commands/perf.js';
+import { customizationsCmd } from './commands/customizations.js';
 import { midserversCmd } from './commands/midservers.js';
 import { diffCmd } from './commands/diff.js';
 import { graphqlCmd } from './commands/graphql.js';
@@ -405,7 +407,9 @@ export function buildCLI() {
     // DEVELOPER
     .command(atfCmd(wrap))
     .command(approvalsCmd(wrap))
+    .command(skippedUpdatesCmd(wrap))
     .command(perfCmd(wrap))
+    .command(customizationsCmd(wrap))
     .command(midserversCmd(wrap))
     .command(diffCmd(wrap))
     .command(graphqlCmd(wrap))

package/src/commands/actions.js

@@ -9,8 +9,10 @@ import { cancelled, pickDesignerRecord, designerScope, guidedActionCreate, guide
 const ACTION_COMMANDS = [
   { name: 'list', description: 'List actions' },
   { name: 'show [identifier]', description: 'Show an action by name or sys_id' },
+  { name: 'help [identifier]', description: 'Show action input requirements and live usage examples' },
   { name: 'definition [identifier]', description: 'Read the full JSON definition including executable step_instances' },
   { name: 'step-types', description: 'Read step schema templates for a target scope' },
+  { name: 'action-type-schema', description: 'Read provider metadata for an exact action type ID and scope' },
   { name: 'create', description: 'Create an action: guided in a terminal, full JSON definition in scripts' },
   { name: 'update [identifier]', description: 'Save a full definition through Process Flow (alias: edit)' },
   { name: 'test [identifier]', description: 'Execute an action and optionally wait for actual outputs' },
@@ -28,6 +30,53 @@ async function actionID(argv, app) {
   return unwrapSysId(await resolveRecord(app.sdk, { table: ACTION_TABLE, identifier: argv.identifier, matchField: 'name', resource: 'action' }));
 }
 
+const refID = value => typeof value === 'string' ? value : value?.value ?? value?.sys_id ?? value?.sysId ?? value?.id;
+const asBoolean = value => value === true || value === 1 || (typeof value === 'string' && value.toLowerCase() === 'true');
+const EXAMPLE_TYPES = new Set(['approval_rules', 'conditions', 'schedule_date_time']);
+function collectActionExamples(node, snapshotId, allowedInputs, examples, flowName) {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node)) { for (const item of node) collectActionExamples(item, snapshotId, allowedInputs, examples, flowName); return; }
+  const typeId = refID(node.actionTypeSysId || node.action_type_sys_id || node.actionType || node.action_type);
+  if (typeId === snapshotId && Array.isArray(node.inputs)) {
+    const values = Object.fromEntries(node.inputs.filter(input => input?.name && allowedInputs.has(input.name) && input.value !== undefined && input.value !== null)
+      .map(input => [input.name, refID(input.value) ?? input.value]));
+    if (Object.keys(values).length) examples.push({ flow: flowName, inputs: values });
+  }
+  for (const [key, value] of Object.entries(node)) if (key !== 'inputs') collectActionExamples(value, snapshotId, allowedInputs, examples, flowName);
+}
+async function findActionExamples(sdk, definition, inputDefinitions) {
+  const snapshotId = refID(definition.latest_snapshot);
+  if (!/^[a-f0-9]{32}$/i.test(snapshotId || '')) return { examples: [], status: 'unavailable' };
+  const allowedInputs = new Set(inputDefinitions.filter(input => EXAMPLE_TYPES.has(input.type)
+    && !/(password|secret|token|credential|authorization|cookie|api[_-]?key)/i.test(input.name)).map(input => input.name));
+  if (!allowedInputs.size) return { examples: [], status: 'not_applicable' };
+  const query = new URLSearchParams({
+    sysparm_query: `action_type=${snapshotId}^ORDERBYsys_id`,
+    sysparm_fields: 'sys_id,flow,action_type',
+    sysparm_limit: '20',
+    sysparm_display_value: 'false',
+  });
+  const rows = await sdk.listStrict('sys_hub_action_instance', query);
+  if (!rows.length) return { examples: [], status: 'none' };
+  const flowIds = [...new Set(rows.map(row => refID(row.flow)).filter(value => /^[a-f0-9]{32}$/i.test(value || '')))];
+  if (!flowIds.length) return { examples: [], status: 'unavailable' };
+  const examples = [];
+  let unreadable = false;
+  for (const flowId of flowIds.slice(0, 10)) {
+    try {
+      const result = await sdk.inspectFlow(flowId);
+      const payloadActions = result?.payload?.actionInstances;
+      if (!Array.isArray(payloadActions) || !payloadActions.some(item => item && typeof item === 'object' && !Array.isArray(item))) {
+        unreadable = true;
+        continue;
+      }
+      collectActionExamples(result.payload, snapshotId, allowedInputs, examples, result?.flow?.name || flowId);
+    } catch { unreadable = true; }
+    if (examples.length >= 3) break;
+  }
+  return { examples: examples.slice(0, 3), status: examples.length ? 'found' : unreadable ? 'unavailable' : 'none' };
+}
+
 export const actionsCmd = wrap => {
   // Reuse the existing list/show picker and output contract only.
   const base = buildDevCmd('actions', ACTION_TABLE, ['action'], ['name', 'active', 'sys_scope', 'sys_updated_on'], wrap, {
@@ -55,7 +104,7 @@ export const actionsCmd = wrap => {
     describe: 'Flow Designer actions: create, edit full definitions, and test with outputs',
     builder: y => base.builder(y)
       .command({
-        command: 'create', describe: 'Create parent and executable Process Flow action; verify persistence',
+        command: 'create', describe: 'Create a Process Flow action. Use `jsn actions step-types --scope <sys_id>` for live provider schemas. The required definition structure is code-owned; step-specific fields are provider-defined.',
         builder: yy => dataOptions(yy).option('scope', { type: 'string', describe: 'Exact target scope sys_id, or global' }),
         handler: run(async (argv, app) => {
           const guided = !hasDefinitionData(argv) ? await guidedActionCreate(argv, app) : undefined;
@@ -65,6 +114,27 @@ export const actionsCmd = wrap => {
           app.ok(result, { summary: `Created and verified action ${result.sys_id}` });
         }),
       })
+      .command({
+        command: 'help [identifier]', describe: 'Show action input requirements and examples from flows on this instance',
+        builder: scopeOption,
+        handler: run(async (argv, app) => {
+          const id = await actionID(argv, app);
+          if (id === undefined) return;
+          const scope = await actionScope(app.sdk, id, argv.scope);
+          const definition = await app.sdk.getProcessFlowAction(id, scope);
+          const inputs = (definition.inputs || []).map(input => ({
+            name: input.name,
+            type: input.type || input.parameter?.type || input.parameter?.inputType || input.valueType || 'unknown',
+            mandatory: asBoolean(input.mandatory ?? input.required ?? input.parameter?.mandatory ?? input.parameter?.required),
+            default: input.defaultValue ?? input.default ?? input.parameter?.defaultValue ?? '',
+            description: input.description || input.label || input.parameter?.label || '',
+          }));
+          const exampleResult = await findActionExamples(app.sdk, definition, inputs);
+          app.ok({ action: { id, name: definition.name, scope }, inputs, examples: exampleResult.examples,
+            examples_status: exampleResult.status },
+          { summary: `Input help for action ${definition.name || id}` });
+        }),
+      })
       .command({
         command: 'definition [identifier]', describe: 'Read full JSON definition including executable step_instances',
         builder: scopeOption,
@@ -116,13 +186,30 @@ export const actionsCmd = wrap => {
         }),
       })
       .command({
-        command: 'step-types', describe: 'Read step schema templates for a target scope',
+        command: 'step-types', describe: 'Read full live step schemas for a target scope',
         builder: yy => yy.option('scope', { type: 'string', describe: 'Exact transaction scope sys_id, or global' }),
         handler: run(async (argv, app) => {
           const scope = await designerScope(argv, app);
           app.ok(await app.sdk.getProcessFlowStepTypes(scope), { summary: 'Process Flow step schemas' });
         }),
       })
+      .command({
+        command: 'action-type-schema', describe: 'Read live provider input/output metadata for an exact action type ID and scope',
+        builder: yy => yy.option('id', { type: 'string', demandOption: true, describe: 'Exact 32-character action type sys_id' }).option('scope', { type: 'string', demandOption: true, describe: 'Exact transaction scope sys_id, or global' }),
+        handler: run(async (argv, app) => {
+          if (!/^[a-f\d]{32}$/i.test(argv.id)) throw errUsage('--id must be an exact 32-character action type sys_id');
+          if (!/^(?:[a-fA-F0-9]{32}|global)$/.test(argv.scope)) throw errUsage('--scope must be an exact scope sys_id or global');
+          app.requireInstance();
+          const url = `${app.sdk.baseURL}/api/now/processflow/action/action_types/${encodeURIComponent(argv.id)}?${new URLSearchParams({ sysparm_transaction_scope: argv.scope })}`;
+          const response = await app.sdk.request(url, { method: 'GET' });
+          const result = response?.result;
+          if (response?.error || result?.error || (result?.errorCode !== undefined && result.errorCode !== 0 && result.errorCode !== '0')) {
+            throw new Error(result?.errorMessage || response?.error?.message || 'Provider rejected the action type schema request');
+          }
+          if (!result || typeof result !== 'object') throw new Error('Provider returned no action type metadata');
+          app.ok(result, { summary: `Provider action type schema ${argv.id}` });
+        }),
+      })
       .command({
         command: 'delete [identifier]', describe: 'Delete action parent explicitly',
         builder: yy => scopeOption(yy).option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),

package/src/commands/catalog.js

@@ -63,8 +63,8 @@ export function catalogCmd(wrap) {
               for (const v of argv.variable) {
                 const parts = String(v).split(':');
                 if (parts.length >= 2) {
-                  const typeName = parts.length >= 2 ? parts[parts.length - 1] : '';
-                  const label = parts.length >= 3 ? parts[parts.length - 1] : parts[0];
+                  const typeName = parts[1];
+                  const label = parts.length >= 3 ? parts.slice(2).join(':') : parts[0];
                   const sysName = parts[0].replace(/[^a-zA-Z0-9_]/g, '_').toLowerCase();
                   try {
                     await app.sdk.create('item_option_new', {

package/src/commands/customizations.js

@@ -0,0 +1,82 @@
+import { declareCapabilities } from '../capabilities.js';
+import { errUsageHint, errUsage } from '../errors.js';
+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';
+
+// Only capture needs an instance. Saved reports never need network access.
+declareCapabilities('customizations', { noInstance: true, skipDailyChecks: true, mutationSubcommands: [] });
+const listHint = { action: 'list', cmd: 'jsn customizations list', description: 'Browse saved customization captures' };
+const showHint = id => ({ action: 'show', cmd: `jsn customizations show ${id}`, description: 'Review this saved capture' });
+const compareHint = id => ({ action: 'compare', cmd: `jsn customizations compare ${id} OTHER_RUN_ID`, description: 'Compare captured metadata and evidence' });
+function requireReport(id) {
+  const report = getReport(id);
+  if (!report) throw errUsageHint(`Unknown customization report: ${id}`, 'Run `jsn customizations list` to find saved captures.');
+  return report;
+}
+async function pickReport(app, argv, exclude = null, message = 'Select a customization capture') {
+  if (!canUsePicker(app, argv)) throw errUsageHint('A report ID is required when prompts are unavailable.', 'Run `jsn customizations list`, then pass the run ID explicitly.');
+  const runs = listReports({ limit: 1000 }).filter(run => run.run_id !== exclude);
+  if (!runs.length) throw errUsage('No saved customization captures available');
+  const picked = await paginatedSearch({ message, totalCount: runs.length, pageSize: 10, source: async (term = '') => runs.filter(run => `${run.run_id} ${run.label} ${run.instance}`.toLowerCase().includes(term.toLowerCase())).map(run => ({ name: `${run.run_id} ${run.label || '(unlabeled)'} ${run.instance}`, value: run })) });
+  return picked?.value ? requireReport(picked.value.run_id) : null;
+}
+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)] });
+}
+export function customizationsCmd(wrap) {
+  return {
+    command: 'customizations [subcommand]',
+    describe: 'Capture and compare read-only customization evidence locally',
+    builder: y => y
+      .command({ command: 'capture', describe: 'Capture bounded read-only metadata and historical upgrade evidence',
+        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' }),
+        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');
+          const customerScopes = Array.isArray(argv.customerScope) ? argv.customerScope : argv.customerScope ? [argv.customerScope] : [];
+          const report = await captureReport({ sdk: app.sdk, instance: app.getEffectiveInstance(), profile: app.session?.profileName || '', label: argv.label || '', customerScopes, pageSize: argv.pageSize, maxPages: argv.maxPages });
+          show(app, report);
+        }),
+      })
+      .command({ command: 'list', aliases: ['ls'], describe: 'List saved local captures',
+        builder: b => b.option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Maximum captures to list' }),
+        handler: wrap(async (argv, app) => {
+          if (canUsePicker(app, argv)) { const report = await pickReport(app, argv); if (report) show(app, report); return; }
+          const runs = listReports({ limit: argv.limit });
+          app.ok({ runs, count: runs.length, _formatted: formatReportList(runs) }, { summary: `${runs.length} customization capture(s)`, breadcrumbs: [listHint, ...(runs[0] ? [showHint(runs[0].run_id)] : [])] });
+        }),
+      })
+      .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) => {
+        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) => {
+        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)] });
+      }) })
+      .command({ command: 'compare [baseline] [new]', describe: 'Compare two saved captures from the same instance', 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');
+        if (!baseline) return;
+        const newer = argv.new ? requireReport(argv.new) : await pickReport(app, argv, baseline.run_id, 'Select the new capture');
+        if (!newer) return;
+        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)] });
+      }) }),
+    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/flows.js

@@ -6,7 +6,7 @@ import { inspectFlow } from '../flow-inspection.js';
 import { publishFlows, publishFlowLifecycle, publishDoctor, flowStatus } from '../flow-publish.js';
 import { resolveRecord, unwrapSysId } from '../resolve-record.js';
 import { createFlowFromManifest, updateFlowFromManifest, readCurrentUpdateSet } from '../flow-create.js';
-import { EXCLUDED_TRIGGER_TYPES, SUPPORTED_TRIGGER_TYPES } from '../flow-triggers.js';
+import { EXCLUDED_TRIGGER_TYPES, SUPPORTED_TRIGGER_TYPES, readTriggerCatalog, readTriggerInputDefinitions } from '../flow-triggers.js';
 import { testFlow } from '../flow-test.js';
 import { errUsage } from '../errors.js';
 import { cancelled, pickDesignerRecord, guidedFlowCreate, guidedFlowEdit, guidedFlowTestRecord, hasDefinitionData, confirmDesignerMutation } from '../flow-designer-interactive.js';
@@ -63,6 +63,25 @@ export function flowsCmd(wrap) {
     describe: 'Manage Flow Designer flows',
     builder: (yargs) => {
       return yargs
+        .command({
+          command: 'schemas',
+          describe: 'Read live trigger catalog and declared inputs; supported marks verified CLI creation families',
+          handler: wrap(async (_argv, app) => {
+            app.requireInstance();
+            const catalog = await readTriggerCatalog(app.sdk);
+            for (const category of catalog.categories) {
+              for (const trigger of category.triggers) {
+                if (trigger.supported) trigger.inputs = await readTriggerInputDefinitions(app.sdk, trigger.sysId);
+              }
+            }
+            for (const trigger of catalog.ungrouped) {
+              if (trigger.supported) trigger.inputs = await readTriggerInputDefinitions(app.sdk, trigger.sysId);
+            }
+            const data = { ...catalog, structural_contract: 'Manifest keys and persistence shape are code-owned; trigger definitions and input metadata are instance-derived.' };
+            data._formatted = [...catalog.categories.flatMap(c => c.triggers.map(t => `${c.name}: ${t.name} [${t.type}] ${t.supported ? 'supported' : 'not supported'}; inputs: ${(t.inputs || []).map(i => i.name + ':' + i.type).join(', ')}`)), ...catalog.ungrouped.map(t => `${t.name} [${t.type}] ungrouped${t.supported ? '; supported' : '; not supported'}; inputs: ${(t.inputs || []).map(i => i.name + ':' + i.type).join(', ')}`)].join('\n');
+            app.ok(data, { summary: 'Live Flow trigger schemas' });
+          }),
+        })
         .command({
           command: 'list',
           aliases: ['ls'],
@@ -294,7 +313,7 @@ export function flowsCmd(wrap) {
         })
         .command({
           command: 'create',
-          describe: 'Create a draft flow: pick a trigger category then trigger in a terminal, or use a JSON manifest in scripts',
+          describe: 'Create a draft flow from a JSON manifest or guided prompts. Use `jsn flows schemas` for instance-derived trigger and input schemas, and `jsn actions action-type-schema --id <actionTypeId> --scope <scopeId>` for provider action inputs. Manifest structure remains code-owned.',
           builder: (y) => y
             .option('data', { type: 'string', describe: 'Flow manifest as inline JSON' })
             .option('data-file', { type: 'string', describe: 'Read the flow manifest from a JSON file' })
@@ -322,7 +341,7 @@ export function flowsCmd(wrap) {
         .command({
           command: 'update [identifier]',
           aliases: ['edit'],
-          describe: 'Safely update supported fields of an existing inactive Draft flow',
+          describe: 'Safely update an inactive Draft flow from a partial JSON manifest. Use `jsn flows schemas` for live trigger inputs and `jsn actions action-type-schema --id <actionTypeId> --scope <scopeId>` for provider action inputs. Manifest structure remains code-owned; omitted values are preserved.',
           builder: (y) => y
             .option('data', { type: 'string', describe: 'Update manifest as inline JSON' })
             .option('data-file', { type: 'string', describe: 'Read the update manifest from a JSON file' })