Merge branch 'main' into java-workflow-streams

Author: flippedcoder

.github/workflows/mermaid-ci.yml

@@ -0,0 +1,33 @@
+name: Mermaid CI
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "scripts/lint-mermaid.mjs"
+      - "package.json"
+      - "yarn.lock"
+      - ".github/workflows/mermaid-ci.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  mermaid:
+    name: Validate Mermaid syntax
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Setup Node.js Environment
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "24"
+          cache: "yarn"
+
+      - name: Install Dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Lint Mermaid Diagrams
+        run: yarn lint:mermaid

.github/workflows/update-custom-role-permissions.yml

@@ -28,7 +28,7 @@ jobs:
           token: ${{ steps.generate_token.outputs.token }}
 
       - name: Setup Node
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v6.4.0
         with:
           node-version: '20'
 

.github/workflows/vale-ci.yml

@@ -22,4 +22,7 @@ jobs:
           level: info
           filter_mode: diff_context
           fail_on_error: false
+          # Scope linting to docs only; do not put the path in vale_flags —
+          # the action runs `vale ${vale_flags} sync`, so a path there breaks sync.
+          files: docs
           vale_flags: "--config=.vale-ci.ini"

.gitignore

@@ -22,8 +22,6 @@ temp/
 .env.test.local
 .env.production.local
 .vs
-AGENTS.md
-CLAUDE.md
 .claude/*
 .omc
 
@@ -55,3 +53,4 @@ test-results/*
 screenshots
 # Ignore cookbook recipes since they are synced from the remote repo
 ai-cookbook
+scripts/mermaid-compare/*

AGENTS.md

@@ -0,0 +1,152 @@
+# 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) |
+| Mermaid diagrams | [MERMAID.md](./readme/MERMAID.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

COMPONENTS.md

@@ -20,12 +20,10 @@ Whether you’re using core components or experimenting with new ones, this guid
 - [Using Components in MDX Source Files](#using-components-in-mdx-source-files)
 - [Using IntegrationsGrid](#using-integrationsgrid)
 - [Using CaptionedImage](#using-captionedimage)
-- [Using DiscoverableDisclosure](#using-discoverabledisclosure)
 - [Using DocsTable](#using-docstable)
 - [Using PhotoCarousel](#using-photocarousel)
 - [Using RelatedRead](#using-relatedread)
 - [Using ToolTipTerm](#using-tooltipterm)
-- [Using ZoomingImage](#using-zoomingimage)
 - [Using SdkGuideLinks](#using-sdkguidelinks)
 - [Using ReleaseNoteHeader](#using-release-note-header)
 
@@ -118,9 +116,9 @@ import * as Components from '@site/src/components';
 Components imported this way use the "Components." prefix before their name:
 
 ```
-<Components.DiscoverableDisclosure>
+<Components.RelatedRead>
 ...Content that is folded away...
-</Components.DiscoverableDisclosure>
+</Components.RelatedRead>
 ```
 
 ## Using IntegrationsGrid
@@ -155,7 +153,7 @@ For example, the Python SDK integrations page pre-filters to Python:
 <IntegrationsGrid defaultSdks={["Python"]} />
 ```
 
-Valid SDK values are `"Java"`, `"Python"`, `"TypeScript"`, and `"Ruby"`.
+Valid SDK values are `"Go"`, `"Java"`, `"Python"`, `"TypeScript"`, and `"Ruby"`.
 
 ### Filter behavior
 
@@ -253,23 +251,6 @@ One click will zoom out, another will zoom back.
 Most rendering will allow readers to pull the image around to view all parts of the image. 
 On non-mobile systems, cursors will change to interactive elements when hovered above zoomable items to indicate interaction.
 
-## Using DiscoverableDisclosure
-
-Role: Provide a more discoverable `<Details>` section.
-
-Unlike Details, it does not require a separate `<Summary>`.
-
-Usage:
-
-```
-<DiscoverableDisclosure label = "your_summary_text">
-...your content...
-</DiscoverableDisclosure>
-```
-
-An additional `prompt` prop enables you to specify the leading text.
-Normally it defaults to `prompt = "Dive deeper — "`.
-
 ## Using DocsTable
 
 In certain rare instances, standard Markdown tables won't work for our needs.
@@ -442,25 +423,6 @@ Use the `tooltip` prop to add non-reusable content specific to one tooltip term.
 <Components.ToolTipTerm term="your term" tooltip="any custom content you want to add" />
 ```
 
-## Using ZoomingImage
-
-Role: Provide image "asides" embedded into instructions where a standard image would normally interfere.
-
-A ZoomingImage is presented at a very small size, with the understanding that it is too small to view.
-An optional component, the image uses a magnifying glass and text prompt for discovery.
-See the instructions for [Prometheus Grafana](http://docs.temporal.io/cloud/metrics/prometheus-grafana#grafana-data-sources-configuration) for an example.
-
-Reserve ZoomingImages for situations where the image itself is an obstacle to communicating steps or other content.
-It provides opt-in supplementary information.
-
-Usage:
-
-```
-<ZoomingImage src="/path/to/image" alt="Alt text" />
-```
-
-Images are normally stored in the '/static' folder in `img` or `diagrams`.
-
 ## Using SdkGuideLinks
 
 Role: Render a vertical list of SDK guide links, each with a colored block icon and label, linking readers to the relevant SDK-specific page.

COMPONENT_REGISTRY.md

@@ -24,14 +24,12 @@ Generated by `scripts/audit-components.mjs`. Run to update.
 | `AWSRegions` | 2 | `transclude` | ✅ |
 | `GCPRegions` | 2 | `transclude` | ✅ |
 | `PatternCards` | 2 | `cards` | ✅ |
-| `DiscoverableDisclosure` | 1 | `transparent` | ✅ |
 | `CustomRolePermissionsTable` | 1 | `transclude` | ✅ |
 | `InvitationContent` | 1 | `strip-block` | ✅ |
 | `RetrySimulator` | 1 | `strip-block` | ✅ |
 | `SayHelloWorkflow` | 1 | `UNKNOWN` | ❌ |
 | `ISayHelloNexusService` | 1 | `UNKNOWN` | ❌ |
 | `CallerWorkflow` | 1 | `UNKNOWN` | ❌ |
-| `SdkLogos` | 1 | `strip-block` | ✅ |
 | `StandaloneActivityDemo` | 1 | `UNKNOWN` | ❌ |
 | `SdkSvg` | 1 | `strip-block` | ✅ |
 | `SdkGuideLinks` | 1 | `UNKNOWN` | ❌ |

CONTRIBUTING.md

@@ -165,9 +165,19 @@ If you are considering using a custom slug, answer these questions first:
 # Social share images (og:image)
 
 Every doc page automatically gets a social-share preview card generated at build time — the image that
-shows up when a link to the page is shared in Slack, X, LinkedIn, etc. It's built from the page's `title`,
-`description`, and a section label derived from its folder (e.g. `develop/go/...` → "Go SDK"). There's
-nothing to do for a normal page.
+shows up when a link to the page is shared in Slack, X, LinkedIn, etc. It's built from the page's `title`
+and `description`. There's nothing to do for a normal page.
+
+The image itself is rendered by a `postBuild` step (`plugins/og-image/`), but *which* image a page points
+at is decided earlier, during MDX compilation (`plugins/og-image/remarkPlugin.js`), which writes it into
+the page's front matter as a real `image` field — the same field you'd set manually (below). This matters
+because it's what makes the image survive past the initial page load: Docusaurus renders `<head>` through
+`react-helmet-async`, which re-renders it again on the client the moment a page hydrates. A tag injected
+after the fact by patching the built HTML would get silently wiped out and replaced with the site-wide
+default as soon as a real browser (or anything else that executes JavaScript) hydrated the page — only
+tools that read the raw HTML without running JS (like `curl`, or most social-share scrapers) would ever
+see it. Going through real front matter means Docusaurus's own metadata rendering produces the same tag
+both times, so there's nothing for hydration to revert.
 
 If you want a page to use a different image instead of the generated one, you have two options:
 
@@ -200,6 +210,11 @@ This only happens during `yarn build` (see below) — running `yarn start` won't
 overridden images, since it skips the production build step entirely. The generator itself lives in
 `plugins/og-image/`.
 
+Note that `yarn build` always runs in production mode (`NODE_ENV=production`), whether that's on your
+machine, a Vercel preview deployment for a PR, or the real production deploy — so `yarn build && yarn
+serve` locally is enough to preview real generated cards on new content before pushing anything; you don't
+need to wait for an actual deploy.
+
 # Local development command reference
 
 The following commands are available to aid in local development:

MARKDOWN_PIPELINE.md

@@ -108,7 +108,7 @@ Each component maps to a strategy in `COMPONENT_REGISTRY` (in `scripts/mdx-to-md
 | `Tabs` / `TabItem` | `tabs` / `tabitem` | All tabs flattened, each under a **bold label** header |
 | `SdkTabs` / `SdkTabs.<Lang>` | `sdk-tabs` | Same, with language labels (`DotNet` → **.NET**) |
 | `CodeSnippet` | `code-snippet` | Fenced code block using the `language` prop |
-| `CaptionedImage`, `EnlargeImage`, `ZoomingImage`, `Components.CaptionedImage` | `captioned-image` | `![alt or caption or title](src)` |
+| `CaptionedImage`, `EnlargeImage`, `Components.CaptionedImage` | `captioned-image` | `![alt or caption or title](src)` |
 | `PhotoCarousel` | `photo-carousel` | One `![caption](url)` per entry in the `images`/`captions` arrays |
 | `CallToAction` | `call-to-action` | `- [h3 title](href): p description` |
 | `ReleaseNoteHeader` | `release-note-header` | `> **Public Preview** — Go, Java…` availability note + body blockquote. The self-closing form (`<ReleaseNoteHeader … />`) emits just the note and leaves the page body intact. |
@@ -120,8 +120,8 @@ Each component maps to a strategy in `COMPONENT_REGISTRY` (in `scripts/mdx-to-md
 | `IntegrationsGrid` | `integrations-grid` | Markdown list resolved from `integrations-data.json`, filtered by the `defaultSdks` prop |
 | `HomePageHero` | `home-page-hero` | Homepage hero's headline, intro paragraphs, and link cards (content mirrored from the component) |
 | `QuickstartCards`, `PatternCards` | `cards` | Markdown link list parsed from the inline `items={[{href,title,description}]}` prop |
-| `ZoomPanPinch`, `DiscoverableDisclosure` | `transparent` | Wrapper stripped; inner content passed through |
-| `DocCardList`, `CardList`, `LandingCard`, `ThemedImage`, `SdkLogos`, `SdkSvg`, `CloudRegionCount`, `RetrySimulator`, `ServerlessWorkerDemo`, `OperationsTable`, `InvitationContent` | `strip-block` | Removed entirely (visual/dynamic, no extractable text) |
+| `ZoomPanPinch` | `transparent` | Wrapper stripped; inner content passed through |
+| `DocCardList`, `CardList`, `LandingCard`, `ThemedImage`, `SdkSvg`, `CloudRegionCount`, `RetrySimulator`, `ServerlessWorkerDemo`, `OperationsTable`, `InvitationContent` | `strip-block` | Removed entirely (visual/dynamic, no extractable text) |
 | `DL`, `DT`, `DD`, `DefinitionList` | `strip-tag` | Tags stripped, text content kept |
 | `details` / `summary` | `details` / `summary` | `<summary>` becomes a heading; body expanded inline |