clack 0.4.6 → 0.6.0

data/README.md

@@ -1,29 +1,65 @@
-# Clack
-
-**Effortlessly beautiful CLI prompts for Ruby.**
-
-A faithful Ruby port of [@clack/prompts](https://github.com/bombshell-dev/clack). 16+ prompt types, zero dependencies, Ruby 3.2+. `gem "clack"` and go.
+<p align="center">
+  <br>
+  <br>
+  <code>&nbsp;C&nbsp;L&nbsp;A&nbsp;C&nbsp;K&nbsp;</code>
+  <br>
+  <br>
+  <i>CLI prompts for Ruby. Zero dependencies.</i>
+  <br>
+  <br>
+  <a href="https://rubygems.org/gems/clack"><img src="https://img.shields.io/gem/v/clack?style=flat-square&color=cc342d" alt="Gem Version"></a>
+  <a href="https://github.com/swhitt/clackrb/actions"><img src="https://img.shields.io/github/actions/workflow/status/swhitt/clackrb/ci.yml?style=flat-square&label=tests" alt="Tests"></a>
+  <a href="https://www.ruby-lang.org"><img src="https://img.shields.io/badge/ruby-3.2%2B-cc342d?style=flat-square" alt="Ruby 3.2+"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT License"></a>
+</p>
 
 <p align="center">
-  <img src="examples/demo.gif?v=2" width="640" alt="Clack demo">
+  <img src="examples/demo.gif?v=2" width="640" alt="Clack demo showing beautiful terminal prompts">
 </p>
 
+---
+
 ## Why Clack?
 
-- **Beautiful by default** — Thoughtfully designed prompts that just look right
-- **Vim-friendly** — Navigate with `hjkl` or arrow keys
-- **Accessible** — Graceful ASCII fallbacks for limited terminals
-- **Composable** — Group prompts together with `Clack.group`
-- **Zero dependencies** — Everything in one gem
+The standard approach:
+
+```ruby
+print "What is your project named? "
+name = gets.chomp
+print "Pick a framework (1=Rails, 2=Sinatra, 3=Roda): "
+framework = gets.chomp.to_i
+```
+
+No navigation, no validation, no visual feedback. With Clack:
+
+```ruby
+require "clack"
+
+Clack.intro "create-app"
+
+name = Clack.text(message: "What is your project named?", placeholder: "my-app")
+# => Renders a gorgeous, navigable text input with placeholder text
+
+framework = Clack.select(
+  message: "Pick a framework",
+  options: [
+    { value: "rails", label: "Ruby on Rails", hint: "recommended" },
+    { value: "sinatra", label: "Sinatra" },
+    { value: "roda", label: "Roda" }
+  ]
+)
+# => Arrow-key navigation, vim bindings, instant submit
+
+Clack.outro "You're all set!"
+```
+
+---
 
 ## Installation
 
 ```ruby
 # Gemfile
 gem "clack"
-
-# Or from GitHub
-gem "clack", github: "swhitt/clackrb"
 ```
 
 ```bash
@@ -31,15 +67,18 @@ gem "clack", github: "swhitt/clackrb"
 gem install clack
 ```
 
+---
+
 ## Quick Start
 
 ```ruby
 require "clack"
 
-Clack.intro "project-setup"
+Clack.intro "create-app"
 
 result = Clack.group do |g|
   g.prompt(:name) { Clack.text(message: "Project name?", placeholder: "my-app") }
+
   g.prompt(:framework) do
     Clack.select(
       message: "Pick a framework",
@@ -50,6 +89,7 @@ result = Clack.group do |g|
       ]
     )
   end
+
   g.prompt(:features) do
     Clack.multiselect(
       message: "Select features",
@@ -66,126 +106,16 @@ end
 Clack.outro "You're all set!"
 ```
 
-## Demo
-
-Try it yourself:
-
-```bash
-ruby examples/full_demo.rb
-```
-
-<details>
-<summary>Recording the demo GIF</summary>
-
-Requires [asciinema](https://asciinema.org/), [agg](https://github.com/asciinema/agg), and [expect](https://core.tcl-lang.org/expect/index):
-
-```bash
-# Record the demo (automated via expect script)
-asciinema rec examples/demo.cast --command "expect examples/demo.exp" --overwrite -q
-
-# Split batched frames to show typing (Ruby buffers terminal output)
-ruby examples/split_cast.rb
-
-# Convert to GIF
-agg examples/demo.cast examples/demo.gif --font-size 18 --cols 80 --rows 28 --speed 0.6
-```
-</details>
+---
 
 ## Prompts
 
-All prompts return the user's input, or `Clack::CANCEL` if they pressed Escape/Ctrl+C.
-
-```ruby
-# Check for cancellation
-result = Clack.text(message: "Name?")
-exit 1 if Clack.cancel?(result)
-
-# Or use handle_cancel for a one-liner that prints "Cancelled" and returns true
-result = Clack.text(message: "Name?")
-exit 1 if Clack.handle_cancel(result)
-
-# With a custom message
-exit 1 if Clack.handle_cancel(result, "Aborted by user")
-```
-
-### Validation & Transforms
-
-Prompts support `validate:` and `transform:` options.
-
-```
-User Input → Validation (raw) → Transform (if valid) → Final Value
-```
-
-Validation returns an error message, a `Clack::Warning`, or `nil` to pass. Transforms normalize the value after validation passes.
-
-**Validation results:**
-- `nil` or `false` - passes validation
-- String - shows error (red), user must fix input
-- `Clack::Warning.new(message)` - shows warning (yellow), user can confirm with Enter or edit
-
-```ruby
-# Use symbol shortcuts (preferred)
-name = Clack.text(message: "Name?", transform: :strip)
-code = Clack.text(message: "Code?", transform: :upcase)
-
-# Chain multiple transforms
-username = Clack.text(
-  message: "Username?",
-  transform: Clack::Transformers.chain(:strip, :downcase)
-)
-
-# Combine validation and transform
-amount = Clack.text(
-  message: "Amount?",
-  validate: ->(v) { "Must be a number" unless v.match?(/\A\d+\z/) },
-  transform: :to_integer
-)
-
-# Warning validation (soft failure, user can confirm or edit)
-file = Clack.text(
-  message: "Output file?",
-  validate: ->(v) { Clack::Warning.new("File exists. Overwrite?") if File.exist?(v) }
-)
-```
-
-Built-in validators and transformers:
-
-```ruby
-# Validators - return error message, Warning, or nil
-Clack::Validators.required              # Non-empty input
-Clack::Validators.min_length(3)         # Minimum character count
-Clack::Validators.max_length(100)       # Maximum character count
-Clack::Validators.format(/\A[a-z]+\z/, "Only lowercase")
-Clack::Validators.email                 # Email format (user@host.tld)
-Clack::Validators.url                   # URL format (http/https)
-Clack::Validators.integer               # Integer string ("-5", "42")
-Clack::Validators.in_range(1..100)      # Numeric range (parses as int)
-Clack::Validators.one_of(%w[a b c])     # Allowlist check
-Clack::Validators.path_exists           # File/dir exists on disk
-Clack::Validators.directory_exists      # Directory exists on disk
-Clack::Validators.future_date           # Date strictly after today
-Clack::Validators.past_date             # Date strictly before today
-Clack::Validators.date_range(min: d1, max: d2) # Date within range
-Clack::Validators.combine(v1, v2)       # First error/warning wins
-
-# Warning validators - allow user to confirm or edit
-Clack::Validators.file_exists_warning   # For file overwrite confirmations
-Clack::Validators.as_warning(validator) # Convert any validator to warning
-
-# Transformers - normalize the value (use :symbol or Clack::Transformers.name)
-:strip / :trim      # Remove leading/trailing whitespace
-:downcase / :upcase # Change case
-:capitalize         # "hello world" -> "Hello world"
-:titlecase          # "hello world" -> "Hello World"
-:squish             # Collapse whitespace to single spaces
-:compact            # Remove all whitespace
-:to_integer         # Parse as integer
-:to_float           # Parse as float
-:digits_only        # Extract only digits
-```
+All prompts return the user's input, or `Clack::CANCEL` if the user pressed Escape/Ctrl+C.
 
 ### Text
 
+Single-line text input with placeholders, defaults, validation, and tab completion.
+
 <img src="examples/images/text.svg" alt="Text prompt">
 
 ```ruby
@@ -199,16 +129,16 @@ name = Clack.text(
 )
 ```
 
-**Tab completion** - press `Tab` to fill the longest common prefix of matching candidates:
+**Tab completion** -- press `Tab` to fill the longest common prefix of matching candidates:
 
 ```ruby
-# Tab completion from a static list
+# Static list
 cmd = Clack.text(
   message: "Command?",
   completions: %w[build test deploy lint format]
 )
 
-# Dynamic tab completion
+# Dynamic completions
 file = Clack.text(
   message: "File?",
   completions: ->(input) { Dir.glob("#{input}*") }
@@ -217,6 +147,8 @@ file = Clack.text(
 
 ### Password
 
+Masked text input for secrets and API keys.
+
 <img src="examples/images/password.svg" alt="Password prompt">
 
 ```ruby
@@ -228,7 +160,7 @@ secret = Clack.password(
 
 ### Multiline Text
 
-Multi-line text input. Enter inserts a newline, Ctrl+D submits.
+For when one line isn't enough. Enter inserts a newline, Ctrl+D submits.
 
 ```ruby
 bio = Clack.multiline_text(
@@ -240,6 +172,8 @@ bio = Clack.multiline_text(
 
 ### Confirm
 
+Yes/no toggle with customizable labels.
+
 <img src="examples/images/confirm.svg" alt="Confirm prompt">
 
 ```ruby
@@ -253,7 +187,7 @@ proceed = Clack.confirm(
 
 ### Select
 
-Single selection with keyboard navigation.
+Pick one from a list. Navigate with arrow keys or `hjkl`.
 
 <img src="examples/images/select.svg" alt="Select prompt">
 
@@ -272,7 +206,7 @@ db = Clack.select(
 
 ### Multiselect
 
-Multiple selections with toggle controls.
+Pick many. Toggle with Space. Select all with `a`. Invert with `i`.
 
 <img src="examples/images/multiselect.svg" alt="Multiselect prompt">
 
@@ -294,17 +228,18 @@ features = Clack.multiselect(
 
 ### Autocomplete
 
-Type to filter from a list of options. Filtering uses **fuzzy matching** by default -- characters must appear in order but don't need to be consecutive (e.g. "fb" matches "foobar"). Pass `filter:` to override with custom logic.
+Type to filter with fuzzy matching -- "fb" matches "foobar". Pass `filter:` to override with custom logic.
 
 ```ruby
 color = Clack.autocomplete(
   message: "Pick a color",
   options: %w[red orange yellow green blue indigo violet],
   placeholder: "Type to search...",
-  max_items: 5  # Default; scrollable via ↑↓
+  max_items: 5  # Default; scrollable via up/down arrows
 )
 
-# Custom filter logic (receives option hash and query string)
+# Custom filter logic (receives the option and query string).
+# The option is a value object; opt.label and opt[:label] both work.
 cmd = Clack.autocomplete(
   message: "Select command",
   options: commands,
@@ -312,11 +247,11 @@ cmd = Clack.autocomplete(
 )
 ```
 
-> Vim-style `j`/`k`/`h`/`l` navigation is not available — all keyboard input feeds into the search field. Use `↑↓` arrow keys to navigate results.
+> Vim-style `j`/`k`/`h`/`l` navigation is not available in autocomplete -- all keyboard input feeds into the search field. Use arrow keys to navigate results.
 
 ### Autocomplete Multiselect
 
-Type to filter with multi-selection support.
+Type-to-filter with multi-selection support.
 
 ```ruby
 colors = Clack.autocomplete_multiselect(
@@ -325,17 +260,17 @@ colors = Clack.autocomplete_multiselect(
   placeholder: "Type to filter...",
   required: true,              # At least one selection required
   initial_values: ["red"],     # Pre-selected values
-  max_items: 5                 # Default; scrollable via ↑↓
+  max_items: 5                 # Default; scrollable via up/down arrows
 )
 ```
 
 **Shortcuts:** `Space` toggle | `Enter` confirm
 
-> The `a` (select all), `i` (invert), and `j`/`k`/`h`/`l` shortcuts from `Multiselect` are not available here — all keyboard input feeds into the search field instead. Use `↑↓` arrow keys to navigate.
+> The `a` (select all), `i` (invert), and `j`/`k`/`h`/`l` shortcuts from Multiselect are not available here -- all keyboard input feeds into the search field instead. Use arrow keys to navigate.
 
 ### Path
 
-File/directory path selector with filesystem navigation.
+Filesystem navigation with Tab completion and arrow key selection.
 
 ```ruby
 project_dir = Clack.path(
@@ -345,7 +280,7 @@ project_dir = Clack.path(
 )
 ```
 
-**Navigation:** Type to filter | `Tab` to autocomplete | `↑↓` to select
+**Navigation:** Type to filter | `Tab` to autocomplete | up/down arrows to select
 
 ### Date
 
@@ -362,11 +297,11 @@ date = Clack.date(
 )
 ```
 
-**Navigation:** `Tab`/`←→` between segments | `↑↓` adjust value | type digits directly
+**Navigation:** `Tab`/left-right arrows between segments | up/down arrows to adjust value | type digits directly
 
 ### Range
 
-Numeric selection with a visual slider track. Navigate with `←→` or `↑↓` arrow keys (or `hjkl`).
+Visual slider for numeric selection.
 
 ```ruby
 volume = Clack.range(
@@ -376,11 +311,12 @@ volume = Clack.range(
   step: 5,
   initial_value: 50
 )
+# Navigate with arrow keys or hjkl
 ```
 
 ### Select Key
 
-Quick selection using keyboard shortcuts.
+Instant selection via keyboard shortcuts. No arrow key navigation needed.
 
 ```ruby
 action = Clack.select_key(
@@ -393,6 +329,34 @@ action = Clack.select_key(
 )
 ```
 
+### Group Multiselect
+
+Multiselect with options organized into named categories.
+
+```ruby
+features = Clack.group_multiselect(
+  message: "Select features",
+  options: [
+    {
+      label: "Frontend",
+      options: [
+        { value: "hotwire", label: "Hotwire" },
+        { value: "stimulus", label: "Stimulus" }
+      ]
+    },
+    {
+      label: "Background",
+      options: [
+        { value: "sidekiq", label: "Sidekiq" },
+        { value: "solid_queue", label: "Solid Queue" }
+      ]
+    }
+  ],
+  selectable_groups: true,  # Toggle all options in a group at once
+  group_spacing: 1          # Blank lines between groups
+)
+```
+
 ### Spinner
 
 Non-blocking animated indicator for async work.
@@ -411,7 +375,7 @@ spinner.stop("Dependencies installed!")
 # Or: spinner.cancel("Cancelled")
 ```
 
-**Block form** - wraps a block with automatic success/error handling:
+**Block form** -- wraps a block with automatic success/error handling:
 
 ```ruby
 result = Clack.spin("Installing dependencies...") { system("npm install") }
@@ -430,7 +394,7 @@ end
 
 ### Progress
 
-Visual progress bar for measurable operations.
+A visual progress bar for measurable operations.
 
 ```ruby
 progress = Clack.progress(total: 100, message: "Downloading...")
@@ -446,7 +410,7 @@ progress.stop("Download complete!")
 
 ### Tasks
 
-Run multiple tasks with status indicators.
+Run multiple tasks sequentially with status indicators.
 
 ```ruby
 results = Clack.tasks(tasks: [
@@ -472,63 +436,133 @@ Clack.tasks(tasks: [
 ])
 ```
 
-### Group Multiselect
-
-Multiselect with options organized into groups.
-
-```ruby
-features = Clack.group_multiselect(
-  message: "Select features",
-  options: [
-    {
-      label: "Frontend",
-      options: [
-        { value: "hotwire", label: "Hotwire" },
-        { value: "stimulus", label: "Stimulus" }
-      ]
-    },
-    {
-      label: "Background",
-      options: [
-        { value: "sidekiq", label: "Sidekiq" },
-        { value: "solid_queue", label: "Solid Queue" }
-      ]
-    }
-  ],
-  selectable_groups: true,  # Toggle all options in a group at once
-  group_spacing: 1          # Blank lines between groups
-)
-```
-
 <details>
-<summary><h3 style="display:inline">Quick Reference</h3></summary>
+<summary><strong>Quick Reference Table</strong> (click to expand)</summary>
 
 | Prompt | Method | Key Options | Defaults |
 |--------|--------|-------------|----------|
-| Text | `Clack.text` | `placeholder:`, `default_value:`, `initial_value:`, `completions:` | — |
+| Text | `Clack.text` | `placeholder:`, `default_value:`, `initial_value:`, `completions:` | -- |
 | Password | `Clack.password` | `mask:`, `validate:` | `mask: "▪"` |
 | Confirm | `Clack.confirm` | `active:`, `inactive:`, `initial_value:` | `active: "Yes"`, `inactive: "No"`, `initial_value: true` |
-| Select | `Clack.select` | `options:`, `initial_value:`, `max_items:` | — |
+| Select | `Clack.select` | `options:`, `initial_value:`, `max_items:` | -- |
 | Multiselect | `Clack.multiselect` | `options:`, `initial_values:`, `required:`, `cursor_at:` | `required: true` |
 | Group Multiselect | `Clack.group_multiselect` | `options:` (nested), `selectable_groups:`, `group_spacing:` | `selectable_groups: false` |
 | Autocomplete | `Clack.autocomplete` | `options:`, `placeholder:`, `filter:`, `max_items:` | `max_items: 5` |
 | Autocomplete Multiselect | `Clack.autocomplete_multiselect` | `options:`, `required:`, `initial_values:`, `filter:` | `required: true`, `max_items: 5` |
-| Select Key | `Clack.select_key` | `options:` (with `:key`) | — |
+| Select Key | `Clack.select_key` | `options:` (with `:key`) | -- |
 | Path | `Clack.path` | `root:`, `only_directories:` | `root: "."` |
 | Date | `Clack.date` | `format:`, `initial_value:`, `min:`, `max:` | `format: :iso` |
 | Range | `Clack.range` | `min:`, `max:`, `step:`, `initial_value:` | `min: 0`, `max: 100`, `step: 1` |
 | Multiline Text | `Clack.multiline_text` | `initial_value:`, `validate:` | Submit with **Ctrl+D** |
-| Spinner | `Clack.spinner` / `Clack.spin` | block form auto-handles success/error | — |
+| Spinner | `Clack.spinner` / `Clack.spin` | block form auto-handles success/error | -- |
 | Tasks | `Clack.tasks` | `tasks:` (`{title:, task:, enabled:}`) | `enabled: true` |
-| Progress | `Clack.progress` | `total:`, `message:` | — |
+| Progress | `Clack.progress` | `total:`, `message:` | -- |
 
 All prompts accept `message:`, `validate:`, `help:`, and return `Clack::CANCEL` on Escape/Ctrl+C.
 
 </details>
 
+---
+
+## Cancellation
+
+```ruby
+result = Clack.text(message: "Name?")
+exit 1 if Clack.cancel?(result)
+
+# Or the one-liner version (prints "Cancelled" and returns true)
+result = Clack.text(message: "Name?")
+exit 1 if Clack.handle_cancel(result)
+
+# With a custom message
+exit 1 if Clack.handle_cancel(result, "Aborted by user")
+```
+
+---
+
+## Validation and Transforms
+
+Every prompt supports `validate:` and `transform:`. The pipeline looks like this:
+
+```
+User Input --> Validation (raw) --> Transform (if valid) --> Final Value
+```
+
+Validation returns an error message, a `Clack::Warning`, or `nil` to pass.
+
+**Validation results:**
+- `nil` or `false` -- passes validation
+- String -- shows error (red), user must fix input
+- `Clack::Warning.new(message)` -- shows warning (yellow), user can confirm with Enter or edit
+
+```ruby
+# Symbol shortcuts (clean and idiomatic)
+name = Clack.text(message: "Name?", transform: :strip)
+code = Clack.text(message: "Code?", transform: :upcase)
+
+# Chain multiple transforms
+username = Clack.text(
+  message: "Username?",
+  transform: Clack::Transformers.chain(:strip, :downcase)
+)
+
+# Combine validation and transform
+amount = Clack.text(
+  message: "Amount?",
+  validate: ->(v) { "Must be a number" unless v.match?(/\A\d+\z/) },
+  transform: :to_integer
+)
+
+# Warning validation (soft failure -- user can confirm or edit)
+file = Clack.text(
+  message: "Output file?",
+  validate: ->(v) { Clack::Warning.new("File exists. Overwrite?") if File.exist?(v) }
+)
+```
+
+### Built-in Validators
+
+```ruby
+Clack::Validators.required              # Non-empty input
+Clack::Validators.min_length(3)         # Minimum character count
+Clack::Validators.max_length(100)       # Maximum character count
+Clack::Validators.format(/\A[a-z]+\z/, "Only lowercase")
+Clack::Validators.email                 # Email format (user@host.tld)
+Clack::Validators.url                   # URL format (http/https)
+Clack::Validators.integer               # Integer string ("-5", "42")
+Clack::Validators.in_range(1..100)      # Numeric range (parses as int)
+Clack::Validators.one_of(%w[a b c])     # Allowlist check
+Clack::Validators.path_exists           # File/dir exists on disk
+Clack::Validators.directory_exists      # Directory exists on disk
+Clack::Validators.future_date           # Date strictly after today
+Clack::Validators.past_date             # Date strictly before today
+Clack::Validators.date_range(min: d1, max: d2)  # Date within range
+Clack::Validators.combine(v1, v2)       # First error/warning wins
+
+# Warning validators -- allow user to confirm or edit
+Clack::Validators.file_exists_warning   # For file overwrite confirmations
+Clack::Validators.as_warning(validator) # Convert any validator to warning
+```
+
+### Built-in Transformers
+
+```ruby
+:strip / :trim      # Remove leading/trailing whitespace
+:downcase / :upcase # Change case
+:capitalize         # "hello world" -> "Hello world"
+:titlecase          # "hello world" -> "Hello World"
+:squish             # Collapse whitespace to single spaces
+:compact            # Remove all whitespace
+:to_integer         # Parse as integer
+:to_float           # Parse as float
+:digits_only        # Extract only digits
+```
+
+---
+
 ## Prompt Groups
 
-Chain multiple prompts and collect results in a hash. Cancellation is handled automatically.
+Chain multiple prompts and collect results in a hash. If the user cancels any prompt, the whole group returns `Clack::CANCEL`.
 
 ```ruby
 result = Clack.group do |g|
@@ -550,9 +584,11 @@ Clack.group(on_cancel: ->(r) { cleanup(r) }) do |g|
 end
 ```
 
-## Logging
+---
+
+## Pretty Printing
 
-Beautiful, consistent log messages.
+### Logging
 
 ```ruby
 Clack.log.info("Starting build...")
@@ -579,9 +615,9 @@ success = Clack.stream.command("npm install", type: :info)
 Clack.stream.success(io_stream)
 ```
 
-## Note
+### Note
 
-Display important information in a box.
+Display important information in a box:
 
 ```ruby
 Clack.note(<<~MSG, title: "Next Steps")
@@ -593,7 +629,7 @@ MSG
 
 ### Box
 
-Render a customizable bordered box.
+Render a customizable bordered box:
 
 ```ruby
 Clack.box("Hello, World!", title: "Greeting")
@@ -611,7 +647,7 @@ Clack.box(
 
 ### Task Log
 
-Streaming log that clears on success and shows full output on failure. Useful for build output.
+Streaming log that clears on success and shows full output on failure. Great for build output:
 
 ```ruby
 tl = Clack.task_log(title: "Building...", limit: 10)
@@ -626,6 +662,8 @@ tl.success("Build complete!")
 # tl.error("Build failed!")
 ```
 
+---
+
 ## Session Markers
 
 ```ruby
@@ -637,9 +675,9 @@ Clack.outro("Done!")        # └ Done!
 Clack.cancel("Aborted")     # └ Aborted (red)
 ```
 
-## Configuration
+---
 
-Customize key bindings and display options globally:
+## Configuration
 
 ```ruby
 # Add custom key bindings (merged with defaults)
@@ -657,6 +695,8 @@ When CI mode is active, prompts immediately submit with their default values ins
 
 Clack also warns when terminal width is below 40 columns, since prompts may not render cleanly in very narrow terminals.
 
+---
+
 ## Testing
 
 Clack ships with first-class test helpers. Require `clack/testing` explicitly (it is not auto-loaded):
@@ -692,12 +732,40 @@ The `PromptDriver` yielded to the block provides these methods:
 | `ctrl_d` | Press Ctrl+D (submit multiline text) |
 | `key(sym_or_char)` | Press an arbitrary key by symbol (e.g. `:escape`) or raw character |
 
+---
+
+## Try It
+
+```bash
+ruby examples/full_demo.rb
+```
+
+<details>
+<summary>Recording the demo GIF</summary>
+
+Requires [asciinema](https://asciinema.org/), [agg](https://github.com/asciinema/agg), and [expect](https://core.tcl-lang.org/expect/index):
+
+```bash
+# Record the demo (automated via expect script)
+asciinema rec examples/demo.cast --command "expect examples/demo.exp" --overwrite -q
+
+# Split batched frames to show typing (Ruby buffers terminal output)
+ruby examples/split_cast.rb
+
+# Convert to GIF
+agg examples/demo.cast examples/demo.gif --font-size 18 --cols 80 --rows 28 --speed 0.6
+```
+</details>
+
+---
+
 ## Requirements
 
 - Ruby 3.2+
 - No runtime dependencies
+- Unicode terminal recommended (ASCII fallbacks included)
 
-## Development
+### Development
 
 ```bash
 bundle install
@@ -706,9 +774,11 @@ bundle exec rake spec   # Tests only
 COVERAGE=true bundle exec rake spec  # With coverage
 ```
 
-## Roadmap
+### Roadmap
+
+- **Wizard mode** -- Multi-step flows with back navigation (`Clack.wizard`). The current `Clack.group` runs prompts as sequential Ruby code, so there's no way to "go back" and re-answer a previous question. A declarative wizard API would define steps as a graph with branching and let the engine handle forward/back navigation.
 
-- **Wizard mode** - Multi-step flows with back navigation (`Clack.wizard`). The current `Clack.group` runs prompts as sequential Ruby code, so there's no way to "go back" and re-answer a previous question. A declarative wizard API would define steps as a graph with branching and let the engine handle forward/back navigation.
+---
 
 ## Credits
 
@@ -716,4 +786,4 @@ This is a Ruby port of [Clack](https://github.com/bombshell-dev/clack), created
 
 ## License
 
-MIT - See [LICENSE](LICENSE)
+MIT -- See [LICENSE](LICENSE)