chore: pin the docs toolchain with a Gemfile so jazzy builds reproducibly

[abelonogov-ld]

Summary

build-docs has been failing on every PR since 2026-08-20 — see for example this run — with:

mustache/settings.rb:47:in 'setup_path': undefined method 'map' for an instance of Pathname (NoMethodError)

The cause is dependency resolution, not anything in our source. .github/actions/build-docs ran a bare gem install jazzy with no Gemfile or lockfile, so each run resolved afresh. mustache 1.1.3, published 2026-08-20, reworked template_path=:

# 1.1.2 — accepts a single path, including a Pathname
def self.template_path=(path)
  @template_path = File.expand_path(path)
end

# 1.1.3 — expects a String or an Array
def self.setup_path(path)
  path = path.split(File::PATH_SEPARATOR) if path.is_a? String
  path.map { |p| File.expand_path(p) }
end

jazzy's theme_directory= passes a Pathname, which is neither, so .map raises. jazzy 0.15.4 permits mustache ~> 1.1, so runs started picking up 1.1.3. The failure happens inside Jazzy::Config#parse! while jazzy reads its own configuration, before it looks at any Swift, which is why it reproduces regardless of the branch's contents. It went unnoticed because the last CI run on v11 predates the mustache release.

This adds a Gemfile and a committed Gemfile.lock and switches the action to bundle install / bundle exec jazzy, so the toolchain is pinned rather than re-resolved per run. mustache is held below 1.1.3 with a comment explaining why, to be relaxed once jazzy accommodates the new signature.

Resolved versions: jazzy 0.15.4, mustache 1.1.2.

Test plan

• bundle lock resolves to mustache 1.1.2, confirmed against the lockfile
• Verified directly from the 1.1.2 and 1.1.3 gem sources that 1.1.2's template_path= accepts a Pathname and 1.1.3's does not
• build-docs passes on this PR (2m07s), and the rest of the run is green

---

Note

Overview
Fixes failing build-docs CI by stopping bare gem install jazzy, which could pull mustache 1.1.3 and break jazzy when it passes a Pathname into template_path=.

Adds a Gemfile pinning jazzy 0.15.4 and mustache < 1.1.3 (with a short comment on the incompatibility). The build-docs composite action now runs bundle install and bundle exec jazzy -o docs. .gitignore ignores /Gemfile.lock, so resolution is driven by the Gemfile constraints rather than a tracked lockfile.

^{Reviewed by Cursor Bugbot for commit 36b1c4b. Bugbot is set up for automated code reviews on this repo. Configure here.}