[DRAFT] SAA operator commands documentation

.github/workflows/check-redirects.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
 

.github/workflows/cleanup-report.yml

@@ -18,7 +18,7 @@ jobs:
       BRANCH_REPORTS_DIR: reports/${{ github.event.ref }}
     steps:
       - name: Checkout GitHub Pages Branch
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           ref: gh-pages
 

.github/workflows/docs-preview-links.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
 

.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/screenshot-capture.yml

@@ -27,7 +27,7 @@ jobs:
       contents: read
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Setup Node.js Environment
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
@@ -67,7 +67,7 @@ jobs:
         shardTotal: [4]
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Setup Node.js Environment
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0

.github/workflows/snipsync.yml

@@ -21,7 +21,7 @@ jobs:
           private-key: ${{ secrets.TEMPORAL_CICD_PRIVATE_KEY }}
 
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           token: ${{ steps.generate_token.outputs.token }}
           ref: main

.github/workflows/update-cli-docs.yml

@@ -36,15 +36,15 @@ jobs:
           private-key: ${{ secrets.TEMPORAL_CICD_PRIVATE_KEY }}
 
       - name: Checkout docs repo
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: true
           token: ${{ steps.generate_token.outputs.token }}
           path: docs
           ref: main
 
       - name: Checkout CLI repo
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           path: cli
           ref: ${{ github.event.inputs.cli_release_tag }}
@@ -54,12 +54,12 @@ jobs:
           repository: temporalio/cli
 
       - name: Setup Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0
         with:
           go-version: '1.26'
 
       - name: Checkout cloud-cli repo
-        uses: actions/checkout@v6.0.3
+        uses: actions/checkout@v7
         with:
           path: cloud-cli
           submodules: recursive
@@ -77,6 +77,31 @@ jobs:
           go run ./cmd/gen-docs -input internal/temporalcli/commands.yaml -input cliext/option-sets.yaml -output dist/docs
           go run ./cmd/gen-docs -input ../cloud-cli/temporalcloudcli/commands.yml -output dist/docs -subdir cloud
 
+      - name: Copy generated command reference into the docs repo
+        working-directory: docs
+        run: |
+          set -ex
+
+          # Regenerate the command reference pages. cp -R preserves the cloud/
+          # subdirectory produced by -subdir.
+          rm -rf docs/cli/command-reference
+          mkdir -p docs/cli/command-reference
+          cp -R ../cli/dist/docs/* docs/cli/command-reference/
+
+          # gen-docs intentionally does not emit index.mdx landing pages: those
+          # are hand-maintained (custom ordering, embedded components such as
+          # ReleaseNoteHeader). Restore them after regeneration so they are not
+          # lost by the rm -rf above.
+          git checkout HEAD -- docs/cli/command-reference/index.mdx
+          git checkout HEAD -- docs/cli/command-reference/cloud/index.mdx
+
+      - name: Post-process generated CLI docs
+        working-directory: docs
+        # Injects the ReleaseNoteHeader banner into cloud CLI pages and keeps
+        # command-reference/index.mdx and sidebars.js in sync with the
+        # generated commands. Not previously called from this workflow.
+        run: node bin/post-process-cli-docs.js
+
       - name: Publish generated docs to documentation repo
         env:
           GH_TOKEN: ${{ github.token }}
@@ -93,10 +118,7 @@ jobs:
 
           branch_name="update-cli-docs-$CLI_RELEASE_TAG"
           git checkout -b "$branch_name"
-          rm -rf docs/cli/command-reference
-          mkdir -p docs/cli/command-reference
-          cp -r ../cli/dist/docs/* docs/cli/command-reference/
-          git add .
+          git add -A docs/cli/command-reference
           git commit -m "$COMMIT_MESSAGE"
           git push origin "$branch_name"
 

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

@@ -22,13 +22,13 @@ jobs:
           private-key: ${{ secrets.TEMPORAL_CICD_PRIVATE_KEY }}
 
       - name: Checkout docs repo
-        uses: actions/checkout@v6.0.3
+        uses: actions/checkout@v7
         with:
           persist-credentials: true
           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

@@ -14,12 +14,15 @@ jobs:
     name: Lint prose
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - uses: vale-cli/vale-action@2.1.2
         with:
           reporter: github-pr-review
           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"

.github/workflows/visual-comparison.yml

@@ -44,7 +44,7 @@ jobs:
       pull-requests: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Setup Node.js
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
@@ -119,7 +119,7 @@ jobs:
         shardTotal: [4]
     steps:
       - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Setup Node.js
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
@@ -212,7 +212,7 @@ jobs:
       actions: read
     steps:
       - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Setup Node.js
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0

.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/*

.vale-ci.ini

@@ -5,11 +5,65 @@ MinAlertLevel = suggestion
 [*.{md,mdx}]
 BasedOnStyles = Temporal
 
-; Only enable the two rules we want in CI
+; Only enable the high-confidence rules we want in CI.
+; Temporal.terms (term-capitalization substitution) is disabled here because
+; it produces too many false positives to be useful as a CI gate.
 Temporal.badwords = NO
 Temporal.complexwords = NO
 Temporal.programming = NO
 Temporal.WordList = NO
+Temporal.terms = NO
+
+; Temporal.Headings and Temporal.RelativeLinks are intentionally left enabled
+; (not listed above) — they're the two high-confidence checks this CI gate runs.
+
+; ignore MDX custom heading-ID comments, e.g. {/* #ha-worker-patterns */}
+TokenIgnores = (\{/\*[^\n]*?\*/\})
+
+; These are reference docs whose headings are literal command/metric names
+; (e.g. "## audit-log", "### --workflow_id"), not prose — sentence-case
+; capitalization doesn't apply, so skip Temporal.Headings for them.
+[docs/references/sdk-metrics.mdx]
+Temporal.Headings = NO
+
+[docs/tctl-v1/**]
+Temporal.Headings = NO
+
+[docs/cli/command-reference/**]
+Temporal.Headings = NO
+
+[docs/cloud/tcld/**]
+Temporal.Headings = NO
+
+[docs/cloud/references/regions/**]
+Temporal.Headings = NO
+
+[docs/cloud/metrics/reference.mdx]
+Temporal.Headings = NO
+
+[docs/cloud/metrics/openmetrics/metrics-reference.mdx]
+Temporal.Headings = NO
+
+[docs/references/cluster-metrics.mdx]
+Temporal.Headings = NO
+
+[docs/references/configuration.mdx]
+Temporal.Headings = NO
+
+[docs/references/web-ui-configuration.mdx]
+Temporal.Headings = NO
+
+[docs/references/server-options.mdx]
+Temporal.Headings = NO
+
+[docs/references/errors.mdx]
+Temporal.Headings = NO
+
+[docs/references/commands.mdx]
+Temporal.Headings = NO
+
+[docs/references/events.mdx]
+Temporal.Headings = NO
 
 [formats]
 mdx = md

.vale.ini

@@ -27,6 +27,51 @@ Google.Will = NO
 Microsoft.ComplexWords = NO
 Google.WordList = NO
 
+; These are reference docs whose headings are literal command/metric names
+; (e.g. "## audit-log", "### --workflow_id"), not prose — sentence-case
+; capitalization doesn't apply, so skip Temporal.Headings for them.
+[docs/references/sdk-metrics.mdx]
+Temporal.Headings = NO
+
+[docs/tctl-v1/**]
+Temporal.Headings = NO
+
+[docs/cli/command-reference/**]
+Temporal.Headings = NO
+
+[docs/cloud/tcld/**]
+Temporal.Headings = NO
+
+[docs/cloud/references/regions/**]
+Temporal.Headings = NO
+
+[docs/cloud/metrics/reference.mdx]
+Temporal.Headings = NO
+
+[docs/cloud/metrics/openmetrics/metrics-reference.mdx]
+Temporal.Headings = NO
+
+[docs/references/cluster-metrics.mdx]
+Temporal.Headings = NO
+
+[docs/references/configuration.mdx]
+Temporal.Headings = NO
+
+[docs/references/web-ui-configuration.mdx]
+Temporal.Headings = NO
+
+[docs/references/server-options.mdx]
+Temporal.Headings = NO
+
+[docs/references/errors.mdx]
+Temporal.Headings = NO
+
+[docs/references/commands.mdx]
+Temporal.Headings = NO
+
+[docs/references/events.mdx]
+Temporal.Headings = NO
+
 [formats]
 mdx = md