Merge branch 'main' into python-nexus-ga

Author: jsundai

.gitignore

@@ -12,6 +12,7 @@ test-results
 .docusaurus
 .cache-loader
 temp/
+.claude/*
 
 # Misc
 .DS_Store
@@ -23,6 +24,8 @@ temp/
 .vs
 AGENTS.md
 CLAUDE.md
+.claude/*
+.omc
 
 npm-debug.log*
 yarn-debug.log*

docs/best-practices/cloud-access-control.mdx

@@ -37,7 +37,7 @@ This approach ensures near-zero-downtime rotation and prevents authentication fa
 
 For mutual TLS (mTLS) implementations, using Let's Encrypt is not recommended, as it is designed primarily for public-facing services and lacks support for internal certificate requirements. 
 
-While we are not making a specific product recommendation, there are several valid options for managing certificates. Many organizations choose vendor solutions such as AWS Private CA, Setigo, Microsoft Certification Authority, or DigiCert for their robust integration and lifecycle features. Alternatively, self-signed certificates are a valid and commonly used approach, even in production environments. If you choose to self-sign, tools like [OpenSSL](https://openssl-library.org/), [CFSSL](https://github.com/cloudflare/cfssl), or [step CLI](https://github.com/smallstep/cli) can help generate and manage certificates effectively. 
+While we are not making a specific product recommendation, there are several valid options for managing certificates. Many organizations choose vendor solutions such as AWS Private CA, Sectigo, Microsoft Certification Authority, or DigiCert for their robust integration and lifecycle features. Alternatively, self-signed certificates are a valid and commonly used approach, even in production environments. If you choose to self-sign, tools like [OpenSSL](https://openssl-library.org/), [CFSSL](https://github.com/cloudflare/cfssl), or [step CLI](https://github.com/smallstep/cli) can help generate and manage certificates effectively. 
 
 Select the option that aligns best with your infrastructure, security requirements, and operational needs.
 
@@ -56,6 +56,6 @@ One convention is to give certificates a common name that matches the namespace.
 
 #### 2. Use Certificate Filters to restrict access when using shared CAs (e.g., `dev` vs `prod`):
 
-  Certificate Filters are an additional way of validating using the client certificate presented during client authenticationGive certificates a common name that matches the namespace. This is not a requirement.   
+  Certificate Filters are an additional way of validating using the client certificate presented during client authentication. Give certificates a common name that matches the namespace. This is not a requirement.   
 
   If you do this when using the same CA for dev and prod environments, then you can leverage Certificate Filters to prevent access to production. 

docs/best-practices/knowledge-hub.mdx

@@ -27,7 +27,7 @@ To bootstrap your knowledge hub, use the
 ## What belongs in your knowledge hub
 
 Although Temporal itself has [thorough documentation](https://docs.temporal.io/), not all of it applies to your organization or your teams' use cases.
-The knolwedge hub distills the documentation into just the specific information your teams need.
+The knowledge hub distills the documentation into just the specific information your teams need.
 One way to organize the content is according to where developers are in their journey.
 The following sample outline shows what sections to include.
 
@@ -82,7 +82,7 @@ Include the following items in this section:
 
 ## Measuring success of your knowledge hub
 
-After you've created your knolwedge hub, establish metrics to measure its effectiveness for your organization.
+After you've created your knowledge hub, establish metrics to measure its effectiveness for your organization.
 The following table shows example indicators that organizations use to measure the impact of their knowledge hub,
 along with realistic before-and-after targets:
 

docs/best-practices/managing-namespace.mdx

@@ -106,7 +106,7 @@ Use a custom [Authorizer](/self-hosted-guide/security#authorizer-plugin) on your
 
 If an Authorizer is not set, Temporal uses the `nopAuthority` authorizer that unconditionally allows all API calls.
 
-On Temporal Cloud, [role-based access controls](/cloud/users#namespace-level-permissions) provide namespace-level authorization without custom configuration.
+On Temporal Cloud, [role-based access controls](/cloud/manage-access/roles-and-permissions#namespace-level-permissions) provide namespace-level authorization without custom configuration.
 
 ### Enable deletion protection (Temporal Cloud only) {#deletion-protection}
 

docs/best-practices/worker.mdx

@@ -59,7 +59,6 @@ production-ready Worker image:
 
 {/* SNIPSTART oms-dockerfile-worker */}
 [Dockerfile](https://github.com/temporalio/reference-app-orders-go/blob/main/Dockerfile)
-
 ```Dockerfile
 FROM golang:1.24.1 AS oms-builder
 
@@ -79,7 +78,6 @@ RUN --mount=type=cache,target=/go/pkg/mod \
 
 FROM busybox AS oms-worker
 ```
-
 {/* SNIPEND oms-dockerfile-worker */}
 
 This Dockerfile uses a multi-stage build pattern with two stages:
@@ -102,27 +100,25 @@ uses environment variables to configure the Worker:
 
 {/* SNIPSTART oms-billing-worker-deployment {"selectedLines": ["20-35"]} */}
 [deployments/k8s/billing-worker-deployment.yaml](https://github.com/temporalio/reference-app-orders-go/blob/main/deployments/k8s/billing-worker-deployment.yaml)
-
 ```yaml
 # ...
-spec:
-  containers:
-    - args:
-        - -k
-        - supersecretkey
-        - -s
-        - billing
-      env:
-        - name: FRAUD_API_URL
-          value: http://billing-api:8084
-        - name: TEMPORAL_ADDRESS
-          value: temporal-frontend.temporal:7233
-      image: ghcr.io/temporalio/reference-app-orders-go-worker:latest
-      name: billing-worker
-      imagePullPolicy: Always
-  enableServiceLinks: false
+    spec:
+      containers:
+        - args:
+            - -k
+            - supersecretkey
+            - -s
+            - billing
+          env:
+            - name: FRAUD_API_URL
+              value: http://billing-api:8084
+            - name: TEMPORAL_ADDRESS
+              value: temporal-frontend.temporal:7233
+          image: ghcr.io/temporalio/reference-app-orders-go-worker:latest
+          name: billing-worker
+          imagePullPolicy: Always
+      enableServiceLinks: false
 ```
-
 {/* SNIPEND */}
 
 ### Separate Task Queues logically
@@ -150,7 +146,6 @@ Worker reference to avoid this issue.
 
 {/* SNIPSTART oms-billing-worker-go {"selectedLines": ["12-23"]} */}
 [app/billing/worker.go](https://github.com/temporalio/reference-app-orders-go/blob/main/app/billing/worker.go)
-
 ```go
 // ...
 // RunWorker runs a Workflow and Activity worker for the Billing system.
@@ -166,7 +161,6 @@ func RunWorker(ctx context.Context, config config.AppConfig, client client.Clien
 	return w.Run(temporalutil.WorkerInterruptFromContext(ctx))
 }
 ```
-
 {/* SNIPEND */}
 
 ### Use Worker Versioning to safely deploy new Workflow code

docs/cli/activity.mdx

@@ -27,6 +27,8 @@ This file is generated from https://github.com/temporalio/cli/blob/main/internal
 
 This page provides a reference for the `temporal` CLI `activity` command. The flags applicable to each subcommand are presented in a table within the heading for the subcommand. Refer to [Global Flags](#global-flags) for flags that you can use with every subcommand.
 
+To use the CLI with Standalone Activities, see the CLI commands in the [Go](/docs/develop/go/standalone-activities.mdx), [Python](/docs/develop/python/standalone-activities.mdx), and [.NET](/docs/develop/dotnet/standalone-activities.mdx) Standalone Activity guides.
+
 ## complete
 
 Complete an Activity, marking it as successfully finished. Specify the
@@ -114,7 +116,7 @@ activity timeout, as well as, optionally, the
 
 If the activity may be executing (i.e. it has not yet timed out), the
 reset will take effect the next time it fails, heartbeats, or times out.
-If is waiting for a retry (i.e. has failed or timed out), the reset
+If it is waiting for a retry (i.e. has failed or timed out), the reset
 will apply immediately.
 
 If the activity is already paused, it will be unpaused by default.
@@ -136,7 +138,7 @@ reset, handle this error and then re-throw it when you've cleaned up.
 
 If the `reset_heartbeats` flag is set, the heartbeat details will also be cleared.
 
-Specify the Activity Type of ID and Workflow IDs:
+Specify the Activity Type or ID and Workflow IDs:
 
 ```
 temporal activity reset \

docs/cli/cmd-options.mdx

@@ -132,7 +132,7 @@ If set, the Activity will start at a random time within the specified jitter dur
 
 ## activity-type
 
-Command is applied to the all running activities with of this type.
+Command is applied to all running activities of this type.
 
 ## address
 

docs/cli/setup-cli.mdx

@@ -55,6 +55,12 @@ Install with Homebrew (if available):
 brew install temporal
 ```
 
+Or install with Snap:
+
+```bash
+snap install temporal
+```
+
 Or download from the CDN:
 
 - [Linux amd64](https://temporal.download/cli/archive/latest?platform=linux&arch=amd64)

docs/cli/workflow.mdx

@@ -105,7 +105,7 @@ Use the following options to change the behavior of this command. You can also u
 
 ## delete
 
-Delete a Workflow Executions and its Event History:
+Delete a Workflow Execution and its Event History:
 
 ```
 temporal workflow delete \

docs/cloud/billing-api.mdx

@@ -0,0 +1,130 @@
+---
+id: billing-api
+title: Cloud Billing API
+sidebar_label: Cloud Billing API
+description: The Temporal Cloud Billing API provides namespace-level cost attribution through on-demand billing reports.
+slug: /cloud/billing-api
+toc_max_heading_level: 4
+keywords:
+  - explanation
+tags:
+  - API
+  - Billing
+  - Temporal Cloud
+---
+
+The Temporal Cloud Billing API provides Namespace-level cost attribution through on-demand billing reports. 
+Reports are delivered in CSV format and can be accessed via API or downloaded directly for use in FinOps tooling and cost management platforms.  
+
+This API is part of the [Cloud Operations API](/ops).
+
+:::tip Support, stability, and dependency info
+
+The Temporal Cloud Billing API is in [Pre-release](/evaluate/development-production-features/release-stages#pre-release).
+
+:::
+
+The Billing API allows you to:
+
+- Generate billing reports for specified invoice months  
+- Retrieve report status and metadata  
+- Download CSV reports that can be fed into internal analytics tooling or cloud cost management platforms
+
+The Billing Report contains:
+
+- Accurate Namespace-level cost attribution  
+- Hourly granularity  
+- A [FOCUS](https://focus.finops.org/)-friendly data format
+
+For complete request and response schemas, refer to the Schema below.
+
+Billing report generation is **asynchronous**. You initiate report creation, then poll for completion.
+
+## Report data limitations
+
+For pre-release, reports can be generated with hourly granularity only, for the current billing month, and the previous billing month.
+
+## Allowed date ranges
+
+Date ranges must use billing-month boundaries (MM/YYYY). 
+Requests may include the current billing month. 
+The data in finalized reports includes usage up to `current_time` \- 24 hours (rounded up to nearest hour).
+
+## Rate limits and concurrency
+
+Rate limits apply to API usage. 
+
+### Per-account concurrency
+
+Within a single account:
+
+- Only one billing report per account is generated at a time  
+- Additional requests are accepted but queued  
+
+### Report Generation Latency
+
+Report generation time varies and is not guaranteed. Factors that affect it include the size of the requested date range and overall platform load.
+
+## Best practices
+
+Provide an idempotency key (`async_operation_id`) when retrying requests.  
+
+Poll `GetBillingReport` using exponential backoff.
+
+Download reports immediately after generation (URLs expire).
+
+Avoid frequent generation of large overlapping ranges in the current billing period.
+
+## Billing report schema
+
+Billing reports are delivered in CSV format.
+
+Each row represents a charge record.
+
+| Column Name | Description | Example |
+| ----- | ----- | ----- |
+| BillingAccountID | Temporal Cloud account ID | a2dd6 |
+| BillingAccountName | Temporal Cloud account name | temporal |
+| BillingCurrency | The currency an account is billed in | USD (cents) |
+| BillingPeriodEnd | The exclusive end bound of a billing period | 2024-02-01T00:00:00Z |
+| BillingPeriodStart | The inclusive start bound of a billing period | 2024-01-01T00:00:00Z |
+| ChargeCategory | The highest level classification of a charge based on how it is billed | Usage |
+| ChargeDescription | A self contained summary of the charge’s purpose | Actions \- Tier 1 |
+| ChargeFrequency | Indicates how often a charge will occur | Usage-Based |
+| ChargePeriodEnd | Time period end from when this charge took place, correlates to data granularity | 2025-10-01T01:00:00.000Z |
+| ChargePeriodStart | Time period start from when this charge took place, correlates to data granularity | 2025-10-01T00:00:00.000Z |
+| ContractedCost | Cost calculated by multiplying ContractedUnitPrice and PricingQuantity | 100.00 |
+| ContractedUnitPrice | The agreed-upon unit price for a single pricing unit of the associated SKU. Inclusive of negotiated discounts | 10.00 |
+| InvoiceID | The ID of the invoice for this billing period | in\_XXXXXXXXXXXXXXXXXXXX |
+| InvoiceIssuer | The entity responsible for issuing payable invoices | stripe |
+| PricingQuantity | The volume of a given SKU used or purchased | 10.00 |
+| PricingUnit | The measurement unit used for PricingQuantity | 1 Million Actions |
+| Provider | The provider of purchased resources or services | Temporal Technologies |
+| Publisher | The publisher of purchased resources or services | Temporal Technologies |
+| ResourceID | Namespace name \+ Temporal Cloud account ID | production.a2dd6 |
+| ResourceName | Namespace name \+ Temporal Cloud account ID | production.a2dd6 |
+| ResourceType | The type of resource the charge applies to | Namespace |
+| ServiceCategory | The highest level classification of a service based on the core function of the service | Temporal Cloud |
+| ServiceName | An offering that can be purchased from a provider | Temporal Cloud |
+| ServiceSubcategory | A secondary classification of the service category for a service based on its core function | Actions |
+| SKUID | A unique identifier that represents a specific SKU | essentials-actions |
+| SKUMeter | The functionality being metered or measured by a particular SKU in a charge | Actions |
+| Tags | Provider and customer defined tags associated with resources | `{"$tmprl_project":["project-id"],"namespace-tag-key":["namespace-tag-value"]}` |
+
+## Generate a report
+
+To generate a report, follow these steps:
+
+1. Create a billing report using `CreateBillingReport`. The response includes a `billing_report_id` and `async_operation_id`.
+1. Poll `GetBillingReport` using the `billing_report_id`  
+1. When the report state becomes `BILLING_REPORT_STATE_GENERATED`, retrieve the download URL  
+1. Download the report before the URL expires
+
+### Key identifiers
+
+| Identifier | Purpose |
+| ----- | ----- |
+| `billing_report_id` | Identifies the billing report and is used to retrieve metadata and download URLs |
+| `async_operation_id` | Identifies the background operation responsible for generating the report |
+
+The async operation follows the standard Cloud Operations async model (see [Async Operations](/ops#per-identity-rate-limits)).