Generate GraphQL API reference from schema at build time

[dkijania]

Part of #1195 (Track 2).

Goal

Replace the single hand-written prose page (docs/node-developers/graphql-api.mdx) with a structured, per-type reference generated from MinaProtocol/mina's graphql_schema.json at build time. This is the single biggest win for AI agent discoverability of the GraphQL surface.

Why generate

Today's page is one MDX file with a handful of cherry-picked queries. An LLM agent asking "what fields does bestChain accept?" or "what mutations exist?" has no structured answer to scrape — only prose. A schema-generated reference gives:

• Per-type pages with stable URLs (/integrate/graphql-api/queries/best-chain, /integrate/graphql-api/types/Block, etc.)
• Field-level documentation pulled directly from the schema's description strings
• Always in sync with the daemon's actual schema — no drift

Approach

1. Add a build script (scripts/generate-graphql-reference.mjs) that:
   • Fetches graphql_schema.json from MinaProtocol/mina at the pinned branch (compatible or whatever the docs reflect).
   • Walks the schema and emits .mdx files under docs/integrate/graphql-api/{queries,mutations,subscriptions,types,enums,scalars}/<name>.mdx.
   • Also emits a _meta.js or sidebar fragment so sidebars.js can include the generated tree without manual edits.
2. Wire it into package.json build step before docusaurus build (alongside the existing generate-llms-txt.mjs).
3. Add to CI: regenerate and git diff --exit-code to catch schema drift, same pattern as check-llms-txt.
4. Decide: commit the generated MDX (current pattern, fits llms-full.txt and search) or generate at build only (smaller repo, but search index degrades). Recommend commit for parity with llms-full.txt.

Tools to consider: graphql-markdown, @graphql-tools/load, or a small custom script. Custom is probably simpler than fighting graphql-markdown's opinions.

Acceptance criteria

• scripts/generate-graphql-reference.mjs exists and runs cleanly against the pinned schema source.
• Generated tree under docs/integrate/graphql-api/{queries,mutations,subscriptions,types,enums,scalars}/.
• sidebars.js includes the generated tree (manually or via a generated fragment).
• Old docs/node-developers/graphql-api.mdx either removed or kept as a 1-paragraph orientation page that links into the generated reference.
• CI step check-graphql-reference (or extension of check-llms-txt) catches drift.
• static/llms-full.txt regenerated.

Depends on

Section structure from #1195 Track 1 (path under docs/integrate/graphql-api/). If that issue isn't done first, generate under a temporary path and move later.