gem-contribute 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f6941e81cacd8ab2bb7abb6824bb54d5b04ec05789d24c792b48eb4c5125e02
-  data.tar.gz: 9a548392f2d027dbc99719d74de627940086e3858fd5c5152fa8d4ecffddb7b8
+  metadata.gz: fb726fe2025ba0cc501be01d13b4138ff4b21a9c755ad81c9b0181ef35f41c88
+  data.tar.gz: 33e6e83e38b27f2b4e2079fc79cfa76c2bfb178a2ba37424a05dfc8ad91398c0
 SHA512:
-  metadata.gz: 1a4c00ea48ba2ef0245f3564d97b2bb0e6d3eb7098a79ef598a58dda95c6130630648e04351e8a5ef7f767456d938a836c647aa02c18d7b22663816a6b9d7d2e
-  data.tar.gz: 1d60a359d87cc17ba4e2c8bad1acab5f039334df63afd34055165d1a61b569e3c9c7fd57f5159d33ed0031e7634cabb93fd1b82e52f36cd4a5d0e30bfd2ef2ca
+  metadata.gz: fa04494e7ac4294f90d14ecb01d3f111d7e890dd5dc9ec1c5b77bc83aa215e8c0cac467f6bd9fa38ffa73c4665aece92520269473cf0f95555f48096a5a2b372
+  data.tar.gz: 4e9bfd2d676ac59d5d8c8c8db0e7928641c8e4f031a85fd435f1e52ec3b1b770aa41a705f456ad488a23019520093787d58e8326bbbf42e51f24a30e185a0cfc

data/.gem_release.yml

@@ -0,0 +1 @@
+file: lib/gem_contribute/version.rb

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+## Summary
+
+<!-- One or two sentences. What changes, and why. The "why" is the part that's hard to recover later. -->
+
+## Linked issue / ADR
+
+<!--
+Issue # this closes (or "none — drive-by fix").
+For non-trivial changes: which ADR(s) does this touch? If you skipped that step, write "no ADR" plus a one-line reason.
+-->
+
+## Working agreement
+
+- [ ] Single concern (multi-concern PRs get bounced — see [CLAUDE.md](../CLAUDE.md))
+- [ ] `bin/rubocop` and `bin/rspec` pass locally
+- [ ] New behavior has a test; bug fix has a regression test
+- [ ] Async work goes through Rooibos Commands (no direct threads / `Async` / synchronous shellouts)
+
+## Test plan
+
+<!--
+How was this verified? Spec output, manual smoke, screenshots — whatever applies.
+"`bin/rspec` passes" is the floor, not a test plan.
+-->
+
+## Notes for reviewer
+
+<!-- Tradeoffs, open questions, follow-ups — anything not obvious from the diff. Delete the section if there's nothing to add. -->

data/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: Specs and Rubocop
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+          bundler-cache: true
+
+      - name: Run specs
+        run: bin/rspec
+
+      - name: Run rubocop
+        run: bin/rubocop

data/.github/workflows/pr-template-check.yml

@@ -0,0 +1,100 @@
+name: PR template check
+
+# Verifies that PR descriptions include all required sections from
+# .github/PULL_REQUEST_TEMPLATE.md. Posts (or updates) a single comment
+# listing what's missing, and fails the check until the body is fixed.
+#
+# Security note: pull_request_target gives us write access to comment
+# back on the PR. We never check out PR HEAD; the body is read via the
+# event payload (data, not code).
+
+on:
+  pull_request_target:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  template-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify required sections
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          set -euo pipefail
+
+          MARKER="<!-- pr-template-check -->"
+
+          # Required headings — must appear verbatim somewhere in the body.
+          required=(
+            "## Summary"
+            "## Linked issue / ADR"
+            "## Working agreement"
+            "## Test plan"
+          )
+          # "## Notes for reviewer" is intentionally optional — the template
+          # tells contributors to delete it when there's nothing to add.
+
+          missing=()
+          for heading in "${required[@]}"; do
+            if ! grep -Fq "$heading" <<< "${PR_BODY:-}"; then
+              missing+=("$heading")
+            fi
+          done
+
+          # Strip HTML comments and template placeholder text, then check
+          # the body has *some* substance. Catches PRs filed with the raw
+          # unmodified template.
+          stripped=$(printf '%s' "${PR_BODY:-}" | perl -0777 -pe 's/<!--.*?-->//gs')
+          # Drop heading lines and checklist scaffolding; what's left should
+          # be the contributor's own prose.
+          prose=$(printf '%s' "$stripped" | grep -Ev '^\s*(##|- \[[ x]\]|$)' || true)
+          prose_chars=$(printf '%s' "$prose" | tr -d '[:space:]' | wc -c | tr -d ' ')
+
+          # Find any prior bot comment so we can edit instead of stacking.
+          prior_id=$(gh api "repos/$REPO/issues/$PR_NUMBER/comments" \
+            --jq ".[] | select(.user.login == \"github-actions[bot]\" and (.body | contains(\"$MARKER\"))) | .id" \
+            | head -n1)
+
+          if [ ${#missing[@]} -eq 0 ] && [ "$prose_chars" -ge 40 ]; then
+            echo "PR body looks good."
+            if [ -n "$prior_id" ]; then
+              gh api -X PATCH "repos/$REPO/issues/comments/$prior_id" \
+                -f body="$MARKER
+✅ PR template check passed. Thanks for filling out the template."
+            fi
+            exit 0
+          fi
+
+          {
+            echo "$MARKER"
+            echo "👋 This PR is missing pieces from the [PR template](https://github.com/$REPO/blob/main/.github/PULL_REQUEST_TEMPLATE.md):"
+            echo ""
+            if [ ${#missing[@]} -gt 0 ]; then
+              echo "**Missing sections:**"
+              for m in "${missing[@]}"; do
+                echo "- \`$m\`"
+              done
+              echo ""
+            fi
+            if [ "$prose_chars" -lt 40 ]; then
+              echo "**Body looks unfilled** — the template comments are still there but no actual content has been written. Please fill in at least the Summary and Test plan."
+              echo ""
+            fi
+            echo "Edit the PR description (no new commit needed) and the check will re-run automatically. See [CLAUDE.md](https://github.com/$REPO/blob/main/CLAUDE.md) for why these sections matter."
+          } > /tmp/comment.md
+
+          if [ -n "$prior_id" ]; then
+            gh api -X PATCH "repos/$REPO/issues/comments/$prior_id" \
+              -F body=@/tmp/comment.md
+          else
+            gh pr comment "$PR_NUMBER" --repo "$REPO" --body-file /tmp/comment.md
+          fi
+
+          echo "::error::PR template is incomplete — see the bot comment on the PR."
+          exit 1

data/CHANGELOG.md

@@ -4,6 +4,47 @@ All notable changes to this project will be documented here. The format is based
 
 ## [Unreleased]
 
+### Added
+
+- `gem-contribute fork <gem>` — the look-around-first counterpart to `fix`: fork the gem's repo, clone it, leave you on the default branch with no issue-tied work yet. Same `-e` / `-a` flags. Use this when you want to read the code before deciding whether to commit to a specific issue (closes [#12](https://github.com/cdhagmann/gem-contribute/issues/12)).
+- `gem-contribute fix -e` opens your editor in the clone directory after fork/clone/branch. Uses the new `editor` config key, falling back to `$EDITOR` (closes [#14](https://github.com/cdhagmann/gem-contribute/issues/14)).
+- `gem-contribute fix -a` launches your configured AI coding tool (new `ai_tool` config key) with the clone directory as cwd. Combine with `-e` to open both — editor first, AI tool second (closes [#14](https://github.com/cdhagmann/gem-contribute/issues/14)).
+- `gem-contribute fix` posts a "👋 I've started working on this" comment to the issue by default so other contributors don't double up on the same work. Opt out per-invocation with `--no-comment`, globally with `comment_on_fix: false` in config, or per-repo via `comment_on_fix_overrides` (YAML-only). Posting is soft-fail — the fork/clone/branch part still succeeds even if the comment can't be posted (closes [#18](https://github.com/cdhagmann/gem-contribute/issues/18)).
+- `scan` appends `· N claimed` to project lines whose open issues have already been claimed via the working-on-this marker, so you can spot already-in-progress work at a glance (closes [#20](https://github.com/cdhagmann/gem-contribute/issues/20)).
+- `issues <gem|all>` prefixes claimed issues with `[claimed]` for the same reason (closes [#20](https://github.com/cdhagmann/gem-contribute/issues/20)).
+- Long-running CLI operations (`fix`'s fork → clone → branch pipeline; `submit`'s `git push`) now show a tty-spinner in interactive terminals. Non-TTY contexts (CI, piped output, redirected stderr) fall back to plain status lines — no behavior change for scripted use (closes [#30](https://github.com/cdhagmann/gem-contribute/issues/30)).
+
+### Changed
+
+- `gem-contribute init` reads input through `tty-prompt`. Cosmetic side effect: default values are now displayed in parens — `(~/code/oss)` — instead of brackets — `[~/code/oss]` — matching tty-prompt's convention. Y/n parsing is now built-in instead of hand-rolled (closes [#31](https://github.com/cdhagmann/gem-contribute/issues/31)).
+- Internal class `ForkCloneBranch` renamed to `Fix` (the long name was cumbersome and didn't mirror the `fix` CLI verb). User-facing CLI surface unchanged.
+- Internal architecture: `HostAdapter` now owns every host-API verb (`fork`, `comment`, `pull_request_url`) plus host-specific URL templating (`clone_url`, `repo_url`); the new `Operations::Fork` / `Operations::Clone` primitives compose those with `Git`; `CLI::Fork` and `CLI::Fix` are thin compositions on top. The fork-readiness polling moved into the adapter — multi-host adapters can model readiness however the host actually works. See [ADR-0011](docs/adr/0011-host-adapter-owns-host-verbs.md). User-facing CLI surface unchanged.
+- Internal architecture (ADR-0012 Phase 1): `Operations::*` classes are now output-free and return `dry-monads` `Success` / `Failure` `Result` types; new `Operations::Branch` and `Operations::Announce` primitives; `Operations::FixPipeline` composes Fork → Clone → Branch → Announce via `dry-operation`; `Workflow#build_adapter` returns a `Result` and the old `with_workflow_rescues` rescue chain is gone; `CLI::Fork` / `CLI::Fix` initializers use `dry-initializer`. See [ADR-0012](docs/adr/0012-output-free-service-objects-three-interface-architecture.md). User-facing CLI surface unchanged.
+- Internal architecture (ADR-0012 Phase 2): every CLI verb writes through a semantic `Output::Standard` (or `Output::Null` in tests) abstraction — `#info`, `#progress`, `#warn`, `#error` — instead of raw `@stdout.puts` / `@stderr.puts`. `#progress` accepts an optional block and wraps a `tty-spinner` in TTY contexts. Existing constructors still accept `stdout:` / `stderr:` and auto-wrap them, so test suites injecting StringIO streams keep working unchanged. New deps: `tty-spinner ~> 0.9`, `tty-prompt ~> 0.23` (both pure-Ruby) (closes [#29](https://github.com/cdhagmann/gem-contribute/issues/29)).
+
+### Removed
+
+- The `fork-clone-branch` CLI alias has been removed. Use `gem-contribute fix` instead — same behavior, shorter to type.
+
+### Fixed
+
+- `gem-contribute fork` no longer prints `cd <path> && explore` — `explore` was meant as English but read as a (non-existent) shell command, so a copy-paste produced `command not found`. The "Next:" hint is now conditional on `-e` / `-a`: with neither flag it suggests `cd <path> && $EDITOR .`; with either flag it skips the directory step (you're already in your editor) and just points at the `fix` command.
+
+## [0.2.0] - 2026-05-02
+
+### Added
+
+- `gem-contribute init` — interactive first-run setup: prompts for `clone_root` and chains into `auth login` when no token is cached. Users who skip it can run each step separately at any time.
+- Rate-limit footer after `scan` and `issues` runs: `GitHub rate limit: 4,587 / 5,000 remaining · resets at 14:32 UTC`. Surfaced so users know whether a degraded run is seconds or minutes away from recovering (closes [#4](https://github.com/cdhagmann/gem-contribute/issues/4)).
+
+### Changed
+
+- `gem-contribute fix` now errors with an `init` hint when `clone_root` is not configured, instead of silently defaulting to `~/code/oss/`. Existing users with a configured `clone_root` are unaffected (closes [#15](https://github.com/cdhagmann/gem-contribute/issues/15)).
+
+### Fixed
+
+- `gem-contribute submit` no longer requires an `upstream` remote. When only `origin` is present (e.g. when dogfooding on your own repo), it treats `origin` as the upstream and emits a same-repo compare URL. The cross-fork path is unchanged for normal contributors.
+
 ## [0.1.0] - 2026-04-28
 
 ### Added

data/CLAUDE.md

@@ -4,7 +4,7 @@ This file is read by Claude Code when working in this repository. Treat it as th
 
 ## Project shape
 
-`gem-contribute` is a terminal UI that reads a project's `Gemfile.lock`, surfaces open contributable issues from the gems' source repositories, and offers one-keystroke fork-clone-branch.
+`gem-contribute` is a terminal UI that reads a project's `Gemfile.lock`, surfaces open contributable issues from the gems' source repositories, and offers a one-keystroke `fix` flow.
 
 Read `docs/design.md` and the ADRs in `docs/adr/` before making non-trivial changes. The design doc describes the architecture and the ADRs explain why specific decisions were made. If a change conflicts with an ADR, propose updating the ADR first; don't silently violate it.
 

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,86 @@
+# Contributor Covenant Code of Conduct
+
+Version 3.0.
+
+## Our Pledge
+
+We pledge to make our community welcoming, safe, and equitable for all.
+
+We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant.
+
+## Encouraged Behaviors
+
+While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language.
+
+With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including:
+
+1. Respecting the **purpose of our community**, our activities, and our ways of gathering.
+2. Engaging **kindly and honestly** with others.
+3. Respecting **different viewpoints** and experiences.
+4. **Taking responsibility** for our actions and contributions.
+5. Gracefully giving and accepting **constructive feedback**.
+6. Committing to **repairing harm** when it occurs.
+7. Behaving in other ways that promote and sustain the **well-being of our community**.
+
+## Restricted Behaviors
+
+We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct.
+
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop.
+2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people.
+3. **Stereotyping or discrimination.** Characterizing anyone's personality or behavior on the basis of immutable identities or traits.
+4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community.
+5. **Violating confidentiality.** Sharing or acting on someone's personal or private information without their permission.
+6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group.
+7. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions.
+2. **Failing to credit sources.** Not properly crediting the sources of content you contribute.
+3. **Promotional materials.** Sharing marketing or other commercial content in a way that is outside the norms of the community.
+4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors.
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm.
+
+When an incident does occur, it is important to report it promptly. To report a possible violation, email **gem.contribute@cdhagmann.com**. Reports are read by the project maintainer.
+
+Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution.
+
+## Addressing and Repairing Harm
+
+If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped.
+
+1. Warning
+   1. Event: A violation involving a single incident or series of incidents.
+   2. Consequence: A private, written warning from the Community Moderators.
+   3. Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations.
+
+2. Temporarily Limited Activities
+   1. Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation.
+   2. Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members.
+   3. Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over.
+
+3. Temporary Suspension
+   1. Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation.
+   2. Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions.
+   3. Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted.
+
+4. Permanent Ban
+   1. Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member.
+   2. Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior.
+   3. Repair: There is no possible repair in cases of this severity.
+
+This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at https://www.contributor-covenant.org/version/3/0/.
+
+Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0.

data/CONTRIBUTING.md

@@ -5,11 +5,18 @@ Thanks for considering a contribution. This project is *about* lowering the fric
 ## Quick start
 
 ```
-git clone https://github.com/cdhagmann/gem-contribute
-cd gem-contribute
+gem install gem-contribute
+gem-contribute init                          # set clone_root and auth with GitHub
+gem-contribute fork gem-contribute           # fork + clone; lands on the default branch
 bundle install
-bin/rspec               # tests should pass on a clean checkout
-bin/gem-contribute      # tool should run against this repo's own Gemfile.lock
+bin/rspec                                    # tests should pass on a clean checkout
+bin/gem-contribute                           # tool should run against this repo's own Gemfile.lock
+```
+
+Once you've picked an issue to work on, branch off the default with `fix`:
+
+```
+gem-contribute fix gem-contribute/<issue#>   # creates gem-contribute/issue-<N> off the default branch
 ```
 
 ## What we welcome
@@ -21,14 +28,6 @@ bin/gem-contribute      # tool should run against this repo's own Gemfile.lock
 - Performance improvements with before/after numbers
 - Accessibility improvements to the TUI (color contrast, keyboard-only flows, screen-reader compatibility)
 
-## What we'd push back on
-
-- Label normalization (see [ADR-0005](docs/adr/0005-render-labels-verbatim.md))
-- Parsing CONTRIBUTING.md for structured data (see [ADR-0007](docs/adr/0007-display-contributing-verbatim.md))
-- AI-anything that summarizes, suggests, or rewrites maintainer-authored content
-- Bundler plugin packaging (see [ADR-0006](docs/adr/0006-standalone-gem-not-plugin.md)) — we'll consider it later, just not now
-
-If you have a strong case for any of the above, open an issue first and let's talk before you write code.
 
 ## PR expectations
 
@@ -39,7 +38,7 @@ If you have a strong case for any of the above, open an issue first and let's ta
 
 ## Code of Conduct
 
-Be kind. Assume good faith. The Ruby community deserves both. Specific incidents go to chris@example.com (placeholder — TODO: update before merging this).
+Be kind. Assume good faith. The Ruby community deserves both. The full text — adapted from [Contributor Covenant 3.0](https://www.contributor-covenant.org/version/3/0/) — lives in [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Specific incidents go to gem.contribute@cdhagmann.com.
 
 ## AI assistance
 

data/README.md

@@ -1,5 +1,7 @@
 # gem-contribute
 
+[![CI](https://github.com/cdhagmann/gem-contribute/actions/workflows/ci.yml/badge.svg)](https://github.com/cdhagmann/gem-contribute/actions/workflows/ci.yml)
+
 Find contributable issues in the gems your project already depends on.
 
 ```
@@ -35,10 +37,12 @@ Requires Ruby 3.2 or later.
 The CLI is a small set of subcommands:
 
 ```
+gem-contribute init                   One-time interactive setup (sets clone_root, then auth).
 gem-contribute scan [path]            Summarize the contributable surface of a Gemfile.lock.
 gem-contribute issues <gem|all>       List "good first issue" issues for one gem (or all).
 gem-contribute auth login             Authenticate with GitHub via OAuth device flow.
-gem-contribute fix <gem>/<issue#>     Fork the gem's repo, clone the fork, branch from main.
+gem-contribute fork <gem|owner/repo>  Fork and clone any GitHub repo, land on the default branch.
+gem-contribute fix <gem>/<issue#>     Fork, clone, and branch from main for a specific issue.
 gem-contribute submit                 Push the branch and open a pre-filled PR in the browser.
 gem-contribute config set <key> <val> Persist user preferences (e.g. clone_root).
 ```
@@ -46,29 +50,38 @@ gem-contribute config set <key> <val> Persist user preferences (e.g. clone_root)
 A typical session:
 
 ```sh
-$ gem-contribute auth login              # one-time; uses GitHub device flow
+$ gem-contribute init                    # one-time: sets clone_root, then auth via GitHub device flow
 $ gem-contribute scan                    # see what's worth contributing to
 $ gem-contribute issues rubocop          # drill into one project's issues
 $ gem-contribute fix rubocop/12345       # fork, clone, branch
-$ cd ~/code/oss/rubocop/rubocop          # (or wherever clone_root points)
+$ cd ~/code/oss/rubocop/rubocop          # whatever clone_root you set during init
 # ... make your change, commit ...
 $ gem-contribute submit                  # push + open the PR compare page in your browser
 ```
 
-The `auth login` step opens GitHub's device-flow page in your browser and copies the one-time code to your clipboard — same UX as `gh auth login`, no token paste, no client secret. Tokens cache at `~/.config/gem-contribute/auth.json` (mode 0600).
+Or, when you want to look around a project before picking an issue, use `fork`:
+
+```sh
+$ gem-contribute fork rubocop                       # fork-and-clone a gem by name
+$ gem-contribute fork rubyevents/rubyevents -e      # fork-and-clone any GitHub repo and open your editor
+```
+
+`fork` does the same fork-clone-upstream sequence as `fix` but stops on the default branch — no issue branch, no comment. Handy for "build it locally and decide what to fix later." When you've picked an issue, `gem-contribute fix <gem>/<issue#>` branches off cleanly.
+
+The auth step (run automatically by `init`, or directly via `gem-contribute auth login`) opens GitHub's device-flow page in your browser and copies the one-time code to your clipboard — same UX as `gh auth login`, no token paste, no client secret. Tokens cache at `~/.config/gem-contribute/auth.json` (mode 0600).
 
 ## Configuration
 
-User config lives at `~/.config/gem-contribute/config.yml`. Manage it with `gem-contribute config`:
+User config lives at `~/.config/gem-contribute/config.yml`. The interactive way to set it is `gem-contribute init`; for scripted setup, use `gem-contribute config`:
 
 ```sh
 gem-contribute config set clone_root ~/Projects/oss
 gem-contribute config list
 ```
 
-| Key          | Default      | Notes                                            |
-|--------------|--------------|--------------------------------------------------|
-| `clone_root` | `~/code/oss` | Where `fix` clones forks (`<root>/<owner>/<repo>`). |
+| Key          | Notes                                                                              |
+|--------------|------------------------------------------------------------------------------------|
+| `clone_root` | Where `fix` clones forks (`<root>/<owner>/<repo>`). Set via `init` or `config set`. No default — `fix` errors if unset. |
 
 ## Design
 

data/docs/OPEN_QUESTIONS.md

@@ -0,0 +1,167 @@
+# Open Questions — Roadmap to v1
+
+Working list of unresolved planning questions for the v1 roadmap (TUI + CLI + `bundle contribute` + `gem contribute`). Walked through one at a time with the maintainer; each gets crossed off and folded into the ROADMAP / ADRs as it's answered.
+
+Order is rough priority — top items block downstream design, bottom items are polish.
+
+---
+
+## Q1. ~~What is the "world map view"?~~ — ANSWERED 2026-05-03
+
+A near-easter-egg view showing the locations of people who've kicked the tires on `gem-contribute`. Tracked as [issue #5](https://github.com/cdhagmann/gem-contribute/issues/5). Not a primary fragment — a hidden/discoverable view.
+
+**Implications this surfaces:**
+- Requires some form of opt-in usage reporting (the tool has to phone home with *something* to populate the map). New component: a tire-kicker reporting backend.
+- Privacy/consent UX needs to live somewhere — likely first-run prompt or `init` flow.
+- Backend service is itself a v1 dependency *if* the map ships in v1.
+
+→ See **Q1a** below.
+
+---
+
+## Q1a. ~~Does the world map ship in v1?~~ — ANSWERED 2026-05-03
+
+No. Preserving the option by choosing Rooibos now; tire-kicker map waits until there's enough adoption to make the data interesting. No backend work in v1 scope.
+
+**ADR-0013 reasoning lock-in:**
+1. Workshop onboarding cost — the main argument for bubbletea — is no longer a constraint (workshop ended 2026-05-02)
+2. Preserving the world map view (issue #5) as a future option
+3. ADR-0008's original technical reasoning still stands (Command primitives matched our verbs, snapshot test helpers, fractal Router architecture)
+4. Bubbletea-ruby's testing story was unverified per ADR-0010; Rooibos shipped tested helpers
+
+---
+
+## Q2. ~~Packaging shape~~ — ANSWERED 2026-05-03
+
+One gem. `gem-contribute` ships the standalone CLI, the Bundler plugin hooks, and the RubyGems plugin hooks all together. ADR-0012's mention of a future `rubygems-contribute` gem is overridden by ADR-0014 (the new plugin ADR).
+
+---
+
+## Q3. ~~What do `bundle contribute` / `gem contribute` do?~~ — ANSWERED 2026-05-03
+
+CLI only — no TUI from the plugins. Reasoning: Bundler and RubyGems plugins aren't typically interactive; they're CLI subcommands. The TUI is a property of the standalone `gem-contribute` binary.
+
+- `gem-contribute` (no args) → TUI
+- `bundle contribute` (no args) → CLI default (`scan` or `list all` — see **Q3a**)
+- `gem contribute` (no args) → CLI default (same)
+- `<any>` `<verb>` → CLI verb
+
+**Architectural consequence:** the plugin entry points never need to load Rooibos. Keeps plugin install lightweight.
+
+---
+
+## Q3a. Bare-call default for the plugins: `scan` or `list all`?
+
+User flagged as undecided. Both are read-only summary actions; difference is granularity and verbosity.
+
+- **`scan`** — current verb; prints the summary table (`47 gems · 44 on github.com · 2 on gitlab.com · …`) plus top contributable projects by issue count. Hits the network for the issue counts (cached).
+- **`list all`** — would presumably print every gem with its resolved source. Less network, more data, less curated.
+
+No urgency to pick — can be deferred to Phase 4. Worth deciding alongside the verb taxonomy review (does `list` exist as a separate verb? sub-verbs of `list`?).
+
+---
+
+## Q4. ~~Default behavior of bare `gem-contribute`~~ — ANSWERED 2026-05-03
+
+Packwerk-style launcher: `gem-contribute` (no args) opens a mini TUI that lists subcommands; arrow keys + enter pick one. `gem-contribute <verb>` runs the verb directly with no TUI in the way.
+
+→ See **Q4a**: this reframes what the "full TUI" is.
+
+---
+
+## Q4a. ~~What happens to the design.md "full TUI"?~~ — ANSWERED 2026-05-03
+
+Bare `gem-contribute` launches the design.md four-fragment TUI (ProjectList → IssueList → IssueDetail → ContributingViewer + AuthOverlay + the eventual WorldMap). The packwerk reference was establishing "yes, raw command launches a TUI" as precedent — not a directive to mirror packwerk's exact subcommand-picker shape. Subcommands stay CLI.
+
+Phase 3 of ROADMAP doesn't need rewriting; just confirm the entry-point wiring in `cli.rb` (no-arg → launch TUI vs print USAGE).
+
+---
+
+## Q5. ~~Multi-host adapters in v1?~~ — ANSWERED 2026-05-03
+
+GitHub-only at v1.0. v1.x point releases will add adapters (GitLab, Codeberg, etc.). ADR-0011's architecture is the bet that paying off.
+
+---
+
+## Q6. ~~Does ADR-0012's dry-rb adoption survive the framework revert?~~ — ANSWERED 2026-05-03
+
+Yes. We need both a CLI and a TUI; output-free service objects with `Result` returns are what lets both consume the same service layer. ADR-0013 (Rooibos revert) doesn't touch ADR-0012.
+
+Sub-question on `dry-cli` adoption is **deferred to Phase 4/5** when the plugin entry points get wired — easier to decide once the plugin shape is concrete.
+
+---
+
+## Q7. Rooibos 0.7.x verification — ASSIGNED TO ME
+
+Pre-Phase-3 task (no user decision needed): confirm Rooibos's current version on rubygems.org, verify Command primitives still exist, verify snapshot test helpers still ship. Folded into ROADMAP Phase 3.
+
+---
+
+## Q8. ~~Workshop docs disposition~~ — MY CALL: archive
+
+Moving workshop-era docs (`workshop.md`, `talk/`, `workshop-issues/`, `prep-plan.md`) to `docs/archive/` in Phase 6. Preserves history without polluting the active doc surface. Flag if you'd rather delete or keep them in place.
+
+---
+
+## Q9. ~~Test framework + cassette policy~~ — MY CALL: keep design.md's strategy as-is
+
+RSpec, VCR cassettes committed, no formal coverage target (just "every public method, every Update branch"). Snapshot helpers come from Rooibos — verified in Q7. Flag if you want a different testing posture for v1.
+
+---
+
+## Q10. ~~v1 out-of-scope confirmation~~ — MY CALL: existing exclusions stand
+
+All ADR-mandated out-of-scope items remain out for v1.0:
+- Private repos / `repo` OAuth scope
+- PR creation from inside the TUI (browser-based stays per ADR-0011)
+- AI-anything
+- Label normalization
+- CONTRIBUTING parsing
+- Multi-host adapters (per Q5; v1.x territory)
+- World map view (per Q1a; post-v1)
+
+Flag if anything moves into v1.
+
+---
+
+## Q11. Branding / homepage — DEFER
+
+Pre-release polish; revisit during Phase 6.
+
+---
+
+## Q12. CHANGELOG.md / CONTRIBUTING.md / MAINTAINER.md — task list, not decision
+
+Folded into ROADMAP Phase 6. No decision needed.
+
+---
+
+## Q13. ~~OAuth App identity for v1 release~~ — ANSWERED 2026-05-03
+
+Stay on the personal-account OAuth App for v1.0. Migrate to a dedicated identity when rate limits actually bite. Pragmatic — fits the rest of the v1 scope (don't pay for problems we don't have yet).
+
+---
+
+## Q14. ~~CI / release automation~~ — ANSWERED 2026-05-03
+
+GitHub Actions, two workflows:
+
+**CI (`ci.yml`)** — runs on push/PR:
+- rubocop
+- rspec
+- integration tests gated behind `GEM_CONTRIBUTE_INTEGRATION=1` (off by default)
+- smoke test: `bundle plugin install` + `gem install` on a clean Ruby image, verify both plugin entry points dispatch a verb
+
+**Release (`release.yml`)** — runs on `v*` tag push:
+- **Trusted Publishing via OIDC.** No API key stored as a secret; rubygems.org issues a short-lived token from the GitHub Actions OIDC claim. Compatible with `rubygems_mfa_required = true` (which the gemspec already sets).
+- Setup: configure a trusted publisher entry on rubygems.org (gem name + repo + workflow filename) before the first automated release.
+
+Multi-Ruby matrix and signed gems are post-v1.0 unless they become a real ask.
+
+---
+
+## Notes / parking lot
+
+- `docs/ideas.md` has one stray idea: "Make sure it respects PR templates" — file as a v1 issue.
+- `docs/index.md` and `docs/_config.yml` suggest a Jekyll site; not yet investigated.
+- `docs/claude-code-prompt.md` — not yet investigated.