feat(gamification): Phase 1 — full kill-switch + textbook XP wrapping

Until now the 'gamification' feature flag did nothing: it had no row in
app_settings, the admin couldn't toggle it, awardXP/awardCoins ignored
it, and the CSS only hid three dashboard widgets — XP bars in textbooks
stayed visible regardless.

Phase 1 closes every hole.

Backend (source of truth):
  • migration 029 seeds feature_gamification_enabled=1
  • new isGamificationEnabled() helper in gamification/_shared.js with a
    30s cache + invalidateGamificationCache() for instant admin toggles
  • awardXP / awardCoins / updateStreak / unlockAchievement /
    checkAchievements all bail out when the flag is off
  • /api/gamification/* and /api/shop/* (user routes) return 404 when
    disabled; admin routes remain open so the switch itself is reachable
  • adminController.updateFeatures gains 'gamification' in the allow-list
    and invalidates the cache on flip

Frontend:
  • LS.isGamificationEnabled() (synchronous, populated by loadFeatures)
    so xp.js + applyCosmetics can bail without a round-trip
  • xp.js load/add/flush become no-ops when the flag is off
  • applyCosmetics skips the round-trip when off
  • CSS .no-gamification rule expanded to cover .hero-xp-badge, .po-xp,
    .xp-card, .xp-bar, #frames-section, and a universal [data-gamified]
    hook for future blocks

Textbooks (Variant 2 of the plan):
  • backend/scripts/wrap_textbook_xp.py — idempotent script that adds
    data-gamified to 167 XP tags across 63 textbook files (chapters +
    hubs, all subjects/grades). Single CSS rule now hides everything.

Verified end-to-end: with the flag off, awardXP/awardCoins write nothing;
flipping back restores normal behavior.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/src/controllers/gamification/service.js

@@ -4,7 +4,7 @@ const sse = require('../../sse');
 const { pushParentNotif } = require('../../utils/notifications');
 const {
   stmts, xpToLevel, levelMinXp, levelMaxXp, rankName,
-  GOAL_TIERS, ACHIEVEMENT_DEFS,
+  GOAL_TIERS, ACHIEVEMENT_DEFS, isGamificationEnabled,
 } = require('./_shared');
 
 /* ═══════════════════════════════════════════════════════════════════════
@@ -16,12 +16,14 @@ const {
 /* ── Coins ─────────────────────────────────────────────────────────── */
 function awardCoins(userId, amount /*, reason */) {
   if (!amount || amount <= 0) return;
+  if (!isGamificationEnabled()) return;       // master kill-switch
   stmts.incrCoins.run(amount, userId);
 }
 
 /* ── XP ────────────────────────────────────────────────────────────── */
 function awardXP(userId, amount, reason) {
   if (!amount || amount <= 0) return;
+  if (!isGamificationEnabled()) return;       // master kill-switch
   stmts.insertXpLog.run(userId, amount, reason);
   stmts.incrXP.run(amount, userId);
   const user = stmts.getXP.get(userId);
@@ -52,6 +54,7 @@ function getXPInfo(userId) {
 
 /* ── Streak (called by onTestFinished) ─────────────────────────────── */
 function updateStreak(userId) {
+  if (!isGamificationEnabled()) return;
   const user = stmts.getStreak.get(userId);
   if (!user) return;
   const today = new Date().toISOString().slice(0, 10);
@@ -103,6 +106,7 @@ function pushAchievementNotif(userId, ach) {
 }
 
 function unlockAchievement(userId, slug) {
+  if (!isGamificationEnabled()) return false;
   const ach = stmts.getAchBySlug.get(slug);
   if (!ach) return false;
   const exists = stmts.hasUserAch.get(userId, ach.id);
@@ -114,6 +118,7 @@ function unlockAchievement(userId, slug) {
 }
 
 function checkAchievements(userId) {
+  if (!isGamificationEnabled()) return;
   const row = stmts.getUserForAch.get(userId);
   if (!row) return;
   const { test_count: testCount, perfect_count: perfectCount, class_count: classCount } = row;