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/adminController.js

@@ -509,10 +509,12 @@ function getFeatures(_req, res) {
 /* ── PATCH /api/admin/features ──────────────────────────────────────── */
 function updateFeatures(req, res) {
   const allowed = ['crossword', 'hangman', 'pet', 'red_book', 'collection',
-                   'flashcards', 'knowledge_map', 'board', 'biochem', 'live_quiz', 'classroom'];
+                   'flashcards', 'knowledge_map', 'board', 'biochem', 'live_quiz', 'classroom',
+                   'gamification'];
   const updates = req.body;
   const stmt = db.prepare("INSERT OR REPLACE INTO app_settings (key, value) VALUES (?, ?)");
   const getOld = db.prepare("SELECT value FROM app_settings WHERE key = ?");
+  let touchedGamification = false;
   for (const [name, enabled] of Object.entries(updates)) {
     if (!allowed.includes(name)) continue;
     const settingKey = `feature_${name}_enabled`;
@@ -521,6 +523,15 @@ function updateFeatures(req, res) {
     const newVal = enabled ? '1' : '0';
     stmt.run(settingKey, newVal);
     audit(req, 'feature.update', `feature:${name}`, `${oldVal} -> ${newVal}`);
+    if (name === 'gamification') touchedGamification = true;
+  }
+  // Invalidate the gamification cache so the kill-switch takes effect
+  // immediately (otherwise awardXP keeps running for up to 30s).
+  if (touchedGamification) {
+    try {
+      const { invalidateGamificationCache } = require('./gamification/_shared');
+      invalidateGamificationCache();
+    } catch { /* defensive — shouldn't fail */ }
   }
   res.json({ ok: true });
 }