@optique/core 1.4.0-dev.2733 → 1.4.0-dev.2740

package/dist/constructs.cjs

@@ -1,4 +1,5 @@
 const require_internal_annotations = require('./internal/annotations.cjs');
+const require_internal_command_doc_policy = require('./internal/command-doc-policy.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_message = require('./message.cjs');
@@ -1187,7 +1188,8 @@ function isUnselectedBooleanOptionState(state) {
 	return state != null && typeof state === "object" && "success" in state && state.success === true && "value" in state && state.value === false;
 }
 function preserveExclusiveStateAfterOptionsTerminator(context, result) {
-	const mergedExec = require_execution_context.mergeChildExec(context.exec, result.next.exec);
+	const childExec = require_execution_context.mergeChildExec(context.exec, result.next.exec);
+	const mergedExec = childExec == null ? childExec : require_internal_command_doc_policy.mergeCommandDocPolicy(context.exec, context.exec, childExec);
 	return {
 		success: true,
 		next: {
@@ -1528,7 +1530,7 @@ function or(...args) {
 		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
 		for (const { parser, index: i, state: childState } of orderedParsers) {
-			const childContext = withChildContext$1(require_short_option.forkOptionScope(context), i, childState, parser);
+			const childContext = withChildContext$1(require_short_option.forkOptionScope(commandDocBranchContext(context, activeState?.[0], i)), i, childState, parser);
 			const result = parser.parse(childContext);
 			if (result.success && result.consumed.length === 0) {
 				const own = require_passthrough.retainConsumingFailureHint(void 0, childContext, result.next);
@@ -1583,7 +1585,7 @@ function or(...args) {
 					}
 					const previouslyConsumed = activeState[1].consumed;
 					const checkResult = parser.parse({
-						...withChildContext$1(context, i, parser.initialState, parser),
+						...withChildContext$1(commandDocBranchContext(context, activeState?.[0], i), i, parser.initialState, parser),
 						buffer: previouslyConsumed
 					});
 					const canConsumeShared = checkResult.success && checkResult.consumed.length === previouslyConsumed.length && checkResult.consumed.every((c, idx) => c === previouslyConsumed[idx]);
@@ -1686,7 +1688,7 @@ function or(...args) {
 			if (activeState != null && activeState[1].success) {
 				const previouslyConsumed = activeState[1].consumed;
 				const checkResult = provisionalConsuming.parser.parse({
-					...withChildContext$1(require_short_option.forkOptionScope(context), provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
+					...withChildContext$1(require_short_option.forkOptionScope(commandDocBranchContext(context, activeState?.[0], provisionalConsuming.index)), provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
 					buffer: previouslyConsumed
 				});
 				const canConsumeShared = checkResult.success && checkResult.consumed.length === previouslyConsumed.length && checkResult.consumed.every((c, idx) => c === previouslyConsumed[idx]);
@@ -1737,7 +1739,7 @@ function or(...args) {
 		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
 		for (const { parser, index: i, state: childState } of orderedParsers) {
-			const childContext = withChildContext$1(require_short_option.forkOptionScope(context), i, childState, parser);
+			const childContext = withChildContext$1(require_short_option.forkOptionScope(commandDocBranchContext(context, activeState?.[0], i)), i, childState, parser);
 			const resultOrPromise = parser.parse(childContext);
 			const result = await resultOrPromise;
 			if (result.success && result.consumed.length === 0) {
@@ -1793,7 +1795,7 @@ function or(...args) {
 					}
 					const previouslyConsumed = activeState[1].consumed;
 					const checkResultOrPromise = parser.parse({
-						...withChildContext$1(context, i, parser.initialState, parser),
+						...withChildContext$1(commandDocBranchContext(context, activeState?.[0], i), i, parser.initialState, parser),
 						buffer: previouslyConsumed
 					});
 					const checkResult = await checkResultOrPromise;
@@ -1898,7 +1900,7 @@ function or(...args) {
 			if (activeState != null && activeState[1].success) {
 				const previouslyConsumed = activeState[1].consumed;
 				const checkResult = await provisionalConsuming.parser.parse({
-					...withChildContext$1(require_short_option.forkOptionScope(context), provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
+					...withChildContext$1(require_short_option.forkOptionScope(commandDocBranchContext(context, activeState?.[0], provisionalConsuming.index)), provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
 					buffer: previouslyConsumed
 				});
 				const canConsumeShared = checkResult.success && checkResult.consumed.length === previouslyConsumed.length && checkResult.consumed.every((c, idx) => c === previouslyConsumed[idx]);
@@ -2114,7 +2116,7 @@ function createLongestMatch(...args) {
 		let error = getInitialError(context);
 		let consumingFailure;
 		for (const { parser, index: i, state: childState } of selectExclusiveChildren(syncParsers, context.state)) {
-			const childContext = withChildContext$1(require_short_option.forkOptionScope(context), i, childState, parser);
+			const childContext = withChildContext$1(require_short_option.forkOptionScope(commandDocBranchContext(context, normalizeExclusiveState(context.state)?.[0], i)), i, childState, parser);
 			const result = parser.parse(childContext);
 			if (isOptionsTerminatorOnlyResult(context, result)) {
 				optionsTerminatorMatches.push({
@@ -2152,7 +2154,7 @@ function createLongestMatch(...args) {
 		let error = getInitialError(context);
 		let consumingFailure;
 		for (const { parser, index: i, state: childState } of selectExclusiveChildren(parsers, context.state)) {
-			const childContext = withChildContext$1(require_short_option.forkOptionScope(context), i, childState, parser);
+			const childContext = withChildContext$1(require_short_option.forkOptionScope(commandDocBranchContext(context, normalizeExclusiveState(context.state)?.[0], i)), i, childState, parser);
 			const resultOrPromise = parser.parse(childContext);
 			const result = await resultOrPromise;
 			if (isOptionsTerminatorOnlyResult(context, result)) {
@@ -7953,6 +7955,14 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		}
 	}));
 }
+function commandDocBranchContext(context, activeIndex, nextIndex) {
+	if (activeIndex == null || activeIndex === nextIndex) return context;
+	const exec = require_internal_command_doc_policy.withoutCommandDocPolicySubtree(context.exec, [...context.exec?.path ?? [], activeIndex]);
+	return exec === context.exec ? context : {
+		...context,
+		exec
+	};
+}
 
 //#endregion
 exports.DuplicateOptionError = DuplicateOptionError;

package/dist/constructs.js

@@ -1,4 +1,5 @@
 import { annotateFreshArray, getAnnotations, inheritAnnotations } from "./internal/annotations.js";
+import { mergeCommandDocPolicy, withoutCommandDocPolicySubtree } from "./internal/command-doc-policy.js";
 import { validateLabel } from "./validate.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames, isDocHidden, mergeHidden } from "./usage.js";
 import { message, optionName, text, values } from "./message.js";
@@ -1187,7 +1188,8 @@ function isUnselectedBooleanOptionState(state) {
 	return state != null && typeof state === "object" && "success" in state && state.success === true && "value" in state && state.value === false;
 }
 function preserveExclusiveStateAfterOptionsTerminator(context, result) {
-	const mergedExec = mergeChildExec(context.exec, result.next.exec);
+	const childExec = mergeChildExec(context.exec, result.next.exec);
+	const mergedExec = childExec == null ? childExec : mergeCommandDocPolicy(context.exec, context.exec, childExec);
 	return {
 		success: true,
 		next: {
@@ -1528,7 +1530,7 @@ function or(...args) {
 		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
 		for (const { parser, index: i, state: childState } of orderedParsers) {
-			const childContext = withChildContext$1(forkOptionScope(context), i, childState, parser);
+			const childContext = withChildContext$1(forkOptionScope(commandDocBranchContext(context, activeState?.[0], i)), i, childState, parser);
 			const result = parser.parse(childContext);
 			if (result.success && result.consumed.length === 0) {
 				const own = retainConsumingFailureHint(void 0, childContext, result.next);
@@ -1583,7 +1585,7 @@ function or(...args) {
 					}
 					const previouslyConsumed = activeState[1].consumed;
 					const checkResult = parser.parse({
-						...withChildContext$1(context, i, parser.initialState, parser),
+						...withChildContext$1(commandDocBranchContext(context, activeState?.[0], i), i, parser.initialState, parser),
 						buffer: previouslyConsumed
 					});
 					const canConsumeShared = checkResult.success && checkResult.consumed.length === previouslyConsumed.length && checkResult.consumed.every((c, idx) => c === previouslyConsumed[idx]);
@@ -1686,7 +1688,7 @@ function or(...args) {
 			if (activeState != null && activeState[1].success) {
 				const previouslyConsumed = activeState[1].consumed;
 				const checkResult = provisionalConsuming.parser.parse({
-					...withChildContext$1(forkOptionScope(context), provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
+					...withChildContext$1(forkOptionScope(commandDocBranchContext(context, activeState?.[0], provisionalConsuming.index)), provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
 					buffer: previouslyConsumed
 				});
 				const canConsumeShared = checkResult.success && checkResult.consumed.length === previouslyConsumed.length && checkResult.consumed.every((c, idx) => c === previouslyConsumed[idx]);
@@ -1737,7 +1739,7 @@ function or(...args) {
 		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
 		for (const { parser, index: i, state: childState } of orderedParsers) {
-			const childContext = withChildContext$1(forkOptionScope(context), i, childState, parser);
+			const childContext = withChildContext$1(forkOptionScope(commandDocBranchContext(context, activeState?.[0], i)), i, childState, parser);
 			const resultOrPromise = parser.parse(childContext);
 			const result = await resultOrPromise;
 			if (result.success && result.consumed.length === 0) {
@@ -1793,7 +1795,7 @@ function or(...args) {
 					}
 					const previouslyConsumed = activeState[1].consumed;
 					const checkResultOrPromise = parser.parse({
-						...withChildContext$1(context, i, parser.initialState, parser),
+						...withChildContext$1(commandDocBranchContext(context, activeState?.[0], i), i, parser.initialState, parser),
 						buffer: previouslyConsumed
 					});
 					const checkResult = await checkResultOrPromise;
@@ -1898,7 +1900,7 @@ function or(...args) {
 			if (activeState != null && activeState[1].success) {
 				const previouslyConsumed = activeState[1].consumed;
 				const checkResult = await provisionalConsuming.parser.parse({
-					...withChildContext$1(forkOptionScope(context), provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
+					...withChildContext$1(forkOptionScope(commandDocBranchContext(context, activeState?.[0], provisionalConsuming.index)), provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
 					buffer: previouslyConsumed
 				});
 				const canConsumeShared = checkResult.success && checkResult.consumed.length === previouslyConsumed.length && checkResult.consumed.every((c, idx) => c === previouslyConsumed[idx]);
@@ -2114,7 +2116,7 @@ function createLongestMatch(...args) {
 		let error = getInitialError(context);
 		let consumingFailure;
 		for (const { parser, index: i, state: childState } of selectExclusiveChildren(syncParsers, context.state)) {
-			const childContext = withChildContext$1(forkOptionScope(context), i, childState, parser);
+			const childContext = withChildContext$1(forkOptionScope(commandDocBranchContext(context, normalizeExclusiveState(context.state)?.[0], i)), i, childState, parser);
 			const result = parser.parse(childContext);
 			if (isOptionsTerminatorOnlyResult(context, result)) {
 				optionsTerminatorMatches.push({
@@ -2152,7 +2154,7 @@ function createLongestMatch(...args) {
 		let error = getInitialError(context);
 		let consumingFailure;
 		for (const { parser, index: i, state: childState } of selectExclusiveChildren(parsers, context.state)) {
-			const childContext = withChildContext$1(forkOptionScope(context), i, childState, parser);
+			const childContext = withChildContext$1(forkOptionScope(commandDocBranchContext(context, normalizeExclusiveState(context.state)?.[0], i)), i, childState, parser);
 			const resultOrPromise = parser.parse(childContext);
 			const result = await resultOrPromise;
 			if (isOptionsTerminatorOnlyResult(context, result)) {
@@ -7953,6 +7955,14 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		}
 	}));
 }
+function commandDocBranchContext(context, activeIndex, nextIndex) {
+	if (activeIndex == null || activeIndex === nextIndex) return context;
+	const exec = withoutCommandDocPolicySubtree(context.exec, [...context.exec?.path ?? [], activeIndex]);
+	return exec === context.exec ? context : {
+		...context,
+		exec
+	};
+}
 
 //#endregion
 export { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, seq, tuple };

package/dist/doc.cjs

@@ -350,13 +350,13 @@ function formatDocPage(programName, page, options = {}) {
 		}
 		return rendered;
 	};
-	const usageLabel = page.usage != null && options.showUsage !== false ? require_text_layout.spaceAfterLabel(label("Usage:", "usage")) : "";
+	const showUsage = options.showUsage ?? page.showUsage ?? true;
+	const usageLabel = page.usage != null && showUsage ? require_text_layout.spaceAfterLabel(label("Usage:", "usage")) : "";
 	const usageLabelWidth = require_text_layout.measureText(usageLabel).lastLineWidth;
 	const defaultStyle = require_terminal_internal.styleCode(options.theme?.annotationStyles?.default ?? { dim: true });
 	const choicesStyle = require_terminal_internal.styleCode(options.theme?.annotationStyles?.choices ?? { dim: true });
 	require_validate.validateProgramName(programName);
 	const termIndent = options.termIndent ?? 2;
-	const showUsage = options.showUsage ?? true;
 	if (options.maxWidth != null && (!Number.isFinite(options.maxWidth) || !Number.isInteger(options.maxWidth))) throw new TypeError(`maxWidth must be a finite integer, got ${options.maxWidth}.`);
 	const filteredSections = page.sections.map((s) => ({
 		...s,

package/dist/doc.d.cts

@@ -77,6 +77,13 @@ interface EnvironmentBindingDoc {
  * for commands, options, and other related information.
  */
 interface DocPage {
+  /**
+   * Default visibility of the usage synopsis for this page.
+   * Explicit formatter options override this value; omission defaults to true.
+   * Runner-produced pages include the selected command or runner setting.
+   * @since 1.4.0
+   */
+  readonly showUsage?: boolean;
   /** Independent environment documentation in this page's scope. @since 1.4.0 */
   readonly environmentBindings?: readonly EnvironmentBindingDoc[];
   readonly brief?: Message;
@@ -339,9 +346,10 @@ interface DocPageFormatOptions {
    */
   maxWidth?: number;
   /**
-   * Whether to include the usage synopsis in the output.
+   * Whether to include the usage synopsis in the output. Overrides the
+   * page's `showUsage` default when supplied.
    *
-   * @default `true`
+   * @default The page default, or `true` when it is omitted.
    * @since 1.2.0
    */
   showUsage?: boolean;

package/dist/doc.d.ts

@@ -77,6 +77,13 @@ interface EnvironmentBindingDoc {
  * for commands, options, and other related information.
  */
 interface DocPage {
+  /**
+   * Default visibility of the usage synopsis for this page.
+   * Explicit formatter options override this value; omission defaults to true.
+   * Runner-produced pages include the selected command or runner setting.
+   * @since 1.4.0
+   */
+  readonly showUsage?: boolean;
   /** Independent environment documentation in this page's scope. @since 1.4.0 */
   readonly environmentBindings?: readonly EnvironmentBindingDoc[];
   readonly brief?: Message;
@@ -339,9 +346,10 @@ interface DocPageFormatOptions {
    */
   maxWidth?: number;
   /**
-   * Whether to include the usage synopsis in the output.
+   * Whether to include the usage synopsis in the output. Overrides the
+   * page's `showUsage` default when supplied.
    *
-   * @default `true`
+   * @default The page default, or `true` when it is omitted.
    * @since 1.2.0
    */
   showUsage?: boolean;

package/dist/doc.js

@@ -350,13 +350,13 @@ function formatDocPage(programName, page, options = {}) {
 		}
 		return rendered;
 	};
-	const usageLabel = page.usage != null && options.showUsage !== false ? spaceAfterLabel(label("Usage:", "usage")) : "";
+	const showUsage = options.showUsage ?? page.showUsage ?? true;
+	const usageLabel = page.usage != null && showUsage ? spaceAfterLabel(label("Usage:", "usage")) : "";
 	const usageLabelWidth = measureText(usageLabel).lastLineWidth;
 	const defaultStyle = styleCode(options.theme?.annotationStyles?.default ?? { dim: true });
 	const choicesStyle = styleCode(options.theme?.annotationStyles?.choices ?? { dim: true });
 	validateProgramName(programName);
 	const termIndent = options.termIndent ?? 2;
-	const showUsage = options.showUsage ?? true;
 	if (options.maxWidth != null && (!Number.isFinite(options.maxWidth) || !Number.isInteger(options.maxWidth))) throw new TypeError(`maxWidth must be a finite integer, got ${options.maxWidth}.`);
 	const filteredSections = page.sections.map((s) => ({
 		...s,

package/dist/execution-context.cjs

@@ -1,3 +1,4 @@
+const require_internal_command_doc_policy = require('./internal/command-doc-policy.cjs');
 const require_short_option = require('./short-option.cjs');
 
 //#region src/execution-context.ts
@@ -19,7 +20,7 @@ function withChildExecPath(exec, segment) {
 function mergeChildExec(parent, child) {
 	if (parent == null) return child;
 	if (child == null) return parent;
-	return {
+	return require_internal_command_doc_policy.mergeCommandDocPolicy(parent, child, {
 		...parent,
 		trace: child.trace ?? parent.trace,
 		dependencyRuntime: child.dependencyRuntime ?? parent.dependencyRuntime,
@@ -27,7 +28,7 @@ function mergeChildExec(parent, child) {
 		commandPath: child.commandPath ?? parent.commandPath,
 		preCompletedByParser: child.preCompletedByParser ?? parent.preCompletedByParser,
 		excludedSourceFields: child.excludedSourceFields ?? parent.excludedSourceFields
-	};
+	});
 }
 /**
 * Creates a child parser context while keeping flat and nested execution data

package/dist/execution-context.js

@@ -1,3 +1,4 @@
+import { mergeCommandDocPolicy } from "./internal/command-doc-policy.js";
 import { withOptionScopeChild } from "./short-option.js";
 
 //#region src/execution-context.ts
@@ -19,7 +20,7 @@ function withChildExecPath(exec, segment) {
 function mergeChildExec(parent, child) {
 	if (parent == null) return child;
 	if (child == null) return parent;
-	return {
+	return mergeCommandDocPolicy(parent, child, {
 		...parent,
 		trace: child.trace ?? parent.trace,
 		dependencyRuntime: child.dependencyRuntime ?? parent.dependencyRuntime,
@@ -27,7 +28,7 @@ function mergeChildExec(parent, child) {
 		commandPath: child.commandPath ?? parent.commandPath,
 		preCompletedByParser: child.preCompletedByParser ?? parent.preCompletedByParser,
 		excludedSourceFields: child.excludedSourceFields ?? parent.excludedSourceFields
-	};
+	});
 }
 /**
 * Creates a child parser context while keeping flat and nested execution data

package/dist/facade.cjs

@@ -545,14 +545,13 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 		if (completionParser) {
 			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 			const doc = require_internal_parser.getDocPage(completionParser, [displayName]);
-			if (doc) stderr(require_doc.formatDocPage(programName, doc, completionDocOptions({
+			if (doc) stderr(require_doc.formatDocPage(programName, withDocShowUsage(doc, showUsage), completionDocOptions({
 				messageFormatter,
 				theme,
 				colors,
 				maxWidth,
 				termWidth,
-				sectionOrder,
-				showUsage
+				sectionOrder
 			})));
 		}
 		if (!wroteError) writeError();
@@ -1024,7 +1023,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
 						}, commandList, isTopLevel);
 						const groupedDoc = applyHelpSections(augmentedDoc, helpSections);
-						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine) : groupedDoc;
+						const renderedDoc = withDocShowUsage(isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine) : groupedDoc, showUsage);
 						stdout(require_doc.formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
@@ -1035,8 +1034,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							showChoices,
 							showAliases,
 							showEnvironment,
-							sectionOrder,
-							showUsage
+							sectionOrder
 						})));
 						return onHelp(0, renderedDoc);
 					}
@@ -1103,7 +1101,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						}, commandList, isTopLevel);
 						const defaultRootUsage = typeof usageLine === "function" && (options.help || options.version || options.completion) ? require_usage.normalizeUsage(getRootHelpGeneratorParser().usage) : augmentedDoc.usage ?? [];
 						const groupedDoc = applyHelpSections(augmentedDoc, helpSections);
-						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine, defaultRootUsage) : groupedDoc;
+						const renderedDoc = withDocShowUsage(isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine, defaultRootUsage) : groupedDoc, showUsage);
 						stderr(require_doc.formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
@@ -1114,8 +1112,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							showChoices,
 							showAliases,
 							showEnvironment,
-							sectionOrder,
-							showUsage
+							sectionOrder
 						})));
 					}
 					if (effectiveAboveError === "usage") {
@@ -1223,6 +1220,13 @@ function runParserAsync(parser, programName, args, options) {
 	const result = runParser(parser, programName, args, options);
 	return Promise.resolve(result);
 }
+function withDocShowUsage(page, fallback) {
+	const showUsage = page.showUsage ?? fallback;
+	return showUsage == null ? page : {
+		...page,
+		showUsage
+	};
+}
 function applyUsageLine(doc, usageLine, defaultUsageLine = doc.usage ?? []) {
 	const customUsageLine = typeof usageLine === "function" ? usageLine(require_usage.cloneUsage(defaultUsageLine)) : usageLine;
 	return {

package/dist/facade.d.cts

@@ -172,7 +172,8 @@ interface RunOptions<THelp, TError> {
    */
   readonly showEnvironment?: boolean | ShowEnvironmentOptions;
   /**
-   * Whether to include the usage synopsis in full help output.
+   * Default visibility of the usage synopsis in full help output.
+   * Command-level `showUsage` settings override this default.
    *
    * This affects help pages produced by `--help`, the help command, and
    * `aboveError: "help"`.  It does not suppress usage-only error preambles
@@ -242,8 +243,8 @@ interface RunOptions<THelp, TError> {
      * page passed to {@link formatDocPage}. Treat the page as read-only.
      * It includes runner-provided entries and root usage customization.
      * Subcommand and meta-command help use the selected command's docs,
-     * with the run-level footer as a fallback. Formatting options remain
-     * separate from the page.
+     * with the run-level footer as a fallback. The resolved `showUsage`
+     * default is included in the page; other formatting options remain separate.
      *
      * Handlers may ignore either argument. Wrappers that invoke this
      * callback themselves must forward both arguments.

package/dist/facade.d.ts

@@ -172,7 +172,8 @@ interface RunOptions<THelp, TError> {
    */
   readonly showEnvironment?: boolean | ShowEnvironmentOptions;
   /**
-   * Whether to include the usage synopsis in full help output.
+   * Default visibility of the usage synopsis in full help output.
+   * Command-level `showUsage` settings override this default.
    *
    * This affects help pages produced by `--help`, the help command, and
    * `aboveError: "help"`.  It does not suppress usage-only error preambles
@@ -242,8 +243,8 @@ interface RunOptions<THelp, TError> {
      * page passed to {@link formatDocPage}. Treat the page as read-only.
      * It includes runner-provided entries and root usage customization.
      * Subcommand and meta-command help use the selected command's docs,
-     * with the run-level footer as a fallback. Formatting options remain
-     * separate from the page.
+     * with the run-level footer as a fallback. The resolved `showUsage`
+     * default is included in the page; other formatting options remain separate.
      *
      * Handlers may ignore either argument. Wrappers that invoke this
      * callback themselves must forward both arguments.

package/dist/facade.js

@@ -545,14 +545,13 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 		if (completionParser) {
 			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 			const doc = getDocPage(completionParser, [displayName]);
-			if (doc) stderr(formatDocPage(programName, doc, completionDocOptions({
+			if (doc) stderr(formatDocPage(programName, withDocShowUsage(doc, showUsage), completionDocOptions({
 				messageFormatter,
 				theme,
 				colors,
 				maxWidth,
 				termWidth,
-				sectionOrder,
-				showUsage
+				sectionOrder
 			})));
 		}
 		if (!wroteError) writeError();
@@ -1024,7 +1023,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
 						}, commandList, isTopLevel);
 						const groupedDoc = applyHelpSections(augmentedDoc, helpSections);
-						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine) : groupedDoc;
+						const renderedDoc = withDocShowUsage(isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine) : groupedDoc, showUsage);
 						stdout(formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
@@ -1035,8 +1034,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							showChoices,
 							showAliases,
 							showEnvironment,
-							sectionOrder,
-							showUsage
+							sectionOrder
 						})));
 						return onHelp(0, renderedDoc);
 					}
@@ -1103,7 +1101,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						}, commandList, isTopLevel);
 						const defaultRootUsage = typeof usageLine === "function" && (options.help || options.version || options.completion) ? normalizeUsage(getRootHelpGeneratorParser().usage) : augmentedDoc.usage ?? [];
 						const groupedDoc = applyHelpSections(augmentedDoc, helpSections);
-						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine, defaultRootUsage) : groupedDoc;
+						const renderedDoc = withDocShowUsage(isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine, defaultRootUsage) : groupedDoc, showUsage);
 						stderr(formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
@@ -1114,8 +1112,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							showChoices,
 							showAliases,
 							showEnvironment,
-							sectionOrder,
-							showUsage
+							sectionOrder
 						})));
 					}
 					if (effectiveAboveError === "usage") {
@@ -1223,6 +1220,13 @@ function runParserAsync(parser, programName, args, options) {
 	const result = runParser(parser, programName, args, options);
 	return Promise.resolve(result);
 }
+function withDocShowUsage(page, fallback) {
+	const showUsage = page.showUsage ?? fallback;
+	return showUsage == null ? page : {
+		...page,
+		showUsage
+	};
+}
 function applyUsageLine(doc, usageLine, defaultUsageLine = doc.usage ?? []) {
 	const customUsageLine = typeof usageLine === "function" ? usageLine(cloneUsage(defaultUsageLine)) : usageLine;
 	return {