feat: implement AI-driven learning content generation service and interactive leaderboard functionality

AI_AGENT.md

@@ -0,0 +1,58 @@
+# AI Agent Context Guide: Respellion Learning Platform
+
+Welcome, fellow AI agent! If you are reading this, you are tasked with maintaining or extending the Respellion Learning Platform. This document provides the critical context, architectural patterns, and design standards you need to successfully work on this codebase.
+
+## 1. Architectural Overview
+This is a single-page React application built with **Vite**. It is completely self-contained and currently runs without a dedicated backend database.
+*   **Frontend:** React, React Router, Tailwind CSS.
+*   **Animations:** Framer Motion (used extensively for page transitions, podium effects, and gamification feedback).
+*   **Icons:** Lucide React.
+*   **Visualizations:** D3.js (used strictly for the Admin Knowledge Graph).
+
+## 2. State Management & Storage (Critical)
+There is **no backend database**. All data is persisted locally in the browser using a custom wrapper around `window.localStorage` located at `src/lib/storage.js`. 
+
+**Namespacing Convention:**
+You must strictly adhere to these prefixes when reading/writing to `storage.js`:
+*   `kb:*` - Knowledge base data (e.g., `kb:topics`, `kb:relations`, `kb:content:{topicId}`).
+*   `admin:*` - Admin settings (e.g., `admin:anthropic_key`, `admin:sources`, `admin:use_simulation`).
+*   `user:{id}:*` - Specific user progress (e.g., `user:{id}:week:{n}:learn_done`).
+*   `quiz:bank:{topicId}` - Cached banks of AI-generated multiple-choice questions.
+*   `quiz:result:{userId}:week:{n}` - The exact score and payload of a user's weekly test.
+*   `leaderboard:current` - The active points ledger. Array of objects: `{ userId, name, points, testsCompleted, perfectScores }`.
+*   `users:registry` - Array of registered users, including admins.
+
+## 3. The AI Integration (Anthropic)
+The application acts as a proxy to the Anthropic API (`claude-sonnet-4`). 
+*   **Location:** `src/lib/api.js`.
+*   **Proxy:** In Docker, `/api/anthropic` is proxied via Nginx to bypass CORS restrictions. If the user reports CORS errors during local dev, ensure the Vite proxy in `vite.config.js` matches the Nginx spec.
+*   **JSON Enforcement:** Prompts *must* strictly enforce that Claude returns *only* raw JSON. Do not let the AI wrap the response in markdown blocks (`\`\`\``) unless you build a regex to strip them (which is currently implemented via `.match(/\{[\s\S]*\}/)`).
+
+## 4. Design System & Aesthetics
+Respellion relies on a premium, modern aesthetic. 
+*   **CSS Variables:** Rely heavily on the variables defined in `src/index.css`.
+    *   Colors: `var(--color-bg)`, `var(--color-paper)`, `var(--color-teal)`, `var(--color-accent)`.
+    *   Radii: `var(--r-sm)`, `var(--r-lg)`, `var(--r-org)` (an organic, pill-like shape used for badges and podiums).
+*   **Tailwind:** Tailwind is mapped to these CSS variables. Avoid hardcoding random hex codes. Use the existing Tailwind classes like `bg-teal`, `text-fg-muted`, and `border-bg-warm`.
+*   **Components:** Always reuse the UI primitives in `src/components/ui/` (`Card.jsx`, `Button.jsx`, `Tag.jsx`, `Input.jsx`).
+
+## 5. Gamification Rules
+If you are extending the Gamification system (`src/pages/Leaderboard.jsx`):
+*   Tests grant **+2 points** per correct answer.
+*   A 100% score grants the **Perfectionist** badge.
+*   Completing 1 test grants **First Steps**, completing 5 grants **Veteran**.
+*   Do not reset points dynamically. Read from `leaderboard:current`, mutate, and save back immediately.
+
+## 6. Docker & Deployment
+The app is fully containerized.
+*   **Build:** `docker build -t respellion-app:latest .`
+*   **Run:** `docker run -d -p 8080:80 --name respellion respellion-app:latest`
+*   **Nginx:** Ensure any new frontend routes are caught by the Nginx `try_files $uri $uri/ /index.html;` directive defined in `nginx.conf` to prevent 404s on page refresh.
+
+## 7. How to Add New Features
+1. **Define State:** Decide where the data lives in `localStorage`.
+2. **Build UI:** Create components using `Card`, `Button`, and `framer-motion` for smooth entry (`animate-in fade-in slide-in-from-bottom-4`).
+3. **Wire Logic:** Connect to `src/store/AppContext.jsx` if it requires global user context, otherwise manage locally and persist to `storage.js`.
+4. **Test:** Run the Docker container to ensure no build errors exist.
+
+Good luck! You are building a platform that empowers continuous learning. Keep it fast, keep it beautiful, and keep the user engaged.