ci(docs): pin the Mintlify CLI version used by the docs checks

[GigaHierz]

The hole, and the fix

The required status check is currently red on every open PR in this repo, for a reason that has nothing to do with any of their diffs.

docs-validation.yml invokes npx mintlify with no version, so it resolves the latest dist-tag at run time. latest is 4.2.931, and that release carries a transitive dependency on @mintlify/auth-edge@0.0.51 — a package that is not published on the npm registry. The CLI therefore cannot be installed, and the job dies before it reads a single file:

npm warn exec The following package was not found and will be installed: mintlify@4.2.931
npm error code E404
npm error 404 Not Found - GET https://registry.npmjs.org/@mintlify%2fauth-edge - Not found
npm error 404  The requested resource '@mintlify/auth-edge@0.0.51' could not be found
##[error]Process completed with exit code 1.

Confirmed at the registry rather than through a local npm cache, which reports a stale latest:

$ curl -s https://registry.npmjs.org/mintlify | jq '."dist-tags"'
{ "latest": "4.2.931" }
$ curl -s -o /dev/null -w '%{http_code}' https://registry.npmjs.org/@mintlify%2fauth-edge
404

This pins the version behind an env key so there is one place to bump.

Why pin rather than wait it out

Waiting works only until the next bad publish. An unpinned npx in a required status check means any upstream mistake, at any hour, blocks merging repo-wide — and the failure names npm, not the docs, so the next person to hit it loses time working out that their PR is fine. The cost of pinning is a deliberate bump; the comment in the file says how to do it.

I did not pin to the newest working release blindly — 4.2.920 is the version I actually ran the full check set against.

Verification

Against current main (3a415880), locally:

$ npx mintlify@4.2.920 validate
success build validation passed

$ npx mintlify@4.2.920 broken-links --check-redirects
success no broken links found

$ bash scripts/check-orphans.sh
No orphan pages found.

Because pull_request workflows run from the PR's merge ref, this PR exercises its own fix — if the pin is wrong, this PR goes red rather than main.

What this does NOT do

• Does not change what the checks check. Same three steps, same order, same flags as ci(docs): validate docs.json and redirect destinations #2329 landed them.
• Does not set up automated bumps. A Dependabot/Renovate rule for this env value would be the follow-up if we want the version to keep moving on its own.
• Does not touch the mint CLI used locally by contributors, which is installed globally per AGENTS.md.

Urgency

This is the first thing in the queue that needs a review — nothing else can merge until it lands.

🤖 Generated with Claude Code