refactor(ruby): updated /develop/ruby to restructure content

.vscode/settings.json

@@ -1,3 +0,0 @@
-{
-  "editor.formatOnSave": true
-}

docs/cloud/get-started/index.mdx

@@ -58,7 +58,7 @@ See our guides for connecting each SDK to your Temporal Cloud Namespace:
 - [Connect to Temporal Cloud in TypeScript](/develop/typescript/core-application#connect-to-temporal-cloud)
 - [Connect to Temporal Cloud in .NET](/develop/dotnet/temporal-client#connect-to-temporal-cloud)
 - [Connect to Temporal Cloud in PHP](/develop/php/temporal-client#connect-to-temporal-cloud)
-- [Connect to Temporal Cloud in Ruby](/develop/ruby/temporal-client#connect-to-temporal-cloud)
+- [Connect to Temporal Cloud in Ruby](/develop/ruby/client/temporal-client#connect-to-temporal-cloud)
 
 ## Run your first Workflow
 
@@ -70,7 +70,7 @@ See our guides for starting a workflow using each SDK:
 - [Start a workflow in TypeScript](/develop/typescript/core-application#start-workflow-execution)
 - [Start a workflow in .NET](/develop/dotnet/temporal-client#start-workflow)
 - [Start a workflow in PHP](/develop/php/temporal-client#start-workflow-execution)
-- [Start a workflow in Ruby](/develop/ruby/temporal-client#start-workflow)
+- [Start a workflow in Ruby](/develop/ruby/client/temporal-client#start-workflow)
 
 ## Invite your team
 

docs/develop/ruby/activities/basics.mdx

@@ -0,0 +1,68 @@
+---
+id: basics
+title: Activity Basics - Ruby SDK
+sidebar_label: Activity Basics
+description: This section explains Activity Basics with the Ruby SDK
+toc_max_heading_level: 4
+keywords:
+  - Ruby SDK
+tags:
+  - Ruby SDK
+  - Temporal SDKs
+---
+
+## Develop an Activity {#develop-activity}
+
+One of the primary things that Workflows do is orchestrate the execution of Activities.
+An Activity is a normal method execution that's intended to execute a single, well-defined action (either short or long-running), such as querying a database, calling a third-party API, or transcoding a media file.
+An Activity can interact with world outside the Temporal Platform or use a Temporal Client to interact with a Temporal Service.
+For the Workflow to be able to execute the Activity, we must define the [Activity Definition](/activity-definition).
+
+You can develop an Activity Definition by creating a class that extends `Temporalio::Activity::Definition`.
+To register a class as an Activity with a custom name, use the `activity_name` class method in the class definition.
+Otherwise, the activity name is the unqualified class name.
+
+```ruby
+class MyActivity < Temporalio::Activity::Definition
+  def execute(input)
+    "#{input['greeting']}, #{input['name']}!"
+  end
+end
+```
+
+Activity implementation code should be _idempotent_. Learn more about [idempotency](/activity-definition#idempotency).
+
+There is no explicit limit to the total number of parameters that an [Activity Definition](/activity-definition) may support.
+However, there is a limit to the total size of the data that ends up encoded into a gRPC message Payload.
+
+A single argument is limited to a maximum size of 2 MB.
+And the total size of a gRPC message, which includes all the arguments, is limited to a maximum of 4 MB.
+
+Some SDKs require that you pass context objects, others do not.
+When it comes to your application data—that is, data that is serialized and encoded into a Payload—we recommend that you use a single hash or object as an argument that wraps the application data passed to Activities.
+This is so that you can change what data is passed to the Activity without breaking a method signature.
+
+The `execute` method in your Activity can technically accept multiple parameters of any data type that Temporal can convert.
+However, Temporal strongly encourages using a single parameter object to simplify versioning and maintainability.
+
+### Activity Concurrency and Executors {#activity-concurrency-and-executors}
+
+:::note
+
+This section covers advanced concurrency and execution options that most users will not need when getting started.
+
+:::
+
+By default, activities run in the "thread pool executor" (i.e. `Temporalio::Worker::ActivityExecutor::ThreadPool`).
+This default is shared across all workers and is a naive thread pool that continually makes threads as needed when none are
+idle/available to handle incoming work.
+If a thread sits idle long enough, it will be killed.
+
+The maximum number of concurrent activities a worker will run at a time is configured via its `tuner` option.
+The default is `Temporalio::Worker::Tuner.create_fixed` which defaults to 100 activities at a time for that worker.
+When this value is reached, the worker will stop asking for work from the server until there are slots available again.
+
+In addition to the thread pool executor, there is also a fiber executor in the default executor set.
+To use fibers, call `activity_executor :fiber` class method at the top of the activity class (the default of this value is `:default` which is the thread pool executor).
+Activities can only choose the fiber executor if the worker has been created and run in a fiber, but thread pool executor is always available.
+Currently due to [an issue](https://github.com/temporalio/sdk-ruby/issues/162), workers can only run in a fiber on Ruby versions 3.3 and newer.

docs/develop/ruby/activities/dynamic-activity.mdx

@@ -0,0 +1,38 @@
+---
+id: dynamic-activity
+title: Dynamic Activities - Ruby SDK
+sidebar_label: Dynamic Activities
+description: This section explains Dynamic Activities with the Ruby SDK
+toc_max_heading_level: 4
+keywords:
+  - Ruby SDK
+tags:
+  - Ruby SDK
+  - Temporal SDKs
+---
+
+## Set a Dynamic Activity {#set-a-dynamic-activity}
+
+A Dynamic Activity in Temporal is an Activity that is invoked dynamically at runtime if no other Activity with the same name is registered.
+An Activity can be made dynamic by invoking `activity_dynamic` class method at the top of the definition.
+You must register the Activity with the Worker before it can be invoked.
+Only one Dynamic Activity can be present on a Worker.
+
+Often, dynamic is used in conjunction with `activity_raw_args` which does not convert arguments but instead passes them
+through as a splatted array of `Temporalio::Converters::RawValue` instances.
+
+```ruby
+class MyDynamicActivity < Temporalio::Activity::Definition
+  # Make this the dynamic activity and accept raw args
+  activity_dynamic
+  activity_raw_args
+
+  def execute(*raw_args)
+    raise Temporalio::Error::ApplicationError, 'One arg expected' unless raw_args.size == 1
+
+    # Use payload converter to convert it
+    input = Temporalio::Activity::Context.current.payload_converter.from_payload(raw_args.first.payload)
+    "#{input['greeting']}, #{input['name']}!"
+  end
+end
+```

docs/develop/ruby/activities/execution.mdx

@@ -0,0 +1,48 @@
+---
+id: execution
+title: Activity execution - Ruby SDK
+description: Shows how to perform Activity execution with the Ruby SDK
+sidebar_label: Activity Execution
+slug: /develop/ruby/activities/execution
+toc_max_heading_level: 3
+tags:
+  - Ruby SDK
+  - Temporal SDKs
+  - Activity
+---
+
+## Start Activity Execution {#activity-execution}
+
+Calls to spawn [Activity Executions](/activity-execution) are written within a [Workflow Definition](/workflow-definition).
+The call to spawn an Activity Execution generates the [ScheduleActivityTask](/references/commands#scheduleactivitytask) Command.
+This results in the set of three [Activity Task](/tasks#activity-task) related Events ([ActivityTaskScheduled](/references/events#activitytaskscheduled), [ActivityTaskStarted](/references/events#activitytaskstarted), and `ActivityTask[Closed]`)in your Workflow Execution Event History.
+
+The values passed to Activities through invocation parameters or returned through a result value are recorded in the Execution history.
+The entire Execution history is transferred from the Temporal service to Workflow Workers when a Workflow state needs to recover.
+A large Execution history can thus adversely impact the performance of your Workflow.
+
+Therefore, be mindful of the amount of data you transfer through Activity invocation parameters or Return Values.
+Otherwise, no additional limitations exist on Activity implementations.
+
+To spawn an Activity Execution, use the `execute_activity` operation from within your Workflow Definition.
+
+```ruby
+class MyWorkflow < Temporalio::Workflow::Definition
+  # Customize the name
+  workflow_name :MyDifferentWorkflowName
+
+  def execute(name)
+    Temporalio::Workflow.execute_activity(
+      MyActivity,
+      { greeting: 'Hello', name: },
+      start_to_close_timeout: 100
+    )
+  end
+end
+```
+
+Activity Execution semantics rely on several parameters.
+The only required value that needs to be set is either a [Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout) or a [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout).
+These values are set as keyword parameters.
+
+The Activity result is the returned from the `execute_activity` call.

docs/develop/ruby/activities/index.mdx

@@ -0,0 +1,25 @@
+---
+id: index
+title: Activities - Ruby SDK
+sidebar_label: Activities
+description: This section explains how to implement Activities with the Ruby SDK
+toc_max_heading_level: 4
+keywords:
+  - Ruby SDK
+tags:
+  - Ruby SDK
+  - Temporal SDKs
+---
+
+import * as Components from '@site/src/components';
+
+![Ruby SDK Banner](/img/assets/banner-ruby-temporal.png)
+
+## Activities
+
+- [Activity Basics](/develop/ruby/activities/basics)
+- [Activity Execution](/develop/ruby/activities/execution)
+- [Timeouts](/develop/ruby/activities/timeouts)
+- [Asynchronous Activity Completion](/develop/ruby/activities/asynchronous-activity)
+- [Dynamic Activity](/develop/ruby/activities/dynamic-activity)
+- [Benign exceptions](/develop/ruby/activities/benign-exceptions)

docs/develop/ruby/activities/timeouts.mdx

@@ -0,0 +1,100 @@
+---
+id: timeouts
+title: Activity Timeouts - Ruby SDK
+sidebar_label: Timeouts
+description: Optimize Workflow Execution with Temporal Ruby SDK - Set Activity Timeouts and Retry Policies efficiently.
+toc_max_heading_level: 4
+keywords:
+  - Ruby
+  - failure detection
+  - timeouts
+tags:
+  - Activities
+  - Workflows
+  - Errors
+  - Failures
+  - Ruby SDK
+  - Temporal SDKs
+---
+
+## Activity timeouts {#activity-timeouts}
+
+Each Activity Timeout controls a different aspect of how long an Activity Execution can take:
+
+- **[Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout)**
+- **[Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout)**
+- **[Schedule-To-Start Timeout](/encyclopedia/detecting-activity-failures#schedule-to-start-timeout)**
+
+At least one of `start_to_close_timeout` or `schedule_to_close_timeout` is required.
+
+```ruby
+Temporalio::Workflow.execute_activity(
+  MyActivity,
+  { greeting: 'Hello', name: },
+  start_to_close_timeout: 5 * 60
+)
+```
+
+### Activity Retry Policy {#activity-retries}
+
+By default, Activities use a system Retry Policy.
+You can override it by specifying a custom Retry Policy.
+
+To create an Activity Retry Policy in Ruby, set the `retry_policy` parameter when executing an activity.
+
+```ruby
+Temporalio::Workflow.execute_activity(
+  MyActivity,
+  { greeting: 'Hello', name: },
+  start_to_close_timeout: 5 * 60,
+  retry_policy: Temporalio::RetryPolicy.new(max_interval: 10)
+)
+```
+
+### Override the retry interval with `next_retry_delay` {#next-retry-delay}
+
+If you raise an application-level error, you can override the Retry Policy's delay by specifying a new delay.
+
+```ruby
+raise Temporalio::Error::ApplicationError.new(
+  'Some error',
+  type: 'SomeErrorType',
+  next_retry_delay: 3 * Temporalio::Activity::Context.current.info.attempt
+)
+```
+
+## Heartbeat an Activity {#activity-heartbeats}
+
+A Heartbeat is a periodic signal from the Worker to the Temporal Service indicating the Activity is still alive and making progress.
+
+- Heartbeats are used to detect Worker failure.
+- Cancellations are delivered via Heartbeats.
+- Heartbeats may contain custom progress details.
+
+```ruby
+class MyActivity < Temporalio::Activity::Definition
+  def execute
+    # This is a naive loop simulating work, but similar heartbeat logic
+    # applies to other scenarios as well
+    loop do
+      # Send heartbeat
+      Temporalio::Activity::Context.current.heartbeat
+      # Sleep before heartbeating again
+      sleep(3)
+    end
+  end
+end
+```
+
+### Heartbeat Timeout {#heartbeat-timeout}
+
+The Heartbeat Timeout sets the maximum duration between Heartbeats before the Temporal Service considers the Activity failed.
+
+```ruby
+Temporalio::Workflow.execute_activity(
+  MyActivity,
+  { greeting: 'Hello', name: },
+  start_to_close_timeout: 5 * 60,
+  heartbeat_timeout: 5
+)
+```

docs/develop/ruby/debugging.mdx → docs/develop/ruby/best-practices/debugging.mdx

@@ -35,13 +35,13 @@ For production Workflows, debugging options include:
 
 - [Web UI](/web-ui)
 - [Temporal CLI](/cli)
-- [Replay](/develop/ruby/testing-suite#replay-test)
-- [Tracing](/develop/ruby/observability#tracing)
-- [Logging](/develop/ruby/observability#logging)
+- [Replay](/develop/ruby/best-practices/testing-suite#replay-test)
+- [Tracing](/develop/ruby/workers/observability#tracing)
+- [Logging](/develop/ruby/workers/observability#logging)
 
 You can analyze Worker performance using:
 
-- [Metrics](/develop/ruby/observability#metrics)
+- [Metrics](/develop/ruby/workers/observability#metrics)
 - [Worker performance guide](/develop/worker-performance)
 
 To monitor Server performance: