chore(release): 0.6.0 gem-release-ready

[ajmarkow]

Releases 0.6.0.

Why minor, not patch

This narrows supported Ruby to 3.2 and newer. The runtime dependencies already required it, so the previous >= 3.1.0 constraint let the gem install on a Ruby it could not actually run on.

Semver exempts 0.x from its rules, so nothing forces this. But the 0.x convention puts compatibility changes in MINOR, and it means anyone pinned at ~> 0.5.3 opts in deliberately rather than being held back without knowing why.

Nobody breaks either way. RubyGems enforces required_ruby_version while resolving, so Ruby 3.1 users stay on 0.5.3 with a working install.

Contents

• lib/snippet_cli/version.rb → 0.6.0
• CHANGELOG.md — new, covering 0.6.0 back to 0.5.0. The gemspec already advertised a changelog_uri pointing at a file that did not exist, so that link was dead on RubyGems.
• docs/updating-version.md — corrects the semver section of the runbook merged in docs: add an agent release runbook and make AGENTS.md canonical #3. It claimed raising required_ruby_version stops affected users installing at all, which overstates it; they keep a working install and silently stop receiving updates. Also notes the 0.x exemption.

The Nix pins stay on 0.5.3

nix/gemset.nix and nix/Gemfile.lock are deliberately untouched. They pin the published gem, and 0.6.0 does not exist on RubyGems until publish runs. update-gemset repins them afterwards and opens its own PR.

nix/Gemfile needs no change either — its ~> 0.5 constraint is >= 0.5, < 1.0, so 0.6.0 sits inside it. (A 1.0.0 release would fall outside, and update-gemset is built to fail loudly rather than repin the wrong version.)

Expected CI behaviour

nix pins match version.rb should pass with a notice, not fail:

::notice::version.rb is 0.6.0, which RubyGems has not indexed yet.
Release in flight -- update-gemset repins after publish.

This is the release-in-flight path, and this PR is its first real exercise in CI.

After merge

publish pushes the gem, tags v0.6.0, and creates a release. Then update-gemset waits for RubyGems to index it, regenerates the pins, and opens chore/repin-gemset-v0.6.0 with auto-merge. This is also the first live use of GEMSET_BOT_TOKEN; if its scopes are wrong the job fails at checkout, leaving the gem published but unpinned — recoverable by rerunning that job.

🤖 Generated with Claude Code

[ajmarkow]

Also folded in: the README's system-config section documented only inputs.snippet_cli.packages.${pkgs.system}.default, never the overlay that #2 added. Now shows the overlay as the simplest path, with the direct-package form kept as the fallback. Verified pkgs.snippet_cli resolves once the overlay is applied.