ci: notify the docs retrieval index after prod deploy, and keep code indentation in static Markdown (TE-28101)

.github/workflows/docs-retrieval-index-notify.yml

@@ -0,0 +1,118 @@
+# Runs after every successful production deploy of testmuCom and tells
+# docs-retrieval-service (TE-28101) which commit is now live: an HMAC-signed
+# POST /v1/index with the deployed commit sha. The service downloads that
+# commit, diffs it against what it has indexed and updates the search index in
+# the background.
+#
+# Why workflow_run and not push: a push fires before the site is built and
+# uploaded, so an indexer triggered by it would read pages that are not live
+# yet. workflow_run waits for the deploy to finish, and the `if` below skips
+# failed or cancelled deploys.
+#
+# workflow_run only fires for a workflow file on the default branch
+# (testmuCom). On any other branch this file is dormant.
+#
+# This is its own file on purpose: documentation-notify.yml (the product-context
+# notifier) is a separate workflow and is not changed by this one.
+#
+# One-time setup (Settings, Secrets and variables, Actions):
+#   Secret   DOCS_RETRIEVAL_DISPATCH_TOKEN  same value as INDEX_DISPATCH_HMAC on the service
+#   Variable DOCS_RETRIEVAL_URL             service base URL, no trailing slash
+#            (while it is unset, the job logs a notice and succeeds)
+#
+# Manual run: Actions, "Notify docs retrieval index after prod deploy", Run
+# workflow, with the 40-character sha of a commit that is already deployed.
+name: Notify docs retrieval index after prod deploy
+
+on:
+  workflow_run:
+    workflows: ['Deployment (Prod - testmucom New Bucket)']
+    types: [completed]
+    branches: [testmuCom]
+  workflow_dispatch:
+    inputs:
+      sha:
+        description: 'Deployed commit sha (40 hex characters)'
+        required: true
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-retrieval-index-${{ github.event.workflow_run.head_sha || inputs.sha }}
+  cancel-in-progress: false
+
+jobs:
+  docs-retrieval-index:
+    name: 'docs-retrieval-service: index deployed commit'
+    if: github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Signed POST /v1/index
+        env:
+          SHA: ${{ github.event.workflow_run.head_sha || inputs.sha }}
+          HMAC_SECRET: ${{ secrets.DOCS_RETRIEVAL_DISPATCH_TOKEN }}
+          BASE_URL: ${{ vars.DOCS_RETRIEVAL_URL }}
+        run: |
+          set -euo pipefail
+          # Until docs-retrieval-service is deployed and DOCS_RETRIEVAL_URL is
+          # set, this job does nothing and succeeds, so prod deploys stay green.
+          if [ -z "${BASE_URL}" ]; then
+            echo "::notice::DOCS_RETRIEVAL_URL variable is not set, so the docs-retrieval index is not notified. Nothing to do."
+            exit 0
+          fi
+          if [ -z "${HMAC_SECRET}" ]; then
+            echo "::error::DOCS_RETRIEVAL_URL is set but the DOCS_RETRIEVAL_DISPATCH_TOKEN secret is not."
+            exit 1
+          fi
+          if ! printf '%s' "${SHA}" | grep -Eq '^[0-9a-f]{40}$'; then
+            echo "::error::sha must be 40 lowercase hex characters, got '${SHA}'."
+            exit 1
+          fi
+
+          attempt=0
+          max_attempts=6
+          delay=15
+          while :; do
+            attempt=$((attempt + 1))
+            # Sign the exact bytes that are sent. The timestamp is fresh on every
+            # attempt because the service rejects a ts more than 5 minutes old.
+            printf '{"sha":"%s","ts":%s,"trigger":"deploy"}' "${SHA}" "$(date +%s)" > body.json
+            sig=$(openssl dgst -sha256 -hmac "${HMAC_SECRET}" -r body.json | cut -d' ' -f1)
+            status=$(curl -sS -o response.json -w '%{http_code}' \
+              --max-time 30 \
+              -X POST "${BASE_URL}/v1/index" \
+              -H 'Content-Type: application/json' \
+              -H "X-Signature-256: sha256=${sig}" \
+              --data-binary @body.json || echo 000)
+            echo "attempt ${attempt}: HTTP ${status}"
+            cat response.json 2>/dev/null || true
+            echo
+
+            case "${status}" in
+              200|202)
+                echo "Index run accepted for ${SHA}."
+                exit 0
+                ;;
+              400|401|403|404|413)
+                echo "::error::docs-retrieval-service refused the request (HTTP ${status}); retrying will not help."
+                exit 1
+                ;;
+              409|429|5*|000)
+                # 409: another index run is in progress. The nightly reconcile
+                # also catches up, but retry so this deploy is indexed promptly.
+                if [ "${attempt}" -ge "${max_attempts}" ]; then
+                  echo "::error::Giving up after ${attempt} attempts (last HTTP ${status})."
+                  exit 1
+                fi
+                echo "Retrying in ${delay}s."
+                sleep "${delay}"
+                delay=$((delay * 2))
+                ;;
+              *)
+                echo "::error::Unexpected HTTP ${status}."
+                exit 1
+                ;;
+            esac
+          done

.github/workflows/static-md-fence-fidelity.yml

@@ -0,0 +1,44 @@
+# Fails a pull request when the plain-Markdown copies written by
+# scripts/generate-static-md.js (served as <slug>.md and linked from llms.txt)
+# lose or change code: every fenced code block must keep its lines and their
+# relative indentation. Needs no npm install; both scripts use Node built-ins only.
+name: Static Markdown fence fidelity
+
+on:
+  pull_request:
+    branches: [testmuCom, stage]
+    paths:
+      - 'docs/**'
+      - 'scripts/generate-static-md.js'
+      - 'scripts/check-static-md-fences.js'
+      - '.github/workflows/static-md-fence-fidelity.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: static-md-fence-fidelity-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: |
+            docs
+            scripts
+            package.json
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Generate static Markdown
+        run: node scripts/generate-static-md.js
+
+      - name: Check fenced code survives unchanged
+        run: npm run check-static-md-fences

docs/kane-cli-testmd-composition.md

@@ -290,7 +290,7 @@ Rules:
 
 <VerifiedTag value="Verified" />
 
-```markdown
+````markdown
 ## OK
 @import ./helpers/login.md
 
@@ -301,9 +301,6 @@ optional: true
 @import ./helpers/skip-tour.md
 
 ## NOT OK — extra config
-
-<VerifiedTag value="Verified" />
-
 ```yaml
 timeout: 60
 ```
@@ -312,10 +309,7 @@ timeout: 60
 ## NOT OK — body mixes prose and import
 Click somewhere first.
 @import ./helpers/login.md
-
-<VerifiedTag value="Verified" />
-
-```
+````
 
 ## How paths resolve
 
@@ -328,9 +322,6 @@ tests/
   helpers/
     login.md               # contains: @import ./submit-button.md
     submit-button.md
-
-<VerifiedTag value="Verified" />
-
 ```
 
 When `checkout_test.md` imports `../../helpers/login.md`, the path is relative to `tests/e2e/`, so it resolves to `helpers/login.md`. When `login.md` imports `./submit-button.md`, the path is relative to `helpers/`, so it resolves to `helpers/submit-button.md`.
@@ -381,16 +372,13 @@ A root-level `@import` step can be marked optional in the same way a prose step
 
 <VerifiedTag value="Verified" />
 
-```markdown
+````markdown
 ## Skip the tour if it shows up
 ```yaml
 optional: true
 ```
 @import ./helpers/dismiss-product-tour.md
-
-<VerifiedTag value="Verified" />
-
-```
+````
 
 If the helper fails, the run continues to the next step. The `Result.md` entry is suffixed with `(optional)`.
 

docs/playwright-sdk.md

@@ -382,3 +382,4 @@ You can pass any standard Playwright CLI options directly to this command. For i
 
 ```bash
 npx playwright-node-sdk playwright test tests/my-test.spec.js
+```

docs/smartui-appium-hooks.md

@@ -819,6 +819,9 @@ config = {
   'pageCount': 15 # Enter the number of pages for the Full Page screenshot (Minimum 1, Maximum 20)
 }
 driver.execute("smartui.takeScreenshot", config)
+```
+
+</TabItem>
 <TabItem value='ruby-2' label='Ruby' default>
 
 ```ruby

docs/smartui-build-merging.md

@@ -187,6 +187,7 @@ npx smartui merge build --source build-123 --target build-456
 ```bash
 # 1. Merge staging build to production
 npx smartui merge build --source staging-build-123 --target prod-build-456
+```
 
 ### 2. Feature Build Strategy
 
@@ -195,6 +196,7 @@ npx smartui merge build --source staging-build-123 --target prod-build-456
 ```bash
 # 1. Merge feature build into main build
 npx smartui merge build --source feature-build-789 --target main-build-101
+```
 
 ### 3. Hotfix Build Strategy
 

docs/smartui-cli-env-variables.md

@@ -452,6 +452,9 @@ In case you are accessing your network using corporate proxies, set the proxies
 
 ```bash
 export HTTP_PROXY="http://<username>:<password>@<domain.com>:<port>/"
+```
+
+</TabItem>
 <TabItem value="Windows-4" label='Windows - CMD'>
 
 ```bash

package.json

@@ -8,6 +8,7 @@
     "start": "docusaurus start",
     "prebuild": "node scripts/build-api-data.js && node scripts/generate-api-pages.js && node scripts/generate-static-md.js && node scripts/generate-llms-txt.js && node scripts/generate-skill-index.js",
     "generate-static-md": "node scripts/generate-static-md.js",
+    "check-static-md-fences": "node scripts/check-static-md-fences.js",
     "generate-llms-txt": "node scripts/generate-llms-txt.js",
     "generate-skill-index": "node scripts/generate-skill-index.js",
     "sitemap-exclusions": "node scripts/sitemap-exclusions.js",