rooibos 0.5.0

data/doc/contributors/design/commands_and_outlets.md

@@ -0,0 +1,214 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Custom Commands Design (`rooibos`)
+
+This document describes the architectural design and guiding principles of custom commands in `rooibos`. It is intended for contributors, architects, and AI agents working on the codebase.
+
+## Core Abstractions
+
+Custom commands extend Rooibos with user-defined side effects: WebSockets, gRPC, database polling, background workers. The architecture provides four key components:
+
+| Component | Purpose |
+|-----------|---------|
+| `Command::Custom` | Mixin for command identification |
+| `Command::Outlet` | Messaging gateway for result delivery |
+| `Command::CancellationToken` | Cooperative cancellation mechanism |
+| `Command.custom { ... }` | Wrapper giving callables unique identity |
+
+---
+
+## Guiding Design Principles
+
+### 1. Messaging Gateway over Raw Queue
+
+Commands produce messages. Those messages cross threads. Without abstraction, queue manipulation scatters across the codebase.
+
+The Outlet wraps the internal queue with a domain-specific API. Commands call `out.put(:tag, data)` instead of managing queue details. Debug mode validates Ractor-shareability automatically—commands cannot accidentally push unshareable data.
+
+| Aspect | Raw Queue | Outlet |
+|--------|-----------|--------|
+| Ractor safety | Manual | Automatic |
+| Error messages | Generic | Contextual |
+| API | `queue << Ractor.make_shareable([...])` | `out.put(:tag, data)` |
+| Pattern | Implementation detail | **Messaging Gateway** |
+
+This implements the **Messaging Gateway** pattern from Enterprise Integration Patterns. The Outlet is a **Facade** (Gang of Four) over the queue, and acts as a **Channel Adapter** translating command results into update function messages.
+
+### 2. Cooperative Cancellation over Thread Termination
+
+Long-running commands block the event loop. WebSocket listeners, database pollers, and streaming connections run indefinitely until stopped. Stopping them abruptly corrupts state.
+
+`Thread#kill` terminates immediately. Mutexes may deadlock. Resources may leak. Database transactions may abort mid-write.
+
+The `CancellationToken` signals cancellation requests. Commands check `token.cancelled?` periodically and stop at safe points. Cleanup code runs. Resources release. Transactions commit.
+
+| Aspect | `Thread#kill` | CancellationToken |
+|--------|---------------|------------------|
+| Cleanup | None (immediate termination) | Command controls cleanup |
+| Resource safety | May corrupt state | Clean shutdown |
+| Mutexes | May deadlock | Released properly |
+| Pattern | Forceful | **Cooperative** |
+
+**Configurable grace periods** accommodate different cleanup needs:
+
+- `0.5` seconds — Quick HTTP abort, minimal cleanup
+- `2.0` seconds — Default, suitable for most commands
+- `5.0` seconds — WebSocket close handshake with remote server
+- `Float::INFINITY` — Never force-kill (database transactions)
+
+### 3. Command Identity via Object Reference
+
+The runtime tracks active commands by their object identity. When the update function returns `Command.cancel(handle)`, the runtime looks up that exact object in its registry and signals its token.
+
+Class-based commands get unique identity automatically—each `MyCommand.new` produces a distinct object. Reusable lambdas and procs share identity. Dispatch them twice, and cancellation would affect both.
+
+`Command.custom(callable)` wraps a callable in a unique container. Each call produces a distinct handle. Store it in your model. Cancel it later by returning `Command.cancel(handle)`.
+
+### 4. Automatic Error Propagation
+
+Commands run in threads. Exceptions bubble up silently. The update function never sees them. Backtraces written to STDERR corrupt the TUI display.
+
+The runtime catches unhandled exceptions and pushes `Command::Error` to the queue. This is automatic—commands do not rescue exceptions unless they want custom handling. The update function pattern-matches on `Command::Error` and reacts appropriately.
+
+This mirrors the sentinel pattern used for `Command::Exit` and `Command::Cancel`.
+
+**Error categorization:** We use a single `Command::Error` sentinel for all command exceptions. Distinguishing "framework bugs" vs "user bugs" at the sentinel level adds complexity with marginal benefit. Instead, exception *classes* provide the signal:
+
+| Exception Class | Source |
+|-----------------|--------|
+| `RatatuiRuby::Error::Invariant` | Framework validation (debug mode) |
+| `RatatuiRuby::Error::Internal` | Framework bugs |
+| `ArgumentError`, `RuntimeError`, etc. | User code |
+
+The update function can pattern-match on `error_msg.exception.class` if it needs to distinguish sources.
+
+### 5. Ractor Readiness
+
+This design is forward-compatible with Ruby's Ractor-based parallelism.
+
+**What's already shareable:**
+
+| Pattern | Shareable? | Why |
+|---------|------------|-----|
+| Module-constant lambda | ✅ Yes | `self` is the frozen module |
+| Closure-free block | ✅ Yes | No captured variables |
+| `Data.define` command | ✅ Yes | Immutable by definition |
+| Frozen class instance | ✅ Yes | Deeply frozen |
+
+**Debug mode validation:**
+
+In debug mode, Rooibos validates Ractor shareability at dispatch time. `Ractor.shareable?(command)` catches most issues. The Outlet's `put` method validates messages before pushing them to the queue.
+
+**Why Thread dispatch is Ractor-safe:**
+
+Commands execute in Threads within the **main Ractor**. Only messages (via Outlet) cross the shareability boundary. The `CancellationToken` stays within its Thread—never shared across Ractors. The `@active_commands` hash is local to the Runtime (main Ractor).
+
+When Ruby evolves to true Ractor parallelism, this design upgrades transparently: commands are already validated as shareable, so they could be sent to worker Ractors without code changes.
+
+---
+
+## Pattern Lineage
+
+This design implements several established patterns from the software architecture literature.
+
+### Design Patterns (Gang of Four)
+
+| Component | Pattern |
+|-----------|---------|
+| Custom Mixin | **Command** — Encapsulates a request as an object |
+| Outlet | **Facade** — Simplified interface to a complex subsystem |
+| Runtime | **Mediator** — Coordinates command dispatch and message routing |
+| Update Function | **State** — Behavior changes based on internal state |
+
+### Enterprise Integration Patterns (Hohpe & Woolf)
+
+| Component | Pattern |
+|-----------|---------|
+| Outlet | **Messaging Gateway** — Wraps message channel access |
+| Outlet | **Channel Adapter** — Connects applications to messaging systems |
+| Queue | **Point-to-Point Channel** — Single consumer receives each message |
+
+### Cancellation Patterns
+
+| Platform | Mechanism | Relationship |
+|----------|-----------|--------------|
+| **.NET** | `CancellationToken` | Direct inspiration for API design |
+| **Go** | `context.Context` | Cooperative cancellation via `ctx.Done()` |
+| **JavaScript** | `AbortController` | Web Fetch API cancellation |
+| **Java** | `Thread.interrupt()` | Flag-based cooperative cancellation |
+| **Kotlin** | `Job.cancel()` | Coroutine cancellation |
+
+---
+
+## Prior Art
+
+### The Elm Architecture (TEA)
+
+| Framework | Language | Notes |
+|-----------|----------|-------|
+| **Elm** | Elm | Original TEA; `Cmd` + `Sub` primitives |
+| **BubbleTea** | Go | TUI implementation; "Subscriptions are Loops" philosophy |
+| **Iced** | Rust | GUI TEA with Command + Subscription |
+| **Miso** | Haskell | Web TEA with Effect + Sub |
+| **Bolero** | F# | Web TEA with Cmd + Sub |
+
+### Redux Ecosystem
+
+| Library | Pattern | Mapping |
+|---------|---------|---------|
+| **Redux Thunk** | Raw dispatch access | Direct queue access (rejected) |
+| **Redux Saga** | `put()` effect dispatches actions | **Outlet#put** ← adopted |
+| **Redux Observable** | RxJS Observables | RxRuby (rejected for complexity) |
+| **redux-loop** | Elm-style Cmd | Recursive commands |
+
+Redux Saga's `put()` is the direct inspiration for `out.put()`. The Saga pattern—long-running processes that listen for actions and dispatch new ones—maps directly to Rooibos's custom commands.
+
+### Ruby Ecosystem
+
+| Library | Pattern | Relationship |
+|---------|---------|--------------|
+| **Observable** (stdlib) | Observer pattern | Similar push semantics, lacks thread-safety |
+| **Concurrent Ruby** | Actor, Promises | More complex than needed |
+| **Celluloid** | Actor mailboxes | Inspiration for internal terminology |
+| **Sidekiq** | Background jobs | Similar "fire command, receive result" model |
+
+---
+
+## Key Influences Summary
+
+| Influence | What We Adopted |
+|-----------|-----------------|
+| **Elm** | MVU architecture, Cmd/Msg pattern |
+| **BubbleTea** | "Subscriptions are Loops" philosophy |
+| **Redux Saga** | `put()` for message dispatch |
+| **.NET CancellationToken** | Cooperative cancellation with grace periods |
+| **EIP Messaging Gateway** | Outlet as infrastructure abstraction |
+| **Go context.Context** | Cancellation propagation pattern |
+
+---
+
+## Further Reading
+
+### External Resources
+
+- [Elm Guide](https://guide.elm-lang.org/) — Official Elm documentation covering commands and effects
+- [BubbleTea](https://github.com/charmbracelet/bubbletea) — Go TUI framework based on The Elm Architecture
+- [Redux Saga](https://redux-saga.js.org/) — Saga pattern and `put()` effect documentation
+- [Enterprise Integration Patterns](https://www.enterpriseintegrationpatterns.com/) — Messaging patterns reference by Hohpe & Woolf
+
+### Academic References
+
+1. **Gamma, Helm, Johnson, Vlissides** (1994). *Design Patterns: Elements of Reusable Object-Oriented Software*. Addison-Wesley.
+   - Command, Facade, Mediator, State patterns
+
+2. **Fowler, M.** (2002). *Patterns of Enterprise Application Architecture*. Addison-Wesley.
+   - Gateway pattern
+
+3. **Hohpe, G. & Woolf, B.** (2003). *Enterprise Integration Patterns*. Addison-Wesley.
+   - Messaging Gateway, Message Channel, Point-to-Point Channel, Channel Adapter
+
+4. **Joshi, U.** (2023). *Patterns of Distributed Systems*. Addison-Wesley.
+   - Write-Ahead Log, Thread Pool

data/doc/contributors/kit-no-outlet.md

@@ -0,0 +1,238 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Why Kit Doesn't Need Outlet
+
+> **Context**: The `unified-draft.md` specifies `Rooibos::Command::Outlet` for message passing from custom commands to the Rooibos runtime. This document explains why Kit (the component-based runtime) does not need this abstraction.
+
+---
+
+## The Core Insight: Immediate-Mode Rendering
+
+RatatuiRuby's Engine is **immediate-mode**:
+
+> "Each frame, your code describes the entire UI from scratch. The Engine draws it and immediately forgets it, holding no application state between renders."
+
+This means Kit walks the entire component tree and calls `render` **every frame**. Components don't need to notify anyone of state changes—the next frame automatically sees updated state.
+
+---
+
+## Rooibos vs Kit: Different Problems
+
+| Concern | Rooibos | Kit |
+|---------|-----|-----|
+| **State model** | Immutable (Ractor-safe) | Mutable (encapsulated) |
+| **State location** | Single Model in runtime | Distributed in components |
+| **Async results** | Message → Queue → Update | Callback → mutate state |
+| **Render trigger** | After update function | **Every frame** |
+| **Re-render notification** | Implicit (update always renders) | **Not needed** (always renders) |
+
+---
+
+## WebSocket Example: Rooibos vs Kit
+
+### Rooibos: Outlet Required
+
+```ruby
+
+class WebSocketCommand
+  include Rooibos::Command::Custom
+
+  def call(out, token)
+    ws = WebSocket::Client.new(@url)
+    ws.on_message { |msg| out.put(:ws, :message, data: msg) }
+    ws.connect
+
+    until token.cancelled?
+      sleep 1
+    end
+
+    ws.close
+  end
+end
+
+def update(msg, model)
+  case msg
+  in [:ws, :message, data:]
+    model.with(messages: model.messages + [data])
+  end
+end
+```
+
+Rooibos needs Outlet because:
+1. Command runs in a separate thread
+2. Model is immutable—can't mutate from callback
+3. Runtime must receive messages to call `update`
+
+### Kit: Direct Mutation
+
+```ruby
+class WebSocketTab
+  include Kit::Component
+
+  def initialize(url:)
+    @url = url
+    @messages = []
+  end
+
+  def mount
+    @ws = WebSocket::Client.new(@url)
+    @ws.on_message { |msg| @messages << msg }
+    @ws.connect_async
+  end
+
+  def unmount
+    @ws&.close
+  end
+
+  def render(frame, area)
+    frame.render_widget(tui.list(items: @messages.last(10)), area)
+  end
+end
+```
+
+Kit doesn't need Outlet because:
+1. Component owns the WebSocket directly
+2. State is mutable—callbacks mutate `@messages`
+3. Next frame's `render` sees updated state automatically
+
+---
+
+## Why Each Rooibos Concept Is Unnecessary in Kit
+
+### Outlet (Message Gateway)
+
+**Rooibos**: Routes messages from command thread → runtime queue → update function.
+
+**Kit**: Not needed. Callbacks mutate component state directly. Immediate-mode rendering sees changes next frame.
+
+### CancellationToken
+
+**Rooibos**: Runtime signals command to stop cooperatively, since commands run in spawned threads tracked by the runtime.
+
+**Kit**: Not needed. Components have `unmount` lifecycle hook. Component stops its own resources:
+
+```ruby
+def unmount
+  @ws&.close
+  @polling_thread&.kill
+end
+```
+
+### Ractor Safety
+
+**Rooibos**: Messages cross thread boundaries and must be Ractor-shareable for future Ruby 4.0 compatibility.
+
+**Kit**: Not needed. Components are mutable by design. State stays within the component. No Ractor isolation required.
+
+### Thread Tracking
+
+**Rooibos**: Runtime tracks spawned command threads to ensure clean shutdown.
+
+**Kit**: Not needed. Each component tracks its own resources. Tree traversal during shutdown calls `unmount` on each component.
+
+---
+
+## What Kit DOES Need
+
+### 1. Lifecycle Hooks
+
+```ruby
+module Kit::Component
+  def mount
+    # Called when component enters tree
+  end
+
+  def unmount
+    # Called when component leaves tree
+  end
+end
+```
+
+These replace Rooibos's command spawning and cancellation.
+
+### 2. Thread Safety for Complex Mutations
+
+For simple mutations (array append, boolean toggle), Ruby's GIL is sufficient.
+
+For complex mutations:
+
+```ruby
+def mount
+  @mutex = Mutex.new
+  @ws = WebSocket::Client.new(@url)
+  @ws.on_message do |msg|
+    @mutex.synchronize { @messages << msg }
+  end
+end
+
+def render(frame, area)
+  messages = @mutex.synchronize { @messages.dup }
+  # render with messages
+end
+```
+
+### 3. Error Handling
+
+Components should rescue and surface errors:
+
+```ruby
+def mount
+  @ws = WebSocket::Client.new(@url)
+  @ws.on_error { |e| @error = e.message }
+rescue => e
+  @error = e.message
+end
+```
+
+---
+
+## Comparison Table
+
+| Abstraction | Rooibos | Kit | Why Different |
+|-------------|-----|-----|---------------|
+| **Outlet** | ✓ Required | ✗ Not needed | Kit mutates directly |
+| **CancellationToken** | ✓ Required | ✗ Not needed | Kit has `unmount` |
+| **Ractor safety** | ✓ Required | ✗ Not needed | Kit is mutable |
+| **Thread tracking** | ✓ Runtime tracks | ✗ Not needed | Components self-manage |
+| **Lifecycle hooks** | ✗ Not applicable | ✓ Required | Kit needs mount/unmount |
+| **Mutex** | ✗ Uses Outlet | ⚠ If complex | Kit needs manual locking |
+
+---
+
+## Architectural Summary
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                          ENGINE                                  │
+│               (Immediate-mode, renders every frame)              │
+├─────────────────────────────┬───────────────────────────────────┤
+│         ROOIBOS             │              KIT                   │
+│                             │                                    │
+│  Immutable Model            │  Mutable Components                │
+│  Commands spawn threads     │  Components own resources          │
+│  Outlet sends messages      │  Callbacks mutate state            │
+│  Runtime tracks threads     │  unmount cleans up                 │
+│  Ractor-safe required       │  GIL + Mutex sufficient            │
+│                             │                                    │
+│  NEEDS OUTLET               │  DOESN'T NEED OUTLET               │
+└─────────────────────────────┴───────────────────────────────────┘
+```
+
+---
+
+## Conclusion
+
+**Outlet is Rooibos-specific.** It solves the problem of getting async results into an immutable, unidirectional data flow.
+
+Kit's paradigm—mutable components with immediate-mode rendering—makes Outlet unnecessary:
+
+1. **Callbacks mutate state** → No message routing needed
+2. **Render every frame** → No change notification needed
+3. **`unmount` hook** → No external cancellation needed
+4. **Components own resources** → No runtime tracking needed
+
+The Outlet stays in `Rooibos::Command::Outlet`. Kit needs no equivalent.

data/doc/contributors/priorities.md

@@ -0,0 +1,38 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Feature Priorities
+
+This document outlines the remaining work before `rooibos` reaches v1.0.0.
+
+## 1. Built-In Commands
+
+Six primitives remain unimplemented. See [Command Composition Design](./design/command_composition.md) for full specifications.
+
+| Command / Method | Purpose | Complexity |
+|------------------|---------|------------|
+| `Command.wait(seconds, tag)` | One-shot timer | Low |
+| `Command.tick(interval, tag)` | Recurring timer (subscriptions) | Low |
+| `Command.batch([...])` | Parallel execution (fire-and-forget) | Medium |
+| `Command.all([...])` | Parallel execution (aggregating) | Medium |
+| `Command.http(method, url, tag)` | HTTP requests via stdlib | Medium |
+| `Outlet#source(command, token)` | Command composition | Low |
+
+Implementation order follows increasing complexity. Each can be tested independently.
+
+> [!NOTE]
+> `Command.sequence` was considered but rejected. See [Rejected Alternatives](./design/command_composition.md#rejected-alternatives) for rationale.
+
+## 2. Documentation
+
+The README warns: "Because this gem is in pre-release, it lacks documentation."
+
+Before v1.0.0:
+
+- [ ] Document all public `Command.*` factories with RDoc examples
+- [ ] Write Quickstart guide
+- [ ] Write Fractal Architecture guide
+- [ ] Write Custom Commands guide (including `out.source` composition)
+- [ ] Ensure all examples are copy-pasteable and tested

data/doc/custom.css

@@ -0,0 +1,22 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+
+img {
+  max-width: 100%;
+  height: auto;
+}
+
+.theme-toggle {
+  margin-left: 0 !important;
+}
+
+/* Terminal Previews (Native PNGs)
+ * The images already contain the window chrome and shadows.
+ * We just need to center them and ensure they scale down on mobile.
+ */
+img[src*="images/"] {
+  display: block;
+  margin: 2em auto;
+}

data/doc/getting_started/quickstart.md

@@ -0,0 +1,56 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Quickstart
+
+Welcome to **rooibos**! This guide will help you get up and running with your first Terminal User Interface in Ruby.
+
+## Installation
+
+See [Installation in the README](../README.md#installation) for setup instructions.
+
+
+## Tutorials
+
+### Basic Application
+
+Here is a "Hello World" application that demonstrates the core lifecycle of a **rooibos** app.
+
+_Because this gem is in pre-release, it lacks documentation. Please check the source files.
+
+#### How it works
+
+_Because this gem is in pre-release, it lacks documentation. Please check the source files.
+
+## Examples
+
+These examples showcase the full power of **rooibos**. You can find their source code in the [examples directory](../examples).
+
+### Widget Demos
+
+Focused examples for individual concepts. Each demonstrates a single concept and ways to interact with it.
+
+| Widget | What it demonstrates |
+|--------|---------------------|
+| _Automated Tests_ | _Because this gem is in pre-release, it lacks documentation. Please check the automated tests for details._ |
+
+### Sample Applications
+
+These larger examples combine concepts into complete applications, demonstrating real-world TUI patterns and architectures.
+
+| Application | Architecture | What you'll learn |
+|-------------|--------------|-------------------|
+| _Automated Tests_ | _Because this gem is in pre-release, it lacks documentation. Please check the automated tests for details._ |
+
+
+## Next Steps
+
+Now that you've seen what **rooibos** can do:
+
+- **Deep dive**: Read the [Application Architecture](../concepts/application_architecture.md) guide for scaling patterns
+- **Test your TUI**: See the [Testing Guide](../concepts/application_testing.md) for snapshot and style assertions
+- **Avoid common mistakes**: See [Terminal Output During TUI Sessions](https://man.sr.ht/~kerrick/ratatui_ruby/troubleshooting/tui_output.md) to prevent screen corruption
+- **Explore the API**: Browse the [full documentation](../index.md)
+- **Learn the philosophy**: Read [Why RatatuiRuby?](https://man.sr.ht/~kerrick/ratatui_ruby/why.md) for comparisons and design decisions
+- **Get help**: Join the [discussion mailing list](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss)

data/doc/index.md

@@ -0,0 +1,25 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Start Here
+
+
+## Documentation for Users
+
+- [README](../README.md): Project overview and installation
+
+### Getting Started
+
+- [Why RatatuiRuby?](https://man.sr.ht/~kerrick/ratatui_ruby/why.md): Philosophy, comparisons, and what makes us different
+- [Quickstart](./getting_started/quickstart.md): Build your first TUI app
+
+### Concepts
+
+- [Application Architecture](./concepts/application_architecture.md): Lifecycle patterns and API choices
+- [Testing Your Application](./concepts/application_testing.md): Snapshot testing and style assertions
+
+
+## Documentation for Contributors
+
+- [Contributing Guidelines](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md): How to contribute patches and features

data/examples/app_fractal_dashboard/README.md

@@ -0,0 +1,60 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Cmd.map Fractal Dashboard
+
+Demonstrates **Fractal Architecture** using `Cmd.map` for component composition.
+
+## Problem
+
+Without composition, a complex app needs one giant `case` statement handling every possible message from every child—the "God Reducer" anti-pattern. This doesn't scale.
+
+## Solution
+
+`Cmd.map` wraps child commands so their results route through parents:
+
+```ruby
+# Child produces [:system_info, {stdout:, ...}]
+child_cmd = SystemInfoWidget.fetch_cmd
+
+# Parent wraps to produce [:stats, :system_info, {...}]
+parent_cmd = Cmd.map(child_cmd) { |m| [:stats, *m] }
+```
+
+Each layer handles only its own messages. Parents pattern-match on the first element to route to the correct child.
+
+## Architecture
+
+```
+Dashboard (root)
+├── StatsPanel
+│   ├── SystemInfoWidget → Cmd.exec("uname -a", :system_info)
+│   └── DiskUsageWidget  → Cmd.exec("df -h", :disk_usage)
+└── NetworkPanel
+    ├── PingWidget       → Cmd.exec("ping -c 1 localhost", :ping)
+    └── UptimeWidget     → Cmd.exec("uptime", :uptime)
+```
+
+## Hotkeys
+
+| Key | Action |
+|-----|--------|
+| `s` | Fetch system info |
+| `d` | Fetch disk usage |
+| `p` | Ping localhost |
+| `u` | Fetch uptime |
+| `q` | Quit |
+
+## Key Concepts
+
+1. **Widget isolation**: Each widget has its own `Model`, `UPDATE`, and `fetch_cmd`. It knows nothing about parents.
+2. **Message routing**: Parents prefix child messages (`:stats`, `:network`) and pattern-match to route.
+3. **Recursive dispatch**: `Cmd.map` delegates inner command execution to the runtime, then transforms the result.
+
+## Usage
+
+```bash
+ruby examples/widget_cmd_map/app.rb
+```