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>

js/api.js

@@ -806,14 +806,24 @@ function initPage({ requireLogin = true } = {}) {
 
 /* ── Feature flags (cached per page load, bust on demand) ───────────── */
 let _featuresCache = null;
+/* Synchronous mirror of features.gamification, populated on first
+   loadFeatures() resolve. Used by xp.js to bail out without network. */
+let _gamificationEnabled = null;
+function isGamificationEnabled() {
+  // Default to true when the cache hasn't resolved yet — page-load order
+  // means some code runs before /api/features. The CSS kill-switch
+  // (body.no-gamification) catches the visual side regardless.
+  return _gamificationEnabled !== false;
+}
 async function loadFeatures() {
   if (_featuresCache) return _featuresCache;
   try {
     _featuresCache = await apiFetch('/api/features');
   } catch { _featuresCache = {}; }
+  _gamificationEnabled = _featuresCache.gamification !== false;
   return _featuresCache;
 }
-function clearFeaturesCache() { _featuresCache = null; }
+function clearFeaturesCache() { _featuresCache = null; _gamificationEnabled = null; }
 
 /**
  * Show board sidebar link only for teachers/admins and students in a class.
@@ -1045,6 +1055,7 @@ window.LS = {
   patch: (path, body) => apiFetch(path, { method: 'PATCH', body: JSON.stringify(body) }),
   applyCosmetics: applyCosmetics,
   refreshNavAvatar,
+  isGamificationEnabled,
   loadFeatures,
   clearFeaturesCache,
   hideDisabledFeatures,
@@ -1060,6 +1071,9 @@ window.LS = {
    ═══════════════════════════════════════════════════════════════════════ */
 async function applyCosmetics() {
   if (!isLoggedIn()) return;
+  // Skip the round-trip entirely when gamification is off. Server will
+  // 404 anyway, but a synchronous bail-out keeps the network quiet.
+  if (!isGamificationEnabled()) return;
   try {
     const c = await getMyActiveCosmetics();
     if (!c) return;