docs(api): regenerate documentation

Author: Xunnamius

docs/api/src/exports/classes/CliError.md

@@ -6,7 +6,7 @@
 
 # Class: CliError
 
-Defined in: [src/error.ts:132](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/error.ts#L132)
+Defined in: [src/error.ts:141](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/error.ts#L141)
 
 Represents a CLI-specific error with suggested exit code and other
 properties. As `CliError` has built-in support for cause chaining, this class
@@ -32,7 +32,7 @@ can be used as a simple wrapper around other errors.
 
 > **new CliError**(`reason`?, `options`?): [`CliError`](CliError.md)
 
-Defined in: [src/error.ts:142](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/error.ts#L142)
+Defined in: [src/error.ts:151](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/error.ts#L151)
 
 Represents a CLI-specific error, optionally with suggested exit code and
 other context.
@@ -59,7 +59,7 @@ other context.
 
 > **new CliError**(`reason`, `options`, `message`, `superOptions`): [`CliError`](CliError.md)
 
-Defined in: [src/error.ts:147](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/error.ts#L147)
+Defined in: [src/error.ts:156](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/error.ts#L156)
 
 This constructor syntax is used by subclasses when calling this constructor
 via `super`.
@@ -96,7 +96,7 @@ via `super`.
 
 > **\[$type\]**: `string`[]
 
-Defined in: [src/error.ts:137](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/error.ts#L137)
+Defined in: [src/error.ts:146](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/error.ts#L146)
 
 ***
 
@@ -120,7 +120,7 @@ Defined in: node\_modules/typescript/lib/lib.es2022.error.d.ts:26
 
 > **dangerouslyFatal**: `boolean` = `false`
 
-Defined in: [src/error.ts:135](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/error.ts#L135)
+Defined in: [src/error.ts:144](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/error.ts#L144)
 
 This option is similar in intent to yargs's `exitProcess()` function,
 except applied more granularly.
@@ -177,13 +177,20 @@ Defined in: node\_modules/typescript/lib/lib.es5.d.ts:1076
 
 ### showHelp
 
-> **showHelp**: `boolean` = `false`
+> **showHelp**: `undefined` \| `boolean` \| `"full"` \| `"short"` \| `"default"`
 
-Defined in: [src/error.ts:134](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/error.ts#L134)
+Defined in: [src/error.ts:143](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/error.ts#L143)
 
-If `true`, help text will be sent to stderr _before this exception finishes
-bubbling_. Where the exception is thrown will determine which instance is
-responsible for error text generation.
+If truthy, help text will be sent to stderr _before this exception finishes
+bubbling_.
+
+Specifically, if `showHelp` is set to `"full"`, the full help text will be
+sent to stderr, including the entire `usage` string. If set to `"short"`
+(or `true`), the same help text will be sent to stderr except only the
+first line of usage will be included. If set to `"default"`, the value of
+`ExecutionContext::state.showHelpOnFail` will be used. If set to
+`false` (the default), no help text will be sent to stderr related to this
+error.
 
 #### Default
 
@@ -213,7 +220,7 @@ Defined in: node\_modules/typescript/lib/lib.es5.d.ts:1078
 
 > **suggestedExitCode**: [`FrameworkExitCode`](../enumerations/FrameworkExitCode.md) = `FrameworkExitCode.DefaultError`
 
-Defined in: [src/error.ts:133](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/error.ts#L133)
+Defined in: [src/error.ts:142](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/error.ts#L142)
 
 The exit code that will be returned when the application exits, given
 nothing else goes wrong in the interim.

docs/api/src/exports/classes/GracefulEarlyExitError.md

@@ -6,7 +6,7 @@
 
 # Class: GracefulEarlyExitError
 
-Defined in: [src/error.ts:218](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/error.ts#L218)
+Defined in: [src/error.ts:227](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/error.ts#L227)
 
 Represents an exceptional event that should result in the immediate
 termination of the application but with an exit code indicating success
@@ -25,7 +25,7 @@ ignored.
 
 > **new GracefulEarlyExitError**(`error`?, `options`?): [`GracefulEarlyExitError`](GracefulEarlyExitError.md)
 
-Defined in: [src/error.ts:229](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/error.ts#L229)
+Defined in: [src/error.ts:238](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/error.ts#L238)
 
 Represents an exceptional event that should result in the immediate
 termination of the application but with an exit code indicating success
@@ -58,7 +58,7 @@ ignored.
 
 > **\[$type\]**: `string`[]
 
-Defined in: [src/error.ts:220](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/error.ts#L220)
+Defined in: [src/error.ts:229](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/error.ts#L229)
 
 #### Overrides
 
@@ -82,7 +82,7 @@ Defined in: node\_modules/typescript/lib/lib.es2022.error.d.ts:26
 
 > **dangerouslyFatal**: `boolean` = `false`
 
-Defined in: [src/error.ts:135](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/error.ts#L135)
+Defined in: [src/error.ts:144](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/error.ts#L144)
 
 This option is similar in intent to yargs's `exitProcess()` function,
 except applied more granularly.
@@ -139,13 +139,20 @@ Defined in: node\_modules/typescript/lib/lib.es5.d.ts:1076
 
 ### showHelp
 
-> **showHelp**: `boolean` = `false`
+> **showHelp**: `undefined` \| `boolean` \| `"full"` \| `"short"` \| `"default"`
 
-Defined in: [src/error.ts:134](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/error.ts#L134)
+Defined in: [src/error.ts:143](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/error.ts#L143)
 
-If `true`, help text will be sent to stderr _before this exception finishes
-bubbling_. Where the exception is thrown will determine which instance is
-responsible for error text generation.
+If truthy, help text will be sent to stderr _before this exception finishes
+bubbling_.
+
+Specifically, if `showHelp` is set to `"full"`, the full help text will be
+sent to stderr, including the entire `usage` string. If set to `"short"`
+(or `true`), the same help text will be sent to stderr except only the
+first line of usage will be included. If set to `"default"`, the value of
+`ExecutionContext::state.showHelpOnFail` will be used. If set to
+`false` (the default), no help text will be sent to stderr related to this
+error.
 
 #### Default
 
@@ -175,7 +182,7 @@ Defined in: node\_modules/typescript/lib/lib.es5.d.ts:1078
 
 > **suggestedExitCode**: [`FrameworkExitCode`](../enumerations/FrameworkExitCode.md) = `FrameworkExitCode.DefaultError`
 
-Defined in: [src/error.ts:133](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/error.ts#L133)
+Defined in: [src/error.ts:142](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/error.ts#L142)
 
 The exit code that will be returned when the application exits, given
 nothing else goes wrong in the interim.

docs/api/src/exports/enumerations/FrameworkExitCode.md

@@ -6,7 +6,7 @@
 
 # Enumeration: FrameworkExitCode
 
-Defined in: [src/constant.ts:51](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/constant.ts#L51)
+Defined in: [src/constant.ts:51](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/constant.ts#L51)
 
 Well-known exit codes shared across CLI implementations.
 
@@ -16,7 +16,7 @@ Well-known exit codes shared across CLI implementations.
 
 > **AssertionFailed**: `3`
 
-Defined in: [src/constant.ts:75](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/constant.ts#L75)
+Defined in: [src/constant.ts:75](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/constant.ts#L75)
 
 The exit code used when a sanity check fails. This includes (but is not
 limited to) all _framework errors_.
@@ -34,7 +34,7 @@ of Black Flag by the developer.
 
 > **DefaultError**: `1`
 
-Defined in: [src/constant.ts:59](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/constant.ts#L59)
+Defined in: [src/constant.ts:59](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/constant.ts#L59)
 
 Hard-coded default fallback exit code when fatal errors occur.
 
@@ -44,7 +44,7 @@ Hard-coded default fallback exit code when fatal errors occur.
 
 > **NotImplemented**: `2`
 
-Defined in: [src/constant.ts:63](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/constant.ts#L63)
+Defined in: [src/constant.ts:63](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/constant.ts#L63)
 
 The exit code used when executing an unimplemented child command.
 
@@ -54,6 +54,6 @@ The exit code used when executing an unimplemented child command.
 
 > **Ok**: `0`
 
-Defined in: [src/constant.ts:55](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/constant.ts#L55)
+Defined in: [src/constant.ts:55](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/constant.ts#L55)
 
 The exit code used when execution succeeds and exits gracefully.

docs/api/src/exports/functions/configureProgram.md

@@ -8,7 +8,7 @@
 
 > **configureProgram**(`commandModulesPath`, `configurationHooks`?): `Promise`\<[`PreExecutionContext`](../util/type-aliases/PreExecutionContext.md)\>
 
-Defined in: [src/index.ts:188](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/index.ts#L188)
+Defined in: [src/index.ts:188](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/index.ts#L188)
 
 Create and return a [PreExecutionContext](../util/type-aliases/PreExecutionContext.md) containing fully-configured
 [Program](../util/type-aliases/Program.md) instances and an [Executor](../util/type-aliases/Executor.md) entry point function.

docs/api/src/exports/functions/isCliError.md

@@ -8,7 +8,7 @@
 
 > **isCliError**(`parameter`): `parameter is CliError`
 
-Defined in: [src/error.ts:31](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/error.ts#L31)
+Defined in: [src/error.ts:33](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/error.ts#L33)
 
 Type guard for [CliError](../classes/CliError.md).
 

docs/api/src/exports/functions/isGracefulEarlyExitError.md

@@ -8,7 +8,7 @@
 
 > **isGracefulEarlyExitError**(`parameter`): `parameter is GracefulEarlyExitError`
 
-Defined in: [src/error.ts:44](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/error.ts#L44)
+Defined in: [src/error.ts:46](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/error.ts#L46)
 
 Type guard for [GracefulEarlyExitError](../classes/GracefulEarlyExitError.md).
 

docs/api/src/exports/functions/runProgram.md

@@ -10,7 +10,7 @@
 
 > **runProgram**\<`CustomCliArguments`\>(`commandModulesPath`): [`RunProgramReturnType`](../type-aliases/RunProgramReturnType.md)\<`CustomCliArguments`\>
 
-Defined in: [src/index.ts:668](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/index.ts#L668)
+Defined in: [src/index.ts:674](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/index.ts#L674)
 
 Invokes the dynamically imported
 `configureProgram(commandModulesPath).execute()` function.
@@ -46,7 +46,7 @@ if any other exception occurs, or `Arguments` otherwise.
 
 > **runProgram**\<`CustomCliArguments`\>(`commandModulesPath`, `configurationHooks`): [`RunProgramReturnType`](../type-aliases/RunProgramReturnType.md)\<`CustomCliArguments`\>
 
-Defined in: [src/index.ts:688](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/index.ts#L688)
+Defined in: [src/index.ts:694](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/index.ts#L694)
 
 Invokes the dynamically imported `configureProgram(commandModulesPath,
 configurationHooks).execute()` function.
@@ -86,7 +86,7 @@ if any other exception occurs, or `Arguments` otherwise.
 
 > **runProgram**\<`CustomCliArguments`\>(`commandModulesPath`, `preExecutionContext`): [`RunProgramReturnType`](../type-aliases/RunProgramReturnType.md)\<`CustomCliArguments`\>
 
-Defined in: [src/index.ts:712](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/index.ts#L712)
+Defined in: [src/index.ts:718](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/index.ts#L718)
 
 Invokes the `preExecutionContext.execute()` function.
 
@@ -127,7 +127,7 @@ if any other exception occurs, or `Arguments` otherwise.
 
 > **runProgram**\<`CustomCliArguments`\>(`commandModulesPath`, `argv`): [`RunProgramReturnType`](../type-aliases/RunProgramReturnType.md)\<`CustomCliArguments`\>
 
-Defined in: [src/index.ts:736](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/index.ts#L736)
+Defined in: [src/index.ts:742](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/index.ts#L742)
 
 Invokes the dynamically imported
 `configureProgram(commandModulesPath).execute(argv)` function. If `argv` is a
@@ -168,7 +168,7 @@ if any other exception occurs, or `Arguments` otherwise.
 
 > **runProgram**\<`CustomCliArguments`\>(`commandModulesPath`, `argv`, `configurationHooks`): [`RunProgramReturnType`](../type-aliases/RunProgramReturnType.md)\<`CustomCliArguments`\>
 
-Defined in: [src/index.ts:760](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/index.ts#L760)
+Defined in: [src/index.ts:766](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/index.ts#L766)
 
 Invokes the dynamically imported `configureProgram(commandModulesPath,
 configurationHooks).execute(argv)` function. If `argv` is a string, `argv =
@@ -213,7 +213,7 @@ if any other exception occurs, or `Arguments` otherwise.
 
 > **runProgram**\<`CustomCliArguments`\>(`commandModulesPath`, `argv`, `preExecutionContext`): [`RunProgramReturnType`](../type-aliases/RunProgramReturnType.md)\<`CustomCliArguments`\>
 
-Defined in: [src/index.ts:786](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/index.ts#L786)
+Defined in: [src/index.ts:792](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/index.ts#L792)
 
 Invokes the `preExecutionContext.execute(argv)` function. If `argv` is a
 string, `argv = argv.split(' ')` is applied first.
@@ -259,7 +259,7 @@ if any other exception occurs, or `Arguments` otherwise.
 
 > **runProgram**\<`CustomCliArguments`\>(...`args`): [`RunProgramReturnType`](../type-aliases/RunProgramReturnType.md)\<`CustomCliArguments`\>
 
-Defined in: [src/index.ts:806](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/index.ts#L806)
+Defined in: [src/index.ts:812](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/index.ts#L812)
 
 Run the given program with the configuration given in `args`.
 

docs/api/src/exports/type-aliases/Arguments.md

@@ -8,7 +8,7 @@
 
 > **Arguments**\<`CustomCliArguments`, `CustomExecutionContext`\>: `_Arguments`\<[`FrameworkArguments`](../util/type-aliases/FrameworkArguments.md)\<`CustomExecutionContext`\> & `CustomCliArguments`\>
 
-Defined in: [src/types/program.ts:19](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/types/program.ts#L19)
+Defined in: [src/types/program.ts:19](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/types/program.ts#L19)
 
 Represents the parsed CLI arguments, plus `_` and `$0`, any (hidden)
 arguments/properties specific to Black Flag, and an indexer falling back to

docs/api/src/exports/type-aliases/ChildConfiguration.md

@@ -8,7 +8,7 @@
 
 > **ChildConfiguration**\<`CustomCliArguments`, `CustomExecutionContext`\>: `Partial`\<[`Configuration`](Configuration.md)\<`CustomCliArguments`, `CustomExecutionContext`\>\>
 
-Defined in: [src/types/module.ts:162](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/types/module.ts#L162)
+Defined in: [src/types/module.ts:170](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/types/module.ts#L170)
 
 A partial extension to the [Configuration](Configuration.md) interface for child
 configurations. This type was designed for use in external ESM/CJS module

docs/api/src/exports/type-aliases/Configuration.md

@@ -8,7 +8,7 @@
 
 > **Configuration**\<`CustomCliArguments`, `CustomExecutionContext`\>: `object`
 
-Defined in: [src/types/module.ts:15](https://github.com/Xunnamius/black-flag/blob/41bcd587ae1e5e4c88c48238363c70e315cd242a/src/types/module.ts#L15)
+Defined in: [src/types/module.ts:15](https://github.com/Xunnamius/black-flag/blob/5e1e5b553c79657a97e5923bcba77a292781de9e/src/types/module.ts#L15)
 
 A replacement for the `CommandModule` type that comes with yargs.
 Auto-discovered configuration modules must implement this interface or a
@@ -76,7 +76,9 @@ first invoked** and so aren't available until a little later.
 
 > **command**: `"$0"` \| `` `$0 ${string}` ``
 
-The command as interpreted by yargs. May contain positional arguments.
+The command as interpreted by yargs. May contain positional arguments
+declared using the [`yargs::command`
+DSL](https://github.com/yargs/yargs/blob/main/docs/advanced.md#positional-arguments).
 
 It is usually unnecessary to change or use this property if you're not
 using positional arguments. If you want to change your command's name, use
@@ -123,7 +125,8 @@ be considered "hidden" by yargs.
 A function called when this command is invoked. It will receive an object
 of parsed arguments.
 
-If `undefined`, a `CommandNotImplementedError` will be thrown.
+If `undefined`, the command will be considered "unimplemented" and a
+`CommandNotImplementedError` will be thrown.
 
 #### Parameters
 
@@ -159,6 +162,11 @@ filename without extension is "index".
 
 Set a usage message shown at the top of the command's help text.
 
+Depending on the value of `ExecutionContext::state.showHelpOnFail`, either
+the "short" first line of usage text will be output during errors or the
+"full" usage string. Either way, whenever help text is explicitly requested
+(e.g. `--help` is given), the full usage string will be output.
+
 Several replacements are made to the `usage` string before it is output. In
 order: