#Points & Rewards System
Unify the scoring, grading, progression, and rewards layers into a cohesive points & rewards experience. Builds on the existing Points & Grading System (migration 0174) and Pac-Man Progression (migration 0175) foundations.
#Existing Foundations
| Layer | Status | Key Tables |
|---|
| Points & Grading | Shipped | card_interactions.points_earned, card_interactions.difficulty_level, user_quality_grades |
| Pac-Man Progression | Phase 1-4 done, migration pending | progression_tiers, tier_rewards, user_progression, user_topic_progression |
| Legacy Milestones | Deprecated (pending removal) | reward_milestones, user_reward_claims |
#Key Deliverables
#Stripe Credit Application
- Apply subscription credit when
subscription_credit_accumulated >= 1.0
- Invoice item credit via Stripe API
- Credit meter reset after application
#Prestige Reset Flow
- Full Cherry reset with crowned icons
- 1.5x point scaling for prestige players
- Credit meter reset
- Prestige counter tracking
#Legacy Migration
- Deprecate
reward_milestones and user_reward_claims tables
- Remove old milestone UI (
RewardsProgress component)
- Deprecate
/api/user/rewards route
- Migrate any remaining milestone data to Pac-Man progression
#Feed & UI Integration
- GlobalTierIndicator in feed/card routes (currently only in authenticated layout)
- TopicFruitLabel next to topic labels in feed
- RewardUnlockBanner celebratory tier advancement overlay
- SubscriptionCreditMeter (0% -> 100% free month meter)
#Profile & Cosmetics
- TopicTierGrid on profile page (per-topic fruit icons)
- PrestigeKeyCollection trophy case on profile page
- Custom SVG fruit icons (12 base + 12 crowned) replacing emoji placeholders
- Move FruitBadge to
packages/ui (consolidate duplicated emoji maps)
#Blockers
- Migration 0175 (Pac-Man progression) must be applied to production first
- Bulk recalculation worker handler not yet implemented
#Reference Docs
| Document | Path |
|---|
| Points & Grading Session | docs/done/2026-mar/2026-03-24T16-15--feat-v2-fact-engine--points-grading-system.md |
| Pac-Man Design Spec | docs/superpowers/specs/2026-03-26-pacman-progression-design.md |
| Admin Dashboard Spec | docs/superpowers/specs/2026-03-27-admin-progression-dashboard-design.md |
| Pac-Man TODO | docs/projects/pacman-progression/TODO.md |