@jacebenson/jsn 4.3.7-dev.39 → 4.3.7-dev.41

package/package.json

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

package/src/cli-adapter.js

@@ -24,11 +24,38 @@ class CommandNode {
     if (typeof this.definition.builder === 'function') this.definition.builder(this.api());
   }
 
+  /**
+   * Register a child, replacing any existing registration that claims the same
+   * canonical name (or that the new child claims as an alias).
+   *
+   * yargs semantics are last-registration-wins: a command module re-registers a
+   * subcommand to layer a specialized handler over the base one (see
+   * `requests show`). Appending instead of replacing left the base registration
+   * first in the list and reachable by dispatch/help while the duplicate was
+   * invisible to the registry (child counts, inventory, completion).
+   *
+   * Registration order is preserved (the slot is replaced in place) and the
+   * replaced node's aliases are carried over so layered commands keep resolving
+   * through the alias that the base registration published.
+   */
+  register(child) {
+    const index = this.children.findIndex((existing) => existing.name === child.name
+      || existing.aliases.includes(child.name)
+      || child.aliases.includes(existing.name));
+    if (index === -1) {
+      this.children.push(child);
+      return child;
+    }
+    child.aliases = [...new Set([...child.aliases, ...this.children[index].aliases])];
+    this.children[index] = child;
+    return child;
+  }
+
   api() {
     const node = this;
     return {
       command(definition, builder, handler) {
-        node.children.push(new CommandNode(typeof definition === 'string' ? { command: definition, builder, handler } : definition));
+        node.register(new CommandNode(typeof definition === 'string' ? { command: definition, builder, handler } : definition));
         return this;
       },
       option(name, config = {}) { node.options.set(name, { ...config, name }); return this; },
@@ -63,10 +90,16 @@ export class LocalCLI {
   option(name, config) { this.root.options.set(name, { ...config, name }); return this; }
   options(config) { for (const [name, value] of Object.entries(config)) this.option(name, value); return this; }
   command(definition, builder, handler) {
-    const node = new CommandNode(typeof definition === 'string' ? { command: definition, builder, handler } : definition);
-    this.root.children.push(node);
+    this.root.register(new CommandNode(typeof definition === 'string' ? { command: definition, builder, handler } : definition));
     return this;
   }
+  /**
+   * Register the fallback used when a parent command (a node with children) is
+   * invoked with no subcommand and declares no handler of its own. Without it
+   * those parents exited 0 having printed nothing, which reads as success to a
+   * script and as a hang to a human.
+   */
+  onParentDiscovery(fn) { this.parentDiscovery = fn; return this; }
   demandCommand(count, message) { this.root.demand = { count, message }; return this; }
   completion(name, _description, handler) { this.completionCommand = name; this.completionHandler = handler; return this; }
   help() { this.helpEnabled = true; return this; }
@@ -175,6 +208,54 @@ export class LocalCLI {
     if (this.failHandler) return this.failHandler(message, error);
     throw error || new Error(message);
   }
+  /**
+   * Describe the registered command surface: root commands (canonical name,
+   * aliases, describe, child names) and the global option declarations.
+   *
+   * This is the single source both the grouped root help and the machine
+   * discovery output are generated from, so neither can drift away from the
+   * commands that actually exist. Builders run here (idempotently) because a
+   * parent's children are only registered when its builder is invoked.
+   */
+  commandRegistry() {
+    const visible = (node) => node.name !== this.completionCommand;
+    const serialize = (node) => {
+      node.build();
+      return {
+        name: node.name,
+        command: node.definition.command || node.name,
+        aliases: [...node.aliases],
+        description: node.definition.describe || '',
+        subcommands: node.children.filter(visible).map((child) => child.name),
+      };
+    };
+    return {
+      commands: this.root.children.filter(visible).map(serialize),
+      options: [...this.root.options.values()].map((spec) => ({
+        name: spec.name,
+        alias: names(spec.alias),
+        description: spec.description || spec.describe || '',
+        choices: spec.choices || [],
+        type: spec.type || 'boolean',
+      })),
+    };
+  }
+
+  /** Structured child signatures for a parent node, built on demand. */
+  subcommandsOf(node) {
+    return node.children
+      .filter((child) => child.name !== this.completionCommand)
+      .map((child) => {
+        child.build();
+        return {
+          name: child.name,
+          command: child.definition.command || child.name,
+          aliases: [...child.aliases],
+          description: child.definition.describe || '',
+        };
+      });
+  }
+
   _help(node, path = []) {
     const lines = [node.usageText || `Usage: ${this.script} ${path.join(' ') || '<command>'}`];
     if (node.definition.describe) lines.push(`\n${node.definition.describe}`);
@@ -232,6 +313,11 @@ export class LocalCLI {
     const parsed = this._parseOptions(commandArgs, path);
     if (!parsed) return;
     const argv = parsed.values;
+    // A parent command's own children are registry-derived, so a default
+    // handler can list exactly what is registered instead of repeating a
+    // hand-written list that drifts (see the records parent, which advertised
+    // an `inspect` description the registration disagreed with).
+    if (node.children.length) argv.subcommands = this.subcommandsOf(node);
     const specs = [...this._optionConfig(path).values()];
     const positions = positionSpec(node.definition.command || '').map((position) => ({
       ...position, ...node.positionals.get(position.name), name: position.name,
@@ -242,7 +328,13 @@ export class LocalCLI {
     for (const middleware of this.middlewares) await middleware(argv);
     for (const commandNode of path) for (const middleware of commandNode.middlewares) await middleware(argv);
     if (node.definition.handler) await node.definition.handler(argv);
-    else if (node.demand?.count && !path.length) return this._fail(node.demand.message);
+    // A parent with no handler of its own used to fall through and exit 0
+    // with no output — indistinguishable from a command that ran and found
+    // nothing. The registered discovery hook (cli.js) prints the child
+    // surface instead: a JSON envelope in machine mode, a list for humans.
+    else if (path.length && argv.subcommands?.length && this.parentDiscovery) {
+      await this.parentDiscovery(argv, { path: path.map((n) => n.name), subcommands: argv.subcommands });
+    } else if (node.demand?.count && !path.length) return this._fail(node.demand.message);
   }
 }
 

package/src/cli.js

@@ -10,7 +10,8 @@ import { resolveSession, applySession } from './session.js';
 import { renderHelp } from './help.js';
 import { isMutationCommand, refreshMutationCommands } from './mutations.js';
 import { noInstanceCommands, dailyCheckSkipCommands } from './capabilities.js';
-import { guardExit, exitWithError } from './errors.js';
+import { guardExit, exitWithError, AppError, CodeUsage } from './errors.js';
+import { formatCommandList } from './helpers.js';
 
 // Command modules
 import { setupCmd } from './commands/setup.js';
@@ -73,6 +74,53 @@ import { midserversCmd } from './commands/midservers.js';
 import { diffCmd } from './commands/diff.js';
 import { graphqlCmd } from './commands/graphql.js';
 
+/**
+ * Did the caller explicitly ask for machine output?
+ *
+ * Read from the raw argv because parse-time failures happen BEFORE the format
+ * middleware can run, so `--json`/`--format=json` had not reached the output
+ * controller yet — which is exactly why the structured failure envelope was
+ * unreachable for the mistakes scripts and agents hit most (a missing required
+ * flag, a bad choice, an unknown command).
+ */
+function explicitJsonRequest(args) {
+  return args.some((arg, i) => {
+    if (arg === '--json') return true;
+    if (arg.startsWith('--json=')) return arg !== '--json=false';
+    if (arg === '--format=json') return true;
+    return arg === '--format' && args[i + 1] === 'json';
+  });
+}
+
+/**
+ * The output format the caller explicitly asked for, read from the raw argv.
+ *
+ * Same reason as explicitJsonRequest: the format middleware never runs for a
+ * parse-time failure, so an explicit `--format=styled` (human) or
+ * `--format=json` (machine) was silently ignored and the failure was rendered
+ * by the pipe/TTY default instead of what was asked for.
+ */
+function explicitFormat(args) {
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--json') return 'json';
+    if (arg === '--quiet' || arg === '-q') return 'quiet';
+    if (arg === '--styled') return 'styled';
+    if (arg === '--markdown') return 'markdown';
+    if (arg === '--csv') return 'csv';
+    if (arg.startsWith('--format=')) return arg.slice('--format='.length);
+    if (arg === '--format' && args[i + 1]) return args[i + 1];
+  }
+  return '';
+}
+
+/**
+ * Parent commands owned by another change. The adapter's discovery fallback
+ * (which gives a handler-less parent its child list instead of a silent exit 0)
+ * is skipped for these families so their own fix owns the behavior.
+ */
+const DISCOVERY_OWNED_ELSEWHERE = new Set(['auth', 'perf', 'skill', 'groupmembers', 'grouproles']);
+
 function wrap(handler) {
   return async (argv) => {
     try {
@@ -435,14 +483,33 @@ export function buildCLI() {
         cliInstance.showCompletionScript();
       },
     })
+    .onParentDiscovery((argv, { path, subcommands }) => {
+      // Reached only for a parent command that declares no default handler of
+      // its own (cmdb, platform, and any future parent) — the adapter used to
+      // fall through and exit 0 having printed nothing. Children come from the
+      // registry, description included, so this list cannot drift from the
+      // registrations the way a hand-written one did.
+      if (DISCOVERY_OWNED_ELSEWHERE.has(path[0])) return;
+      const canonical = path.join(' ');
+      const summary = `jsn ${canonical} — available subcommands.`;
+      (argv.app || app).ok({
+        command: canonical,
+        subcommands,
+        _formatted: formatCommandList({
+          title: `jsn ${canonical}`,
+          commands: subcommands,
+          footer: `Run "jsn ${canonical} <command> --help" for details.`,
+        }),
+      }, { summary });
+    })
     .help('help', 'Show help')
     .version(false)
     .strictCommands()
     .strictOptions(false)
     .fail((msg, err) => {
       if (err) throw err;
+      const raw = process.argv.slice(2);
       if (msg === 'You must specify a command') {
-        const raw = process.argv.slice(2);
         const hasLoneProfile = raw.some((a, i, arr) => {
           if (a !== '--profile' && a !== '-p') return false;
           const next = arr[i + 1];
@@ -458,11 +525,40 @@ export function buildCLI() {
           }
           process.exit(0);
         }
-        process.stdout.write(renderHelp(loadConfig()) + '\n');
+        // No command is a discovery request, not a failure: the human view
+        // stays exactly as it was (exit 0 + grouped help), and an explicit
+        // --json gets the same surface as machine-readable data instead of
+        // prose that a parser cannot read.
+        if (explicitJsonRequest(raw)) {
+          app.output.setFormat('json');
+          const { commands } = cliInstance.commandRegistry();
+          app.ok({ commands }, {
+            summary: `${commands.length} registered commands — run "jsn <command> --json" for a command's subcommands.`,
+          });
+          process.exit(0);
+        }
+        process.stdout.write(renderHelp(loadConfig(), cliInstance.commandRegistry()) + '\n');
         process.exit(0);
       }
-      process.stderr.write(msg + '\n');
-      process.exit(1);
+      // Every other failure here (unknown command, missing required argument,
+      // invalid choice/number) is a usage failure. Route it through the same
+      // renderer as handler and guard failures: exit 2, and the documented
+      // error envelope on stdout when the caller is in JSON mode. Previously
+      // this wrote raw prose to stderr and exited 1, so the exit code and the
+      // output shape depended on which layer rejected the command.
+      if (explicitJsonRequest(raw)) app.output.setFormat('json');
+      else {
+        const requestedFormat = explicitFormat(raw);
+        if (requestedFormat) app.output.setFormat(requestedFormat);
+      }
+      let hint;
+      try {
+        const path = cliInstance._findPath(raw).path.map((n) => n.name).join(' ');
+        hint = `Run "jsn ${path ? `${path} ` : ''}--help" for usage.`;
+      } catch {
+        hint = 'Run "jsn --help" for the command list.';
+      }
+      exitWithError(new AppError(CodeUsage, msg, hint), { app });
     });
 
   // Snapshot the root command names (plus aliases) for the completion

package/src/commands/cmdb.js

@@ -8,6 +8,7 @@
 import {
   assertSafeExactMatch,
   buildQuerySuffix,
+  formatCommandList,
   formatRecordForDisplay,
   getStringField,
   interactiveList,
@@ -351,6 +352,23 @@ export function cmdbCmd(wrap) {
   return {
     command: 'cmdb [subcommand]',
     describe: 'Query the Configuration Management Database (CMDB) — CIs and relationship traversal (read-only)',
+    // Parent discovery. Without a handler `jsn cmdb` exited 0 having printed
+    // nothing: a script reads that as success and a human as a hang. The child
+    // list comes from the registry (argv.subcommands), so it cannot drift from
+    // what is registered; the styled view is a side channel that JSON ignores.
+    handler: wrap(async (argv, app) => {
+      const subcommands = argv.subcommands || [];
+      const summary = 'Query the Configuration Management Database (CMDB): CI lookup and relationship traversal. Read-only.';
+      app.ok({
+        command: 'cmdb',
+        subcommands,
+        _formatted: formatCommandList({
+          title: summary,
+          commands: subcommands,
+          footer: 'Run "jsn cmdb <command> --help" for details.',
+        }),
+      }, { summary });
+    }),
     builder: (yargs) => {
       return yargs
         .command({

package/src/commands/docs/docs.js

@@ -15,6 +15,7 @@ import { searchDocs, getDocByIdOrPath } from './search.js';
 import { serveDocs } from './serve.js';
 import { syncCommunity, listCommunityDocs } from './community.js';
 import { declareCapabilities } from '../../capabilities.js';
+import { formatCommandList } from '../../helpers.js';
 
 declareCapabilities('docs', { noInstance: true, skipDailyChecks: true });
 
@@ -256,21 +257,22 @@ export function docsCmd(wrap) {
             .demandCommand(1, 'Specify an action: sync or list'),
         });
     },
-    handler: () => {
-      process.stdout.write('jsn docs — ServiceNow documentation search\n\n');
-      process.stdout.write('Available subcommands:\n');
-      process.stdout.write('  sync      Download docs and build a searchable index (handles updates too)\n');
-      process.stdout.write('  status    Show whether docs are downloaded, indexed, embedded, or served\n');
-      process.stdout.write('  search    Full-text + semantic search across the local docs index\n');
-      process.stdout.write('  show      Display a full documentation page by id or path\n');
-      process.stdout.write('  serve     Start a local web UI for browsing and searching docs\n');
-      process.stdout.write('  community Sync ServiceNow Community articles (hubs + linked posts) into the index\n');
-      process.stdout.write('\n');
-      process.stdout.write('Tip: use "jsn docs serve --expose" to bind to 0.0.0.0 and share on your network.\n');
-      process.stdout.write('\n');
-      const dbPath = getDocsDbPath();
-      process.stdout.write(`Docs DB: ${dbPath} (run "jsn docs status" for details, or query directly with sqlite3)\n`);
-      process.stdout.write('\nRun "jsn docs <command> --help" for details.\n');
-    },
+    handler: wrap(async (argv, app) => {
+      const subcommands = argv.subcommands || [];
+      const summary = 'jsn docs — ServiceNow documentation search (sync, status, search, show, serve).';
+      app.ok({
+        command: 'docs',
+        subcommands,
+        _formatted: formatCommandList({
+          title: summary,
+          commands: subcommands,
+          footer: [
+            'Tip: use "jsn docs serve --expose" to bind to 0.0.0.0 and share on your network.',
+            `Docs DB: ${getDocsDbPath()} (run "jsn docs status" for details, or query directly with sqlite3)`,
+            'Run "jsn docs <command> --help" for details.',
+          ].join('\n'),
+        }),
+      }, { summary });
+    }),
   };
 }

package/src/commands/flows.js

@@ -6,6 +6,7 @@ import { inspectFlow } from '../flow-inspection.js';
 import { publishFlows, publishFlowLifecycle, publishDoctor, flowStatus } from '../flow-publish.js';
 import { resolveRecord, unwrapSysId } from '../resolve-record.js';
 import { createFlowFromManifest, updateFlowFromManifest, readCurrentUpdateSet } from '../flow-create.js';
+import { EXCLUDED_TRIGGER_TYPES, SUPPORTED_TRIGGER_TYPES } from '../flow-triggers.js';
 import { testFlow } from '../flow-test.js';
 import { errUsage } from '../errors.js';
 import { cancelled, pickDesignerRecord, guidedFlowCreate, guidedFlowEdit, guidedFlowTestRecord, hasDefinitionData, confirmDesignerMutation } from '../flow-designer-interactive.js';
@@ -32,6 +33,18 @@ function flowInspectionAdapter(app) {
   };
 }
 
+// The picker is driven by the instance's own trigger definitions, but this CLI
+// can only create the families it has verified. State both plainly so a created
+// flow never surprises the operator with a trigger that was not really set.
+function triggerGuidance(trigger) {
+  return {
+    supported_families: [...SUPPORTED_TRIGGER_TYPES].sort(),
+    excluded_families: [...EXCLUDED_TRIGGER_TYPES.entries()].map(([type, reason]) => ({ type, reason })).sort((a, b) => a.type.localeCompare(b.type)),
+    created_trigger: trigger ? { id: trigger.id, type: trigger.type, name: trigger.name, triggerDefinitionId: trigger.triggerDefinitionId } : null,
+    note: 'The trigger picker lists only families this CLI can create and verify. Families the picker omits are reported in excluded_families.',
+  };
+}
+
 declareCapabilities('flows', { mutationSubcommands: ['create', 'update', 'edit', 'delete', 'publish', 'test'] });
 
 function renderChecks(checks) {
@@ -281,10 +294,11 @@ export function flowsCmd(wrap) {
         })
         .command({
           command: 'create',
-          describe: 'Guide draft flow creation in a terminal, or use a schema-driven JSON manifest',
+          describe: 'Create a draft flow: pick a trigger category then trigger in a terminal, or use a JSON manifest in scripts',
           builder: (y) => y
             .option('data', { type: 'string', describe: 'Flow manifest as inline JSON' })
-            .option('data-file', { type: 'string', describe: 'Read the flow manifest from a JSON file' }),
+            .option('data-file', { type: 'string', describe: 'Read the flow manifest from a JSON file' })
+            .option('scope', { type: 'string', describe: 'Transaction scope sys_id or global for the guided picker' }),
           handler: wrap(async (argv, app) => {
             app.requireInstance();
             const dataFile = argv.dataFile ?? argv['data-file'];
@@ -299,8 +313,8 @@ export function flowsCmd(wrap) {
             const result = await createFlowFromManifest(app.sdk, app.getEffectiveInstance(), manifest, {
               readUpdateSet: () => readCurrentUpdateSet(app.sdk),
             });
-            app.ok(result, {
-              summary: `Created draft flow "${result.flow.name}" (${result.flow.id}) without activation`,
+            app.ok({ ...result, trigger_guidance: triggerGuidance(result.trigger) }, {
+              summary: `Created draft flow "${result.flow.name}" (${result.flow.id}) with trigger ${result.trigger?.type ?? 'unknown'} (${result.trigger?.id ?? 'no trigger id'}) without activation`,
               breadcrumbs: [{ action: 'show', cmd: `jsn flows show ${result.flow.id}`, description: 'Inspect the draft flow' }],
             });
           }),

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/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,6 +119,24 @@ 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).
@@ -152,12 +171,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 +228,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') {