From 25d6af2e9321cff208a7c6df5b3911ebd385e0f8 Mon Sep 17 00:00:00 2001
From: Matt Perpick <matt@braintrustdata.com>
Date: Sat, 25 Oct 2025 15:48:43 -0400
Subject: [PATCH 1/8] Setup Yard docs.

---
 .gitignore         |  2 ++
 .yardopts          | 12 ++++++++++++
 Gemfile.lock       |  5 +++++
 README.md          |  1 +
 Rakefile           |  7 +++++++
 braintrust.gemspec |  2 ++
 6 files changed, 29 insertions(+)
 create mode 100644 .yardopts

diff --git a/.gitignore b/.gitignore
index 54a06cbf..1a729ef6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,6 +2,8 @@
 *.rbc
 /.config
 /coverage/
+/doc/
+/.yardoc
 /InstalledFiles
 /pkg/
 /spec/reports/
diff --git a/.yardopts b/.yardopts
new file mode 100644
index 00000000..68cc00c0
--- /dev/null
+++ b/.yardopts
@@ -0,0 +1,12 @@
+--markup markdown
+--markup-provider kramdown
+--output-dir doc
+--readme README.md
+--title "Braintrust Ruby SDK Documentation"
+--protected
+--no-private
+--hide-warnings
+lib/**/*.rb
+-
+README.md
+CONTRIBUTING.md
diff --git a/Gemfile.lock b/Gemfile.lock
index a11a48e1..724f93c6 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -37,6 +37,8 @@ GEM
       google-protobuf (~> 4.26)
     hashdiff (1.2.1)
     json (2.15.1)
+    kramdown (2.5.1)
+      rexml (>= 3.3.9)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     minitest (5.26.0)
@@ -123,6 +125,7 @@ GEM
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.37)
 
 PLATFORMS
   arm64-darwin-23
@@ -134,6 +137,7 @@ PLATFORMS
 DEPENDENCIES
   appraisal (~> 2.5)
   braintrust!
+  kramdown (~> 2.0)
   minitest (~> 5.0)
   minitest-reporters (~> 1.6)
   rake (~> 13.0)
@@ -141,6 +145,7 @@ DEPENDENCIES
   standard (~> 1.0)
   vcr (~> 6.0)
   webmock (~> 3.0)
+  yard (~> 0.9)
 
 BUNDLED WITH
    2.4.19
diff --git a/README.md b/README.md
index 99f63635..5ac5ed0a 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
 # Braintrust Ruby SDK
 
 [![Gem Version](https://badge.fury.io/rb/braintrust.svg)](https://badge.fury.io/rb/braintrust)
+[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://rubydoc.info/gems/braintrust)
 ![Beta](https://img.shields.io/badge/status-beta-yellow)
 
 ## Overview
diff --git a/Rakefile b/Rakefile
index 654caaae..5e279eef 100644
--- a/Rakefile
+++ b/Rakefile
@@ -23,6 +23,8 @@ desc "Remove Ruby build artifacts"
 task :clean do
   FileUtils.rm_rf("pkg")
   FileUtils.rm_rf("coverage")
+  FileUtils.rm_rf("doc")
+  FileUtils.rm_rf(".yardoc")
   FileUtils.rm_rf("tmp")
   FileUtils.rm_f(Dir.glob("*.gem"))
   FileUtils.rm_f("changelog.md")
@@ -65,6 +67,11 @@ task build: [:clean] do
   sh "gem build braintrust.gemspec"
 end
 
+desc "Generate YARD documentation"
+task :yard do
+  sh "bundle exec yard doc"
+end
+
 desc "Run tests and open coverage report"
 task coverage: :test do
   coverage_file = "coverage/index.html"
diff --git a/braintrust.gemspec b/braintrust.gemspec
index b7ab8bf2..b46e9048 100644
--- a/braintrust.gemspec
+++ b/braintrust.gemspec
@@ -46,4 +46,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "vcr", "~> 6.0"
   spec.add_development_dependency "webmock", "~> 3.0"
   spec.add_development_dependency "appraisal", "~> 2.5"
+  spec.add_development_dependency "yard", "~> 0.9"
+  spec.add_development_dependency "kramdown", "~> 2.0"
 end

From d7252ff1516a1ddf96c093f013d7c3af7670b11d Mon Sep 17 00:00:00 2001
From: Matt Perpick <matt@braintrustdata.com>
Date: Sat, 25 Oct 2025 15:50:02 -0400
Subject: [PATCH 2/8] clean chnagelog

---
 braintrust.gemspec | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/braintrust.gemspec b/braintrust.gemspec
index b46e9048..e4622f95 100644
--- a/braintrust.gemspec
+++ b/braintrust.gemspec
@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.email = ["info@braintrust.dev"]
 
   spec.summary = "Ruby SDK for Braintrust"
-  spec.description = "OpenTelemetry-based SDK for Braintrust with tracing, OpenAI integration, and evals"
+  spec.description = "Braintrust Ruby SDK for evals, tracing and more. "
   spec.homepage = "https://github.com/braintrustdata/braintrust-sdk-ruby"
   spec.license = "Apache-2.0"
   spec.required_ruby_version = ">= 3.2.0"

From b3ca44d529c5971661b7a0e75b6830bd28cfaf17 Mon Sep 17 00:00:00 2001
From: Matt Perpick <matt@braintrustdata.com>
Date: Sat, 25 Oct 2025 15:52:22 -0400
Subject: [PATCH 3/8] fix changelog link

---
 braintrust.gemspec | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/braintrust.gemspec b/braintrust.gemspec
index e4622f95..2650e8f8 100644
--- a/braintrust.gemspec
+++ b/braintrust.gemspec
@@ -16,7 +16,7 @@ Gem::Specification.new do |spec|
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
-  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/releases"
 
   # Specify which files should be added to the gem when it is released.
   spec.files = Dir.glob(%w[

From 5ad1196bd06f599a2822f52e2b0c056ba3ec50c3 Mon Sep 17 00:00:00 2001
From: Matt Perpick <matt@braintrustdata.com>
Date: Sat, 25 Oct 2025 16:14:47 -0400
Subject: [PATCH 4/8] clean release notes

---
 scripts/generate-release-notes.sh | 40 ++++++++++++++++++++++---------
 1 file changed, 29 insertions(+), 11 deletions(-)

diff --git a/scripts/generate-release-notes.sh b/scripts/generate-release-notes.sh
index 05fcaa1e..9605fe82 100755
--- a/scripts/generate-release-notes.sh
+++ b/scripts/generate-release-notes.sh
@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 # Script to generate release notes for GitHub Release
-# Compares current tag with previous tag
+# Shows commits since the previous release
+# Expected tag format: v0.0.1, v0.0.2, etc. (with 'v' prefix)
 
 set -euo pipefail
 
@@ -8,24 +9,41 @@ set -euo pipefail
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$REPO_ROOT"
 
-# Get current tag
-CURRENT_TAG="${GITHUB_REF_NAME:-$(git describe --tags --exact-match 2>/dev/null || echo "")}"
+# Get current tag (expects format: v0.0.1)
+# Accepts optional argument: ./generate-release-notes.sh v0.0.2
+# Defaults to HEAD (unreleased changes) for local development
+CURRENT_TAG="${1:-${GITHUB_REF_NAME:-$(git describe --tags --exact-match 2>/dev/null || echo "HEAD")}}"
 
-if [ -z "$CURRENT_TAG" ]; then
-  echo "Error: No tag found. This script should be run on a tagged commit."
+# Special case: HEAD shows what would be in next release
+if [ "$CURRENT_TAG" = "HEAD" ]; then
+  PREVIOUS_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+  if [ -z "$PREVIOUS_TAG" ]; then
+    echo "Error: No previous tag found"
+    exit 1
+  fi
+
+  echo "## Changelog"
+  echo ""
+  git log "${PREVIOUS_TAG}..HEAD" --pretty=format:"- %s (%h)" --no-merges
+  exit 0
+fi
+
+# Validate tag format (must start with 'v' and contain version number)
+if [[ ! "$CURRENT_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+ ]]; then
+  echo "Error: Invalid tag format. Expected format: v0.0.1"
+  echo "Got: $CURRENT_TAG"
   exit 1
 fi
 
 # Get previous tag
 PREVIOUS_TAG=$(git describe --tags --abbrev=0 "${CURRENT_TAG}^" 2>/dev/null || echo "")
 
-# Generate release notes
+# Generate release notes with consistent header
+echo "## Changelog"
+echo ""
+
 if [ -n "$PREVIOUS_TAG" ]; then
-  echo "## Changes since $PREVIOUS_TAG"
-  echo ""
   git log "${PREVIOUS_TAG}..${CURRENT_TAG}" --pretty=format:"- %s (%h)" --no-merges
 else
-  echo "## Initial Release"
-  echo ""
-  echo "First release of the Braintrust Ruby SDK"
+  echo "Initial beta version of the Ruby SDK."
 fi

From 2a89815f060d84a005e557e308764a5dd8fa67fa Mon Sep 17 00:00:00 2001
From: Matt Perpick <matt@braintrustdata.com>
Date: Sat, 25 Oct 2025 16:18:58 -0400
Subject: [PATCH 5/8] release notes

---
 scripts/generate-release-notes.sh | 47 +++++++++++++------------------
 1 file changed, 19 insertions(+), 28 deletions(-)

diff --git a/scripts/generate-release-notes.sh b/scripts/generate-release-notes.sh
index 9605fe82..24e62fad 100755
--- a/scripts/generate-release-notes.sh
+++ b/scripts/generate-release-notes.sh
@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Script to generate release notes for GitHub Release
-# Shows commits since the previous release
+# Shows commits between two points in history
 # Expected tag format: v0.0.1, v0.0.2, etc. (with 'v' prefix)
 
 set -euo pipefail
@@ -9,41 +9,32 @@ set -euo pipefail
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$REPO_ROOT"
 
-# Get current tag (expects format: v0.0.1)
-# Accepts optional argument: ./generate-release-notes.sh v0.0.2
-# Defaults to HEAD (unreleased changes) for local development
-CURRENT_TAG="${1:-${GITHUB_REF_NAME:-$(git describe --tags --exact-match 2>/dev/null || echo "HEAD")}}"
+# Determine END commit (what to release)
+# Priority: arg > GITHUB_REF_NAME > current tag > HEAD
+END="${1:-${GITHUB_REF_NAME:-$(git describe --tags --exact-match 2>/dev/null || echo "HEAD")}}"
 
-# Special case: HEAD shows what would be in next release
-if [ "$CURRENT_TAG" = "HEAD" ]; then
-  PREVIOUS_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
-  if [ -z "$PREVIOUS_TAG" ]; then
-    echo "Error: No previous tag found"
-    exit 1
-  fi
-
-  echo "## Changelog"
-  echo ""
-  git log "${PREVIOUS_TAG}..HEAD" --pretty=format:"- %s (%h)" --no-merges
-  exit 0
-fi
-
-# Validate tag format (must start with 'v' and contain version number)
-if [[ ! "$CURRENT_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+ ]]; then
-  echo "Error: Invalid tag format. Expected format: v0.0.1"
-  echo "Got: $CURRENT_TAG"
+# Validate tag format if not HEAD
+if [ "$END" != "HEAD" ] && [[ ! "$END" =~ ^v[0-9]+\.[0-9]+\.[0-9]+ ]]; then
+  echo "Error: Invalid tag format. Expected format: v0.0.1 or HEAD"
+  echo "Got: $END"
   exit 1
 fi
 
-# Get previous tag
-PREVIOUS_TAG=$(git describe --tags --abbrev=0 "${CURRENT_TAG}^" 2>/dev/null || echo "")
+# Determine START commit (previous release)
+if [ "$END" = "HEAD" ]; then
+  # Local: show unreleased changes since last tag
+  START=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+else
+  # CI: show changes since previous tag
+  START=$(git describe --tags --abbrev=0 "${END}^" 2>/dev/null || echo "")
+fi
 
-# Generate release notes with consistent header
+# Generate changelog
 echo "## Changelog"
 echo ""
 
-if [ -n "$PREVIOUS_TAG" ]; then
-  git log "${PREVIOUS_TAG}..${CURRENT_TAG}" --pretty=format:"- %s (%h)" --no-merges
+if [ -n "$START" ]; then
+  git log "${START}..${END}" --pretty=format:"- %s (%h)" --no-merges
 else
   echo "Initial beta version of the Ruby SDK."
 fi

From 5c366393f9be0f6a0a597423c4fade37ed7791d0 Mon Sep 17 00:00:00 2001
From: Matt Perpick <matt@braintrustdata.com>
Date: Sat, 25 Oct 2025 16:19:41 -0400
Subject: [PATCH 6/8] bump version

---
 lib/braintrust/version.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/braintrust/version.rb b/lib/braintrust/version.rb
index 73c4bae7..45be2d73 100644
--- a/lib/braintrust/version.rb
+++ b/lib/braintrust/version.rb
@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Braintrust
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

From 84a9c6ffd8f6e53f6da980dad10c524157a802a8 Mon Sep 17 00:00:00 2001
From: Matt Perpick <matt@braintrustdata.com>
Date: Sat, 25 Oct 2025 16:32:31 -0400
Subject: [PATCH 7/8] bump genfile

---
 Gemfile.lock |  2 +-
 mise.toml    | 15 ++++++++++++++-
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/Gemfile.lock b/Gemfile.lock
index 724f93c6..f3abfc9c 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    braintrust (0.0.1)
+    braintrust (0.0.2)
       openssl (~> 3.3.1)
       opentelemetry-exporter-otlp (~> 0.28)
       opentelemetry-sdk (~> 1.0)
diff --git a/mise.toml b/mise.toml
index 1e4dadbe..782d84b3 100644
--- a/mise.toml
+++ b/mise.toml
@@ -24,7 +24,20 @@ run = "watchexec --exts rb --watch lib --watch test --restart --clear -- rake te
 
 [tasks.precommit]
 description = "Run linter before commit (full CI runs on push)"
-run = "bundle exec rake lint"
+run = """
+bundle check || bundle install --quiet
+if ! git diff --quiet --exit-code Gemfile.lock; then
+  echo ""
+  echo "Gemfile.lock is out of sync with gemspec"
+  echo ""
+  echo "Changes detected:"
+  git diff Gemfile.lock | head -20
+  echo ""
+  echo "Fix: git add Gemfile.lock"
+  exit 1
+fi
+bundle exec rake lint
+"""
 
 [hooks]
 postinstall = """

From 50322f2fd7531685c86f9e386d5e7ff7bcbbc6e0 Mon Sep 17 00:00:00 2001
From: Matt Perpick <matt@braintrustdata.com>
Date: Sat, 25 Oct 2025 16:33:35 -0400
Subject: [PATCH 8/8] precommit

---
 mise.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mise.toml b/mise.toml
index 782d84b3..f35360f2 100644
--- a/mise.toml
+++ b/mise.toml
@@ -25,7 +25,7 @@ run = "watchexec --exts rb --watch lib --watch test --restart --clear -- rake te
 [tasks.precommit]
 description = "Run linter before commit (full CI runs on push)"
 run = """
-bundle check || bundle install --quiet
+bundle check > /dev/null 2>&1 || bundle install --quiet
 if ! git diff --quiet --exit-code Gemfile.lock; then
   echo ""
   echo "Gemfile.lock is out of sync with gemspec"