Merge branch 'main' into codex/workflow-pause-docs

Author: Duncanma

.gitignore

@@ -22,8 +22,6 @@ temp/
 .env.test.local
 .env.production.local
 .vs
-AGENTS.md
-CLAUDE.md
 .claude/*
 .omc
 

AGENTS.md

@@ -0,0 +1,151 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in the [Temporal documentation](https://github.com/temporalio/documentation) repository.
+
+## Read these first
+
+| Topic | File |
+|-------|------|
+| Where content belongs | [INFORMATION-ARCHITECTURE.md](./INFORMATION-ARCHITECTURE.md) |
+| React components in MDX | [COMPONENTS.md](./COMPONENTS.md) |
+| LLM Markdown pipeline | [MARKDOWN_PIPELINE.md](./MARKDOWN_PIPELINE.md) |
+| Component → Markdown mapping | [COMPONENT_REGISTRY.md](./COMPONENT_REGISTRY.md) |
+
+## Repository overview
+
+- **Site:** Docusaurus static site for [docs.temporal.io](https://docs.temporal.io).
+- **Content:** MDX files under `docs/`. URLs are served at the site root (`/workflows`), not under `/docs/`.
+- **UI code:** React components in `src/components/`. Sidebar navigation is in `sidebars.js`.
+- **Redirects:** Legacy URL changes go in `vercel.json` before or alongside file moves.
+
+## Where to put content
+
+Use [INFORMATION-ARCHITECTURE.md](./INFORMATION-ARCHITECTURE.md) to choose the section. 
+
+## Style Guide
+
+Follow [STYLE.md](./STYLE.md) and Vale rules in `vale/styles/`. The most common mistakes:
+
+### Temporal terms are proper nouns
+
+Capitalize Temporal core terms. Do not capitalize generic uses.
+
+- Correct: "Register the Activity in the Workflow."
+- Incorrect: "Register the activity in the workflow."
+
+Vale enforces many substitutions automatically. See `vale/styles/Temporal/terms.yml`.
+
+### Temporal Service, not Cluster
+
+In body prose, use **Temporal Service**, not **Cluster** or **Temporal Cluster**.
+
+- Correct: "The Worker polls the Temporal Service for tasks."
+- Incorrect: "The Worker polls the Cluster for tasks."
+
+Exceptions: **Multi-Cluster Replication**, code/config identifiers, and CLI command names.
+
+### Identifier abbreviation
+
+Outside Temporal core terms, spell out "identifier." For core terms, use `Id` (not `ID` or `id`).
+
+- Correct: "Provide an order identifier as a Workflow Id."
+- Incorrect: "Provide an order ID as a Workflow ID."
+
+In code blocks, follow each language's conventions.
+
+### Headings
+
+- Use **sentence case**: "How to get started with Temporal"
+- Prefer **infinitive verb forms** or questions: "How to install Temporal", not "Installing Temporal"
+- Develop pages: task-oriented headings ("Start a Workflow Execution")
+
+### Writing style
+
+Follow [STYLE.md](./STYLE.md) and the [Google developer documentation style guide](https://developers.google.com/style) for tone (conversational, second person, active voice) and structure (short paragraphs, one idea per sentence). A few additions specific to model output:
+
+- Cut filler that adds no information: "it's worth noting that," "in order to," "simply," "easily," "just." 
+- Avoid vague intensifiers doing the work a specific fact should do: "powerful," "robust," "seamless," "cutting-edge," "leverage" (use "use"), "unlock," "elevate," "streamline." Replace with what the thing actually does.
+- Don't pad a page to look thorough. Prefer brevity over overly-verbose paragraphs. 
+- Do not add emojis to documentation prose and use em-dashes sparingly. 
+
+### Word choice
+
+Prefer common, concrete verbs and nouns.
+
+| Prefer | Instead of |
+|--------|------------|
+| use | utilize, leverage |
+| help | facilitate |
+| to | in order to |
+| many | numerous, various (when you can be specific, be specific) |
+
+### Tense and time
+
+Document current behavior. Don't make future promises. Tie claims to a version, release note, or release stage when that matters.
+
+| Prefer | Instead of |
+|--------|------------|
+| Temporal Server v1.31.0 and later supports Cassandra 5.0.4 and later. | A future release will support Cassandra 5. |
+
+## Frontmatter
+
+Typical fields:
+
+```yaml
+---
+id: page-id
+title: Page title
+sidebar_label: Short label
+description: One sentence for SEO and previews.
+keywords:
+  - keyword
+tags:
+  - Concepts
+---
+```
+
+- Write `description` as a single clear sentence.
+- Do not change `id` or `slug` without a redirect plan.
+- Match `tags` and `keywords` to sibling pages in the same section.
+- Use existing concepts and keywords. Don't add new ones unless it's a new feature.
+
+## MDX and components
+
+- Pages are `.mdx` with YAML frontmatter (see [Frontmatter](#frontmatter) above).
+- Import shared components from `@site/src/components` unless a page uses a one-off import path already established nearby.
+- Before adding a component, check [COMPONENTS.md](./COMPONENTS.md) and [COMPONENT_REGISTRY.md](./COMPONENT_REGISTRY.md).
+- Reuse existing components (`Tabs`, `SdkTabs`, `CaptionedImage`, `ViewSourceCodeNotice`, etc.) instead of inventing inline HTML patterns.
+- Interactive demos live in `src/components/elements/`. Export new public components from `src/components/index.js` when needed.
+
+
+## URLs and navigation
+
+Adding or moving pages usually requires:
+
+- Updating `sidebars.js` for navigation placement
+- Adding redirects in `vercel.json` when the public URL changes
+- Fixing internal links across the repo
+
+## Code samples and Snipsync
+
+- Prefer code extracted from CI-enabled sample repos via [Snipsync](https://github.com/temporalio/snipsync).
+- Snippets are wrapped in `<!--SNIPSTART id-->` / `<!--SNIPEND-->`. Edit the **source repo** named inside the wrapper, then run `yarn snipsync`.
+
+## Commands
+
+Requires Node.js 24+ and Yarn.
+
+```bash
+yarn              # Install dependencies
+yarn start        # Dev server at http://localhost:3000
+yarn build        # Production build; catches MDX/build errors
+yarn check-links  # Broken link check (run after build)
+yarn snipsync     # Refresh Snipsync code snippets
+```
+
+Vale linting (style):
+
+```bash
+yarn lint:py      # Example: lint Python SDK docs
+yarn vale         # Full Vale run via assembly script
+```

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

STYLE.md

@@ -21,6 +21,32 @@ Do not capitalize generic versions of Temporal terms. Use generic versions spari
 
 - Incorrect: "Next, register the activity within the workflow."
 
+#### Temporal Service, not Cluster
+
+In body prose, refer to the Temporal backend as **Temporal Service**, not **Cluster** or **Temporal Cluster**.
+
+- Correct: "Connect your Temporal Client to the Temporal Service."
+- Incorrect: "Connect your Temporal Client to the Temporal Cluster."
+
+This applies to running instances you operate or connect to ("your Temporal Service", "the Temporal Service", "across the Temporal Service").
+
+Exceptions:
+
+- **Multi-Cluster Replication** and other compound terms that include "Cluster" as part of an official name.
+- Code, configuration keys, file paths, CLI commands, and API identifiers (for example, `tctl cluster`, `cluster.pem`).
+- Quoting third-party or historical text where the source uses "Cluster".
+
+#### Word choice
+
+Prefer common, concrete verbs and nouns.
+
+| Prefer | Instead of |
+|--------|------------|
+| use | utilize, leverage |
+| help | facilitate |
+| to | in order to |
+| many | numerous, various (when you can be specific, be specific) |
+
 #### Abbreviation of "identifier"
 
 Do not abbreviate the word "identifier" as "ID", "Id", or "id" unless it's part of a Temporal core term. For core terms, the correct abbreviation is "Id", such as in "Workflow Id" or "Activity Id".

docs/best-practices/managing-aps-limits.mdx

@@ -207,6 +207,7 @@ Use Provisioned capacity when the on-demand model can't respond quickly enough:
 
 :::note
 When switching back to on-demand mode, your APS limit resets to the running average from the last 7 days.
+If Temporal Support has set a custom limit for your Namespace, that limit is preserved across the switch.
 Plan for this if your workload is sensitive to the transition.
 :::
 

docs/cloud/capacity-modes.mdx

@@ -100,7 +100,7 @@ Actions that are external to the core Temporal service do not contribute to your
 ## On-Demand Capacity {/* #on-demand-capacity */}
 
 Using On-Demand Capacity, your rate limit grows automatically along with your usage.
-Each Namespace has an Actions per second (APS), Requests per second (RPS), and Operations per second (OPS) limit that scales automatically with usage. Your APS limit never falls below its [default limit](/cloud/limits#actions-per-second).
+Each Namespace has an Actions per second (APS), Requests per second (RPS), and Operations per second (OPS) limit that scales automatically with usage. Your APS limit never falls below its [default limit](/cloud/limits#actions-per-second). If Temporal Support has manually set your Namespace's limit, that value becomes your floor in place of the default, and it persists across capacity mode changes.
 
 Scaling automatically adjusts based on the lesser of 4 * APS Average or 2 * APS P90 over the past 7 days.
 
@@ -180,6 +180,10 @@ For the metrics to watch and how to alert on utilization, see [Provisioned capac
 Capacity Modes and TRUs can be set via the Temporal Cloud UI, CLI, or API. 
 Capacity modes can be set and adjusted by Global Admin and Namespace Admin. 
 
+When you switch to Provisioned Capacity, your limit is set by the number of TRUs you select.
+When you switch back to On-Demand, your limit is recalculated from the trailing 7-day usage formula and never falls below your floor.
+If Temporal Support has set a custom limit for your Namespace, that limit is your floor, so switching to Provisioned and back to On-Demand preserves it.
+
 ### Setting Capacity Modes from the UI
 
 You can set Capacity Modes for an individual Namespace by navigating to the Namespace page in the Temporal Cloud UI (`https://cloud.temporal.io/namespaces/<Namespace ID>`).