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

# Release v2.500.8

> Released August 25, 2026

## 🔴 Release v2.500.8

⭐⭐⭐ Moderate Complexity • 48 commits • 438 files changed

<Note>
  **Massive release with seven new features, platform-wide improvements, and critical fixes.** Users can now preview locked achievements and see winnable rewards, admins have new leaderboard ranking options and UI controls, and we've added Dutch language support with a complete vertical video system for social media marketing.
</Note>

## What's New

* **Preview locked achievements** – Users see what they need to do to earn achievements they haven't completed yet
* **Winnable rewards in widget** – Show users the rewards they're eligible to win directly in the benefits view
* **Referral leaderboard ranking** – Create leaderboards that rank users by referral count instead of just points or XP
* **Dutch language support** – Loyalty widget now fully translated and responsive to Dutch locale
* **Control reward volume display** – Toggle whether to show the "reward volume remaining" label in the theme settings
* **Provisional results notice** – Users see clear messaging when leaderboard results are pending final distribution
* **Vertical video system** – Complete design system and template library for creating consistent social media videos across all channels

## Apps Updated

<CardGroup cols={3}>
  <Card title="User App" icon="mobile">
    ✓ Updated – 9 major features, 7 fixes
  </Card>

  <Card title="API" icon="server">
    ✓ Updated – Leaderboard metrics, data structures
  </Card>

  <Card title="Admin" icon="gear">
    ✓ Updated – New UI controls, leaderboard options
  </Card>

  <Card title="MCP Server" icon="robot">
    ✓ Updated – Tool schema changes
  </Card>

  <Card title="Design System" icon="palette">
    ✓ Updated – Dutch translations, new hook utilities
  </Card>

  <Card title="Games" icon="gamepad">
    ✓ Updated – Game integration improvements
  </Card>
</CardGroup>

## Admin Highlights

* **Referral leaderboard metric** – New option in leaderboard creation to rank communities by total referrals instead of points or XP
* **Hide reward volume remaining label** – Toggle in theme settings to control whether the "X rewards left" label displays on reward cards across the platform
* **Provisional results notice** – Manual leaderboards now show a clear notice when results haven't been distributed yet, reducing support questions
* **Leaderboard performance** – Fixed queries to stop loading expired completion leaderboards, improving dashboard load times
* **Community theme schema expansion** – Enhanced theme configuration to support new display options

## User Highlights

* **Preview locked achievements** – See the full details of achievements you haven't earned yet, including requirements and rewards, in a dedicated modal
* **Winnable rewards browsing** – The benefits view now highlights which rewards you're actively eligible to win right now
* **Better mobile consent flow** – Improved cookie consent actions on mobile devices for smoother user experience
* **Correct sessionless widget** – Fixed widget behavior for anonymous users, properly handling consent states
* **Images in quick actions** – Drawers for quick actions now render images properly instead of showing broken placeholders

## Shopify Highlights

* **Dutch language support in widget** – Loyalty widget respects Shopify store locale and renders completely in Dutch when applicable
* **Widget OAuth session recovery** – Fixed critical issue where OAuth sign-in sessions weren't properly handed off to the widget iframe, ensuring smooth authentication flows
* **Navigation scope fix** – Community-scoped navigation properly maintained when intercepting user navigation

## Detailed Changes

<AccordionGroup>
  <Accordion title="User App – Achievements & Rewards" icon="mobile">
    * Preview locked achievements with full details before earning them
    * Show winnable rewards in the widget benefits view with eligibility status
    * Render images correctly in quick-action drawers
    * Improved mobile cookie consent flow
    * Fix sessionless widget states for anonymous users
  </Accordion>

  <Accordion title="User App – Internationalization" icon="globe">
    * Full Dutch (nl) translation of loyalty widget with 4,400+ translated keys
    * Language detection from community theme configuration
    * Locale merge for multi-language support
    * Updated all other languages (en, de, es, fr, pt, zh) with new strings
  </Accordion>

  <Accordion title="User App – OAuth & Security" icon="lock">
    * Hand off OAuth session to widget iframe for seamless authentication
    * Stop anonymous users from creating referral codes
    * Keep intercepted navigation community-scoped
    * Recover widget token after OAuth callback
  </Accordion>

  <Accordion title="Admin App – Leaderboards & Themes" icon="gear">
    * Add referral count as a new leaderboard metric option
    * New theme toggle to hide/show reward volume remaining label
    * Provisional results notice for manual leaderboard periods
    * Branding layout section with component preview
    * Enhanced community theme schema for new display options
  </Accordion>

  <Accordion title="API – Data & Performance" icon="server">
    * Add referral leaderboard metric to leaderboard service
    * Update leaderboard schema and types for new metric
    * Fix leaderboard queries to skip expired completion periods
    * Provisional results flag for undistributed manual leaderboards
    * Enhanced OpenAPI documentation
  </Accordion>

  <Accordion title="MCP Server – Tools & Schemas" icon="robot">
    * Update leaderboard tool schemas for referral metric
    * Add referral leaderboard mapping in tools
    * Enhanced MCP replay corpus for new feature coverage
  </Accordion>

  <Accordion title="Design System & Brand" icon="palette">
    * Add hook for hide-reward-volume-remaining feature flag
    * Complete Dutch locale file with 4,400+ translations
    * New vertical video system: 8 design templates (kinetic-statement, object-opener, question-card, reward-moment, stat-count, streak-week, the-turn, tier-climb)
    * Video templates with master render system for 4 social channels
    * Remotion-based video generation tool in `tools/brand-video/`
    * Brand social playbook updated with vertical video examples
  </Accordion>
</AccordionGroup>

## Breaking Changes

None.

## Technical Notes

* **Leaderboard metric expansion**: `ReferralLeaderboardMetricType` added to metric union. Existing leaderboards unaffected; new ones can opt into referral ranking.
* **Theme schema evolution**: `hideRewardVolumeRemaining` boolean added to both org and community theme schemas with sensible defaults (false = show label by default).
* Security and access-control hardening.
* **Dutch locale**: 4,400+ keys across all user-facing surfaces. Widget locale detection respects community theme language preference.
* **Video generation**: `tools/brand-video/` is a Remotion-based CLI tool for rendering templates; not part of the deployed platform. Brand team references: 8 MP4/PNG pairs in `docs/brand/social/examples/vertical-video/`.

## Usage Examples

### Referral Leaderboard (Admin)

1. Create a new leaderboard in **Admin → Leaderboards**
2. Under "Metric," select **Referral Count** (new option)
3. The leaderboard now ranks communities by total referrals instead of points
4. Users see where their referred members rank in the community

### Preview Locked Achievement (User Widget)

1. User opens the widget and navigates to **Achievements**
2. Locked (uncompleted) achievements show a "Preview" button
3. Click to see the full achievement card with requirements and unlock conditions
4. Users can plan their next challenge based on what they see

### Hide Reward Volume Label (Admin)

1. Go to **Admin → Community Settings → Branding & Appearance**
2. Under **Layout**, toggle **"Show reward volume remaining"**
3. When OFF: reward cards no longer display "X rewards left" text
4. Applies immediately across widget, earned rewards, and dashboard

## Release Stats

| Metric            | Value                                 |
| ----------------- | ------------------------------------- |
| Total Commits     | 48                                    |
| Lines Added       | +44,320                               |
| Lines Removed     | -3,895                                |
| Files Changed     | 438                                   |
| Apps Modified     | 5 (User, Admin, API, MCP, Games)      |
| Packages Modified | 3 (API Client, Design System, Models) |

## Contributors

<CardGroup cols={4}>
  <Card>
    <img src="https://github.com/dch@wenudj.com.png" alt="dch" style={{borderRadius: '50%', width: 48}} />

    **@dch**

    19 commits • +5,509 lines
  </Card>

  <Card>
    <img src="https://github.com/erek_d@me.com.png" alt="erek_d" style={{borderRadius: '50%', width: 48}} />

    **@erek\_d**

    18 commits • +38,146 lines
  </Card>

  <Card>
    <img src="https://github.com/zuhayrk00@gmail.com.png" alt="zuhayrk00" style={{borderRadius: '50%', width: 48}} />

    **@zuhayrk00**

    4 commits • +2,004 lines
  </Card>

  <Card>
    <img src="https://github.com/hienhang@hotmail.co.uk.png" alt="HienH" style={{borderRadius: '50%', width: 48}} />

    **@HienH**

    3 commits • +2,318 lines
  </Card>

  <Card>
    <img src="https://github.com/jamescockayne.png" alt="jamescockayne" style={{borderRadius: '50%', width: 48}} />

    **@jamescockayne**

    2 commits • +200 lines
  </Card>

  <Card>
    <img src="https://github.com/solicshop@gmail.com.png" alt="solicshop" style={{borderRadius: '50%', width: 48}} />

    **@solicshop**

    1 commit • +4,152 lines
  </Card>
</CardGroup>

***

*v2.500.8 deployed on August 25, 2026*