ollama-client 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 908909c57f4d7067168bcdcecce27471ea2587d6452aecb68aca2c25a8547839
-  data.tar.gz: fcbf8ee83cba0f05bcae0892e103ae1201a7db1b045c25848caf0d8a71ca891d
+  metadata.gz: 9b126aae11a2fd7f0ff26e53e90e12222eb88e23fa6ecf622215c4a9317fe6ce
+  data.tar.gz: 2656544e1ce4bfa852dc687108bdde17084773c3a1e76c53ae9ed59d77604256
 SHA512:
-  metadata.gz: 67800e85b23a59fd9717ec76a2d27a591538d1813846213cb095d853d41547d6da3bbb10b8096a05b500bec66576a2e0f9268a5ad8738a9c0176b8f2051a99eb
-  data.tar.gz: 1bb186cb330c6fec601ed909af0fa9ef9bee786827edeb9195955ed25e7d0e8ab1d2eb81c302e47806cf304014ad847c207cc05f7b881392f936413419158714
+  metadata.gz: 5cbd78f768412b8e413e9222b4b0b2ef68e094280546742a0bd8191269072a6281ae4182d591e889ba3829c5b047b0e053c2410fa7734dc4cf1dfe320b527239
+  data.tar.gz: 2f1c2eafa75910646ed2300c8ad5ab312aefe56bb03d6e4797356e219543a57532058c2b2f3fc31b773caf0e7e0d26b3a71a6f9887b1a40955f5b818ffe6e227

data/docs/GEM_RELEASE_GUIDE.md

@@ -0,0 +1,794 @@
+# Automated Gem Release Guide
+
+Complete guide to setting up automated Ruby gem releases using GitHub Actions and git tags.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Prerequisites](#prerequisites)
+3. [Initial Setup](#initial-setup)
+4. [GitHub Actions Workflow](#github-actions-workflow)
+5. [RubyGems Authentication](#rubygems-authentication)
+6. [Release Process](#release-process)
+7. [Troubleshooting](#troubleshooting)
+8. [Best Practices](#best-practices)
+
+## Overview
+
+This guide shows how to automate gem releases so that:
+- **Pushing a git tag** (e.g., `v1.2.3`) triggers an automated release
+- **GitHub Actions** validates, builds, and publishes the gem
+- **No manual `gem push`** required
+
+### Benefits
+
+✅ **Consistent releases** - Same process every time
+✅ **Version validation** - Tag must match gem version
+✅ **CI/CD integration** - Tests run before release
+✅ **Security** - API keys stored in GitHub Secrets
+✅ **Audit trail** - All releases tracked in GitHub
+
+## Prerequisites
+
+### 1. RubyGems Account
+
+Create an account at https://rubygems.org if you don't have one.
+
+### 2. Gem Ownership
+
+You must own the gem name or it must be available:
+
+```bash
+# Check if name is available
+gem search ^your-gem-name$ --remote
+
+# If gem exists, check ownership
+gem owner your-gem-name
+
+# Request ownership (if gem is abandoned)
+# Visit: https://rubygems.org/gems/your-gem-name
+```
+
+### 3. Gem Structure
+
+Your gem should have:
+
+```
+your-gem/
+├── .github/
+│   └── workflows/
+│       └── release.yml       # ← We'll create this
+├── lib/
+│   └── your_gem/
+│       └── version.rb         # ← Must have VERSION constant
+├── your-gem.gemspec           # ← Gem specification
+├── Gemfile
+└── README.md
+```
+
+## Initial Setup
+
+### Step 1: Version File
+
+Create `lib/your_gem/version.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+module YourGem
+  VERSION = "0.1.0"
+end
+```
+
+### Step 2: Gemspec File
+
+Create `your-gem.gemspec`:
+
+```ruby
+# frozen_string_literal: true
+
+require_relative "lib/your_gem/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "your-gem"
+  spec.version = YourGem::VERSION
+  spec.authors = ["Your Name"]
+  spec.email = ["your.email@example.com"]
+
+  spec.summary = "Brief description"
+  spec.description = "Longer description"
+  spec.homepage = "https://github.com/yourusername/your-gem"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released
+  spec.files = Dir.glob(%w[
+    lib/**/*.rb
+    lib/**/*.json
+    sig/**/*.rbs
+    *.md
+    LICENSE.txt
+  ]).reject { |f| File.directory?(f) }
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Dependencies
+  # spec.add_dependency "example-gem", "~> 1.0"
+
+  # Development dependencies
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rubocop", "~> 1.21"
+end
+```
+
+### Step 3: Test Local Build
+
+```bash
+# Build the gem locally
+gem build your-gem.gemspec
+
+# Test installation
+gem install ./your-gem-0.1.0.gem
+
+# Clean up
+rm your-gem-0.1.0.gem
+```
+
+## GitHub Actions Workflow
+
+### Create Workflow File
+
+Create `.github/workflows/release.yml`:
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3.4"  # Use your Ruby version
+          bundler-cache: true
+
+      - name: Validate tag matches gem version
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF#refs/tags/}"
+          tag_version="${tag#v}"
+          gem_version=$(ruby -e "require_relative 'lib/your_gem/version'; puts YourGem::VERSION")
+          if [ "$tag_version" != "$gem_version" ]; then
+            echo "❌ Tag version ($tag_version) does not match gem version ($gem_version)"
+            exit 1
+          fi
+          echo "✅ Tag v$tag_version matches gem version $gem_version"
+
+      - name: Build gem
+        run: gem build your-gem.gemspec
+
+      - name: Publish gem
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+        run: |
+          set -euo pipefail
+          gem_version=$(ruby -e "require_relative 'lib/your_gem/version'; puts YourGem::VERSION")
+          gem_file="your-gem-${gem_version}.gem"
+          if [ ! -f "$gem_file" ]; then
+            echo "❌ Gem file not found: $gem_file"
+            exit 1
+          fi
+          echo "📦 Publishing $gem_file to RubyGems..."
+          gem push "$gem_file"
+          echo "✅ Published successfully!"
+```
+
+**Important:** Replace:
+- `your_gem` with your gem's module name
+- `YourGem` with your module constant
+- `your-gem` with your gem's name
+
+### Optional: Add Testing Before Release
+
+Add a test job that runs before release:
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  # Run tests first
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3.4"
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rake spec
+      - name: Run RuboCop
+        run: bundle exec rubocop
+
+  # Release only if tests pass
+  release:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      # ... (release steps as above)
+```
+
+## RubyGems Authentication
+
+### Step 1: Get RubyGems API Key
+
+1. **Login to RubyGems:**
+   - Visit: https://rubygems.org/sign_in
+
+2. **Create API Key:**
+   - Go to: https://rubygems.org/profile/edit
+   - Scroll to "API Keys" section
+   - Click **"New API Key"**
+
+3. **Configure Key:**
+   - **Name:** `GitHub Actions - your-gem` (descriptive name)
+   - **Scopes:** Select **"Push rubygems"** only (principle of least privilege)
+   - Click **"Create"**
+
+4. **Copy Key:**
+   - Copy the generated key (you won't see it again!)
+   - Format: `rubygems_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+### Step 2: Add to GitHub Secrets
+
+1. **Navigate to Secrets:**
+   - Go to your GitHub repo
+   - Click **Settings** → **Secrets and variables** → **Actions**
+   - Or visit: `https://github.com/USERNAME/REPO/settings/secrets/actions`
+
+2. **Create Secret:**
+   - Click **"New repository secret"**
+   - **Name:** `RUBYGEMS_API_KEY` (must match workflow file)
+   - **Value:** Paste your RubyGems API key
+   - Click **"Add secret"**
+
+3. **Verify:**
+   - You should see `RUBYGEMS_API_KEY` in the list
+   - The value will be hidden (shows as `***`)
+
+### Step 3: Test Authentication (Optional)
+
+Test locally before using in CI:
+
+```bash
+# Set up credentials file
+mkdir -p ~/.gem
+echo "---
+:rubygems_api_key: your_api_key_here" > ~/.gem/credentials
+chmod 600 ~/.gem/credentials
+
+# Build and push manually to test
+gem build your-gem.gemspec
+gem push your-gem-0.1.0.gem
+
+# Clean up
+rm your-gem-0.1.0.gem
+```
+
+## Release Process
+
+### Standard Release Workflow
+
+#### 1. Update Version
+
+Edit `lib/your_gem/version.rb`:
+
+```ruby
+module YourGem
+  VERSION = "1.2.3"  # Bump version
+end
+```
+
+#### 2. Update Changelog
+
+Edit `CHANGELOG.md`:
+
+```markdown
+## [1.2.3] - 2026-01-17
+
+### Added
+- New feature X
+- New feature Y
+
+### Fixed
+- Bug fix A
+- Bug fix B
+
+### Changed
+- Improvement C
+```
+
+#### 3. Commit Changes
+
+```bash
+git add lib/your_gem/version.rb CHANGELOG.md
+git commit -m "Bump version to 1.2.3"
+git push origin main
+```
+
+#### 4. Create and Push Tag
+
+**Option A: Annotated Tag (Recommended)**
+
+```bash
+# Create annotated tag with message
+git tag -a v1.2.3 -m "Release v1.2.3
+
+- New feature X
+- Bug fix A
+- Improvement C"
+
+# Push the tag
+git push origin v1.2.3
+```
+
+**Option B: Lightweight Tag**
+
+```bash
+# Create simple tag
+git tag v1.2.3
+
+# Push it
+git push origin v1.2.3
+```
+
+#### 5. Monitor Release
+
+1. **Check GitHub Actions:**
+   - Go to: `https://github.com/USERNAME/REPO/actions`
+   - Watch the "Release" workflow run
+   - Should show: ✅ Validate → ✅ Build → ✅ Publish
+
+2. **Verify on RubyGems:**
+   - Visit: `https://rubygems.org/gems/your-gem`
+   - Confirm version 1.2.3 is published
+   - Check download stats
+
+3. **Test Installation:**
+   ```bash
+   gem install your-gem
+   # Or with version
+   gem install your-gem -v 1.2.3
+   ```
+
+### Quick Release Script
+
+Create `bin/release.sh`:
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+# Usage: ./bin/release.sh 1.2.3
+
+VERSION=$1
+TAG="v${VERSION}"
+
+echo "🚀 Releasing version ${VERSION}"
+
+# Verify version in version.rb matches
+CURRENT_VERSION=$(ruby -e "require_relative 'lib/your_gem/version'; puts YourGem::VERSION")
+if [ "$CURRENT_VERSION" != "$VERSION" ]; then
+  echo "❌ Version mismatch!"
+  echo "   lib/your_gem/version.rb: $CURRENT_VERSION"
+  echo "   Requested: $VERSION"
+  exit 1
+fi
+
+# Verify clean working directory
+if [ -n "$(git status --porcelain)" ]; then
+  echo "❌ Working directory not clean. Commit or stash changes first."
+  exit 1
+fi
+
+# Verify on main branch
+BRANCH=$(git branch --show-current)
+if [ "$BRANCH" != "main" ]; then
+  echo "⚠️  Not on main branch (currently on: $BRANCH)"
+  read -p "Continue anyway? [y/N] " -n 1 -r
+  echo
+  if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+    exit 1
+  fi
+fi
+
+# Create and push tag
+echo "📝 Creating tag $TAG"
+git tag -a "$TAG" -m "Release $TAG"
+
+echo "⬆️  Pushing tag to origin"
+git push origin "$TAG"
+
+echo "✅ Tag pushed! GitHub Actions will publish the gem."
+echo "📊 Monitor: https://github.com/USERNAME/REPO/actions"
+echo "📦 Once published: https://rubygems.org/gems/your-gem"
+```
+
+Make it executable:
+
+```bash
+chmod +x bin/release.sh
+```
+
+Use it:
+
+```bash
+# Update version in lib/your_gem/version.rb first
+# Update CHANGELOG.md
+# Commit changes
+git add -A
+git commit -m "Bump version to 1.2.3"
+git push
+
+# Run release script
+./bin/release.sh 1.2.3
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. "Access Denied" Error
+
+```
+Pushing gem to https://rubygems.org...
+Access Denied. Please sign up for an account
+```
+
+**Solution:**
+- Verify `RUBYGEMS_API_KEY` secret is set in GitHub
+- Check API key has "Push rubygems" scope
+- Ensure you own the gem name
+
+#### 2. "Gem name already taken"
+
+```
+There was a problem saving your gem: Name 'your-gem' is already taken
+```
+
+**Solution:**
+```bash
+# Check ownership
+gem owner your-gem
+
+# If you own it - check credentials
+# If you don't - choose a different name or request ownership
+```
+
+#### 3. Version Mismatch Error
+
+```
+❌ Tag version (1.2.3) does not match gem version (1.2.2)
+```
+
+**Solution:**
+```bash
+# Update version in lib/your_gem/version.rb
+# Delete incorrect tag
+git tag -d v1.2.3
+git push origin :refs/tags/v1.2.3
+
+# Create correct tag
+git tag -a v1.2.3 -m "Release v1.2.3"
+git push origin v1.2.3
+```
+
+#### 4. "Gem file not found"
+
+```
+❌ Gem file not found: your-gem-1.2.3.gem
+```
+
+**Solution:**
+- Check gemspec file is named correctly
+- Verify `spec.name` matches gem name
+- Test build locally: `gem build your-gem.gemspec`
+
+#### 5. Workflow Not Triggering
+
+**Check:**
+```bash
+# Verify tag format
+git tag -l  # Should show v1.2.3 format
+
+# Check workflow file location
+ls -la .github/workflows/release.yml
+
+# Verify tag trigger in workflow
+grep "tags:" .github/workflows/release.yml
+```
+
+### Debug Failed Releases
+
+#### View Workflow Logs
+
+1. Go to: `https://github.com/USERNAME/REPO/actions`
+2. Click on failed "Release" run
+3. Expand failed step to see error
+
+#### Re-run Failed Release
+
+```bash
+# Delete failed tag locally and remotely
+git tag -d v1.2.3
+git push origin :refs/tags/v1.2.3
+
+# Fix the issue
+
+# Re-create and push tag
+git tag -a v1.2.3 -m "Release v1.2.3"
+git push origin v1.2.3
+```
+
+#### Manual Release (Emergency)
+
+If GitHub Actions fails, release manually:
+
+```bash
+# Build gem
+gem build your-gem.gemspec
+
+# Push manually
+gem push your-gem-1.2.3.gem
+
+# Tag the commit after successful push
+git tag -a v1.2.3 -m "Release v1.2.3 (manual)"
+git push origin v1.2.3
+```
+
+## Best Practices
+
+### 1. Semantic Versioning
+
+Follow [SemVer](https://semver.org/):
+
+- **MAJOR** (1.0.0 → 2.0.0): Breaking changes
+- **MINOR** (1.0.0 → 1.1.0): New features, backward compatible
+- **PATCH** (1.0.0 → 1.0.1): Bug fixes, backward compatible
+
+### 2. Changelog Maintenance
+
+Keep `CHANGELOG.md` updated:
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+- Features in development
+
+## [1.2.3] - 2026-01-17
+
+### Added
+- New feature X
+
+### Fixed
+- Bug Y
+
+### Changed
+- Improvement Z
+
+## [1.2.2] - 2026-01-10
+...
+```
+
+### 3. Pre-Release Checklist
+
+Before tagging a release:
+
+- [ ] Version bumped in `lib/your_gem/version.rb`
+- [ ] `CHANGELOG.md` updated with changes
+- [ ] All tests passing locally (`bundle exec rake spec`)
+- [ ] RuboCop clean (`bundle exec rubocop`)
+- [ ] Changes committed and pushed to main
+- [ ] Local build works (`gem build your-gem.gemspec`)
+
+### 4. Git Tag Conventions
+
+Use consistent tag format:
+
+✅ **Good:**
+- `v1.2.3` (recommended)
+- `1.2.3` (acceptable)
+
+❌ **Bad:**
+- `version-1.2.3`
+- `release-1.2.3`
+- `v1.2.3-final`
+
+### 5. Security
+
+**API Key Security:**
+- ✅ Store in GitHub Secrets only
+- ✅ Use "Push rubygems" scope only
+- ✅ Rotate keys periodically (every 6-12 months)
+- ✅ Delete keys for deprecated projects
+- ❌ Never commit API keys to git
+- ❌ Never share API keys in chat/email
+
+**Gem File Security:**
+- Include only necessary files in gem
+- Use `spec.files` to explicitly list included files
+- Exclude sensitive files (`.env`, credentials, etc.)
+
+### 6. Release Notes
+
+Create GitHub releases for major versions:
+
+```bash
+# Using gh CLI
+gh release create v1.2.3 \
+  --title "v1.2.3 - Feature Name" \
+  --notes "## Highlights
+
+- New feature X
+- Bug fix Y
+
+See [CHANGELOG.md](CHANGELOG.md) for details."
+```
+
+### 7. Testing
+
+Always test gems before public release:
+
+```bash
+# Build gem
+gem build your-gem.gemspec
+
+# Install locally
+gem install ./your-gem-1.2.3.gem
+
+# Test in a sample project
+cd ~/tmp/test-project
+bundle init
+echo 'gem "your-gem", path: "/path/to/your-gem"' >> Gemfile
+bundle install
+
+# Test functionality
+ruby -e "require 'your_gem'; puts YourGem::VERSION"
+```
+
+## Example: Complete Release Flow
+
+Here's a complete example from start to finish:
+
+```bash
+# 1. Create new feature branch
+git checkout -b feature/add-cool-feature
+
+# 2. Implement feature
+# ... code changes ...
+
+# 3. Test locally
+bundle exec rspec
+bundle exec rubocop
+
+# 4. Commit and push
+git add -A
+git commit -m "Add cool feature"
+git push origin feature/add-cool-feature
+
+# 5. Create PR and merge to main
+gh pr create --title "Add cool feature"
+# ... review and merge ...
+
+# 6. Pull latest main
+git checkout main
+git pull origin main
+
+# 7. Bump version
+# Edit lib/your_gem/version.rb: VERSION = "1.3.0"
+# Edit CHANGELOG.md: Add [1.3.0] section
+
+# 8. Commit version bump
+git add lib/your_gem/version.rb CHANGELOG.md
+git commit -m "Bump version to 1.3.0"
+git push origin main
+
+# 9. Create and push tag
+git tag -a v1.3.0 -m "Release v1.3.0
+
+- Add cool feature
+- Fix minor bugs"
+git push origin v1.3.0
+
+# 10. Monitor GitHub Actions
+# Visit: https://github.com/USERNAME/REPO/actions
+# Watch Release workflow complete
+
+# 11. Verify on RubyGems
+# Visit: https://rubygems.org/gems/your-gem
+# Confirm v1.3.0 is live
+
+# 12. Test installation
+gem install your-gem
+ruby -e "require 'your_gem'; puts YourGem::VERSION"
+# Should output: 1.3.0
+
+# 13. Announce release (optional)
+# - Update README badges
+# - Post on social media
+# - Notify users/community
+```
+
+## Additional Resources
+
+### Official Documentation
+
+- **RubyGems Guides:** https://guides.rubygems.org/
+- **GitHub Actions:** https://docs.github.com/en/actions
+- **Semantic Versioning:** https://semver.org/
+
+### Useful Tools
+
+- **gh CLI:** https://cli.github.com/ - Manage GitHub from command line
+- **gem-release:** https://github.com/svenfuchs/gem-release - Automate version bumping
+- **bundler:** https://bundler.io/ - Dependency management
+
+### Related Workflows
+
+For more advanced setups, check:
+- **Multi-platform testing:** Test on multiple Ruby versions
+- **Dependency updates:** Automated dependabot PRs
+- **Documentation:** Auto-generate and publish docs
+- **Code coverage:** Track test coverage over time
+
+## Conclusion
+
+You now have a complete automated gem release pipeline that:
+
+1. ✅ Validates version matches tag
+2. ✅ Builds gem automatically
+3. ✅ Publishes to RubyGems
+4. ✅ Maintains security with GitHub Secrets
+5. ✅ Provides audit trail via git tags
+
+This workflow can be reused for all your Ruby gems with minimal modifications!
+
+---
+
+**Questions or Issues?**
+
+- Check [Troubleshooting](#troubleshooting) section
+- Review [GitHub Actions logs](https://github.com/USERNAME/REPO/actions)
+- Consult [RubyGems Guides](https://guides.rubygems.org/)

data/docs/GET_RUBYGEMS_SECRET.md

@@ -0,0 +1,151 @@
+# How to Get Your RubyGems OTP Secret
+
+## The Problem
+
+You need the **OTP secret key** from RubyGems, not the 6-digit codes from your authenticator app.
+
+## What It Looks Like
+
+```
+Example: JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP
+
+✅ Valid format:
+- All UPPERCASE letters A-Z
+- Numbers 2-7 only
+- Usually 16-32 characters
+- No spaces, dashes, underscores, or special characters
+
+❌ This is NOT it:
+- 123456 (that's the OTP code, not the secret)
+- abc123_secret (contains invalid characters)
+- YOUR_SECRET_HERE (that's a placeholder!)
+```
+
+## Step-by-Step: Get Your Secret
+
+### Method 1: Find Existing Secret (If Saved)
+
+When you first enabled MFA on RubyGems, it showed you a QR code and a secret key. If you saved that secret key, use it!
+
+Check these places:
+- Password manager (1Password, LastPass, Bitwarden, etc.)
+- Notes app
+- Screenshot of the QR code setup page
+
+### Method 2: Regenerate MFA on RubyGems
+
+If you can't find the original secret, regenerate it:
+
+#### Step 1: Log in to RubyGems
+Go to https://rubygems.org
+
+#### Step 2: Go to MFA Settings
+1. Click your profile picture/name (top right)
+2. Click **Edit Profile**
+3. Click **Multi-factor Authentication** (left sidebar)
+
+#### Step 3: Regenerate MFA
+1. Click **"Disable Multi-factor Authentication"**
+2. Confirm disabling
+3. Click **"Enable Multi-factor Authentication"** again
+4. You'll see a QR code and the **secret key** text
+
+#### Step 4: Save the Secret
+```
+IMPORTANT: Copy the secret key NOW!
+Example: JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP
+```
+
+#### Step 5: Update Your Authenticator App
+1. Remove the old RubyGems entry from your authenticator app
+2. Scan the new QR code
+3. Enter the 6-digit code to verify
+
+⚠️ **Warning:** After regenerating, your old authenticator codes won't work!
+
+## Test Your Secret
+
+Once you have the secret, test it:
+
+```bash
+# Replace JBSWY... with YOUR actual secret
+ruby -r rotp -e "puts ROTP::TOTP.new('JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP').now"
+```
+
+**Expected output:**
+```
+123456  ← A 6-digit number
+```
+
+**This number should match** your authenticator app at the same time!
+
+## Common Mistakes
+
+### ❌ Using the 6-digit OTP code
+```bash
+# WRONG - This is the code, not the secret
+ruby -r rotp -e "puts ROTP::TOTP.new('123456').now"
+# Error: Invalid Base32 Character
+```
+
+### ❌ Using the placeholder text
+```bash
+# WRONG - This is the example placeholder
+ruby -r rotp -e "puts ROTP::TOTP.new('YOUR_SECRET_HERE').now"
+# Error: Invalid Base32 Character - '_'
+```
+
+### ✅ Using the actual secret
+```bash
+# CORRECT - Your actual Base32 secret from RubyGems
+ruby -r rotp -e "puts ROTP::TOTP.new('JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP').now"
+# Output: 123456
+```
+
+## Where to Use It
+
+Once you have your real secret:
+
+### 1. Test Locally
+```bash
+ruby -r rotp -e "puts ROTP::TOTP.new('YOUR_ACTUAL_SECRET').now"
+```
+
+### 2. Add to GitHub Secrets
+1. Go to: https://github.com/YOUR_USERNAME/YOUR_REPO/settings/secrets/actions
+2. Click **New repository secret**
+3. Name: `RUBYGEMS_OTP_SECRET`
+4. Value: Your actual secret (e.g., `JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP`)
+5. Click **Add secret**
+
+## Still Having Issues?
+
+### Error: "Invalid Base32 Character"
+
+Your secret contains invalid characters. Check:
+- No underscores (`_`)
+- No lowercase letters
+- No numbers 0, 1, 8, 9
+- No spaces or special characters
+
+Valid characters: `A-Z` and `2-7` only
+
+### Error: "OTP code doesn't match"
+
+1. Make sure your computer's time is synchronized
+2. Try again (codes change every 30 seconds)
+3. Verify the secret is correct
+
+### Can't Find Secret Anywhere
+
+You'll need to regenerate MFA (see Method 2 above).
+
+## Security Note
+
+🔒 **Keep your OTP secret secure!**
+- Don't share it publicly
+- Don't commit it to git
+- Store it in a password manager
+- Only add it to GitHub Secrets (which are encrypted)
+
+The secret is like a password - anyone with it can generate your OTP codes!

data/docs/QUICK_OTP_SETUP.md

@@ -0,0 +1,80 @@
+# Quick OTP Setup for Automated Releases
+
+## What You Need
+
+Your GitHub repository needs **two secrets** for automated gem releases with MFA:
+
+1. **RUBYGEMS_API_KEY** - Your RubyGems API key
+2. **RUBYGEMS_OTP_SECRET** - Your RubyGems OTP secret
+
+## Step 1: Get Your OTP Secret
+
+1. Log in to https://rubygems.org
+2. Go to **Edit Profile** → **Multi-factor Authentication**
+3. Copy the **secret key** (long alphanumeric string like `JBSWY3DPEHPK3PXP`)
+
+**⚠️ Save this securely!** If you don't see it, you may need to regenerate your MFA.
+
+## Step 2: Add Secrets to GitHub
+
+1. Go to your GitHub repo: https://github.com/shubhamtaywade82/ollama-client
+2. Click **Settings** → **Secrets and variables** → **Actions**
+3. Add two secrets:
+
+| Secret Name           | Value           | Where to Get It                       |
+| --------------------- | --------------- | ------------------------------------- |
+| `RUBYGEMS_API_KEY`    | Your API key    | https://rubygems.org/profile/api_keys |
+| `RUBYGEMS_OTP_SECRET` | Your OTP secret | RubyGems MFA settings (Step 1)        |
+
+## Step 3: Test It
+
+```bash
+# Bump version in lib/ollama/version.rb
+# Then create and push tag:
+git tag v0.2.4
+git push origin v0.2.4
+```
+
+The GitHub Action will automatically:
+- Generate OTP code
+- Build gem
+- Push to RubyGems with OTP authentication
+
+## Test OTP Locally (Optional)
+
+```bash
+gem install rotp
+ruby -r rotp -e "puts ROTP::TOTP.new('YOUR_SECRET_HERE').now"
+```
+
+This should match the code in your authenticator app.
+
+## Troubleshooting
+
+### "Invalid OTP code"
+- Verify `RUBYGEMS_OTP_SECRET` is correct
+- Check it matches your authenticator app
+
+### "unauthorized"
+- Verify `RUBYGEMS_API_KEY` is correct
+- Create new API key with push permissions
+
+### Need more help?
+See full guide: `docs/RUBYGEMS_OTP_SETUP.md`
+
+## How It Works
+
+```yaml
+- name: Install OTP generator
+  run: gem install rotp
+
+- name: Publish gem with OTP
+  env:
+    GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+    RUBYGEMS_OTP_SECRET: ${{ secrets.RUBYGEMS_OTP_SECRET }}
+  run: |
+    otp_code=$(ruby -r rotp -e "puts ROTP::TOTP.new(ENV['RUBYGEMS_OTP_SECRET']).now")
+    gem push "ollama-client-${version}.gem" --otp "$otp_code"
+```
+
+That's it! Your automated releases are now secured with MFA. 🔒

data/docs/QUICK_RELEASE.md

@@ -0,0 +1,106 @@
+# Quick Release Reference
+
+Quick reference for releasing gems via GitHub Actions. See [GEM_RELEASE_GUIDE.md](GEM_RELEASE_GUIDE.md) for full details.
+
+## One-Time Setup
+
+### 1. RubyGems API Key
+1. Visit: https://rubygems.org/profile/edit
+2. Create API key with "Push rubygems" scope
+3. Copy the key
+
+### 2. GitHub Secret
+1. Go to: `https://github.com/USERNAME/REPO/settings/secrets/actions`
+2. Add secret: `RUBYGEMS_API_KEY`
+3. Paste your RubyGems API key
+
+### 3. Workflow File
+Create `.github/workflows/release.yml`:
+
+```yaml
+name: Release
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3.4"
+          bundler-cache: true
+      - name: Validate version
+        run: |
+          tag_version="${GITHUB_REF#refs/tags/v}"
+          gem_version=$(ruby -e "require_relative 'lib/your_gem/version'; puts YourGem::VERSION")
+          [ "$tag_version" = "$gem_version" ] || exit 1
+      - name: Build and publish
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+        run: |
+          gem build your-gem.gemspec
+          gem push your-gem-*.gem
+```
+
+## Release Process
+
+### Every Release
+
+```bash
+# 1. Update version
+# Edit: lib/your_gem/version.rb
+VERSION = "1.2.3"
+
+# 2. Update changelog
+# Edit: CHANGELOG.md
+
+# 3. Commit
+git add lib/your_gem/version.rb CHANGELOG.md
+git commit -m "Bump version to 1.2.3"
+git push
+
+# 4. Tag and push
+git tag -a v1.2.3 -m "Release v1.2.3"
+git push origin v1.2.3
+
+# 5. Monitor
+# https://github.com/USERNAME/REPO/actions
+```
+
+## Quick Commands
+
+```bash
+# Create release script: bin/release.sh
+#!/bin/bash
+VERSION=$1
+git tag -a v${VERSION} -m "Release v${VERSION}"
+git push origin v${VERSION}
+echo "✅ Releasing v${VERSION} - check GitHub Actions"
+
+# Use it:
+chmod +x bin/release.sh
+./bin/release.sh 1.2.3
+```
+
+## Common Issues
+
+**Access Denied?**
+- Check `RUBYGEMS_API_KEY` secret exists
+- Verify API key has "Push rubygems" scope
+
+**Version Mismatch?**
+- Update `lib/your_gem/version.rb`
+- Delete tag: `git tag -d v1.2.3 && git push origin :refs/tags/v1.2.3`
+
+**Workflow Not Running?**
+- Verify `.github/workflows/release.yml` exists
+- Check tag format: `v1.2.3` (with v prefix)
+
+## Links
+
+- **Full Guide:** [GEM_RELEASE_GUIDE.md](GEM_RELEASE_GUIDE.md)
+- **Your Actions:** https://github.com/USERNAME/REPO/actions
+- **RubyGems:** https://rubygems.org/profile/edit
+- **GitHub Secrets:** https://github.com/USERNAME/REPO/settings/secrets/actions

data/docs/README.md

@@ -2,6 +2,11 @@
 
 This directory contains internal development documentation for the ollama-client gem.
 
+## Quick Links
+
+- 🚀 **[Quick Release Reference](QUICK_RELEASE.md)** - Fast release checklist
+- 📘 **[Complete Release Guide](GEM_RELEASE_GUIDE.md)** - Full automation setup (794 lines)
+
 ## Contents
 
 ### Design Documentation
@@ -17,6 +22,7 @@ This directory contains internal development documentation for the ollama-client
 
 ### CI/Automation
 - **[CLOUD.md](CLOUD.md)** - Cloud agent guide for automated testing and fixes
+- **[GEM_RELEASE_GUIDE.md](GEM_RELEASE_GUIDE.md)** - Complete guide for automated gem releases via GitHub Actions and git tags
 
 ## For Users
 

data/docs/RUBYGEMS_OTP_SETUP.md

@@ -0,0 +1,199 @@
+# RubyGems OTP Setup for Automated Releases
+
+This guide explains how to configure OTP (One-Time Password) authentication for automated gem releases with MFA enabled.
+
+## Why This Is Needed
+
+When `rubygems_mfa_required = "true"` is set in your gemspec, RubyGems requires MFA verification for all gem pushes, including automated CI/CD releases. This guide shows how to configure GitHub Actions to generate OTP codes automatically.
+
+## Prerequisites
+
+- RubyGems account with MFA enabled
+- Admin access to your GitHub repository (to add secrets)
+- Authenticator app (Google Authenticator, Authy, 1Password, etc.)
+
+## Step 1: Get Your RubyGems OTP Secret
+
+### Option A: From Existing MFA Setup
+
+If you already have MFA enabled on RubyGems:
+
+1. **Log in to RubyGems.org**
+2. **Go to Edit Profile** → **Multi-factor Authentication**
+3. **Click "Show QR Code"** or **"Regenerate Recovery Codes"**
+4. When you see the QR code, look for the **secret key** (usually shown below the QR code)
+5. Copy the secret key (it's a long alphanumeric string like `JBSWY3DPEHPK3PXP`)
+
+### Option B: Enable MFA Fresh
+
+If you're setting up MFA for the first time:
+
+1. **Log in to RubyGems.org**
+2. **Go to Edit Profile** → **Multi-factor Authentication**
+3. **Click "Enable MFA"**
+4. You'll see a QR code and a **secret key** below it
+5. **Copy the secret key** before scanning the QR code
+6. Scan the QR code with your authenticator app
+7. Enter the 6-digit code to verify
+
+**⚠️ IMPORTANT:** Save the secret key securely. You'll need it for GitHub Actions.
+
+### What the Secret Looks Like
+
+```
+Example: JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP
+- All uppercase letters and numbers
+- Typically 32 characters long
+- Base32 encoded
+```
+
+## Step 2: Add Secrets to GitHub
+
+### 2.1: Add API Key Secret
+
+1. Go to your GitHub repository
+2. Click **Settings** → **Secrets and variables** → **Actions**
+3. Click **New repository secret**
+4. Name: `RUBYGEMS_API_KEY`
+5. Value: Your RubyGems API key (get from https://rubygems.org/profile/api_keys)
+6. Click **Add secret**
+
+### 2.2: Add OTP Secret
+
+1. Still in **Secrets and variables** → **Actions**
+2. Click **New repository secret**
+3. Name: `RUBYGEMS_OTP_SECRET`
+4. Value: Your OTP secret key (from Step 1)
+5. Click **Add secret**
+
+## Step 3: Verify GitHub Secrets
+
+Your repository should now have two secrets:
+
+```
+✅ RUBYGEMS_API_KEY
+✅ RUBYGEMS_OTP_SECRET
+```
+
+## Step 4: Test the Setup
+
+### Test Locally First
+
+You can test OTP generation locally before pushing:
+
+```bash
+# Install rotp gem
+gem install rotp
+
+# Generate an OTP code (replace with your actual secret)
+ruby -r rotp -e "puts ROTP::TOTP.new('YOUR_SECRET_HERE').now"
+```
+
+This should output a 6-digit code that matches your authenticator app.
+
+### Test in CI/CD
+
+1. Bump your gem version in `lib/ollama/version.rb`
+2. Commit and push
+3. Create and push a matching tag:
+
+```bash
+git tag v0.2.4
+git push origin v0.2.4
+```
+
+4. Check GitHub Actions to see the release workflow run
+
+## How It Works
+
+The GitHub Actions workflow:
+
+1. **Installs `rotp` gem** - Ruby library for generating TOTP codes
+2. **Generates OTP code** - Uses your secret to generate a 6-digit code
+3. **Pushes gem** - Runs `gem push --otp <code>` with the generated code
+
+```yaml
+- name: Install OTP generator
+  run: gem install rotp
+
+- name: Publish gem with OTP
+  env:
+    GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+    RUBYGEMS_OTP_SECRET: ${{ secrets.RUBYGEMS_OTP_SECRET }}
+  run: |
+    otp_code=$(ruby -r rotp -e "puts ROTP::TOTP.new(ENV['RUBYGEMS_OTP_SECRET']).now")
+    gem push "ollama-client-${gem_version}.gem" --otp "$otp_code"
+```
+
+## Troubleshooting
+
+### "Invalid OTP code" Error
+
+**Cause:** Time synchronization issue or wrong secret
+
+**Solutions:**
+1. Verify your secret is correct
+2. Check server time is synchronized:
+   ```bash
+   date
+   ```
+3. Try regenerating the secret on RubyGems
+
+### "OTP code expired" Error
+
+**Cause:** Code expired before being used (they last 30 seconds)
+
+**Solution:** The workflow generates the code immediately before use, so this shouldn't happen. If it does, there may be a network delay. The workflow will need to retry.
+
+### "unauthorized" Error
+
+**Cause:** API key is invalid or doesn't have push permissions
+
+**Solutions:**
+1. Verify `RUBYGEMS_API_KEY` is correct
+2. Create a new API key with push permissions
+3. Update the secret in GitHub
+
+### Missing Secrets
+
+**Error:** `RUBYGEMS_OTP_SECRET not found`
+
+**Solution:** Ensure both secrets are added to GitHub (Settings → Secrets and variables → Actions)
+
+## Security Considerations
+
+### ✅ Pros
+- MFA protection on gem releases
+- OTP secret encrypted in GitHub Secrets
+- No manual intervention needed
+- Audit trail in GitHub Actions
+
+### ⚠️ Considerations
+- OTP secret stored in GitHub increases attack surface
+- If GitHub is compromised, attacker has both API key and OTP secret
+- Alternative: Remove `rubygems_mfa_required` and rely on account-level MFA
+
+### Best Practices
+
+1. **Rotate API keys** regularly
+2. **Use scoped API keys** (push-only if possible)
+3. **Enable GitHub branch protection** on main branch
+4. **Require PR reviews** for sensitive changes
+5. **Monitor release logs** for unauthorized pushes
+6. **Regenerate OTP secret** if you suspect compromise
+
+## Alternative: Account-Level MFA Only
+
+If you want simpler automation:
+
+1. Remove `rubygems_mfa_required` from gemspec
+2. Keep account-level MFA enabled on RubyGems
+3. Use API key only (no OTP needed)
+
+This is the recommended approach for most projects as it provides good security with less complexity.
+
+## Reference
+
+- [RubyGems MFA Documentation](https://guides.rubygems.org/setting-up-multifactor-authentication/)
+- [ROTP Gem Documentation](https://github.com/mdp/rotp)
+- [GitHub Encrypted Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets)

data/lib/ollama/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ollama
-  VERSION = "0.2.3"
+  VERSION = "0.2.4"
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ollama-client
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - Shubham Taywade
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-01-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -59,9 +60,14 @@ files:
 - docs/CLOUD.md
 - docs/CONSOLE_IMPROVEMENTS.md
 - docs/FEATURES_ADDED.md
+- docs/GEM_RELEASE_GUIDE.md
+- docs/GET_RUBYGEMS_SECRET.md
 - docs/HANDLERS_ANALYSIS.md
 - docs/PRODUCTION_FIXES.md
+- docs/QUICK_OTP_SETUP.md
+- docs/QUICK_RELEASE.md
 - docs/README.md
+- docs/RUBYGEMS_OTP_SETUP.md
 - docs/SCHEMA_FIXES.md
 - docs/TESTING.md
 - docs/TEST_UPDATES.md
@@ -141,6 +147,7 @@ metadata:
   source_code_uri: https://github.com/shubhamtaywade82/ollama-client
   changelog_uri: https://github.com/shubhamtaywade82/ollama-client/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -155,7 +162,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.5.11
+signing_key:
 specification_version: 4
 summary: An agent-first Ruby client for Ollama (planner/executor + safe tool loops)
 test_files: []