@jacebenson/jsn 4.3.7-dev.40 → 4.3.7-dev.43

package/src/commands/platform.js

@@ -1,4 +1,5 @@
 import { declareCapabilities } from '../capabilities.js';
+import { formatCommandList } from '../helpers.js';
 
 function numberOrString(value) {
   const n = Number(value);
@@ -270,6 +271,22 @@ export function platformCmd(wrap) {
   return {
     command: 'platform',
     describe: 'Inspect read-only platform health and node statistics',
+    // Parent discovery. This parent had no handler, so `jsn platform` and
+    // `jsn platform --json` exited 0 with no output at all — silent success.
+    // Children come from the registry, not a second hand-written list.
+    handler: wrap(async (argv, app) => {
+      const subcommands = argv.subcommands || [];
+      const summary = 'Inspect read-only platform health and node statistics.';
+      app.ok({
+        command: 'platform',
+        subcommands,
+        _formatted: formatCommandList({
+          title: summary,
+          commands: subcommands,
+          footer: 'Run "jsn platform <command> --help" for details.',
+        }),
+      }, { summary });
+    }),
     builder: (y) => y.command({
       command: 'health',
       describe: 'Show cluster, queue, semaphore, and node health',

package/src/commands/records.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
+import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('records', {
@@ -514,20 +514,24 @@ export function recordsCmd(wrap) {
         })
 
     },
-    handler: (argv) => {
+    // Parent discovery through the output controller: the subcommand list is
+    // registry-derived (argv.subcommands), so `jsn records --json` returns a
+    // structured envelope instead of prose, and the descriptions can no longer
+    // describe a different surface than the registrations (the previous
+    // hand-written list advertised `inspect` as table schema/statistics).
+    handler: wrap(async (argv, app) => {
       if (argv._[1]) return; // a subcommand ran — its own handler handled it
-      console.log('Query and manage records in any ServiceNow table.');
-      console.log('');
-      console.log('Available subcommands:');
-      console.log('  list                  List records from a table (includes total by default)');
-      console.log('  get                   Get a single record by sys_id (--attachments to include files)');
-      console.log('  create                Create a record');
-      console.log('  update                Update a record');
-      console.log('  delete                Delete a record');
-      console.log('  aggregate              Run Stats API aggregation with optional grouping');
-      console.log('  inspect                Inspect table schema and statistics');
-      console.log('');
-      console.log('Run "jsn records <command> --help" for details.');
-    },
+      const subcommands = argv.subcommands || [];
+      const summary = 'Query and manage records in any ServiceNow table.';
+      app.ok({
+        command: 'records',
+        subcommands,
+        _formatted: formatCommandList({
+          title: summary,
+          commands: subcommands,
+          footer: 'Run "jsn records <command> --help" for details.',
+        }),
+      }, { summary });
+    }),
   };
 }

package/src/commands/skill.js

@@ -8,6 +8,7 @@ import { execSync } from 'node:child_process';
 
 import { globalConfigPath } from '../config.js';
 import { declareCapabilities } from '../capabilities.js';
+import { canUsePicker } from '../helpers.js';
 
 declareCapabilities('skill', { noInstance: true, skipDailyChecks: true });
 
@@ -305,8 +306,10 @@ export function skillCmd(wrap) {
                   }
                 }
               }
-            } else if (process.stdin.isTTY) {
-              // Interactive: show multi-select picker
+            } else if (canUsePicker(app, argv)) {
+              // Interactive: show multi-select picker. canUsePicker() (not a
+              // bare stdin TTY check) keeps a PTY allocated for an agent,
+              // CI, JSN_NO_PROMPTS, --json/--quiet or --get out of a prompt.
               const fetchedVersion = extractVersion(content);
               // Check if any existing installed copies are outdated
               const outdated = [];

package/src/errors.js

@@ -10,6 +10,7 @@ export const CodeAPI = 'api_error';
 export const CodeAmbiguous = 'ambiguous';
 export const CodeEmptyResult = 'empty_result';
 export const CodeConfirmationRequired = 'confirmation_required';
+export const CodeExtractionNotFound = 'extraction_not_found';
 
 export class AppError extends Error {
   constructor(code, message, hint = '', status = 0, cause = null) {
@@ -118,17 +119,48 @@ export function errAmbiguous(resource, matches) {
   );
 }
 
+/**
+ * Structured error for `--get <path>` resolving to nothing.
+ *
+ * An unresolvable path (typo, wrong envelope shape, out-of-range index) is a
+ * failure, not a value: printing `undefined` and exiting 0 made a misspelled
+ * extract look like a successful empty result until the next tool in the pipe
+ * tried to parse it. A path that resolves to a present null, false, 0, or ""
+ * is a real value and is returned unchanged — only an unresolved path errors.
+ */
+export function errExtractionNotFound(path) {
+  return new AppError(
+    CodeExtractionNotFound,
+    `No value at --get path "${path}".`,
+    'Check the path against the envelope (run the same command without --get, or with --json, to see its shape). '
+    + 'Present null, false, 0, and "" values are returned as-is; only an unresolvable path fails.'
+  );
+}
+
 /**
  * Structured error for a destructive action that requires confirmation
  * but no human is available to answer (non-TTY, pipes, or AI agents).
+ *
  * The hint is written to be machine-parseable: an agent can read the
- * re-run command and either present it to its user or execute it.
+ * exact re-run command — target, table, pinned profile/instance — and
+ * present it to its user for approval before executing. It deliberately
+ * does NOT recommend permanently disabling confirmations: an approval for
+ * one destructive action is not consent to disarm the guard for every
+ * future action.
+ *
+ * @param {string} question — e.g. `Delete incident INC0010001?`
+ * @param {string} [rerunCmd] — complete re-run command WITHOUT --force,
+ *   already shell-quoted. Empty when the caller cannot reconstruct it.
  */
-export function errConfirmationRequired(question, rerunCmd) {
+export function errConfirmationRequired(question, rerunCmd = '') {
+  const cmd = String(rerunCmd || '').trim();
+  const hint = cmd
+    ? `This is a destructive action. Ask your user to approve this exact command, then re-run:\n  ${cmd} --force`
+    : 'This is a destructive action. Ask your user to approve it, then re-run the same command with --force.';
   return new AppError(
     CodeConfirmationRequired,
-    `${question} — confirmation required. Pass --force to skip, or set skip_confirmations on the profile to disable prompts.`,
-    `This is a destructive action. Ask your user to confirm, then re-run:\n  ${rerunCmd} --force\nOr set skip_confirmations on the profile to disable prompts:\n  jsn auth login <instance> --skip-confirmations`
+    `${question} — confirmation required. Pass --force only after your user approves this operation.`,
+    hint
   );
 }
 
@@ -152,12 +184,20 @@ export function isErrorCode(err, code) {
  *
  * Exit-code contract (observable behavior, pinned by tests):
  *   not_found              → 1   stderr, "Error (not_found): …" + identifier hint
- *   usage / usage_error    → 2   stderr, "Error (usage): …"
+ *   extraction_not_found   → 1   JSON envelope on stdout in JSON mode, else stderr
+ *   usage / usage_error    → 2   JSON envelope on stdout in JSON mode
+ *                                (machine consumers), else stderr "Error (usage): …"
  *   system_error           → 3   stderr, "Error (system): …"
  *   confirmation_required  → 1   JSON envelope on stdout in JSON mode
  *                                (machine consumers), else stderr + hint
  *   anything else          → 1   stderr, "Error: …"
  *
+ * The JSON envelope is the SAME shape for every failure that a machine
+ * consumer can hit — guardError(), the mutation middleware, parse-time
+ * failures routed by cli.js, and handler-thrown AppErrors all end up here, so
+ * `--json` never yields human prose on stdout and never yields a
+ * success-shaped payload for a failed command.
+ *
  * jsonMode resolution: prefer app.output.effectiveFormat() (respects
  * --json/--quiet/etc. shortcuts AND piped-stdout auto-detection); fall
  * back to argv.format for callers without an App (unit tests).
@@ -201,15 +241,35 @@ export function renderAppError(err, { app = null, argv = null, identifier = '' }
     return { stream: 'stderr', text, exitCode: 1 };
   }
 
+  if (code === CodeExtractionNotFound) {
+    // Same contract as every other machine-consumable failure: a parseable
+    // envelope on stdout when the caller is in JSON mode, human text on
+    // stderr otherwise. Exit 1 — the command ran, the value was absent.
+    if (resolveJsonMode(app, argv) && app) {
+      return { stream: 'stdout', text: null, exitCode: 1, appErr: true };
+    }
+    let text = `Error (${code}): ${err.message}\n`;
+    if (err.hint) text += `\nHint: ${err.hint}\n`;
+    return { stream: 'stderr', text, exitCode: 1 };
+  }
+
   // 'usage' is the legacy literal; CodeUsage ('usage_error') is the
   // exported constant. Both render as the usage class.
   if (code === CodeUsage || code === 'usage') {
-    // Interactive command families can opt into machine-readable fail-fast errors
-    // without changing the legacy stderr contract for other usage errors.
-    if (err.jsonEnvelope === true && resolveJsonMode(app, argv) && app) {
+    // Usage failures were the last split-brain case: a parse-time failure
+    // exited 1 with raw prose, a middleware guard exited 2 with a JSON
+    // envelope, and a handler-thrown usage error exited 2 with prose — all
+    // for the same class of mistake. One renderer, one exit code (2), and a
+    // structured envelope whenever the caller is in JSON mode.
+    if (resolveJsonMode(app, argv) && app) {
       return { stream: 'stdout', text: null, exitCode: 2, appErr: true };
     }
-    return { stream: 'stderr', text: `Error (usage): ${err.message}\n`, exitCode: 2 };
+    // Keep the actionable hint (the failing command's --help) in the human view
+    // too — it used to be dropped on this path while every other error class
+    // printed one.
+    let text = `Error (usage): ${err.message}\n`;
+    if (err.hint) text += `\nHint: ${err.hint}\n`;
+    return { stream: 'stderr', text, exitCode: 2 };
   }
 
   if (code === 'system_error') {

package/src/flow-create.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { assertSafeExactMatch } from './helpers.js';
 import { createVerifiedFlowVersion } from './flow-versioning.js';
 import {
+  RECORD_TRIGGER_FAMILY,
   SUPPORTED_TRIGGER_TYPES,
   TRIGGER_DEFINITION_TABLE,
   buildTriggerInputs,
@@ -11,6 +12,7 @@ import {
   readTriggerInputDefinitions,
   tableInputFor,
   flowDesignParameter,
+  triggerFamily,
 } from './flow-triggers.js';
 
 const FLOW_ENDPOINT = '/api/now/processflow/flow';
@@ -264,7 +266,11 @@ export function buildTypedInputs(action, schema) {
       throw new Error(`Action ${action.type} input "${field.name}" has a malformed parameter block; refusing to change it`);
     }
     const suppliedValue = Object.prototype.hasOwnProperty.call(supplied, field.name) ? supplied[field.name] : field.default;
-    if ((suppliedValue === undefined || suppliedValue === null) && (field.mandatory === true || field.required === true)) throw new Error(`Missing required input "${field.name}" for action ${action.type}`);
+    const parameter = field.parameter || {};
+    if ((suppliedValue === undefined || suppliedValue === null)
+      && (field.mandatory === true || field.required === true || parameter.mandatory === true || parameter.required === true)) {
+      throw new Error(`Missing required input "${field.name}" for action ${action.type}`);
+    }
     const value = suppliedValue ?? null;
     const displayValue = field.displayValue ?? field.display_value ?? value;
     // global_snFlowDesigner_ActionInstanceValue accepts ONLY these keys. The
@@ -277,13 +283,29 @@ export function buildTypedInputs(action, schema) {
       children: Array.isArray(field.children) ? field.children : [],
       displayField: stringValue(field.displayField || field.display_field || ''),
       scriptActive: false,
-      parameter: flowDesignParameter(field),
+      parameter: actionInputParameter(field),
       value: { schemaless: false, schemalessValue: '', value },
       displayValue: { schemaless: false, schemalessValue: '', value: displayValue },
     };
   });
 }
 
+// Providers hand back the input metadata in one of two shapes: nested inside a
+// `parameter` block (the earlier contract) or FLAT on the input object (the real
+// published Log action's action_types route). The nested block wins when it
+// exists, flat keys fill in only what it leaves empty, and the result is always
+// narrowed to the fields global_snFlowDesigner_FlowDesignParameter accepts.
+export function actionInputParameter(field) {
+  if (field?.parameter === undefined) return flowDesignParameter(field);
+  const parameter = flowDesignParameter(field.parameter);
+  const flat = flowDesignParameter(field);
+  for (const key of Object.keys(flat)) {
+    if (flat[key] === undefined || flat[key] === '') continue;
+    if (parameter[key] === undefined || parameter[key] === '') parameter[key] = flat[key];
+  }
+  return parameter;
+}
+
 function parseSimpleCondition(condition) {
   if (!condition) return null;
   const match = condition.match(/^([A-Za-z_][A-Za-z0-9_.]*)(STARTSWITH|ENDSWITH|LIKE|NOT LIKE|=|!=|IN|ISEMPTY|ISNOTEMPTY)([^,^]*)$/);
@@ -552,8 +574,8 @@ function updatedTrigger(flow, manifest, descriptor) {
   if (!existing) throw new Error('Saved flow has no trigger instance');
   const existingMetadata = parseMaybeJson(existing.metadata, null);
   if (existing.metadata && (!existingMetadata || typeof existingMetadata !== 'object' || Array.isArray(existingMetadata))) throw new Error('Saved record trigger metadata is unreadable; refusing to replace it');
-  const existingType = stringValue(existing.triggerType || existing.trigger_type || existingMetadata?.triggerType || existingMetadata?.trigger_type);
-  if (existingType && existingType !== 'record_create_or_update') throw new Error(`Only record_create_or_update trigger updates are supported; found ${existingType}`);
+  const existingFamily = triggerFamily(existing);
+  if (existingFamily && existingFamily !== RECORD_TRIGGER_FAMILY) throw new Error(`Only ${RECORD_TRIGGER_FAMILY} trigger updates are supported; found ${existingFamily}`);
   const inputs = clone(inputList(existing));
   const tableInput = inputs.find(input => input.name === 'table');
   const conditionInput = inputs.find(input => input.name === 'condition');

package/src/flow-inspection.js

@@ -298,11 +298,7 @@ function buildLabelCache(payload) {
   if (!payload || typeof payload !== 'object') return cache;
   let entries = payload.label_cache;
   if (!Array.isArray(entries)) {
-    try {
-      entries = JSON.parse(payload.labelCacheAsJsonString || '[]');
-    } catch {
-      entries = [];
-    }
+    entries = parseLabelCacheJson(payload.labelCacheAsJsonString);
   }
   for (const e of entries) {
     if (!e || typeof e !== 'object') continue;
@@ -313,6 +309,20 @@ function buildLabelCache(payload) {
   return cache;
 }
 
+// labelCacheAsJsonString is a JSON document, and JSON `null` or `{}` parses
+// successfully into something that is not iterable — that threw
+// "entries is not iterable" and broke `flows show` on real drafts whose cache is
+// empty. An empty cache simply has no labels.
+function parseLabelCacheJson(value) {
+  if (typeof value !== 'string' || !value.trim()) return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
 const GUID_PILL_RE = /\{\{([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.([^}]+)\}\}/g;
 
 /**

package/src/flow-test.js

@@ -1,4 +1,5 @@
 import { assertSafeExactMatch } from './helpers.js';
+import { RECORD_TRIGGER_FAMILY, triggerFamily } from './flow-triggers.js';
 
 const FLOW_ENDPOINT = '/api/now/processflow/flow';
 
@@ -30,15 +31,14 @@ function inputValue(trigger, name) {
   return valueOf(input?.value ?? input?.displayValue);
 }
 
-function triggerType(trigger) {
-  return valueOf(trigger?.triggerType || trigger?.trigger_type || trigger?.type);
-}
-
 export function deriveRecordTrigger(definition) {
   const trigger = findTrigger(definition);
   if (!trigger) throw new Error('Flow definition has no trigger instance');
-  const type = triggerType(trigger);
-  if (type !== 'record_create_or_update') throw new Error(`Flow test supports only record_create_or_update triggers; found ${type || 'unknown'}`);
+  // `type` is the family; `triggerType` is only the picker category ("Record").
+  // triggerFamily keeps a deliberate legacy fallback for saved instances that
+  // predate the split.
+  const type = triggerFamily(trigger);
+  if (type !== RECORD_TRIGGER_FAMILY) throw new Error(`Flow test supports only ${RECORD_TRIGGER_FAMILY} triggers; found ${type || 'unknown'}`);
   const table = inputValue(trigger, 'table');
   if (!table) throw new Error('Flow definition record trigger has no table');
   return { trigger, type, table };

package/src/flow-triggers.js

@@ -358,6 +358,59 @@ export function buildTriggerInstance({ flowId, definition, triggerType = '', inp
   };
 }
 
+export const RECORD_TRIGGER_FAMILY = 'record_create_or_update';
+
+// A trigger instance carries the FAMILY and the picker CATEGORY in two different
+// fields: `type` is the family Flow Designer executes ("record_create_or_update",
+// "daily", …) and `triggerType` is the category display name ("Record",
+// "Scheduled", …). Creation writes the family to `type` (resolveTriggerDefinition
+// reads it from sys_hub_trigger_definition), and the live ProcessFlow read-back
+// returns exactly that shape, so `type` is authoritative.
+//
+// Instances and fixtures that predate that split stored the family in
+// `triggerType` (and sometimes inside the raw metadata block), so those stay as
+// deliberate fallbacks — otherwise a real saved trigger reads as the category
+// "Record" and every consumer rejects it.
+export function triggerFamily(source) {
+  const metadata = parsedObject(source?.metadata);
+  const candidates = [
+    source?.type,
+    source?.trigger_type,
+    metadata?.type,
+    metadata?.trigger_type,
+    source?.triggerType,
+    metadata?.triggerType,
+  ];
+  for (const candidate of candidates) {
+    const family = familyValue(candidate);
+    if (family) return family;
+  }
+  return '';
+}
+
+function parsedObject(value) {
+  if (value && typeof value === 'object' && !Array.isArray(value)) return value;
+  if (typeof value !== 'string' || !value.trim()) return null;
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function familyValue(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'object') {
+    for (const key of ['value', 'display_value', 'sys_id']) {
+      const nested = familyValue(value[key]);
+      if (nested) return nested;
+    }
+    return '';
+  }
+  return String(value).trim();
+}
+
 // The snFlowDesigner GraphQL input types take `attributes` as a String
 // ("key=value,key=value") even though the ProcessFlow read path renders it as an
 // object. Sending the object fails validation: "not a valid 'String'".

package/src/help.js

@@ -1,5 +1,14 @@
 // Custom grouped help renderer
 // Organized by ServiceNow domain model with subgroup dividers
+//
+// The command rows are generated from the LIVE command registry
+// (`cli.commandRegistry()`): every registered root command appears, with the
+// description its own registration declares. The tables below are placement
+// hints only — group order, dividers, and a fallback description for a command
+// that declares none. A command that is registered but not hinted lands in the
+// trailing "MORE" group, so help can never silently drop a command again
+// (`approvals`, `cmdb`, `docs`, `perf`, `platform`, … were missing from the
+// hand-written list while being fully registered).
 
 function renderGroup(name, commands) {
   const lines = [`\n${name}`];
@@ -23,6 +32,8 @@ const CORE_COMMANDS = [
   { name: 'changes', alias: 'chg', desc: 'Manage change requests' },
   { name: 'requests', alias: 'req', desc: 'Manage service catalog requests' },
   { name: 'tasks', alias: 'task', desc: 'Manage catalog tasks' },
+  { name: 'tickets', desc: 'Query generic tickets' },
+  { name: 'approvals', desc: 'Approval requests (list, approve, reject, submit, history)' },
 ];
 
 const AUTOMATION_COMMANDS = [
@@ -96,6 +107,7 @@ const DATA_COMMANDS = [
   { name: 'tables', alias: 't', desc: 'Table definitions' },
   { name: 'columns', alias: 'col', desc: 'Column definitions' },
   { name: 'relationships', alias: 'rel', desc: 'Table relationships' },
+  { name: 'cmdb', desc: 'CMDB: CI lookup and relationship traversal (read-only)' },
 
   { divider: '── Shared Code, Transforms, Logs ──' },
   { name: 'includes', alias: 'si', desc: 'Script includes' },
@@ -104,6 +116,8 @@ const DATA_COMMANDS = [
   { name: 'properties', alias: 'prop', desc: 'System properties' },
 
   { name: 'records', desc: 'Generic Table API (any table)' },
+  { name: 'transactions', desc: 'Client transaction timings' },
+  { name: 'snippets', desc: 'Saved query snippets' },
 ];
 
 const CONFIG_COMMANDS = [
@@ -112,12 +126,20 @@ const CONFIG_COMMANDS = [
   { name: 'updatesets', desc: 'Update sets (set, create, export)' },
   { name: 'scopes', desc: 'Application scopes' },
   { name: 'domains', desc: 'Domains (domain separation)' },
+  { name: 'midservers', desc: 'MID Servers and MID-run commands' },
+  { name: 'platform', desc: 'Platform health and node statistics (read-only)' },
+  { name: 'completion', desc: 'Shell completion script' },
 ];
 
 const DEVELOPER_COMMANDS = [
   { name: 'atf', desc: 'Automated Test Framework (list, suites, run, results)' },
   { name: 'eval', desc: 'Run server-side JavaScript' },
   { name: 'rest', desc: 'Raw REST API calls' },
+  { name: 'graphql', desc: 'GraphQL queries' },
+  { name: 'codesearch', desc: 'Search code across ServiceNow artifacts' },
+  { name: 'docs', desc: 'Local ServiceNow documentation search' },
+  { name: 'diff', desc: 'Compare records across configured profiles' },
+  { name: 'perf', desc: 'Read-only performance capture and comparison' },
   { name: 'skill', desc: 'AI agent skill file (show, fetch, install)' },
   { name: 'version', desc: 'Version info (--check for npm updates)' },
 ];
@@ -132,17 +154,50 @@ const COMMAND_GROUPS = {
   'DEVELOPER': DEVELOPER_COMMANDS,
 };
 
-function renderFlags() {
-  return `
-FLAGS
-  --instance    ServiceNow instance URL (e.g., https://dev12345.service-now.com)  [string]
-  -p, --profile Configuration profile to use                                      [string]
-  --format      Output format: auto, json, markdown, styled, quiet                [string]
-  --json        Output in JSON format                                            [boolean]
-  -q, --quiet   Output only data, no envelope                                    [boolean]
-  --styled      Force styled output                                              [boolean]
-  --markdown    Output in Markdown format                                        [boolean]
-  --help        Show help                                                        [boolean]`;
+/**
+ * Domain separation is an optional plugin — only advertise `domains` when the
+ * active profile's capability probe found it installed.
+ */
+function isCapabilityHidden(name, config) {
+  if (name !== 'domains') return false;
+  const activeName = config?.activeProfile || config?.defaultProfile;
+  return !(activeName && config?.profiles?.[activeName]?.domain_separation);
+}
+
+/**
+ * Group rows for one domain: registry first (alias/description from the
+ * command's own registration), hint text only as a fallback description.
+ */
+function rowsFor(hint, byName, used, config) {
+  const rows = [];
+  for (const entry of hint) {
+    if (entry.divider) { rows.push(entry); continue; }
+    const node = byName.get(entry.name);
+    if (!node || isCapabilityHidden(node.name, config)) continue;
+    used.add(node.name);
+    rows.push({
+      name: node.name,
+      alias: node.aliases[0] || entry.alias || '',
+      desc: node.description || entry.desc || '',
+    });
+  }
+  return rows;
+}
+
+function renderFlags(options) {
+  // Derived from the registered global options, so a new global flag cannot be
+  // missing from help (--get and --csv were, along with the csv format choice).
+  const lines = [];
+  for (const spec of options) {
+    if (spec.name === 'help') continue;
+    const alias = spec.alias.length ? `-${spec.alias.join(', -')}, ` : '';
+    const suffix = spec.name === 'format' && spec.choices.length
+      ? ` [string: ${spec.choices.join(', ')}]`
+      : ` [${spec.type}]`;
+    lines.push(`  ${`${alias}--${spec.name}`.padEnd(24)}${spec.description}${suffix}`);
+  }
+  lines.push(`  ${'--help'.padEnd(24)}Show help${' [boolean]'}`);
+  return `\nFLAGS\n${lines.join('\n')}`;
 }
 
 function renderTips() {
@@ -150,35 +205,45 @@ function renderTips() {
 TIPS
   --query is available on every list command (e.g. "incidents list --query priority=1")
   Use "jsn <command> --help" for details, or "jsn <command> list --help" for list options
+  "jsn --json" prints the registered command surface as JSON for scripts and agents
 
 LEARN MORE
   Use "jsn <command> --help" for more information about a command.`;
 }
 
-export function renderHelp(config) {
-  // Domain separation is an optional plugin — only advertise `domains`
-  // when the active profile's capability probe found it installed.
-  const activeName = config?.activeProfile || config?.defaultProfile;
-  const hasDS = !!(activeName && config?.profiles?.[activeName]?.domain_separation);
-  const configCmds = hasDS
-    ? CONFIG_COMMANDS
-    : CONFIG_COMMANDS.filter((c) => !c.name || c.name !== 'domains');
-
-  const COMMAND_GROUPS_LOCAL = {
-    ...COMMAND_GROUPS,
-    'CONFIGURATION': configCmds,
-  };
-
-  const sections = Object.entries(COMMAND_GROUPS_LOCAL).map(([name, cmds]) => renderGroup(name, cmds));
+/**
+ * Render the grouped root help.
+ *
+ * @param {object} config — profile config (capability-conditioned hiding)
+ * @param {{commands: Array, options: Array}} [registry] — from
+ *   `cli.commandRegistry()`. Without it only the hint tables render, which is
+ *   the fallback for callers that have no registry (unit tests).
+ */
+export function renderHelp(config, registry = null) {
+  const commands = Array.isArray(registry?.commands) ? registry.commands : [];
+  const byName = new Map(commands.map((command) => [command.name, command]));
+  const used = new Set();
+
+  const sections = Object.entries(COMMAND_GROUPS)
+    .map(([name, hint]) => [name, rowsFor(hint, byName, used, config)])
+    .filter(([, rows]) => rows.some((row) => !row.divider))
+    .map(([name, rows]) => renderGroup(name, rows));
+
+  // Anything registered that the hint tables don't place. This is the safety
+  // net that keeps help complete as commands are added at the root.
+  const unplaced = commands
+    .filter((command) => !used.has(command.name) && !isCapabilityHidden(command.name, config))
+    .map((command) => ({ name: command.name, alias: command.aliases[0] || '', desc: command.description || '' }));
+  if (unplaced.length) sections.push(renderGroup('MORE', unplaced));
 
   return [
     'Usage: jsn <command> [options]',
     '',
-    `Command-line interface for ServiceNow`,
+    'Command-line interface for ServiceNow',
     '',
     ...sections,
     '',
-    renderFlags(),
+    renderFlags(Array.isArray(registry?.options) ? registry.options : []),
     renderTips(),
     '',
   ].join('\n');