rooibos 0.5.0 → 0.6.0

data/doc/essentials/the_runtime.md

@@ -0,0 +1,21 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# The Runtime
+
+
+By the end of this guide, you will:
+
+- Describe how Rooibos orchestrates your Model, Update, and View
+- Enable debug mode for Ractor shareability validation
+- Explain when renders happen (after every UPDATE)
+- Use the `Cmd` and `Msg` shorthand aliases
+- Compare the runtime to Rails Rack request cycle
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+
+---
+
+[**Previous:** Commands](./commands.md) | [**Next:** Shortcuts](./shortcuts.md)

data/doc/essentials/update_functions.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Update Functions
+
+
+By the end of this guide, you will:
+
+- Write pure functions that return `[new_model, command]`
+- Explain why side effects are forbidden in UPDATE
+- Return `nil` when no async work is needed
+- Structure complex UPDATE logic with helper methods
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+
+---
+
+[**Previous:** Messages](./messages.md) | [**Next:** Views](./views.md)

data/doc/essentials/views.md

@@ -0,0 +1,22 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Views
+
+
+By the end of this guide, you will:
+
+- Understand that VIEW receives `(model, tui)` arguments
+- Explain what a VIEW callable returns (RatatuiRuby widgets)
+- Compose layouts using Rect, Constraint, and Layout (see RatatuiRuby docs)
+- Understand that VIEW is called on every render (keep it fast)
+- Know that VIEWs can accept kwargs for advanced composition (see Scaling Up)
+- Know when to link out to RatatuiRuby for widget details
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+
+---
+
+[**Previous:** Update Functions](./update_functions.md) | [**Next:** Commands](./commands.md)

data/doc/getting_started/for_go_developers.md

@@ -0,0 +1,16 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# For Go Developers
+
+
+By the end of this guide, you will:
+
+- Translate BubbleTea Model/Update/View to Rooibos equivalents
+- Identify Ruby syntax that differs from Go (blocks, symbols, no explicit types)
+- Understand how Rooibos handles Cmd differently than BubbleTea
+- Run the same counter example in both frameworks side-by-side
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).

data/doc/getting_started/for_python_developers.md

@@ -0,0 +1,16 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# For Python Developers
+
+
+By the end of this guide, you will:
+
+- Compare Rooibos to Textual approach (reactive vs. functional)
+- Map Python concepts to Ruby equivalents (decorators → blocks, dataclasses → Data.define)
+- Understand why immutable state simplifies async coordination
+- Identify key syntax differences (indentation vs. end, snake_case conventions)
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).

data/doc/getting_started/for_react_developers.md

@@ -0,0 +1,17 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# For React Developers
+
+
+By the end of this guide, you will:
+
+- Map React concepts to Rooibos equivalents (useState → Model, useReducer → Update)
+- Explain how Commands replace useEffect for side effects
+- Understand why Rooibos has no component lifecycle (and why that is simpler)
+- Translate "thinking in components" to "thinking in fragments"
+- Read Ruby syntax confidently after seeing the JS equivalent
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).

data/doc/getting_started/index.md

@@ -0,0 +1,52 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Getting Started
+
+By the end of this section, you will:
+
+- Identify which learning path matches your background
+- Know the prerequisites for building TUIs with Ruby
+- Choose where to start based on your experience level
+
+---
+
+## Choose Your Path
+
+### I want to understand the philosophy first
+
+→ [**Why Rooibos?**](./why_rooibos.md) — Learn what TUIs are, why functional state management matters, and how Rooibos compares to alternatives.
+
+### I want to start coding immediately
+
+→ [**Quickstart**](./quickstart.md) — Build your first Rooibos app in 5 minutes.
+
+### I'm new to Ruby
+
+→ [**Installation**](./install.md) — Set up Ruby on your system, then check out the [Ruby Primer](./ruby_primer.md) for language basics.
+
+---
+
+## Coming From Another Ecosystem?
+
+We've written guides that map familiar concepts to Rooibos:
+
+| Your Background | Guide |
+|-----------------|-------|
+| React / Redux | [For React Developers](./for_react_developers.md) |
+| Go / BubbleTea | [For Go Developers](./for_go_developers.md) |
+| Python / Textual | [For Python Developers](./for_python_developers.md) |
+
+---
+
+## What's Next?
+
+After getting started, continue to the **[Tutorial](../tutorial/index.md)** to build a complete File Browser application.
+
+For deep conceptual understanding, explore the **[Essentials](../essentials/the_elm_architecture.md)**.
+
+---
+
+[**Next:** Why Rooibos?](./why_rooibos.md)

data/doc/getting_started/install.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Installation
+
+
+By the end of this guide, you will:
+
+- Install Ruby on macOS, Linux, or Windows (for non-Rubyists)
+- Create a new Ruby project with Bundler
+- Add Rooibos and RatatuiRuby as dependencies
+- Verify your setup runs a minimal app
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+
+---
+
+[**Previous:** Why Rooibos?](./why_rooibos.md) | [**Next:** Quickstart](./quickstart.md)

data/doc/getting_started/quickstart.md

@@ -2,55 +2,19 @@
   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
+# Quickstart
 
-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._ |
+By the end of this guide, you will:
 
+- Run your first Rooibos application
+- Identify the three parts of an MVU app (Model, Update, View)
+- Make a change and see it reflected immediately
+- Know where to go next for deeper learning
 
-## Next Steps
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
 
-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)
+[**Previous:** Installation](./install.md)

data/doc/getting_started/ruby_primer.md

@@ -0,0 +1,19 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Ruby Primer
+
+
+By the end of this guide, you will:
+
+- Read and write basic Ruby syntax (variables, methods, classes)
+- Explain Ruby object model: everything is an object
+- Distinguish between symbols (`:key`) and strings (`"key"`)
+- Use blocks, procs, and lambdas for callbacks
+- Create immutable structs with `Data.define`
+- Handle nil safely (Ruby equivalent of null/None)
+- Call methods with keyword arguments
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).

data/doc/getting_started/why_rooibos.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Why Rooibos?
+
+
+By the end of this guide, you will:
+
+- Explain what a TUI (terminal user interface) is and why you would build one
+- Describe The Elm Architecture in one sentence
+- Compare Rooibos to alternatives (callbacks, threads, BubbleTea, Textual)
+- Articulate why functional state management prevents common bugs
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+
+---
+
+[**Previous:** Getting Started](./index.md) | [**Next:** Installation](./install.md)

data/doc/index.md

@@ -2,24 +2,92 @@
   SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
   SPDX-License-Identifier: CC-BY-SA-4.0
 -->
-# Start Here
 
+# Rooibos Documentation
 
-## Documentation for Users
+Build terminal user interfaces with Ruby using The Elm Architecture.
 
-- [README](../README.md): Project overview and installation
+---
 
-### Getting Started
+## 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
+New to Rooibos? Start here.
 
-### Concepts
+- [**Why Rooibos?**](./getting_started/why_rooibos.md) — What is a TUI? Why functional state management?
+- [**Installation**](./getting_started/install.md) — Set up Ruby and add Rooibos to your project
+- [**Quickstart**](./getting_started/quickstart.md) — Build your first app in 5 minutes
 
-- [Application Architecture](./concepts/application_architecture.md): Lifecycle patterns and API choices
-- [Testing Your Application](./concepts/application_testing.md): Snapshot testing and style assertions
+### Coming from another ecosystem?
 
+- [For React Developers](./getting_started/for_react_developers.md) — Redux → Rooibos mental model
+- [For Go Developers](./getting_started/for_go_developers.md) — BubbleTea → Rooibos translation
+- [For Python Developers](./getting_started/for_python_developers.md) — Textual → Rooibos translation
+- [Ruby Primer](./getting_started/ruby_primer.md) — Ruby basics for polyglots
 
-## Documentation for Contributors
+---
 
-- [Contributing Guidelines](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md): How to contribute patches and features
+## Tutorial
+
+Learn by building a complete **File Browser** application.
+
+→ [**Start the Tutorial**](./tutorial/index.md)
+
+---
+
+## Essentials
+
+Deep-dive into core concepts.
+
+- [The Elm Architecture](./essentials/the_elm_architecture.md) — Model-View-Update explained
+- [Models](./essentials/models.md) — Designing state with `Data.define`
+- [Messages](./essentials/messages.md) — Events and pattern matching
+- [Update Functions](./essentials/update_functions.md) — Pure state transitions
+- [Views](./essentials/views.md) — Rendering with RatatuiRuby
+- [Commands](./essentials/commands.md) — Async operations and side effects
+- [The Runtime](./essentials/the_runtime.md) — How Rooibos runs your app
+- [Shortcuts](./essentials/shortcuts.md) — `Cmd` and `Msg` aliases
+
+---
+
+## Scaling Up
+
+Advanced patterns for larger applications.
+
+- [Custom Commands](./scaling_up/custom_commands.md) — Write your own async commands
+- [Command Composition](./scaling_up/command_composition.md) — Chain and parallelize work
+- [Fractal Architecture](./scaling_up/fractal_architecture.md) — Nested fragments with `Cmd.map`
+- [Message Routing](./scaling_up/message_routing.md) — The Router DSL
+- [Ractor Safety](./scaling_up/ractor_safety.md) — Future-proof your app
+- [Async Patterns](./scaling_up/async_patterns.md) — Streaming, polling, websockets
+- [Testing](./scaling_up/testing.md) — Comprehensive testing strategies
+
+---
+
+## Best Practices
+
+Common UI patterns and recipes.
+
+- [Modal Dialogs](./best_practices/modal_dialogs.md)
+- [Forms and Validation](./best_practices/forms_and_validation.md)
+- [Lists and Tables](./best_practices/lists_and_tables.md)
+- [HTTP Workflows](./best_practices/http_workflows.md)
+- [Streaming Data](./best_practices/streaming_data.md)
+- [Orchestration](./best_practices/orchestration.md)
+
+---
+
+## Troubleshooting
+
+When things go wrong.
+
+- [Common Errors](./troubleshooting/common_errors.md) — Error messages and fixes
+- [Debugging](./troubleshooting/debugging.md) — Tracing and inspection
+- [Performance](./troubleshooting/performance.md) — Optimization tips
+
+---
+
+## For Contributors
+
+- [Documentation Plan](./contributors/documentation_plan.md) — The roadmap for these docs
+- [Documentation Style Guide](./contributors/documentation_style.md) — How to write docs
+- [Design Documents](./contributors/design/) — Architecture decisions

data/doc/scaling_up/async_patterns.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Async Patterns
+
+
+By the end of this guide, you will:
+
+- Handle streaming data from SSE or websockets
+- Implement polling with `Command.wait` and timers
+- Coordinate multiple async sources without race conditions
+- Clean up connections when your app exits
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+
+---
+
+[**Previous:** Ractor Safety](./ractor_safety.md) | [**Next:** Testing](./testing.md)

data/doc/scaling_up/command_composition.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Command Composition
+
+
+By the end of this guide, you will:
+
+- Chain dependent operations with `out.source`
+- Run parallel work with `out.standing`
+- Block until async commands complete with `out.wait`
+- Design multi-step async workflows
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+
+---
+
+[**Previous:** Custom Commands](./custom_commands.md) | [**Next:** Fractal Architecture](./fractal_architecture.md)

data/doc/scaling_up/custom_commands.md

@@ -0,0 +1,21 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Custom Commands
+
+
+By the end of this guide, you will:
+
+- Write a custom command using the `out` parameter
+- Implement cooperative cancellation with `token`
+- Define the correct call signature for your command
+- Override `rooibos_cancellation_grace_period` for cleanup time
+- Decide when to write a custom command vs. using built-ins
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+
+---
+
+[**Next:** Command Composition](./command_composition.md)

data/doc/scaling_up/fractal_architecture.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Fractal Architecture
+
+
+By the end of this guide, you will:
+
+- Compose child fragments using `Command.map`
+- Route parent messages to the correct child
+- Use the Router DSL to simplify complex routing
+- Decide when fractal architecture is worth the complexity
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+
+---
+
+[**Previous:** Command Composition](./command_composition.md) | [**Next:** Message Routing](./message_routing.md)

data/doc/scaling_up/index.md

@@ -0,0 +1,30 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Scaling Up
+
+Advanced patterns for building larger Rooibos applications.
+
+---
+
+## Custom Async Work
+
+- [**Custom Commands**](./custom_commands.md) — Write your own async commands with `out` and `token`
+- [**Command Composition**](./command_composition.md) — Chain and parallelize with `out.source`, `out.standing`
+
+## Application Architecture
+
+- [**Fractal Architecture**](./fractal_architecture.md) — Nested fragments with `Cmd.map`
+- [**Message Routing**](./message_routing.md) — The Router DSL for complex apps
+
+## Production Concerns
+
+- [**Ractor Safety**](./ractor_safety.md) — Future-proof your app for Ruby 4
+- [**Async Patterns**](./async_patterns.md) — Streaming, polling, websockets
+- [**Testing**](./testing.md) — Comprehensive testing strategies
+
+---
+
+**Looking for recipes?** Check out [Best Practices](../best_practices/modal_dialogs.md).

data/doc/scaling_up/message_routing.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Message Routing
+
+
+By the end of this guide, you will:
+
+- Use the Router DSL (`include Rooibos::Router` then `route :prefix, to: Module`)
+- Delegate messages to child fragments cleanly
+- Handle cross-cutting concerns (logging, analytics) centrally
+- Debug message routing with logging
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+
+---
+
+[**Previous:** Fractal Architecture](./fractal_architecture.md) | [**Next:** Ractor Safety](./ractor_safety.md)

data/doc/scaling_up/ractor_safety.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Ractor Safety
+
+
+By the end of this guide, you will:
+
+- Explain why Rooibos requires shareable state (future-proofing for Ruby 4)
+- Identify what makes an object shareable
+- Use the Callable pattern to capture data safely
+- Debug "not shareable" errors in tests and debug mode
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+
+---
+
+[**Previous:** Message Routing](./message_routing.md) | [**Next:** Async Patterns](./async_patterns.md)

data/doc/scaling_up/testing.md

@@ -0,0 +1,21 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Testing
+
+
+By the end of this guide, you will:
+
+- Test UPDATE functions as pure functions (input → output)
+- Mock or stub commands to avoid touching network/filesystem
+- Use `inject_key`/`inject_sync` helpers to test with real commands
+- Assert VIEW output using TestHelper
+- Structure test files for maintainability
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+
+---
+
+[**Previous:** Async Patterns](./async_patterns.md)

data/doc/troubleshooting/common_errors.md

@@ -0,0 +1,20 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Common Errors
+
+
+By the end of this guide, you will:
+
+- Recognize all Rooibos & RatatuiRuby error messages
+- Identify the root cause for each error
+- Apply the fix and verify it works
+- Know where to ask for help if you are stuck
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+
+---
+
+**Troubleshooting:** [Debugging](./debugging.md) | [Performance](./performance.md)

data/doc/troubleshooting/debugging.md

@@ -0,0 +1,21 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Debugging
+
+
+By the end of this guide, you will:
+
+- Enable `debug: true` to validate Ractor shareability and warn about callables missing Command::Custom
+- Use RatatuiRuby's breakpoint debugging features in an MVU context
+- Inspect Model state at any point in execution
+- Use Ruby's Logger gem for file logging when stdout is unavailable
+- Log messages in your Update function to trace application flow
+
+> ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+
+---
+
+**Troubleshooting:** [Common Errors](./common_errors.md) | [Performance](./performance.md)

data/doc/troubleshooting/index.md

@@ -0,0 +1,23 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Troubleshooting
+
+When things go wrong.
+
+---
+
+## Guides
+
+- [**Common Errors**](./common_errors.md) — Error messages, causes, and fixes
+- [**Debugging**](./debugging.md) — Tracing, logging, and inspection
+- [**Performance**](./performance.md) — Identifying and fixing bottlenecks
+
+---
+
+## Still Stuck?
+
+- Check the [RatatuiRuby Troubleshooting](https://ratatui-ruby.dev/docs) for widget-related issues
+- Open an issue on [GitHub](https://github.com/your-org/rooibos/issues)