> ## 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.

# v2.458.1

<ReleaseBadges date="2026-07-23" size="massive" complexity={3} majorFeatures={["AI Community Reports", "Member-Key Authentication", "Widget Auto-Configuration"]} />

## What's New

Nudj v2.458.1 ships **AI-powered community analytics**, **member-key-based auto-login** for enterprise integrations (Konzum), and **precision admin form improvements** that reduce friction across challenge setup, reward configuration, and leaderboard management.

This release focuses on **admin efficiency** (fewer form steps, clearer error guidance) and **enterprise authentication** (zero-friction login for loyalty programs with existing member databases). The AI reports feature unlocks **data-driven community insights** — administrators can now generate detailed, AI-analyzed snapshots of community performance, member engagement, and challenge participation trends in a single click.

### Key Capabilities

**Admins can now:**

* 📊 **Generate AI-powered community reports** analyzing engagement patterns, member activity, challenge performance, and recommending next actions
* 🔐 **Enable zero-friction member login** for programs integrated with member databases (Konzum cards, corporate IDs) via member-key authentication
* ⚙️ **Auto-configure widget sections** based on saved community settings (section preferences now persist and apply to the widget instantly)
* 🎯 **Pinpoint error resolution** — reward redemption date validation errors now direct you to the exact form step (Dates) rather than a generic toast
* 📈 **Preserve leaderboard history** — expired rankings now remain visible in the admin dashboard for performance analysis
* 🛡️ **Export participant data safely** — CSV exports now work for all participant roles and levels

***

## Feature Breakdown

### 1. AI Community Reports (NEW)

**What it does:** Administrators can generate AI-analyzed snapshots of community engagement, automatically surfaced in an admin dashboard. Reports include:

* Community engagement overview (members, challenges, participation rates)
* Member activity trends and segmentation
* Challenge performance analysis
* Personalized improvement recommendations
* Export-ready report snapshots

**How admins use it:**

1. Navigate to **Admin > Reports** (new tab)
2. Click **Generate New Report**
3. Select the community and reporting period
4. AI generates a detailed report within seconds
5. View, share, or export the full analysis

**Customer benefit:** Data-driven decision-making at scale. Instead of manually auditing spreadsheets, admins get actionable insights on member engagement, which challenges resonate, and where to focus next.

**Implementation:**

* New `CommunityReportDtoModel` and `CommunityReportQueuePayloadDtoModel` in packages/models
* Full tRPC router: `trpc/routers/admin/community-reports/`
* Queue-based generation via QStash with AI prompt synthesis
* Admin UI with report list, viewer, delete, and status tracking

***

### 2. MultiPlusCard Member-Key Authentication (NEW)

**What it does:** Enterprise customers with existing member databases (Konzum, corporate loyalty cards) can now enable **member-key-based login** — users log in with a card or member ID instead of email/password.

**How it works:**

1. Admin enables the feature in **Settings > Organisation Features**
2. Users visit the loyalty program and see a **member-key login** option
3. User enters their card/member ID
4. System validates the key and auto-creates/logs in the user
5. Zero friction — existing cardholders don't need to sign up

**Customer benefit:** Removes signup friction for loyalty programs linked to physical or digital member databases. Konzum cardholders go from "sign up to play" to "enter your card ID to play" in one tap.

**Security note:** Member keys are validated via `/api/member-key/validate` (authenticated, rate-limited, logs all attempts).

**Implementation:**

* New `member-key-auth-middleware.ts` in the user app
* Validation route at `apps/api/app/api/member-key/validate`
* Feature flag: `MEMBER_KEY_AUTHENTICATION` in `FeatureKeyEnum`
* Added to high-risk paths registry (auth expansion)

***

### 3. Widget Section Auto-Configuration

**What it does:** When admins configure widget sections (hero card, leaderboard, challenge list, etc.), those settings now **automatically apply to the live widget**. Previously, admins had to manually refresh or re-sync.

**Customer benefit:** Faster iteration on widget UX. Admins tweak section layouts, colors, or content in the admin panel and see the changes live in the embedded widget instantly.

**Technical:** The user app now honors `widgetPanel.sectionConfig` from the community profile instead of ignoring it.

***

## Fixes & Improvements

### Admin Form Polish

| Issue                                             | Fix                                                                                              |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Reward redeem-by-date errors vague**            | Errors now highlight the **Dates** step in the form sidebar and clear duplicate toasts (NJ-1721) |
| **Reward step sidebar mismatched actual steps**   | Sidebar now accurately reflects the create/edit form's true step order (NJ-1734)                 |
| **Reward create form silently navigates to shop** | Form now stays on the page instead of jumping to `/admin/shop` on accidental click (NJ-1724)     |
| **Fulfilment details header outside card**        | UI now contains the header inside its card border for visual consistency (NJ-1723)               |

### Data Export & Leaderboard

| Issue                                         | Fix                                                                                                                       |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **CSV exports blocked for some participants** | Participant CSV exports now work for all roles and permission levels (WS-576)                                             |
| **Expired leaderboard rankings vanish**       | Expired rankings now stay visible in the admin dashboard, enabling performance review and historical comparison (NJ-1675) |

### Technical Reliability

| Issue                                            | Fix                                                                                                                   |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **Cache tags inconsistent, invalidation misses** | Unified cache tag derivation across all mutations — registration and invalidation now use the same tag list (NJ-1685) |
| **MCP chat and tool validation loose**           | Combined hardening: stricter chat prompt validation + tighter MCP tool input schemas (NJ-1655)                        |
| **Shopify plan confirmation missing**            | User is now prompted to confirm plan details when returning from a pricing flow (NJ-1741)                             |
| **Shopify Blob upload untested in deploy**       | Added smoke-test coverage for Vercel Blob uploads in the Shopify integration (NJ-1717)                                |

***

## Per-App Changes

<PerAppSummary>
  ### Admin App

  **Primary changes:** New AI Reports feature (list page, report viewer, generation form), reward form improvements, leaderboard data retention, widget section sync.

  * 21 new files: Reports infrastructure (components, tests, dialogs)
  * Enhanced reward step sidebar tracking
  * Improved error guidance for date validation
  * Command menu updated with Reports navigation

  ### API

  **Primary changes:** AI report generation (backend slice, tRPC router, queue handler), member-key validation, cache tag consolidation, participant CSV exports, leaderboard history.

  * 18 new files: Community reports service, models, tests, queue payloads
  * 4 new tRPC endpoints: generate, get, list, delete community reports
  * New member-key validation route
  * Unified cache tag registry
  * Leaderboard query now includes expired rankings

  ### User App

  **Primary changes:** Member-key authentication middleware, widget section config honor, form navigation fixes.

  * New middleware: `member-key-auth-middleware.ts`
  * Widget now syncs section configuration from community profile
  * Layout navigation fixed for reward creation

  ### MCP Server

  **Primary changes:** Chat and tool validation hardening.

  * Stricter chat message validation
  * Tighter tool input schema checking

  ### Database

  **Primary changes:** New community reports collection, cache tag mappings.

  * Migration: `20260710120000-add-community-reports-collection`
  * Community reports schema with timestamps, status, snapshot data

  ### Models & Packages

  **Primary changes:** DTOs for community reports, queue payloads, feature flags, service layer.

  * New DTOs: `CommunityReportDtoModel`, `CommunityReportSnapshotDtoModel`, `CommunityReportQueuePayloadDtoModel`
  * New enum: `CommunityReportStatusEnum`
  * New service: `CommunityReportService`
  * Feature flag: `MEMBER_KEY_AUTHENTICATION`
</PerAppSummary>

***

## Breaking Changes

None. All changes are backward-compatible.

***

## Technical Highlights

### AI Report Generation Pipeline

Reports are generated asynchronously via QStash to handle AI inference latency:

1. Admin requests report generation (synchronous tRPC call)
2. Report created with `status: "pending"`
3. QStash enqueues report generation job
4. Handler runs AI analysis on community snapshot
5. Report updated with `status: "completed"` + HTML output
6. Admin receives notification and can view/export

**Models affected:** `CommunityReportDtoModel`, `CommunityReportStatusEnum`, `CommunityReportQueuePayloadDtoModel`

**Services affected:** `CommunityReportService` with queue integration

### Cache Tag Consolidation

Cache invalidation previously derived tags differently across mutations, causing stale data in some flows. v2.458.1 **unifies tag derivation** from a single authoritative `CacheTag` registry. Every mutation now uses the same tag list for both registration and invalidation.

**Before:**

```typescript theme={null}
// Mutation derives tags one way
const tags = [entity.id, entity.communityId];
// Registration uses tags
await revalidateTags(tags);
// But query registration used different tags
CacheTag.Achievement.Multiple.Keyed([["communityId", id]]);
```

**After:**

```typescript theme={null}
// Single authoritative list
const tags = [
  CacheTag.Achievement.Single.ID(result.id),
  CacheTag.Achievement.Multiple.Keyed([["organisationId", result.organisationId]]),
  CacheTag.Achievement.Multiple.Keyed([["communityId", result.communityId]]),
];
await revalidateTags(tags);
```

**Impact:** No more stale caches after mutations. Full consistency across all entity types.

### Member-Key Authentication

New authentication route added to high-risk RBAC registry (`scripts/rules/check-high-risk.sh`). Member-key validation is rate-limited and logged for audit trails.

***

## Migration Guide

### For Admins

**New Features:**

* Reports are available immediately in **Admin > Reports** tab (feature flag: `COMMUNITY_REPORTS_ENABLED`)
* Member-key login must be explicitly enabled in **Settings > Organisation Features > Member Key Authentication**

**Leaderboard Data:**

* Expired rankings are now retained and visible. No action needed — historical data is automatically available.

**CSV Exports:**

* Participant CSV exports now work for all user roles. If you previously received permission errors, try again.

### For Developers

**New Endpoints:**

* `POST /api/v2/admin/community-reports/generate` — start report generation
* `GET /api/v2/admin/community-reports/{id}` — fetch report details
* `GET /api/v2/admin/community-reports` — list community reports (paginated)
* `DELETE /api/v2/admin/community-reports/{id}` — delete a report

**New Queue Job:**

* `QueueNameEnum.CommunityReportGeneration` — handle async report generation

**New Models:**

* `CommunityReportDtoModel` — report definition
* `CommunityReportStatusEnum` — `"pending"` | `"completed"` | `"failed"`
* `CommunityReportQueuePayloadDtoModel` — async job payload

***

## Contributors

<div className="grid grid-cols-1 md:grid-cols-2 gap-4 mt-6">
  <ContributorCard username="dch@wenudj.com" commits={7} filesChanged={51} linesAdded={1665} linesRemoved={807} />

  <ContributorCard username="solicshop@gmail.com" commits={5} filesChanged={53} linesAdded={1721} linesRemoved={895} />

  <ContributorCard username="erek_d@me.com" commits={3} filesChanged={218} linesAdded={22590} linesRemoved={1852} />

  <ContributorCard username="zuhayrk00@gmail.com" commits={2} filesChanged={79} linesAdded={8684} linesRemoved={96} />

  <ContributorCard username="jamescockayne" commits={1} filesChanged={14} linesAdded={615} linesRemoved={3} />
</div>

***

## Release Metrics

| Metric            | Value   |
| ----------------- | ------- |
| **Total Commits** | 19      |
| **Files Changed** | 407     |
| **Lines Added**   | 35,420  |
| **Lines Removed** | 3,647   |
| **Release Size**  | Massive |
| **Complexity**    | 3/5     |

***

## Next Steps

* **Early access:** The AI Reports feature is available now. Enable via `COMMUNITY_REPORTS_ENABLED` flag in Platform Config.
* **Member-key rollout:** Konzum integrations should enable Member Key Authentication in org settings to start testing.
* **Leaderboard analysis:** Review historical rankings now visible in the Leaderboard admin page.

***

## Support

For issues or questions about the new AI Reports feature or member-key authentication:

* Check the [Admin Guide](https://docs.nudj.cx/admin) for detailed instructions
* Review [API Documentation](https://api.nudj.cx/docs) for technical details
* Contact your Nudj support engineer

**Known Limitations:**

* AI report generation time varies based on community size (typical: 5–30 seconds)
* Member-key format is organization-specific and must be validated server-side
* Reports are stored for 90 days before auto-deletion

***

## Acknowledgments

This release involved contributions from our infrastructure, API, admin, and user app teams. Special thanks to the QA team for comprehensive testing of the new report generation pipeline and member-key validation flows.