Merge branch 'main' into fix-tcld-command-reference-grammar

Author: Duncanma

.github/skills/code-review/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: code-review
+description: >-
+  Review pull requests in the Temporal documentation repository against AGENTS.md
+  and docs style conventions. Use when reviewing docs, MDX, sidebar, redirect, or
+  Docusaurus changes in temporalio/documentation.
+---
+
+# Temporal documentation code review
+
+Review this PR as a Temporal docs change. Prefer concrete, actionable comments.
+Cite paths when asking for a fix. Do not nitpick optional style that Vale does not
+enforce in CI unless it hurts clarity or correctness.
+
+## Read these first (when relevant to the diff)
+
+| Topic | File |
+| ----- | ---- |
+| Agent / repo guidance | [AGENTS.md](../../../AGENTS.md) |
+| Where content belongs | [readme/INFORMATION-ARCHITECTURE.md](../../../readme/INFORMATION-ARCHITECTURE.md) |
+| Style | [readme/STYLE.md](../../../readme/STYLE.md) |
+| React components in MDX | [readme/COMPONENTS.md](../../../readme/COMPONENTS.md) |
+| Component → Markdown mapping | [readme/COMPONENT_REGISTRY.md](../../../readme/COMPONENT_REGISTRY.md) |
+| Mermaid | [readme/MERMAID.md](../../../readme/MERMAID.md) |
+| LLM Markdown pipeline | [MARKDOWN_PIPELINE.md](../../../MARKDOWN_PIPELINE.md) |
+| CI / automations | [readme/AUTOMATIONS.md](../../../readme/AUTOMATIONS.md) |
+
+## Must-check for every docs PR
+
+### Correctness and scope
+
+- Claims match current product behavior (no future promises unless tied to a version or release stage).
+- New or moved pages land in the right IA section.
+- Changing `id` or `slug` includes a `vercel.json` redirect plan.
+- Adding or moving pages updates `sidebars.js` and fixes inbound links when needed.
+- Draft PRs are appropriate when blocked on upstream/SDK/other-team work (see AGENTS.md Pull requests).
+
+### Temporal terminology (flag these)
+
+- Capitalize Temporal core terms as proper nouns (Workflow, Activity, Worker, Namespace, etc.).
+- Prefer **Temporal Service** over **Cluster** / **Temporal Cluster** in body prose (exceptions: Multi-Cluster Replication, code/config identifiers, CLI names).
+- Outside core terms, spell out "identifier." For core terms use `Id` (not `ID` / `id`), e.g. Workflow Id.
+- Prefer **use** over utilize/leverage; avoid filler and vague intensifiers (powerful, robust, seamless, unlock, streamline).
+
+### Headings and frontmatter
+
+- Headings: sentence case; prefer infinitive or questions; Develop pages use task-oriented headings.
+- Frontmatter: clear one-sentence `description`; match `tags` to siblings; do **not** add unused `keywords`.
+- Do not invent new tags/keywords unless this is a genuinely new feature area.
+
+### MDX and components
+
+- Prefer shared imports from `@site/src/components`.
+- Reuse existing components (`Tabs`, `SdkTabs`, `CaptionedImage`, etc.) instead of one-off HTML.
+- New public components should be exported from `src/components/index.js` when needed.
+- Check COMPONENTS.md / COMPONENT_REGISTRY.md before blessing a new pattern.
+
+### Code samples
+
+- Prefer Snipsync from CI-enabled sample repos when a matching snippet exists.
+- Snip edits belong in the **source** sample repo, then `yarn snipsync`.
+
+### Style / CI bar
+
+- CI-scoped Vale is the merge bar: `vale --config .vale-ci.ini` on touched files (Headings + RelativeLinks).
+- Do not require fixing the full Vale suggestion set unless the author opted into it.
+- Relative internal links preferred where Vale RelativeLinks applies.
+
+## Diff-type checklists
+
+### New or heavily rewritten MDX page
+
+- [ ] IA placement and sidebar entry
+- [ ] Redirects if URL changed
+- [ ] Terminology + headings + description
+- [ ] Components reused appropriately
+- [ ] Samples: Snipsync or justified docs-owned code
+
+### `sidebars.js` / navigation only
+
+- [ ] IDs resolve to real pages
+- [ ] Nesting and labels match section conventions
+
+### `vercel.json` redirects
+
+- [ ] Old public paths covered
+- [ ] Destinations are current canonical URLs
+
+### UI / React (`src/components`, theme, CSS)
+
+- [ ] Fits existing design system; no one-off layout inventions without need
+- [ ] Accessibility basics (labels, contrast) when relevant
+- [ ] Public exports updated if a new shared component is introduced
+
+### Config / build (`docusaurus.config.js`, plugins)
+
+- [ ] Internal footer/`to:` links are real routes (plugin-generated files like `/llms.txt` need absolute URLs or they break `onBrokenLinks: 'throw'`)
+
+## How to leave comments
+
+- Group related nits; lead with blockers (wrong term, broken URL, missing redirect/sidebar).
+- Separate **blocking** vs **suggestion**.
+- If unsure about product behavior, ask rather than inventing.
+
+## Out of scope for this skill
+
+- Rewriting the entire PR in review comments
+- Enforcing full Vale / Google style beyond AGENTS.md and CI-scoped rules

docs/best-practices/security-controls.mdx

@@ -118,7 +118,7 @@ Temporal Cloud Namespace has a [Retention Period](/temporal-service/temporal-ser
 
 ### Availability and Disaster Recovery
 
-Temporal Cloud’s platform is engineered for fault-tolerance out of the box, but you determine which Namespaces merit the very highest availability guarantees. Use the table below to decide when to turn on different High Availability models and how to operationalise them.
+Temporal Cloud’s platform is engineered for fault-tolerance out of the box, but you determine which Namespaces merit the very highest availability guarantees. Use the table below to decide when to turn on different High Availability models and how to operationalize them.
 
 | Namespace scope | Use Case | Uptime SLA | Recovery Time Objective (RTO) | Recovery Point Objective (RPO) |
 |-----------------|----------|------------|--------------------------------|--------------------------------|

docs/cloud/audit-logs.mdx

@@ -197,7 +197,7 @@ An Audit Log can be viewed in the Temporal Cloud UI.
 1. In the Temporal Cloud UI, select **Settings**.
 1. On the **Settings** page, select **Audit Logs**.
 
-Up to 1000 events can be downloaded from the Audit Log UI to a local file.
+Up to 1,000 events can be downloaded from the Audit Log UI to a local file.
 
 ## Access an Audit Log via API {/* #audit-log-api */}
 

docs/cloud/manage-access/custom-roles.mdx

@@ -313,7 +313,7 @@ temporal cloud custom-role create --spec @role.json
 
 Once you have created a Custom Role, it is available on the Identities page to assign to a user or group, the same as
 the pre-defined Temporal permissions. See
-[How to update an account-level role in Temporal Cloud](/cloud/manage-access/users#update-roles) for more inforamtion.
+[How to update an account-level role in Temporal Cloud](/cloud/manage-access/users#update-roles) for more information.
 
 ## Modifying a Custom Role
 

docs/cloud/projects.mdx

@@ -114,7 +114,7 @@ In Temporal Cloud UI:
   </TabItem>
   <TabItem value="cloud-api" label="Cloud Operations API">
 
-The process for createing a [Namespace](/cloud/namespaces#create-a-namespace), [Nexus Endpoint](/nexus/registry#view-and-manage-nexus-endpoints), or [Connectivity Rule](/cloud/connectivity#creating-a-connectivity-rule) with the Cloud Operations API is the same as the standard process for creating those resources, with the addition of the `projectId` for the Project in which you're creating the resource.
+The process for creating a [Namespace](/cloud/namespaces#create-a-namespace), [Nexus Endpoint](/nexus/registry#view-and-manage-nexus-endpoints), or [Connectivity Rule](/cloud/connectivity#creating-a-connectivity-rule) with the Cloud Operations API is the same as the standard process for creating those resources, with the addition of the `projectId` for the Project in which you're creating the resource.
 
 
 Use the

docs/design-patterns/continue-as-new.mdx

@@ -359,7 +359,7 @@ This approach is more reliable than a fixed iteration count because it accounts
 
 The Continue-As-New pattern is a good fit for periodic Workflows running indefinitely (cron-like behavior), processing unbounded data streams, long-running Workflows with repetitive patterns, Workflows that accumulate state over many iterations, and preventing event history from growing too large.
 
-It is not a good fit for short-lived Workflows (under 1000 events), Workflows that naturally complete, one-time batch processing, or Workflows that require full history for audit purposes.
+It is not a good fit for short-lived Workflows (under 1,000 events), Workflows that naturally complete, one-time batch processing, or Workflows that require full history for audit purposes.
 
 ## Benefits and trade-offs
 

docs/design-patterns/entity-workflow.mdx

@@ -552,7 +552,7 @@ Trade-offs:
 - [Safe Message Handlers](https://github.com/temporalio/samples-go/tree/main/safe_message_handler) — Entity Workflow with Updates, Signals, and Continue-As-New.
 
 **Java:**
-- [Safe Message Handlers](https://github.com/temporalio/samples-java/tree/main/core/src/main/java/io/temporal/samples/safemessagehandler) — Entity Workflow with Updates, Signals, and Continue-As-New.
+- [Safe Message Handlers](https://github.com/temporalio/samples-java/tree/main/core/src/main/java/io/temporal/samples/safemessagepassing) — Entity Workflow with Updates, Signals, and Continue-As-New.
 
 **TypeScript:**
 - [Safe Message Handlers](https://github.com/temporalio/samples-typescript/tree/main/message-passing/safe-message-handlers) — Entity Workflow with Updates, Signals, and Continue-As-New.

docs/develop/dotnet/workflows/message-passing.mdx

@@ -30,7 +30,7 @@ This page introduces these features for the Temporal .NET SDK.
 ## Write message handlers {/* #writing-message-handlers */}
 
 :::info
-The code that follows is part of a [working solution](https://github.com/temporalio/samples-dotnet/tree/main/src/MessagePassing).
+The code that follows is part of a [working solution](https://github.com/temporalio/samples-dotnet/tree/main/src/SafeMessageHandlers).
 :::
 
 Follow these guidelines when writing your message handlers:

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

@@ -108,9 +108,7 @@ follow. Only the driver setup differs between the two. Everything after that is
     [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials).
 
     <!--SNIPSTART go-gcs-driver-create-->
-
     [features/snippets/external_storage/gcs_setup/gcs_driver_create.go](https://github.com/temporalio/features/blob/main/features/snippets/external_storage/gcs_setup/gcs_driver_create.go)
-
     ```go
     gcsClient, err := storage.NewClient(context.Background())
     if err != nil {
@@ -125,7 +123,6 @@ follow. Only the driver setup differs between the two. Everything after that is
     	log.Fatalf("create GCS driver: %v", err)
     }
     ```
-
     <!--SNIPEND-->
 
            </TabItem>
@@ -139,9 +136,7 @@ follow. Only the driver setup differs between the two. Everything after that is
     driver:
 
     <!--SNIPSTART go-s3-external-storage-setup-->
-
     [features/snippets/external_storage/s3_setup/s3_external_storage_setup.go](https://github.com/temporalio/features/blob/main/features/snippets/external_storage/s3_setup/s3_external_storage_setup.go)
-
     ```go
     c, err := client.Dial(client.Options{
     	HostPort: "localhost:7233",
@@ -156,7 +151,6 @@ follow. Only the driver setup differs between the two. Everything after that is
 
     w := worker.New(c, "my-task-queue", worker.Options{})
     ```
-
     <!--SNIPEND-->
 
     A Worker inherits this configuration from the Client it is created with. When your Workers run in their own process,
@@ -189,9 +183,7 @@ The following example shows a custom driver that uses local disk as the backing
 development and testing only. In production, use a durable storage system that is accessible to all Workers:
 
 <!--SNIPSTART go-custom-storage-driver-->
-
 [features/snippets/external_storage/custom_driver/custom_storage_driver.go](https://github.com/temporalio/features/blob/main/features/snippets/external_storage/custom_driver/custom_storage_driver.go)
-
 ```go
 type LocalDiskStorageDriver struct {
 	storeDir string
@@ -270,7 +262,6 @@ func (d *LocalDiskStorageDriver) Retrieve(
 	return payloads, nil
 }
 ```
-
 <!--SNIPEND-->
 
 The following sections walk through the key parts of the driver implementation.
@@ -332,9 +323,7 @@ the threshold stay inline in Event History. The size compared against the thresh
 which includes its metadata, not just your data.
 
 <!--SNIPSTART go-external-storage-threshold-->
-
 [features/snippets/external_storage/threshold/threshold_config.go](https://github.com/temporalio/features/blob/main/features/snippets/external_storage/threshold/threshold_config.go)
-
 ```go
 c, err := client.Dial(client.Options{
 	ExternalStorage: converter.ExternalStorage{
@@ -343,7 +332,6 @@ c, err := client.Dial(client.Options{
 	},
 })
 ```
-
 <!--SNIPEND-->
 
 ## Use multiple storage drivers
@@ -370,9 +358,7 @@ The following example registers two drivers but always selects `preferredDriver`
 only registered so the Worker can retrieve payloads that were previously stored with it:
 
 <!--SNIPSTART go-external-storage-multiple-drivers-->
-
 [features/snippets/external_storage/multiple_drivers/multiple_drivers.go](https://github.com/temporalio/features/blob/main/features/snippets/external_storage/multiple_drivers/multiple_drivers.go)
-
 ```go
 type PreferredSelector struct {
 	preferred converter.StorageDriver
@@ -392,7 +378,6 @@ func MultipleDriversSetup(preferredDriver, legacyDriver converter.StorageDriver)
 	}
 }
 ```
-
 <!--SNIPEND-->
 
 ## Multi-region durability with Amazon S3

docs/develop/php/activities/asynchronous-activity.mdx

@@ -85,7 +85,7 @@ There are two parts to implementing an asynchronously completed Activity:
 The following example demonstrates the first part:
 
 <!--SNIPSTART samples-php-async-activity-completion-activity-class-->
-[app/src/AsyncActivityCompletion/GreetingActivity.php](https://github.com/temporalio/samples-php/blob/main/app/src/AsyncActivityCompletion/GreetingActivity.php)
+[app/src/AsyncActivityCompletion/GreetingActivity.php](https://github.com/temporalio/samples-php/blob/master/app/src/AsyncActivityCompletion/GreetingActivity.php)
 ```php
 class GreetingActivity implements GreetingActivityInterface
 {
@@ -118,7 +118,7 @@ class GreetingActivity implements GreetingActivityInterface
 The following code demonstrates how to complete the Activity successfully using `WorkflowClient`:
 
 <!--SNIPSTART samples-php-async-activity-completion-completebytoken-->
-[app/src/AsyncActivityCompletion/CompleteCommand.php](https://github.com/temporalio/samples-php/blob/main/app/src/AsyncActivityCompletion/CompleteCommand.php)
+[app/src/AsyncActivityCompletion/CompleteCommand.php](https://github.com/temporalio/samples-php/blob/master/app/src/AsyncActivityCompletion/CompleteCommand.php)
 ```php
 $client = $this->workflowClient->newActivityCompletionClient();
 // Complete the Activity.