gem-contribute 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ba185bef64e34f7c11bce3b56e18dc85f9a937a597db98615977b8b29d0306a
-  data.tar.gz: f1f2c4b77dca2e77da8eaa188a3a2db6d87d4c62eef471c3e9e8d13faff3ecc5
+  metadata.gz: fb726fe2025ba0cc501be01d13b4138ff4b21a9c755ad81c9b0181ef35f41c88
+  data.tar.gz: 33e6e83e38b27f2b4e2079fc79cfa76c2bfb178a2ba37424a05dfc8ad91398c0
 SHA512:
-  metadata.gz: 6a52e54602d58024cc94db5cd353556b0f0d18ea6b07a5647a918a96c748547b692531a53ee1f6a1fd7e7a887b9cf30650edce9568a84a76d993245b68d35661
-  data.tar.gz: 9c4b75036cb2091312b1405797ebea50fe9ab1103ae793081834c03a5e18a1151c006f127e84f160b234a8ab6b8037e243bf3d09feea962daeb8854f96c3770b
+  metadata.gz: fa04494e7ac4294f90d14ecb01d3f111d7e890dd5dc9ec1c5b77bc83aa215e8c0cac467f6bd9fa38ffa73c4665aece92520269473cf0f95555f48096a5a2b372
+  data.tar.gz: 4e9bfd2d676ac59d5d8c8c8db0e7928641c8e4f031a85fd435f1e52ec3b1b770aa41a705f456ad488a23019520093787d58e8326bbbf42e51f24a30e185a0cfc

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -2,21 +2,27 @@
 
 <!-- One or two sentences. What changes, and why. The "why" is the part that's hard to recover later. -->
 
-## Review preference
+## Linked issue / ADR
 
-Lowering friction is the whole point of this project. Pick whichever fits — defaults to the first if you don't tick anything.
+<!--
+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.
+-->
 
-- [ ] **Ship it.** Review for correctness, tests, and design fit. Skip style nits unless they're load-bearing.
-- [ ] **Full review, please.** Feedback on style, naming, idioms, and alternative designs welcome. I want the deep version, whether to learn the Ruby way or to stress-test a pattern I'm trying.
-
-## Working agreement check
+## Working agreement
 
 - [ ] Single concern (multi-concern PRs get bounced — see [CLAUDE.md](../CLAUDE.md))
-- [ ] ADRs touched: <!-- list ADR numbers, or "none" -->
 - [ ] `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. -->
+<!-- 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,32 @@ 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

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/CONTRIBUTING.md

@@ -6,11 +6,17 @@ Thanks for considering a contribution. This project is *about* lowering the fric
 
 ```
 gem install gem-contribute
-gem-contribute init                       # set clone_root and auth with GitHub
-gem-contribute fix gem-contribute/issue-5
+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

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.
 
 ```
@@ -39,7 +41,8 @@ gem-contribute init                   One-time interactive setup (sets clone_roo
 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).
 ```
@@ -56,6 +59,15 @@ $ cd ~/code/oss/rubocop/rubocop          # whatever clone_root you set during in
 $ gem-contribute submit                  # push + open the PR compare page in your browser
 ```
 
+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

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.