dry-cli-help 0.2.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 603fe4d7d4f905ffd720b33ce12f7847ce9d61658935a68609444ea35de0afed
-  data.tar.gz: 5ba0fe8b6319be69b6308f4613afbbaf56b818fdbed8ff1844b790e83d47cb74
+  metadata.gz: 10fb8e86e571ad96c6f523f4807d040b0421ebe1fa65e334738fa785e0212196
+  data.tar.gz: 408f6dd175e32d407f38306c9c61211a9b8e9d7e82f8870cde02ce58cfe64a23
 SHA512:
-  metadata.gz: cf16c7662f59e52d41f97569be72627dd946af8f0e13f19563f202daa6576895c3d594e5114ab2980830f2b0943b47bd6a1c17b8a45ae121e7f62673b8b594a5
-  data.tar.gz: 268c5be6c337e75f509e557d85e5e78ac9e72799b8fbca949ec729a3e8c34dc05e129e97c5f4eb8c37e7d8a7c769347d13e67f5b82b7a30a283e37b290320444
+  metadata.gz: f42c06e5cb90eae00d6fc11f1fa4cbfed1f789005b4aa6dc0ea27cd60522de63019804c154e818efc4eb4bc52e673765ad638f881f94faa445b0b1a6ce637060
+  data.tar.gz: 9e711ac3f6b30580e1e979f391019de8f1c5d155b9ded6b1c72881e698d79347e337299aca96316b9c9806507d9b1d7022c0f30d9bf715083e60a7a651775c82

data/CHANGELOG.md

@@ -1,10 +1,22 @@
 ## [Unreleased]
 
+## [0.5.0] - Unreleased
+
+- The `dry-cli` dependency no longer pins a version range; any release satisfies it.
+- `SPECIFICATION.md` moves to `docs/SPECIFICATION.md`, marked as the specification for 0.1.0, and stays out of the YARD documentation.
+- The README documents which sections each screen prints, how groups and nested commands list, the description column and minimum wrap width, `Help.config`, `Help.reset!`, and the `ArgumentError` a bad setting raises.
+
+## [0.2.1] - 2026-09-15
+
 - Every setting is made once, in `Dry::CLI::Help.configure`, which now also accepts a block without an argument and runs it against the configuration. The `help` block on registries is removed, along with `Help.config_for` and `Configuration#merge`: the gem adds nothing to dry-cli's registry or command DSL.
 - A `styles` block declares every element's look in one place, replacing `style(element, *names)`. New elements `usage`, `example` and `example_comment`; `comment` is renamed `example_comment` and defaults to bold black.
 - Heading case moves into the heading style: `styles { heading :bold, case: :Capitalize }`, one of `:UPPERCASE`, `:Capitalize`, `:lowercase` or `:as_is`. The `heading_case` setting is removed.
 - `examples/` holds three single-file dry-cli tools that switch this gem on with `--with-dry-cli-help` or `-w`.
 
+## [0.2.0] - 2026-09-14
+
+- Documentation, justfile, lefthook and packaging fixes after the conversion. No change to behavior.
+
 ## [0.1.0] - 2026-09-12
 
 - Initial release as `dry-cli-help`, converted from `dry-cli-autocomplete`. The shell completion generator is removed; that gem remains the place for it.

data/README.md

@@ -5,7 +5,7 @@
 Configurable, wrapped, colored help screens for [dry-cli](https://github.com/dry-rb/dry-cli) applications.
 
 > [!NOTE]
-> The design, the settings and every decision behind them are in [SPECIFICATION.md](SPECIFICATION.md).
+> The original design, the settings and the decisions behind them are in [docs/SPECIFICATION.md](docs/SPECIFICATION.md), written for version 0.1.0.
 
 dry-cli prints help as it finds it: no title, no description of the program, no color, one line per description however long, and commands sorted alphabetically. This gem keeps the command structure you already declared and changes only what the user reads before a command runs. Progress bars, spinners and error panels belong in `dry-cli-ui`.
 
@@ -54,7 +54,7 @@ OPTIONS
 
 Headings are bold and yellow, commands green, options and arguments cyan, and every description wraps to the terminal with a hanging indent.
 
-Although, it is best to show them side by side as a screenshot: this script `rbcheck` is in the `examples` folder of the gem.
+The same comparison as screenshots, taken from `examples/rbcheck`:
 
 | Standard dry-cli Help Screen                    | Require `dry/cli/help`                   |
 | :---------------------------------------------- | :--------------------------------------- |
@@ -69,6 +69,8 @@ gem install dry-cli-help
 
 Or add `gem "dry-cli-help"` to your `Gemfile`.
 
+It requires Ruby 4.0 or newer, and depends on `dry-cli` and `pastel`.
+
 ## Usage
 
 Require it after dry-cli. That alone changes every help screen in the process.
@@ -85,7 +87,7 @@ Dry::CLI::Help.configure do
   title "MyCLI"
 
   description <<~TEXT
-    This utility does something very important.
+    Compile, validate, and evaluate rules.
   TEXT
 
   epilogue "Documentation: https://example.com/my-cli"
@@ -99,10 +101,10 @@ module My
   module CLI
     extend Dry::CLI::Registry
 
-    register "compile", Compile
+    register "compile",  Compile
     register "validate", Validate
     register "evaluate", Evaluate
-    register "version", Version, aliases: ["--version", "-v"]
+    register "version",  Version, aliases: ["--version", "-v"]
   end
 end
 ```
@@ -130,7 +132,7 @@ OPTIONS
 Documentation: https://example.com/my-cli
 ```
 
-A command reachable as `--version` lists under Options by its dashed names.
+A command reachable as `--version` lists under Options by its dashed names. Commands marked `hidden: true` in the registry stay out of every list, and a non-dashed alias prints next to its command, as in `build, b`.
 
 A block that takes an argument receives the configuration instead of running against it:
 
@@ -141,6 +143,8 @@ Dry::CLI::Help.configure do |config|
 end
 ```
 
+Every setting validates its value and raises `ArgumentError` on one it cannot use. `Dry::CLI::Help.config` returns the current settings, and `Dry::CLI::Help.reset!` forgets them all, which is handy between tests.
+
 ## Examples
 
 The [`examples`](examples) folder holds three single-file tools built on dry-cli. Each one loads and configures this gem only when you pass `--with-dry-cli-help`, or `-w` for short, so you can run the same command both ways and compare:
@@ -160,7 +164,7 @@ if [ARGV.delete("--with-dry-cli-help"), ARGV.delete("-w")].any?
   require "dry/cli/help"
 
   Dry::CLI::Help.configure do
-    title "RBCheck"
+    title "rbcheck"
     description "Small checks for Ruby projects."
     epilogue "Report bugs at https://example.com/rbcheck/issues"
   end
@@ -202,7 +206,7 @@ Every screen below comes from running it in an 80-column terminal.
 
 ### `rbcheck -h`
 
-dry-cli alone prints a list of commands and exits 1. Also note the lack of wrapping on the long description.
+dry-cli alone prints a list of commands to stderr and exits 1, and does not wrap the long description.
 
 ```text
 Commands:
@@ -210,10 +214,13 @@ Commands:
   rbcheck version                                 # Print the version
 ```
 
-With this gem in play it exits 0 and prints:
+With this gem, `rbcheck -h` prints the help below to stdout and exits 0.
+
+> [!NOTE]
+> Whether a CLI run with no arguments should exit 1 or 0 is debatable. dry-cli exits 1, and so does this gem by default: plain `rbcheck` prints the same screen to stderr and exits 1. Set [`exit_code_without_arguments`](#dsl-based-configuration-api) to `0` to treat it like `-h` instead.
 
 ```text
-RB	check
+rbcheck
 
 Small checks for Ruby projects.
 
@@ -298,11 +305,13 @@ In a terminal the headings print bold yellow, usage lines, commands and examples
 
 `examples/todo` shows nested commands, custom headings and a `styles` block. `examples/deploy` shows a fixed width, a banner above command help, reordered sections and help without a command exiting 0. [`examples/README.md`](examples/README.md) lists what each one demonstrates.
 
-## Settings
+## DSL-based Configuration API
+
+The gem offers a compact DSL in the general spirit of Ruby and `dry-rb` in particular, and makes the following methods available within the `configure` block.
 
 | Setting                       | Values                           | Default         | What it does                                                                                                              |
 | ----------------------------- | -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `title`                       | String                           | none            | Prints a bold first line at the top of the top-level help                                                                 |
+| `title`                       | String                           | none            | Prints the first line of the banner, above the top-level help                                                             |
 | `description`                 | String                           | none            | Prints paragraphs under the title, reflowed to the wrap width                                                             |
 | `epilogue`                    | String                           | none            | Prints paragraphs at the very end of the top-level help                                                                   |
 | `color`                       | `true`, `false`, `:auto`         | `:auto`         | Paints headings, commands, arguments and options; `:auto` paints only a terminal                                          |
@@ -315,7 +324,15 @@ In a terminal the headings print bold yellow, usage lines, commands and examples
 
 `color :auto` colors a terminal and honors [`NO_COLOR`](https://no-color.org). `width :terminal` reads `COLUMNS`, then the console, then falls back to 80, and `margin` keeps columns free at the right edge.
 
-Running the program with no command prints the top-level help and exits 1, as dry-cli does. `exit_code_without_arguments 0` prints it to stdout and exits 0 instead. `-h` and `--help` always exit 0.
+Running the program, or a group such as `my-cli db`, with no command prints its help to stderr and exits 1, as dry-cli does. With
+
+```ruby
+exit_code_without_arguments 0
+```
+
+it prints to stdout and exits 0 instead. `-h` and `--help` always print to stdout and exit 0. A mistyped command prints dry-cli's suggestion, then the help, to stderr and exits 1.
+
+The banner (title and description) and the epilogue print on the top-level help. A CLI built from a single command, `Dry::CLI.new(Deploy)`, counts as top level, so its command help gets both.
 
 ### Headings, sections and groups
 
@@ -331,11 +348,24 @@ Dry::CLI::Help.configure do
 end
 ```
 
-- `heading` replaces one section's heading text. How headings are cased belongs to their style, below.
-- `group` lists commands under a heading of their own, in the order given. Ungrouped commands stay under Commands. A group inside a group names the full path, such as `"db migrate"`.
+- `heading` replaces one section's heading text. It takes `:usage`, `:description`, `:commands`, `:subcommands`, `:arguments`, `:options` or `:examples`; `banner` and `epilogue` have no heading. How headings are cased belongs to their style, below.
+- `group` lists commands under a heading of their own, in the order given. Ungrouped commands stay under Commands, and groups print below them in the order declared. A group with no commands raises `ArgumentError`; a group whose commands a screen does not list prints no heading there. A nested command is named by its full path, such as `"db migrate"`, and its group shows on `my-cli db -h`.
 - `sections` sets the order; a section left out is hidden. `hide` hides sections without restating the order.
 
-The sections are `banner`, `usage`, `description`, `commands`, `subcommands`, `arguments`, `options`, `examples` and `epilogue`. Each screen prints the ones that apply to it.
+The sections are `banner`, `usage`, `description`, `commands`, `subcommands`, `arguments`, `options`, `examples` and `epilogue`. Each screen prints the ones that apply to it:
+
+| Screen                                        | Sections it can print                                                                           |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| A listing: `my-cli`, `my-cli -h`, `my-cli db` | `banner`, `usage`, `commands`, `options`, `epilogue`                                            |
+| A command: `my-cli compile -h`                | `banner`, `usage`, `description`, `subcommands`, `arguments`, `options`, `examples`, `epilogue` |
+
+A few details of those screens:
+
+- A command that also has subcommands gets a second usage line, `my-cli db COMMAND [OPTIONS]`, and a Subcommands section.
+- A group registered without a command of its own describes itself by what it holds, as in `Subcommands: add, remove`.
+- An array argument prints as `FILES...`.
+- Every definition list on a screen shares one description column, never wider than half the wrap width. A term longer than that column puts its description on the next line.
+- Text never wraps narrower than 20 columns, however small the terminal.
 
 ### Styles
 
@@ -386,7 +416,7 @@ class Deploy < Dry::CLI::Command
 end
 ```
 
-The methods are the eight colors `black red green yellow blue magenta cyan white`, their `bright_` forms, the `on_` and `on_bright_` backgrounds, and `clear bold dim italic underline inverse hidden strikethrough`. `Dry::CLI::Help::Colors.enabled = false` turns them all off.
+The methods are the eight colors `black red green yellow blue magenta cyan white`, their `bright_` forms, the `on_` and `on_bright_` backgrounds, and `clear bold dim italic underline inverse hidden strikethrough`. `Dry::CLI::Help::Colors.enabled` takes `true`, `false` or `:auto` (the default, which colors only a terminal and honors `NO_COLOR`). Help screens ignore that switch and follow the `color` setting.
 
 ## How it works
 
@@ -410,7 +440,7 @@ flowchart TB
     command_screen --> formatter["Formatter"]
     listing_screen --> formatter
 
-    help_config["Help.configure + registry help block"] --> formatter
+    help_config["Help.configure"] --> formatter
 
     formatter --> output["stdout or stderr"]
 ```
@@ -420,13 +450,16 @@ Both methods are `@api private` in dry-cli. `spec/dry/cli/help/dry_cli_contract_
 ## Development
 
 ```bash
-just install     # bundle install
-just test        # the suite; a full run enforces 100% line and branch coverage
-just lint        # rubocop
-just ci          # both
-just lefthook    # every pre-commit hook against every file
-just format      # rubocop -a, then mdformat --wrap no on every Markdown file
-bin/console      # IRB with the gem loaded
+just install        # bundle install
+just test           # the suite; a full run enforces 100% line and branch coverage
+just test-coverage  # measure coverage even for a partial run
+just lint           # rubocop
+just ci             # rubocop, then the suite with coverage
+just lefthook       # every pre-commit hook against every file
+just format         # mdformat --wrap no on every Markdown file, then rubocop -a
+just doc            # YARD documentation
+just build          # build the .gem into pkg/
+bin/console         # IRB with the gem loaded
 ```
 
 ## Contributing
@@ -434,7 +467,21 @@ bin/console      # IRB with the gem loaded
 Bug reports and pull requests are welcome at <https://github.com/kigster/dry-cli-help>.
 
 > [!WARNING]
-> The `dry-` prefix and the `Dry::CLI::Help` namespace do not imply endorsement by dry-rb. This is an independent gem that extends theirs.
+> The `dry-` prefix and the `Dry::CLI::Help` namespace do not imply endorsement by dry-rb.
+>
+> This is an independent and opinionated gem that extends theirs.
+
+## Note to Dry-Rb Maintainers
+
+First — hats off to all of you who tirelessly built out one of the most valuable collections of libraries in the Ruby ecosystem.
+
+While I admire and would be willing to contribute any or all of the extension gem's code to the original gem, I feel that creating plugins and extensions allows the author to fully express their needs and wants, and then, if the authors of `dry-cli` become interested in any of them, I would be honored to submit a PR to `dry-cli` itself.
+
+This method offered a very open road to extensibility and experimentation. If the code quality or design is not up to the level required for direct contributions to `dry-rb`, then let it be known that:
+
+1. We would be very happy to receive any feedback and improve, refactor, and update the gem assuming it improves it
+1. Roll any part of the codebase as a PR to the `dry-cli` core.
+1. We hold the authors of `dry-rb` in high regard, and generally would love to collaborate, as long as the feedback loop/cycle is not so long that the context of the changes gets lost in time, as with so many contributions made to other gems in the past.
 
 ## License
 

data/Rakefile

@@ -28,7 +28,7 @@ end
 task build: :permissions
 
 YARD::Rake::YardocTask.new(:doc) do |t|
-  t.files = %w[lib/**/*.rb - README.md LICENSE.txt CHANGELOG.md SPECIFICATION.md]
+  t.files = %w[lib/**/*.rb - README.md LICENSE.txt CHANGELOG.md]
   t.options.unshift("--title", '"dry-cli-help: configurable help screens for dry-cli"')
   t.after = -> { exec("open doc/index.html") } if RUBY_PLATFORM =~ /darwin/
 end

data/lib/dry/cli/help/version.rb

@@ -9,7 +9,7 @@ module Dry
   # inherits from Object, so an empty reopening is compatible either way.
   class CLI
     module Help
-      VERSION = "0.2.1"
+      VERSION = "0.5.0"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dry-cli-help
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -15,20 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.1.1
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.1.1
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: pastel
   requirement: !ruby/object:Gem::Requirement
@@ -56,7 +50,6 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- SPECIFICATION.md
 - lib/dry-cli-help.rb
 - lib/dry/cli/help.rb
 - lib/dry/cli/help/colors.rb

data/SPECIFICATION.md

@@ -1,213 +0,0 @@
-# dry-cli-help
-
-Enhanced help presentation for [`dry-cli`](https://github.com/dry-rb/dry-cli).
-
-## Purpose
-
-`dry-cli-help` improves the **static, human-facing documentation** generated by `dry-cli`.
-
-It does not replace `dry-cli` or introduce another command framework. It takes the command structure already defined through `dry-cli` and provides richer, more configurable help output.
-
-## Responsibilities
-
-- Top-level application title and description
-- Command descriptions
-- Automatic line wrapping based on terminal width
-- ANSI color and styling
-- Configurable headings
-- Improved spacing and indentation
-- Usage formatting
-- Arguments and options formatting
-- Examples
-- Epilogues
-- Command grouping
-- Section ordering
-- Hiding or customizing sections
-- Consistent formatting across commands
-
-## Example
-
-Every setting is made once, in one block, before any CLI runs. The registry, its commands and their options stay exactly as dry-cli declares them:
-
-```ruby
-require "dry/cli"
-require "dry/cli/help"
-
-Dry::CLI::Help.configure do
-  title "MyCLI"
-
-  description <<~TEXT
-    Compile, validate, and evaluate tax rules.
-  TEXT
-
-  color :auto
-  width :terminal
-
-  styles do
-    heading :bold, :yellow, case: :UPPERCASE
-    example_comment :bold, :black
-  end
-end
-
-module CLI
-  extend Dry::CLI::Registry # plain dry-cli, nothing added
-
-  register "compile", Compile
-  register "validate", Validate
-  register "evaluate", Evaluate
-end
-```
-
-Result:
-
-```text
-MyCLI
-
-Compile, validate, and evaluate tax rules.
-
-USAGE
-  my-cli COMMAND [OPTIONS]
-
-COMMANDS
-  compile       Compile tax rules
-  validate      Validate the rule corpus
-  evaluate      Evaluate a tax return
-
-OPTIONS
-  --help        Show help
-  --version     Show version
-```
-
-## Design Principle
-
-`dry-cli-help` owns what the user sees **before a command runs**.
-
-It should remain focused on documentation and presentation rather than runtime command UI.
-
-Runtime features such as progress bars, spinners, status displays, and error panels belong in `dry-cli-ui`.
-
-## Relationship
-
-```text
-dry-cli
-    │
-    └── dry-cli-help
-          │
-          ├── descriptions
-          ├── usage
-          ├── wrapping
-          ├── headings
-          ├── colors
-          ├── arguments/options
-          └── examples
-```
-
-## Requirements carried from the first draft
-
-1. **Exit status without arguments.** dry-cli prints the command list and exits 1 when run with no command. The status is configurable. Asking for help with `-h` or `--help` always exits 0.
-1. **Banner.** The title and description print above the command list for `mycli`, `mycli -h` and `mycli --help`. A separate setting decides whether they also print for `mycli subcommand -h`.
-1. **Wrapping.** Three modes: no wrapping (dry-cli's behavior), wrapping at a fixed column such as 80 or 100, and wrapping at the terminal's width minus an optional margin.
-1. **Colors.** Built on `pastel`. A `Colors` module, when included, makes each style below available as a method: `red("text")` returns decorated text, and `red.bold("text")` chains.
-   - Foreground: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, and the `bright_` form of each.
-   - Background: `on_black`, `on_red`, `on_green`, `on_yellow`, `on_blue`, `on_magenta`, `on_cyan`, `on_white`, and the `on_bright_` form of each.
-   - Styles: `clear`, `bold`, `dim`, `italic`, `underline`, `inverse`, `hidden`, `strikethrough`.
-
-## Decisions
-
-### Integration
-
-Requiring `dry/cli/help` changes help output for every `Dry::CLI` in the process. It does not replace `Dry::CLI::Banner` or `Dry::CLI::Usage`. It prepends one module to `Dry::CLI` that overrides two private methods, the only two places dry-cli prints help:
-
-| dry-cli method                         | When dry-cli calls it                                      |
-| -------------------------------------- | ---------------------------------------------------------- |
-| `Dry::CLI#help(command, prog_name)`    | `mycli deploy -h`, for any command with a class            |
-| `Dry::CLI#spell_checker(result, argv)` | `mycli`, `mycli -h`, `mycli db` for a group, `mycli bogus` |
-
-Both are `@api private` in dry-cli 1.4.1. A spec asserts they exist, so a dry-cli release that renames them fails this gem's suite rather than a host's help screen. `Dry::CLI::Help::Integration` holds the override.
-
-The gem adds nothing to `Dry::CLI::Registry` or `Dry::CLI::Command`. The DSL a host uses to declare commands, arguments, options and examples is dry-cli's, unchanged, so adding or removing this gem never touches a command definition.
-
-### Configuration
-
-One place. `Dry::CLI::Help.configure` holds every setting for the process, and every CLI in the process renders with it. A setting it leaves alone takes the default below.
-
-The block reads and writes both ways: `title "MyCLI"` when the block takes no argument and runs against the configuration, and `config.title = "MyCLI"` when it takes one and receives it.
-
-| Setting                       | Values                           | Default         | Effect                                                             |
-| ----------------------------- | -------------------------------- | --------------- | ------------------------------------------------------------------ |
-| `title`                       | String                           | none            | First line of the banner                                           |
-| `description`                 | String                           | none            | Paragraphs under the title, wrapped                                |
-| `epilogue`                    | String                           | none            | Paragraphs at the end of the top-level help                        |
-| `color`                       | `true`, `false`, `:auto`         | `:auto`         | `:auto` colors a terminal and honors `NO_COLOR`                    |
-| `wrap`                        | `true`, `false`                  | `true`          | `false` prints descriptions as written                             |
-| `width`                       | `:terminal`, Integer             | `:terminal`     | The column text wraps at                                           |
-| `margin`                      | Integer                          | `0`             | Columns kept free at the right edge when `width` is `:terminal`    |
-| `exit_code_without_arguments` | Integer, 0 to 255                | `1`             | Status for `mycli` or `mycli group` with no command                |
-| `banner_on_subcommands`       | `true`, `false`                  | `false`         | Print the title and description above `mycli command -h`           |
-| `command_order`               | `:registration`, `:alphabetical` | `:registration` | Order commands list in; dry-cli sorts alphabetically               |
-| `heading(section, text)`      | Section name, String             | see below       | Replaces one heading's text                                        |
-| `styles { ... }`              | One line per element             | see below       | Declares how every element looks, and how headings are cased       |
-| `group(name, *commands)`      | String, command paths            | none            | Lists those commands under their own heading, in declaration order |
-| `sections(*names)`            | Section names                    | all             | Order of sections; a section left out is hidden                    |
-| `hide(*names)`                | Section names                    | none            | Hides sections without restating the order                         |
-
-Terminal width comes from `COLUMNS`, then the console, then 80. A resolved wrap width never falls below 20 columns.
-
-### Sections
-
-In default order, with default headings:
-
-| Section       | Heading     | Top-level help | Command help                        |
-| ------------- | ----------- | -------------- | ----------------------------------- |
-| `banner`      | none        | yes            | when `banner_on_subcommands` is set |
-| `usage`       | Usage       | yes            | yes                                 |
-| `description` | Description | no             | yes                                 |
-| `commands`    | Commands    | yes            | no                                  |
-| `subcommands` | Subcommands | no             | when the command has children       |
-| `arguments`   | Arguments   | no             | yes                                 |
-| `options`     | Options     | yes            | yes                                 |
-| `examples`    | Examples    | no             | yes                                 |
-| `epilogue`    | none        | yes            | only for a single command           |
-
-A single command passed to `Dry::CLI.new(SomeCommand)` is the whole program, so its command help prints the banner and the epilogue too.
-
-A group listing, `mycli db` where `db` has no command of its own, renders as top-level help scoped to the group, with the banner only when `banner_on_subcommands` is set, and no epilogue.
-
-Every Options section starts with `-h, --help  Show help`, because both spellings work at every level. The example above shows `--help` alone; `spec/dry/cli/help/integration_spec.rb` holds the exact output.
-
-At any level, a command registered under a name or alias starting with `-`, such as `register "version", Version, aliases: ["--version"]`, lists under Options rather than Commands.
-
-### Styles
-
-Every element's look is declared in one `styles` block inside `configure`. Each line names an element and its styles, from `Colors::STYLES`. An element left out keeps its default; a line with no styles prints the element plain.
-
-```ruby
-styles do
-  heading :bold, :blue, case: :Capitalize
-  example :yellow
-  example_comment # plain
-end
-```
-
-| Element           | Default styles   | Applies to                                 |
-| ----------------- | ---------------- | ------------------------------------------ |
-| `title`           | `bold`           | The banner title                           |
-| `heading`         | `bold`, `yellow` | Every section and group heading            |
-| `usage`           | `green`          | Every usage line, whole                    |
-| `command`         | `green`          | Command names in a list                    |
-| `argument`        | `cyan`           | Argument names                             |
-| `option`          | `cyan`           | Option names                               |
-| `example`         | `green`          | The command line of an example             |
-| `example_comment` | `bold`, `black`  | The part of an example after the first `#` |
-
-`heading` alone takes `case:`, one of `:UPPERCASE` (the default), `:Capitalize`, `:lowercase` or `:as_is`, each written the way it cases. It applies to every heading. `:Capitalize` raises only the first letter and leaves the rest as written. `heading case: :as_is` with no styles changes the case and keeps the heading's styles.
-
-### Layout
-
-- Every section after the first starts after one blank line. Section bodies indent two columns.
-- A definition list (commands, arguments, options) aligns its descriptions in one column across the whole screen, two columns past the longest term that has a description. The column never passes half the wrap width, and a term longer than the column puts its description on the next line.
-- Examples align among themselves. A full command line is longer than any option, and sharing its column would push every other description to the right.
-- A group registered without a command has no description of its own, so it lists as `Subcommands: a, b`.
-- An argument or option description ends with what a reader needs to supply it: `(required; one of: json, yaml; default: "json")`. An array argument reads `NAME...`.
-- Descriptions wrap with a hanging indent under the description column. Paragraphs split on blank lines and reflow; a line starting with whitespace prints verbatim.
-- An example written `"prod # ship to production"` renders the part after the first `#` surrounded by spaces as its description.