Background

v0.1 ships as a CLI: scan, issues, auth, fix, submit, config. The original design (see docs/design.md) called for a terminal UI; ADR-0010 records the decision to build it on bubbletea-ruby (Charm's Bubble Tea ported to Ruby) with lipgloss-ruby for styling. ADR-0010 supersedes the earlier ADR-0008 (Rooibos) — read it for the framework-choice reasoning.

The CLI's data layer is already shaped for the TUI: parsers, resolvers, and adapters return plain values, all the long-running I/O is structured so it can be wrapped in bubbletea Commands without orchestration code, and the CLI subcommands only do orchestration the TUI will replace.

What this issue covers

A working Stage 3 TUI that gets a user from "I have a Gemfile.lock" to "I have a working branch on a forked issue" without typing a subcommand.

Minimum viable scope:

• Top-level list view of the ranked scan results (the same projects today's gem-contribute scan prints).
• Enter drills into a project's open issues (today's gem-contribute issues <gem> output).
• f on a selected issue triggers the fork-clone-branch state machine and displays progress (today's gem-contribute fix <gem>/<n>).
• q quits.
• Status line shows current GitHub rate-limit (the adapter already records it).

Out of scope for this issue (file separately if wanted):

• c to read CONTRIBUTING.md inline — see ADR-0007, which deliberately rejects in-tool summarization. A "view the file" pane would be in scope; "summarize the contributing guide" would not.
• A submit keybinding from inside the TUI. The Stage 4 question is whether submit is a TUI flow or stays a CLI follow-up.

Implementation notes

• ADR-0010 explains the reasoning for bubbletea-ruby over Rooibos and bare ratatui.
• All async work goes through bubbletea Commands (a Bubbletea::Cmd is a closure that returns a message). Do not spawn threads or use Async. Resolver, adapter, and git shell-outs already structure their I/O so they can be wrapped trivially. Define thin helpers — http_command(url, envelope:), system_command(argv, envelope:), wait_command(seconds, envelope:) — once, and use them everywhere.
• Tests for the TUI: assert colors and modifiers in the view (lipgloss styling), and use system tests that inject events and snapshot results. Pure-function update testing is the bedrock — pre-merge, verify bubbletea-ruby's test helpers (or port teatest patterns from Go's bubbletea / build a minimal snapshot harness).
• The CLI subcommands stay. The TUI is additive — gem-contribute (no args) opens the TUI; the existing subcommands keep working as scriptable equivalents.

Acceptance criteria

• Running gem-contribute (no arguments) launches the TUI.
• List view renders within ~500ms on a cached scan.
• Drill-down to issues works, with labels rendered verbatim per ADR-0005.
• f triggers fork-clone-branch and shows progress as the state machine advances.
• Specs cover the update methods, view rendering, and at least one end-to-end snapshot test.

Related

• ADR-0010: Use Charm-Ruby (bubbletea + lipgloss) for the TUI layer
• ADR-0008: Use Rooibos for the TUI layer (superseded)
• ADR-0005: Render labels verbatim
• Issue Add preferred_labels config so non-canonical good-first-issue labels are caught #1 (preferred labels — orthogonal but lands in the same UI)