gem-contribute 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f6941e81cacd8ab2bb7abb6824bb54d5b04ec05789d24c792b48eb4c5125e02
-  data.tar.gz: 9a548392f2d027dbc99719d74de627940086e3858fd5c5152fa8d4ecffddb7b8
+  metadata.gz: 1ba185bef64e34f7c11bce3b56e18dc85f9a937a597db98615977b8b29d0306a
+  data.tar.gz: f1f2c4b77dca2e77da8eaa188a3a2db6d87d4c62eef471c3e9e8d13faff3ecc5
 SHA512:
-  metadata.gz: 1a4c00ea48ba2ef0245f3564d97b2bb0e6d3eb7098a79ef598a58dda95c6130630648e04351e8a5ef7f767456d938a836c647aa02c18d7b22663816a6b9d7d2e
-  data.tar.gz: 1d60a359d87cc17ba4e2c8bad1acab5f039334df63afd34055165d1a61b569e3c9c7fd57f5159d33ed0031e7634cabb93fd1b82e52f36cd4a5d0e30bfd2ef2ca
+  metadata.gz: 6a52e54602d58024cc94db5cd353556b0f0d18ea6b07a5647a918a96c748547b692531a53ee1f6a1fd7e7a887b9cf30650edce9568a84a76d993245b68d35661
+  data.tar.gz: 9c4b75036cb2091312b1405797ebea50fe9ab1103ae793081834c03a5e18a1151c006f127e84f160b234a8ab6b8037e243bf3d09feea962daeb8854f96c3770b

data/.gem_release.yml

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

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+## Summary
+
+<!-- One or two sentences. What changes, and why. The "why" is the part that's hard to recover later. -->
+
+## Review preference
+
+Lowering friction is the whole point of this project. Pick whichever fits — defaults to the first if you don't tick anything.
+
+- [ ] **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
+
+- [ ] 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)
+
+## Notes for reviewer
+
+<!-- Tradeoffs, open questions, follow-ups — anything not obvious from the diff. -->

data/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented here. The format is based
 
 ## [Unreleased]
 
+## [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/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,8 +5,9 @@ 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 fix gem-contribute/issue-5
 bundle install
 bin/rspec               # tests should pass on a clean checkout
 bin/gem-contribute      # tool should run against this repo's own Gemfile.lock
@@ -21,14 +22,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 +32,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

@@ -35,6 +35,7 @@ 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.
@@ -46,29 +47,29 @@ 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).
+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/adr/0008-rooibos-tui-framework.md

@@ -1,6 +1,6 @@
 # ADR 0008: Use Rooibos for the TUI layer
 
-**Status:** Accepted
+**Status:** Superseded by [ADR-0010](0010-charm-ruby-tui-framework.md)
 **Date:** 2026-04-27
 **Supersedes parts of:** the original "TUI built directly on `ratatui_ruby`" approach implied by ADR-0001 and the `docs/design.md` v1.
 

data/docs/adr/0010-charm-ruby-tui-framework.md

@@ -0,0 +1,84 @@
+# ADR 0010: Use Charm-Ruby (bubbletea + lipgloss) for the TUI layer
+
+**Status:** Accepted
+**Date:** 2026-05-02
+**Supersedes:** [ADR-0008](0008-rooibos-tui-framework.md)
+
+## Context
+
+[ADR-0008](0008-rooibos-tui-framework.md) chose Rooibos (on `ratatui_ruby`) as the TUI framework. That decision was made on 2026-04-27, *before* `bubbletea-ruby` (Marco Roth's Ruby bindings to Charm's Bubble Tea) existed. Bubbletea-ruby was first published on 2025-12-26 and is now at 0.1.4 (March 2026); the companion styling library, `lipgloss-ruby`, is at 0.2.2.
+
+Stage 3 (the TUI work, [issue #2](https://github.com/cdhagmann/gem-contribute/issues/2)) has not started, so the cost of changing this decision is at its lifetime minimum.
+
+## Decision
+
+Use **bubbletea-ruby** as the TUI framework, with **lipgloss-ruby** for styling. This replaces Rooibos and removes `ratatui_ruby` from the dependency tree.
+
+## Reasoning
+
+**Idiomatic Ruby surface.** Bubbletea-ruby's API is plain Ruby — `class Foo; include Bubbletea::Model; def init; def update(msg); def view; end`. Rooibos uses lambda-as-constants (`Init = ->`, `View = ->`), which ADR-0008 itself called out as a real onboarding cost for Rails developers. For Blue Ridge Ruby 2026, lower onboarding cost matters.
+
+**Battle-tested core.** The Go bubbletea library is the dominant TUI framework in the Go ecosystem — used by `gh`, `glow`, the Charm CLI suite, and dozens of other production tools. Bubbletea-ruby is a young binding (0.1.x), but the rendering and event-loop semantics it wraps are mature in a way that no pure-Ruby alternative is.
+
+**Workshop transferability.** "You're learning the Ruby flavor of Bubble Tea" is a stronger pitch than "you're learning Rooibos." MVU is the transferable mental model; Bubble Tea is the largest MVU-TUI ecosystem to walk into afterward.
+
+**Install friction is acceptable on workshop hardware.** Both frameworks ship precompiled binaries via the standard Ruby gem-platform mechanism. On a typical Mac/Linux workshop laptop, `gem install` pulls a binary; no Rust or Go toolchain on the user's machine. Verified on rubygems.org:
+
+| Platform                   | ratatui_ruby (1.5.0) | bubbletea (0.1.4) / lipgloss (0.2.2) |
+|----------------------------|-----------------------|---------------------------------------|
+| macOS arm64                | precompiled           | precompiled                            |
+| macOS x86_64               | source build          | precompiled                            |
+| Linux x86_64 gnu           | precompiled           | precompiled                            |
+| Linux x86_64 musl          | source build          | precompiled                            |
+| Linux arm64 (gnu/musl)     | source build          | precompiled                            |
+| Windows                    | precompiled           | source build                           |
+
+Bubbletea wins broadly on Mac+Linux; ratatui_ruby wins on Windows. For a regional Ruby conference, that asymmetry favors bubbletea.
+
+**Companion ecosystem.** Lipgloss-ruby provides idiomatic styling; the Charm-Ruby umbrella (charm-ruby.dev) signals an ongoing port effort, not a one-off binding.
+
+## Tradeoffs accepted
+
+**Project-shaped Command primitives are gone.** Rooibos provides `Command.system`, `Command.http`, `Command.wait`, `Command.cancel` as first-class primitives matching this project's exact verbs. Bubbletea-ruby follows the Go idiom: a Command is a closure that returns a message. We write thin helpers — `http_command(url, envelope:)`, `system_command(argv, envelope:)`, `wait_command(seconds, envelope:)` — once, and use them throughout. This is the only meaningful piece of Rooibos value we reproduce ourselves.
+
+**Test helpers unverified.** Rooibos shipped pure-function-Update testing + snapshot helpers + headless terminal style assertions. Bubbletea-ruby's testing story is not yet documented in its README. Pre-merge of Stage 3, verify what bubbletea-ruby ships and either use it, port `teatest` patterns from Go's bubbletea, or build a minimal snapshot harness. Acceptable risk because pure-function `update` is testable on its own.
+
+**Younger Ruby surface.** Bubbletea-ruby is at 0.1.4; Rooibos was at 0.7/0.8. Both are pre-1.0 with API-change risk; bubbletea-ruby has had less time to settle. Mitigation: pin bubbletea-ruby and lipgloss to known-good versions; bump deliberately with verification.
+
+**Two native gems vs one.** Bubbletea-ruby and lipgloss-ruby are both Go-built native gems; Rooibos was pure Ruby on top of one native gem (`ratatui_ruby`). The user-visible difference is marginal — both `bundle install` to a precompiled binary on common platforms.
+
+**Maintainer alignment.** Rooibos and `ratatui_ruby` were both Kerrick Long: one mind, one ecosystem. Charm-Ruby splits maintainership across charmbracelet (Go upstream) and Marco Roth (Ruby bindings, plus many other projects). When Go upstream bumps an API, Marco's lag determines our exposure. Mitigation: pin to a known-good version; bump deliberately.
+
+**Windows attendees compile.** No precompiled bubbletea binary for Windows. Document the source-build path in `docs/workshop.md` for any Windows attendee.
+
+## Alternatives considered
+
+- **Stay on Rooibos.** ADR-0008's reasoning is no longer current. The "lambda-as-constant style is unfamiliar" cost it identified is removed by switching, and the platform matrix favors bubbletea on the workshop's expected hardware.
+- **Bare bubbletea (no lipgloss).** Bubbletea handles the rendering loop; lipgloss handles styling. Skipping lipgloss means hand-building style helpers. Not worth it — lipgloss is small, well-shaped, and idiomatic to use alongside bubbletea.
+- **Wait for bubbletea-ruby 1.0.** Same logic as ADR-0008 declining to wait for Rooibos 1.0: the architectural fit is good, the change cost rises every week we delay, and pinning is sufficient mitigation.
+
+## Consequences
+
+**On dependencies:** remove `rooibos` from the gemspec. Add `bubbletea` (`~> 0.1.4`) and `lipgloss` (`~> 0.2.2`). Drop the `ratatui_ruby` Rust-toolchain warning from `docs/workshop.md`.
+
+**On `docs/design.md`:** the TUI-layer section needs reworking — fragments become bubbletea models composed by routing, lambda-as-constant examples are replaced with idiomatic class-with-mixin examples, the Command list (`Command.http`, etc.) is replaced with the wrapper helpers defined above.
+
+**On `CLAUDE.md`:** the working-agreement bullet "Async work is always a Rooibos Command" becomes "Async work is always a bubbletea Command." The package-pinning note about Rooibos is replaced with bubbletea/lipgloss pins.
+
+**On ADR-0008:** marked Superseded by ADR-0010.
+
+**On [issue #2](https://github.com/cdhagmann/gem-contribute/issues/2):** rewritten to point at bubbletea-ruby + lipgloss-ruby instead of Rooibos.
+
+**On the workshop:** attendees still learn MVU, but the framing is "Charm-style TUI in Ruby" — the same pattern as `gh`, `glow`, and the Charm CLIs they may already know.
+
+**On testing:** before Stage 3 lands, verify bubbletea-ruby's test helpers. If absent, port `teatest` patterns or build a minimal snapshot harness. Pure-function `update` testability is independent of the framework choice.
+
+**On the maintainer relationship:** reach out to Marco Roth before the workshop to mention "we're building a workshop project on bubbletea-ruby for Blue Ridge Ruby 2026" — same etiquette ADR-0008 prescribed for Kerrick Long.
+
+## What this *doesn't* change
+
+- ADR-0001 (just-in-time auth). MVU shape preserved; framework change.
+- ADR-0002, ADR-0003, ADR-0004 (data layer). Outside the TUI.
+- ADR-0005, ADR-0007 (render verbatim, no parsing). Display contract; framework choice doesn't affect it.
+- ADR-0006 (standalone gem, not Bundler plugin). Packaging concern; orthogonal.
+- ADR-0009 (top-level namespace). Orthogonal.

data/docs/adr/README.md

@@ -13,8 +13,9 @@ Format: [Michael Nygard's template](https://github.com/joelparkerhenderson/archi
 - [0005 — Render labels verbatim](0005-render-labels-verbatim.md)
 - [0006 — Ship as a standalone gem, not a Bundler plugin](0006-standalone-gem-not-plugin.md)
 - [0007 — Show CONTRIBUTING; don't parse it](0007-display-contributing-verbatim.md)
-- [0008 — Use Rooibos for the TUI layer](0008-rooibos-tui-framework.md)
+- [0008 — Use Rooibos for the TUI layer](0008-rooibos-tui-framework.md) — superseded by 0010
 - [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)
 
 ## When to add an ADR
 

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
 

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.