ci: docs retrieval index trigger, and keep code indentation in static Markdown (TE-28101)

[chaitanyas-maker]

Raised on stage first, as requested on #3557. #3557 carries the same change for testmuCom.

What this changes

1. New workflow .github/workflows/docs-retrieval-index-notify.yml. 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.

   • The existing documentation-notify.yml (product-context notifier) is not touched. The docs retrieval trigger is a separate file so the two workflows stay independent.

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 (for PRs into stage and testmuCom). 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 7 broken fences in 3 pages that the check finds on stage. 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-build-merging.md: closes the bash blocks of strategies 1 and 2 before the next heading.

   smartui-appium-hooks.md and smartui-cli-env-variables.md need the same fix on testmuCom (ci: notify the docs retrieval index after prod deploy, and keep code indentation in static Markdown (TE-28101) #3557) but are already closed on stage.

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 stage at 08fce1fc with this branch's docs, generator run locally (1,408 generated files):

Measure	Before the generator fix	After
Changed code lines (fence-fidelity check)	20,024 in 535 docs	0
Generated files with an indented line inside a code block	0	536
Generated files whose content changes		537

Without the doc fixes the check also reports 7 unclosed or interrupted fences in 3 docs (5,143 code blocks compared). With them it passes: Checked 5174 code block(s) in 1408 doc(s): 0 error(s), 13 warning(s). The three fixed pages also compile with @mdx-js/mdx.

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 workflow is dormant on stage. workflow_run only fires for workflow files on the default branch (testmuCom), so it starts running once this file reaches testmuCom (#3557). Even then it does nothing until DOCS_RETRIEVAL_URL is set: while the variable is unset, the job logs a notice and succeeds, so it never turns a prod deploy red. The service is not deployed yet. Once the URL is set, a missing DOCS_RETRIEVAL_DISPATCH_TOKEN is an error.

The workflows have not run on GitHub yet. Their YAML was parsed and passes actionlint, and the notify step's shell was run locally for the unset and missing-secret cases.

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)
• 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