Improve developer & AI discoverability: SDKs, GraphQL, Docker Compose

[dkijania]

Goal

Improve the docs2 site's structure and content for both human developers and AI agents (LLM-assisted exploration, scraping, codegen). Three concrete tracks below — each can ship independently.

Track 1 — New top-level "Integrate with Mina" section

The current top-level IA is role-based (zkApp Developer, Node Developer, Node Operator, Exchange Operator). There is no canonical home for integrators — wallets, indexers, exchanges, bridges, services consuming Mina via SDK or API. As a result:

• mina-signer floats at the docs root.
• The various SDKs (mina-sdk-rust, mina-sdk-go, mina-sdk-python, plus the upcoming mina-archive-sdk-js / mina-archive-sdk-go for archive-node-api) have no entry point in the docs.
• Exchange Operators is its own silo even though it's effectively a use case built on Rosetta + archive + signer.

Proposed structure

Integrate with Mina/
  index.mdx                       (overview + decision tree: which SDK for what)
  sdks/
    overview.mdx                  (matrix: language × capability × status)
    rust.mdx                      (mina-sdk-rust)
    go.mdx                        (mina-sdk-go)
    python.mdx                    (mina-sdk-python)
    archive-js.mdx                (mina-archive-sdk-js)
    archive-go.mdx                (mina-archive-sdk-go)
  graphql-api/                    (see Track 2)
  archive-node-api/               (REST/GraphQL surface of archive-node-api)
  rosetta/                        (link or move from exchange-operators)
  webhooks-and-streaming/         (subscriptions, future)

Each SDK page should follow a fixed template: Install / Quickstart / Auth / Common operations / Link to autogenerated reference / Repo + issues. Predictable URL structure matters for AI agents — they can navigate by pattern.

API reference itself stays autogenerated in each SDK's own repo (rustdoc, godoc, sphinx). docs2 hosts the narrative + canonical link.

Open question

Should Exchange Operators remain separate, or fold under Integrate as a use-case page composing Rosetta + archive SDK + signer?

---

Track 2 — GraphQL: schema-generated reference + live playground

Today docs/node-developers/graphql-api.mdx is one prose page with hand-pasted queries. It's the worst case for AI agents — no structured per-field schema, no live exploration.

Proposed changes

1. Schema-generated reference. Pull graphql_schema.json from MinaProtocol/mina at build, generate per-type pages (queries / mutations / subscriptions / types) under integrate/graphql-api/. Tools: graphql-markdown or a small custom script. AI agents get structured per-field docs instead of prose.
2. Live GraphiQL/Playground page embedded in MDX, pointed at a public devnet endpoint, read-only (mutation buttons hidden / mutations rejected at proxy). Libraries: @graphiql/react or graphql-playground-react.
3. Cookbook of example queries split by use case — each as its own .mdx:
   • "Get account balance"
   • "Watch new blocks"
   • "Estimate transaction fee"
   • "Find a transaction in archive"
   • etc.
4. Skip mock data initially. A live devnet endpoint is more useful than mocks and avoids drift. If devnet rate-limits become a problem, add a thin Cloudflare Worker proxy with caching.

Tradeoff

Live endpoint means the playground breaks if devnet is down. Schema-generated reference adds a build-time dependency on MinaProtocol/mina.

---

Track 3 — Docker Compose examples: stop maintaining content twice

Today docs/node-operators/{archive-node,block-producer-node,seed-peers,snark-workers}/docker-compose.mdx and docs/exchange-operators/rosetta/docker-compose.mdx contain inline YAML with hardcoded image tags (e.g. 3.3.0-8c0c2e6-bullseye-mainnet in block-producer-node/docker-compose.mdx:20). These drift from the network release every cycle.

Options

• Keep inline + tag check: extend validate-docker-images to assert tags match the current release manifest. Lowest disruption.
• Reference + embed at build time: replace inline YAML with a remark plugin that fetches from a canonical source (e.g. a MinaProtocol/mina-deployment-examples repo) at build. Best for AI/scraping (still inline in HTML) and removes drift. Recommended.
• Reference only: short prose + deep link. Lightest to maintain, worst for casual readers and AI scrapers.

Tradeoff

Build-time embed adds CI complexity (fetches from external repo) but eliminates copy/paste drift permanently.

---

Cross-cutting: AI discoverability

• llms-full.txt is generated and CI-checked (good).
• Add a top-level llms.txt index pointing to per-section landing pages so agents can navigate without scraping the full bundle.
• Ensure each SDK page and each generated GraphQL type page has stable, predictable URLs.

---

Suggested order of execution

1. Integrate with Mina section + SDK landing pages (low risk, high signal — even stubs improve discoverability).
2. Schema-generated GraphQL reference (biggest AI win, replaces thin prose page).
3. Live GraphiQL playground page.
4. Docker Compose embed-from-source (after deciding canonical home for the YAML).

Each track is independently shippable.