> ## 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.407.27
> Released July 1, 2026
## 🔴 v2.407.27
⭐⭐ Moderate • 14 commits • 113 files
This release delivers powerful admin bulk actions for reward management, critical stability improvements to the AI community-setup onboarding workflow, and a collection of quality-of-life fixes across the platform. The bulk reward status feature saves admins time when managing large reward catalogs, while the onboarding improvements ensure the AI setup wizard never stalls mid-process, even when individual steps encounter recoverable errors.
## What's New
* **Bulk reward status management** – Instantly archive, enable, or disable multiple rewards at once instead of updating them individually
* **AI onboarding reliability** – Community-setup wizard now gracefully recovers from tool failures and continues automatically without human intervention
* **Leaderboard status awareness** – Archived and draft leaderboards can now be archived without triggering validation errors
* **Enhanced widget polish** – Improved visual hierarchy for inline games, cleaner date selector spacing, and safer reward descriptions in the widget
* **Template naming clarity** – Renamed duplicate "Reward Redeemer" achievement template to "First Redemption" to avoid confusion
## Apps Updated
✓ Updated - Game layer stacking, HTML stripping, sold-out reward handling
✓ Updated - Onboarding recovery, timed action expiry, write-conflict retries
✓ Updated - Bulk actions, leaderboard fixes, template naming, UI polish
✓ Updated - Tool failure tracking, comprehensive test coverage
✓ Updated - Action component improvements
— No changes
## Detailed Changes
### Bulk Reward Status Management (NJ-1333)
**Instantly manage multiple rewards without individual edits** – Admins can now select multiple rewards from the rewards list and bulk-update their status (Active, Archived, or Disabled) in a single operation. A contextual action bar appears above the table showing the number of selected rewards and offering immediate status change options.
**Implementation highlights:**
* Multi-select checkboxes on each reward row
* Floating action bar with bulk status options
* Optimistic UI updates with proper error handling and rollback
* Status-aware validation preserves data integrity
**Changes:**
* Added `BulkActionBar` component for consistent bulk UI patterns
* Created `useBulkRowActions` hook for reusable bulk selection logic
* Extended `rewards-data-table.tsx` with selection column and bulk action routing
* Added test coverage for multi-select workflows
### Leaderboard Status Awareness (NJ-1364)
**Archived and draft leaderboards can now be archived** – The leaderboard save form now correctly validates status transitions, allowing admins to archive a leaderboard that is already in archived or draft state. Previously, the status field validation would fail when attempting to archive an already-archived board.
**Changes:**
* Fixed `leaderboard-schema.ts` status validation logic
* Updated `use-leaderboard-form.ts` to handle status-aware transitions
* Added test coverage for edge case status changes
### Achievement Template Naming (NJ-1362)
**Removed template naming confusion** – The duplicate "Reward Redeemer" achievement template has been renamed to "First Redemption" to better reflect the achievement's purpose (completing a first redemption) and eliminate naming confusion in the template catalog.
**Changes:**
* Updated template registry with new name
* No schema or functional changes
### UI Refinements
* **Duplicate button removal (NJ-1358)**: Removed the second "Disconnect Store" button that appeared in Shopify General settings
* **Date selector spacing (NJ-1371)**: Improved visual spacing between Start/Expiration date selectors in the Access & Scheduling section
* **Brand memory improvements (NJ-1324)**: Refactored tool-step display to reuse shared Task collapsible components, reducing code duplication and improving consistency
### AI Community-Setup Onboarding Recovery (NJ-1324)
**Onboarding wizard never hard-stops — automatic recovery from tool failures** – The AI-driven community-setup wizard now gracefully handles individual step failures and automatically advances through remaining setup steps. If an onboarding step encounters a recoverable error (like an MCP tool timeout or model-generation failure), the system:
1. **Auto-retries up to 2 times** via the existing `useChatAutoRetry` hook
2. **Auto-skips** the failing step after retries are exhausted (marked with a review warning for the admin)
3. **Resumes the queue** so remaining setup steps complete without manual intervention
This ensures a setup wizard with 5 steps never gets blocked on step 2 waiting for a "Try Again" button — the wizard continues and the admin can review/fix the skipped steps afterward.
**Root-cause fixes:**
* **Tool failure tracking (new)**: Introduced `tool-failure-tracking.ts` with structured error classification and recovery state management
* **Stall detection**: Comprehensive detection for three types of stalls:
* Active tool work in flight (MCP tools, image generation)
* Setup-wizard image tool stalls (90s ceiling with fail-soft recovery)
* Overall chat-stream progress stalls (120s no-message ceiling)
* **Write-conflict retry layer (new)**: Added `retryOnWriteConflict.ts` utility for transient database conflicts during action/reward updates
* **Onboarding recovery state**: Tracks error count and auto-skips on threshold (initial attempt + 2 auto-retries = 3 total)
**Implementation:**
* `/api/chat/_lib/tool-failure-tracking.ts` – Extracts and classifies tool failures from MCP + image tool responses
* `/lib/mutation/retry-on-write-conflict.ts` – Retries mutations on detected write conflicts (e.g., duplicate key, concurrent updates)
* `use-chat-queue-runner.ts` – Enhanced with three configurable stall timeouts (configurable for testing)
* `chat.tsx` – Integrated `useChatAutoRetry` hook for automatic regeneration on stream errors
* Comprehensive test coverage: 21 new test files covering stall detection, recovery, approval flows, and edge cases
**Changes:**
* Added `AUTO_SKIP_SETUP_ERROR_THRESHOLD = 3` constant (initial + 2 retries)
* Added three stall timeout constants with defaults (100s image, 120s progress, 300s active tool work)
* Enhanced `onboarding-guide-types.ts` with recovery metadata
* Updated tRPC `update-onboarding-guide-task.ts` handler with recovery state transitions
### Timed Action Expiry (NJ-1373)
**Actions with expiry now hard-expire and prevent completion** – Timed actions (those with an `expiresAt` field) are now properly enforced at the API level. The system validates action expiry on completion, preventing users from completing actions that have passed their expiration time, even if they were cached or queued client-side.
**Changes:**
* Added expiry check in action-completion handler
* Updated action schema validation to include expiry status
* Added comprehensive test coverage for expired action edge cases
### Analytics Export Hardening (NJ-1374)
**Tightened export RBAC, coverage gates, and data escaping** – Multiple security and governance improvements to the analytics export system:
* **Enforced challenge read permission**: Users must have `read` permission on a challenge before exporting it
* **Scoped export checks**: Verification that exported data belongs to the requesting organization only
* **Included shared challenges**: Exports now properly include challenges shared across communities
* **CSV escaping**: Proper escaping of special characters in CSV output to prevent formula injection
* **Coverage ratchet**: Analytics coverage tracking is now mergeable and doesn't cause accidental CI failures
**Changes:**
* Added RBAC checks in export handler
* Updated export governance framework
* Enhanced CSV generation with safety escaping
* Improved coverage tracking logic
### Game Layer Stacking (NJ-1369)
**Inline games now stay above wizard overlays** – Fixed a z-index issue where inline games displayed underneath the AI community-setup wizard overlay, making them impossible to interact with. Games now render at the correct stacking level.
**Changes:**
* Updated `platform-play-game-action.tsx` z-index handling
* Added test coverage for game overlay interaction
### Reward Description Safety (NJ-1368)
**Widget no longer displays HTML in reward descriptions** – The widget's Spend Benefits and Spend list now strips HTML tags from reward descriptions, ensuring clean text display and preventing any unintended markup from appearing in the user interface.
**Changes:**
* Added HTML stripping to reward description rendering
* Updated `reward-description` component to sanitize input
### Sold-Out Reward Handling (NJ-1352)
**Sold-out rewards now properly disabled in the widget** – Rewards that have reached their allocation limit are now correctly disabled in the user-facing widget, preventing users from attempting to redeem unavailable rewards.
**Changes:**
* Enhanced sold-out detection logic
* Updated reward item disabled state
### Legacy Route Redirection (NJ-1189)
**Old loyalty-list routes now redirect properly** – Removed legacy route references and implemented proper redirects for outdated loyalty-list navigation patterns, ensuring links from external systems or user bookmarks still work.
**Changes:**
* Added route redirect handlers
* Maintained backward compatibility
### Date Selector Spacing (NJ-1371)
**Improved visual spacing in Access & Scheduling** – Enhanced the layout of Start and Expiration date selectors in the Access & Scheduling settings section, providing better visual separation and clearer labeling.
**Changes:**
* Updated selector layout and spacing
* Added harness test coverage
### Settings UI Cleanup (NJ-1358)
**Removed duplicate Disconnect Store button** – The General settings page was displaying a duplicate "Disconnect Store" button. Only one button now appears.
**Changes:**
* Removed duplicate UI element
### Points Configuration Token Refresh (NJ-1357)
**Points config token refreshes after birthday toggle** – When toggling the birthday bonus feature, the points configuration is now properly refreshed, ensuring the configuration reflects the latest state immediately.
**Changes:**
* Added token refresh on feature toggle
* Enhanced configuration state management
### Comprehensive Tool Testing (NJ-1324)
**Full direct-MCP test coverage with promptfoo** – Added exhaustive test coverage for all MCP tools (17 tools, 20+ test scenarios covering success paths, error handling, edge cases, and validation). All tests pass with the Vercel AI Gateway judge.
**Implementation:**
* Created `__tests__/tools/` test suite with focused specs per tool
* Added schema validation tests for all tool inputs
* Implemented promptfoo coverage runner with exit-code enforcement
* Added test fixtures and utilities for common patterns
**Test coverage includes:**
* Brand memory operations (save, update, community ID validation)
* Challenge creation and validation
* Action image upload disclaimer handling
* Leaderboard reward allocation validation
* Unified tool ID validation across all create/update tools
* Campaign resolution for challenge distribution
* Image endpoint caching behavior
**Changes:**
* Added 15+ new test files under `__tests__/tools/`
* Enhanced tool configuration validation
* Improved schema definitions for type safety
### Action Component Improvements (NJ-1369)
**Enhanced platform-play-game-action rendering** – Improved the game action component's rendering and z-index handling to ensure proper layering within the platform UI.
**Changes:**
* Updated component styling
* Added test coverage for interaction scenarios
## Admin Highlights
* **Bulk Reward Status Updates** – Select multiple rewards and instantly change their status (Active/Archived/Disabled) in one operation, dramatically reducing time spent managing large reward catalogs
* **Leaderboard Status Flexibility** – Archived and draft leaderboards can now be archived without triggering validation errors, improving workflow flexibility
* **Cleaner Template Naming** – Renamed duplicate "Reward Redeemer" achievement template to "First Redemption" for better clarity
* **Enhanced Date Pickers** – Improved visual spacing and layout of date selectors in Shopify Access & Scheduling settings
* **Brand Memory UI Refinement** – Simplified tool-step display using shared Task collapsible components for consistency and reduced code duplication
## User Experience Improvements
* **Reliable Game Interaction** – Inline games now render above wizard overlays and are fully clickable during AI setup
* **Clean Reward Information** – Reward descriptions in the widget display clean text without HTML markup
* **Better Reward Availability** – Sold-out rewards are now properly disabled, preventing redemption attempts
* **Protected Action Completion** – Timed actions that have expired are now prevented from completion, protecting campaign integrity
## Technical Notes
This release prioritizes **wizard reliability and admin efficiency**. The onboarding recovery system represents a significant architectural improvement: instead of blocking on a single failed step, the system now classifies failure types (tool timeout, MCP error, image generation stall) and applies appropriate recovery strategies. The three-tier stall detection (active tool work, image tool operations, overall progress) catches edge cases that would previously hang indefinitely.
The bulk actions infrastructure is now reusable — any admin table needing bulk operations can import `BulkActionBar` and `useBulkRowActions` for consistent UI and behavior.
The analytics export hardening hardens the security boundary around data access, ensuring exports respect RBAC and organizational scoping in all cases.
## Migration Guide
No action required. This is a backward-compatible release:
* **Admins**: New bulk actions are opt-in features that appear automatically when selecting multiple rewards
* **End users**: Widget behavior improvements are transparent (games stay clickable, descriptions are cleaner, sold-out rewards disable)
* **API consumers**: All endpoints maintain existing contracts; new validation (timed action expiry) aligns with documented behavior
* **MCP clients**: Tool behavior is unchanged; improved test coverage ensures consistency
## Related Features
* [Reward Management](/admin-guide/rewards)
* [Leaderboards](/admin-guide/leaderboards)
* [AI Community Setup](/admin-guide/onboarding)
* [Widget Configuration](/admin-guide/brand-kit)
* [Analytics & Reporting](/admin-guide/analytics)
***
## Contributors
**@[erek\_d@me.com](mailto:erek_d@me.com)**
5 commits • +12,689/-324 lines
**@[solicshop@gmail.com](mailto:solicshop@gmail.com)**
4 commits • +1,098/-44 lines
**@[dch@wenudj.com](mailto:dch@wenudj.com)**
2 commits • +382/-29 lines
**@[tomcarroll09@duck.com](mailto:tomcarroll09@duck.com)**
2 commits • +282/-170 lines
## Release Stats
| Metric | Value |
| ------------- | -------- |
| Total Commits | 14 |
| Lines Added | +14,503 |
| Lines Removed | -474 |
| Files Changed | 113 |
| Release Size | Massive |
| Complexity | Moderate |
***
*v2.407.27 deployed on July 1, 2026*