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

[chaitanyas-maker]

What this changes

1. New workflow .github/workflows/docs-retrieval-index-notify.yml (on testmuCom). It runs on workflow_run when Deployment (Prod - testmucom New Bucket) finishes with conclusion == 'success', and has one job, docs-retrieval-index. It sends an HMAC-SHA256 signed POST /v1/index to docs-retrieval-service with the deployed commit sha. The body is {"sha":"<40 hex>","ts":<epoch seconds>,"trigger":"deploy"} and the header is X-Signature-256: sha256=<hex>. A fresh ts is signed on each attempt. It retries HTTP 409, 429, 5xx and connection failures up to 6 times (15, 30, 60, 120 and 240 seconds apart), and fails at once on 400, 401, 403, 404 and 413. It can also be run by hand (Actions, "Notify docs retrieval index after prod deploy", Run workflow) with a deployed sha.
   • Product-context is not part of this PR any more. An earlier revision put this job and a moved product-context dispatch into documentation-notify.yml, the path stage already uses for its push-triggered product-context notifier. The docs retrieval trigger is now its own file, and the product-context workflow on stage is left as it is, so stage and testmuCom do not diverge on that file.
2. Fix in scripts/generate-static-md.js. When it shielded fenced code blocks, it removed all leading whitespace from every code line. It now removes at most the fence's own indentation, as CommonMark does.
3. New check scripts/check-static-md-fences.js, the npm run check-static-md-fences script, and a pull request workflow static-md-fence-fidelity.yml. The check runs after the generator and compares every fenced code block in docs/ with its copy in static/docs/: the same non-blank lines, in order, with the same relative indentation. It fails on a changed line, and on a source fence that is never closed or that another opening fence interrupts. It warns (fails only with --strict) when a code block is missing from the generated copy. Node built-ins only, no npm install needed.
4. Doc fixes for the 9 broken fences in 5 pages that the check found. On the live site every later fence on these pages pairs the wrong way round, so prose renders as code and code as prose:
   • kane-cli-testmd-composition.md: the two test.md examples that contain a nested yaml step block now use four-backtick outer fences. Four <VerifiedTag> lines that the badge script had inserted inside those examples and inside the path tree are removed (the tag before each example stays).
   • playwright-sdk.md: closes the last bash block, which ends the page.
   • smartui-appium-hooks.md: closes the Python full-page block and its TabItem before the Ruby tab.
   • smartui-build-merging.md: closes the bash blocks of strategies 1 and 2 before the next heading.
   • smartui-cli-env-variables.md: closes the MacOS/Linux HTTP_PROXY block and its TabItem before the Windows tab.

Why

• Search index trigger. The MCP search_testmu_docs tool is backed by docs-retrieval-service, which needs to know when new docs are live. A push trigger fires before the site is built and uploaded, so this uses workflow_run on the prod deploy and skips failed or cancelled deploys.

• Broken code in the Markdown copies. The .md copies under static/docs/ are served as <slug>.md, linked from llms.txt, and read by AI agents and the retrieval index. The generator flattened indentation in code blocks, so YAML and Python lost their meaning. For example hyperexecute-yaml-version0.2.md served:

  # before
  framework:
  name: "maven/testng"
  # after
  framework:
    name: "maven/testng"

Numbers

Measured on testmuCom at f9d611a5 with this branch's docs, generator run locally (1,439 generated files, 4,924 code blocks compared):

Measure	Before the generator fix	After
Changed code lines (fence-fidelity check)	19,646 in 534 docs	0
Generated files with an indented line inside a code block	0	533
Generated files whose content changes		534

Without the doc fixes the check also reports 9 unclosed or interrupted fences in 5 docs. With them it passes: 0 error(s), 13 warning(s).

The committed copies under static/docs/ are not regenerated in this PR, because prebuild regenerates them on every build.

Settings needed (names only)

Kind	Name	Notes
Repository variable	DOCS_RETRIEVAL_URL	docs-retrieval-service base URL, no trailing slash
Repository secret	DOCS_RETRIEVAL_DISPATCH_TOKEN	HMAC key shared with the service

The docs retrieval call does nothing until DOCS_RETRIEVAL_URL is set. The service is not deployed yet. While the variable is unset, docs-retrieval-index logs a notice and succeeds, so it never turns a prod deploy red. Once the URL is set, a missing DOCS_RETRIEVAL_DISPATCH_TOKEN is an error.

Same change on stage

As requested in review, this change is also raised against stage in #3558, with the same workflow file, generator fix and check. On stage only 3 pages need fence fixes (smartui-appium-hooks.md and smartui-cli-env-variables.md are already closed there).

workflow_run only fires for workflow files on the default branch, so the workflow runs only once it is on testmuCom; on stage it is dormant. The workflows have not run on GitHub yet. Their YAML was parsed and passes actionlint, and the notify step's shell was run locally.

Known issue, not fixed here

The generator drops whole regions of 6 pages, so 13 code blocks are missing from their .md copies. This happens with and without this PR (probably in the tag-stripping steps), and the check reports it as warnings:

• deep-dive-into-hyperexecute-yaml (6 blocks)
• hyperexecute-background-services (2 blocks; the generated file is 13 lines, only the FAQ is left)
• hyperexecute-projects (2 blocks)
• legacy-test-platform-to-lambdatest (generated as migrate-from-legacy-platform-to-testmu.md, 1 block)
• playwright-test-execution-setup (1 block)
• travis-ci-with-hyperexecute (1 block)

🤖 Generated with Claude Code