chore: sync docs/release-docs-staging with develop

Author: github-actions[bot]

.github/workflows/cloud-docs-automation.yml

@@ -92,10 +92,11 @@ jobs:
             import { readFileSync, appendFileSync } from "fs"
             const a = JSON.parse(readFileSync("/tmp/analysis.json", "utf8"))
             const prefix = "IMPORTANT: Only make file changes using the Write and Edit tools. Never use git commands to stage, commit, or push files.\n\nIMPORTANT: To load the writing-docs skill, use the Skill tool directly with skill='writing-docs'. Do NOT spawn a sub-agent or use the Task tool to load it.\n\n"
+            const suffix = "\n\n---\n\nIMPORTANT — final step: after applying all documentation changes, write these two files using the Write tool:\n\n1. /tmp/pr-title.txt — a single-line pull request title. It MUST start with \"docs: \", followed by a concise summary of what was changed, and MUST end with \" [automated]\". Keep it under 100 characters. Example: \"docs: document new environment variables page [automated]\"\n2. /tmp/pr-summary.md — a short summary (2-4 sentences, or a few bullet points) of what was updated. Plain markdown, no top-level heading.\n\nIf you made no documentation changes, do not create either file.\n"
             const delimiter = "CLAUDE_PROMPT_EOF"
             appendFileSync(
               process.env.GITHUB_OUTPUT,
-              `CLAUDE_PROMPT<<${delimiter}\n${prefix}${a.claudePrompt}\n${delimiter}\n`
+              `CLAUDE_PROMPT<<${delimiter}\n${prefix}${a.claudePrompt}${suffix}\n${delimiter}\n`
             )
           EOF
 
@@ -134,21 +135,35 @@ jobs:
             echo "No documentation changes found."
           fi
 
-      - name: Build PR body
+      - name: Build PR metadata
         id: pr-body
         if: steps.check.outputs.needs_docs == 'true' && steps.changes.outputs.has_changes == 'true'
         run: |
           node --input-type=module << 'EOF'
-            import { readFileSync, appendFileSync } from "fs"
+            import { existsSync, readFileSync, appendFileSync } from "fs"
 
             const a = JSON.parse(readFileSync("/tmp/analysis.json", "utf8"))
             const flagged = Array.isArray(a.featureFlaggedFeatures) ? a.featureFlaggedFeatures : []
 
+            // Title generated by Claude, with a fallback if it is missing or malformed
+            let title = existsSync("/tmp/pr-title.txt")
+              ? readFileSync("/tmp/pr-title.txt", "utf8").split("\n")[0].trim()
+              : ""
+            if (!title.startsWith("docs: ") || !title.endsWith("[automated]")) {
+              title = "docs: update cloud documentation [automated]"
+            }
+
+            const summary = existsSync("/tmp/pr-summary.md")
+              ? readFileSync("/tmp/pr-summary.md", "utf8").trim()
+              : ""
+
             const lines = [
               "## Automated Cloud Documentation Updates",
               "",
               "This PR contains automated documentation changes triggered by Cloud production deployments.",
               "",
+              summary || "_No summary was generated._",
+              "",
               "> Review carefully before merging. Claude may have missed context or made incorrect assumptions.",
             ]
 
@@ -170,6 +185,7 @@ jobs:
 
             const body = lines.join("\n")
             const delimiter = "PR_BODY_EOF"
+            appendFileSync(process.env.GITHUB_OUTPUT, `TITLE=${title}\n`)
             appendFileSync(process.env.GITHUB_OUTPUT, `BODY<<${delimiter}\n${body}\n${delimiter}\n`)
           EOF
 
@@ -182,8 +198,8 @@ jobs:
           base: develop
           branch: docs/cloud-docs
           branch-suffix: timestamp
-          title: "chore(docs): cloud doc changes (automated)"
-          labels: "type: chore"
+          title: ${{ steps.pr-body.outputs.TITLE }}
+          labels: "type: docs"
           add-paths: |
             www/apps/cloud/app
             www/apps/cloud/generated

.github/workflows/docs-automation.yml

@@ -101,18 +101,100 @@ jobs:
             echo "Created new branch docs/release-docs-staging"
           fi
 
+      - name: Fetch existing PR body
+        id: existing-pr
+        if: steps.check.outputs.needs_docs == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.REFERENCE_PAT }}
+          REPO: ${{ github.repository }}
+        run: |
+          # The docs/release-docs-staging branch is long-lived: its PR is reused
+          # until the next release. Claude rewrites this body in place, so a
+          # failed lookup fails the step rather than losing the existing entries.
+          REPO_OWNER="${REPO%%/*}"
+          PR_NUMBER=$(gh api "repos/$REPO/pulls?head=${REPO_OWNER}:docs/release-docs-staging&state=open" --jq '.[0].number')
+          if [ "$PR_NUMBER" = "null" ]; then
+            PR_NUMBER=""
+          fi
+
+          if [ -n "$PR_NUMBER" ]; then
+            gh api "repos/$REPO/pulls/$PR_NUMBER" --jq '.body // ""' > /tmp/existing-pr-body.md
+            echo "Fetched body of PR #$PR_NUMBER"
+          else
+            : > /tmp/existing-pr-body.md
+            echo "No open PR for docs/release-docs-staging yet"
+          fi
+          echo "number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
+
       - name: Extract Claude prompt
         id: extract-prompt
         if: steps.check.outputs.needs_docs == 'true'
+        env:
+          COMMIT_SHA: ${{ inputs.commit_sha || github.sha }}
+          REPO: ${{ github.repository }}
         run: |
           node --input-type=module << 'EOF'
             import { readFileSync, appendFileSync } from "fs"
             const a = JSON.parse(readFileSync("/tmp/analysis.json", "utf8"))
+            const { COMMIT_SHA: sha, REPO: repo } = process.env
+            const date = new Date().toISOString().split("T")[0]
+            const projectList = a.affectedProjects
+              .map((p) => `- **${p.project}**: ${p.reason}`)
+              .join("\n")
+
             const prefix = "IMPORTANT: Only make file changes using the Write and Edit tools. Never use git commands to stage, commit, or push files.\n\nIMPORTANT: To load the writing-docs skill, use the Skill tool directly with skill='writing-docs'. Do NOT spawn a sub-agent or use the Task tool to load it.\n\n"
+
+            // Claude owns the whole PR description so its format stays consistent
+            // across runs instead of being appended to by this workflow.
+            const suffix = [
+              "",
+              "",
+              "---",
+              "",
+              "IMPORTANT — final step: update the pull request description.",
+              "",
+              "These documentation changes land on a long-lived pull request that is reused for every commit until the next release. Read the current description from /tmp/existing-pr-body.md with the Read tool (the file is empty if the pull request does not exist yet), then write the FULL updated description to /tmp/pr-body.md with the Write tool.",
+              "",
+              "Rules for the updated description:",
+              "- Keep the existing structure and formatting exactly as-is. Do not reformat, reorder, or rewrite entries that are already there.",
+              "- Never remove, merge, or shorten existing entries. The description only grows.",
+              "- Add exactly one new entry for this commit, after the existing entries, matching the format the existing entries already use.",
+              "- Your new entry must summarize the documentation changes you just made in 2-4 sentences or a few bullet points.",
+              "- Write the file even if the description ends up unchanged in structure.",
+              "",
+              "Facts for this commit's entry:",
+              `- Commit: [\`${sha.slice(0, 7)}\`](https://github.com/${repo}/commit/${sha})`,
+              `- Date: ${date}`,
+              "- Affected projects:",
+              projectList.replace(/^/gm, "  "),
+              "",
+              "If /tmp/existing-pr-body.md is empty, create the description from scratch with exactly this structure:",
+              "",
+              "```markdown",
+              "## Automated Documentation Updates",
+              "",
+              "This PR accumulates automated documentation changes for the next release.",
+              "Each entry below corresponds to a merged commit that triggered updates.",
+              "",
+              "> Review carefully before merging. Claude may have missed context",
+              "> or made incorrect assumptions.",
+              "",
+              "---",
+              "",
+              `### [\`${sha.slice(0, 7)}\`](https://github.com/${repo}/commit/${sha}) — ${date}`,
+              "",
+              "<your 2-4 sentence summary of what was updated>",
+              "",
+              "**Affected projects:**",
+              projectList,
+              "```",
+              "",
+            ].join("\n")
+
             const delimiter = "CLAUDE_PROMPT_EOF"
             appendFileSync(
               process.env.GITHUB_OUTPUT,
-              `CLAUDE_PROMPT<<${delimiter}\n${prefix}${a.claudePrompt}\n${delimiter}\n`
+              `CLAUDE_PROMPT<<${delimiter}\n${prefix}${a.claudePrompt}${suffix}\n${delimiter}\n`
             )
           EOF
 
@@ -187,43 +269,52 @@ jobs:
         if: steps.check.outputs.needs_docs == 'true' && steps.changes.outputs.has_changes == 'true'
         run: git push origin docs/release-docs-staging
 
-      - name: Create or update Pull Request
+      - name: Resolve PR body
         if: steps.check.outputs.needs_docs == 'true' && steps.changes.outputs.has_changes == 'true'
         env:
-          GH_TOKEN: ${{ secrets.REFERENCE_PAT }}
           COMMIT_SHA: ${{ inputs.commit_sha || github.sha }}
           REPO: ${{ github.repository }}
         run: |
           node --input-type=module << 'EOF'
-            import { readFileSync, writeFileSync } from "fs"
-            import { execSync } from "child_process"
+            import { existsSync, readFileSync, writeFileSync } from "fs"
 
             const a = JSON.parse(readFileSync("/tmp/analysis.json", "utf8"))
             const { COMMIT_SHA: sha, REPO: repo } = process.env
             const date = new Date().toISOString().split("T")[0]
 
+            const existingBody = readFileSync("/tmp/existing-pr-body.md", "utf8").trim()
+            const claudeBody = existsSync("/tmp/pr-body.md")
+              ? readFileSync("/tmp/pr-body.md", "utf8").trim()
+              : ""
+
+            // Claude owns the body. Fall back to a deterministic append only if it
+            // wrote nothing, or if it dropped content that was already there.
+            const droppedContent =
+              existingBody.length > 0 && claudeBody.length < existingBody.length
+            if (claudeBody && !droppedContent) {
+              writeFileSync("/tmp/pr-body.md", claudeBody)
+              process.exit(0)
+            }
+
+            console.log(
+              claudeBody
+                ? "Claude's PR body is shorter than the existing one; falling back."
+                : "Claude wrote no PR body; falling back."
+            )
+
             const projectList = a.affectedProjects
               .map((p) => `- **${p.project}**: ${p.reason}`)
               .join("\n")
 
-            const commitUrl = `https://github.com/${repo}/commit/${sha}`
             const newEntry = [
-              `### [\`${sha.slice(0, 7)}\`](${commitUrl}) — ${date}`,
+              `### [\`${sha.slice(0, 7)}\`](https://github.com/${repo}/commit/${sha}) — ${date}`,
+              "",
+              "_No summary was generated._",
               "",
               "**Affected projects:**",
               projectList,
             ].join("\n")
 
-            let existingBody = ""
-            try {
-              const owner = repo.split("/")[0]
-              const out = execSync(
-                `gh api "repos/${repo}/pulls?head=${owner}:docs/release-docs-staging&state=open" --jq '.[0].body'`,
-                { encoding: "utf8" }
-              ).trim()
-              if (out !== "null" && out !== "") existingBody = out
-            } catch { /* PR does not exist yet */ }
-
             const header = [
               "## Automated Documentation Updates",
               "",
@@ -234,29 +325,33 @@ jobs:
               "> or made incorrect assumptions.",
             ].join("\n")
 
-            const body = existingBody
-              ? `${existingBody}\n\n---\n\n${newEntry}`
-              : `${header}\n\n---\n\n${newEntry}`
-
-            writeFileSync("/tmp/pr-body.md", body)
+            const base = existingBody || header
+            writeFileSync("/tmp/pr-body.md", `${base}\n\n---\n\n${newEntry}`)
           EOF
 
-          REPO_OWNER="${REPO%%/*}"
-          PR_NUMBER=$(gh api "repos/$REPO/pulls?head=${REPO_OWNER}:docs/release-docs-staging&state=open" --jq '.[0].number' 2>/dev/null || echo "")
-          if [ -n "$PR_NUMBER" ] && [ "$PR_NUMBER" != "null" ]; then
+      - name: Create or update Pull Request
+        if: steps.check.outputs.needs_docs == 'true' && steps.changes.outputs.has_changes == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.REFERENCE_PAT }}
+          REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ steps.existing-pr.outputs.number }}
+          # The branch is long-lived, so the title stays static
+          PR_TITLE: "docs: doc changes for next release [automated]"
+        run: |
+          if [ -n "$PR_NUMBER" ]; then
             gh api "repos/$REPO/pulls/$PR_NUMBER" \
               --method PATCH \
-              --field title="chore(docs): doc changes for next release (automated)" \
+              --field title="$PR_TITLE" \
               --field body="$(cat /tmp/pr-body.md)"
           else
             PR_NUMBER=$(gh api "repos/$REPO/pulls" \
               --method POST \
-              --field title="chore(docs): doc changes for next release (automated)" \
+              --field title="$PR_TITLE" \
               --field body="$(cat /tmp/pr-body.md)" \
               --field base="develop" \
               --field head="docs/release-docs-staging" \
               --jq '.number')
             gh api "repos/$REPO/issues/$PR_NUMBER/labels" \
               --method POST \
-              --field 'labels[]=type: chore'
+              --field 'labels[]=type: docs'
           fi

.github/workflows/dx-triage-doc-fixes.yml

@@ -128,6 +128,15 @@ jobs:
             DX-2591
             DX-2593
 
+            ## Step 5 — Write the PR title and summary
+
+            After applying all fixes, write these two files using the Write tool:
+
+            1. /tmp/pr-title.txt — a single-line pull request title. It MUST start with "docs: ", followed by a concise summary of what was changed, and MUST end with " [automated]". Keep it under 100 characters. Example: "docs: fix incorrect subscriber examples and payment provider setup [automated]"
+            2. /tmp/pr-summary.md — a short summary (2-4 sentences, or a few bullet points) of what was updated. Plain markdown, no top-level heading.
+
+            If no issues qualified or were fixed, do not create either file.
+
       - name: Stage documentation changes
         id: changes
         run: |
@@ -151,6 +160,21 @@ jobs:
             echo "No issues fixed."
           fi
 
+      - name: Read Claude-generated PR metadata
+        id: pr-meta
+        if: steps.changes.outputs.has_changes == 'true'
+        run: |
+          TITLE=""
+          if [ -s /tmp/pr-title.txt ]; then
+            TITLE=$(head -n 1 /tmp/pr-title.txt | sed 's/[[:space:]]*$//')
+          fi
+          # Fall back to a static title if Claude's title is missing or malformed
+          case "$TITLE" in
+            "docs: "*"[automated]") ;;
+            *) TITLE="docs: fix documentation issues in triage inbox [automated]" ;;
+          esac
+          echo "title=$TITLE" >> "$GITHUB_OUTPUT"
+
       - name: Commit documentation changes
         if: steps.changes.outputs.has_changes == 'true'
         run: |
@@ -167,6 +191,7 @@ jobs:
           REPO: ${{ github.repository }}
           BRANCH: ${{ steps.branch.outputs.name }}
           FIXED_IDS: ${{ steps.fixed-ids.outputs.ids }}
+          PR_TITLE: ${{ steps.pr-meta.outputs.title }}
         run: |
           BODY_FILE=$(mktemp)
 
@@ -175,6 +200,16 @@ jobs:
 
           This PR fixes documentation issues from the triage inbox.
           Each issue was evaluated by Claude and deemed a self-contained doc fix.
+          BODY_EOF
+
+          echo "" >> "$BODY_FILE"
+          if [ -s /tmp/pr-summary.md ]; then
+            cat /tmp/pr-summary.md >> "$BODY_FILE"
+          else
+            echo "_No summary was generated._" >> "$BODY_FILE"
+          fi
+
+          cat >> "$BODY_FILE" << 'BODY_EOF'
 
           > Review carefully before merging. Claude may have missed context or made
           > incorrect assumptions.
@@ -192,19 +227,19 @@ jobs:
           if [ -n "$PR_NUMBER" ] && [ "$PR_NUMBER" != "null" ]; then
             gh api "repos/$REPO/pulls/$PR_NUMBER" \
               --method PATCH \
-              --field title="docs: fix documentation issues in triage inbox" \
+              --field title="$PR_TITLE" \
               --field body="$(cat "$BODY_FILE")"
             echo "Updated PR #$PR_NUMBER"
           else
             PR_NUMBER=$(gh api "repos/$REPO/pulls" \
               --method POST \
-              --field title="docs: fix documentation issues in triage inbox" \
+              --field title="$PR_TITLE" \
               --field body="$(cat "$BODY_FILE")" \
               --field base="develop" \
               --field head="$BRANCH" \
               --jq '.number')
             gh api "repos/$REPO/issues/$PR_NUMBER/labels" \
               --method POST \
-              --field 'labels[]=type: chore'
+              --field 'labels[]=type: docs'
             echo "Created PR #$PR_NUMBER"
           fi