TOF-447: Add docs CI gates: frontmatter, links, redirects, code samples, OpenAPI

[Copilot]

Adds five Python validation scripts and a GitHub Actions workflow that block merges when docs quality invariants break.

Relates to: https://linear.app/mixpanel/issue/TOF-447/aeo-qw10-add-docs-ci-gates

Why this matters for AEO

Search engines and assistants redistribute code samples verbatim. A broken snippet does not just fail one reader — it propagates at scale into answers, repos, and other people's docs. The Next.js page in TOF-438 had shipped a snippet importing a function that was never defined; that is the class of defect this exists to stop.

The rest of the plan is a one-time cleanup that decays without enforcement. Every gate here corresponds to work in another quick win:

Gate	Locks in
Frontmatter: title, description, uniqueness	TOF-439 descriptions, TOF-445 titles
Internal links resolve to canonical routes	TOF-441
Redirects: no chains, loops, or duplicate sources	TOF-441
Code blocks declare a language	TOF-438
OpenAPI specs parse and resolve	TOF-447

Descriptions matter beyond hygiene: Mintlify generates llms.txt from that field, and /llms.txt was the single most-fetched page by AI agents in the trailing 30 days at 7,833 requests. A page without a description renders bare in the index agents actually read.

The gates

• check_frontmatter.py — every page needs a non-empty title and description, and no two pages may share a rendered title
• check_links.py — internal links must resolve to a real page or a redirect source; code fences and inline code are excluded so a page documenting an example link does not fail
• check_redirects.py — no duplicate sources, no loops, no chains (a destination that is itself redirected), and every destination resolves
• check_code_samples.py — every fenced block declares a language
• check_openapi.py (new) — all 14 specs parse, carry openapi/info/paths, and every local $ref resolves. Uses openapi-spec-validator for full schema validation when installed, and then checks every example (media-type, parameter, and schema-level) against the schema it illustrates. Still runs structurally without the validator.

Fixes from review

check_redirects.py had an 88% false-positive rate. Its docstring says chained redirects are allowed, but it only matched exact sources and ignored the 461 wildcard sources in docs.json. It reported 25 errors on main of which 3 were real. A gate that noisy gets disabled in a week.

It also could not see loops. Every node in a cycle is itself a source, so the chained-redirect rule silently swallowed /self → /self and /a → /b → /a. Both now fail.

check_links.py would have failed any future page showing an example link inside a code fence. Zero occurrences today, which is exactly when it is cheap to fix.

check_code_samples.py mis-parsed nested fences — a ```python block inside a ````mdx block closed the outer one early.

Actions are now pinned to commit SHAs, matching stale.yml. Four near-identical jobs collapsed into one with ordered steps, plus a concurrency group.

Verification

Each gate was executed, not just reviewed:

• All five pass on this branch's content
• Each fails on a deliberate bad fixture: empty title, bare fence, dead link, redirect loop, spec with a dangling $ref
• check_openapi.py validates all 14 real specs

Existing violations: baselined, not blocking

The first CI run failed because the frontmatter gate correctly found real problems already on main: 362 pages without a description and 14 groups of duplicate titles. The checker wasn't wrong, but a gate that fails every unrelated PR on day one would get disabled.

So each check can list known violations in scripts/docs-ci-baseline.json. Only new violations fail. A new page without a description, a new duplicate title, or a new redirect chain is blocked; old ones aren't.

Gate	Blocking?	Baselined today
Frontmatter (title, description, unique titles)	Yes, for new violations	407 entries (362 descriptions, 45 duplicate-title pages)
Code samples declare a language	Yes, fully	0 (two bare fences from main fixed here)
Internal links	Yes, fully	0
Redirects (duplicates, loops, chains, dead destinations)	Yes, for new violations	229 chains
OpenAPI (parse, structure, $refs, schema, examples)	Yes, fully	0 (one invalid GDPR example fixed here)

Baseline entries that stop occurring print a note but never fail. So the cleanup PRs can land in any order without touching the baseline. Verified against each tree: #172 clears all 362 description entries, #178 clears all 45 duplicate-title entries, #174 clears all 229 chains. Prune afterwards with:

python scripts/check_frontmatter.py --update-baseline
python scripts/check_redirects.py --update-baseline

Merge order no longer matters. This PR can merge before or after #172, #174, and #178.

Not implemented

Rec #20 Part B asks that priority code examples be compiled or smoke-tested, not just checked for a language tag. That needs fixtures or runnable example projects per language and is a larger piece of work. The Next.js page was instead verified by hand for TOF-438: both routers scaffolded with create-next-app, every snippet transcribed verbatim, npm run build and npm run dev passing in both.

[linear-code]

TOF-447

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
mixpanel-docs	🟢 Ready	View Preview	Sep 25, 2026, 8:17 PM

[greptile-apps]

Confidence Score: 4/5

[Medium risk] Adds documentation validation gates to the CI pipeline.

The PR is not safe to merge until its link gate accepts the new Markdown-format documentation link.

_{Reviews (7) · Last reviewed commit: "Merge branch 'main' into copilot/tof-447..."}

[tylergoerzen-mxp]

Ready for review. Docs checks is green on 09a6745.

Why the job was failing

The checker wasn't buggy. The frontmatter gate correctly found real problems already on main: 362 pages without a description and 14 groups of duplicate titles. Merging it as-is would have blocked every unrelated PR.

What changed

• Baseline for existing violations. Known violations live in scripts/docs-ci-baseline.json. Only new ones fail. Fixed entries print a note but never fail, so TOF-439: Backfill description frontmatter on every docs page #172, TOF-441: Flatten redirect chains and fix internal links to redirected URLs #174, and TOF-445: Title-to-query alignment pass across 38 docs pages #178 can land in any order.
• Redirect chains now fail (Greptile). 229 existing chains are baselined; TOF-441: Flatten redirect chains and fix internal links to redirected URLs #174 clears all of them.
• Wildcard redirect destinations must match at least one page (Greptile).
• OpenAPI examples are validated against their schemas (Greptile). This caught one real error in the GDPR spec, fixed here.
• Merged main, resolved conflicts in docs.json and reference/event-deduplication.mdx, and tagged two bare code fences that landed on main.

What each gate enforces

Gate	Enforces	Blocking	Baselined
Frontmatter	Non-empty title and description, unique titles	New violations	407 (362 descriptions, 45 duplicate-title pages)
Code samples	Every fence declares a language	Fully	0
Internal links	Links resolve to a page or redirect	Fully	0
Redirects	No duplicate sources, loops, or chains; destinations exist	New violations	229 chains
OpenAPI	Parses, required structure, local $refs, spec schema, examples match schemas	Fully	0

None of the gates are warn-only.

Updating the baseline

After a cleanup PR merges, prune the fixed entries:

python scripts/check_frontmatter.py --update-baseline
python scripts/check_redirects.py --update-baseline

Don't use --update-baseline to get a new violation past CI. Fix it instead.

Out of scope

Greptile flagged that the Slack Bot and Warehouse Sync Monitoring redirects in docs.json point to general pages. Those came in from main, not from this PR.