Merge branch 'main' into patch-3

Author: brianmacdonald-temporal

.gitignore

@@ -25,6 +25,7 @@ temp/
 AGENTS.md
 CLAUDE.md
 .claude/*
+.omc
 
 npm-debug.log*
 yarn-debug.log*

docs/cli/activity.mdx

@@ -27,7 +27,7 @@ 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) and [Python](/docs/develop/python/standalone-activities.mdx) Standalone Activity guides.
+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
 

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)).

docs/cloud/get-started/billing-and-cost.mdx

@@ -24,24 +24,28 @@ tags:
 import * as Components from '@site/src/components';
 
 Temporal strives to provide full transparency over billing and costs.
-Account Owners and Finance Admins can view their [detailed billing information](https://cloud.temporal.io/billing) at any time.
 Use this information to assess your spending patterns, inspect your credit ledger, check your invoice histories, update payment details,
 and manage your current plan as needed.
-You can see namespace-level cost estimates on the [usage dashboard](https://cloud.temporal.io/usage).
 
 For more information on current Temporal Cloud pricing for Actions, storage, and services/support, please visit our [Pricing](/cloud/pricing) page.
 
-The [billing](https://cloud.temporal.io/billing) page includes the following information.
-If you're not on a standard plan, your billing page may show a subset of this list:
+Temporal Provides multiple ways to view your usage and billing data:
 
-- [Current balance](#current-balance): Your balance to date for this billing cycle
-- [Recent bill](#recent-bill): The amount of your most recent bill
-- [Invoice history](#invoice): Access to all past invoices
-- [Credit ledger](#credit-table): A record of all credit related transactions including details on credit grants, purchases, usage, and remaining credits, if applicable
-- [Plan](#plans): Your current plan, consumption pricing, and entitlements, with the ability to manage upgrades and downgrades, payment method, and account deletion
+- [Billing Center](https://cloud.temporal.io/billing) allows you to see summary invoices and credits, manage plans, and delete your accounts.
+    - Coming soon: Billing dashboard enhancements to visualize billing by Namespace over time
+    - Viewable by Account Owners and Finance Admin
+- [Usage Dashboards](https://cloud.temporal.io/usage) allow you to monitor Namespace level usage over time.
+    - Coming soon: Additional granularity based on Action Types, grouping by Tags, and grouping by Projects
+    - Viewable by Account Owners, Finance Admin, Global Admin on an account level. Namespace level usage is visible on the Namespace pages to those with access.
+- [Billing API](/cloud/billing-api) allow you to access billing information on a Namespace basis down to an hourly granularity, enriched with Tags and Projects.
+The Billing API provides a FOCUS-guided data format that can be ingested into your cloud cost management platform or analytics tooling, or downloaded as a CSV.
+    - Viewable by Account Owners, Finance Admin
 
-The [Usage](https://cloud.temporal.io/usage) page shows the cost breakdown by Namespace.
-If your organization separates projects by Namespace -- for architectural reasons, for development/production differentiation, for different products, etc -- you can view individual costs for each Namespace.
+:::tip Support, stability, and dependency info
+
+The Temporal Cloud Billing API is in [Pre-release](/evaluate/development-production-features/release-stages#pre-release).
+
+:::
 
 ## Current balance {#current-balance}
 

docs/cloud/high-availability/failovers.mdx

@@ -55,7 +55,8 @@ For more control over the failover process, you can [disable automated failovers
 
 :::tip
 
-You can test the failover of Namespace with High Availability features by manually triggering a failover using the UI or the 'tcld' CLI utility.
+You can test the failover of a Namespace with High Availability features by manually triggering a failover using the Web UI, the tcld CLI, or the Cloud Ops API.
+The Terraform provider does not support triggering failovers.
 In most scenarios, we recommend you let Temporal handle failovers for you.
 
 After failover, be aware of the following points:
@@ -193,6 +194,14 @@ A forced failover when there is a significant replication lag has a higher likel
 ### Trigger the failover {#manual-failovers}
 
 You can trigger a failover manually using the Temporal Cloud Web UI, the tcld CLI, or the Cloud Ops API, depending on your preference and setup.
+
+:::info Terraform not supported
+
+The [Temporal Cloud Terraform provider](https://registry.terraform.io/providers/temporalio/temporalcloud/latest) does not support triggering failovers.
+You must use the Web UI, tcld CLI, or Cloud Ops API.
+
+:::
+
 The following instructions outline the steps for each method:
 
 <Tabs>

docs/cloud/worker-health.mdx

@@ -382,12 +382,79 @@ Workers, the Server can obtain an accurate count of Workers, understand Worker p
 
 Use the Temporal CLI to view information about all Workers connected to Temporal Server. Use `temporal worker describe` to see details of a specific Worker. Use `temporal worker list` to get a complete list of all connected Workers.
 
-If you wish to disable Worker heartbeating (features above will not work with this feature disabled) or set heartbeating to be more frequent than every 60 seconds (allowed range is 1s to 60s), set the configuration relevant to your SDK.
+If you wish to disable Worker heartbeating or set heartbeating to be more frequent than every 60 seconds (allowed range is 1s to 60s), set the configuration relevant to your SDK. The server needs Worker heartbeating to understand Worker status accurately. Disabling the Worker heartbeat will cause features that provide the list of active Workers and information about those Workers to show missing or inaccurate information.
 <SdkTabs hideUnsupportedLanguages>
+<SdkTabs.Go>
+
+_Available since Go SDK v1.41.0_
+
+Set the `WorkerHeartbeatInterval` field on [`client.Options`](https://pkg.go.dev/go.temporal.io/sdk/client#Options) to adjust the heartbeat interval.
+Set it to a negative value to disable heartbeating.
+
+#### Enable host resource reporting
+
+By default, the Go SDK reports `0` for CPU and memory usage in Worker heartbeats.
+To enable host resource reporting, provide a `SysInfoProvider` when creating your Worker.
+You must use a resource based tuner to enable host resource reporting.
+
+The SDK includes a [gopsutil](https://github.com/shirou/gopsutil)-based implementation via the [sysinfo](https://pkg.go.dev/go.temporal.io/sdk/contrib/sysinfo) library that supports cgroup metrics in containerized Linux environments:
+
+```go
+import (
+    "log"
+    
+    "go.temporal.io/sdk/client"
+    "go.temporal.io/sdk/contrib/envconfig"
+    "go.temporal.io/sdk/contrib/sysinfo"
+    "go.temporal.io/sdk/worker"
+)
+
+c, err := client.Dial(envconfig.MustLoadDefaultClientOptions())
+if err != nil {
+	log.Fatalln("Unable to create client", err)
+}
+defer c.Close()
+tuner, err := worker.NewResourceBasedTuner(worker.ResourceBasedTunerOptions{
+	TargetMem:    0.8,
+	TargetCpu:    0.9,
+	InfoSupplier: sysinfo.SysInfoProvider(),
+})
+w := worker.New(c, "my-task-queue", worker.Options{
+	Tuner:                      tuner,
+})
+```
+
+You can also implement the `worker.SysInfoProvider` interface to provide your own resource metrics.
+
+</SdkTabs.Go>
 <SdkTabs.Python>
+
+_Available since Python SDK v1.20.0_
+
 Use `TelemetryConfig()` to adjust heartbeat settings. See the [Python SDK documentation](https://python.temporal.io/temporalio.bridge.runtime.RuntimeOptions.html#worker_heartbeat_interval_millis) for more details.
+
 </SdkTabs.Python>
+<SdkTabs.TypeScript>
+
+_Available since TypeScript SDK v1.14.0_
+
+Set the `workerHeartbeatInterval` property on [`RuntimeOptions`](https://typescript.temporal.io/api/interfaces/worker.RuntimeOptions) to adjust the heartbeat interval.
+Set it to `0` to disable heartbeating.
+
+</SdkTabs.TypeScript>
+<SdkTabs.DotNet>
+
+_Available since .NET SDK v1.10.0_
+
+Set the `WorkerHeartbeatInterval` property on [`TemporalRuntimeOptions`](https://dotnet.temporal.io/api/Temporalio.Runtime.TemporalRuntimeOptions.html) to adjust the heartbeat interval.
+Set it to `null` to disable heartbeating.
+
+</SdkTabs.DotNet>
 <SdkTabs.Ruby>
+
+_Available since Ruby SDK v1.1.0_
+
 Add configurations to `Runtime()` to adjust heartbeat settings. See the [Ruby SDK documentation](https://ruby.temporal.io/Temporalio/Runtime.html) for more details.
+
 </SdkTabs.Ruby>
 </SdkTabs>

docs/develop/dotnet/core-application.mdx

@@ -84,6 +84,60 @@ This means there are several things Workflows cannot do such as:
 Some calls in .NET do unsuspecting non-deterministic things and are easy to accidentally use.
 This is especially true with `Task`s.
 Temporal requires that the deterministic `TaskScheduler.Current` is used, but many .NET async calls will use `TaskScheduler.Default` implicitly (and some analyzers even encourage this).
+
+The following sections cover replay-safe APIs, followed by .NET-specific `Task` gotchas.
+
+#### Logging
+
+Use [`Workflow.Logger`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html#Temporalio_Workflows_Workflow_Logger), which is an instance of .NET's `ILogger`. The SDK logger automatically suppresses log messages during replay to avoid duplicates:
+
+```csharp
+Workflow.Logger.LogInformation("Starting workflow for {Name}", name);
+```
+
+For logger configuration, see [Observability: Logging](/develop/dotnet/observability#logging).
+
+#### Random numbers and UUIDs
+
+Use [`Workflow.Random`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html#Temporalio_Workflows_Workflow_Random) to get a deterministic `Random` instance. For UUIDs, use [`Workflow.NewGuid()`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html#Temporalio_Workflows_Workflow_NewGuid). Never use `System.Random` or `Guid.NewGuid()` directly:
+
+```csharp
+// Good - deterministic across replays
+var value = Workflow.Random.Next(1, 100);
+var uniqueId = Workflow.NewGuid();
+
+// Bad - different result on every replay
+var value = new Random().Next(1, 100);
+```
+
+#### Current time
+
+Use [`Workflow.UtcNow`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html#Temporalio_Workflows_Workflow_UtcNow) instead of `DateTime.UtcNow`. The SDK returns the time of the last Workflow Task, which is consistent across replays:
+
+```csharp
+var currentTime = Workflow.UtcNow;
+```
+
+#### Detecting replay (advanced)
+
+Use [`Workflow.Unsafe.IsReplaying`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.Unsafe.html#Temporalio_Workflows_Workflow_Unsafe_IsReplaying) to guard code that should only run on the first execution, such as emitting metrics or sending external notifications from an Interceptor.
+:::caution
+
+Never use this to affect Workflow business logic — branching on replay status breaks determinism.
+
+:::
+
+```csharp
+if (!Workflow.Unsafe.IsReplaying)
+{
+    EmitMetric("workflow_started", 1);
+}
+```
+
+If your goal is to always take action when something new is happening, check that `Workflow.Unsafe.IsReplayingHistoryEvents` is false instead. This will be false during read-only operations like queries and update validators. This is what the SDK's built-in logger and metric meter use internally.
+
+#### .NET Task gotchas
+
 Here are some known gotchas to avoid with .NET tasks inside of Workflows:
 
 - Do not use `Task.Run` - this uses the default scheduler and puts work on the thread pool.

docs/develop/dotnet/index.mdx

@@ -69,6 +69,14 @@ Connect to a Temporal Service and start a Workflow Execution.
 - [Get Workflow results](/develop/dotnet/temporal-client#get-workflow-results): Retrieve and process the results of your
   Workflows efficiently.
 
+## [Standalone Activities](/develop/dotnet/standalone-activities)
+
+Execute Activities independently without a Workflow using the Temporal Client.
+
+- [How to execute a Standalone Activity](/develop/dotnet/standalone-activities#execute-activity)
+- [How to start a Standalone Activity without waiting](/develop/dotnet/standalone-activities#start-activity)
+- [How to get a handle to an existing Standalone Activity](/develop/dotnet/standalone-activities#get-activity-handle)
+
 ## [Testing](/develop/dotnet/testing-suite)
 
 Set up the testing suite and test Workflows and Activities.

docs/develop/dotnet/message-passing.mdx

@@ -37,8 +37,7 @@ Follow these guidelines when writing your message handlers:
 
 - Message handlers are defined as methods on the Workflow class, using one of the three attributes: [`WorkflowQueryAttribute`](https://dotnet.temporal.io/api/Temporalio.Workflows.WorkflowQueryAttribute.html), [`WorkflowSignalAttribute`](https://dotnet.temporal.io/api/Temporalio.Workflows.WorkflowSignalAttribute.html), and [`WorkflowUpdateAttribute`](https://dotnet.temporal.io/api/Temporalio.Workflows.WorkflowUpdateAttribute.html).
 - The parameters and return values of handlers and the main Workflow function must be [serializable](/dataconversion).
-- Prefer data classes to multiple input parameters.
-  Data class parameters allow you to add fields without changing the calling signature.
+- Prefer data classes to multiple input parameters. Data class parameters allow you to add fields without changing the calling signature. Keep in mind that serialization and deserialization can fail with the default data converter if the new field does not have a default value.
 
 ### Query handlers {#queries}