> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# CLAUDE

# Trophy Docs

Mintlify documentation site for Trophy. Repo-root paths are the canonical English source; `es/**` is generated by the translation workflow. See `README.md` for Lingo and MCP setup (Cursor-specific steps there).

## Dev server

* Never open a browser when starting the dev server. Use `npm run dev` (already passes `--no-open`) or, if invoking Mintlify directly, always pass `--no-open` (for example `mint dev --no-open`).

## Writing style

* Never abbreviate "leaderboard" to "board" in docs copy, comments or commit messages. Always write "leaderboard".

## Localization Workflow

* Treat repo-root docs paths as the canonical English source and keep identical relative file paths/filenames across all locales.
* For planned doc changes, default scope to English source files only. Do not plan or execute manual edits to non-English locale content (for example `es/**`) unless the user explicitly asks for localized updates; rely on the existing translation workflow to propagate English changes.
* Keep all locale navigation in `docs.json` under `navigation.languages`; do not reintroduce `navigation.global` or top-level `navbar`.
* Keep SEO metatags in English unless explicitly requested otherwise.
* Do not translate code snippets, inline code, URLs, route slugs, or API identifiers.
* Shared media lives under repo-root `assets/`. Default-language pages are at repo-root section paths (for example `<section>/<page>.mdx`) and targets are under locale directories (for example `es/<section>/<page>.mdx`), so relative `src` paths need one more `../` under each locale segment than in English. `scripts/localize-internal-links.mjs` rewrites markdown `](/...)` and JSX `href="/..."` only (absolute navigation paths). Relative repo-root `assets/` `src` and MDX `import` paths are normalized by `scripts/localize-mdx-paths.mjs` after Lingo.
* `scripts/localize-mdx-paths.mjs` rewrites: `<locale>/components/*.jsx` for the active locale; `from ".../snippets/..."`; and JSX `src=".../assets/..."` so `../` depth matches the file’s path. Run after Lingo in `translate:generate` and translate-on-main; CI checks via `translate:localize-mdx-paths:check`.
* Shared MDX snippets live under repo-root `snippets/` (not per-locale). Import with relative paths from each page; do not add shared MDX snippets to Lingo `i18n.json` buckets unless you intend to translate them.
* Locale-aware React components that can contain text live under `components/*.jsx` for default language and `<locale>/components/*.jsx` for targets, and are manually maintained per locale (do not add them to Lingo `i18n.json` buckets; do not keep these in shared `snippets/`).
* Endpoint and webhook MDX must pin a **repo-local** OpenAPI file in frontmatter (do **not** put remote OpenAPI URLs in frontmatter, and do **not** set tab/group-level `openapi` in `docs.json` navigation—tab `openapi` auto-populates endpoints and duplicates MDX nav entries; remote URLs in frontmatter are not reliably resolved by Mintlify). Specs live under `openapi/application.json` (Application API + webhooks) and `openapi/admin.json` (Admin API), also listed under `api.openapi` in `docs.json`. Forms: `openapi: "/openapi/application.json GET /path"`, `openapi: "/openapi/application.json webhook <eventKey>"`, `openapi: "/openapi/admin.json METHOD /path"`. Keep those lines identical across locales; Lingo must not alter them.
* English **nav titles** for those pages come from OpenAPI **`summary`** via `scripts/sync-openapi-titles.mjs` (`npm run translate:sync-openapi-titles`). It runs at the start of `translate:generate` and on the translate-on-main workflow. Lingo translates the `title` field for target locales; the script only fills a missing target `title` with English (bootstrap)—it does not overwrite existing translations.
* Mintlify custom heading IDs use markdown `## Title {#slug}` (see Mintlify docs). Slugs are aligned from English source root files via `scripts/sync-heading-anchors.mjs`. Never translate or alter `{#…}`; sync runs after Lingo in PIT/CI. Do not merge heading-count drift between source root and target locales without fixing structure first.
* For Mintlify `<Accordion>` components that may be deep-linked, always set explicit `id` values (do not rely on title-derived hashes) and keep those `id`s identical across locales.
* Do not use fragile OpenAPI parameter hash links like `#parameter-*` in docs links; link to the endpoint page and reference parameter names inline in prose/code.
* Treat `lingo/brand-voice.md` as the source of truth for **brand voice** (tone and style) only. Do not add structural or tooling rules there (for example Mintlify `{#slug}` handling); those stay in this rule, README, and optionally in the Lingo engine **Instructions** field—not brand voice.
* Do not add script-based brand voice sync; sync brand voice on demand via Lingo MCP tools from chat.
* Treat `lingo/glossary.csv` as the glossary source of truth; use MCP sync with canonical key `sourceLocale|targetLocale|type|sourceText`.
* For glossary sync, always do dry-run first, show create/update/delete counts, then apply on confirmation.
* When adding locales, update both `docs.json` language blocks and `i18n.json` `locale.targets`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.