docs: update README and AI_AGENT.md with platform architecture, selective content generation, and deployment details

README.md

@@ -1,16 +1,80 @@
-# React + Vite
+# Respellion Learning Platform
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+An internal AI-powered learning platform that keeps Respellion employees up to date with the company's evolving knowledge base.
 
-Currently, two official plugins are available:
+## Features
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+- **Weekly Learning Station** — Each employee is assigned a topic each week (via deterministic hash of user ID + week number). They choose their preferred format: Article, Slides, or Infographic. Content is generated on-demand by Claude and cached per topic.
+- **Weekly Test** — AI-generated quiz based on the knowledge graph. Results are stored and feed the leaderboard.
+- **Leaderboard & Gamification** — Points for correct answers, badges for streaks and perfect scores.
+- **R42 Chatbot** — An always-available AI assistant (backed by Claude) with access to the full knowledge graph. Can propose graph updates that admins approve or reject.
+- **Admin Panel** — Manage the knowledge graph, sync from GitHub, review generated content, refine it with AI, and monitor team progress.
 
-## React Compiler
+## Tech Stack
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+| Layer | Technology |
+|---|---|
+| Frontend | React 18 + Vite |
+| Styling | Vanilla CSS (custom properties) + Tailwind utility classes |
+| Animations | Framer Motion |
+| Icons | Lucide React |
+| Graph viz | D3.js (admin knowledge graph only) |
+| Backend / DB | PocketBase (self-hosted) |
+| AI | Anthropic Claude (via Caddy reverse proxy) |
+| Infra | Docker + Caddy |
 
-## Expanding the ESLint configuration
+## Getting Started (local dev)
 
-If you are developing a production application, we recommend using TypeScript with type-aware lint rules enabled. Check out the [TS template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts) for information on how to integrate TypeScript and [`typescript-eslint`](https://typescript-eslint.io) in your project.
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Start PocketBase (Windows)
+./pocketbase.exe serve
+
+# 3. Start the dev server
+npm run dev
+```
+
+The Vite dev server proxies `/api/anthropic` and `/pb` — see `vite.config.js`.
+
+## Deployment (Docker)
+
+```bash
+docker compose up -d
+```
+
+The `Caddyfile` handles:
+- SPA fallback routing
+- `/pb/*` → PocketBase sidecar
+- `/api/anthropic/*` → Anthropic API (with server-side API key injection)
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `src/lib/learningService.js` | Selective content generation (article / slides / infographic) |
+| `src/lib/extractionPipeline.js` | GitHub file → knowledge graph extraction |
+| `src/lib/api.js` | Anthropic API wrapper (`generateContent` + `chat`) |
+| `src/lib/db.js` | All PocketBase data access |
+| `src/lib/giteaService.js` | GitHub API client (folder listing + raw file fetch) |
+| `src/store/AppContext.jsx` | Global state; computes ISO week number on load |
+| `src/components/admin/UploadZone.jsx` | GitHub sync UI (default folder: `docs/knowledge-base/`) |
+| `AI_AGENT.md` | Detailed context guide for AI coding agents |
+
+## Content Types
+
+Learning content is generated **on demand per type** and merged into the cached object:
+
+| Type | Key in DB | Description |
+|---|---|---| 
+| Article | `content.article` | Long-form reading |
+| Slides | `content.slides` | Slide deck with speaker notes |
+| Infographic | `content.infographic` | Visual summary with stats and steps |
+
+> The podcast type was removed. Do not re-add it.
+
+## Documentation
+
+- **`AI_AGENT.md`** — Full architectural guide for AI coding agents (patterns, gotchas, decisions).
+- **`CHANGELOG.md`** — PocketBase upstream changelog (not application changelog).