Make the Mintlify trigger reliable

[roh26it]

Summary

The Mintlify trigger ran on every merge and always passed, but docs often did not update. This PR fixes the two causes in this repo.

Problem	Fix
The job called Mintlify about 5 s after the push. raw.githubusercontent.com sends cache-control: max-age=300, so the build could fetch a stale openapi.yaml.	Wait 310 s after a push. Then fail if the raw URL does not match openapi.yaml at the pushed commit.
curl ignored HTTP errors, and the job never checked the result. A bad token or a failed build still passed.	Use --fail-with-body, require a statusId, then poll GET /v1/project/update-status/{statusId} until success or failure. A failure prints the Mintlify summary and logs.

Other changes:

• The workflow has two jobs. wait-for-spec waits and checks the spec; a newer push cancels it, which is safe because nothing has gone to Mintlify yet. deploy triggers and polls; it queues and is never cancelled, so each Mintlify build finishes before the next one starts.
• workflow_dispatch lets you run the workflow by hand from the Actions tab. A manual run skips the wait. Both jobs run only on master, because the spec check always reads the master URL.
• The workflow uses the existing MINTLIFY_TOKEN and MINTLIFY_PROJECT_ID secrets. No new secrets.

This PR does not make new endpoints appear. docs-core API pages are stubs, so each new endpoint also needs a stub page and a nav entry in docs-core (for example, Portkey-AI/docs-core#1098 for /decisions).

Test plan

• Workflow YAML parses, and bash -n passes on each run script
• The hash check matches today: git show origin/master:openapi.yaml and the raw URL have the same SHA-256
• After merge, the run on master waits, triggers, and ends with Mintlify status: success
• A manual workflow_dispatch run on master skips the wait; a run on another branch skips both jobs

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

Deployment ordering and manual-dispatch reliability issues remain unresolved.

Review effort: Lite
Findings: 1 · 1

Open (2)

• Cancelled runs can overwrite newer Mintlify deployments · New
• Manual runs can compare a branch against the master spec · New

What changed in this PR

Improves Mintlify documentation deployments by validating spec freshness and monitoring deployment status.

Changes:

• Adds delayed spec validation and hash checks.
• Polls Mintlify deployment results and reports failures.
• Adds manual dispatch and concurrency controls.

File	Summary
.github/​workflows/​mintlify-update.yml	Updates the workflow for validated Mintlify deployments.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The concurrency configuration can replace pending deployments, so it does not guarantee every merge is processed.

Review effort: Lite
Findings: None

Resolved since last review (2)

• Cancelled runs can overwrite newer Mintlify deployments
• Manual runs can compare a branch against the master spec