Add all Ruby SDK reference files (11 files, ~2100 lines)

Created complete Ruby reference documentation covering:
- ruby.md: Overview, quick start, key concepts, file organization
- patterns.md: Signals, queries, updates, child workflows, saga, cancellation, etc.
- determinism.md: Illegal call tracing, safe alternatives table
- determinism-protection.md: TracePoint, durable fiber scheduler, customization
- versioning.md: Patching API, type versioning, worker versioning
- testing.md: WorkflowEnvironment, mocking, replay, activity testing
- error-handling.md: ApplicationError, retries, timeouts, workflow failure
- data-handling.md: Data converter, ActiveModel, hints, search attributes
- observability.md: Logging, metrics, best practices
- gotchas.md: Common mistakes, illegal call tracing issues
- advanced-features.md: Schedules, async completion, worker tuning, Rails

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

references/ruby/advanced-features.md

@@ -0,0 +1,191 @@
+# Ruby SDK Advanced Features
+
+## Schedules
+
+Create recurring workflow executions with `Temporalio::Client::Schedule`.
+
+```ruby
+require 'temporalio/client'
+
+# Create a schedule
+schedule_id = 'daily-report'
+client.create_schedule(
+  schedule_id,
+  Temporalio::Client::Schedule.new(
+    action: Temporalio::Client::Schedule::Action::StartWorkflow.new(
+      DailyReportWorkflow,
+      id: 'daily-report',
+      task_queue: 'reports'
+    ),
+    spec: Temporalio::Client::Schedule::Spec.new(
+      intervals: [
+        Temporalio::Client::Schedule::Spec::Interval.new(every: 86_400) # 1 day in seconds
+      ]
+    )
+  )
+)
+
+# Manage schedules
+handle = client.schedule_handle(schedule_id)
+handle.pause(note: 'Maintenance window')
+handle.unpause
+handle.trigger
+handle.delete
+```
+
+## Async Activity Completion
+
+For activities that complete asynchronously (e.g., human tasks, external callbacks).
+
+```ruby
+class RequestApproval < Temporalio::Activity::Definition
+  def execute(request_id)
+    # Get task token for async completion
+    task_token = Temporalio::Activity::Context.current.info.task_token
+
+    # Store task token for later completion (e.g., in database)
+    store_task_token(request_id, task_token)
+
+    # Signal that this activity completes asynchronously
+    Temporalio::Activity::Context.current.raise_complete_async
+  end
+end
+
+# Later, complete the activity from another process
+client = Temporalio::Client.connect('localhost:7233')
+task_token = get_task_token(request_id)
+handle = client.async_activity_handle(task_token: task_token)
+
+if approved
+  handle.complete('approved')
+else
+  handle.fail(Temporalio::Error::ApplicationError.new('Rejected'))
+end
+```
+
+If you configure a `heartbeat_timeout:` on the activity, the external completer is responsible for sending heartbeats via the async handle. If you do NOT set a `heartbeat_timeout`, no heartbeats are required.
+
+## Worker Tuning
+
+Configure worker performance settings.
+
+```ruby
+worker = Temporalio::Worker.new(
+  client: client,
+  task_queue: 'my-queue',
+  workflows: [MyWorkflow],
+  activities: [MyActivity],
+  max_concurrent_workflow_tasks: 100,
+  max_concurrent_activities: 100
+)
+worker.run
+```
+
+## Workflow Failure Exception Types
+
+Control which exceptions cause workflow failure vs workflow task failure (which Temporal retries automatically).
+
+### Per-Workflow Configuration
+
+```ruby
+class MyWorkflow < Temporalio::Workflow::Definition
+  # Class method approach
+  def self.workflow_failure_exception_type
+    MyCustomError
+  end
+
+  def execute
+    raise MyCustomError, 'This fails the workflow, not just the task'
+  end
+end
+```
+
+### Worker-Level Configuration
+
+```ruby
+Temporalio::Worker.new(
+  client: client,
+  task_queue: 'my-queue',
+  workflows: [MyWorkflow],
+  workflow_failure_exception_types: [MyCustomError]
+)
+```
+
+**Tips:**
+- Set to `[Exception]` in tests so any unhandled exception fails the workflow immediately rather than retrying the workflow task forever. Surfaces bugs faster.
+- Include `Temporalio::Workflow::NondeterminismError` to fail the workflow instead of leaving it in a retrying state on non-determinism errors.
+
+## Activity Concurrency and Executors
+
+Ruby uses `Temporalio::Worker::ActivityExecutor::ThreadPool` by default. Activities run in a thread pool.
+
+```ruby
+# Default: activities run in thread pool
+worker = Temporalio::Worker.new(
+  client: client,
+  task_queue: 'my-queue',
+  workflows: [MyWorkflow],
+  activities: [MyActivity],
+  activity_executors: {
+    default: Temporalio::Worker::ActivityExecutor::ThreadPool.new(max_threads: 20)
+  }
+)
+```
+
+Fiber-based execution is also possible for IO-bound activities using Ruby's fiber scheduler.
+
+## Rails Integration
+
+### ActiveRecord Considerations
+
+Never pass ActiveRecord models directly to Temporal workflows or activities. Serialize to plain data structures.
+
+```ruby
+# BAD - Passing AR model
+client.execute_workflow(
+  ProcessOrderWorkflow,
+  Order.find(42),  # Don't pass AR objects!
+  id: 'order-42',
+  task_queue: 'orders'
+)
+
+# GOOD - Pass serializable data
+client.execute_workflow(
+  ProcessOrderWorkflow,
+  { id: 42, total: order.total, status: order.status },
+  id: 'order-42',
+  task_queue: 'orders'
+)
+```
+
+### Zeitwerk and Autoloading
+
+Rails uses Zeitwerk for autoloading. Workflow and activity classes must be loadable by Zeitwerk or explicitly required.
+
+```ruby
+# In config/initializers/temporal.rb or similar
+# Eager load Temporal classes so they're available to the worker
+Rails.application.config.after_initialize do
+  Dir[Rails.root.join('app/workflows/**/*.rb')].each { |f| require f }
+  Dir[Rails.root.join('app/activities/**/*.rb')].each { |f| require f }
+end
+```
+
+### Forking Considerations
+
+If using a forking server (Puma, Unicorn), workers must be created **after** the fork. Connections established before fork are not safe to share across processes.
+
+```ruby
+# In Puma config (puma.rb)
+on_worker_boot do
+  # Create Temporal client and worker AFTER fork
+  client = Temporalio::Client.connect('localhost:7233')
+  worker = Temporalio::Worker.new(
+    client: client,
+    task_queue: 'my-queue',
+    workflows: [MyWorkflow],
+    activities: [MyActivity]
+  )
+  Thread.new { worker.run }
+end
+```

references/ruby/data-handling.md

@@ -0,0 +1,192 @@
+# Ruby SDK Data Handling
+
+## Overview
+
+Data converters serialize and deserialize workflow/activity inputs and outputs. The `Temporalio::Converters` module provides the conversion pipeline.
+
+## Default Data Converter
+
+The default converter handles types in this order:
+
+1. `nil` - null payload
+2. Bytes - `String` with `ASCII_8BIT` encoding
+3. Protobuf - objects implementing `Google::Protobuf::MessageExts`
+4. JSON - everything else, via Ruby's `JSON` module
+
+Note: symbol keys become strings on deserialization. `create_additions: true` by default.
+
+## ActiveModel Integration
+
+Use the `ActiveModelJSONSupport` mixin for custom model classes:
+
+```ruby
+module ActiveModelJSONSupport
+  def as_json(_options = {})
+    { JSON.create_id => self.class.name }.merge(instance_variables.each_with_object({}) do |var, hash|
+      hash[var.to_s.delete('@')] = instance_variable_get(var)
+    end)
+  end
+
+  def to_json(*args)
+    as_json.to_json(*args)
+  end
+
+  def self.included(base)
+    base.define_method(:json_create) do |hash|
+      obj = base.new
+      hash.each do |key, value|
+        next if key == JSON.create_id
+        obj.instance_variable_set("@#{key}", value)
+      end
+      obj
+    end
+  end
+end
+
+class MyModel
+  include ActiveModelJSONSupport
+  attr_accessor :name, :value
+
+  def initialize(name: nil, value: nil)
+    @name = name
+    @value = value
+  end
+end
+```
+
+## Custom Data Converter
+
+```ruby
+converter = Temporalio::Converters::DataConverter.new(
+  payload_converter: my_payload_converter,
+  payload_codec: my_payload_codec,
+  failure_converter: my_failure_converter
+)
+
+client = Temporalio::Client.connect(
+  'localhost:7233',
+  'default',
+  data_converter: converter
+)
+```
+
+## Converter Hints
+
+Ruby-specific feature for guiding deserialization to the correct type:
+
+```ruby
+class MyWorkflow
+  workflow_arg_hint MyClass
+  workflow_result_hint MyClass
+
+  workflow_update :my_update, arg_hints: [MyClass]
+
+  def execute(input)
+    # input is deserialized as MyClass
+  end
+end
+```
+
+Custom converters use these hints to know the target deserialization type.
+
+## Payload Encryption
+
+Implement a `PayloadCodec` with `encode` and `decode`:
+
+```ruby
+class EncryptionCodec
+  def encode(payloads)
+    payloads.map { |p| encrypt(p) }
+  end
+
+  def decode(payloads)
+    payloads.map { |p| decrypt(p) }
+  end
+
+  private
+
+  def encrypt(payload)
+    # encryption logic
+  end
+
+  def decrypt(payload)
+    # decryption logic
+  end
+end
+
+converter = Temporalio::Converters::DataConverter.new(
+  payload_codec: EncryptionCodec.new
+)
+```
+
+## Search Attributes
+
+Define a search attribute key:
+
+```ruby
+key = Temporalio::SearchAttributes::Key.new(
+  'CustomerId',
+  Temporalio::SearchAttributes::IndexedValueType::KEYWORD
+)
+```
+
+Set at workflow start:
+
+```ruby
+client.start_workflow(
+  MyWorkflow,
+  'arg',
+  id: 'wf-1',
+  task_queue: 'my-queue',
+  search_attributes: Temporalio::SearchAttributes.new({ key => 'customer-123' })
+)
+```
+
+Upsert from a workflow:
+
+```ruby
+Temporalio::Workflow.upsert_search_attributes({ key => 'new-value' })
+```
+
+Query workflows:
+
+```ruby
+client.list_workflows(filter: "CustomerId = 'customer-123'")
+```
+
+## Workflow Memo
+
+Set at workflow start:
+
+```ruby
+client.start_workflow(
+  MyWorkflow,
+  'arg',
+  id: 'wf-1',
+  task_queue: 'my-queue',
+  memo: { 'region' => 'us-east', 'priority' => 'high' }
+)
+```
+
+Read from within a workflow:
+
+```ruby
+region = Temporalio::Workflow.memo['region']
+```
+
+## Deterministic APIs for Values
+
+Use these instead of standard Ruby equivalents inside workflows:
+
+```ruby
+Temporalio::Workflow.uuid       # deterministic UUID
+Temporalio::Workflow.random     # deterministic random number
+Temporalio::Workflow.now        # deterministic current time
+```
+
+## Best Practices
+
+- Use dedicated model classes for Temporal data, not ActiveRecord models.
+- Keep payloads small; store large data externally and pass references.
+- Encrypt sensitive data with a `PayloadCodec`.
+- Use `Temporalio::Workflow.uuid`, `.random`, and `.now` inside workflows for determinism.