Skip to main content

​
AGENTS.md

Guidance for AI coding agents (Cursor, Claude, Windsurf, Warp, GitHub Copilot, etc.) working in this repository.

​
Project Overview

This is the public documentation site for the entire D-Sports ecosystem, built on Mintlify. It documents:
  • The D-Sports API (full OpenAPI reference + per-domain narrative docs)
  • The D-Sports Engage native mobile app (architecture, integration contracts, compliance evidence)
  • The d-sports-backend Rust rewrite (parity/shim only — not the production API)
  • The leagues data repo (league assets, sync workflows, canonical team data)
  • The d-sports-site marketing site
  • The Game Engine (native client, API server, modularity) as its own Guides section
  • Cross-cutting topics: ecosystem overview, AI tooling integration (Cursor, Claude Code, Windsurf), authentication, errors, rate limits
Pages are MDX files with YAML frontmatter. Configuration lives in docs.json. Run mint dev to preview locally. To refresh the site from latest source main branches, run /update-docs. That command loads .cursor/skills/update-docs/SKILL.md: pull d-sports-api, d-sports-engage-native, and d-sports-backend, diff OpenAPI/routes, update the spec in the API repo first if needed, sync it here, then rewrite narrative pages and nav.

​
Build & Run Commands

The predev hook runs bun run sync-openapi automatically before mint dev. The script lives at scripts/sync-openapi.ts and copies openapi.json from d-sports-api (--api, D_SPORTS_API, or sibling ../d-sports-api) into api-reference/openapi.json. If that checkout is missing, it keeps the committed spec.

​
Repository Layout

​
Conventions

​
Frontmatter (every MDX page)

​
Style

  • Active voice, second person (“you”) — talking to the reader
  • One idea per sentence — keep it scannable
  • Sentence case for headings (## Adding a new endpoint, not ## Adding A New Endpoint)
  • Bold for UI elements: “Click Settings”
  • Code formatting for file names, paths, commands, and code references (e.g. prisma/schema.prisma)
  • Avoid emoji unless the surrounding doc already uses them
  • All sidebar / tab structure is in docs.json. New pages must be referenced there or they won’t appear in the nav.
  • Run mint broken-links after restructuring to catch dangling references.

​
OpenAPI

  • Never hand-edit api-reference/openapi.json. It is regenerated from d-sports-api’s spec by scripts/sync-openapi.ts.
  • If the API changes, update the spec in d-sports-api, then re-run bun run sync-openapi here, then update the matching narrative page under api-reference/domains/<domain>.mdx and the deep dive under repositories/d-sports-api/<domain>/.
  • The endpoint coverage tracker is at api-reference/domains/route-coverage-matrix.mdx.

​
Common Tasks

​
Add a new docs page

  1. Create the MDX file in the right folder (mirror existing structure).
  2. Add proper frontmatter (title, description minimum).
  3. Add the page to docs.json under the right group/tab.
  4. Run bun run dev and verify it renders + appears in the sidebar.
  5. Run mint broken-links if you added cross-page links.

​
Document a new API domain

  1. Add narrative page under api-reference/domains/<new-domain>.mdx.
  2. Mirror with deep-dive folder repositories/d-sports-api/<new-domain>/ containing at least index.mdx, architecture.mdx, behavior.mdx.
  3. Update repositories/d-sports-api.mdx to link the new domain.
  4. Add both pages to docs.json.

​
Update an integration contract

For native ↔ API contract changes, update both: Keep them in sync — they are the canonical contract docs that cross-team reviewers read.

​
Mintlify Quick Reference

Full schema: mintlify.com/docs.json. Component cheat sheet: mintlify.com/docs/llms.txt.

​
Code blocks

Fenced blocks support title, icon, lines, wrap, expandable, highlight, focus, twoslash, and diff syntax (// [!code ++] / // [!code --]).
filename.ts

​
MDX 3

Mintlify supports MDX 3: adjacent block JSX/expressions without extra newlines, await in expressions, ES2024 syntax.

​
Sibling Workspaces

This documentation site sits alongside the code repos it documents: When the source repo changes, the docs need to keep up. The d-sports-api repo is the most coupled — most doc PRs here are paired with one there.

​
What Not To Do

  • Don’t hand-edit api-reference/openapi.json. It’s generated.
  • Don’t write docs that duplicate repositories/<repo>/AGENTS.md — link to the source repo instead. AGENTS.md files are for in-repo agent guidance; this site is for end-users and integrators.
  • Don’t ship product features from this repo. Code lives in the sibling repos.
  • Don’t add a page without registering it in docs.json — Mintlify won’t surface it in the nav.

​
Optional: Mintlify MCP

For live docs search inside an agent, see the Mintlify MCP server. The workspace d-sports-engage-native already wires it into .cursor/mcp.json as Mintlify Docs.

​
Cursor Cloud specific instructions

The dependency-refresh step (bun install) runs automatically on VM startup. bun and the mint CLI are pre-installed in the environment snapshot (both on PATH via /usr/local/bin); you do not need to install them.
  • bun run sync-openapi keeps the committed spec when d-sports-api is not beside this repo. Pass --api <dir> or set D_SPORTS_API to copy from a checkout. bun run dev can run in the cloud VM without a sibling clone. The generated api-reference/openapi.json is already committed. mint dev serves on http://localhost:3000.
  • Lint/validate commands both run but exit non-zero for pre-existing, non-environment reasons (see the Build & Run Commands and Development sections). mint broken-links reports the four ../<sibling-repo>/ links in this file (AGENTS.md is agent guidance, not a published page). mint validate emits one warning because Mintlify tries to validate docs.json as an OpenAPI file. Neither indicates a broken setup.