Document new Nexus Operation timeouts

docs/develop/go/temporal-nexus.mdx

@@ -336,6 +336,45 @@ func HelloCallerWorkflow(ctx workflow.Context, name string, language service.Lan
 ```
 <!--SNIPEND-->
 
+### Set Nexus Operation timeouts
+
+Nexus Operations support [three types of timeouts](/nexus/operations#timeouts) that control how long the caller is willing to wait at different stages of the Operation lifecycle.
+Set these timeouts in `NexusOperationOptions` when calling `ExecuteOperation`.
+
+#### Schedule-to-Close timeout
+
+The [Schedule-to-Close timeout](/nexus/operations#schedule-to-close-timeout) limits the total duration of the Operation from when it is scheduled to when it completes.
+The Nexus Machinery automatically retries failed requests until this timeout is exceeded.
+
+```go
+fut := c.ExecuteOperation(ctx, service.HelloOperationName, service.HelloInput{Name: name, Language: language}, workflow.NexusOperationOptions{
+	ScheduleToCloseTimeout: 10 * time.Minute,
+})
+```
+
+#### Schedule-to-Start timeout
+
+The [Schedule-to-Start timeout](/nexus/operations#schedule-to-start-timeout) limits how long the caller will wait for the Operation to be started by the handler.
+If not set, no Schedule-to-Start timeout is enforced.
+
+```go
+fut := c.ExecuteOperation(ctx, service.HelloOperationName, service.HelloInput{Name: name, Language: language}, workflow.NexusOperationOptions{
+	ScheduleToStartTimeout: 2 * time.Minute,
+})
+```
+
+#### Start-to-Close timeout
+
+The [Start-to-Close timeout](/nexus/operations#start-to-close-timeout) limits how long the caller will wait for an asynchronous Operation to complete after it has been started.
+This timeout only applies to asynchronous Operations.
+If not set, no Start-to-Close timeout is enforced.
+
+```go
+fut := c.ExecuteOperation(ctx, service.HelloOperationName, service.HelloInput{Name: name, Language: language}, workflow.NexusOperationOptions{
+	StartToCloseTimeout: 5 * time.Minute,
+})
+```
+
 ### Register the caller Workflow in a Worker
 
 After developing the caller Workflow, the next step is to register it with a Worker.

docs/encyclopedia/nexus-operations.mdx

@@ -14,6 +14,10 @@ keywords:
   - nexus circuit breaking
   - nexus circuit breaker
   - circuit breaker is open
+  - nexus timeouts
+  - schedule-to-close timeout
+  - schedule-to-start timeout
+  - start-to-close timeout
   - execution semantics
   - temporal sdk
   - versioning
@@ -179,7 +183,7 @@ For example, when you execute a Nexus Operation in a caller Workflow the followi
 ## Automatic retries {#automatic-retries}
 
 Once the caller Workflow schedules an Operation with the caller's Temporal Service, the caller's Nexus Machinery keeps trying to start the Operation.
-If a [retryable Nexus error](/references/failures#nexus-errors) is returned the Nexus Machinery will retry until the Nexus Operation's Start-to-Close-Timeout is exceeded.
+If a [retryable Nexus error](/references/failures#nexus-errors) is returned the Nexus Machinery will retry until the Nexus Operation's [Schedule-to-Close timeout](#schedule-to-close-timeout) or [Schedule-to-close timeout](#schedule-to-close-timeout) is exceeded.
 
 For example, if a Nexus handler returns a [retryable error](/references/failures#nexus-errors), or an [upstream timeout](https://github.com/nexus-rpc/api/blob/main/SPEC.md#predefined-handler-errors) is encountered by the caller, the Nexus request will be retried up to the [default Retry Policy's](https://github.com/temporalio/temporal/blob/de7c8879e103be666a7b067cc1b247f0ac63c25c/components/nexusoperations/config.go#L111) max attempts and expiration interval.
 
@@ -193,6 +197,50 @@ This differs from how Activities and Workflows handle errors and retries:
 
 See [errors in Nexus handlers](/nexus/error-handling#errors-in-nexus-handlers) to control the retry behavior by returning a [non-retryable Nexus error](/references/failures#non-retryable-nexus-errors).
 
+## Timeouts {#timeouts}
+
+Nexus Operations support three types of timeouts that control how long the caller is willing to wait at different stages of the Operation lifecycle.
+These timeouts are set by the caller when scheduling the Operation.
+
+### Schedule-to-Close timeout {#schedule-to-close-timeout}
+
+The Schedule-to-Close timeout limits the total duration from when the Operation is scheduled to when it completes.
+This is the overall timeout for the entire Operation.
+The Nexus Machinery [automatically retries](#automatic-retries) failed requests internally until this timeout is exceeded, at which point the Operation fails with a [NexusOperationTimedOut](/references/events#nexusoperationtimedout) event.
+
+This timeout covers the full [Nexus Operation lifecycle](https://docs.temporal.io/nexus/operations#operation-lifecycle). Asynchronous Operations are scheduled, started, and completed. Synchronous Operations don't have an intermediate started state because they complete as part of the start request.
+
+In Temporal Cloud, the [maximum Schedule-to-Close timeout is 60 days](https://docs.temporal.io/cloud/limits#nexus-operation-duration-limits).
+
+### Schedule-to-Start timeout {#schedule-to-start-timeout}
+
+The Schedule-to-Start timeout limits how long the caller is willing to wait for the Operation to be started (or completed, if synchronous) by the handler.
+If the Operation is not started within this timeout, it fails with `TIMEOUT_TYPE_SCHEDULE_TO_START`.
+
+If not set or set to zero, no Schedule-to-Start timeout is enforced.
+
+:::note
+
+The Schedule-to-Start timeout requires Temporal Server version 1.31.0 or later.
+
+:::
+
+### Start-to-Close timeout {#start-to-close-timeout}
+
+The Start-to-Close timeout limits how long the caller is willing to wait for an asynchronous Operation to complete after it has been started.
+If the Operation does not complete within this timeout after starting, it fails with `TIMEOUT_TYPE_START_TO_CLOSE`.
+
+This timeout only applies to asynchronous Operations.
+Synchronous Operations ignore this timeout because they complete as part of the start request.
+
+If not set or set to zero, no Start-to-Close timeout is enforced.
+
+:::note
+
+The Start-to-Close timeout requires Temporal Server version 1.31.0 or later.
+
+:::
+
 ## Circuit breaking {#circuit-breaking}
 
 Circuit breaking handles deployment issues, such as remote service faults, that take time to recover.
@@ -296,7 +344,7 @@ Pending Nexus Operations: 1
 
 ### At-least-once execution semantics and idempotency
 
-The Nexus Machinery provides reliable execution with at-least-once execution semantics for a Nexus Operation, until the caller's Schedule-to-Close-Timeout is exceeded, at which time the overall Nexus Operation times out.
+The Nexus Machinery provides reliable execution with at-least-once execution semantics for a Nexus Operation, until the caller's [Schedule-to-Close timeout](#schedule-to-close-timeout) is exceeded, at which time the overall Nexus Operation times out.
 
 The Nexus Machinery breaks up the [Nexus Operation lifecycle](/nexus/operations#operation-lifecycle) into one or more [Nexus Tasks](/tasks#nexus-task) that a Nexus handler is responsible for processing.
 If a Nexus handler times out or returns a non-retryable Nexus error, then the Nexus Machinery will retry the Nexus request to provide at-least-once execution.