Merge pull request #94 from trophyso/leaderboard-eligibility

leaderboard eligibility

Author: cbrinicombe13

.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "permissions": {
+    "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./.env.*.local)"]
+  }
+}

CLAUDE.md

@@ -0,0 +1,29 @@
+# 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).
+
+## 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`.

assets/features/leaderboards/eligibility.png

@@ -134,6 +134,46 @@ Para obtener las clasificaciones de un grupo particular de usuarios con una comb
   para que un usuario se incluya en las clasificaciones devueltas.
 </Note>
 
+## Elegibilidad {#eligibility}
+
+La elegibilidad controla qué usuarios pueden participar en una clasificación. Úsala cuando una clasificación deba estar abierta solo a un grupo específico de usuarios, por ejemplo, clientes de pago, una región concreta o una cohorte beta.
+
+La elegibilidad se basa en [atributos de usuario personalizados](/es/features/users#custom-user-attributes). Un usuario solo puede participar en una clasificación, y aparecer en su ranking, si sus atributos cumplen todas las reglas de elegibilidad que definas. Las clasificaciones sin reglas de elegibilidad están abiertas a todos los usuarios.
+
+Para definir reglas de elegibilidad, ve a la página de configuración de la clasificación y añade uno o más atributos de usuario, junto con los valores que deben tener los usuarios, en el campo **Atributos de usuario** de la sección **Elegibilidad**.
+
+<Frame>
+  <img
+    height="200"
+    width="100%"
+    noZoom
+    src="../../assets/features/leaderboards/eligibility.png"
+  />
+</Frame>
+
+<Note>
+  Cuando defines varias reglas de elegibilidad, un usuario debe cumplirlas todas
+  para ser elegible.
+</Note>
+
+Los usuarios que no son elegibles no reciben puntuación y no aparecen en los rankings. Las posiciones se calculan solo entre los usuarios elegibles, por lo que no quedan huecos donde habría estado un usuario no elegible. Si los atributos de un usuario cambian y ya no cumplen las reglas, Trophy lo elimina de la ejecución actual de la clasificación.
+
+Las ejecuciones históricas nunca se modifican. Una vez que una ejecución ha finalizado, sus rankings quedan fijados, independientemente de cómo cambien después los atributos de los usuarios.
+
+<Note>
+  Las reglas de elegibilidad solo se pueden cambiar mientras una clasificación está `Inactive`. Consulta
+  [estados de la clasificación](#leaderboard-statuses).
+</Note>
+
+### Elegibilidad frente a desgloses {#eligibility-vs-breakdowns}
+
+Los [desgloses](#ranking-breakdowns) y la elegibilidad usan atributos de usuario, pero cumplen funciones distintas:
+
+- **Los desgloses** dividen a los participantes en grupos más pequeños. Todos los usuarios siguen clasificados, pero dentro de su propio grupo.
+- **La elegibilidad** decide quién puede participar. Los usuarios que no cumplen las reglas quedan excluidos por completo.
+
+Puedes usar ambas opciones en la misma clasificación, por ejemplo, para limitar una clasificación a los usuarios de pago y luego agruparlos por país.
+
 ## Fechas de Inicio y Fin {#start-end-dates}
 
 Usa fechas de inicio y fin para controlar la ventana dentro de la cual las clasificaciones están clasificando activamente a los usuarios.
@@ -211,6 +251,8 @@ Si una clasificación ya tiene un número de participantes que coincide con su m
 
 La única excepción a esto es cuando se utilizan [atributos de desglose](#ranking-breakdowns) para agrupar a los participantes en cohortes más pequeñas. Al usar atributos de desglose, el límite de participantes se aplica a cada grupo, no de manera general.
 
+Si una clasificación tiene reglas de [elegibilidad](#eligibility), el límite de participantes solo cuenta a los usuarios elegibles.
+
 <Tip>
 Si necesitas un límite de participantes mayor, considera usar [atributos de desglose](#ranking-breakdowns) para agrupar a los participantes en cohortes más pequeñas. O contáctanos en [support@trophy.so](mailto:support@trophy.so) y estaremos encantados de aumentar tus valores predeterminados.
 </Tip>
@@ -255,7 +297,7 @@ Para crear una clasificación, dirígete a la [página de clasificaciones](https
     </Step>
 
     <Step title="Guarda los cambios">
-    Guarda los cambios y dirígete a la página de configuración para establecer [fechas de inicio y fin](#start-end-dates), [programaciones de clasificaciones recurrentes](#repeating-leaderboards) y más.
+    Guarda los cambios y ve a la página de configuración para definir la [elegibilidad](#eligibility), las [fechas de inicio y fin](#start-end-dates), las [programaciones de clasificaciones recurrentes](#repeating-leaderboards) y más.
     </Step>
 
 </Steps>
@@ -365,6 +407,14 @@ Este gráfico es un histograma de las puntuaciones de los usuarios en una clasif
 
 {" "}
 
+<Accordion id="leaderboard-eligibility-faq" title="¿Puedo limitar una clasificación a determinados usuarios?">
+  Sí. Añade reglas de [elegibilidad](#eligibility) a la clasificación mediante atributos
+  de usuario personalizados, y solo los usuarios con los valores de atributo correspondientes podrán
+  participar y aparecer en la clasificación.
+</Accordion>
+
+{" "}
+
 <Accordion id="leaderboard-weekly-faq" title="No veo una opción de clasificación semanal, ¿cómo puedo configurar una?">
   Trophy admite la ejecución de clasificaciones repetitivas en cualquier número
   arbitrario de días. Así que una clasificación semanal sería simplemente una clasificación que se repite cada 7

es/features/leaderboards.mdx

@@ -187,6 +187,13 @@ Los atributos personalizados de usuario pueden utilizarse para personalizar logr
   >
     Controla qué usuarios reciben correos electrónicos gamificados.
   </Card>
+  <Card
+    title="Elegibilidad para clasificaciones"
+    icon="ranking-star"
+    href="/es/features/leaderboards#eligibility"
+  >
+    Limita las clasificaciones a grupos específicos de usuarios.
+  </Card>
   <Card
     title="Personalización de Correos Electrónicos"
     icon="trophy"

es/features/users.mdx

@@ -134,6 +134,46 @@ To fetch rankings for a particular group of users with a specific combination of
   for a user to be included in the returned rankings.
 </Note>
 
+## Eligibility {#eligibility}
+
+Eligibility controls which users are allowed to take part in a leaderboard at all. Use it when a leaderboard should only be open to a specific group of users, for example paying customers, a particular region or a beta cohort.
+
+Eligibility is based on [custom user attributes](/features/users#custom-user-attributes). A user can only take part in, and appear in the rankings of, a leaderboard if their attributes match every eligibility rule you set. Leaderboards with no eligibility rules are open to all users.
+
+To set eligibility rules, head to the leaderboard configuration page and add one or more user attributes and the values users must have in the **User attributes** field of the **Eligibility** section.
+
+<Frame>
+  <img
+    height="200"
+    width="100%"
+    noZoom
+    src="../assets/features/leaderboards/eligibility.png"
+  />
+</Frame>
+
+<Note>
+  When you set multiple eligibility rules, a user must match all of them to be
+  eligible.
+</Note>
+
+Users who aren't eligible are not scored and don't appear in rankings. Ranks are calculated across eligible users only, so there are no gaps where ineligible users would have been. If a user's attributes change and they no longer match, Trophy removes them from the current run of the leaderboard.
+
+Historical runs are never changed. Once a run has finished its rankings are fixed, regardless of how users' attributes change afterwards.
+
+<Note>
+  Eligibility rules can only be changed while a leaderboard is `Inactive`. See
+  [leaderboard statuses](#leaderboard-statuses).
+</Note>
+
+### Eligibility vs Breakdowns {#eligibility-vs-breakdowns}
+
+[Breakdowns](#ranking-breakdowns) and eligibility both use user attributes but do different jobs:
+
+- **Breakdowns** split participants into smaller groups. Every user is still ranked, just within their own group.
+- **Eligibility** decides who can participate. Users who don't match are excluded entirely.
+
+You can use both on the same leaderboard, for example to limit a leaderboard to paying users and then group them by country.
+
 ## Start & End Dates {#start-end-dates}
 
 Use start and end dates to control the window within which leaderboards are actively ranking users.
@@ -213,6 +253,8 @@ If a leaderboard already has a number of participants that matches its configure
 
 The only exception to this is when using [breakdown attributes](#ranking-breakdowns) to group participants into smaller cohorts. When using breakdown attributes the participant limit applies to each group, not overall.
 
+If a leaderboard has [eligibility](#eligibility) rules, the participant limit only counts eligible users.
+
 <Tip>
 If you require a larger participant limit, considering using [breakdown attributes](#ranking-breakdowns) to group participants into smaller cohorts. Or please contact us at [support@trophy.so](mailto:support@trophy.so) and we'll be happy to increase your defaults.
 </Tip>
@@ -257,7 +299,7 @@ To create a leaderboard, head to the [leaderboards page](https://app.trophy.so/l
     </Step>
 
     <Step title="Hit save">
-    Hit save and head to the configure page to set up [start & end dates](#start-end-dates), [repeating leaderboard schedules](#repeating-leaderboards) and more.
+    Hit save and head to the configure page to set up [eligibility](#eligibility), [start & end dates](#start-end-dates), [repeating leaderboard schedules](#repeating-leaderboards) and more.
     </Step>
 
 </Steps>
@@ -367,6 +409,14 @@ This chart is a histogram of users' scores in a particular leaderboard. This is
 
 {" "}
 
+<Accordion id="leaderboard-eligibility-faq" title="Can I limit a leaderboard to certain users?">
+  Yes. Add [eligibility](#eligibility) rules to the leaderboard using custom
+  user attributes, and only users with matching attribute values will be able
+  to take part and appear in the rankings.
+</Accordion>
+
+{" "}
+
 <Accordion id="leaderboard-weekly-faq" title="I don't see a weekly leaderboard option, how can I set one up?">
   Trophy supports running repeating leaderboards on any arbitrary number of
   days. So a weekly leaderboard would just be a leaderboard that repeats every 7

features/leaderboards.mdx

@@ -185,11 +185,18 @@ Custom user attributes can be used to personalize achievements, customize the wa
   </Card>
   <Card
     title="Email Personalization"
-    icon="trophy"
+    icon="braces"
     href="/features/emails#email-variables"
   >
     Personalize email copy and subject lines with custom user attributes.
   </Card>
+  <Card
+    title="Leaderboard Eligibility"
+    icon="users"
+    href="/features/leaderboards#eligibility"
+  >
+    Limit leaderboards to specific groups of users.
+  </Card>
 </CardGroup>
 
 #### Data Aggregation and Filtering {#data-aggregation-and-filtering}