[benibauer3]

The hole, and the fix

mintlify validate fails on MDX syntax errors (an unclosed <Note>, a stray {) but passes a page that uses a component that does not exist, such as <Notte> or <CardGrup>. mintlify broken-links --check-redirects passes it too. Mintlify has nothing to render for the tag, and nothing in CI notices. PR previews do not build for this repo (#2430), so no one sees it before merge either.

This adds scripts/check_components.py (standard library only, same shape as check_redirects.py) and runs it in docs-validation.yml. A component in a page must be a Mintlify built-in, imported by that page, or defined by that page. Tags in fenced code blocks, inline code and comments are ignored, and lowercase tags (HTML) are not checked.

The built-in list is Mintlify's own: allowedComponents plus the components named in componentIds.js, from @mintlify/common 1.0.1164, which is what mintlify@4.2.920 (the CI pin) ships. The file carries the command to rebuild the list when MINTLIFY_VERSION is bumped. The trade-off: an allowlist can fail CI on a real component that Mintlify adds later, and the failure message says where to add it. The alternative, a deny-by-nothing check, would not catch anything.

Also in the diff: one line in AGENTS.md §1 (commands) and one in §6 (components), and an entry in scripts/README.md.

What this does NOT do / residual risk

• It does not check that an imported file exists or exports the name, or that a component gets the props it needs. Those need either a new check or a preview.
• It does not replace a visual check: layout, tables, images and tabs still need mint dev.
• Indented (4-space) code blocks are not recognised as code. None exist in the repo today; a tag inside one would be flagged.
• Pinned in tests: a closing tag alone is not counted, only opening tags; an unclosed fence runs to the end of the page (CommonMark behaviour).

Judgement calls

• Scope of files: every .md/.mdx except node_modules, submodules, scripts and hidden directories. snippets/*.mdx are included, because they render inside pages. Reversible: one constant, SKIPPED_DIRECTORIES.
• Member expressions (<Color.Row>, <NS.Thing>) are checked on the first part only, so <Color.Anything> passes. Lenient on purpose, to avoid a false red on a real nested component.
• Python, not Node: CI already runs Python checks; no new dependency.

Issues

Refs #2430. It does not close it: previews are still missing. This covers the one failure class validate misses, so reviewers need mint dev less often.

Stacking / conflicts

Branched off main, independent. Touches docs-validation.yml, AGENTS.md and scripts/README.md. I applied the diffs of the other open PRs that touch those files (#2432 and #2421) on top of this branch with git apply --check: both apply cleanly.

Verification evidence

All on this head (cced26b), Node 24, mintlify@4.2.920.

Green on the real docs: 235 files scanned, 638 component tags examined.

$ python3 scripts/check_components.py
No unknown components found.
$ python3 -m unittest discover -s scripts -p 'test_*.py'
Ran 56 tests in 0.052s   OK        (31 of them new)

Red on a misspelled page. I appended <Notte> and <CardGrup> blocks to build/agents/8004.mdx (then reverted). The existing Mintlify steps stay green; the new one fails:

$ npx -p node@24 -p mintlify@4.2.920 mintlify validate
success build validation passed
$ ... mintlify broken-links --check-redirects
success no broken links found
$ python3 scripts/check_components.py
Found 2 use(s) of a component that does not exist:
  build/agents/8004.mdx:470: <Notte> is not a Mintlify component and is not imported or defined in this page
  build/agents/8004.mdx:474: <CardGrup> is not a Mintlify component and is not imported or defined in this page
exit=1

Mutations of the script, each run against the new tests:

Mutation	Tests red
never flag	18
flag everything	10
ignore imports	4
ignore export const/function	2
check the full member name, not the first part	2
do not strip code and comments	8
scan node_modules/submodules/scripts	1
scan hidden directories	1
fence never closes	4
blanking drops newlines (line numbers shift)	2
exit code always 0	1
remove Note from built-ins	2

Not run here: the GitHub Actions run itself. This PR is from a fork, so the workflow may need approval before it runs.

Remaining ops steps

• none

Checklist

• Title is the commit message I want on main
• Ships tests; fixtures are inline strings; failure paths (flagged, exit 1) are tested
• Covers the seam: main() and the directory scan, not only the pure functions
• No error responses or secrets involved
• Judgement calls flagged above
• Tests pass locally on the current head
• README and AGENTS.md updated
• Not a UI, wallet, money or lockfile change
• Questions for the maintainer: is scanning snippets/ and the root .md files wanted? Say so and I will narrow SKIPPED_DIRECTORIES.

🤖 Generated with Claude Code

[mintlify]

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit cced26b.

Approve preview

[benibauer3]

@palango, could you review and approve this one? It adds a CI check for components that do not exist (<Notte>, <CardGrup>): mintlify validate and broken-links pass those today, and PR previews do not build (#2430), so nothing catches them before merge.

Two things I need from you, since this PR comes from a fork and my token cannot approve:

1. Approve the workflow run for this PR, so Documentation Validation runs with the new step. I ran every step locally on cced26b (Node 24, mintlify@4.2.920) and it is green; the output is in the description.
2. Review the one open question at the end of the description: the check scans every .md/.mdx except node_modules, submodules, scripts and hidden directories, including snippets/ and the root .md files. If you want it narrower, it is one constant (SKIPPED_DIRECTORIES).

It applies cleanly on top of #2432 and #2421 (checked with git apply --check). Separately, #2434 has your approval and is still open; it is ready to merge if you agree.