@jacebenson/jsn 4.3.13-dev.83.1 → 4.3.13-dev.84.1

package/package.json

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

package/src/commands/_generic.js

@@ -1,7 +1,8 @@
 // Generic table-based CRUD command builder
 
 import { formatRecordForDisplay, getStringField, buildRecordPayload, confirmDelete, interactiveList, canPrompt } from '../helpers.js';
-import { resolveRecord, unwrapSysId } from '../resolve-record.js';
+import { getRecord, listRecords, recordListParams, createRecord, updateRecord, deleteRecord, recordOptions } from '../records-engine.js';
+import { unwrapSysId } from '../resolve-record.js';
 import { getCurrentUser, getCurrentApplication } from '../context.js';
 import { FormatAuto } from '../output.js';
 import { declareCapabilities } from '../capabilities.js';
@@ -120,7 +121,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         command: 'list',
         aliases: ['ls'],
         describe: `List ${name}`,
-        builder: (y) => y
+        builder: (y) => recordOptions(y)
           .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true^priority=1")' })
           .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "name,label,super_class")' })
           .option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Max records' }),
@@ -147,7 +148,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
             const recordName = getStringField(record, 'name') || getStringField(record, 'sys_id');
             record._context = { instance_url: app.getEffectiveInstance(), table };
             if (opts.onShow) {
-              await opts.onShow(record, app);
+              await opts.onShow(record, app, argv);
             }
             app.ok(record, {
               summary: `${singular.charAt(0).toUpperCase() + singular.slice(1)}: ${recordName}`,
@@ -160,19 +161,15 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
           }
 
           // Non-interactive: text/table output
-          const params = new URLSearchParams();
-          params.set('sysparm_limit', String(limit));
-          params.set('sysparm_display_value', 'all');
-          params.set('sysparm_fields', ['sys_id', ...columns].join(','));
           const baseQ = extraQuery ? extraQuery + '^' : '';
           const q = query ? query + '^ORDERBYDESCsys_updated_on' : (baseQ + 'ORDERBYDESCsys_updated_on');
-          params.set('sysparm_query', q);
-          const records = await app.sdk.list(table, params);
+          const params = recordListParams({ limit, fields: ['sys_id', ...columns], query: q });
+          const records = await listRecords(app.sdk, { table, params, displayValues: argv.displayValues ?? opts.referenceMode });
           app.ok({
             table,
             count: records.length,
             columns,
-            records: records.map(r => formatRecordForDisplay(r, columns)),
+            records: argv.displayValues || opts.listProjection === 'full' ? records : records.map(r => formatRecordForDisplay(r, columns)),
             context: { instance_url: app.getEffectiveInstance() },
           }, {
             summary: `${records.length} ${name}(s)`,
@@ -184,6 +181,11 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         command: opts.resolveIdentifier ? 'show [identifier]' : 'show <identifier>',
         aliases: ['get'],
         describe: `Show ${vowelArticle(singular)} ${singular} by name or sys_id`,
+        builder: y => {
+          const command = recordOptions(y);
+          return opts.relationships?.essential?.length ? command.option('essential', { type: 'boolean', default: true,
+            describe: 'Fetch profile-declared essential children; --no-essential skips them. Supplementary lists remain lazy.' }) : command;
+        },
         handler: wrap(async (argv, app) => {
           const id = opts.resolveIdentifier ? await opts.resolveIdentifier(argv, app) : argv.identifier;
           if (id === undefined) return;
@@ -192,14 +194,14 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
           const fields = (showFields && showFields.length > 0)
             ? [...new Set(['sys_id', ...showFields])]
             : undefined;
-          const record = await resolveRecord(app.sdk, { table, identifier: id, matchField: 'name', resource: singular, fields });
+          const record = await getRecord(app.sdk, { table, identifier: id, identifierField: argv.identifierField, displayValues: argv.displayValues ?? opts.referenceMode, matchField: opts.identifierField || 'name', resource: singular, fields });
           record._context = {
             instance_url: app.getEffectiveInstance(),
             table,
           };
 
           if (opts.onShow) {
-            await opts.onShow(record, app);
+            await opts.onShow(record, app, argv);
           }
 
           const summary = typeof showSummary === 'function' ? showSummary(record, id) : showSummary;
@@ -214,14 +216,14 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         .command({
           command: 'create',
           describe: `Create a new ${singular}`,
-          builder: (y) => y
+          builder: (y) => recordOptions(y, false)
             .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
             .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const recordData = buildRecordPayload(argv);
-            const record = await app.sdk.create(table, recordData);
+            const record = await createRecord(app.sdk, { table, data: recordData });
             app.ok(record, {
               summary: `Created ${singular}`,
               breadcrumbs: [
@@ -233,31 +235,31 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         .command({
           command: 'update <identifier>',
           describe: `Update ${vowelArticle(singular)} ${singular}`,
-          builder: (y) => y
+          builder: (y) => recordOptions(y, false)
             .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
             .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
-            const record = await resolveRecord(app.sdk, { table, identifier: id, matchField: 'name', resource: singular });
+            const record = await getRecord(app.sdk, { table, identifier: id, identifierField: argv.identifierField, displayValues: argv.displayValues ?? opts.referenceMode, matchField: opts.identifierField || 'name', resource: singular });
             if (scopeValidation) {
               await guardScope(app.sdk, record);
             }
 
             const sysID = unwrapSysId(record);
             const recordData = buildRecordPayload(argv);
-            const updated = await app.sdk.update(table, sysID, recordData);
+            const updated = await updateRecord(app.sdk, { table, record: { sys_id: sysID }, data: recordData });
             app.ok(updated, { summary: `Updated ${singular} ${id}` });
           }),
         })
         .command({
           command: 'delete <identifier>',
           describe: `Delete ${vowelArticle(singular)} ${singular}`,
-          builder: (y) => y.option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
+          builder: (y) => recordOptions(y, false).option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
-            const record = await resolveRecord(app.sdk, { table, identifier: id, matchField: 'name', resource: singular });
+            const record = await getRecord(app.sdk, { table, identifier: id, identifierField: argv.identifierField, displayValues: argv.displayValues ?? opts.referenceMode, matchField: opts.identifierField || 'name', resource: singular });
             if (scopeValidation) {
               await guardScope(app.sdk, record);
             }
@@ -267,7 +269,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
 
             await confirmDelete(app, argv, `Delete ${singular} '${recordName}'`);
 
-            await app.sdk.delete(table, sysID);
+            await deleteRecord(app.sdk, { table, record: { sys_id: sysID } });
             app.ok({ name: recordName, sys_id: sysID, deleted: true }, { summary: `Deleted ${singular} '${recordName}'` });
           }),
         });

package/src/commands/_simple.js

@@ -1,4 +1,4 @@
-import { buildDevCmd } from './_generic.js';
+import { buildProfileCommand } from '../record-profiles.js';
 import { getStringField } from '../helpers.js';
 // Simple table-based commands — singular names passed for grammar
 // Default columns and aliases match the Go version exactly
@@ -47,13 +47,13 @@ async function fetchExtensionChain(sdk, record) {
 
 export { actionsCmd } from './actions.js';
 
-export const includesCmd = (wrap) => buildDevCmd('includes', 'sys_script_include', ['include', 'si'], ['name', 'api_name', 'active', 'sys_scope'], wrap, { singular: 'script include', scopeValidation: true });
+export const includesCmd = (wrap) => buildProfileCommand('includes', wrap);
 
-export const rulesCmd = (wrap) => buildDevCmd('rules', 'sys_script', ['rule', 'br'], ['name', 'collection', 'active', 'order', 'sys_scope'], wrap, { singular: 'business rule', scopeValidation: true });
+export const rulesCmd = (wrap) => buildProfileCommand('rules', wrap);
 
-export const clientScriptsCmd = (wrap) => buildDevCmd('clientscripts', 'sys_script_client', ['clientscript', 'cs'], ['name', 'table', 'active', 'type', 'sys_scope'], wrap, { singular: 'client script', scopeValidation: true });
+export const clientScriptsCmd = (wrap) => buildProfileCommand('clientscripts', wrap);
 
-export const uiActionsCmd = (wrap) => buildDevCmd('uiactions', 'sys_ui_action', ['uiaction', 'ua'], ['name', 'table', 'active', 'order', 'sys_scope'], wrap, { singular: 'UI action', scopeValidation: true });
+export const uiActionsCmd = (wrap) => buildProfileCommand('uiactions', wrap);
 
 // NOTE: uipolicies has exactly ONE definition — the rich one in
 // ./uipolicies.js (re-exported below at the bottom of this file). A plain
@@ -62,10 +62,7 @@ export const uiActionsCmd = (wrap) => buildDevCmd('uiactions', 'sys_ui_action',
 // this module's uiPoliciesCmd before uipoliciesCmd — so the factory version
 // was dead code shadowing nothing. Deleted; the re-export is the behavior.
 
-export const tablesCmd = (wrap) => buildDevCmd('tables', 'sys_db_object', ['table', 't'], ['name', 'label', 'super_class', 'create_access_controls'], wrap, {
-  singular: 'table',
-  scopeValidation: true,
-  showFields: ['name', 'label', 'super_class', 'create_access_controls', 'sys_scope', 'sys_created_on', 'sys_updated_on', 'sys_created_by', 'sys_updated_by', 'is_extendable'],
+export const tablesCmd = (wrap) => buildProfileCommand('tables', wrap, {
   async onShow(record, app) {
     const tableName = getStringField(record, 'name');
     const [count, extChain] = await Promise.all([
@@ -81,48 +78,48 @@ export { columnsCmd } from './columns.js';
 
 // Read-only commands (Go only has list/show)
 export { importCmd } from './import.js';
-export const spPagesCmd = (wrap) => buildDevCmd('sppages', 'sp_page', ['sp-pages'], ['id', 'title', 'sys_scope'], wrap, { singular: 'Service Portal page', readOnly: true });
-export const spWidgetsCmd = (wrap) => buildDevCmd('spwidgets', 'sp_widget', ['sp-widget', 'widgets'], ['id', 'name', 'sys_scope'], wrap, { singular: 'Service Portal widget', readOnly: true });
-export const uiPagesCmd = (wrap) => buildDevCmd('uipages', 'sys_ui_page', ['ui-page', 'pages'], ['name', 'sys_scope'], wrap, { singular: 'UI page', scopeValidation: true });
-export const appMenuCmd = (wrap) => buildDevCmd('appmenu', 'sys_app_application', ['app-menu', 'menu'], ['name', 'active', 'sys_scope'], wrap, { singular: 'application menu', scopeValidation: true });
+export const spPagesCmd = (wrap) => buildProfileCommand('sppages', wrap);
+export const spWidgetsCmd = (wrap) => buildProfileCommand('spwidgets', wrap);
+export const uiPagesCmd = (wrap) => buildProfileCommand('uipages', wrap);
+export const appMenuCmd = (wrap) => buildProfileCommand('appmenu', wrap);
 
 // Commands with full CRUD
-export const aclsCmd = (wrap) => buildDevCmd('acls', 'sys_security_acl', ['acl'], ['name', 'operation', 'type', 'active', 'sys_scope'], wrap, { singular: 'ACL', scopeValidation: true });
-export const rolesCmd = (wrap) => buildDevCmd('roles', 'sys_user_role', ['role', 'r'], ['name', 'description', 'elevated_privilege', 'sys_scope'], wrap, { singular: 'role', scopeValidation: true });
-export const propertiesCmd = (wrap) => buildDevCmd('properties', 'sys_properties', ['property', 'prop'], ['name', 'value', 'description', 'sys_scope'], wrap, { singular: 'property', scopeValidation: true });
+export const aclsCmd = (wrap) => buildProfileCommand('acls', wrap);
+export const rolesCmd = (wrap) => buildProfileCommand('roles', wrap);
+export const propertiesCmd = (wrap) => buildProfileCommand('properties', wrap);
 
 // New commands for scoped-app tables
-export const relationshipsCmd = (wrap) => buildDevCmd('relationships', 'sys_relationship', ['relationship', 'rel'], ['name', 'sys_scope'], wrap, { singular: 'relationship', scopeValidation: true });
-export const appmodulesCmd = (wrap) => buildDevCmd('appmodules', 'sys_app_module', ['appmodule', 'am'], ['name', 'active', 'sys_scope'], wrap, { singular: 'application module', scopeValidation: true });
-export const listcontrolsCmd = (wrap) => buildDevCmd('listcontrols', 'sys_ui_list_control', ['listcontrol', 'lc'], ['name', 'active', 'sys_scope'], wrap, { singular: 'list control', scopeValidation: true });
-export const viewsCmd = (wrap) => buildDevCmd('views', 'sys_ui_view', ['view', 'vw'], ['name', 'title', 'sys_scope'], wrap, { singular: 'view', scopeValidation: true });
-export const privilegesCmd = (wrap) => buildDevCmd('privileges', 'sys_scope_privilege', ['privilege', 'priv'], ['source_scope', 'target_scope', 'target_name', 'operation', 'status'], wrap, { singular: 'privilege', scopeValidation: true });
-export const uxscriptsCmd = (wrap) => buildDevCmd('uxscripts', 'sys_ux_lib_source_script', ['uxscript', 'ux'], ['name', 'active', 'sys_scope'], wrap, { singular: 'UX script', scopeValidation: true });
+export const relationshipsCmd = (wrap) => buildProfileCommand('relationships', wrap);
+export const appmodulesCmd = (wrap) => buildProfileCommand('appmodules', wrap);
+export const listcontrolsCmd = (wrap) => buildProfileCommand('listcontrols', wrap);
+export const viewsCmd = (wrap) => buildProfileCommand('views', wrap);
+export const privilegesCmd = (wrap) => buildProfileCommand('privileges', wrap);
+export const uxscriptsCmd = (wrap) => buildProfileCommand('uxscripts', wrap);
 export { aliasesCmd } from './aliases.js';
-export const catalogscriptsCmd = (wrap) => buildDevCmd('catalogscripts', 'catalog_script_client', ['catalogscript'], ['name', 'table', 'active', 'sys_scope'], wrap, { singular: 'catalog script', scopeValidation: true });
+export const catalogscriptsCmd = (wrap) => buildProfileCommand('catalogscripts', wrap);
 
 // ── Automation: Async ──
-export const scriptactionsCmd = (wrap) => buildDevCmd('scriptactions', 'sysevent_script_action', ['scriptaction'], ['name', 'active', 'sys_scope'], wrap, { singular: 'script action', scopeValidation: true });
-export const scheduledjobsCmd = (wrap) => buildDevCmd('scheduledjobs', 'sysauto_script', ['scheduledjob'], ['name', 'active', 'run_type', 'sys_scope'], wrap, { singular: 'scheduled job', scopeValidation: true });
-export const asyncrulesCmd = (wrap) => buildDevCmd('asyncrules', 'sys_script', ['asyncrule'], ['name', 'collection', 'active', 'order', 'sys_scope'], wrap, { singular: 'async business rule', scopeValidation: true, extraQuery: 'when=async' });
-export const triggersCmd = (wrap) => buildDevCmd('triggers', 'sysevent_register', ['trigger'], ['name', 'event_name', 'active', 'sys_scope'], wrap, { singular: 'event trigger', scopeValidation: true });
+export const scriptactionsCmd = (wrap) => buildProfileCommand('scriptactions', wrap);
+export const scheduledjobsCmd = (wrap) => buildProfileCommand('scheduledjobs', wrap);
+export const asyncrulesCmd = (wrap) => buildProfileCommand('asyncrules', wrap);
+export const triggersCmd = (wrap) => buildProfileCommand('triggers', wrap);
 
 // ── Automation: In Memory ──
 
-export const assignmentsCmd = (wrap) => buildDevCmd('assignments', 'sysrule_assignment', ['assignment'], ['name', 'active', 'sys_scope'], wrap, { singular: 'assignment rule', scopeValidation: true, readOnly: true });
+export const assignmentsCmd = (wrap) => buildProfileCommand('assignments', wrap);
 
 // ── Automation: Inbound ──
-export const emailCmd = (wrap) => buildDevCmd('email', 'sysevent_in_email_action', ['emails'], ['name', 'active', 'type', 'sys_scope'], wrap, { singular: 'inbound email action', scopeValidation: true });
+export const emailCmd = (wrap) => buildProfileCommand('email', wrap);
 
 // ── Automation: Outbound ──
 export { restmessageCmd } from './restmessage.js';
 export { soapmessagesCmd } from './soapmessages.js';
 
 // ── UX: Core UI ──
-export const uimacrosCmd = (wrap) => buildDevCmd('uimacros', 'sys_ui_macro', ['uimacro'], ['name', 'active', 'sys_scope'], wrap, { singular: 'UI macro', scopeValidation: true });
+export const uimacrosCmd = (wrap) => buildProfileCommand('uimacros', wrap);
 
 // ── UX: Workspaces ──
-export const uxlistsCmd = (wrap) => buildDevCmd('uxlists', 'sys_ux_list', ['uxlist'], ['name', 'active', 'sys_scope'], wrap, { singular: 'workspace list', scopeValidation: true, readOnly: true });
-export const uxapplicabilityCmd = (wrap) => buildDevCmd('uxapplicability', 'sys_ux_applicability_m2m', ['uxapp'], ['name', 'active', 'sys_scope'], wrap, { singular: 'workspace applicability', scopeValidation: true, readOnly: true });
+export const uxlistsCmd = (wrap) => buildProfileCommand('uxlists', wrap);
+export const uxapplicabilityCmd = (wrap) => buildProfileCommand('uxapplicability', wrap);
 export { uipoliciesCmd } from './uipolicies.js';
-export const cataloguipoliciesCmd = (wrap) => buildDevCmd('cataloguipolicies', 'catalog_ui_policy', ['cataloguipolicy', 'cup'], ['short_description', 'catalog_item', 'variable_set', 'active', 'sys_scope'], wrap, { singular: 'catalog UI policy', scopeValidation: true });
+export const cataloguipoliciesCmd = (wrap) => buildProfileCommand('cataloguipolicies', wrap);

package/src/commands/_ticket.js

@@ -2,11 +2,12 @@
 // Used by incidents, changes, requests, tasks, and most dev subcommands
 
 import { getStringField, formatRecordForDisplay, buildQuerySuffix, resolveFieldsParam, confirmDelete, interactiveList, canPrompt, buildRecordPayload } from '../helpers.js';
-import { resolveRecord, resolveSysId } from '../resolve-record.js';
+import { getRecord, listRecords, recordListParams, createRecord, updateRecord, deleteRecord, recordOptions } from '../records-engine.js';
+import { resolveSysId } from '../resolve-record.js';
 import { FormatAuto } from '../output.js';
 import { declareCapabilities } from '../capabilities.js';
 
-export function buildTicketCommands(table, displayName, alias, defaultColumns, stateMap, iconFn, wrap) {
+export function buildTicketCommands(table, displayName, alias, defaultColumns, stateMap, iconFn, wrap, opts = {}) {
   // Ticket-style CRUD: list/show are reads; create/update/delete mutate.
   // Root-level command only.
   declareCapabilities(displayName, { mutationSubcommands: ['create', 'update', 'delete'] });
@@ -21,7 +22,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
           command: 'list',
           aliases: ['ls'],
           describe: `List ${table}`,
-          builder: (y) => y
+          builder: (y) => recordOptions(y)
             .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true")' })
             .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' })
@@ -81,17 +82,12 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
               return;
             }
 
-            const params = new URLSearchParams();
-            params.set('sysparm_limit', String(limit));
-            params.set('sysparm_offset', String(offset));
-            params.set('sysparm_display_value', 'all');
             const fields = resolveFieldsParam(columns);
-            if (fields) params.set('sysparm_fields', fields);
             const q = query ? query + '^ORDERBYDESCsys_updated_on' : 'ORDERBYDESCsys_updated_on';
-            params.set('sysparm_query', q);
+            const params = recordListParams({ limit, offset, fields, query: q });
 
-            const records = await app.sdk.list(table, params);
-            const displayRecords = fields ? records.map(r => formatRecordForDisplay(r, columns)) : records;
+            const records = await listRecords(app.sdk, { table, params, displayValues: argv.displayValues ?? opts.referenceMode });
+            const displayRecords = fields && !argv.displayValues && opts.listProjection !== 'full' ? records.map(r => formatRecordForDisplay(r, columns)) : records;
 
             const breadcrumbs = [
               { action: 'create', cmd: `jsn ${alias} create --description "..."`, description: `Create a new ${displayName}` },
@@ -130,9 +126,14 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
           command: 'show <number>',
           aliases: ['get'],
           describe: `Show a specific ${displayName}`,
+          builder: y => {
+            const command = recordOptions(y);
+            return opts.relationships?.essential?.length ? command.option('essential', { type: 'boolean', default: true, describe: 'Fetch declared essential children; use --no-essential to skip' }) : command;
+          },
           handler: wrap(async (argv, app) => {
             const number = argv.number;
-            const record = await resolveRecord(app.sdk, { table, identifier: number, matchField: 'number', resource: displayName });
+            const record = await getRecord(app.sdk, { table, identifier: number, identifierField: argv.identifierField, displayValues: argv.displayValues ?? opts.referenceMode, matchField: opts.identifierField || 'number', resource: displayName });
+            if (opts.onShow) await opts.onShow(record, app, argv);
             record._context = {
               instance_url: app.getEffectiveInstance(),
               table,
@@ -149,7 +150,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
         .command({
           command: 'create',
           describe: `Create a new ${displayName}`,
-          builder: (y) => y
+          builder: (y) => recordOptions(y, false)
             .option('description', { alias: 'd', type: 'string', describe: 'Short description' })
             .option('priority', { type: 'string', describe: 'Priority (1-5)' })
             .option('data', { type: 'string', describe: 'JSON data for additional fields' })
@@ -163,7 +164,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
             if (!recordData.short_description) {
               throw new Error('short_description is required (use --description, -f short_description=..., or --data)');
             }
-            const record = await app.sdk.create(table, recordData);
+            const record = await createRecord(app.sdk, { table, data: recordData });
             app.ok(record, {
               summary: `Created ${displayName} ${getStringField(record, 'number')}`,
               breadcrumbs: [
@@ -175,7 +176,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
         .command({
           command: 'update <number>',
           describe: `Update a ${displayName}`,
-          builder: (y) => y
+          builder: (y) => recordOptions(y, false)
             .option('data', { type: 'string', describe: 'JSON data to update' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
@@ -183,8 +184,8 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
           handler: wrap(async (argv, app) => {
             const number = argv.number;
             const recordData = buildRecordPayload(argv);
-            const sysID = await resolveSysId(app.sdk, { table, identifier: number, matchField: 'number', resource: displayName });
-            const updated = await app.sdk.update(table, sysID, recordData);
+            const sysID = await resolveSysId(app.sdk, { table, identifier: number, identifierField: argv.identifierField, displayValues: argv.displayValues ?? opts.referenceMode, matchField: opts.identifierField || 'number', resource: displayName });
+            const updated = await updateRecord(app.sdk, { table, record: { sys_id: sysID }, data: recordData });
             app.ok(updated, {
               summary: `Updated ${displayName} ${number}`,
               breadcrumbs: [
@@ -196,12 +197,12 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
         .command({
           command: 'delete <number>',
           describe: `Delete a ${displayName}`,
-          builder: (y) => y.option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
+          builder: (y) => recordOptions(y, false).option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
           handler: wrap(async (argv, app) => {
             const number = argv.number;
             await confirmDelete(app, argv, `Delete ${displayName} ${number}`);
-            const sysID = await resolveSysId(app.sdk, { table, identifier: number, matchField: 'number', resource: displayName });
-            await app.sdk.delete(table, sysID);
+            const sysID = await resolveSysId(app.sdk, { table, identifier: number, identifierField: argv.identifierField, displayValues: argv.displayValues ?? opts.referenceMode, matchField: opts.identifierField || 'number', resource: displayName });
+            await deleteRecord(app.sdk, { table, record: { sys_id: sysID } });
             app.ok({ number, message: `${displayName.charAt(0).toUpperCase() + displayName.slice(1)} deleted` }, {
               summary: `Deleted ${displayName} ${number}`,
             });

package/src/commands/changes.js

@@ -1,7 +1,5 @@
-import { buildTicketCommands } from './_ticket.js';
-
-const changeDefaultColumns = ['number', 'short_description', 'risk', 'state', 'assigned_to'];
+import { buildProfileCommand } from '../record-profiles.js';
 
 export function changesCmd(wrap) {
-  return buildTicketCommands('change_request', 'changes', 'chg', changeDefaultColumns, {}, null, wrap);
+  return buildProfileCommand('changes', wrap);
 }

package/src/commands/incidents.js

@@ -1,7 +1,5 @@
-import { buildTicketCommands } from './_ticket.js';
-
-const incidentDefaultColumns = ['number', 'short_description', 'priority', 'state', 'assigned_to'];
+import { buildProfileCommand } from '../record-profiles.js';
 
 export function incidentsCmd(wrap) {
-  return buildTicketCommands('incident', 'incidents', 'inc', incidentDefaultColumns, {}, null, wrap);
+  return buildProfileCommand('incidents', wrap);
 }

package/src/commands/records.js

@@ -1,6 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, buildRecordPayload, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
+import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, buildRecordPayload, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, verifyWriteBack } from '../helpers.js';
+import { listRecords, recordListParams, getRecord, createRecord, updateRecord, deleteRecord } from '../records-engine.js';
+import { unwrapSysId } from '../resolve-record.js';
+import { errUsage } from '../errors.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('records', {
@@ -67,6 +70,15 @@ function getDefaultColumns(table) {
   return tableDefaultColumns[table] || ['sys_id'];
 }
 
+function recordLookup(argv) {
+  const sysId = argv['sys-id'];
+  if ((sysId === undefined) === (argv.identifier === undefined)) throw errUsage('Supply exactly one of --sys-id or --identifier.');
+  if (sysId !== undefined && argv.identifierField && argv.identifierField !== 'sys_id') throw errUsage('--sys-id cannot be combined with a different --identifier-field.');
+  return { table: argv.table, identifier: sysId ?? argv.identifier,
+    identifierField: sysId !== undefined ? 'sys_id' : (argv.identifierField || 'sys_id'),
+    displayValues: argv.displayValues, resource: 'Record' };
+}
+
 export function recordsCmd(wrap) {
   return {
     command: 'records [subcommand]',
@@ -83,6 +95,7 @@ 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('display-values', { type: 'string', choices: ['raw', 'display', 'both'], describe: 'Reference values: raw, display or both' })
             .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).',
@@ -130,15 +143,10 @@ export function recordsCmd(wrap) {
             }
 
             // Text/table fallback (or sys-id direct lookup)
-            const params = new URLSearchParams();
-            params.set('sysparm_limit', argv['sys-id'] ? '1' : String(argv.limit));
-            params.set('sysparm_offset', String(argv.offset));
-            params.set('sysparm_display_value', 'all');
             const fields = resolveFieldsParam(columns);
-            if (fields) params.set('sysparm_fields', fields);
-            if (query) params.set('sysparm_query', query);
-            const records = await app.sdk.list(table, params);
-            const displayRecords = fields ? records.map(r => formatRecordForDisplay(r, columns)) : records;
+            const params = recordListParams({ limit: argv['sys-id'] ? 1 : argv.limit, offset: argv.offset, fields, query });
+            const records = await listRecords(app.sdk, { table, params, displayValues: argv.displayValues });
+            const displayRecords = fields && !argv.displayValues ? records.map(r => formatRecordForDisplay(r, columns)) : records;
 
             // include_counts: default opt-in on every list. Opt out per-profile
             // (config include_counts:false) or per-invocation (--no-count).
@@ -190,28 +198,23 @@ export function recordsCmd(wrap) {
         })
         .command({
           command: 'get',
-          describe: 'Get a single record by sys_id',
+          describe: 'Get one record by sys_id or an explicit identifier field',
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
-            .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
+            .option('sys-id', { type: 'string', describe: 'Full or unambiguous partial record sys_id (including legacy IDs)' })
+            .option('identifier', { type: 'string', describe: 'Identifier value; use --identifier-field number/name/etc for human identifiers' })
+            .option('identifier-field', { type: 'string', describe: 'Exact identifier field (default sys_id); disambiguates names and legacy sys_ids' })
+            .option('display-values', { type: 'string', choices: ['raw', 'display', 'both'], describe: 'Reference values: raw, display or both' })
             .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' })
-            .epilogue('Example: jsn records get --table incident --sys-id <sys_id> --json'),
+            .epilogue('Exact lookup precedes sys_id prefix, then suffix. Ambiguous matches fail.\nExample: jsn records get --table incident --sys-id <sys_id> --json\nExample: jsn records get --table incident --identifier INC0010001 --identifier-field number --json'),
           handler: wrap(async (argv, app) => {
-            assertSafeExactMatch(argv['sys-id']);
-            const params = new URLSearchParams();
-            params.set('sysparm_query', `sys_id=${argv['sys-id']}`);
-            params.set('sysparm_limit', '1');
-            params.set('sysparm_display_value', 'true');
-            if (argv.columns && argv.columns !== '*') params.set('sysparm_fields', `sys_id,${argv.columns}`);
-            const records = await app.sdk.list(argv.table, params);
-            if (records.length === 0) {
-              throw new Error(`Record not found: ${argv['sys-id']}`);
-            }
-            const record = records[0];
+            const lookup = recordLookup(argv);
+            const fields = argv.columns && argv.columns !== '*' ? argv.columns.split(',') : undefined;
+            const record = await getRecord(app.sdk, { ...lookup, fields, displayValue: 'true' });
             if (argv.attachments) {
               try {
-                const atts = await app.sdk.listAttachments(argv['sys-id']);
+                const atts = await app.sdk.listAttachments(unwrapSysId(record));
                 record._attachments = atts;
               } catch {
                 record._attachments = [];
@@ -241,7 +244,7 @@ export function recordsCmd(wrap) {
             for (const w of warnings) {
               process.stderr.write(`⚠ ${w.hint}\n`);
             }
-            const record = await app.sdk.create(argv.table, recordData);
+            const record = await createRecord(app.sdk, { table: argv.table, data: recordData });
             const sysID = getStringField(record, 'sys_id');
             const mismatches = await verifyWriteBack(app, argv.table, sysID, recordData);
             for (const m of mismatches) {
@@ -258,7 +261,9 @@ export function recordsCmd(wrap) {
           describe: 'Update an existing record',
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
-            .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
+            .option('sys-id', { type: 'string', describe: 'Full or unambiguous partial record sys_id (including legacy IDs)' })
+            .option('identifier', { type: 'string', describe: 'Identifier value; use --identifier-field number/name/etc for human identifiers' })
+            .option('identifier-field', { type: 'string', describe: 'Exact identifier field (default sys_id); disambiguates names and legacy sys_ids' })
             .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' })
@@ -270,8 +275,10 @@ export function recordsCmd(wrap) {
             for (const w of warnings) {
               process.stderr.write(`⚠ ${w.hint}\n`);
             }
-            const record = await app.sdk.update(argv.table, argv['sys-id'], recordData);
-            const mismatches = await verifyWriteBack(app, argv.table, argv['sys-id'], recordData);
+            const lookup = recordLookup(argv);
+            const resolved = await getRecord(app.sdk, lookup);
+            const record = await updateRecord(app.sdk, { table: argv.table, record: resolved, data: recordData });
+            const mismatches = await verifyWriteBack(app, argv.table, unwrapSysId(resolved), recordData);
             for (const m of mismatches) {
               process.stderr.write(`⚠ field "${m.field}" was not persisted (sent: "${m.sent}", got: "${m.got}")\n`);
             }
@@ -286,12 +293,15 @@ export function recordsCmd(wrap) {
           describe: 'Delete a record',
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
-            .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
+            .option('sys-id', { type: 'string', describe: 'Full or unambiguous partial record sys_id (including legacy IDs)' })
+            .option('identifier', { type: 'string', describe: 'Identifier value; use --identifier-field number/name/etc for human identifiers' })
+            .option('identifier-field', { type: 'string', describe: 'Exact identifier field (default sys_id); disambiguates names and legacy sys_ids' })
             .option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
           handler: wrap(async (argv, app) => {
-            await confirmDelete(app, argv, `Delete record from ${argv.table} (${argv['sys-id']})`);
-            await app.sdk.delete(argv.table, argv['sys-id']);
-            app.ok({ message: 'Record deleted', table: argv.table, sys_id: argv['sys-id'] }, { summary: `Deleted record from ${argv.table}` });
+            const lookup = recordLookup(argv);
+            await confirmDelete(app, argv, `Delete record from ${argv.table} (${lookup.identifier})`);
+            const sysID = await deleteRecord(app.sdk, lookup);
+            app.ok({ message: 'Record deleted', table: argv.table, sys_id: sysID }, { summary: `Deleted record from ${argv.table}` });
           }),
         })
         .command({
@@ -369,6 +379,7 @@ export function recordsCmd(wrap) {
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('query', { type: 'string', describe: 'Encoded query to constrain the aggregation' })
             .option('group-by', { type: 'string', describe: 'Comma-separated fields to group by' })
+            .option('display-values', { type: 'string', choices: ['raw', 'display', 'both'], describe: 'Reference values: raw, display or both' })
             .option('count', { type: 'boolean', default: true, describe: 'Include record counts' })
             .option('avg-fields', { type: 'string', describe: 'Comma-separated fields to average' })
             .option('sum-fields', { type: 'string', describe: 'Comma-separated fields to sum' })

package/src/commands/requests.js

@@ -1,11 +1,11 @@
-import { buildTicketCommands } from './_ticket.js';
-import { getStringField, assertSafeExactMatch } from '../helpers.js';
+import { getRecord, recordOptions } from '../records-engine.js';
+import { unwrapSysId } from '../resolve-record.js';
+import { buildProfileCommand } from '../record-profiles.js';
 
-const requestDefaultColumns = ['number', 'short_description', 'stage', 'assigned_to'];
 
 export function requestsCmd(wrap) {
   // Get the base command definition from the shared ticket builder
-  const baseCmd = buildTicketCommands('sc_req_item', 'requests', 'req', requestDefaultColumns, {}, null, wrap);
+  const baseCmd = buildProfileCommand('requests', wrap);
 
   // Override the builder to inject our enriched show handler.
   // yargs allows re-registration — the last .command() call wins the slot.
@@ -16,6 +16,7 @@ export function requestsCmd(wrap) {
       command: 'show <number>',
       aliases: ['get'],
       describe: 'Show a specific request with attachments and catalog variables',
+      builder: y => recordOptions(y),
       handler: wrap(enrichedShowHandler),
     });
   };
@@ -25,17 +26,8 @@ export function requestsCmd(wrap) {
 
 async function enrichedShowHandler(argv, app) {
   const number = argv.number;
-  assertSafeExactMatch(number);
-  const params = new URLSearchParams();
-  params.set('sysparm_query', `number=${number}`);
-  params.set('sysparm_display_value', 'all');
-  params.set('sysparm_limit', '1');
-  const records = await app.sdk.list('sc_req_item', params);
-  if (records.length === 0) {
-    throw new Error(`Request not found: ${number}`);
-  }
-  const record = records[0];
-  const sysID = getStringField(record, 'sys_id');
+  const record = await getRecord(app.sdk, { table: 'sc_req_item', identifier: number, matchField: 'number', identifierField: argv.identifierField, displayValues: argv.displayValues, resource: 'Request' });
+  const sysID = unwrapSysId(record);
 
   // Fetch attachments and catalog variables in parallel
   const [attachments, variables] = await Promise.all([

package/src/commands/tasks.js

@@ -1,7 +1,5 @@
-import { buildTicketCommands } from './_ticket.js';
-
-const taskDefaultColumns = ['number', 'short_description', 'state', 'assigned_to'];
+import { buildProfileCommand } from '../record-profiles.js';
 
 export function tasksCmd(wrap) {
-  return buildTicketCommands('sc_task', 'tasks', 'task', taskDefaultColumns, {}, null, wrap);
+  return buildProfileCommand('tasks', wrap);
 }

package/src/commands/tickets.js

@@ -1,5 +1,6 @@
-import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam, buildRecordPayload } from '../helpers.js';
-import { resolveRecord, resolveSysId } from '../resolve-record.js';
+import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam, buildRecordPayload, confirmDelete } from '../helpers.js';
+import { getRecord, listRecords, recordListParams, createRecord, updateRecord, deleteRecord, recordOptions } from '../records-engine.js';
+import { resolveSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('tickets', { mutationSubcommands: ['create', 'update', 'delete'] });
@@ -15,23 +16,18 @@ export function ticketsCmd(wrap) {
           command: 'list',
           aliases: ['ls'],
           describe: 'List tickets',
-          builder: (y) => y
+          builder: (y) => recordOptions(y)
             .option('query', { type: 'string', describe: 'Encoded query (e.g. "active=true^priority=1")' })
             .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description,priority")' })
             .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' })
             .option('offset', { alias: 'o', type: 'number', default: 0, describe: 'Offset' }),
           handler: wrap(async (argv, app) => {
             const columns = argv.columns ? argv.columns.split(',') : ['number', 'short_description', 'state', 'assigned_to'];
-            const params = new URLSearchParams();
-            params.set('sysparm_limit', String(argv.limit));
-            params.set('sysparm_offset', String(argv.offset));
-            params.set('sysparm_display_value', 'all');
             const fields = resolveFieldsParam(columns);
-            if (fields) params.set('sysparm_fields', fields);
             const q = argv.query ? argv.query + '^ORDERBYDESCsys_updated_on' : 'ORDERBYDESCsys_updated_on';
-            params.set('sysparm_query', q);
-            const records = await app.sdk.list('task', params);
-            const displayRecords = fields ? records.map(r => formatRecordForDisplay(r, columns)) : records;
+            const params = recordListParams({ limit: argv.limit, offset: argv.offset, fields, query: q });
+            const records = await listRecords(app.sdk, { table: 'task', params, displayValues: argv.displayValues });
+            const displayRecords = fields && !argv.displayValues ? records.map(r => formatRecordForDisplay(r, columns)) : records;
             const breadcrumbs = [
               { action: 'create', cmd: 'jsn tickets create -f short_description=New ticket', description: 'Create a new ticket' },
             ];
@@ -63,46 +59,49 @@ export function ticketsCmd(wrap) {
           command: 'show <number>',
           aliases: ['get'],
           describe: 'Show a ticket',
+          builder: y => recordOptions(y),
           handler: wrap(async (argv, app) => {
-            const record = await resolveRecord(app.sdk, { table: 'task', identifier: argv.number, matchField: 'number', resource: 'Ticket' });
+            const record = await getRecord(app.sdk, { table: 'task', identifier: argv.number, identifierField: argv.identifierField, displayValues: argv.displayValues, matchField: 'number', resource: 'Ticket' });
             app.ok(record, { summary: `Ticket ${argv.number}` });
           }),
         })
         .command({
           command: 'create',
           describe: 'Create a new ticket',
-          builder: (y) => y
+          builder: (y) => recordOptions(y, false)
             .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
             .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const recordData = buildRecordPayload(argv);
-            const record = await app.sdk.create('task', recordData);
+            const record = await createRecord(app.sdk, { table: 'task', data: recordData });
             app.ok(record, { summary: `Created ticket ${getStringField(record, 'number')}` });
           }),
         })
         .command({
           command: 'update <number>',
           describe: 'Update a ticket',
-          builder: (y) => y
+          builder: (y) => recordOptions(y, false)
             .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
             .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const recordData = buildRecordPayload(argv);
-            const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, matchField: 'number', resource: 'Ticket' });
-            const updated = await app.sdk.update('task', sysID, recordData);
+            const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, identifierField: argv.identifierField, displayValues: argv.displayValues, matchField: 'number', resource: 'Ticket' });
+            const updated = await updateRecord(app.sdk, { table: 'task', record: { sys_id: sysID }, data: recordData });
             app.ok(updated, { summary: `Updated ticket ${argv.number}` });
           }),
         })
         .command({
           command: 'delete <number>',
           describe: 'Delete a ticket',
+          builder: y => recordOptions(y, false).option('force', { type: 'boolean', default: false, describe: 'Skip confirmation after approval' }),
           handler: wrap(async (argv, app) => {
-            const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, matchField: 'number', resource: 'Ticket' });
-            await app.sdk.delete('task', sysID);
+            await confirmDelete(app, argv, `Delete ticket ${argv.number}`);
+            const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, identifierField: argv.identifierField, displayValues: argv.displayValues, matchField: 'number', resource: 'Ticket' });
+            await deleteRecord(app.sdk, { table: 'task', record: { sys_id: sysID } });
             app.ok({ number: argv.number, message: 'Ticket deleted' }, { summary: `Deleted ticket ${argv.number}` });
           }),
         })

package/src/commands/uipolicies.js

@@ -1,28 +1,3 @@
-import { buildDevCmd } from './_generic.js';
-import { getStringField } from '../helpers.js';
+import { buildProfileCommand } from '../record-profiles.js';
 
-export const uipoliciesCmd = (wrap) => buildDevCmd('uipolicies', 'sys_ui_policy', ['uipolicy', 'up'],
-  ['short_description', 'table', 'sys_class_name', 'active'], wrap, {
-    singular: 'UI policy',
-    scopeValidation: true,
-    onShow: async (record, app) => {
-      const sysID = getStringField(record, 'sys_id') || '';
-      if (!sysID) return;
-      const mp = new URLSearchParams();
-      mp.set('sysparm_query', `ui_policy=${sysID}^ORDERBYorder`);
-      mp.set('sysparm_limit', '100'); mp.set('sysparm_display_value', 'all');
-      mp.set('sysparm_fields', 'name,table,field_name,read_only,mandatory,visible,sys_id');
-      const actions = await app.sdk.list('sys_ui_policy_action', mp);
-      if (actions.length > 0) {
-        console.log(`  Actions (${actions.length}):`);
-        for (const a of actions) {
-          const f = getStringField(a, 'field_name') || '(all fields)';
-          const flags = [];
-          if (getStringField(a, 'mandatory') === 'true') flags.push('mandatory');
-          if (getStringField(a, 'read_only') === 'true') flags.push('read-only');
-          if (getStringField(a, 'visible') === 'false') flags.push('hidden');
-          console.log(`    ${f}  ${flags.length ? `[${flags.join(', ')}]` : ''}`);
-        }
-      }
-    },
-  });
+export const uipoliciesCmd = wrap => buildProfileCommand('uipolicies', wrap);

package/src/errors.js

@@ -256,6 +256,13 @@ export function renderAppError(err, { app = null, argv = null, identifier = '' }
     return { stream: 'stderr', text, exitCode: 1 };
   }
 
+  if (err.resolution) {
+    if (resolveJsonMode(app, argv) && app) return { stream: 'stdout', text: null, exitCode: 1, appErr: true };
+    const lookup = err.resolution;
+    const text = `Error (${code}): ${err.message}\nLookup: ${lookup.mode} ${lookup.table}.${lookup.field}; ${lookup.at_least ? 'at least ' : ''}${lookup.matches} matches.\n${err.hint ? `\nHint: ${err.hint}\n` : ''}`;
+    return { stream: 'stderr', text, exitCode: 1 };
+  }
+
   if (code === CodeNotFound) {
     let text = `Error (${code}): ${err.message}\n`;
     if (identifier) {

package/src/essential-records.js

@@ -0,0 +1,40 @@
+// Essential relationships are a declarative opt-in of specialized profiles.
+// Supplementary metadata/counts live separately; this never fetches them.
+import { assertSafeExactMatch, quoteShellArg } from './helpers.js';
+import { listRecords, displayValue, recordListParams } from './records-engine.js';
+
+export async function enrichEssentialRecords(record, { sdk, relationships, displayValues = 'both', profileName, instance }) {
+  if (!relationships?.length) return record;
+  const id = typeof record.sys_id === 'object' ? record.sys_id?.value : record.sys_id;
+  const entries = await Promise.all(relationships.map(async relationship => {
+    const limit = relationship.limit ?? 100;
+    const query = `${relationship.foreignKey}=${id}`;
+    const result = { table: relationship.table, query, limit, records: [], loaded: 0,
+      coverage: 'visible_rows_only', visibility: 'Subject to field/row ACLs; empty results do not prove no related records.' };
+    try {
+      if (!id) throw new Error('No readable raw parent sys_id');
+      assertSafeExactMatch(id);
+      const ordered = query + (relationship.orderBy ? `^ORDERBY${relationship.orderBy}` : '');
+      const params = recordListParams({ limit: limit + 1, query: ordered,
+        fields: relationship.columns ? ['sys_id', ...relationship.columns] : undefined,
+        displayValue: displayValue(displayValues),
+      });
+      const rows = await listRecords(sdk, { table: relationship.table, params });
+      if (!Array.isArray(rows)) throw new Error('Invalid related record response');
+      result.records = rows.slice(0, limit);
+      result.loaded = result.records.length;
+      result.has_more = rows.length > limit;
+      result.status = 'loaded';
+      const selector = profileName ? ` --profile ${quoteShellArg(profileName)}` : instance ? ` --instance ${quoteShellArg(instance)}` : '';
+      result.command = `jsn${selector} records list --table ${quoteShellArg(relationship.table)} --query ${quoteShellArg(ordered)} --limit ${limit} --json`;
+    } catch (error) {
+      // Provider bodies can contain private data. Preserve uncertainty, not raw errors.
+      result.status = 'unavailable';
+      result.error = { code: error.code === 'forbidden' || error.status === 403 ? 'forbidden' : 'unavailable',
+        message: 'Essential related records could not be read. Check parent identity, table/field permissions and connection.' };
+    }
+    return [relationship.name, result];
+  }));
+  record._essential = Object.fromEntries(entries);
+  return record;
+}

package/src/output.js

@@ -160,6 +160,7 @@ export class OutputWriter {
     const format = this.effectiveFormat();
     const e = error.code ? error : { code: 'unknown', message: String(error), hint: '' };
     const resp = { ok: false, error: e.message, code: e.code, hint: e.hint || '' };
+    if (e.resolution) resp.resolution = e.resolution;
     if (e.context) resp.context = e.context;
     if (e.status === 401 || e.status === 403) resp.status = e.status;
     if (e.recovery) {
@@ -514,6 +515,20 @@ export class OutputWriter {
       this.writer.write('\n');
     }
 
+    if (data._essential && typeof data._essential === 'object') {
+      for (const [name, related] of Object.entries(data._essential)) {
+        this.writer.write(`─ Essential: ${name} (${related.loaded} loaded${related.has_more ? ', more available' : ''}) ─\n`);
+        if (related.status !== 'loaded') this.writer.write(`  Unavailable: ${related.error?.message || 'Read could not be completed.'}\n`);
+        for (const row of related.records || []) {
+          const fields = Object.entries(row).filter(([field]) => field !== 'sys_id').map(([field, value]) => `${field}: ${getDisplayValue(value)}`);
+          this.writer.write(`  ${fields.join(' | ')}\n`);
+        }
+        this.writer.write(`  ${related.visibility}\n`);
+        if (related.command) this.writer.write(`  Retrieve: ${related.command}\n`);
+        this.writer.write('\n');
+      }
+    }
+
     // ── Attachments ──
     if (data._attachments && Array.isArray(data._attachments) && data._attachments.length > 0) {
       this.writer.write('─ Attachments ─\n');

package/src/record-command-profiles.js

@@ -0,0 +1,70 @@
+// Edit table/ticket command defaults here. The key is the CLI command name.
+// Identifier/output defaults and empty relationship policies live in record-profiles.js.
+export default {
+  includes: { table: 'sys_script_include', aliases: ['include', 'si'], columns: ['name', 'api_name', 'active', 'sys_scope'],
+    options: { singular: 'script include', scopeValidation: true } },
+  rules: { table: 'sys_script', aliases: ['rule', 'br'], columns: ['name', 'collection', 'active', 'order', 'sys_scope'],
+    options: { singular: 'business rule', scopeValidation: true } },
+  clientscripts: { table: 'sys_script_client', aliases: ['clientscript', 'cs'], columns: ['name', 'table', 'active', 'type', 'sys_scope'],
+    options: { singular: 'client script', scopeValidation: true } },
+  uiactions: { table: 'sys_ui_action', aliases: ['uiaction', 'ua'], columns: ['name', 'table', 'active', 'order', 'sys_scope'],
+    options: { singular: 'UI action', scopeValidation: true } },
+  sppages: { table: 'sp_page', aliases: ['sp-pages'], columns: ['id', 'title', 'sys_scope'],
+    options: { singular: 'Service Portal page', readOnly: true } },
+  spwidgets: { table: 'sp_widget', aliases: ['sp-widget', 'widgets'], columns: ['id', 'name', 'sys_scope'],
+    options: { singular: 'Service Portal widget', readOnly: true } },
+  uipages: { table: 'sys_ui_page', aliases: ['ui-page', 'pages'], columns: ['name', 'sys_scope'],
+    options: { singular: 'UI page', scopeValidation: true } },
+  appmenu: { table: 'sys_app_application', aliases: ['app-menu', 'menu'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'application menu', scopeValidation: true } },
+  acls: { table: 'sys_security_acl', aliases: ['acl'], columns: ['name', 'operation', 'type', 'active', 'sys_scope'],
+    options: { singular: 'ACL', scopeValidation: true } },
+  roles: { table: 'sys_user_role', aliases: ['role', 'r'], columns: ['name', 'description', 'elevated_privilege', 'sys_scope'],
+    options: { singular: 'role', scopeValidation: true } },
+  properties: { table: 'sys_properties', aliases: ['property', 'prop'], columns: ['name', 'value', 'description', 'sys_scope'],
+    options: { singular: 'property', scopeValidation: true } },
+  relationships: { table: 'sys_relationship', aliases: ['relationship', 'rel'], columns: ['name', 'sys_scope'],
+    options: { singular: 'relationship', scopeValidation: true } },
+  appmodules: { table: 'sys_app_module', aliases: ['appmodule', 'am'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'application module', scopeValidation: true } },
+  listcontrols: { table: 'sys_ui_list_control', aliases: ['listcontrol', 'lc'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'list control', scopeValidation: true } },
+  views: { table: 'sys_ui_view', aliases: ['view', 'vw'], columns: ['name', 'title', 'sys_scope'],
+    options: { singular: 'view', scopeValidation: true } },
+  privileges: { table: 'sys_scope_privilege', aliases: ['privilege', 'priv'], columns: ['source_scope', 'target_scope', 'target_name', 'operation', 'status'],
+    options: { singular: 'privilege', scopeValidation: true } },
+  uxscripts: { table: 'sys_ux_lib_source_script', aliases: ['uxscript', 'ux'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'UX script', scopeValidation: true } },
+  catalogscripts: { table: 'catalog_script_client', aliases: ['catalogscript'], columns: ['name', 'table', 'active', 'sys_scope'],
+    options: { singular: 'catalog script', scopeValidation: true } },
+  scriptactions: { table: 'sysevent_script_action', aliases: ['scriptaction'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'script action', scopeValidation: true } },
+  scheduledjobs: { table: 'sysauto_script', aliases: ['scheduledjob'], columns: ['name', 'active', 'run_type', 'sys_scope'],
+    options: { singular: 'scheduled job', scopeValidation: true } },
+  asyncrules: { table: 'sys_script', aliases: ['asyncrule'], columns: ['name', 'collection', 'active', 'order', 'sys_scope'],
+    options: { singular: 'async business rule', scopeValidation: true, extraQuery: 'when=async' } },
+  triggers: { table: 'sysevent_register', aliases: ['trigger'], columns: ['name', 'event_name', 'active', 'sys_scope'],
+    options: { singular: 'event trigger', scopeValidation: true } },
+  assignments: { table: 'sysrule_assignment', aliases: ['assignment'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'assignment rule', scopeValidation: true, readOnly: true } },
+  email: { table: 'sysevent_in_email_action', aliases: ['emails'], columns: ['name', 'active', 'type', 'sys_scope'],
+    options: { singular: 'inbound email action', scopeValidation: true } },
+  uimacros: { table: 'sys_ui_macro', aliases: ['uimacro'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'UI macro', scopeValidation: true } },
+  uxlists: { table: 'sys_ux_list', aliases: ['uxlist'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'workspace list', scopeValidation: true, readOnly: true } },
+  uxapplicability: { table: 'sys_ux_applicability_m2m', aliases: ['uxapp'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'workspace applicability', scopeValidation: true, readOnly: true } },
+  cataloguipolicies: { table: 'catalog_ui_policy', aliases: ['cataloguipolicy', 'cup'], columns: ['short_description', 'catalog_item', 'variable_set', 'active', 'sys_scope'],
+    options: { singular: 'catalog UI policy', scopeValidation: true } },
+  tables: { table: 'sys_db_object', aliases: ['table', 't'], columns: ['name', 'label', 'super_class', 'create_access_controls'],
+    options: { singular: 'table', scopeValidation: true, showFields: ['name', 'label', 'super_class', 'create_access_controls', 'sys_scope', 'sys_created_on', 'sys_updated_on', 'sys_created_by', 'sys_updated_by', 'is_extendable'] } },
+  incidents: { table: 'incident', aliases: ['incident', 'inc'], columns: ['number', 'short_description', 'priority', 'state', 'assigned_to'], kind: 'ticket' },
+  changes: { table: 'change_request', aliases: ['change_request', 'chg'], columns: ['number', 'short_description', 'risk', 'state', 'assigned_to'], kind: 'ticket' },
+  requests: { table: 'sc_req_item', aliases: ['sc_req_item', 'req'], columns: ['number', 'short_description', 'stage', 'assigned_to'], kind: 'ticket' },
+  tasks: { table: 'sc_task', aliases: ['sc_task', 'task'], columns: ['number', 'short_description', 'state', 'assigned_to'], kind: 'ticket' },
+  uipolicies: { table: 'sys_ui_policy', aliases: ['uipolicy', 'up'], columns: ['short_description', 'table', 'sys_class_name', 'active'],
+    identifierField: 'short_description', options: { singular: 'UI policy', scopeValidation: true },
+    relationships: { essential: [{ name: 'actions', table: 'sys_ui_policy_action', foreignKey: 'ui_policy', limit: 100, orderBy: 'order',
+      columns: ['name', 'table', 'field_name', 'read_only', 'mandatory', 'visible'] }] } },
+};

package/src/record-profiles.js

@@ -0,0 +1,88 @@
+// Declarative command metadata is consumed by the actual command factories.
+// Hooks stay executable code; the compact registry owns aliases/table/defaults/relationship policy.
+import definitions from './record-command-profiles.js';
+import { enrichEssentialRecords } from './essential-records.js';
+import { buildDevCmd } from './commands/_generic.js';
+import { buildTicketCommands } from './commands/_ticket.js';
+
+const namePattern = /^[a-z][a-z0-9_-]*$/i;
+const fieldPattern = /^[a-z_][a-z0-9_]*$/i;
+function freeze(value) {
+  if (value && typeof value === 'object') {
+    for (const entry of Object.values(value)) freeze(entry);
+    Object.freeze(value);
+  }
+  return value;
+}
+export function validateRecordProfiles(profiles) {
+  if (!Array.isArray(profiles)) throw new Error('Record profiles must be an array.');
+  const names = new Set();
+  return profiles.map(definition => {
+    for (const key of ['options', 'output', 'relationships']) {
+      if (definition[key] !== undefined && (!definition[key] || typeof definition[key] !== 'object' || Array.isArray(definition[key]))) throw new Error(`Invalid ${key} for ${definition.name}.`);
+    }
+    const profile = { ...definition,
+      identifierField: definition.identifierField ?? (definition.kind === 'ticket' ? 'number' : 'name'),
+      options: { ...definition.options },
+      output: { references: 'both', listProjection: 'display', ...definition.output },
+      relationships: { essential: [], supplementary: [], ...definition.relationships },
+    };
+    if (!namePattern.test(profile.name || '') || names.has(profile.name)) throw new Error('Invalid or duplicate record profile name.');
+    names.add(profile.name);
+    if (!fieldPattern.test(profile.table || '') || !fieldPattern.test(profile.identifierField || '')) throw new Error(`Invalid table/identifier field for ${profile.name}.`);
+    if (!Array.isArray(profile.aliases) || !profile.aliases.every(alias => namePattern.test(alias))) throw new Error(`Invalid aliases for ${profile.name}.`);
+    if (!Array.isArray(profile.columns) || !profile.columns.length || !profile.columns.every(field => fieldPattern.test(field))) throw new Error(`Invalid columns for ${profile.name}.`);
+    if (!['dev', 'ticket'].includes(profile.kind || 'dev')) throw new Error(`Invalid factory kind for ${profile.name}.`);
+    if (!['raw', 'display', 'both'].includes(profile.output?.references) || !['display', 'full'].includes(profile.output?.listProjection)) throw new Error(`Invalid output preferences for ${profile.name}.`);
+    if (!profile.options || typeof profile.options !== 'object' || Array.isArray(profile.options)) throw new Error(`Invalid factory options for ${profile.name}.`);
+    for (const key of ['readOnly', 'scopeValidation']) {
+      if (profile.options[key] !== undefined && typeof profile.options[key] !== 'boolean') throw new Error(`Invalid ${key} option for ${profile.name}.`);
+    }
+    for (const kind of ['essential', 'supplementary']) {
+      if (!Array.isArray(profile.relationships?.[kind])) throw new Error(`Missing ${kind} relationship policy for ${profile.name}.`);
+      const relationshipNames = new Set();
+      for (const relationship of profile.relationships[kind]) {
+        if (relationshipNames.has(relationship.name)) throw new Error(`Duplicate relationship for ${profile.name}.`);
+        relationshipNames.add(relationship.name);
+        if (relationship.limit !== undefined && (!Number.isInteger(relationship.limit) || relationship.limit < 1 || relationship.limit > 1000)) throw new Error(`Invalid relationship limit for ${profile.name}.`);
+        if (relationship.orderBy !== undefined && !fieldPattern.test(relationship.orderBy)) throw new Error(`Invalid relationship ordering for ${profile.name}.`);
+        if (relationship.columns !== undefined && (!Array.isArray(relationship.columns) || !relationship.columns.every(field => fieldPattern.test(field)))) throw new Error(`Invalid relationship columns for ${profile.name}.`);
+        if (!namePattern.test(relationship.name || '') || !fieldPattern.test(relationship.table || '') || !fieldPattern.test(relationship.foreignKey || '')) throw new Error(`Invalid relationship for ${profile.name}.`);
+      }
+    }
+    return freeze(structuredClone(profile));
+  });
+}
+const profiles = freeze(validateRecordProfiles(Object.entries(definitions).map(([name, profile]) => ({ name, ...profile }))));
+const index = new Map(profiles.map(profile => [profile.name, profile]));
+export const recordProfiles = () => profiles;
+export function getRecordProfile(name) {
+  const profile = index.get(name);
+  if (!profile) throw new Error(`Unknown record command profile: ${name}`);
+  return profile;
+}
+export function buildProfileCommand(name, wrap, hooks = {}) {
+  return buildRecordProfile(getRecordProfile(name), wrap, hooks);
+}
+
+export function buildRecordProfile(definition, wrap, hooks = {}) {
+  const [profile] = validateRecordProfiles([definition]);
+  const options = { ...profile.options, identifierField: profile.identifierField,
+    referenceMode: profile.output.references, listProjection: profile.output.listProjection,
+    relationships: profile.relationships, ...hooks };
+  if (profile.relationships.essential.length) {
+    const hook = options.onShow;
+    options.onShow = async (record, app, argv = {}) => {
+      if (hook) await hook(record, app, argv);
+      if (argv.essential !== false) await enrichEssentialRecords(record, { sdk: app.sdk,
+        relationships: profile.relationships.essential, displayValues: argv.displayValues ?? profile.output.references,
+        profileName: app.session?.profileName, instance: app.getEffectiveInstance?.() });
+    };
+  }
+  const command = profile.kind === 'ticket'
+    ? buildTicketCommands(profile.table, profile.name, profile.aliases.find(alias => alias !== profile.table), profile.columns, {}, null, wrap, options)
+    : buildDevCmd(profile.name, profile.table, profile.aliases, profile.columns, wrap, options);
+  command.aliases = [...profile.aliases];
+  command.recordProfile = profile;
+  return command;
+}

package/src/records-engine.js

@@ -0,0 +1,57 @@
+// In-process CRUD transport shared by generic and specialized commands.
+// Policy (confirmation, scope, payload and output shape) stays with callers.
+import { resolveRecord, unwrapSysId } from './resolve-record.js';
+import { errUsage } from './errors.js';
+
+export function displayValue(mode, fallback = 'all') {
+  if (mode === undefined) return fallback;
+  const values = { raw: 'false', display: 'true', both: 'all' };
+  if (!Object.hasOwn(values, mode)) throw errUsage('display-values must be raw, display or both');
+  return values[mode];
+}
+
+export function recordListParams({ limit, offset, query, fields, displayValue: representation = 'all' } = {}) {
+  const params = new URLSearchParams({ sysparm_display_value: representation });
+  if (limit !== undefined) params.set('sysparm_limit', String(limit));
+  if (offset !== undefined) params.set('sysparm_offset', String(offset));
+  if (query) params.set('sysparm_query', query);
+  if (fields) params.set('sysparm_fields', Array.isArray(fields) ? fields.join(',') : fields);
+  return params;
+}
+
+export function listRecords(sdk, { table, params, displayValues, ...options }) {
+  const query = params ? new URLSearchParams(params) : recordListParams(options);
+  if (displayValues !== undefined) query.set('sysparm_display_value', displayValue(displayValues));
+  return sdk.list(table, query);
+}
+
+export function getRecord(sdk, options) {
+  return resolveRecord(sdk, { ...options, displayValue: displayValue(options.displayValues, options.displayValue || 'all') });
+}
+
+export function createRecord(sdk, { table, data }) {
+  return sdk.create(table, data);
+}
+
+function mutationId(record) {
+  const id = unwrapSysId(record);
+  if (!id) throw errUsage('The matched record has no readable sys_id; check field ACLs before retrying.');
+  return id;
+}
+
+export async function updateRecord(sdk, { table, data, record, ...lookup }) {
+  const resolved = record || await getRecord(sdk, { table, ...lookup });
+  return sdk.update(table, mutationId(resolved), data);
+}
+
+export async function deleteRecord(sdk, { table, record, ...lookup }) {
+  const resolved = record || await getRecord(sdk, { table, ...lookup });
+  const id = mutationId(resolved);
+  await sdk.delete(table, id);
+  return id;
+}
+
+export function recordOptions(y, display = true) {
+  const command = y.option('identifier-field', { type: 'string', describe: 'Exact field for disambiguation (sys_id, number, name, etc); no human-field partial matches' });
+  return display ? command.option('display-values', { type: 'string', choices: ['raw', 'display', 'both'], describe: 'Reference values: raw, display or both; omitted preserves existing output' }) : command;
+}

package/src/resolve-record.js

@@ -9,7 +9,7 @@
 // resolve → mutate → report.
 
 import { assertSafeExactMatch, isHexString } from './helpers.js';
-import { errNotFound } from './errors.js';
+import { errNotFound, errUsage, AppError, CodeAmbiguous } from './errors.js';
 
 /**
  * True when the identifier looks like a ServiceNow sys_id (32 hex chars).
@@ -25,40 +25,60 @@ export function isSysId(identifier) {
  */
 export function unwrapSysId(record) {
   const sysId = record?.sys_id;
-  if (sysId && typeof sysId === 'object') return sysId.value || sysId.display_value || '';
+  if (sysId && typeof sysId === 'object') return sysId.value || '';
   return sysId || '';
 }
 
 /**
- * Resolve a single record by human identifier.
- *
- * @param {object} sdk — SDK handle (uses sdk.list)
- * @param {object} opts
- * @param {string} opts.table — ServiceNow table
- * @param {string} opts.identifier — sys_id (32 hex) or value of matchField
- * @param {string} opts.matchField — field to match non-sys_id identifiers on
- *   (e.g. 'number', 'name', 'user_name')
- * @param {string} [opts.resource] — label for the not-found error
- *   (e.g. 'User' → "User not found: <id>"); defaults to matchField
- * @param {string[]} [opts.fields] — restrict sysparm_fields when set
- * @returns {Promise<object>} the record (display values requested)
- * @throws {AppError} code not_found when no record matches
+ * Exact lookups precede partial sys_id lookup. Configured human identifiers keep
+ * their legacy precedence; identifierField explicitly disambiguates collisions.
+ * Each query requests at most two rows so no operation silently picks a match.
  */
-export async function resolveRecord(sdk, { table, identifier, matchField, resource, fields }) {
+export async function resolveRecord(sdk, { table, identifier, matchField = 'sys_id', identifierField,
+  resource, fields, displayValue = 'all', partial = true }) {
   assertSafeExactMatch(identifier);
-  const queryField = isSysId(identifier) ? 'sys_id' : matchField;
-  const params = new URLSearchParams();
-  params.set('sysparm_query', `${queryField}=${identifier}`);
-  params.set('sysparm_limit', '1');
-  params.set('sysparm_display_value', 'all');
-  if (fields && fields.length > 0) {
-    params.set('sysparm_fields', fields.join(','));
+  if (typeof identifier !== 'string' || !identifier.trim()) throw errUsage('An identifier is required.');
+  for (const value of [table, identifierField || matchField]) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(value || '')) throw errUsage('Invalid table or identifier field name.');
   }
-  const records = await sdk.list(table, params);
-  if (records.length === 0) {
-    throw errNotFound(resource || matchField, identifier);
+  const explicit = identifierField !== undefined;
+  const firstField = identifierField || (isSysId(identifier) ? 'sys_id' : matchField);
+  const attempts = [];
+  async function lookup(field, operator, mode) {
+    const params = new URLSearchParams({
+      sysparm_query: `${field}${operator}${identifier}`,
+      sysparm_limit: '2', sysparm_display_value: displayValue,
+    });
+    if (fields?.length) params.set('sysparm_fields', [...new Set(['sys_id', ...fields])].join(','));
+    const records = await sdk.list(table, params);
+    const resolution = { table, field, mode, matches: Math.min(records.length, 2),
+      ...(records.length >= 2 ? { at_least: true } : {}) };
+    attempts.push(resolution);
+    if (records.length > 1) {
+      const error = new AppError(CodeAmbiguous, `Multiple ${resource || 'records'} found matching ${mode} ${field}: ${identifier}`,
+        'Use a longer/full sys_id or select the exact human field with --identifier-field <field>.');
+      error.resolution = { ...resolution, attempts };
+      throw error;
+    }
+    return records[0];
   }
-  return records[0];
+  let record = await lookup(firstField, '=', 'exact');
+  if (record) return record;
+  if (!explicit && firstField !== 'sys_id') {
+    record = await lookup('sys_id', '=', 'exact');
+    if (record) return record;
+  }
+  // An explicitly selected human field must never fall back to another field.
+  if (partial && (!explicit || firstField === 'sys_id')) {
+    record = await lookup('sys_id', 'STARTSWITH', 'prefix');
+    if (record) return record;
+    record = await lookup('sys_id', 'ENDSWITH', 'suffix');
+    if (record) return record;
+  }
+  const error = errNotFound(resource || matchField, identifier);
+  error.hint = 'No accessible record matched. Check the table/ACLs, supply a full or longer sys_id, or use --identifier-field <field> for an exact human identifier.';
+  error.resolution = { ...attempts.at(-1), attempts };
+  throw error;
 }
 
 /**
@@ -67,5 +87,7 @@ export async function resolveRecord(sdk, { table, identifier, matchField, resour
  */
 export async function resolveSysId(sdk, opts) {
   const record = await resolveRecord(sdk, { fields: ['sys_id'], ...opts });
-  return unwrapSysId(record);
+  const id = unwrapSysId(record);
+  if (!id) throw errUsage('The matched record has no readable sys_id; check field ACLs before retrying.');
+  return id;
 }