kettle-dev 1.1.4 → 1.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e041df45a5e998c2dabf617686124f45b29aa26d93c1dcf21e0da99cffcac3b
-  data.tar.gz: 183b02683f8a96d82ad6df04371b8776110a30eb768c395060f3d8dd2a5011b0
+  metadata.gz: f68d8b2e7fab5b4e07af0c56ef2b13754adcb43a91cb1bc521527153b11db756
+  data.tar.gz: 41a619d94690defc476bcf2666dd71acabeffce33c7c47eaa6b912b5983a9117
 SHA512:
-  metadata.gz: 505620d1cef37c67523e6c8760172f215b650e3f972397170f4f0275a838c8b0a1d9ab1b36e5cc1dbeedfb8327672e02b94be7e2269cb3f446375a83abed040b
-  data.tar.gz: 2de8a12668ed28128b11425f2097473ad60714a98985375c249053ca001b9e23e295c2e1afde917b2d8a13fab4270362cc5bffb4916637e56dd6b43687240425
+  metadata.gz: e5efa939db2b66d476069297dd8340b07f8a62763248e13ef81d4cd9ac34d1c7a8ebd1f11e481580ed608f33a181e32d673fcf552561ad9efd7765b266ff49f0
+  data.tar.gz: 0a9c66859f5fb518e197a29b367da2fe0fdfe0fa941b9de48627ac4464e2f9c497dcbf41882603f8b907664b880922adacf9aab08725a1eae48f3cbae26a8f6b

data/.env.local.example

@@ -11,4 +11,17 @@ export AUTOGEN_FIXTURE_CLEANUP=false # autogenerated gem fixture cleanup after e
 export GIT_HOOK_FOOTER_APPEND=false
 export GIT_HOOK_FOOTER_APPEND_DEBUG=false
 export GIT_HOOK_FOOTER_SENTINEL="⚡️ A message from a fellow meat-based-AI ⚡️"
-export GITHUB_TOKEN=<your GH PAT, for the GHA console bin/rake ci:act - DO NOT EVER COMMIT IT>
+
+# Tokens used by ci:act and CI helpers for reading workflow/pipeline status via APIs
+# GitHub (either GITHUB_TOKEN or GH_TOKEN will be used; fine-grained recommended)
+# - Scope/permissions: For fine-grained tokens, grant repository access (Read) and Actions: Read
+# - For classic tokens, public repos need no scopes; private repos typically require repo
+export GITHUB_TOKEN=<your GH token for GHA status; NEVER COMMIT>
+# Alternatively:
+# export GH_TOKEN=<your GH token>
+
+# GitLab (either GITLAB_TOKEN or GL_TOKEN will be used)
+# - Scope: read_api is sufficient to read pipelines
+export GITLAB_TOKEN=<your GitLab token for pipeline status; NEVER COMMIT>
+# Alternatively:
+# export GL_TOKEN=<your GitLab token>

data/.envrc

@@ -21,8 +21,8 @@ export K_SOUP_COV_DO=true # Means you want code coverage
 export K_SOUP_COV_COMMAND_NAME="Test Coverage"
 # Available formats are html, xml, rcov, lcov, json, tty
 export K_SOUP_COV_FORMATTERS="html,xml,rcov,lcov,json,tty"
-export K_SOUP_COV_MIN_BRANCH=78 # Means you want to enforce X% branch coverage
-export K_SOUP_COV_MIN_LINE=97 # Means you want to enforce X% line coverage
+export K_SOUP_COV_MIN_BRANCH=81 # Means you want to enforce X% branch coverage
+export K_SOUP_COV_MIN_LINE=96 # Means you want to enforce X% line coverage
 export K_SOUP_COV_MIN_HARD=true # Means you want the build to fail if the coverage thresholds are not met
 export K_SOUP_COV_MULTI_FORMATTERS=true
 export K_SOUP_COV_OPEN_BIN= # Means don't try to open coverage results in browser

data/.git-hooks/commit-msg

@@ -1,21 +1,24 @@
 #!/usr/bin/env ruby
 # vim: set syntax=ruby
 
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
-
-require "rubygems"
-require "bundler/setup"
-
-# External gems
-require "gitmoji/regex"
+# Do not rely on Bundler; allow running outside a Bundler context
+begin
+  require "rubygems"
+rescue LoadError
+  # continue
+end
 
-full_text = File.read(ARGV[0])
-# Is the first character a GitMoji?
-gitmoji_index = full_text =~ Gitmoji::Regex::REGEX
-if gitmoji_index == 0
-  exit 0
-else
-  denied = <<EOM
+begin
+  # External gems
+  require "gitmoji/regex"
+
+  full_text = File.read(ARGV[0])
+  # Is the first character a GitMoji?
+  gitmoji_index = full_text =~ Gitmoji::Regex::REGEX
+  if gitmoji_index == 0
+    exit 0
+  else
+    denied = <<EOM
 Oh snap, think again...
 
  ______    _______      ___  _______  _______  _______  _______  ______   __
@@ -36,6 +39,9 @@ Must match: #{Gitmoji::Regex::REGEX.to_s}
 Example: git commit -m "✨ My excellent new feature"
 
 EOM
-  puts denied
-  exit 1
+    puts denied
+    exit 1
+  end
+rescue LoadError => e
+  warn("gitmoji-regex gem not found: #{e.class}: #{e.message}.\n\tInstall the 'gitmoji-regex' gem to enable this check.\n\tSkipping gitmoji check.")
 end

data/.git-hooks/prepare-commit-msg.example

@@ -0,0 +1,19 @@
+#!/bin/sh
+
+# Fail on error and unset variables
+set -eu
+
+# Determine project root as the parent directory of this hook script
+PROJECT_ROOT="$(CDPATH= cd -- "$(dirname -- "$0")"/.. && pwd)"
+
+# Run the Ruby hook within the direnv context (if available),
+# so ENV from .envrc/.env.local at project root is loaded.
+# One of the things .envrc needs to do is add $PROJECT_ROOT/bin/ to the path.
+# You should have this line at the top of .envrc
+#   PATH_add bin
+# NOTE: If this project ships exe scripts it should also add that.
+if command -v direnv >/dev/null 2>&1; then
+  exec direnv exec "$PROJECT_ROOT" "kettle-commit-msg" "$@"
+else
+  raise "direnv not found. Local development of this project ($PROJECT_ROOT) with tools from the kettle-dev gem may not work properly. Please run 'brew install direnv'."
+fi

data/.github/workflows/coverage.yml

@@ -7,7 +7,7 @@ permissions:
 
 env:
   # Lower than local, which is at 100/100, because rubocop-lts isn't installed in the coverage workflow
-  K_SOUP_COV_MIN_BRANCH: 73
+  K_SOUP_COV_MIN_BRANCH: 78
   K_SOUP_COV_MIN_LINE: 93
   K_SOUP_COV_MIN_HARD: true
   K_SOUP_COV_FORMATTERS: "xml,rcov,lcov,tty"
@@ -116,7 +116,7 @@ jobs:
           hide_complexity: true
           indicators: true
           output: both
-          thresholds: '93 73'
+          thresholds: '93 78'
         continue-on-error: ${{ matrix.experimental != 'false' }}
 
       - name: Add Coverage PR Comment

data/.junie/guidelines.md

@@ -133,3 +133,7 @@ Notes
 - Coverage reports: NEVER review the HTML report. Use JSON (preferred), XML, LCOV, or RCOV. For this project, always run tests with K_SOUP_COV_FORMATTERS set to "json".
 - Do NOT modify .envrc in tasks; when running tests locally or in scripts, manually prefix each run, e.g.: K_SOUP_COV_FORMATTERS="json" bin/rspec
 - For all the kettle-soup-cover options, see .envrc and find the K_SOUP_COV_* env vars.
+
+Important documentation rules
+- Do NOT edit files under docs/ manually; they are generated by `bundle exec rake yard` as part of the default rake task.
+- Clarification: Executable scripts provided by this gem (exe/* and installed binstubs) work when the gem is installed as a system gem (gem install kettle-dev). However, the Rake tasks provided by this gem require kettle-dev to be declared as a development dependency in the host project's Gemfile and loaded in the project's Rakefile.

data/.opencollective.yml.example

@@ -0,0 +1,3 @@
+collective: "{OPENCOLLECTIVE|ORG_NAME}"
+readme-backers-commit-subject: "💸 Thanks 🙏 to our new backers 🎒 and subscribers 📜"
+readme-osc-tag: "OPENCOLLECTIVE"

data/CHANGELOG.md

@@ -24,6 +24,34 @@ Please file a bug if you notice a violation of semantic versioning.
 ### Fixed
 ### Security
 
+## [1.1.5] - 2025-09-04
+- TAG: [v1.1.5][1.1.5t]
+- COVERAGE: 33.87% -- 1125/3322 lines in 22 files
+- BRANCH COVERAGE: 22.04% -- 361/1638 branches in 22 files
+- 76.83% documented
+### Added
+- kettle-pre-release: run re-release checks on a library
+  - validate URLs of image assets in Markdown files
+- honor ENV["FUNDING_FORGE"] set to "false" as intentional disabling of funding-related logic.
+- Add CLI Option --only passthrough from kettle-dev-setup to Installation Task
+- Comprehensive documentation of all exe/ scripts in README.md
+- add gitlab pipeline result to ci:act
+- highlight SHA discrepancies in ci:act task header info
+- how to set up forge tokens for ci:act, and other tools, instructions for README.md
+### Changed
+- expanded use of adapter patterns (Exit, Git, and Input)
+- refactored and improved structure of code, more resilient
+- kettle-release: do not abort immediately on CI failure; continue checking all workflows, summarize results, and prompt to (c)ontinue or (q)uit (reuses ci:act-style summary)
+### Removed
+- defensive NameError handling in ChangelogCLI.abort method
+### Fixed
+- replace token {OPENCOLLECTIVE|ORG_NAME} with funding org name
+- prefer .example version of .git-hooks
+- kettle-commit-msg now runs via rubygems (not bundler) so it will work via a system gem
+- fixed logic for handling derivation of forge and funding URLs
+- allow commits to succeed if dependencies are missing or broken
+- RBS types documentation for GemSpecReader
+
 ## [1.1.4] - 2025-09-02
 - TAG: [v1.1.4][1.1.4t]
 - COVERAGE: 67.64% -- 554/819 lines in 9 files
@@ -468,7 +496,9 @@ Please file a bug if you notice a violation of semantic versioning.
   - Selecting will run the selected workflow via `act`
   - This may move to its own gem in the future.
 
-[Unreleased]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.4...HEAD
+[Unreleased]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.5...HEAD
+[1.1.5]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.4...v1.1.5
+[1.1.5t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.1.5
 [1.1.4]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.3...v1.1.4
 [1.1.4t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.1.4
 [1.1.3]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.2...v1.1.3

data/CONTRIBUTING.md

@@ -22,6 +22,35 @@ Follow these instructions:
 6. Make sure to add tests for it. This is important, so it doesn't break in a future release.
 7. Create new Pull Request.
 
+## Executables vs Rake tasks
+
+Executables shipped by kettle-dev can be used with or without generating the binstubs.
+They will work when kettle-dev is installed globally (i.e., `gem install kettle-dev`) and do not require that kettle-dev be in your bundle.
+
+- kettle-changelog
+- kettle-commit-msg
+- kettle-dev-setup
+- kettle-dvcs
+- kettle-pre-release
+- kettle-readme-backers
+- kettle-release
+
+However, the rake tasks provided by kettle-dev do require kettle-dev to be added as a development dependency and loaded in your Rakefile.
+See the full list of rake tasks in head of Rakefile
+
+**Gemfile**
+```ruby
+group :development do
+  gem "kettle-dev", require: false
+end
+```
+
+**Rakefile**
+```ruby
+# Rakefile
+require "kettle/dev"
+```
+
 ## Environment Variables for Local Development
 
 Below are the primary environment variables recognized by stone_checksums (and its integrated tools). Unless otherwise noted, set boolean values to the string "true" to enable.

data/FUNDING.md

@@ -18,11 +18,11 @@ Many paths lead to being a sponsor or a backer of this project. Are you on such
 [🖇sponsor]: https://github.com/sponsors/pboling
 [🖇polar-img]: https://img.shields.io/badge/polar-donate-a51611.svg?style=flat
 [🖇polar]: https://polar.sh/pboling
-[🖇kofi-img]: https://img.shields.io/badge/ko--fi-✓-a51611.svg?style=flat
+[🖇kofi-img]: https://img.shields.io/badge/ko--fi-%E2%9C%93-a51611.svg?style=flat
 [🖇kofi]: https://ko-fi.com/O5O86SNP4
 [🖇patreon-img]: https://img.shields.io/badge/patreon-donate-a51611.svg?style=flat
 [🖇patreon]: https://patreon.com/galtzo
-[🖇buyme-small-img]: https://img.shields.io/badge/buy_me_a_coffee-✓-a51611.svg?style=flat
+[🖇buyme-small-img]: https://img.shields.io/badge/buy_me_a_coffee-%E2%9C%93-a51611.svg?style=flat
 [🖇buyme]: https://www.buymeacoffee.com/pboling
 [🖇paypal-img]: https://img.shields.io/badge/donate-paypal-a51611.svg?style=flat&logo=paypal
 [🖇paypal]: https://www.paypal.com/paypalme/peterboling

data/README.md

@@ -123,7 +123,7 @@ What it does:
   - If any fail, the script prints import links to help you create a mirror on that forge.
 
 <details>
-  <summary>Find this repo on other forges (Coming soon!)</summary>
+  <summary>Find this repo on other forges</summary>
 
 | Federated [DVCS][💎d-in-dvcs] Repository        | Status                                                                | Issues                    | PRs                      | Wiki                      | CI                       | Discussions                  |
 |-------------------------------------------------|-----------------------------------------------------------------------|---------------------------|--------------------------|---------------------------|--------------------------|------------------------------|
@@ -210,6 +210,19 @@ NOTE: Be prepared to track down certs for signed gems and add them the same way
 
 ## ⚙️ Configuration
 
+Note on executables vs Rake tasks
+- Executable scripts provided by this gem (exe/* and installed binstubs) work when the gem is installed as a system gem (gem install kettle-dev). They do not require the gem to be in your bundle to run.
+- The Rake tasks provided by this gem require kettle-dev to be declared as a development dependency in your Gemfile and loaded in your project's Rakefile. Ensure your Gemfile includes:
+  ```ruby
+  group :development do
+    gem "kettle-dev", require: false
+  end
+  ```
+  And your Rakefile loads the gem's tasks, e.g.:
+  ```ruby
+  require "kettle/dev"
+  ```
+
 ### RSpec
 
 This gem integrates tightly with [kettle-test](https://github.com/kettle-rb/kettle-test).
@@ -230,11 +243,16 @@ Then run the one-time project bootstrapper:
 
 ```console
 kettle-dev-setup
+# Or to accept all defaults:
+kettle-dev-setup --allowed=true --force
 ```
 
-After bootstrapping you may want to update the template.
+You'll be able to compare the changes with your diff tool, and certainly revert some of them.
 
-Invoke the rake task directly:
+For your protection:
+- it won't run if git doesn't start out porcelain clean.
+
+After bootstrapping, to update the template to the latest version from a new release of this gem, run:
 
 ```console
 bundle exec rake kettle:dev:install
@@ -310,6 +328,7 @@ Tip: When running a single spec file locally, you may want `K_SOUP_COV_MIN_HARD=
 
 GitHub API and CI helpers
 - GITHUB_TOKEN or GH_TOKEN: Token used by `ci:act` and release workflow checks to query GitHub Actions status at higher rate limits
+- GITLAB_TOKEN or GL_TOKEN: Token used by `ci:act` and CI monitor to query GitLab pipeline status
 
 Releasing and signing
 - SKIP_GEM_SIGNING: If set, skip gem signing during build/release
@@ -344,6 +363,28 @@ GitHub Actions local runner helper
 - `bundle exec rake ci:act` — interactive menu shows workflows from `.github/workflows` with live status and short codes (first 3 letters of file name). Type a number or short code.
 - Non-interactive: `bundle exec rake ci:act[loc]` (short code), or `bundle exec rake ci:act[locked_deps.yml]` (filename).
 
+Setup tokens for API status (GitHub and GitLab)
+- Purpose: ci:act displays the latest status for GitHub Actions runs and (when applicable) the latest GitLab pipeline for the current branch. Unauthenticated requests are rate-limited; private repositories require tokens. Provide tokens to get reliable status.
+- GitHub token (recommended: fine-grained):
+  - Where to create: https://github.com/settings/personal-access-tokens
+    - Fine-grained: “Tokens (fine-grained)” → Generate new token
+    - Classic (fallback): “Tokens (classic)” → Generate new token
+  - Minimum permissions:
+    - Fine-grained: Repository access: Read-only for the target repository (or your org); Permissions → Actions: Read
+    - Classic: For public repos, no scopes are strictly required but rate limits are very low; for private repos, include the repo scope
+  - Add to environment (.env.local via direnv):
+    - GITHUB_TOKEN=your_token_here  (or GH_TOKEN=…)
+- GitLab token:
+  - Where to create (gitlab.com): https://gitlab.com/-/user_settings/personal_access_tokens
+  - Minimum scope: read_api (sufficient to read pipelines)
+  - Add to environment (.env.local via direnv):
+    - GITLAB_TOKEN=your_token_here  (or GL_TOKEN=…)
+- Load environment:
+  - Save tokens in .env.local (never commit this file), then run: direnv allow
+- Verify:
+  - Run: bundle exec rake ci:act
+  - The header will include Repo/Upstream/HEAD; entries will show “Latest GHA …” and “Latest GL … pipeline” with emoji status. On failure to authenticate or rate-limit, you’ll see a brief error/result code.
+
 Project automation bootstrap
 - `bundle exec rake kettle:dev:install` — copies the library’s `.github` folder into your project and offers to install `.git-hooks` templates locally or globally.
 - `bundle exec rake kettle:dev:template` — runs only the templating step used by install; useful to re-apply updates to templates (.github workflows, .devcontainer, .qlty, modular Gemfiles, README, and friends) without the `install` task’s extra prompts.
@@ -372,8 +413,10 @@ Project automation bootstrap
 - This behavior is automatic for any future `*.example` files added to the templates.
 - Exception: `.env.local` is handled specially for safety. Regardless of whether the template provides `.env.local` or `.env.local.example`, the installer copies it to `.env.local.example` in your project, and will never create or overwrite `.env.local`.
 
-Releasing (maintainers)
-- `exe/kettle-release` — guided release helper that:
+### Releasing (maintainers)
+
+- Script: `exe/kettle-release` (run as `kettle-release`)
+- Purpose: guided release helper that:
   - Runs sanity checks (`bin/setup`, `bin/rake`), confirms version/changelog, optionally updates Appraisals, commits “🔖 Prepare release vX.Y.Z”.
   - Optionally runs your CI locally with `act` before any push:
     - Enable with env: `K_RELEASE_LOCAL_CI="true"` (run automatically) or `K_RELEASE_LOCAL_CI="ask"` (prompt [Y/n]).
@@ -381,35 +424,100 @@ Releasing (maintainers)
     - On failure, the release prep commit is soft-rolled-back (`git reset --soft HEAD^`) and the process aborts.
   - Ensures trunk sync and rebases feature as needed, pushes, monitors GitHub Actions with a progress bar, and merges feature to trunk on success.
   - Exports `SOURCE_DATE_EPOCH`, builds (optionally signed), creates gem checksums, and runs `bundle exec rake release` (prompts for signing key + RubyGems MFA OTP as needed).
-
-- start_step map (skip directly to a phase):
-  - 1: Ensure Bundler >= 2.7.0 and begin full flow
-  - 2: Version detection + sanity checks + prompt to confirm version.rb and CHANGELOG.md
-  - 3: Run bin/setup
-  - 4: Run bin/rake (default task)
-  - 5: Run appraisal:update when Appraisals exists (skip otherwise)
-  - 6: Verify git user.name/email and commit release prep "🔖 Prepare release vX.Y.Z"
-  - 7: Optionally run local CI with nektos/act before pushing (see K_RELEASE_LOCAL_CI, K_RELEASE_LOCAL_CI_WORKFLOW)
-  - 8: Ensure trunk is up-to-date and reconcile with GitHub remote if needed
-  - 9: Push current branch to configured remotes (or default), force-pushing on retry when needed
-  - 10: Monitor CI after push (GitHub Actions and/or GitLab pipelines); progress bar; aborts on failure
-  - 11: Merge feature branch into trunk and push
-  - 12: Checkout trunk and pull latest
-  - 13: Signing checks and guidance (abort when signing enabled but cert missing); respect SKIP_GEM_SIGNING
-  - 14: Build gem (honors SKIP_GEM_SIGNING via env prefix)
-  - 15: Generate and validate gem checksums (bin/gem_checksums)
-  - 16: Release via `bundle exec rake release` and validate checksums again
-  - 17: Create GitHub release from CHANGELOG when GITHUB_TOKEN present
-  - 18: Push git tags to remotes (to "all" remote only when present; otherwise to each remote)
-
-  Examples:
+- Options:
+  - start_step map (skip directly to a phase):
+    - 1: Ensure Bundler >= 2.7.0 and begin full flow
+    - 2: Version detection + sanity checks + prompt to confirm version.rb and CHANGELOG.md
+    - 3: Run bin/setup
+    - 4: Run bin/rake (default task)
+    - 5: Run appraisal:update when Appraisals exists (skip otherwise)
+    - 6: Verify git user.name/email and commit release prep "🔖 Prepare release vX.Y.Z"
+    - 7: Optionally run local CI with nektos/act before pushing (see K_RELEASE_LOCAL_CI, K_RELEASE_LOCAL_CI_WORKFLOW)
+    - 8: Ensure trunk is up-to-date and reconcile with GitHub remote if needed
+    - 9: Push current branch to configured remotes (or default), force-pushing on retry when needed
+    - 10: Monitor CI after push (GitHub Actions and/or GitLab pipelines); progress bar; aborts on failure
+    - 11: Merge feature branch into trunk and push
+    - 12: Checkout trunk and pull latest
+    - 13: Signing checks and guidance (abort when signing enabled but cert missing); respect SKIP_GEM_SIGNING
+    - 14: Build gem (honors SKIP_GEM_SIGNING via env prefix)
+    - 15: Generate and validate gem checksums (bin/gem_checksums)
+    - 16: Release via `bundle exec rake release` and validate checksums again
+    - 17: Create GitHub release from CHANGELOG when GITHUB_TOKEN present
+    - 18: Push git tags to remotes (to "all" remote only when present; otherwise to each remote)
+- Examples:
   - After intermittent CI failure, restart from monitoring: `bundle exec kettle-release start_step=10`
+- Tips:
+  - The commit message helper `exe/kettle-commit-msg` prefers project-local `.git-hooks` (then falls back to `~/.git-hooks`).
+  - The goalie file `commit-subjects-goalie.txt` controls when a footer is appended; customize `footer-template.erb.txt` as you like.
+
+### Changelog generator
 
-Tip: The commit message helper `exe/kettle-commit-msg` prefers project-local `.git-hooks` (then falls back to `~/.git-hooks`). The goalie file `commit-subjects-goalie.txt` controls when a footer is appended; customize `footer-template.erb.txt` as you like.
+- Script: `exe/kettle-changelog` (run as `kettle-changelog`)
+- Purpose: Generates a new CHANGELOG.md section for the current version read from `lib/**/version.rb`, moves notes from the Unreleased section, and updates comparison links.
+- Prerequisites:
+  - `coverage/coverage.json` present (generate with: `K_SOUP_COV_FORMATTERS="json" bin/rspec`).
+  - `bin/yard` available (Bundler-installed), to compute documentation coverage.
+- Usage:
+  - `kettle-changelog`
+- Behavior:
+  - Reads version from the unique `lib/**/version.rb` in the project.
+  - Moves entries from the `[Unreleased]` section into a new `[#.#.#] - YYYY-MM-DD` section.
+  - Prepends 4 lines with TAG, line coverage, branch coverage, and percent documented.
+  - Converts any GitLab-style compare links at the bottom to GitHub style, adds new tag/compare links for the new release and a temporary tag reference `[X.Y.Zt]`.
+
+### Pre-release checks
+
+- Script: `exe/kettle-pre-release` (run as `kettle-pre-release`)
+- Purpose: Run a suite of pre-release validations to catch avoidable mistakes (resumable by check number).
+- Usage:
+  - `kettle-pre-release [--check-num N]`
+  - Short option: `kettle-pre-release -cN`
+- Options:
+  - `--check-num N` Start from check number N (default: 1)
+- Checks:
+  - 1) Validate that all image URLs referenced by Markdown files resolve (HTTP HEAD)
+
+### Commit message helper (git hook)
+
+- Script: `exe/kettle-commit-msg` (run by git as `.git/hooks/commit-msg`)
+- Purpose: Append a standardized footer and optionally enforce branch naming rules when configured.
+- Usage:
+  - Git invokes this with the path to the commit message file: `kettle-commit-msg .git/COMMIT_EDITMSG`
+  - Install via `bundle exec rake kettle:dev:install` to copy hook templates into `.git-hooks` and wire them up.
+- Behavior:
+  - When `GIT_HOOK_BRANCH_VALIDATE=jira`, validates the current branch matches the pattern: `^(hotfix|bug|feature|candy)/[0-9]{8,}-…`.
+    - If it matches and the commit message lacks the numeric ID, appends `[<type>][<id>]`.
+  - Always invokes `Kettle::Dev::GitCommitFooter.render` to potentially append a footer if allowed by the goalie.
+  - Prefers project-local `.git-hooks` templates; falls back to `~/.git-hooks`.
+- Environment:
+  - `GIT_HOOK_BRANCH_VALIDATE` Branch rule (e.g., `jira`) or `false` to disable.
+  - `GIT_HOOK_FOOTER_APPEND` Enable footer auto-append when goalie allows (true/false).
+  - `GIT_HOOK_FOOTER_SENTINEL` Required marker to avoid duplicate appends when enabled.
+  - `GIT_HOOK_FOOTER_APPEND_DEBUG` Extra debug output in the footer template (true/false).
+
+### Project bootstrap installer
+
+- Script: `exe/kettle-dev-setup` (run as `kettle-dev-setup`)
+- Purpose: Bootstrap a host gem repository to use kettle-dev’s tooling without manual steps.
+- Usage:
+  - `kettle-dev-setup [options] [passthrough args]`
+- Options (mapped through to `rake kettle:dev:install`):
+  - `--allowed=VAL` Pass `allowed=VAL` to acknowledge prior direnv allow, etc.
+  - `--force` Pass `force=true` to accept prompts non-interactively.
+  - `--hook_templates=VAL` Pass `hook_templates=VAL` to control git hook templating.
+  - `--only=VAL` Pass `only=VAL` to restrict install scope.
+  - `-h`, `--help` Show help.
+- Behavior:
+  - Verifies a clean git working tree, presence of a Gemfile and a gemspec.
+  - Syncs development dependencies from this gem’s example gemspec into the target gemspec (replacing or inserting `add_development_dependency` lines as needed).
+  - Ensures `bin/setup` exists (copies from gem if missing) and replaces/creates the project’s `Rakefile` from `Rakefile.example`.
+  - Runs `bin/setup`, then `bundle exec bundle binstubs --all`.
+  - Stages and commits any bootstrap changes with message: `🎨 Template bootstrap by kettle-dev-setup v<version>`.
+  - Executes `bin/rake kettle:dev:install` with the parsed passthrough args.
 
 ### Open Collective README updater
 
-- Script: `exe/kettle-readme-backers`
+- Script: `exe/kettle-readme-backers` (run as `kettle-readme-backers`)
 - Purpose: Updates README sections for Open Collective backers (individuals) and sponsors (organizations) by fetching live data from your collective.
 - Tags updated in README.md (first match wins for backers):
   - The default tag prefix is `OPENCOLLECTIVE`, and it is configurable:
@@ -421,7 +529,7 @@ Tip: The commit message helper `exe/kettle-commit-msg` prefers project-local `.g
   - Sponsors (Organizations): `<!-- <TAG>-ORGANIZATIONS:START --> … <!-- <TAG>-ORGANIZATIONS:END -->`
 - Handle resolution:
   1. `OPENCOLLECTIVE_HANDLE` environment variable, if set
-  2. `opencollective.yml` in the project root (`collective: "kettle-rb"` by default in this repo)
+  2. `opencollective.yml` in the project root (e.g., `collective: "kettle-rb"` in this repo)
 - Usage:
   - `exe/kettle-readme-backers`
   - `OPENCOLLECTIVE_HANDLE=my-collective exe/kettle-readme-backers`
@@ -434,7 +542,9 @@ Tip: The commit message helper `exe/kettle-commit-msg` prefers project-local `.g
     - Or via .opencollective.yml: set `readme-backers-commit-subject: "💸 Thanks 🙏 to our new backers 🎒 and subscribers 📜"`.
     - Precedence: ENV overrides .opencollective.yml; if neither is set, a sensible default is used.
     - Note: When used with the provided `.git-hooks`, the subject should start with a gitmoji character (see [gitmoji][📌gitmoji]).
-- Tip: Run this locally before committing to keep your README current, or schedule it in CI to refresh periodically.
+- Tip:
+  - Run this locally before committing to keep your README current, or schedule it in CI to refresh periodically.
+  - It runs automatically on a once-a-week schedule by the .github/workflows/opencollective.yml workflow that is part of the kettle-dev template.
 
 ## 🦷 FLOSS Funding
 
@@ -640,11 +750,11 @@ Thanks for RTFM. ☺️
 [🖇sponsor]: https://github.com/sponsors/pboling
 [🖇polar-img]: https://img.shields.io/badge/polar-donate-a51611.svg?style=flat
 [🖇polar]: https://polar.sh/pboling
-[🖇kofi-img]: https://img.shields.io/badge/ko--fi-✓-a51611.svg?style=flat
+[🖇kofi-img]: https://img.shields.io/badge/ko--fi-%E2%9C%93-a51611.svg?style=flat
 [🖇kofi]: https://ko-fi.com/O5O86SNP4
 [🖇patreon-img]: https://img.shields.io/badge/patreon-donate-a51611.svg?style=flat
 [🖇patreon]: https://patreon.com/galtzo
-[🖇buyme-small-img]: https://img.shields.io/badge/buy_me_a_coffee-✓-a51611.svg?style=flat
+[🖇buyme-small-img]: https://img.shields.io/badge/buy_me_a_coffee-%E2%9C%93-a51611.svg?style=flat
 [🖇buyme-img]: https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20latte&emoji=&slug=pboling&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff
 [🖇buyme]: https://www.buymeacoffee.com/pboling
 [🖇paypal-img]: https://img.shields.io/badge/donate-paypal-a51611.svg?style=flat&logo=paypal
@@ -657,7 +767,7 @@ Thanks for RTFM. ☺️
 
 [✇bundle-group-pattern]: https://gist.github.com/pboling/4564780
 [⛳️gem-namespace]: https://github.com/kettle-rb/kettle-dev
-[⛳️namespace-img]: https://img.shields.io/badge/namespace-Kettle%3A%3ADev-3C2D2D.svg?style=square&logo=ruby&logoColor=white
+[⛳️namespace-img]: https://img.shields.io/badge/namespace-Kettle::Dev-3C2D2D.svg?style=square&logo=ruby&logoColor=white
 [⛳️gem-name]: https://rubygems.org/gems/kettle-dev
 [⛳️name-img]: https://img.shields.io/badge/name-kettle--dev-3C2D2D.svg?style=square&logo=rubygems&logoColor=red
 [⛳️tag-img]: https://img.shields.io/github/tag/kettle-rb/kettle-dev.svg
@@ -673,7 +783,7 @@ Thanks for RTFM. ☺️
 [💖💲crunchbase]: https://www.crunchbase.com/person/peter-boling
 [💖💲crunchbase-img]: https://img.shields.io/badge/peter--boling-purple?style=flat&logo=crunchbase
 [💖🐘ruby-mast]: https://ruby.social/@galtzo
-[💖🐘ruby-mast-img]: https://img.shields.io/mastodon/follow/109447111526622197?domain=https%3A%2F%2Fruby.social&style=flat&logo=mastodon&label=Ruby%20%40galtzo
+[💖🐘ruby-mast-img]: https://img.shields.io/mastodon/follow/109447111526622197?domain=https://ruby.social&style=flat&logo=mastodon&label=Ruby%20@galtzo
 [💖🦋bluesky]: https://bsky.app/profile/galtzo.com
 [💖🦋bluesky-img]: https://img.shields.io/badge/@galtzo.com-0285FF?style=flat&logo=bluesky&logoColor=white
 [💖🌳linktree]: https://linktr.ee/galtzo
@@ -793,9 +903,9 @@ Thanks for RTFM. ☺️
 [📗keep-changelog]: https://keepachangelog.com/en/1.0.0/
 [📗keep-changelog-img]: https://img.shields.io/badge/keep--a--changelog-1.0.0-34495e.svg?style=flat
 [📌gitmoji]:https://gitmoji.dev
-[📌gitmoji-img]:https://img.shields.io/badge/gitmoji_commits-%20😜%20😍-34495e.svg?style=flat-square
+[📌gitmoji-img]:https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.819-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-3.322-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year
@@ -809,7 +919,7 @@ Thanks for RTFM. ☺️
 [💎stone_checksums]: https://github.com/galtzo-floss/stone_checksums
 [💎SHA_checksums]: https://gitlab.com/kettle-rb/kettle-dev/-/tree/main/checksums
 [💎rlts]: https://github.com/rubocop-lts/rubocop-lts
-[💎rlts-img]: https://img.shields.io/badge/code_style_%26_linting-rubocop--lts-34495e.svg?plastic&logo=ruby&logoColor=white
+[💎rlts-img]: https://img.shields.io/badge/code_style_&_linting-rubocop--lts-34495e.svg?plastic&logo=ruby&logoColor=white
 [💎appraisal2]: https://github.com/appraisal-rb/appraisal2
 [💎appraisal2-img]: https://img.shields.io/badge/appraised_by-appraisal2-34495e.svg?plastic&logo=ruby&logoColor=white
 [💎d-in-dvcs]: https://railsbling.com/posts/dvcs/put_the_d_in_dvcs/

data/README.md.example

@@ -345,11 +345,11 @@ Thanks for RTFM. ☺️
 [🖇sponsor]: https://github.com/sponsors/pboling
 [🖇polar-img]: https://img.shields.io/badge/polar-donate-a51611.svg?style=flat
 [🖇polar]: https://polar.sh/pboling
-[🖇kofi-img]: https://img.shields.io/badge/ko--fi-✓-a51611.svg?style=flat
+[🖇kofi-img]: https://img.shields.io/badge/ko--fi-%E2%9C%93-a51611.svg?style=flat
 [🖇kofi]: https://ko-fi.com/O5O86SNP4
 [🖇patreon-img]: https://img.shields.io/badge/patreon-donate-a51611.svg?style=flat
 [🖇patreon]: https://patreon.com/galtzo
-[🖇buyme-small-img]: https://img.shields.io/badge/buy_me_a_coffee-✓-a51611.svg?style=flat
+[🖇buyme-small-img]: https://img.shields.io/badge/buy_me_a_coffee-%E2%9C%93-a51611.svg?style=flat
 [🖇buyme-img]: https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20latte&emoji=&slug=pboling&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff
 [🖇buyme]: https://www.buymeacoffee.com/pboling
 [🖇paypal-img]: https://img.shields.io/badge/donate-paypal-a51611.svg?style=flat&logo=paypal
@@ -362,7 +362,7 @@ Thanks for RTFM. ☺️
 
 [✇bundle-group-pattern]: https://gist.github.com/pboling/4564780
 [⛳️gem-namespace]: https://github.com/kettle-rb/kettle-dev
-[⛳️namespace-img]: https://img.shields.io/badge/namespace-Kettle%3A%3ADev-3C2D2D.svg?style=square&logo=ruby&logoColor=white
+[⛳️namespace-img]: https://img.shields.io/badge/namespace-Kettle::Dev-3C2D2D.svg?style=square&logo=ruby&logoColor=white
 [⛳️gem-name]: https://rubygems.org/gems/kettle-dev
 [⛳️name-img]: https://img.shields.io/badge/name-kettle--dev-3C2D2D.svg?style=square&logo=rubygems&logoColor=red
 [⛳️tag-img]: https://img.shields.io/github/tag/kettle-rb/kettle-dev.svg
@@ -378,7 +378,7 @@ Thanks for RTFM. ☺️
 [💖💲crunchbase]: https://www.crunchbase.com/person/peter-boling
 [💖💲crunchbase-img]: https://img.shields.io/badge/peter--boling-purple?style=flat&logo=crunchbase
 [💖🐘ruby-mast]: https://ruby.social/@galtzo
-[💖🐘ruby-mast-img]: https://img.shields.io/mastodon/follow/109447111526622197?domain=https%3A%2F%2Fruby.social&style=flat&logo=mastodon&label=Ruby%20%40galtzo
+[💖🐘ruby-mast-img]: https://img.shields.io/mastodon/follow/109447111526622197?domain=https://ruby.social&style=flat&logo=mastodon&label=Ruby%20@galtzo
 [💖🦋bluesky]: https://bsky.app/profile/galtzo.com
 [💖🦋bluesky-img]: https://img.shields.io/badge/@galtzo.com-0285FF?style=flat&logo=bluesky&logoColor=white
 [💖🌳linktree]: https://linktr.ee/galtzo
@@ -503,9 +503,9 @@ Thanks for RTFM. ☺️
 [📗keep-changelog]: https://keepachangelog.com/en/1.0.0/
 [📗keep-changelog-img]: https://img.shields.io/badge/keep--a--changelog-1.0.0-34495e.svg?style=flat
 [📌gitmoji]:https://gitmoji.dev
-[📌gitmoji-img]:https://img.shields.io/badge/gitmoji_commits-%20😜%20😍-34495e.svg?style=flat-square
+[📌gitmoji-img]:https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.819-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-3.322-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year
@@ -519,7 +519,7 @@ Thanks for RTFM. ☺️
 [💎stone_checksums]: https://github.com/galtzo-floss/stone_checksums
 [💎SHA_checksums]: https://gitlab.com/kettle-rb/kettle-dev/-/tree/main/checksums
 [💎rlts]: https://github.com/rubocop-lts/rubocop-lts
-[💎rlts-img]: https://img.shields.io/badge/code_style_%26_linting-rubocop--lts-34495e.svg?plastic&logo=ruby&logoColor=white
+[💎rlts-img]: https://img.shields.io/badge/code_style_&_linting-rubocop--lts-34495e.svg?plastic&logo=ruby&logoColor=white
 [💎appraisal2]: https://github.com/appraisal-rb/appraisal2
 [💎appraisal2-img]: https://img.shields.io/badge/appraised_by-appraisal2-34495e.svg?plastic&logo=ruby&logoColor=white
 [💎d-in-dvcs]: https://railsbling.com/posts/dvcs/put_the_d_in_dvcs/

data/Rakefile.example

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# kettle-dev Rakefile v1.1.4 - 2025-09-02
+# kettle-dev Rakefile v1.1.5 - 2025-09-05
 # Ruby 2.3 (Safe Navigation) or higher required
 #
 # MIT License (see License.txt)

data/exe/kettle-changelog

@@ -21,8 +21,13 @@
 
 $stdout.sync = true
 
-# Depending library or project must be using bundler
-require "bundler/setup"
+# Do not rely on Bundler; allow running in repos that do not depend on kettle-dev
+# Ensure RubyGems is available for 'require' lookups
+begin
+  require "rubygems"
+rescue LoadError
+  # Older Rubies always have rubygems; continue anyway
+end
 
 script_basename = File.basename(__FILE__)