Make the lint targets resolve their own tooling

[shreyav]

Summary

Two unrelated faults in the lint plumbing. Makefile + package.json, 4 lines.

1. make lint-markdown never worked

The target runs npm run lint:markdown, and that script doesn't exist — so it failed with npm's "Missing script" error rather than any lint output.

markdownlint-cli is already a devDependency and .markdownlint.json is already committed, so the script was the only missing piece. Added:

"lint:markdown": "markdownlint \"mintlify/**/*.mdx\""

The target now fails with real lint output instead of a missing-script error — roughly 450 violations across mintlify/**/*.mdx, dominated by MD031 (79), MD012 (77), MD022 (74) and MD009 (74). Almost all are whitespace.

That is the intended outcome here: a linter reporting genuine violations is working, and the previous state hid them entirely. Fixing the 450 is deliberately not in this PR — it's a large mechanical reformat that would conflict with every open docs PR, including #794, which adds 927 lines to external-accounts.mdx. It should land on its own once the docs queue is clear.

2. npx spectral can execute a package nobody vetted

lint:openapi and the lint-spectral target both called npx spectral. That resolves correctly once dependencies are installed — @stoplight/spectral-cli provides a spectral bin.

On a clean checkout it does not. npx finds no local binary, falls through to the registry, and silently downloads and runs an unrelated package that happens to be named spectral. The lint then appears to pass, having executed something that isn't Spectral at all.

Calling the binary directly from an npm script uses node_modules/.bin and cannot fall through:

- npx spectral lint openapi.yaml --fail-severity=error
+ spectral lint openapi.yaml --fail-severity=error

Also adds a lint:spectral script so the Makefile target routes through npm rather than reaching for npx itself.

Correcting something I've been repeating

I have described make lint as "broken on main" in several recent PR descriptions (#661, #777, #793, #794), attributing it to spectral resolving to a stub. That was overstated. make lint works fine on a checkout with dependencies installed — I hit the failure in an environment where npm install hadn't been run and generalised from it. The stub-resolution hazard is real and worth removing, but it is a fresh-checkout footgun, not a permanently broken target. The genuinely broken one was always lint-markdown.

Verification

• make lint-spectral → exit 0, and node_modules/.bin/spectral confirmed to symlink @stoplight/spectral-cli/dist/index.js
• make lint-markdown → now executes the linter and reports violations (exit 1) instead of "Missing script"
• No lockfile churn — package-lock.json untouched
• Script ordering in package.json kept readable; no other scripts altered

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored		Aug 4, 2026 3:54pm
grid-wallet-demo	Ignored		Aug 4, 2026 3:54pm