gem-contribute 0.1.0 → 0.3.0

data/docs/adr/0014-ship-bundler-and-rubygems-plugins.md

@@ -0,0 +1,75 @@
+# ADR 0014: Ship Bundler and RubyGems plugins as v1 interfaces
+
+**Status:** Accepted
+**Date:** 2026-05-03
+**Amends:** [ADR-0006](0006-standalone-gem-not-plugin.md), [ADR-0012](0012-output-free-service-objects-three-interface-architecture.md)
+
+## Context
+
+[ADR-0006](0006-standalone-gem-not-plugin.md) (2026-04-27) decided to ship as a standalone gem rather than a Bundler plugin. The primary reason was workshop scope — Bundler plugin authoring would distract attendees from the actual learning objectives (Ratatui, OAuth, GitHub's API). It explicitly left the door open: *"A future ADR can revisit this if the tool sees real adoption and the plugin UX becomes the bottleneck."*
+
+[ADR-0012](0012-output-free-service-objects-three-interface-architecture.md) (2026-05-03 morning) added a RubyGems plugin (`gem contribute`) as a third interface, alongside the standalone CLI and the (then-bubbletea) TUI. It noted that the Bundler plugin decision in ADR-0006 was unchanged.
+
+The Blue Ridge Ruby workshop concluded 2026-05-02. ADR-0006's workshop-scope concern is no longer load-bearing.
+
+Separately: the v1 release goal now includes both `bundle contribute` *and* `gem contribute` as discoverable entry points, alongside `gem-contribute` itself. This makes the tool reachable from whatever invocation surface a user is already in.
+
+## Decision
+
+Ship three entry points for v1:
+
+1. **`gem-contribute`** — standalone CLI binary. Bare invocation (no subcommand) launches the Rooibos TUI. Subcommands run as CLI verbs.
+2. **`bundle contribute`** — Bundler plugin. CLI-only. Bare invocation runs a default summary verb (TBD: `scan` vs `list all`). Subcommands run as CLI verbs.
+3. **`gem contribute`** — RubyGems plugin. CLI-only. Same shape as `bundle contribute`.
+
+All three entry points ship in **a single gem** (`gem-contribute`). One `gem install gem-contribute` registers the standalone binary, the Bundler plugin, and the RubyGems plugin.
+
+## Reasoning
+
+**The workshop scope-creep argument has expired.** ADR-0006's central rejection was "plugin authoring would distract workshop attendees." Workshop is done; the v1 audience is end users and contributors, not workshop attendees. The remaining ADR-0006 reasoning (UX nicety of `bundle X`) actually *supports* shipping plugins.
+
+**Plugin entry points are CLI-only, by design.** Bundler and RubyGems plugin ecosystems are built around CLI subcommands, not interactive TUIs. Users running `bundle contribute` expect the same kind of behavior as `bundle exec`, `bundle install`, etc. — text in, text out. The TUI is a property of the standalone binary; the plugins delegate into the same service-layer entry points the CLI uses.
+
+This has a useful architectural consequence: the plugin entry points never need to load Rooibos or `ratatui_ruby`. Plugin install stays lightweight, and plugin invocations don't pay the TUI startup cost.
+
+**One gem rather than three.** ADR-0012 sketched a future `rubygems-contribute` gem. Three gems would follow Ruby ecosystem convention (`bundler-X`, `rubygems-X`) but tripples release ceremony, version coordination, and CHANGELOG maintenance. For a project this size, that cost is not earned. One gem with three entry points: one `gem install`, one CHANGELOG, one version, all three interfaces work.
+
+**ADR-0012's three-interface framing carries over unchanged.** The service layer (output-free, returns `Result`) is what enables three interfaces to share code. ADR-0014 doesn't add a fourth interface; it confirms the third (Bundler plugin) and locks the packaging to a single gem.
+
+## Alternatives considered
+
+- **Stay standalone-only (ADR-0006 unmodified).** Rejected: the original justification (workshop scope) no longer applies, and one of v1's product goals is to make the tool reachable from `bundle X` and `gem X` invocations.
+- **Three separate gems.** Rejected: triples release ceremony for marginal architectural cleanliness. The plugin shims would be tiny — a Bundler `Plugin::API` registration and a `Gem::Command` subclass — not worth their own gemspec, version, and changelog.
+- **Ship `bundle contribute` only, defer `gem contribute` to v1.x.** Rejected as worse-of-both-worlds: same release work, half the surface area covered. They're symmetric pieces of work.
+- **TUI in plugins too.** Rejected: not idiomatic for the Bundler/RubyGems plugin ecosystems, doubles the per-invocation startup cost, and the standalone binary already serves the "I want the TUI" use case.
+
+## Consequences
+
+**On the gemspec:**
+- Add `plugins.rb` (Bundler plugin entry point) per Bundler plugin convention.
+- Add `rubygems_plugin.rb` (RubyGems plugin entry point) per RubyGems plugin convention.
+- The two entry points register their respective subcommand classes (or delegate to a shared dispatch table).
+
+**On `lib/gem_contribute/cli.rb`:**
+- The dispatch table becomes the single source of truth for verb registration.
+- Bare-arg behavior diverges per entry point: `gem-contribute` launches TUI; `bundle contribute` and `gem contribute` run a default CLI verb.
+- Consider `dry-cli` to formalize multi-entry-point command registration (deferred decision; see OPEN_QUESTIONS Q6 sub-question).
+
+**On the Bundler plugin entry point:** must not require Rooibos or `ratatui_ruby` at load time. TUI loading is gated to the standalone-binary entry point only.
+
+**On `ADR-0006`:** status updated to note ADR-0014 amends it. The standalone-gem decision stands; the no-Bundler-plugin decision is reversed.
+
+**On `ADR-0012`:** status updated to note ADR-0014 amends it. The three-interface architecture is preserved; the planned separate `rubygems-contribute` gem is replaced by a single `gem-contribute` gem with three entry points.
+
+**On `docs/design-interface-layer.md`:** "gem plugin pipeline" section needs updating — the plugin shim is internal to the `gem-contribute` gem, not a separate `rubygems-contribute` gem. Same change for the Bundler plugin section (which doesn't yet exist; needs adding).
+
+**On testing:** add at least one smoke test per plugin entry point that proves the plugin registers and dispatches a verb without booting the TUI. Implementation tests live in the existing CLI verb specs (verbs aren't aware of which entry point invoked them).
+
+**On release:** the `bundle plugin install gem-contribute` and `gem install gem-contribute` paths both need verification before v1 ships. Add to Phase 6 acceptance.
+
+## What this *doesn't* change
+
+- ADR-0001 through ADR-0005, ADR-0007 (data layer, display rules). Plugin entry points reuse the same service layer.
+- ADR-0009 (top-level namespace). Plugins live under `GemContribute::` like everything else.
+- ADR-0011 (HostAdapter owns host verbs). Service layer; orthogonal.
+- ADR-0013 (Rooibos as TUI framework). The plugins are CLI-only; framework choice doesn't reach them.

data/docs/adr/README.md

@@ -11,10 +11,15 @@ Format: [Michael Nygard's template](https://github.com/joelparkerhenderson/archi
 - [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)
+- [0006 — Ship as a standalone gem, not a Bundler plugin](0006-standalone-gem-not-plugin.md) — Bundler-plugin decision reversed by 0014; standalone-gem decision stands
 - [0007 — Show CONTRIBUTING; don't parse it](0007-display-contributing-verbatim.md)
-- [0008 — Use Rooibos for the TUI layer](0008-rooibos-tui-framework.md)
+- [0008 — Use Rooibos for the TUI layer](0008-rooibos-tui-framework.md) — superseded by 0010, substance restored by 0013
 - [0009 — Top-level namespace is `GemContribute`](0009-top-level-namespace.md)
+- [0010 — Use Charm-Ruby (bubbletea + lipgloss) for the TUI layer](0010-charm-ruby-tui-framework.md) — superseded by 0013
+- [0011 — HostAdapter owns host verbs; Operations compose them; CLI verbs compose Operations](0011-host-adapter-owns-host-verbs.md)
+- [0012 — Output-free service objects, dry-monads Result contract, three-interface architecture](0012-output-free-service-objects-three-interface-architecture.md) — packaging amended by 0014; service-layer contract stands
+- [0013 — Revert TUI framework to Rooibos](0013-revert-to-rooibos.md) — supersedes 0010, restores 0008's substance
+- [0014 — Ship Bundler and RubyGems plugins as v1 interfaces](0014-ship-bundler-and-rubygems-plugins.md) — amends 0006 and 0012
 
 ## When to add an ADR
 

data/docs/design-interface-layer.md

@@ -0,0 +1,295 @@
+# Interface Layer Design
+
+This document describes the multi-interface architecture introduced by [ADR-0012](adr/0012-output-free-service-objects-three-interface-architecture.md). It is the reference for all work that touches the boundary between service objects and the three output vectors: CLI, TUI, and gem plugin. Read it before changing anything in `lib/gem_contribute/cli/` or `lib/gem_contribute/operations/`.
+
+For the broader system architecture — parsers, resolvers, the host adapter interface, caching — see [`design.md`](design.md).
+
+## The problem with the current boundary
+
+`Operations::Fork` and `Operations::Clone` accept `stdout:` and print progress during `call`:
+
+```ruby
+def call(adapter:, project:)
+  @stdout.puts "Forking #{project.owner}/#{project.repo}..."
+  fork = adapter.fork(project)
+  @stdout.puts fork.reused ? "  Reusing existing fork." : "  Forked → ..."
+  Result.new(...)
+end
+```
+
+This works for a single CLI, but breaks across three interfaces:
+
+- The **TUI** has no output stream. Progress is model state rendered by `View`, not a string printed to stdout. There is no clean way to route `@stdout.puts` into a Rooibos model update.
+- The **gem plugin** needs to own its own output formatting and cannot share stdout injection with the CLI.
+- **Tests** must assert on stdout side effects instead of return values, coupling test setup to I/O concerns.
+
+The same problem appears in `Workflow#build_adapter`, which returns `nil` and prints to stderr on failure — two concerns collapsed into one method.
+
+## Target architecture
+
+Three interface layers share one service layer. The service layer produces no output. Each interface layer translates `Result` values into the output appropriate for its medium.
+
+```
+                          Service Layer
+    ┌────────────────────────────────────────────────────┐
+    │  Operations::Fork    Operations::Clone             │
+    │  Operations::FixPipeline    Resolver               │
+    │  HostAdapter         Auth          Git             │
+    │                                                    │
+    │  Returns Success(Result) | Failure(reason)         │
+    │  No stdout. No stderr. No exceptions across layers.│
+    └───────────────┬───────────────────┬────────────────┘
+                    │                   │                │
+                    ▼                   ▼                ▼
+        ┌───────────────┐   ┌───────────────┐   ┌──────────────┐
+        │  CLI Pipeline │   │  TUI Pipeline │   │  gem plugin  │
+        │               │   │               │   │  Pipeline    │
+        │  Output::     │   │  Commands +   │   │              │
+        │  Standard     │   │  Update       │   │  reuses CLI  │
+        │  tty-spinner  │   │               │   │  pipeline    │
+        │  tty-prompt   │   │               │   │              │
+        └───────────────┘   └───────────────┘   └──────────────┘
+```
+
+The three interface pipelines are entirely separate. A change to CLI output formatting has zero effect on the TUI. A new service object needs no knowledge of any interface.
+
+## Service layer
+
+### Result types
+
+Every operation returns a `dry-monads` `Result`:
+
+- `Success(value)` on the happy path — `value` is a `Data` struct.
+- `Failure(reason)` for expected failure conditions — `reason` is a symbol or tagged tuple.
+
+```ruby
+Success(Operations::Fork::Result.new(clone_url:, fork_url:, upstream_url:, viewer:, reused:))
+
+Failure(:unauthenticated)
+Failure(:adapter_error, "rate limit exceeded")
+```
+
+Typed exceptions (`AuthRequired`, `AdapterError`) are not used as cross-layer signals. They may be raised and rescued within a single operation but do not propagate to callers.
+
+### No I/O
+
+Operations accept no `stdout:` or `stderr:` parameter. The `# rubocop:disable Metrics/ParameterLists` suppressions in the current `CLI::Fork` and `CLI::Fix` initializers are a symptom of this pattern — the extra `stdout:` and `stderr:` parameters inflate every constructor. `dry-initializer` replaces the verbose initializer pattern and the suppressions go away:
+
+```ruby
+class Operations::Fork
+  extend Dry::Initializer
+  # No stdout:. No stderr:. Pure computation.
+end
+```
+
+### Multi-step pipelines
+
+The `fix` flow (fork → clone → branch → announce) is a `dry-operation` pipeline. Each step receives a shared context, enriches it, and returns `Success(enriched)` or `Failure(reason)`. Failure at any step short-circuits the chain — no early returns, no nil checks.
+
+```ruby
+class Operations::FixPipeline
+  include Dry::Operation
+
+  def call(adapter:, project:, issue:, viewer:)
+    fork_result  = step Operations::Fork.new.call(adapter:, project:)
+    clone_result = step Operations::Clone.new.call(adapter:, project:, fork_result:)
+    branch_name  = step Operations::Branch.new.call(path: clone_result.path, issue:)
+    step Operations::Announce.new.call(adapter:, project:, issue:, viewer:, was_resuming: clone_result.reused)
+    Success({ fork: fork_result, clone: clone_result, branch: branch_name })
+  end
+end
+```
+
+Both the CLI and TUI call `FixPipeline` rather than wiring the steps themselves.
+
+### `Workflow#build_adapter`
+
+Currently returns `nil` and prints to stderr. Under the new contract:
+
+```ruby
+def build_adapter
+  token = @store.token_for("github.com")
+  return Failure(:unauthenticated) if token.nil?
+
+  Success(@adapter_factory.call(token: token))
+end
+```
+
+Callers pattern-match on the result; no output side effect in the mixin.
+
+## CLI pipeline
+
+### `Output::Standard`
+
+All CLI verbs use `Output::Standard` instead of raw `@stdout`/`@stderr`. It wraps both streams and exposes a semantic interface:
+
+```ruby
+module GemContribute
+  module Output
+    class Standard
+      def initialize(out: $stdout, err: $stderr)
+        @out = out
+        @err = err
+      end
+
+      def info(message)     = @out.puts(message)
+      def warn(message)     = @err.puts("warning: #{message}")
+      def error(message)    = @err.puts(message)
+      def progress(message) # tty-spinner in interactive terminals;
+                            # falls back to info when stdout is not a TTY
+    end
+
+    class Null
+      def info(_) = nil
+      def warn(_) = nil
+      def error(_) = nil
+      def progress(_) = nil
+    end
+  end
+end
+```
+
+`#progress` is the one method that behaves differently from a plain `puts`. Long operations (fork, clone) show a spinner in interactive terminals. `tty-spinner` detects non-TTY environments automatically and falls back to a plain line — no caller checks `$stdout.tty?`.
+
+### Interactive prompts
+
+`Init` is the one command that reads input. Its current `stdout.print` + injected `@gets` lambda is replaced by `tty-prompt`:
+
+```ruby
+prompt = TTY::Prompt.new(input: @input, output: @output)
+chosen  = prompt.ask("Where should I clone repos?", default: DEFAULT_SUGGESTION)
+proceed = prompt.yes?("Authenticate with GitHub now?")
+```
+
+`TTY::Prompt.new(input:, output:)` provides the same test injection story the current `gets:` lambda provides, with proper default-value display, Y/n handling, and non-TTY fallback built in.
+
+### How CLI verbs change
+
+CLI verbs print around service calls. The operation returns a `Result`; the verb interprets it:
+
+```ruby
+def execute(adapter, project, flags)
+  @output.progress("Forking #{project.owner}/#{project.repo}...")
+
+  case @fork_op.call(adapter: adapter, project: project)
+  in Success(fork_result)
+    @output.info(fork_result.reused ? "  Reusing existing fork." : "  Forked.")
+    continue_with(fork_result, flags)
+  in Failure(:unauthenticated)
+    @output.error("Not authenticated. Run `gem-contribute auth login` first.")
+    1
+  in Failure(:adapter_error, message)
+    @output.error(message)
+    1
+  end
+end
+```
+
+The `with_workflow_rescues` wrapper in `Workflow` is retired — pattern matching on `Result` replaces it.
+
+## TUI pipeline
+
+The TUI never uses an `Output` object. A Rooibos Command wraps the service call, runs it off-thread, and returns a message to `Update`:
+
+```ruby
+def fix_command(adapter:, project:, issue:, viewer:)
+  -> {
+    result = Operations::FixPipeline.new.call(
+      adapter: adapter, project: project, issue: issue, viewer: viewer
+    )
+    { type: :fix_completed, result: result }
+  }
+end
+```
+
+`Update` pattern-matches on the message:
+
+```ruby
+def update(msg, model)
+  case msg
+  in { type: :fix_completed, result: Success({ fork:, clone:, branch: }) }
+    model.with(local_path: clone.path, branch_name: branch, status: :done)
+  in { type: :fix_completed, result: Failure(:unauthenticated) }
+    [model.with(pending_action: :fix), AuthOverlay.start_command]
+  in { type: :fix_completed, result: Failure(:adapter_error, message) }
+    model.with(error: message)
+  end
+end
+```
+
+The service object returns a `Result`; the Command wraps it in a typed message; `Update` renders it as model state. No output object, no stdout, no cross-layer exceptions.
+
+## Plugin pipelines
+
+Per [ADR-0014](adr/0014-ship-bundler-and-rubygems-plugins.md), v1 ships three entry points in a single `gem-contribute` gem: the standalone `gem-contribute` binary, a Bundler plugin (`bundle contribute`), and a RubyGems plugin (`gem contribute`). Both plugins are CLI-only; the TUI is a property of the standalone binary.
+
+- **Bundler plugin** — `plugins.rb` at the gem root, per Bundler convention. Registers a `bundle contribute` command and delegates to the same dispatch table the standalone CLI uses.
+- **RubyGems plugin** — `rubygems_plugin.rb`, per RubyGems convention. Registers a `Gem::Command` subclass for `gem contribute` and delegates the same way.
+
+Both plugin entry points MUST NOT require Rooibos or `ratatui_ruby`. The TUI gets loaded only by the standalone-binary entry point, which keeps plugin install lightweight and plugin invocations fast.
+
+When `dry-cli` is added (alongside the plugin shims), it replaces the hand-rolled `COMMANDS` dispatch in `cli.rb` with declarative command registration. All three entry points register the same underlying commands against their respective hosts — the commands themselves do not change.
+
+The plugin work is deferred until the service layer and CLI pipeline are clean (this document's Phases 1 and 2) and the TUI lands ([ROADMAP](ROADMAP.md) Phase 3).
+
+## New dependencies
+
+| Gem | Role | Phase |
+|---|---|---|
+| `dry-monads` | `Success`/`Failure` Result types | 1 |
+| `dry-operation` | Multi-step pipeline composition for `fix` | 1 |
+| `dry-initializer` | Clean option declarations; removes rubocop suppressions | 1 |
+| `tty-spinner` | Spinner in `Output::Standard#progress` | 2 |
+| `tty-prompt` | Interactive prompts in `Init` | 2 |
+| `dry-cli` | Command registration across all three entry points | 4/5 (with plugin shims) |
+
+Pin all new dependencies to a minor version (`~> x.y`). Bump deliberately; record significant bumps in an ADR note.
+
+## Migration sequence
+
+### Phase 1 — Service layer
+
+1. Add `dry-monads`, `dry-operation`, `dry-initializer` to the gemspec.
+2. Remove `stdout:` from `Operations::Fork` and `Operations::Clone`. Add `reused:` to `Clone::Result`.
+3. Convert both operations to return `Success(Result)` | `Failure(reason)`.
+4. Convert `Workflow#build_adapter` to return `Success(adapter)` | `Failure(:unauthenticated)`.
+5. Build `Operations::FixPipeline` using `dry-operation`.
+6. Replace long initializers in `CLI::Fork` and `CLI::Fix` with `dry-initializer` option declarations.
+7. Update all callers to pattern-match on `Result`. Retire `with_workflow_rescues`.
+
+### Phase 2 — CLI pipeline
+
+1. Introduce `Output::Standard` and `Output::Null`.
+2. Replace raw `@stdout`/`@stderr` in all CLI verbs with `@output`.
+3. Add `tty-spinner` for `Output::Standard#progress`.
+4. Replace `Init`'s `stdout.print` + `@gets` with `tty-prompt`.
+
+### Phases 4 and 5 — Bundler and RubyGems plugins
+
+Per ADR-0014 and the [ROADMAP](ROADMAP.md), the gem-plugin work is split into two ROADMAP phases (one per plugin) and lives within the `gem-contribute` gem rather than as separate `bundler-contribute` / `rubygems-contribute` gems.
+
+1. Add `dry-cli`. Replace the `COMMANDS` dispatch in `cli.rb` with `dry-cli` command registration so multiple entry points can hang off it.
+2. Add `plugins.rb` at the gem root (Bundler plugin entry point). Register a `bundle contribute` command that dispatches into the same registration table.
+3. Add `rubygems_plugin.rb` (RubyGems plugin entry point). Register a `Gem::Command` subclass that does the same.
+4. Smoke-test both plugin install paths in CI.
+
+Each ADR-0012 phase is independently releasable. Phase 1 has no user-visible behaviour change. Phase 2 changes the look of progress output and prompts. The plugin phases add new entry points.
+
+## Testing strategy
+
+**Service layer:** pure function in, `Result` out. Every operation gets unit tests that assert on `Success`/`Failure` values directly. No stdout assertion. No mock needed for output. VCR cassettes for adapter-touching operations; committed to the repo.
+
+**CLI pipeline:** inject `Output::Null` for tests that don't assert on output; inject a capturing double for tests that do. Assert on captured calls to `#info`/`#error`/`#progress`, not on raw stdout strings.
+
+**TUI pipeline:** the Command closure is a plain lambda — call it directly and assert on the returned message hash. `Update` is a pure function — call it with a message and assert on the returned model. Rooibos's snapshot test helpers (per ADR-0008/0013) supplement this for full-flow scenarios.
+
+**gem plugin:** thin entry-point tests only. The CLI pipeline tests cover the behaviour.
+
+## What doesn't change
+
+- The `HostAdapter` interface and `GitHubAdapter` implementation.
+- `Resolver`, `LockfileParser`, `TokenStore`, `Cache` — already output-free.
+- The Auth flow shape. `CLI::Auth` keeps its existing structure; `Workflow#build_adapter`'s change is internal wiring.
+- Caching strategy and TTLs.
+- The Rooibos framework choice (ADR-0013, which superseded ADR-0010).
+- ADR-0005 (render labels verbatim), ADR-0007 (show CONTRIBUTING), ADR-0009 (namespace). None of these touch the interface boundary.

data/docs/design.md

@@ -61,19 +61,42 @@ The `host` is parsed from the URL: `github.com`, `gitlab.com`, `codeberg.org`, o
 ### `HostAdapter` (interface) and `GitHubAdapter` (implementation)
 
 Input: a `Project` plus, for some methods, an auth token.
-Output: issues, CONTRIBUTING content, fork results.
+Output: issues, CONTRIBUTING content, fork results, host-specific URLs.
 
 ```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
+# Reads — no auth
+def issues(project, labels:)
+def issue(project, number)
+def issue_comments(project, number)
+def community_profile(project)
+def file_contents(project, path)
+def search_issues(query)
+
+# Writes — auth required
+def fork(project)                         # idempotent, blocks until ready; → ForkResult
+def comment(project, issue:, body:)
+def pull_request_url(upstream, head_owner:, head_branch:, title:, body:)
+
+# Identity / URL helpers
+def viewer_login                          # auth required
+def clone_url(owner, repo)                # pure templating, no network
+def repo_url(owner, repo)                 # pure templating, no network
 ```
 
 `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.
+`fork` is idempotent and blocking: if the viewer already owns the fork it returns `reused: true` without a POST; otherwise it POSTs and polls the host until the new fork is reachable. Higher layers don't see the polling. PR creation is not an API call — the adapter's `pull_request_url` returns a host-specific compare/MR URL that gets opened in the browser, so the user reviews the PR text before submitting. See [ADR-0011](adr/0011-host-adapter-owns-host-verbs.md).
+
+Adding a new host (GitLab, Codeberg) means writing a new adapter that conforms to the interface — including its own `clone_url` / `repo_url` / `pull_request_url` templates and its own readiness model for `fork`. Operations and CLI don't change.
+
+### `Operations::Fork` and `Operations::Clone`
+
+Two thin primitives sitting between the adapter and the CLI verbs. They're the bootstrap step `fix` and `fork` share:
+
+- `Operations::Fork` calls `adapter.fork(project)` and packages the result with the upstream URL for summary output.
+- `Operations::Clone` clones the fork into `<root>/<owner>/<repo>` (reusing an existing clone if one is there) and adds an `upstream` remote pointing at `adapter.clone_url(upstream)`.
+
+The "reuse if `.git` exists" rule and the upstream-remote convention are gem-contribute policy on top of git, not git primitives — that's why they live here rather than in the `Git` wrapper. See [ADR-0011](adr/0011-host-adapter-owns-host-verbs.md).
 
 ### `Auth`
 
@@ -225,7 +248,7 @@ The Rooibos snapshot tooling normalizes dynamic content (timestamps, paths in `~
 
 ## 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.1 (workshop):** GitHub-only, JIT auth, `fix` 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).
 

data/docs/ideas.md

@@ -0,0 +1 @@
+ - Make sure it respects PR templates

data/docs/index.md

@@ -38,7 +38,7 @@ gem-contribute submit                 # push, then open the PR compare page in y
 
 - **v0.1**: a CLI with `scan`, `issues`, `auth`, `fix`, `submit`, and `config`. GitHub-only.
 - **Planned**: a Rooibos TUI that does all of the above as a single keyboard-driven session ([issue #2](https://github.com/cdhagmann/gem-contribute/issues/2)).
-- **Workshop project**: built for [Blue Ridge Ruby 2026](https://blueridgeruby.com).
+- **Workshop project**: built for [Blue Ridge Ruby 2026](https://blueridgeruby.com). [Lightning talk slides →](talk/)
 
 ## Commands
 
@@ -50,7 +50,7 @@ gem-contribute submit                 # push, then open the PR compare page in y
 | `gem-contribute auth login` | Authenticate with GitHub via OAuth device flow (no token paste, no client secret). |
 | `gem-contribute auth status` | Show whether the cached token is still valid. |
 | `gem-contribute auth logout` | Drop the cached token. |
-| `gem-contribute fix <gem>/<n>` | Fork the gem's repo, clone the fork to `<clone_root>/<owner>/<repo>`, branch from default. Alias: `fork-clone-branch`. |
+| `gem-contribute fix <gem>/<n>` | Fork the gem's repo, clone the fork to `<clone_root>/<owner>/<repo>`, branch from default. |
 | `gem-contribute submit` | From inside a clone, push the current branch and open a pre-filled PR compare page in your browser. |
 | `gem-contribute config set <k> <v>` | Persist user preferences. |
 | `gem-contribute config list` | Show current configuration. |

data/docs/prep-plan.md

@@ -36,14 +36,14 @@ Minimum viable workshop = Stages 1, 2, and 4 done. Stage 3 (the TUI) can become
 **Deliberately not in this stage:**
 - No auth code. Anonymous GitHub API only.
 - No TUI. CLI output via plain `puts`.
-- No fork-clone-branch. That's Stage 2.
+- No `fix` action. That's Stage 2.
 - No Rooibos dependency yet.
 
 **Stop here and check in with Chris.** Demo the script against `gem-contribute`'s own `Gemfile.lock`. The output should make Chris want to keep going.
 
 ### Stage 2 — Auth and the action
 
-**Goal:** Add device-flow auth and the fork-clone-branch action. Still no TUI; everything is CLI flags. Proves the auth and action layers work.
+**Goal:** Add device-flow auth and the `fix` action. Still no TUI; everything is CLI flags. Proves the auth and action layers work.
 
 **Acceptance:**
 
@@ -53,7 +53,7 @@ Minimum viable workshop = Stages 1, 2, and 4 done. Stage 3 (the TUI) can become
 - [ ] Polling respects `slow_down` errors and the 15-minute device-code expiry
 - [ ] `gem-contribute auth login` and `gem-contribute auth status` CLI commands work
 - [ ] `GitHubAdapter` gains `fork`, `already_forked?` methods that raise `AuthRequired` if no token
-- [ ] A `fork-clone-branch` CLI subcommand takes a `gem/issue_number` argument, performs the full sequence, prints the local path
+- [ ] A `fix` CLI subcommand takes a `gem/issue_number` argument, performs the full sequence, prints the local path
 - [ ] Unit tests for the auth state machine (the protocol is deterministic — test it)
 - [ ] Integration test gated on `GEM_CONTRIBUTE_INTEGRATION=1` against a small friendly gem
 - [ ] **Use the tool to open one real PR** — even a typo fix in a README. The proof that the architecture works.
@@ -88,7 +88,7 @@ Minimum viable workshop = Stages 1, 2, and 4 done. Stage 3 (the TUI) can become
 - No label normalization (ADR-0005)
 - No CONTRIBUTING parsing (ADR-0007)
 - No private-repo support
-- No `Worker` orchestrator class — fork-clone-branch is a state machine in `Update`
+- No `Worker` orchestrator class — `fix` is a state machine in `Update`
 
 **Stop and check in with Chris.** This is the demo for the workshop opening.
 
@@ -118,7 +118,7 @@ Minimum viable workshop = Stages 1, 2, and 4 done. Stage 3 (the TUI) can become
 - "Authenticated as @user" indicator
 - Sort gems by issue count
 - Skip path/git source gems with a clear status line
-- Confirmation dialog before fork-clone-branch
+- Confirmation dialog before `fix`
 - `o` to open the gem's homepage in browser
 - "Last updated" warning for stale-looking gems
 
@@ -147,7 +147,7 @@ You're ready when, on a fresh laptop:
 
 1. `git clone … && cd gem-contribute && bundle install` succeeds
 2. `bin/gem-contribute` launches the TUI against a real `Gemfile.lock`
-3. `f` on an issue completes the fork-clone-branch flow with the device-flow prompt firing
+3. `f` on an issue completes the `fix` flow with the device-flow prompt firing
 4. The workshop issues are visible on the public GitHub repo with the `workshop` label
 5. `docs/workshop.md` reads cleanly to someone who hasn't seen the project
 

data/docs/talk/README.md

@@ -0,0 +1,45 @@
+# Talk source
+
+Lightning talk for Blue Ridge Ruby 2026: *Building what you cannot find*.
+
+`lightning.md` is a [Marp](https://marp.app/) presentation. The same file
+is the source of truth for HTML, PDF, and the slides shown live.
+
+## Render the slides
+
+The easiest path is the Marp VS Code extension — open `lightning.md` and
+preview it in the side panel. For a finished export:
+
+```sh
+# one-time
+npm install -g @marp-team/marp-cli
+
+# preview live in browser
+marp --server talk/
+
+# publish to GitHub Pages (committed; appears at /talk/ on the docs site)
+marp talk/lightning.md --html -o docs/talk/index.html
+
+# export to PDF (recommended for the talk itself — survives wifi)
+marp talk/lightning.md --pdf -o talk/lightning.pdf
+```
+
+The HTML version under `docs/talk/index.html` is served via the docs
+site at <https://cdhagmann.com/gem-contribute/talk/>. Re-run the `--html`
+command and commit the changed file whenever the slides change.
+
+## Speaker notes
+
+Embedded as `<!-- ... -->` HTML comments inside `lightning.md`. They
+don't render in the slide output but show up in Marp's presenter view.
+
+## Demo recording
+
+Always record the live demo before the talk and have the video queued
+on the second monitor. Wifi at conferences is unreliable. If `submit`
+hangs, you swap to the recording without losing the audience.
+
+## Timing
+
+Target 5 minutes. Practice with a phone timer at least four times
+standing up. Cut on every pass.