anki_generator 1.1.0 → 1.4.0

data/README.md

@@ -1,31 +1,40 @@
 # Anki Generator
 
-A Ruby tool to generate Anki .apkg files from YAML definitions with AI-powered content generation using OpenRouter and file attachment support.
+A Ruby tool to generate Anki .apkg files from YAML definitions, Markdown notes, or CSV files — with AI-powered content generation (Gemini, OpenAI, Anthropic, OpenRouter, or local Ollama via [ruby_llm](https://github.com/crmne/ruby_llm)), cloze deletions, tags, and a built-in web editor.
 
 ## Features
 
-- **AI-Powered Generation**: Create flashcards using OpenRouter API with multiple AI models (GPT, Claude, Llama, etc.)
+- **AI-Powered Generation**: Create flashcards using any LLM provider supported by [ruby_llm](https://github.com/crmne/ruby_llm) — Gemini, OpenAI, Anthropic, OpenRouter, or a local Ollama server — with multiple AI models
+- **Markdown & CSV Import**: Turn `Q:`/`A:` study notes or spreadsheets into decks; Markdown headings become tags
+- **Cloze Deletion Cards**: `{{cN::...}}` deletions export as real Anki cloze notes (one card per deletion)
+- **Tags & Reverse Cards**: Per-card tags in Anki, plus `--reverse` for recognition + recall pairs
+- **Web UI**: `anki_generator serve` opens a localhost editor — paste notes, generate with AI, export `.apkg`
+- **AnkiConnect Push**: Send decks straight into a running Anki with the AnkiConnect addon
+- **Parallel Generation**: `--jobs N` fans one API call per topic out across threads
+- **Reliable AI Output**: Structured generation via ruby_llm Schematist schemas — cards come back as validated JSON, not prompt-honoured text
 - **File Attachment Support**: Attach code files, documentation, or entire directories for context-aware generation
 - **Prompt File Support**: Use text files as prompts for better organization and reusability
-- **Multiple Input Methods**: Generate from YAML files, direct prompts, or file attachments
+- **Multiple Input Methods**: Generate from YAML files, direct prompts, file attachments, Markdown, or CSV
 - **Intelligent Content Processing**: Automatic text file detection, size limits, and binary file filtering
 - **Direct Prompt-to-Deck Generation**: Create decks in one command without intermediate files
 - **Sync Functionality**: Merge new AI-generated cards with existing decks
-- **Flexible Configuration**: Multiple difficulty levels, context settings, and model selection
+- **Flexible Configuration**: Multiple difficulty levels, context settings, model and provider selection
 - **Comprehensive CLI**: Full command-line interface with extensive options
 
 ## Installation
 
+**Requirements**: Ruby 3.1 or higher
+
 1. Clone the repository
 2. Install dependencies:
    ```bash
    bundle install
    ```
 
-3. Set up your OpenRouter API key:
+3. Set up your LLM API key (e.g. Google Gemini):
    ```bash
    cp .env.example .env
-   # Edit .env and add your OpenRouter API key
+   # Edit .env and add your GOOGLE_API_KEY (https://aistudio.google.com/apikey)
    ```
 
 ## Usage
@@ -56,6 +65,39 @@ Generate a deck from a YAML file:
 ./bin/anki_generator generate "My Deck" input/input.yaml my_deck.apkg
 ```
 
+### Import Markdown or CSV Notes
+
+Turn existing study notes into a deck:
+
+```bash
+# Markdown: Q:/A: pairs or "- **question** — answer" bullets; headings become tags
+./bin/anki_generator import "Biology" notes.md biology.apkg
+
+# Add reversed (recall) cards for every basic card
+./bin/anki_generator import "Biology" notes.md biology.apkg --reverse
+
+# CSV: front,back[,tags] with pipe-separated tags
+./bin/anki_generator import "Capitals" capitals.csv capitals.apkg
+```
+
+### Web Editor
+
+```bash
+./bin/anki_generator serve            # http://127.0.0.1:8787
+./bin/anki_generator serve --port 9000
+```
+
+Paste Markdown/YAML on the left, generate cards with AI, edit the table, export `.apkg`.
+
+### Push to a Running Anki
+
+With the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) addon installed in Anki:
+
+```bash
+./bin/anki_generator push "My Deck" cards.yaml
+./bin/anki_generator push "My Deck" cards.yaml --url http://localhost:8765
+```
+
 ### AI-Powered Generation
 
 Create an AI generation template:
@@ -74,7 +116,7 @@ Generate a deck with AI content:
 
 ```bash
 # Use a specific AI model
-./bin/anki_generator prompt_to_deck "Python basics" "Python Deck" python.apkg --model anthropic/claude-3-sonnet
+./bin/anki_generator prompt_to_deck "Python basics" "Python Deck" python.apkg --model anthropic/claude-sonnet-4
 
 # Set difficulty and count
 ./bin/anki_generator generate_yaml "Advanced algorithms" algo.yaml --difficulty hard --count 20
@@ -102,6 +144,15 @@ Generate a deck with AI content:
 
 # Test API connection
 ./bin/anki_generator test_api --api_key YOUR_API_KEY
+
+# Use a local Ollama model instead of a cloud provider (no API key needed)
+./bin/anki_generator prompt_to_deck "Ruby basics" "Ruby" ruby.apkg --provider ollama --model llama3.2
+
+# Generate one API call per topic, 4 at a time
+./bin/anki_generator generate "AI Deck" ai.yaml out.apkg --api_key KEY --jobs 4
+
+# Basic + reversed cards from a YAML deck
+./bin/anki_generator generate "My Deck" input.yaml out.apkg --reverse
 ```
 
 ## CLI Commands
@@ -116,7 +167,7 @@ anki_generator prompt_to_deck PROMPT DECK_NAME OUTPUT_FILE [options]
 - `--attach FILE_OR_DIR [FILE_OR_DIR...]` - Attach files or directories for context
 - `--prompt-file` - Treat PROMPT as a file path to read from
 - `--save-yaml` - Save intermediate YAML file
-- `--api-key API_KEY` - OpenRouter API key
+- `--api-key API_KEY` - Provider API key (requires `--provider`)
 - `--model MODEL` - AI model to use
 - `--difficulty LEVEL` - Difficulty level (easy, medium, hard)
 - `--count N` - Number of flashcards to generate
@@ -131,7 +182,7 @@ anki_generator generate_yaml PROMPT OUTPUT_YAML [options]
 **Options:**
 - `--attach FILE_OR_DIR [FILE_OR_DIR...]` - Attach files or directories for context
 - `--prompt-file` - Treat PROMPT as a file path to read from
-- `--api-key API_KEY` - OpenRouter API key
+- `--api-key API_KEY` - Provider API key (requires `--provider`)
 - `--model MODEL` - AI model to use
 - `--difficulty LEVEL` - Difficulty level (easy, medium, hard)
 - `--count N` - Number of flashcards to generate
@@ -143,6 +194,37 @@ Generate an Anki deck from an existing YAML file:
 anki_generator generate DECK_NAME YAML_FILE OUTPUT_FILE [options]
 ```
 
+**Options:**
+- `--reverse` - Append a front↔back copy of every basic card
+- `--jobs N` - Generate AI topics in parallel across N threads
+- `--api-key`, `--model`, `--provider` (gemini/openai/anthropic/openrouter/ollama/...), `--sync_with`
+
+### `import` - Import Markdown or CSV
+Turn study notes into a deck:
+```bash
+anki_generator import DECK_NAME INPUT_FILE OUTPUT_FILE [options]
+```
+
+**Options:**
+- `--reverse` - Append reversed copies of basic cards
+
+Supports `.md`/`.markdown` (`Q:`/`A:` pairs, `- **front** — back` bullets, headings → tags) and `.csv` (`front,back[,tags]`, tags pipe-separated).
+
+### `push` - Push to Anki
+Send a YAML deck straight into a running Anki via AnkiConnect:
+```bash
+anki_generator push DECK_NAME YAML_FILE [options]
+```
+
+**Options:**
+- `--url URL` - AnkiConnect endpoint (default `http://localhost:8765`)
+
+### `serve` - Web Editor
+Start the localhost editor UI:
+```bash
+anki_generator serve [--port PORT]
+```
+
 ### `create_ai_template` - Create Template
 Create a template YAML file for AI generation:
 ```bash
@@ -150,7 +232,7 @@ anki_generator create_ai_template TEMPLATE_FILE
 ```
 
 ### `test_api` - Test Connection
-Test your OpenRouter API connection:
+Test your LLM connection:
 ```bash
 anki_generator test_api [options]
 ```
@@ -220,9 +302,14 @@ The tool automatically processes text-based files including:
 ```yaml
 - front: "What is Big O notation?"
   back: "Big O notation describes the limiting behavior of a function..."
+  tags: [complexity, cs]
 
 - front: "Define a graph"
   back: "A graph is a collection of vertices connected by edges"
+
+# Cloze deletion — one card per {{cN::...}} ordinal
+- cloze: "{{c1::Paris}} is the capital of {{c2::France}}"
+  tags: [geography]
 ```
 
 ### AI Generation Format
@@ -247,17 +334,29 @@ cards:
 
 ### Environment Variables
 
-- `OPENROUTER_API_KEY`: Your OpenRouter API key
-- `OPENROUTER_DEFAULT_MODEL`: Default model to use (optional)
+- `GOOGLE_API_KEY` / `GEMINI_API_KEY`: Your Google Gemini API key (default provider)
+- `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`: keys for the other cloud providers
+- `OLLAMA_URL`: Ollama server URL (default `http://localhost:11434`)
+- `ANKI_GENERATOR_MODEL`: Default model to use (optional, or pass `--model`)
+
+### Providers
+
+AI generation is backed by the [ruby_llm](https://github.com/crmne/ruby_llm) gem, so any provider it supports works. Omit `--provider` to auto-resolve from the model name, or pin one explicitly:
+
+- **Gemini** (default model `gemini-3.8-flash`, no `--provider` needed): Google's models, key from `GOOGLE_API_KEY`/`GEMINI_API_KEY`
+- **OpenAI** (`--provider openai`): `OPENAI_API_KEY`
+- **Anthropic** (`--provider anthropic`): `ANTHROPIC_API_KEY`
+- **OpenRouter** (`--provider openrouter`): cloud aggregator, `OPENROUTER_API_KEY`
+- **Ollama** (`--provider ollama`): free, local, private — run any GGUF model on your machine with no API key
 
 ### Supported Models
 
-The tool supports all models available through OpenRouter:
+The tool supports all models available through the configured provider:
 
-- OpenAI: `openai/gpt-4`, `openai/gpt-3.5-turbo`
-- Anthropic: `anthropic/claude-3-sonnet`, `anthropic/claude-3-haiku`
-- Meta: `meta-llama/llama-3.1-8b-instruct`
-- And many more...
+- Google: `gemini-3.8-flash` (default), `gemini-3.8-pro`
+- OpenAI: `gpt-5`, `gpt-4o`
+- Anthropic: `claude-sonnet-4`, `claude-haiku-4`
+- And many more (any model id the provider supports)
 
 ## Examples
 
@@ -320,40 +419,54 @@ See the `input/` directory for example YAML files, or create examples with `rake
 
 ## Development
 
-## Development
-
 ### Quick Start for Developers
 
+The repo pins Ruby via `.ruby-version` (3.3). With rbenv/asdf installed:
+
 ```bash
 # Clone and setup
 git clone <repository-url>
 cd anki_generator
 rake setup                     # Install dependencies and create examples
 
-# Run tests
+# Run tests (coverage report in coverage/, 75% line floor enforced)
 rake test                      # Run all tests
 rake test_file[cli]           # Run specific test
 
+# Lint (zero offenses enforced — CI fails otherwise)
+rake lint
+rake lint_fix                 # Auto-correct safe offenses
+
 # Try the examples
 rake demo_api                 # Test API connection
 rake examples                 # Create example files
 rake demo_attachments         # Demo with file attachments
 ```
 
+### GitHub Actions CI/CD
+
+The project includes GitHub Actions workflows:
+
+- **`ruby.yml`** - Main CI pipeline: tests on Ruby 3.1–3.4 plus a RuboCop lint gate
+- **`release.yml`** - Automated releases when tags are pushed
+- **`manual-test.yml`** - Manual workflow for testing specific scenarios
+
+To trigger a release:
+```bash
+git tag v1.2.0
+git push origin v1.2.0
+```
+
 ### Running Tests
 
 ```bash
-# Run all tests
+# Run all tests (SimpleCov runs by default; the suite fails below 75% line coverage)
 rake test
 
 # Run specific test file
 rake test_file[cli]              # runs tests/test_cli.rb
 rake test_file[file_processor]   # runs tests/test_file_processor.rb
-
-# Run tests with coverage
-rake test_coverage
 ```
-
 ### Development Commands
 
 ```bash
@@ -378,17 +491,27 @@ rake demo_api                 # Test API connection
 # Utilities
 rake help                     # Show CLI help
 rake version                  # Show version info
+rake changelog                # Show changelog for current version
 rake release_prep             # Prepare for release
 ```
 
 ### Project Structure
 
 ```
-├── lib/
-│   ├── anki_generator.rb      # Main generator class
-│   ├── openrouter_client.rb   # OpenRouter API client
-│   ├── anki_cli.rb           # CLI interface
-│   └── file_processor.rb     # File attachment processing
+├── lib/anki_generator/
+│   ├── deck_builder.rb        # Deck assembly: YAML loading, AI generation, sync
+│   ├── card.rb                # Card value object (basic + cloze, tags, reverse)
+│   ├── apkg_writer.rb         # Native .apkg (zip + SQLite) writer
+│   ├── apkg_schema.rb         # Anki collection schema and model JSON
+│   ├── cli.rb                 # Thor CLI (thin shell over Commands::*)
+│   ├── commands/              # One service object per CLI command
+│   ├── importers/             # Markdown and CSV note importers
+│   ├── llm_client.rb          # Provider-agnostic LLM client (ruby_llm gem)
+│   ├── client_factory.rb      # Builds the LLM client (any ruby_llm provider)
+│   ├── anki_connect_client.rb # Push decks into a running Anki
+│   ├── server.rb              # WEBrick servlets for the web editor
+│   ├── prompt_builder.rb      # Prompt construction
+│   └── file_processor.rb      # File attachment processing
 ├── bin/
 │   └── anki_generator         # CLI executable
 ├── tests/                     # Test files
@@ -398,7 +521,7 @@ rake release_prep             # Prepare for release
 
 ## API Integration
 
-The tool integrates with OpenRouter to provide access to multiple AI models. You can:
+The tool integrates with the ruby_llm gem to provide access to multiple AI providers and models. You can:
 
 1. Generate flashcards on any topic
 2. Specify difficulty levels
@@ -421,7 +544,12 @@ The sync feature allows you to:
 2. Create a feature branch
 3. Add tests for new functionality
 4. Ensure all tests pass
-5. Submit a pull request
+5. Update CHANGELOG.md with your changes
+6. Submit a pull request
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed version history and changes.
 
 ## License
 

data/Rakefile

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'rake/testtask'
+require 'fileutils'
+
+# Test tasks
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.test_files = FileList['tests/test_*.rb'].exclude('tests/test_helper.rb')
+  t.verbose = true
+end
+
+desc 'Run all tests (with coverage report and floor enforced via test_helper)'
+task test_all: :test
+
+desc 'Run specific test file'
+task :test_file, [:file] do |_t, args|
+  if args[:file]
+    ruby "-I lib tests/test_#{args[:file]}.rb"
+  else
+    puts 'Usage: rake test_file[file_name] (without test_ prefix)'
+    puts 'Example: rake test_file[cli] runs tests/test_cli.rb'
+  end
+end
+
+# Development tasks
+desc 'Install dependencies'
+task :install do
+  sh 'bundle install'
+end
+
+desc 'Build gem'
+task :build do
+  sh 'gem build anki_generator.gemspec'
+end
+
+desc 'Install gem locally'
+task install_local: :build do
+  gem_file = Dir['anki_generator-*.gem'].last
+  sh "gem install #{gem_file}"
+end
+
+desc 'Clean build artifacts'
+task :clean do
+  FileUtils.rm_f(Dir['*.gem'])
+  FileUtils.rm_f(Dir['*.apkg'])
+  FileUtils.rm_f(Dir['temp_*.yaml'])
+  puts 'Cleaned build artifacts'
+end
+
+# Example and demo tasks
+desc 'Create example files'
+task :examples do
+  FileUtils.mkdir_p('examples')
+
+  File.write('examples/study_prompt.txt', <<~PROMPT)
+    Create flashcards about Ruby programming fundamentals.
+    Focus on basic syntax, data types, control structures, and object-oriented concepts.
+    Make the questions practical and suitable for beginners.
+  PROMPT
+
+  File.write('examples/example_class.rb', <<~'RUBY')
+    class Calculator
+      attr_reader :history
+
+      def initialize
+        @history = []
+      end
+
+      def add(a, b)
+        result = a + b
+        @history << "#{a} + #{b} = #{result}"
+        result
+      end
+    end
+  RUBY
+
+  File.write('examples/manual_cards.yaml', <<~YAML)
+    - front: "What is a Ruby class?"
+      back: "A class is a blueprint for creating objects with shared attributes and methods"
+
+    - front: "How do you define a method in Ruby?"
+      back: "Use the 'def' keyword followed by the method name and optional parameters"
+  YAML
+
+  puts 'Created example files in examples/ directory'
+end
+
+desc 'Demo: Generate cards from prompt'
+task :demo_prompt do
+  puts 'Demo: Generating flashcards from a simple prompt...'
+  puts 'Note: This requires a configured LLM API key (e.g. GOOGLE_API_KEY)'
+
+  sh 'ruby -I lib bin/anki_generator generate_yaml "Ruby basics: variables, methods, classes" ' \
+     'demo_output.yaml --count 5 --difficulty easy'
+  puts 'Generated demo_output.yaml'
+end
+
+desc 'Demo: Generate cards with file attachments'
+task demo_attachments: :examples do
+  puts 'Demo: Generating flashcards with file attachments...'
+  puts 'Note: This requires a configured LLM API key (e.g. GOOGLE_API_KEY)'
+
+  sh 'ruby -I lib bin/anki_generator prompt_to_deck examples/study_prompt.txt "Ruby Study Demo" ' \
+     'demo_deck.apkg --prompt-file --attach examples/example_class.rb --count 8'
+  puts 'Generated demo_deck.apkg with file attachments'
+end
+
+desc 'Demo: Test API connection'
+task :demo_api do
+  puts 'Testing LLM connection...'
+  sh 'ruby -I lib bin/anki_generator test_api'
+end
+
+# Utility tasks
+desc 'Show CLI help'
+task :help do
+  sh 'ruby -I lib bin/anki_generator help'
+end
+
+desc 'Show version info'
+task :version do
+  require_relative 'lib/anki_generator/version'
+  puts "Anki Generator version: #{AnkiGenerator::VERSION}"
+end
+
+desc 'Show changelog for current version'
+task :changelog do
+  version = File.read('lib/anki_generator/version.rb')[/VERSION = '([^']+)'/, 1]
+
+  if File.exist?('CHANGELOG.md')
+    changelog = File.read('CHANGELOG.md')
+
+    version_section = changelog.match(/## \[#{Regexp.escape(version)}\].*?(?=## \[|\z)/m)
+
+    if version_section
+      puts "Changelog for version #{version}:"
+      puts '=' * 40
+      puts version_section[0]
+    else
+      puts "No changelog entry found for version #{version}"
+      puts 'Please update CHANGELOG.md'
+    end
+  else
+    puts 'CHANGELOG.md not found'
+  end
+end
+
+desc 'Lint code with RuboCop'
+task :lint do
+  sh 'rubocop --format simple --fail-level warning'
+end
+
+desc 'Auto-fix linting issues'
+task :lint_fix do
+  sh 'rubocop --auto-correct-all --format simple'
+end
+
+# Combined tasks
+desc 'Full development setup'
+task setup: %i[install examples] do
+  puts 'Development environment ready!'
+  puts "Run 'rake test' to run tests"
+  puts "Run 'rake demo_api' to test API connection"
+  puts "Run 'rake help' to see CLI options"
+end
+
+desc 'Prepare for release'
+task release_prep: %i[clean lint test build] do
+  puts 'Release preparation complete!'
+  puts 'Gem built and tests passed'
+end
+
+task default: :test

data/anki_generator.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'lib/anki_generator/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'anki_generator'
+  spec.version       = AnkiGenerator::VERSION
+  spec.authors       = ['Ceb']
+  spec.email         = ['ceeb.developer@gmail.com']
+  spec.summary       = 'AI-powered Anki flashcard generator with file attachment support'
+  spec.description   = 'A command-line tool that generates Anki flashcard decks (.apkg) from YAML files, direct prompts, or file attachments. Features AI-powered content generation via the provider-agnostic ruby_llm gem (Gemini, OpenAI, Anthropic, OpenRouter, Ollama, and more), file and directory attachment processing for context-aware generation, prompt file support, intelligent content filtering, and flexible deck management with sync capabilities.'
+  spec.homepage      = 'https://github.com/pinkfloydsito/anki_generator'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |file|
+    file.start_with?('tests/', 'scripts/', '.github/', '.kiro/') ||
+      file.match?(/\.gem\z/) || file == '.env.example'
+  end
+  spec.bindir        = 'bin'
+  spec.executables   = ['anki_generator']
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'dotenv', '~> 2.8'
+  spec.add_dependency 'json', '~> 2.0'
+  spec.add_dependency 'ruby_llm', '~> 2.0'
+  spec.add_dependency 'rubyzip', '>= 2.3', '< 3.0'
+  spec.add_dependency 'sinatra', '~> 4.0'
+  spec.add_dependency 'sqlite3', '>= 1.6', '< 3.0'
+  spec.add_dependency 'thor', '~> 1.2'
+  spec.add_dependency 'webrick', '>= 1.8'
+
+  spec.required_ruby_version = '>= 3.1.0'
+
+  spec.metadata = {
+    'homepage_uri' => spec.homepage,
+    'source_code_uri' => spec.homepage,
+    'changelog_uri' => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    'bug_tracker_uri' => "#{spec.homepage}/issues",
+    'documentation_uri' => "#{spec.homepage}/blob/main/README.md",
+    'rubygems_mfa_required' => 'true'
+  }
+end

data/bin/anki_generator

@@ -1,5 +1,6 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require_relative '../lib/anki_cli'
+require_relative '../lib/anki_generator/cli'
 
-AnkiCLI.start(ARGV)
+AnkiGenerator::CLI.start(ARGV)

data/docs/CI_SETUP.md

@@ -0,0 +1,120 @@
+# CI/CD Setup Guide
+
+This document explains the minimal GitHub Actions workflows and Ruby setup.
+
+## Workflows Overview
+
+### 1. `ruby.yml` - Main CI Pipeline
+- **Trigger**: Push/PR to main branch
+- **Ruby Versions**: 3.1, 3.2, 3.3, 3.4
+- **Lint**: RuboCop gate (zero offenses enforced)
+- **Actions**: Test, lint, and build gem
+- **Status**: ✅ Minimal and reliable
+
+### 2. `release.yml` - Automated Releases
+- **Trigger**: Git tags (v*)
+- **Actions**: Test, build, create GitHub release
+- **Artifacts**: Uploads gem file to release
+
+### 3. `manual-test.yml` - Manual Testing
+- **Trigger**: Manual workflow dispatch
+- **Features**: 
+  - Choose Ruby version (3.1, 3.2, 3.3)
+  - Optional demo runs
+  - Full CLI testing
+
+## Ruby Version Support
+
+### Supported Versions
+- ✅ **Ruby 3.1**: Fully supported and tested
+- ✅ **Ruby 3.2**: Fully supported and tested  
+- ✅ **Ruby 3.3**: Fully supported and tested
+
+### Requirements
+- Minimum Ruby version: 3.1.0
+- Minitest: ~> 5.20 (for Ruby 3.3+ compatibility)
+- Additional gems for Ruby 3.3+: mutex_m (automatically included)
+
+## Ruby Setup Issues
+
+### Problem: Self-Hosted Runner Detection
+```
+Error: The current runner (ubuntu-24.04-x64) was detected as self-hosted
+```
+
+### Solutions:
+
+#### Option 1: Use Updated Workflow (Recommended)
+The `ruby.yml` workflow uses `ruby/setup-ruby@v1` which handles newer Ubuntu versions.
+
+#### Option 2: Manual Ruby Installation (Self-Hosted Runners)
+```bash
+# Run the setup script
+./scripts/setup-ruby-self-hosted.sh 3.3.0
+
+# Or manually:
+ruby-build 3.3.0 /opt/hostedtoolcache/Ruby/3.3.0/x64
+touch /opt/hostedtoolcache/Ruby/3.3.0/x64.complete
+```
+
+#### Option 3: Use Different Runner
+```yaml
+runs-on: ubuntu-22.04  # Instead of ubuntu-latest
+```
+## Testing Locally
+
+Before pushing, test locally:
+```bash
+# Run all tests
+bundle exec rake test
+
+# Build gem
+bundle exec rake build
+
+# Install and test CLI
+bundle exec rake install_local
+anki_generator help
+```
+
+## Release Process
+
+1. **Update version** in `anki_generator.gemspec`
+2. **Update CHANGELOG.md** with new version
+3. **Commit changes**:
+   ```bash
+   git add .
+   git commit -m "Bump version to 1.2.0"
+   ```
+4. **Create and push tag**:
+   ```bash
+   git tag v1.2.0
+   git push origin v1.2.0
+   ```
+5. **GitHub Actions will**:
+   - Run tests on Ruby 3.1, 3.2, 3.3
+   - Build gem
+   - Create GitHub release
+   - Upload gem artifact
+
+## Troubleshooting
+
+### Ruby Version Issues
+- Supported: Ruby 3.1, 3.2, 3.3
+- Use `ruby scripts/debug-ruby-version.rb` to diagnose issues
+- Ensure bundler compatibility
+
+### Dependency Issues
+- Run `bundle update` to update dependencies
+- Check for security vulnerabilities: `bundle audit`
+
+### Build Issues
+- Ensure all files are included in gemspec
+- Check for missing dependencies
+- Verify executable permissions on scripts
+
+## Best Practices
+
+1. **Test locally** before pushing
+2. **Use supported Ruby versions** (3.1-3.3)
+3. **Update CHANGELOG.md** for each release
+4. **Monitor CI pipeline** health regularly