Merge branch 'main' into codex/activity-options-ui-docs

Author: flippedcoder

docs/cloud/operation-api.mdx

@@ -22,14 +22,21 @@ The Temporal Cloud Operations API, or the Cloud Ops API, is an open source, publ
 
 ## Develop applications with the Cloud Ops API
 
-You can use the HTTP API or the gRPC API depending on how you need to integrate with your platform. The URL to access both the HTTP and gRPC Cloud Ops API is `saas-api.tmprl.cloud`.
+You can use the HTTP API or the gRPC API depending on how you need to integrate with your platform.
+
+- HTTP: `https://saas-api.tmprl.cloud`
+- gRPC: `saas-api.tmprl.cloud:443`
+
+If you connect to Temporal Cloud over [AWS PrivateLink](/cloud/connectivity/aws-connectivity) or [GCP Private Service Connect](/cloud/connectivity/gcp-connectivity), configure private DNS for `saas-api.tmprl.cloud` so control-plane clients (Cloud Ops API, Terraform, tcld) reach the private endpoint.
 
 ### Prerequisites
 
 These prerequisites are required for using either HTTP or gRPC.
 
-- [Temporal Cloud user account](/cloud/get-started)
-- [API Key](/cloud/tcld/apikey#create) for authentication
+- A Temporal Cloud [User](/cloud/manage-access/users) or [Service Account](/cloud/manage-access/service-accounts)
+- An [API Key](/cloud/api-keys#manage-api-keys) for authentication (owned by that User or Service Account)
+
+Required [roles and permissions](/cloud/manage-access/roles-and-permissions) vary by operation. Some account-wide management operations require Account Owner or Global Admin. Others work with Developer, Finance Admin, Namespace Admin, or custom roles.
 
 ### Use cases
 
@@ -68,17 +75,17 @@ To start using the Go SDK with the Cloud Ops API, follow these steps:
 
 1. Install the Go SDK:
    ```go
-   go get github.com/temporalio/cloud-sdk-go
+   go get go.temporal.io/cloud-sdk@latest
    ```
 
 2. Import and use the SDK:
    ```go
    import (
-       "github.com/temporalio/cloud-sdk-go/client"
+       "go.temporal.io/cloud-sdk/cloudclient"
    )
    ```
 
-3. The Go SDK provides pre-built client interfaces that handle authentication and connection setup. Refer to the [Go samples](https://github.com/temporalio/cloud-samples-go) for detailed usage examples.
+3. The Go SDK provides pre-built client interfaces that handle authentication and connection setup. Refer to the [Go samples](https://github.com/temporalio/cloud-samples-go) for detailed usage examples, including [Cloud Ops API client setup](https://github.com/temporalio/cloud-samples-go/blob/main/client/api/client.go).
 
 The Go SDK eliminates the need to work directly with generated protobuf files and provides a more idiomatic Go experience.
 
@@ -88,60 +95,64 @@ For programming languages other than Go, download the gRPC protobufs from the [C
 
 Use [gRPC](https://grpc.io/docs/) to compile and generate code in your preferred [programming language](https://grpc.io/docs/#official-support). The steps below use Python as an example and require [Python's gRPC tools](https://grpc.io/docs/languages/python/quickstart/#grpc-tools) to be installed, but the approach can be adapted for other supported programming languages.
 
+You can also generate clients from the published Buf module at [buf.build/temporalio/cloud-api](https://buf.build/temporalio/cloud-api).
+
 1. Clone the Temporal Cloud API repository:
 
    ```command
    git clone https://github.com/temporalio/cloud-api.git
    cd cloud-api
    ```
 
-2. Copy Protobuf files:
-
-   - Navigate to the `temporal` directory.
-   - Copy the protobuf files to your project directory.
+2. Compile the Protobuf files from the repository root (protos live under `temporal/` and import each other):
 
-3. Compile the Protobuf files:
-
-   ```python
-   python -m grpc_tools.protoc -I./ --python_out=./ --grpc_python_out=./ *.proto
+   ```command
+   python -m grpc_tools.protoc \
+     -I. \
+     --python_out=. \
+     --grpc_python_out=. \
+     $(find temporal -name '*.proto')
    ```
-   - `-I` specifies the directory of the `.proto` files.
-   - `--python_out=` sets the output directory for generated Python classes.
-   - `--grpc_python_out=` sets the output directory for generated gRPC service classes.
-   - `*.proto` processes all `.proto` files.
+
+   - `-I.` adds the repository root to the import path.
+   - `--python_out=` and `--grpc_python_out=` set the output directories for generated classes.
+   - `find temporal -name '*.proto'` includes all Cloud Ops API protos and their dependencies under `temporal/`.
 
    After compiling the Protobuf files, you will have generated code files in your project directory.
    These files enable interaction with the Temporal Cloud API in your chosen programming language.
 
-4. Import the Generated Files:
-
-   - Locate the Python files (.py) generated in your project directory.
-   - Import these files into your Python application where you intend to interact with the Temporal Cloud API.
-
-2. Use the API:
-   - Use the classes and methods defined in the imported files to communicate with the Temporal Cloud services.
-   - Ensure to handle any required authentication or configuration as needed for Temporal Cloud.
+3. Import the generated files into your application and call the Cloud Ops API. Handle authentication with an API key and set the API version header as described in [Usage guidelines](#usage-guidelines).
 
 This approach can be adapted for other programming languages by following their respective import and usage conventions for the generated code files.
 
 ## Usage guidelines
 
 When interacting with the Temporal Cloud Ops API, follow these guidelines:
 
-- API version header:
-   - Always include the `temporal-cloud-api-version` header in your requests, specifying the API version identifier.
-   - The current API version can be found [here](https://github.com/temporalio/cloud-api/blob/main/VERSION#L1C1-L1C14).
-- Connection URL:
-   - Connect to the Temporal Cloud using the gRPC URL: `saas-api.tmprl.cloud:443`.
-- Engagement steps:
-   - Generate API key:
-     - Obtain an [API Key for authentication](/cloud/api-keys#manage-api-keys). Note that many operations may require Admin privileges.
-   - Set up client:
-     - Establish a secure connection to the Temporal Cloud. Refer to the example [Client setup in Go](https://github.com/temporalio/cloud-samples-go/blob/main/client/temporal/client.go) for guidance.
-   - Execute operations:
-     - For operation specifics, refer to the `cloudservice/v1/request_response.proto` for gRPC messages and `cloudservice/v1/service.proto` for gRPC services.
-
-These steps provide a structured approach to using the Temporal Cloud Ops API effectively, ensuring proper authentication and connection setup.
+### API version header
+
+Use the `temporal-cloud-api-version` header to select an API version. The backend uses this version to safely mutate resources. The current API version is in the [`cloud-api` VERSION file](https://github.com/temporalio/cloud-api/blob/main/VERSION).
+
+**gRPC**
+
+gRPC clients must send a `temporal-cloud-api-version` header on every request.
+
+**HTTP**
+
+For HTTP clients, the version header is optional. If omitted, the HTTP gateway defaults it to the latest API version. This supports simple `curl` usage without looking up a version first.
+
+For production HTTP automation, still pin an explicit version so behavior does not change when the gateway’s latest version advances.
+
+### Connection URL
+
+- gRPC: `saas-api.tmprl.cloud:443`
+- HTTP: `https://saas-api.tmprl.cloud`
+
+### Engagement steps
+
+1. Generate an [API Key for authentication](/cloud/api-keys#manage-api-keys). Required permissions vary by operation; see [roles and permissions](/cloud/manage-access/roles-and-permissions).
+2. Establish a secure connection. For Go, see [Cloud Ops API client setup](https://github.com/temporalio/cloud-samples-go/blob/main/client/api/client.go).
+3. Execute operations. For request and response messages, see `cloudservice/v1/request_response.proto`. For services, see `cloudservice/v1/service.proto`.
 
 ## Rate limits
 
@@ -163,9 +174,9 @@ This limit applies to all requests made by each user through any client (tcld, U
 
 This limit applies to all requests made by each service account through any client (tcld, Cloud Ops API).
 
-**Asynchronous Operations: 10 concurrent operations at a time**
+**Asynchronous operations: 10 concurrent operations at a time**
 
-This limits the number of concurrent asynchronous operations that can be in-flight at any given time.
+By default, each account can have up to 10 long-running (asynchronous) mutating operations in flight at once. This limit applies to a subset of create, update, and delete operations (for example Namespace, User, API Key, Export Sink, and Service Account mutations), not every RPC that returns an async operation.
 
 ### Important considerations
 

docs/develop/worker-performance.mdx

@@ -344,7 +344,7 @@ worker = Temporalio::Worker.new(
 
 ### Cache options (Java SDK) {/* #cache-options */}
 
-A Workflow Cache is created and shared between all Workers on a single host.
+A [Workflow Cache](/workflow-execution#workflow-cache) is created and shared between all Workers on a single host.
 It's designed to limit the resources used by the cache for each host/process.
 These options are defined on `WorkerFactoryOptions`:
 
@@ -371,7 +371,7 @@ These properties should always be true for a Worker's configuration.
 Perform this sanity check after the adjustments to Worker settings.
 
 1. `workflowCacheSize` should be ≤ `maxWorkflowThreadCount`. Each Workflow has at least one Workflow thread.
-2. `maxConcurrentWorkflowTaskExecutionSize` should be ≤ `maxWorkflowThreadCount`. Having more Worker slots than the Workflow cache size will lead to resource contention/stealing between executors and unpredictable delays. It's recommended that `maxWorkflowThreadCount` be at least 2x of `maxConcurrentWorkflowTaskExecutionSize`.
+2. `maxConcurrentWorkflowTaskExecutionSize` should be ≤ `maxWorkflowThreadCount`. It's recommended that `maxWorkflowThreadCount` be at least 2x of `maxConcurrentWorkflowTaskExecutionSize`. This is because having more Worker slots than the Workflow cache size will lead to resource allocation issues between executors and cause unpredictable delays.
 3. `maxConcurrentWorkflowTaskPollers` should be significantly ≤ `maxConcurrentWorkflowTaskExecutionSize`. And `maxConcurrentActivityTaskPollers` should be significantly ≤ `maxConcurrentActivityExecutionSize`. The number of pollers should always be lower than the number of executors.
 
 ## Worker runtime performance tuning {/* #worker-performance-tuning */}

docs/encyclopedia/workflow/workflow-execution/workflow-execution.mdx

@@ -10,7 +10,6 @@ keywords:
 tags:
   - Concepts
   - Workflows
-
 ---
 
 import { CaptionedImage } from '@site/src/components';
@@ -25,6 +24,7 @@ This page provides an overview of Workflow Execution:
 - [Workflow Execution Chain](#workflow-execution-chain)
 - [Memo](#memo)
 - [State Transition](#state-transition)
+- [Workflow cache](#workflow-cache)
 
 ## What is a Workflow Execution? {/* #workflow-execution */}
 
@@ -207,3 +207,11 @@ For more information on Workflow Execution, please refer to the following subpag
 - [Continue-as-New](/workflow-execution/continue-as-new)
 - [Timers and Start Delay](/workflow-execution/timers-delays)
   :::
+
+## Workflow cache
+
+A Workflow Cache is an in-memory LRU (least recently used) cache maintained by Workers that stores the state of Workflow Executions they have processed.
+
+When a Worker picks up a Workflow Task, it caches the Workflow's state in memory. This allows the Worker to continue processing subsequent Tasks for that Workflow without having to fetch the full Event History from the server and replay it from scratch. 
+
+This caching mechanism is closely tied to [Sticky Execution](/sticky-execution). The Temporal Service directs future Workflow Tasks to the same Worker that cached the Workflow, via a dedicated "Sticky Queue". If the cached Workflow is evicted, to make room for another for example, the Worker must replay the Event History to restore its state before continuing.

docs/glossary.md

@@ -805,6 +805,10 @@ are executed with the same Worker without requiring you to manually specify Task
 In day-to-day conversations, the term "Workflow" frequently denotes either a Workflow Type, a Workflow Definition, or a
 Workflow Execution.
 
+#### [Workflow cache](/workflow-execution#workflow-cache)
+
+An in-memory cache on a Worker that holds the state of Workflow Executions it has processed so later Workflow Tasks can avoid a full Event History replay. Used with [Sticky Execution](/sticky-execution). See also [Workflow Cache Tuning](/develop/worker-performance#workflow-cache-tuning).
+
 <!-- _Tags: [term](/tags/term), [explanation](/tags/explanation)_ -->
 
 #### [Workflow Definition](/workflow-definition)

docusaurus.config.js

@@ -250,7 +250,7 @@ module.exports = async function createConfigAsync() {
               '**/clusters/**',
               '**/ai-cookbook/**',
             ], // partials (underscore-prefixed) + context content we don't render
-            editUrl: 'https://github.com/temporalio/documentation/edit/main/docs/',
+            editUrl: 'https://github.com/temporalio/documentation/blob/main/',
             /**
              * Whether to display the author who last updated the doc.
              */

package.json

@@ -70,7 +70,7 @@
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.1.0",
     "@vercel/functions": "^3.7.5",
-    "algoliasearch": "^5.54.1",
+    "algoliasearch": "^5.55.1",
     "chart.js": "^4.4.1",
     "clsx": "^2.1.1",
     "comlink": "^4.4.2",
@@ -83,7 +83,7 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "react-icons": "^5.6.0",
-    "react-instantsearch": "^7.36.0",
+    "react-instantsearch": "^7.38.0",
     "react-markdown": "^10.1.0",
     "react-player": "^3.4.0",
     "rehype-katex": "7",