gem-contribute 0.1.0

data/docs/adr/0004-device-flow-auth.md

@@ -0,0 +1,36 @@
+# ADR 0004: OAuth Device Flow, not Personal Access Tokens
+
+**Status:** Accepted
+**Date:** 2026-04-27
+
+## Context
+
+To fork repos and clone forks on a user's behalf, `gem-contribute` needs an authenticated GitHub session. Two practical options:
+
+1. **Personal Access Token (PAT).** User generates a token in GitHub settings, pastes it into the tool.
+2. **OAuth Device Authorization Grant ("device flow").** Tool displays a code; user opens browser, signs in, enters code; tool polls for the token. Same UX as `gh auth login`.
+
+## Decision
+
+Device flow.
+
+## Reasoning
+
+UX. The PAT flow is genuinely awful: navigate to settings, click through several screens, choose scopes you don't fully understand, name the token, copy it within the one-time-display window, paste it into the tool, hope you didn't fat-finger it. Half the people in the workshop room will lose three minutes to this and one will lose ten.
+
+Device flow is approximately: type `gem-contribute`, click a button in your already-open browser, done. About 30 seconds, no copy-paste, no leaked tokens in shell history.
+
+Critically for an open-source CLI: device flow needs only a `client_id`, no client secret. We can ship the client ID as a public constant in the source code. There is no secret to protect. This is by design — GitHub's docs explicitly support this pattern.
+
+## Alternatives considered
+
+- **PAT only.** Rejected for UX reasons above.
+- **Both, with PAT as fallback.** Reasonable; deferred to v0.2 if anyone asks. The ground-truth use case (corporate networks where the device-flow polling fails for some reason) is real but rare.
+- **GitHub App instead of OAuth App.** GitHub Apps are more powerful and more correct in the long run, but they require token refresh logic and a higher prep burden. Defer until there's a reason to switch.
+
+## Consequences
+
+- The maintainer (initially: Chris) registers an OAuth App on a personal GitHub account and copies the client ID into the source. When the tool is donated to a more permanent home, the OAuth App migrates with it.
+- Rate limits: 50 `user_code` submissions per hour across all users of this client ID. With workshop-scale usage (~12 attendees authing once each), this is fine. If the tool ever gets popular enough to brush this limit, we register additional OAuth Apps or switch to a GitHub App.
+- We must implement: device code request, polling with `slow_down` backoff, token storage at `~/.config/gem-contribute/auth.json` (mode 0600), and graceful handling of the 15-minute device-code expiry.
+- Scope is `public_repo` only at v1. Adding `repo` (for private repos) would be a future ADR.

data/docs/adr/0005-render-labels-verbatim.md

@@ -0,0 +1,46 @@
+# ADR 0005: Render labels verbatim
+
+**Status:** Accepted
+**Date:** 2026-04-27
+
+## Context
+
+GitHub label conventions vary across projects. Common variants meaning roughly "this is approachable for new contributors":
+
+- `good first issue`
+- `good-first-issue`
+- `Good First Issue`
+- `beginner`
+- `easy`
+- `help wanted`
+- `up-for-grabs`
+- `low-hanging fruit`
+- (none — the maintainer doesn't tag at all)
+
+We could normalize these to a canonical set ("Beginner-friendly", "Help wanted", etc.) for cleaner UI. We could also leave them exactly as the maintainer wrote them.
+
+## Decision
+
+Render labels exactly as the maintainer wrote them, with the colors GitHub returns. Allow the user to specify a `preferred_labels` list in config that controls highlighting and sort order, but don't rewrite anything.
+
+## Reasoning
+
+Two reasons, one technical and one social.
+
+**Technical:** Normalization is a heuristic. Heuristics are wrong sometimes. When the heuristic gets it wrong — say, a project uses `easy` to mean "easy to fix once you understand the architecture" rather than "easy for a beginner" — normalization loses information the maintainer encoded deliberately. The user is better served by the raw label and the exercise of reading it in context.
+
+**Social:** The act of reading a project's labels *is* contributor onboarding. It's how you start to understand a project's voice, its triage workflow, its expectations. A tool that smooths that over removes a learning surface. We are not in the business of removing learning surfaces from people who are explicitly here to learn open-source contribution.
+
+The `preferred_labels` config is the escape valve for users who want their own ranking. It's user-controlled, not algorithmic. Different.
+
+## Alternatives considered
+
+- **Normalize to a fixed taxonomy.** Loses information; opinionated in a way the tool shouldn't be. Rejected.
+- **Show normalized labels alongside raw ones.** Visual clutter. The thing we're optimizing for (fast scanning of issue lists) gets worse, not better. Rejected.
+- **Let the user define normalizations in config.** This is approximately what `preferred_labels` does without claiming to normalize. Accepted in that form.
+
+## Consequences
+
+- Issue list rendering must preserve label colors from the GitHub API.
+- `preferred_labels` matches case-insensitively against the raw label text. Hyphens and spaces are treated as equivalent. That's the only normalization we do, and it's only for the user's own preference matching.
+- Users who want a different taxonomy can edit their config. We don't ship one.

data/docs/adr/0006-standalone-gem-not-plugin.md

@@ -0,0 +1,31 @@
+# ADR 0006: Standalone gem, not a Bundler plugin
+
+**Status:** Accepted
+**Date:** 2026-04-27
+
+## Context
+
+Bundler supports plugins that extend `bundle` with new subcommands. A natural-feeling distribution would be `bundle contribute`, mirroring `bundle fund`. Alternatively, we ship as a standalone gem invoked as `gem-contribute`.
+
+## Decision
+
+Standalone gem at v1. Bundler plugin path is not foreclosed; it just isn't v1's problem.
+
+## Reasoning
+
+Bundler plugin authoring has its own learning curve, its own API surface, and its own debugging story. None of that is the part of this project we want attendees of the Blue Ridge Ruby workshop to learn. They're here to learn Ratatui and OAuth and GitHub's API. The Bundler plugin packaging concerns would actively distract.
+
+A standalone gem also keeps the dev loop shorter: clone, `bundle install`, `bin/gem-contribute`. Plugin development requires installing into Bundler's plugin directory and reasoning about how Bundler isolates plugin gems.
+
+The user-facing UX difference is small. `bundle contribute` is two characters shorter than `gem-contribute` and feels more native. That's not zero, but it's not v1's priority either.
+
+## Alternatives considered
+
+- **Plugin from day one.** Rejected: scope creep for the workshop; harder to maintain; harder for new contributors to dive into.
+- **Both.** Rejected: more API surface to keep aligned, double the support burden.
+
+## Consequences
+
+- The CLI binary is `gem-contribute`, not `bundle contribute`.
+- Users who want the `bundle contribute` UX can write a one-line shell alias.
+- A future ADR can revisit this if the tool sees real adoption and the plugin UX becomes the bottleneck.

data/docs/adr/0007-display-contributing-verbatim.md

@@ -0,0 +1,39 @@
+# ADR 0007: Show CONTRIBUTING; don't parse it
+
+**Status:** Accepted
+**Date:** 2026-04-27
+
+## Context
+
+When a user is about to fork-and-branch on an issue, it would be useful to surface the project's contribution guidelines. CONTRIBUTING.md is the canonical location, with `.github/CONTRIBUTING.md` and `docs/CONTRIBUTING.md` as common alternates. GitHub's community profile API (`/repos/:owner/:repo/community/profile`) returns the path of whichever exists.
+
+Two ways to use that file:
+
+1. **Display it.** Show the markdown in a pane. User reads it.
+2. **Parse it.** Programmatically extract things like "this project uses these labels," "PRs require DCO sign-off," "tests are required," etc.
+
+## Decision
+
+Display, don't parse.
+
+## Reasoning
+
+Parsing CONTRIBUTING.md across thousands of projects is heuristic work. The files are written in prose by humans for humans, with no schema, no consistent terminology, and no obligation to be parseable. Any extraction layer we ship will be wrong some of the time, in subtle ways, on the projects that matter most (the ones with non-standard but important guidelines).
+
+The cost of being wrong here is high. A user who relies on a misparsed CONTRIBUTING and opens a PR that violates an unwritten convention is in a worse position than a user who reads the file themselves and notices the convention.
+
+There's also a softer reason: reading a project's CONTRIBUTING is part of the contribution itself. It's where you learn the project's voice and norms. Hiding that behind extracted bullet points makes the user a worse contributor over time.
+
+The pragmatic version of "display, don't parse" is good enough: render the markdown nicely (headings, lists, code blocks, links), let the user scroll through it, surface a "you haven't read this yet" indicator on the issue detail screen if they try to fork before opening CONTRIBUTING.
+
+## Alternatives considered
+
+- **Parse for known signals.** Look for backticked label names, URL patterns, common phrases like "sign your commits." Possibly v0.3+; not v1. The risk is that we introduce the parsing infrastructure and then everyone wants to extend it, and we end up with a half-built NLP system in a TUI tool.
+- **AI-summarize the CONTRIBUTING.** Out of scope, out of character for this project, and an additional dependency we don't want.
+- **Don't surface CONTRIBUTING at all.** Surfacing it is one of the tool's quietly-best features. Rejected.
+
+## Consequences
+
+- We need a markdown renderer that works in a Ratatui pane. There are a few; pick the smallest one that handles headings, lists, code blocks, and links.
+- The "have you read CONTRIBUTING" indicator is local UI state. We track whether the user has opened the CONTRIBUTING pane for the current project in this session. We don't persist this — re-prompting on a fresh run is fine.
+- If someone wants parsing, they can build it as a separate gem that consumes our output.

data/docs/adr/0008-rooibos-tui-framework.md

@@ -0,0 +1,62 @@
+# ADR 0008: Use Rooibos for the TUI layer
+
+**Status:** Accepted
+**Date:** 2026-04-27
+**Supersedes parts of:** the original "TUI built directly on `ratatui_ruby`" approach implied by ADR-0001 and the `docs/design.md` v1.
+
+## Context
+
+`gem-contribute` is a TUI that needs to:
+
+1. Make multiple HTTP calls (RubyGems API, GitHub API, GitHub OAuth device flow polling) without freezing the UI.
+2. Shell out to `git` for fork-clone-branch, also without freezing the UI.
+3. Compose four primary views (project list → issues → issue detail → CONTRIBUTING) with the auth-prompt flow able to interrupt any of them.
+4. Be testable enough that the gem can be maintained past the conference without breaking on every PR.
+
+[`ratatui_ruby`](https://www.ratatui-ruby.dev/) provides the rendering layer, but leaves state management, threading, message dispatch, and testing as exercises for the consumer. [`rooibos`](https://www.rooibos.run/) is a higher-level framework by the same maintainer (Kerrick Long) that layers Model-View-Update on top of `ratatui_ruby`, with async Commands for off-thread work and built-in snapshot testing.
+
+## Decision
+
+Use Rooibos as the TUI framework. `ratatui_ruby` remains a transitive dependency for rendering and widgets, but the application's state, message handling, and async work are expressed in Rooibos terms.
+
+## Reasoning
+
+**The async command pattern is the right abstraction for our problem.** Fork-clone-branch can take 30+ seconds against a large repo. GitHub API calls are routinely 200-500ms. Device-flow polling runs every 5 seconds for up to 15 minutes. Doing any of these on the main thread freezes the UI; doing them ourselves means hand-rolling thread management, message queues, and cancellation. Rooibos provides `Command.system`, `Command.http`, `Command.wait`, and `Command.cancel` as first-class primitives that run off-thread and deliver results back as messages. This is exactly the surface we need.
+
+**Testing is dramatically better.** The original design doc said "no TUI tests at v1, the cost-benefit isn't there." With Rooibos, `Update` is a pure function `(message, model) → model | [model, command]`. Pure functions test trivially, no terminal, no setup, no mocking. View tests use a headless terminal with style assertions. System tests inject events and snapshot results. The pre-conference test commitment goes from "parsers and resolvers only" to "the entire state machine, including the auth flow." This isn't a stretch goal — it's free with the framework.
+
+**The fractal architecture maps to our four-view structure.** Rooibos's Router DSL composes parent fragments out of child fragments. Each view (project list, issue list, issue detail, CONTRIBUTING viewer) becomes a fragment with its own `Model`, `View`, `Update`, and `Init`. The parent dispatches messages to children based on routing rules. This is a structure we'd have to invent and document if we built directly on `ratatui_ruby`; we get it for free.
+
+**The auth flow becomes legible.** With imperative Ratatui, JIT auth requires interrupting the current screen, blocking on a sub-flow, and resuming. With MVU, an `:auth_required` message triggers a state transition; the device-flow polling is a sequence of Commands; the original action retries via another message after success. The whole thing is a state machine, expressed in code as a state machine, testable as a state machine. See ADR-0001 for what this changes.
+
+**Same maintainer as `ratatui_ruby`.** Reduces the chance of cross-library impedance mismatch. Rooibos is the maintainer's opinionated answer to "how should you actually build with this rendering layer."
+
+## Alternatives considered
+
+- **Plain `ratatui_ruby` with our own state and threading.** What the design doc originally implied. Rejected: more code to write and maintain, worse testing story, and we'd be reinventing primitives that Rooibos already provides better. The savings from "fewer dependencies" are dwarfed by the cost of building this layer ourselves.
+
+- **Kit.** Also by Kerrick, OOP component-based, tracked at <https://sr.ht/~kerrick/ratatui_ruby/#chapter-3-the-object-path--kit>. Reasonable for component-heavy UIs with stateful widgets. Rejected for this project: our domain is event-driven and async-heavy (HTTP, system calls, polling), which matches MVU's strengths, and pure-function `Update` is the testing story we want.
+
+- **Wait for Rooibos 1.0.** Rooibos is currently 0.7 with "APIs may change before 1.0." Waiting is the conservative choice. Rejected: the 1.0 timeline is unknown, and the architectural fit is too good to defer. We pin to a specific version and adapt to changes when they come.
+
+## Consequences
+
+**On the design doc:** the "Modules" section needs revision. Views become Rooibos fragments, not bare classes. The `Worker` module disappears — fork-clone-branch is a sequence of Commands emitted from `Update`. The architecture diagram becomes MVU-shaped. Testing strategy shifts from "test the boundaries, skip the TUI" to "test the Update functions everywhere."
+
+**On dependencies:** add `rooibos` to the gemspec. Pin to `~> 0.7.0` for v0.1 (allows patch updates within 0.7, blocks 0.8+ until we audit). Bump deliberately, with an ADR if the bump requires meaningful changes.
+
+**On the workshop:** attendees learn MVU, not just `ratatui_ruby` widgets. This is a real cost — the lambda-as-constant style (`Init = ->`, `View = ->`) is unfamiliar to most Rails developers. Mitigation: the workshop README explicitly frames Rooibos as "the framework," explains MVU in two paragraphs, and points at the "Coming From Rails" guide on rooibos.run before the workshop. Attendees who finish a Rooibos workshop end up with an actually-transferable mental model (MVU shows up in Elm, Redux, Bubble Tea, and increasingly elsewhere).
+
+**On Ractor:** Rooibos uses `Ractor.make_shareable` for thread-safe state. Most Ruby developers have read about Ractors but not used them. The pattern is encapsulated in `Init` and `Update.with(...)`; attendees don't need a deep Ractor mental model to write fragments. Worth a sentence in the workshop preamble, not more.
+
+**On the maintainer relationship:** Kerrick Long maintains both `ratatui_ruby` and Rooibos. Reaching out before the workshop to mention "we're building a workshop project on Rooibos for Blue Ridge Ruby" is good practice — early flag of API changes, possible feedback, possible amplification.
+
+## What this *doesn't* change
+
+- Just-in-time auth (ADR-0001). Implementation cleaner; decision unchanged.
+- Bundler's lockfile parser (ADR-0002). Outside the TUI layer entirely.
+- Issue tracker URI preference (ADR-0003). Outside the TUI layer.
+- Device flow auth (ADR-0004). The flow becomes a sequence of `Command.http` calls in `Update`, but the protocol decision is unchanged.
+- Render labels verbatim (ADR-0005). Display concern; the framework rendering them doesn't matter.
+- Standalone gem vs Bundler plugin (ADR-0006). Packaging concern; orthogonal.
+- Display CONTRIBUTING (ADR-0007). Same.

data/docs/adr/0009-top-level-namespace.md

@@ -0,0 +1,37 @@
+# ADR 0009: Top-level namespace is `GemContribute`, not `Gem::Contribute`
+
+**Status:** Accepted
+**Date:** 2026-04-27
+
+## Context
+
+Running `bundle gem gem-contribute` (and, by extension, `rooibos new .` on a hyphenated gem name) produces a skeleton that nests the project under `Gem::Contribute`. The first commit of this repo did exactly that: `lib/gem/contribute.rb`, `module Gem; module Contribute`.
+
+`Gem` is the namespace of Ruby's stdlib package-management library (`Gem::Specification`, `Gem::Version`, `Gem::Requirement`, `Gem::Dependency`, etc., plus the global `Gem` module method on every spec file we ship). Reopening it for our own application code mixes two unrelated namespaces.
+
+The design doc and ADRs (0001–0008) consistently describe the modules with bare names — `LockfileParser`, `Resolver`, `HostAdapter`, `GitHubAdapter`, `Auth` — never `Gem::Contribute::LockfileParser`. The prose treats them as siblings, not children of `Gem`.
+
+## Decision
+
+Top-level namespace is `GemContribute`. Files live under `lib/gem_contribute/`, with a primary `lib/gem_contribute.rb` entry point. The gem name on RubyGems stays `gem-contribute` (the binary stays `gem-contribute`); only the in-code constant changes.
+
+## Reasoning
+
+**Avoids stdlib collisions.** Inside `module Gem::Contribute`, every reference to `Gem` resolves to *our* reopened module first, not to stdlib. This is fine until it isn't — the moment we reach for `Gem::Specification` or `Gem::Version` (entirely plausible in a tool that talks to RubyGems) we get either a confusing constant lookup or a Rubocop `Lint/ConstantDefinitionInBlock` style warning. Cheaper to never start.
+
+**Matches the design doc's vocabulary.** ADRs and `docs/design.md` describe modules as if they live in their own namespace. Naming the namespace `GemContribute` makes the code read the way the docs read.
+
+**Internal `LockedGem` struct.** The design doc's prose uses "Gem" for the parsed lockfile entry. To keep that meaning without collision-prone identifiers (`GemContribute::Gem` would shadow stdlib's `::Gem` inside the module body), the value object is named `GemContribute::LockedGem` and the user-facing prose still calls it "a gem from the lockfile."
+
+## Alternatives considered
+
+- **Keep `Gem::Contribute`.** What `bundle gem` produces by default. Rejected for the reasons above. The default is a default; defaults are sometimes wrong.
+- **Top-level `Contribute` module.** Short and clean, but `Contribute` as a top-level constant is presumptuous — too many other tools could plausibly use it.
+- **`BlueRidge::GemContribute` or `Workshop::GemContribute`.** Workshop-flavored, but the gem outlives the workshop. Rejected.
+
+## Consequences
+
+- All Ruby files use `GemContribute::Whatever`. RBS signatures match.
+- `lib/` layout is `lib/gem_contribute.rb` + `lib/gem_contribute/*.rb`, not `lib/gem/contribute.rb`.
+- The gemspec's `require "gem_contribute/version"` replaces `require "gem/contribute/version"`.
+- Existing skeleton files from `rooibos new .` (`lib/gem/`, `sig/gem/`, `test/gem/`) are removed; this is a pre-stage-1 reset, not a refactor mid-stream.

data/docs/adr/README.md

@@ -0,0 +1,21 @@
+# Architecture Decision Records
+
+This directory contains short, dated records of meaningful design decisions. Each ADR captures one decision, the context it was made in, the alternatives considered, and the consequences accepted. The goal is auditable reasoning, not exhaustive documentation.
+
+Format: [Michael Nygard's template](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md), kept short.
+
+## Index
+
+- [0001 — Just-in-time auth](0001-just-in-time-auth.md)
+- [0002 — Use Bundler's lockfile parser](0002-bundler-lockfile-parser.md)
+- [0003 — Prefer `bug_tracker_uri` over `source_code_uri`](0003-issue-tracker-preference.md)
+- [0004 — Use OAuth Device Flow, not PATs](0004-device-flow-auth.md)
+- [0005 — Render labels verbatim](0005-render-labels-verbatim.md)
+- [0006 — Ship as a standalone gem, not a Bundler plugin](0006-standalone-gem-not-plugin.md)
+- [0007 — Show CONTRIBUTING; don't parse it](0007-display-contributing-verbatim.md)
+- [0008 — Use Rooibos for the TUI layer](0008-rooibos-tui-framework.md)
+- [0009 — Top-level namespace is `GemContribute`](0009-top-level-namespace.md)
+
+## When to add an ADR
+
+Add one when a decision is non-obvious *and* would be expensive to reverse. Don't add one for "we used Minitest." Do add one when "we picked X over Y for non-obvious reasons and someone six months from now will wonder why."

data/docs/claude-code-prompt.md

@@ -0,0 +1,40 @@
+# Initial prompt for Claude Code
+
+Paste the following as your first message in Claude Code (in the `gem-contribute` directory).
+
+---
+
+We're building `gem-contribute` together for a workshop at Blue Ridge Ruby on April 30 – May 1, 2026.
+
+Before doing anything, read these in order:
+
+1. `CLAUDE.md` — the working agreement
+2. `README.md` — what the project is
+3. `docs/design.md` — the architecture
+4. `docs/adr/` — every ADR; they constrain implementation choices
+5. `docs/prep-plan.md` — the staged plan I want you to execute
+
+Then check out the current state of the repo. Right now there's no Ruby code yet — just docs. The very first thing you do is generate the gem skeleton (gemspec, Gemfile, lib/, bin/, spec/) following standard Bundler conventions for a CLI gem with a native-extension dependency. Use the gem name, version, and license from the README. Don't add any runtime dependencies that aren't justified by the design doc; we'll add `rooibos` and `ratatui_ruby` in Stage 3.
+
+Then start Stage 1 from `docs/prep-plan.md`.
+
+Working rules for our collaboration:
+
+- **Stop at every stage boundary** in the prep plan and tell me what you've done. Don't barrel into the next stage. I want to demo and review.
+- **Commit at meaningful checkpoints**, not all at once at the end. Conventional commits (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`).
+- **Push back on me** if a request contradicts an ADR. Reference the ADR by number. If we change our minds, we update the ADR before writing the conflicting code.
+- **When you hit a real architecture question**, surface it instead of picking. The ADR-0008 / Rooibos call is the kind of thing that should have come back to me as a question, not a fait accompli.
+- **Don't write workshop issues as actual GitHub issues**, just as markdown files per Stage 4. I'll create them on GitHub myself when the repo is public.
+- **Don't register the OAuth App for me.** When Stage 2 needs the client ID, generate a `MAINTAINER.md` with step-by-step instructions for me to do it manually, then pause and wait for me to paste the client ID back.
+- **Don't open the demo PR for me.** When Stage 2 says "use the tool to open one real PR," stop there and have me do it. Watching me use my own tool is the test.
+
+Start by reading the docs and confirming the plan. Then go.
+
+---
+
+## Notes on using this prompt
+
+- If Claude Code asks clarifying questions before reading the docs, tell it to read first and then ask.
+- If it suggests architecture changes early, fine — but require an ADR update *before* the code change, not after.
+- The "stop at every stage boundary" rule is the most important one. Without it, agentic coding sessions tend to overshoot. Reinforce it if needed.
+- The 12–20 hour estimate in `prep-plan.md` is honest, not pessimistic. Plan accordingly.

data/docs/design.md

@@ -0,0 +1,234 @@
+# Design
+
+This document describes the architecture of `gem-contribute` — what the pieces are, how they fit together, and why. It's the document you'd read before making a non-trivial change. For the *reasoning* behind specific choices, see [`adr/`](adr/).
+
+## Goal
+
+Help a Ruby developer contribute to the open-source projects they already depend on, with the lowest possible friction between "I noticed an issue" and "I have a working branch."
+
+That's the only goal. It's worth restating because it disqualifies a lot of adjacent ideas: this is not a general issue browser, not a PR review tool, not a "discover new gems" tool, not a project management tool. The lockfile is the scope.
+
+## The two halves
+
+`gem-contribute` has a clean split between the **data layer** (parsers, resolvers, host adapters, auth) and the **TUI layer** (a Rooibos MVU app). The data layer knows nothing about the UI. The TUI layer talks to the data layer only through Commands and messages.
+
+This split is what makes the offline mode, the test suite, and the future "GitLab adapter weekend project" tractable. Don't violate it.
+
+## Data layer
+
+```
+                Gemfile.lock
+                     │
+                     ▼
+            ┌─────────────────┐
+            │  LockfileParser │     no network
+            └────────┬────────┘
+                     ▼
+              [Gem, Gem, …]
+                     │
+                     ▼
+            ┌─────────────────┐
+            │   Resolver      │     anonymous RubyGems API
+            └────────┬────────┘
+                     ▼
+       [Project(host, owner, repo), …]
+                     │
+                     ▼
+            ┌─────────────────┐
+            │   HostAdapter   │     auth checked just-in-time,
+            │   (per-host)    │     per-host
+            └─────────────────┘
+```
+
+Each stage produces values the next stage consumes. No reverse calls.
+
+### `LockfileParser`
+
+Input: a path to `Gemfile.lock`.
+Output: a list of `Gem` structs (`name`, `version`, `source` — where `source` is `:rubygems`, `:git`, `:path`, etc.).
+
+Pure parsing, no network. Wraps `Bundler::LockfileParser`. See [ADR-0002](adr/0002-bundler-lockfile-parser.md).
+
+### `Resolver`
+
+Input: a `Gem`.
+Output: a `Project` (`host`, `owner`, `repo`, `metadata`) or `nil` if unresolvable.
+
+Hits the RubyGems v1 API anonymously. Prefers `bug_tracker_uri` over `source_code_uri` — see [ADR-0003](adr/0003-issue-tracker-preference.md). Caches under `~/.cache/gem-contribute/`.
+
+The `host` is parsed from the URL: `github.com`, `gitlab.com`, `codeberg.org`, or `:unknown`. Only `github.com` has a working adapter at v0.1.
+
+### `HostAdapter` (interface) and `GitHubAdapter` (implementation)
+
+Input: a `Project` plus, for some methods, an auth token.
+Output: issues, CONTRIBUTING content, fork results.
+
+```ruby
+def issues(project, labels:)              # public, no auth needed
+def community_profile(project)            # public, no auth needed
+def file_contents(project, path)          # public, no auth needed
+def fork(project)                         # auth required
+def already_forked?(project)              # auth required
+```
+
+`GitHubAdapter` checks for a cached token before any auth-required call. If there's no token, it raises `AuthRequired` with the host name. The TUI catches this through its message machinery and triggers the device flow. See [ADR-0001](adr/0001-just-in-time-auth.md).
+
+Adding a new host (GitLab, Codeberg) means writing a new adapter that conforms to the interface. The TUI doesn't change.
+
+### `Auth`
+
+Implements the OAuth 2.0 Device Authorization Grant against `github.com`. Stores tokens at `~/.config/gem-contribute/auth.json` (mode 0600). Token cache is keyed by host so multi-host support drops in cleanly.
+
+The OAuth App is registered under the maintainer's account. Client ID is a public constant in source — there is no client secret in device flow, by design. See [ADR-0004](adr/0004-device-flow-auth.md).
+
+## TUI layer
+
+The TUI is a [Rooibos](https://www.rooibos.run/) application. Rooibos provides Model-View-Update (Elm-style) on top of `ratatui_ruby`, plus async Commands and snapshot testing. See [ADR-0008](adr/0008-rooibos-tui-framework.md) for why.
+
+If you've never used Rooibos: read its [Why Rooibos](https://www.rooibos.run/docs/v0.7/doc/getting_started/why_rooibos_md.html) and the Rails-developer guide before changing TUI code. Twenty minutes of orientation saves hours of writing-against-the-grain.
+
+### Mental model
+
+```
+   ┌────────┐     message      ┌─────────────────┐
+   │  User  │  ───────────────▶│      Update     │
+   └────────┘                  │ (model, msg) →  │
+       ▲                       │  model | [model,│
+       │                       │      command]   │
+       │ keys, mouse           └────────┬────────┘
+       │                                │
+       │                                ├── new model
+       │                                │      │
+       │                                │      ▼
+       │                                │  ┌───────┐
+       │                                │  │ View  │ ───── render ──┐
+       │                                │  └───────┘                │
+       │                                │                           │
+       │                                └── command (async)         │
+       │                                       │                    │
+       │                                       │  http, system,     │
+       │                                       │  wait, etc.        │
+       │                                       │                    │
+       │                                       ▼                    │
+       │                                  message (back to Update)  │
+       │                                                            │
+       └─── terminal ◀──────────────────────────────────────────────┘
+```
+
+State lives in one place. Updates flow in one direction. Async work happens via Commands and reports back as messages.
+
+### Fragments
+
+The app is composed as a tree of Rooibos fragments. Each fragment has its own `Init`, `Model`, `View`, and `Update`. Parents compose children using Rooibos's `Router` DSL.
+
+```
+GemContribute (parent / router)
+├── ProjectList         [project list view]
+├── IssueList           [issue list for selected project]
+├── IssueDetail         [issue body, labels, action keys]
+├── ContributingViewer  [rendered CONTRIBUTING.md]
+└── AuthOverlay         [device flow prompt — can fire over any view]
+```
+
+The `AuthOverlay` is a fragment that renders on top of whatever view is active when an `:auth_required` message fires. When auth succeeds, the overlay closes and the original action retries.
+
+### Commands
+
+All async work is a Rooibos Command. We never spawn a thread directly.
+
+| What                                    | Command                                         |
+|-----------------------------------------|--------------------------------------------------|
+| Fetch issues for a project              | `Command.http(:get, url, :got_issues)`           |
+| Run device-flow auth poll               | `Command.http(:post, url, :got_token_or_pending)`|
+| Wait between auth polls                 | `Command.wait(interval, :poll_again)`            |
+| Fork a repo via API                     | `Command.http(:post, url, :forked)`              |
+| Clone a forked repo                     | `Command.system("git clone …", :cloned)`         |
+| Create a working branch                 | `Command.system("git checkout -b …", :branched)` |
+| Open the project in `$EDITOR`           | `Command.open(path)`                             |
+
+Each command produces a message. `Update` handles the message the same way it handles a key press. There is no other concurrency model in this app.
+
+### Messages and pattern matching
+
+`Update` is a single function that pattern-matches on incoming messages. Example shape:
+
+```ruby
+Update = -> (message, model) {
+  case message
+  in :fork_pressed
+    [model.with(forking: true), Adapters::GitHub.fork_command(model.current_project)]
+  in { type: :http, envelope: :forked, status: 201, body: }
+    fork_data = JSON.parse(body, symbolize_names: true)
+    clone_cmd = GitWorker.clone_command(fork_data[:clone_url], envelope: :cloned)
+    [model.with(fork_data:), clone_cmd]
+  in { type: :http, envelope: :forked, status: 401 }
+    [model.with(pending_action: :fork_pressed), AuthFlow.start_command]
+  in { type: :system, envelope: :cloned, status: 0, stdout: }
+    [model.with(local_path: extract_path(stdout)), GitWorker.branch_command(...)]
+  # … and so on
+  end
+}
+```
+
+This is the entirety of the control flow. Async work is just messages with envelopes. Errors are messages too. The shape never changes.
+
+## What's deliberately not here
+
+- **Label normalization.** Maintainers chose those labels. Render them. ([ADR-0005](adr/0005-render-labels-verbatim.md))
+- **CONTRIBUTING parsing.** Show it. Let the user read it. ([ADR-0007](adr/0007-display-contributing-verbatim.md))
+- **PR creation from inside the TUI.** Out of scope; the user writes code in their editor and pushes from their terminal.
+- **Private gems / private repos.** Possible later. Out of scope at v0.1; the auth scope is `public_repo` only.
+- **Bundler plugin packaging.** Standalone gem at v0.1. ([ADR-0006](adr/0006-standalone-gem-not-plugin.md))
+- **A `Worker` module.** Earlier drafts had one. Fork-clone-branch is a sequence of Commands emitted from `Update`; there's no separate orchestrator class. The state machine *is* the orchestrator.
+- **Direct threading.** All async work goes through Rooibos Commands. ([ADR-0008](adr/0008-rooibos-tui-framework.md))
+
+## Configuration
+
+`~/.config/gem-contribute/config.yml`:
+
+```yaml
+clone_root: ~/code/oss
+preferred_labels:
+  - good first issue
+  - good-first-issue
+  - help wanted
+  - documentation
+hosts:
+  github.com:
+    enabled: true
+```
+
+Everything has a default. The config file is created on first run.
+
+## Caching
+
+| What                           | Where                              | TTL       |
+|--------------------------------|------------------------------------|-----------|
+| RubyGems source URLs           | `~/.cache/gem-contribute/gems/`    | 7 days    |
+| Issue lists                    | `~/.cache/gem-contribute/issues/`  | 5 minutes |
+| Community profiles             | `~/.cache/gem-contribute/repos/`   | 1 day     |
+| File contents (CONTRIBUTING)   | `~/.cache/gem-contribute/files/`   | 1 day     |
+
+`gem-contribute --refresh` invalidates all caches. Cache misses degrade gracefully — if the network is down and the cache is empty, the TUI shows what it has and reports the gap honestly.
+
+## Testing strategy
+
+ADR-0008 changes this materially from earlier drafts. Because `Update` is a pure function and Rooibos provides snapshot helpers, "test the TUI" goes from impractical to easy.
+
+- **Unit tests** for parsers, resolvers, and adapters. Adapters use VCR cassettes; cassettes are committed.
+- **`Update` tests** for every fragment. Pure function in, pure function out. Cover at minimum: every key handler, every command-result message, every error path.
+- **View tests** for color and modifier assertions on rendered output. Verify that preferred labels are highlighted, that error states render in red, etc.
+- **System tests** for full-flow scenarios. Inject keys, run the app to a quiescent state, snapshot the result. Snapshots are committed.
+- **Integration test** against a single live gem (`mailcatcher` is small and friendly) — runs only when `GEM_CONTRIBUTE_INTEGRATION=1` is set. Catches real-world breakage of the adapter.
+
+The Rooibos snapshot tooling normalizes dynamic content (timestamps, paths in `~/code/oss/...`) so snapshot diffs stay legible. Run `UPDATE_SNAPSHOTS=1 rake test` to regenerate baselines.
+
+## Roadmap (non-promises)
+
+**v0.1 (workshop):** GitHub-only, JIT auth, fork-clone-branch working, four primary fragments, Rooibos throughout, snapshot tests for the main flows.
+
+**v0.2:** Better empty states, rate-limit display in the status bar, `r` keybinding to refresh the current view, keyboard help overlay (an additional fragment).
+
+**v0.3:** GitLab adapter. The data-layer/TUI-layer split above is the bet that this is a weekend project, not a rewrite.
+
+**Maybe-never:** Codeberg, sourcehut, private repos, PR creation, label normalization, AI-anything, Bundler plugin, RubyGems plugin (a thin lazy-loading shim is the most we'd consider).