Merge branch 'main' into mm/worker-versioning-steps

Author: flippedcoder

docs/cloud/get-started/namespaces.mdx

@@ -47,8 +47,6 @@ Each Namespace Name must conform to the following rules:
 - A Namespace Name must contain at least 2 characters and no more than 39 characters.
 - A Namespace Name must begin with a letter, end with a letter or number, and contain only letters, numbers, and the
   hyphen (-) character.
-- Each hyphen (-) character must be immediately preceded _and_ followed by a letter or number; consecutive hyphens are
-  not permitted.
 - All letters in a Namespace Name must be lowercase.
 
 ## What is a Temporal Cloud Account ID? {#temporal-cloud-account-id}

docs/develop/go/best-practices/data-handling/external-storage.mdx

@@ -254,6 +254,8 @@ c, err := client.Dial(client.Options{
 })
 ```
 
+You can also package your driver as a [plugin](/develop/plugins-guide) for easier reuse across services.
+
 ## Configure payload size threshold
 
 You can configure the payload size threshold that triggers external storage. By default, payloads larger than 256 KiB
@@ -278,8 +280,7 @@ c, err := client.Dial(client.Options{
 ## Use multiple storage drivers
 
 When you register multiple drivers, you must provide a `DriverSelector` that implements the `StorageDriverSelector`
-interface. The SDK returns an error at client creation if multiple drivers are registered without a selector. The
-selector chooses which driver stores each payload. Any driver in the list that is not selected for storing is still
+interface. The selector chooses which driver stores each payload. Any driver in the list that is not selected for storing is still
 available for retrieval, which is useful when migrating between storage backends. Return `nil` from the selector to
 keep a specific payload inline in Event History.
 
@@ -288,9 +289,9 @@ Multiple drivers are useful in scenarios such as:
 - Driver migration. Your Worker needs to retrieve payloads created by clients that use a different driver than the
   one you prefer. Register both drivers and use the selector to always pick your preferred driver for new payloads.
   The old driver remains available for retrieving existing claims.
-- Latency vs. durability tradeoffs. Some Workflow types may benefit from a faster storage backend
-  at the cost of durability, while others require a durable backend like S3. Use the selector to route based on
-  Workflow context.
+- Multi-cloud storage. Route payloads to different storage backends based on your cloud environment. For
+  example, use S3 for Workers running on AWS and GCS for Workers running on Google Cloud. The selector chooses the
+  appropriate driver based on the runtime environment.
 
 The following example registers two drivers but always selects `preferredDriver` for new payloads. The `legacyDriver`
 is only registered so the Worker can retrieve payloads that were previously stored with it:

docs/develop/python/best-practices/data-handling/external-storage.mdx

@@ -220,9 +220,9 @@ Multiple drivers are useful in scenarios such as:
 - Driver migration. Your Worker needs to retrieve payloads created by clients that use a different driver than the
   one you prefer. Register both drivers and use the selector to always pick your preferred driver for new payloads.
   The old driver remains available for retrieving existing claims.
-- Latency vs. durability tradeoffs. Some Workflow types may benefit from a faster storage backend 
-  at the cost of durability, while others require a durable backend like S3. Use the selector to route based on
-  Workflow context.
+- Multi-cloud storage. Route payloads to different storage backends based on your cloud environment. For
+  example, use S3 for Workers running on AWS and GCS for Workers running on Google Cloud. The selector chooses the
+  appropriate driver based on the runtime environment.
 
 The following example registers two drivers but always selects `preferred_driver` for new payloads. The `legacy_driver`
 is only registered so the Worker can retrieve payloads that were previously stored with it:

docs/develop/typescript/nexus/feature-guide.mdx

@@ -190,10 +190,14 @@ export const helloServiceHandler = nexus.serviceHandler(helloService, {
 A common pattern is to use the Temporal Client from within a sync handler to Signal, Query, or Update a Workflow.
 You can also use Signal-With-Start or Update-With-Start to ensure the Workflow is started and send it a Signal or Update.
 All calls must complete within the [Nexus request timeout](/cloud/limits#nexus-operation-request-timeout).
-The handler receives an AbortSignal via options.signal that is triggered when the deadline is exceeded 
+The handler receives an AbortSignal via `ctx.abortSignal` that is triggered when the deadline is exceeded 
 — pass it to Temporal Client calls to ensure they are canceled if the timeout is reached.
 Updates should be short-lived to stay within this deadline.
 
+The handler context also exposes `ctx.requestDeadline` as an optional `Date`, representing the time by which the current request must complete.
+Note that this is the deadline for the current _request_, not the overall operation.
+Use it to make decisions about whether to start work that may not finish in time, or to set timeouts on downstream calls.
+
 ### Develop an Asynchronous Nexus Operation handler to start a Workflow
 
 Use `@temporalio/nexus`'s `WorkflowRunOperationHandler` helper class to easily expose a Temporal Workflow as a Nexus Operation.
@@ -269,7 +273,7 @@ import { helloServiceHandler } from './handler';
 
 ## Develop a caller Workflow that uses the Nexus Service {#develop-caller-workflow-nexus-service}
 
-To execute a Nexus Operation from a Workflow, import the necessary service definition types, then use `@temporalio/workflow`'s `createNexusClient` to create a Nexus client for that service.
+To execute a Nexus Operation from a Workflow, import the necessary service definition types, then use `@temporalio/workflow`'s `createNexusServiceClient` to create a Nexus client for that service.
 You will need to provide the Nexus Endpoint name, which you registered previously in [Create a Nexus Endpoint to route requests from caller to handler](#create-nexus-endpoint).
 
 <!--SNIPSTART typescript-nexus-hello-service-caller-workflow {"selectedLines": ["1-5","21-34"]}-->
@@ -283,7 +287,7 @@ import { helloService, LanguageCode } from "../service/api";
 const HELLO_SERVICE_ENDPOINT = "hello-service-endpoint-name";
 
 export async function helloCallerWorkflow(name: string, language: LanguageCode): Promise<string> {
-  const nexusClient = wf.createNexusClient({
+  const nexusClient = wf.createNexusServiceClient({
     service: helloService,
     endpoint: HELLO_SERVICE_ENDPOINT,
   });
@@ -440,6 +444,36 @@ For **synchronous Nexus Operations** the following are reported in the caller's
 
 :::
 
+### OpenTelemetry
+
+The `@temporalio/interceptors-opentelemetry` package supports Nexus Operations, providing automatic trace context propagation across Nexus boundaries from the caller Workflow to the handler.
+
+The easiest way to enable it is with the `OpenTelemetryPlugin`, which auto-registers Nexus interceptors alongside Activity and Workflow interceptors:
+
+```ts
+import { OpenTelemetryPlugin } from '@temporalio/interceptors-opentelemetry';
+
+const plugin = new OpenTelemetryPlugin({
+  resource: myResource,
+  spanProcessor: mySpanProcessor,
+});
+
+const worker = await Worker.create({
+  // ...
+  plugins: [plugin],
+  nexusServices: [myServiceHandler],
+});
+```
+
+The plugin creates the following spans:
+
+- **Caller side:** `StartNexusOperation:service/operation` — created when the caller Workflow starts a Nexus Operation.
+- **Handler side:** `RunStartNexusOperation:service/operation` and `RunCancelNexusOperation:service/operation` — created when the handler processes the operation. These spans are children of the caller span, linked via trace context propagated in Nexus request headers.
+
+See the [interceptors-opentelemetry sample](https://github.com/temporalio/samples-typescript/tree/main/interceptors-opentelemetry) for a complete example.
+
+For custom interceptor logic beyond tracing (e.g., logging, authorization), see [Nexus interceptor registration](/develop/typescript/workers/interceptors#nexus-interceptor-registration).
+
 ## Learn more
 
 - Read the high-level description of the [Temporal Nexus feature](/evaluate/nexus) and watch the [Nexus keynote and demo](https://youtu.be/qqc2vsv1mrU?feature=shared&t=2082).

docs/develop/typescript/nexus/quickstart.mdx

@@ -166,7 +166,7 @@ The `nexusServices` parameter registers the handler so it can receive Nexus Oper
 <>
 
 <CodeSnippet language="typescript">
-{`import { proxyActivities, createNexusClient } from '@temporalio/workflow';
+{`import { proxyActivities, createNexusServiceClient } from '@temporalio/workflow';
 // Only import the activity types
 import type * as activities from './activities';
 import { sayHelloService } from './service';
@@ -183,7 +183,7 @@ export async function example(name: string): Promise<string> {
 const NEXUS_ENDPOINT = 'my-nexus-endpoint-name';
 
 export async function callerWorkflow(name: string): Promise<string> {
-    const nexusClient = createNexusClient({
+    const nexusClient = createNexusServiceClient({
       service: sayHelloService,
       endpoint: NEXUS_ENDPOINT,
     });
@@ -203,7 +203,7 @@ The caller Workflow demonstrates the consumer side of Nexus.
 Instead of importing handler code directly, the caller only depends on the Service contract.
 This keeps the caller and handler decoupled so they can live in separate Namespaces, repositories, or even teams.
 
-The `wf.createNexusClient()` method creates a client bound to your Nexus Service and Endpoint.
+The `wf.createNexusServiceClient()` method creates a client bound to your Nexus Service and Endpoint.
 `executeOperation` starts the operation and waits for the result.
 
 </SetupStep>

docs/develop/typescript/workers/interceptors.mdx

@@ -44,6 +44,10 @@ sample.
   Intercept workflow-related methods of [`Client`](https://typescript.temporal.io/api/classes/client.Client/) and
   [`WorkflowHandle`](https://typescript.temporal.io/api/interfaces/client.WorkflowHandle) like starting or signaling a
   Workflow.
+- [NexusInboundCallsInterceptor](https://typescript.temporal.io/api/interfaces/worker.NexusInboundCallsInterceptor):
+  Intercept inbound Nexus Operation calls like `startOperation` and `cancelOperation`.
+- [NexusOutboundCallsInterceptor](https://typescript.temporal.io/api/interfaces/worker.NexusOutboundCallsInterceptor):
+  Intercept outbound calls from Nexus Operations, such as enriching log attributes and metric tags.
 
 All interceptor methods are optional—it's up to the implementor to choose which methods to intercept.
 
@@ -74,6 +78,36 @@ export class ActivityLogInterceptor implements WorkflowOutboundCallsInterceptor
 }
 ```
 
+**Log Nexus Operations**
+
+```ts
+import type {
+  NexusInboundCallsInterceptor,
+  NexusStartOperationInput,
+  NexusStartOperationOutput,
+  Next,
+} from '@temporalio/worker';
+
+export class NexusOperationLogInterceptor implements NexusInboundCallsInterceptor {
+  async startOperation(
+    input: NexusStartOperationInput,
+    next: Next<NexusInboundCallsInterceptor, 'startOperation'>
+  ): Promise<NexusStartOperationOutput> {
+    console.log('Starting Nexus operation', {
+      service: input.ctx.service,
+      operation: input.ctx.operation,
+    });
+    const output = await next(input);
+    console.log('Nexus operation started', {
+      service: input.ctx.service,
+      operation: input.ctx.operation,
+      async: output.result.isAsync,
+    });
+    return output;
+  }
+}
+```
+
 ## Register an Interceptor {#register-interceptor}
 
 Registering an interceptor means providing it to the SDK so Temporal can invoke it when matching Client or Worker calls occur. Once registered, it runs in the call path and can observe or modify request and response data.
@@ -125,3 +159,29 @@ const worker = await Worker.create({
   },
 });
 ```
+
+### Nexus interceptor registration
+
+Nexus interceptors are registered on Worker creation via
+[WorkerOptions](https://typescript.temporal.io/api/interfaces/worker.WorkerOptions#interceptors).
+Pass an array of factory functions to `interceptors.nexus`.
+Each factory receives an [`OperationContext`](https://typescript.temporal.io/api/classes/nexus.OperationContext) and returns an object with optional `inbound` and `outbound` interceptors.
+
+`src/worker/index.ts`
+
+```ts
+import { NexusOperationLogInterceptor } from './nexus-interceptors';
+
+const worker = await Worker.create({
+  // ...
+  nexusServices: [/* your Nexus services */],
+  interceptors: {
+    nexus: [
+      (_ctx) => ({
+        inbound: new NexusOperationLogInterceptor(),
+      }),
+    ],
+  },
+});
+```
+

docs/encyclopedia/activities/activity-operations.mdx

@@ -77,7 +77,7 @@ temporal activity pause \
   --reason "Downstream API is down, pausing until recovery"
 ```
 
-See the [CLI reference for `temporal activity pause`](/cli/activity#pause) for all options, including `--activity-type` for targeting by type.
+See the [CLI reference for `temporal activity pause`](/cli/activity#pause) for all options.
 
 ### Detect Pause in Activity code
 
@@ -104,11 +104,9 @@ Your Activity code may need to handle these cases differently, for example relea
 
 - **A Paused Activity can still time out.** Pause doesn't stop or extend the [Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout). Use [`update-options`](#update-options) to adjust the timeout if needed.
 - **Pause won't interrupt an Activity that doesn't Heartbeat.** The current execution runs to completion, which could take up to the full [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout).
-- **Pausing by `--activity-type` doesn't prevent new Activities of that type from running.** The command Pauses Activities that are pending when it runs. Activities that start afterward are unaffected.
-
 ### Limitations
 
-- **Pause doesn't support bulk operations.** Unlike Unpause, Reset, and Update Options, there's no `--query` flag. You can only Pause Activities within a single Workflow, by Activity Id or by Activity type.
+- **Pause operates on individual Activities by ID within a single Workflow.** Unlike Unpause, Reset, and Update Options, there's no `--query` flag. To pause multiple Activities, issue separate commands for each Activity ID.
 - **No Namespace-wide query for Paused Activities.** You must know the Workflow Id. See [Observability](#observability).
 
 ## Unpause {#unpause}
@@ -206,7 +204,6 @@ Your Activity code may need to handle these cases differently, for example savin
 - **Heartbeat details are preserved by default.** If your Activity uses Heartbeat details for progress tracking and you want a clean restart, pass `--reset-heartbeats`.
 - **Reset won't interrupt an Activity that doesn't Heartbeat.** The current execution runs to completion, which could take up to the full [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout). If the Activity had already retried (attempt > 1), the Temporal Service rejects the current execution's result because Reset changed the expected attempt number. The Activity waits for its Start-To-Close Timeout to expire before a new execution is scheduled.
 - **`--restore-original-options` restores the Activity's original configuration.** It reverts timeouts, Retry Policy, and Task Queue to the values from when the Activity was first scheduled.
-- **Resetting by `--activity-type` or `--match-all` doesn't affect new Activities of that type.** The command Resets Activities that are pending when it runs. Activities that start afterward are unaffected.
 - **Bulk Reset can overwhelm downstream services.** When using `--query` to Reset Activities across many Workflows, use `--jitter` to stagger the restart times.
 
 ## Update Options {#update-options}
@@ -247,7 +244,6 @@ See the [CLI reference for `temporal activity update-options`](/cli/activity#upd
 ### Important considerations
 
 - **Changes to a running Activity take effect on the next execution, not the current one.** If you need the change to apply immediately, the Activity must finish or fail its current execution first.
-- **Updating by `--activity-type` or `--match-all` doesn't affect new Activities of that type.** The command updates Activities that are pending when it runs. Activities that start afterward are unaffected.
 - **`--restore-original-options` is batch-only.** This flag only works with `--query`. It's silently ignored in single-workflow mode. It can't be combined with other option changes in the same command.
 
 ### Limitations
@@ -265,7 +261,7 @@ The UI shows who performed an operation, when, and why (if a `--reason` was prov
 
 ### Find Paused Activities
 
-The `TemporalPauseInfo` [Search Attribute](/search-attribute) is filterable by Activity type within a Workflow.
+The `TemporalPauseInfo` [Search Attribute](/search-attribute) is filterable within a Workflow.
 
 There's no Namespace-wide query to find all Paused Activities across Workflows.
 You must know the Workflow Id.

docs/with-ai.mdx

@@ -44,7 +44,7 @@ Install the Temporal plugin from the [Cursor Marketplace](https://cursor.com/mar
 command in Cursor's agent chat:
 
 ```
-/add-plugin temporal-developer
+/add-plugin temporal
 ```
 
 </TabItem>