diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..0093f52
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,17 @@
+# Normalize line endings across platforms
+* text=auto eol=lf
+
+# Windows scripts that must keep CRLF
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+# Binary assets
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.webp binary
+*.woff binary
+*.woff2 binary
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..92e6ef9
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,70 @@
+# ─── Dependencies ───────────────────────────────────────────────────────────
+node_modules/
+server/node_modules/
+client/node_modules/
+
+# ─── Environment & secrets (never commit) ───────────────────────────────────
+.env
+.env.*
+!.env.example
+server/.env
+client/.env
+client/.env.local
+client/.env.*.local
+
+# ─── Build output ───────────────────────────────────────────────────────────
+client/dist/
+dist/
+build/
+out/
+.vite/
+
+# ─── Logs ───────────────────────────────────────────────────────────────────
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# ─── Testing & coverage ─────────────────────────────────────────────────────
+coverage/
+.nyc_output/
+
+# ─── Caches ─────────────────────────────────────────────────────────────────
+.cache/
+.parcel-cache/
+.turbo/
+.eslintcache
+*.tsbuildinfo
+
+# ─── OS files ───────────────────────────────────────────────────────────────
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+Desktop.ini
+
+# ─── Editors & IDEs ─────────────────────────────────────────────────────────
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json.example
+.idea/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+*~
+
+# ─── Cursor / local tooling ─────────────────────────────────────────────────
+.cursor/
+
+# ─── Misc ───────────────────────────────────────────────────────────────────
+*.local
+.temp/
+tmp/
diff --git a/PRODUCT.md b/PRODUCT.md
new file mode 100644
index 0000000..f31ff5f
--- /dev/null
+++ b/PRODUCT.md
@@ -0,0 +1,545 @@
+# CrowdFAQ — Product Document
+
+> **Version:** 1.0.0 | **Stack:** MERN + Tailwind CSS v3 | **Status:** Production-Ready MVP
+
+---
+
+## 1. Product Overview
+
+**CrowdFAQ** is a full-stack, crowd-sourced FAQ and community Q&A platform where users collaboratively build a shared knowledge base. Anyone can browse answers; authenticated members can ask questions, submit answers, vote, and earn reputation. Moderators can approve or reject community content inline — no separate admin panel required.
+
+The platform was designed to solve a real problem: static FAQ pages go stale and are hard to maintain. CrowdFAQ turns knowledge management into a living, community-driven activity.
+
+### Target Users
+
+| Persona | Need |
+|---------|------|
+| **Guest / Reader** | Quickly find answers to common questions without signing up |
+| **Community Member** | Ask questions, contribute answers, track personal progress |
+| **Moderator / Admin** | Review, approve, or reject community-submitted content |
+
+---
+
+## 2. Feature Catalogue
+
+### 2.1 Core FAQ Browser (`/`)
+
+- **Searchable accordion list** of curated FAQs — expandable/collapsible with smooth CSS animation
+- **Debounced full-text search** (350 ms) hitting server-side MongoDB `$regex` across question body, answer body, tags, keywords, and category simultaneously
+- **Category filter bar** — sticky pill buttons (All + 8 categories); highlights active selection
+- **Sort modes** — Latest / Most Helpful / Most Viewed via a dropdown
+- **Yes / No voting** on every FAQ — localStorage deduplication prevents repeat votes; helpful percentage displayed after voting
+- **View count** tracking — each accordion open increments the FAQ's view counter
+- **Tag chips** displayed on each FAQ card
+- **Decorative hero section** with animated blur blobs and a live quick-stats bar
+- **Two-column desktop layout** with a sticky right sidebar
+
+### 2.2 Community Q&A (`/community`, `/community/:id`)
+
+- **Question list** sorted newest-first; each card shows status badge, category badge, answer count, relative timestamp, submitter name and tags
+- **Status filter tabs**: All · Pending (red count badge) · Approved · Rejected
+- **Search + category dropdown** filter on the community list
+- **Inline moderation** — Approve / Reject / Mark Pending buttons with per-button loading state directly on every question card and answer card
+- **Question detail page** — breadcrumb navigation, full question card, all answers with avatar initials and numbered badges
+- **Answer status tabs** — filter answers by status within a question
+- **Optimistic UI** — submitted answer appends to the list immediately without a round-trip refetch
+
+### 2.3 Ask a Question (`/ask`) — Auth Required
+
+- **Authenticated form**: name and email pre-filled from JWT; no manual entry
+- **Fields**: Question Title (200-char limit), Description (2000-char limit) with live character counters, Category dropdown, Tags
+- **Chip-based tag input** — Enter or comma to add, Backspace to remove, max 5 tags
+- **Real-time duplicate detection** — debounced 600 ms call to `/api/questions/similar`; collapsible SimilarPanel shows matching FAQs with expandable answers before the user submits
+- **Spam prevention** — server enforces one question per registered email per hour; returns `429` with remaining wait time if exceeded
+- **Animated success screen** with pending-review status message and navigation options
+
+### 2.4 Authentication (`/auth`)
+
+- **Tabbed login / signup UI** on a single page (`/auth`)
+- **JWT-based stateless auth** — 7-day expiry, stored in `localStorage`
+- **bcrypt password hashing** (salt rounds: 10) — passwords are never stored in plaintext
+- **Protected routes** — guests redirected to `/auth` with a return-path query param; after login they land back on the intended page
+- **`/api/auth/me`** — validates token and returns current user (used on app load for session restore)
+
+### 2.5 AI-Powered Answer Suggestions
+
+- Available to logged-in users on the question detail page
+- Collapsible **🤖 AI Suggest** panel above the answer textarea
+- On first expand, calls `GET /api/suggest?q=`
+- **Keyword-overlap scoring engine** (no external API required):
+ 1. Tokenises the question, filters stop words
+ 2. Scores every approved FAQ in the database by `keyword hits / total keywords`
+ 3. Returns the best match if score ≥ 25% confidence threshold
+- Panel displays: **confidence percentage bar**, suggested answer text, and source FAQ citation
+- **"Use this suggestion"** button pre-fills the answer textarea for editing before submit
+
+### 2.6 AI Confidence Scores on Answers
+
+- Every submitted answer receives a computed **confidence score (0–100)** stored on the Answer document at submit time
+- Scoring formula: **60% question keyword coverage + 40% FAQ corpus alignment**
+- Displayed as a colour-coded animated progress bar under each answer:
+ - 🟢 ≥ 70% — High confidence
+ - 🟡 ≥ 40% — Medium confidence
+ - 🔴 < 40% — Low confidence
+- Visible on the **Question Detail page** and on the user's **Profile page**
+
+### 2.7 Reputation & Leaderboard System
+
+#### Points Table
+
+| Action | Points |
+|--------|--------|
+| Ask a question | +2 pts |
+| Submit an answer | +5 pts |
+| Answer gets approved | +15 pts |
+| Answer receives an upvote | +10 pts |
+
+#### Levels
+
+| Level | Threshold |
+|-------|-----------|
+| 🌱 Beginner | 0 – 49 pts |
+| ⭐ Contributor | 50 – 199 pts |
+| 🏆 Expert | 200+ pts |
+
+- Level auto-recalculated on every point award (`recalcLevel()` on the User model)
+- **Upvote toggle** on each answer — tracks voters in `upvotedBy[]` to prevent double-voting; requires auth; grayed out for guests with tooltip
+- **Leaderboard page** (`/leaderboard`) — ranked cards with progress bars, medal icons for top 3, level badges, stats row, and a points-system explanation panel
+
+### 2.8 User Profile Page (`/profile`) — Auth Required
+
+- **Gradient banner** — colour scheme matches the user's current level
+- **Gradient avatar** with first-initial, level badge, and points total
+- **Level progress bar** — shows current points and points needed for next level
+- **4-stat grid**: Questions Asked · Answers Given · Answers Approved · Upvotes Received
+- **Three-tab layout**:
+ - ❓ **Questions** — all questions asked with status badges and links
+ - 💬 **Answers** — all answers given with confidence score bars, status, and upvote count
+ - ❤️ **Saved FAQs** — all bookmarked FAQs with full content preview
+- Empty-state CTAs on each tab when no content exists
+
+### 2.9 Save FAQs (Heart Bookmark)
+
+- Heart icon rendered on every FAQ card when the user is logged in
+- Filled rose when saved, hollow grey when not; click toggles
+- Save state persisted in the database (`User.savedFAQs` array of FAQ ObjectIds)
+- `POST /api/auth/save-faq/:faqId` toggles and returns the updated saved list
+- AuthContext syncs state client-side; no page reload required
+
+### 2.10 "People Like You Also Asked" Sidebar
+
+- Sticky right sidebar on the FAQ page (desktop only; hidden on mobile)
+- Appears when any FAQ accordion is expanded
+- Calls `GET /api/faqs/related?category=<>&tags=<>&exclude=<>` — returns up to 4 FAQs in the same category or sharing tags, sorted by helpful votes + views
+- **Login CTA card** shown to guests to encourage saving FAQs
+
+### 2.11 Dark Mode
+
+- Sun/moon toggle in the Navbar
+- Persisted to `localStorage` key `crowdfaq-theme`
+- OS preference detected on first visit (`prefers-color-scheme`)
+- Blocking inline script in `index.html` applies the theme class before React paints — eliminates flash of wrong theme
+- All pages, cards, inputs, buttons, and badges have complete `dark:` variants
+
+---
+
+## 3. Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Browser Client │
+│ React 18 + Vite · React Router v6 · Axios · Tailwind v3 │
+│ │
+│ Pages: FAQ · Auth · Ask · Community · Detail · Leaderboard │
+│ · Profile │
+│ Context: AuthContext · ThemeContext │
+└──────────────────────────┬──────────────────────────────────┘
+ │ /api/* proxy (Vite dev)
+ ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Express API Server │
+│ Node.js · Express 4 · Mongoose · JWT · bcrypt │
+│ │
+│ Routes: /auth · /faqs · /questions · /answers │
+│ · /users · /suggest │
+│ Middleware: requireAuth · optionalAuth │
+└──────────────────────────┬──────────────────────────────────┘
+ │ Mongoose ODM
+ ▼
+┌─────────────────────────────────────────────────────────────┐
+│ MongoDB │
+│ Collections: users · faqs · questions · answers │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Key Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Vite `/api` proxy | Eliminates CORS setup in development; no extra config |
+| `answerCount` denormalized on Question | Avoids expensive `countDocuments()` on every list render; atomically incremented |
+| Optimistic UI on answer submit | Answer appears instantly without a round-trip refetch |
+| `author` defaults to `"Anonymous"` | Legacy compatibility for pre-auth answers |
+| JWT in `localStorage` | Simple stateless auth; works seamlessly with Vite proxy |
+| Blocking theme script in `index.html` | Prevents flash of wrong theme before React hydrates |
+| `max-h` CSS trick for accordion | Smooth CSS animation with zero JS height measurement |
+| Global `.card`, `.btn-primary` in `index.css` | Consistent design tokens; avoids duplicating long Tailwind utility chains |
+| Confidence score stored at submit time | Pre-computed value ensures instant display; no on-the-fly scoring cost |
+| `concurrently` in root `package.json` | Single `npm run dev` starts both servers with colour-coded output |
+
+---
+
+## 4. Data Models
+
+### User
+| Field | Type | Notes |
+|-------|------|-------|
+| `name` | String | Required |
+| `email` | String | Unique, lowercase |
+| `password` | String | bcrypt-hashed, `select: false` |
+| `points` | Number | Default 0 |
+| `level` | Enum | Beginner / Contributor / Expert |
+| `stats` | Object | `questionsAsked`, `answersGiven`, `answersApproved`, `upvotesReceived` |
+| `savedFAQs` | [ObjectId] | Refs to FAQ collection |
+
+### FAQ
+| Field | Type | Notes |
+|-------|------|-------|
+| `question` | String | Required |
+| `answer` | String | Required |
+| `category` | String | — |
+| `tags` | [String] | — |
+| `keywords` | [String] | Used for AI scoring |
+| `status` | Enum | approved / pending / rejected |
+| `helpfulYes` | Number | Vote count |
+| `helpfulNo` | Number | Vote count |
+| `views` | Number | Incremented on accordion open |
+
+### Question
+| Field | Type | Notes |
+|-------|------|-------|
+| `title` | String | Required |
+| `description` | String | — |
+| `name` | String | From auth user |
+| `email` | String | From auth user |
+| `category` | String | — |
+| `tags` | [String] | — |
+| `status` | Enum | pending / approved / rejected |
+| `answerCount` | Number | Denormalized; incremented on answer POST |
+
+### Answer
+| Field | Type | Notes |
+|-------|------|-------|
+| `questionId` | ObjectId | Ref to Question |
+| `body` | String | Required |
+| `author` | String | From auth user name |
+| `authorId` | ObjectId | Ref to User (for point awards) |
+| `status` | Enum | pending / approved / rejected |
+| `confidence` | Number | 0–100; computed at submit |
+| `upvotes` | Number | Count |
+| `upvotedBy` | [String] | Voter emails; prevents double-voting |
+
+---
+
+## 5. API Reference
+
+### Authentication
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| `POST` | `/api/auth/register` | No | Create account |
+| `POST` | `/api/auth/login` | No | Log in, returns JWT |
+| `GET` | `/api/auth/me` | Yes | Current user + populated savedFAQs |
+| `POST` | `/api/auth/save-faq/:faqId` | Yes | Toggle save/unsave an FAQ |
+
+### FAQs
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| `GET` | `/api/faqs` | No | List FAQs (`?search`, `?category`, `?sort`) |
+| `GET` | `/api/faqs/:id` | No | Single FAQ |
+| `POST` | `/api/faqs/:id/vote` | No | Vote helpful / not helpful |
+| `GET` | `/api/faqs/related` | No | Related FAQs by category/tags |
+
+### Community Questions
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| `GET` | `/api/questions` | No | List questions (`?status`, `?search`, `?category`) |
+| `POST` | `/api/questions` | Yes | Create question (+2 pts) |
+| `GET` | `/api/questions/:id` | No | Single question |
+| `GET` | `/api/questions/similar` | No | Duplicate detection (`?q=`) |
+| `PATCH` | `/api/questions/:id/status` | No | Approve / Reject / Pending |
+
+### Answers
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| `GET` | `/api/answers/:questionId` | No | List answers for a question |
+| `POST` | `/api/answers` | Yes | Submit answer (+5 pts, confidence scored) |
+| `PATCH` | `/api/answers/:id/status` | No | Approve (+15 pts to author) / Reject / Pending |
+| `POST` | `/api/answers/:id/upvote` | Yes | Toggle upvote (+10 pts to author) |
+
+### AI & Users
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| `GET` | `/api/suggest?q=` | No | AI-suggested answer from FAQ corpus |
+| `GET` | `/api/users/leaderboard` | No | Top contributors sorted by points |
+| `GET` | `/api/users/:id` | No | Public user profile |
+| `GET` | `/api/users/me/profile` | Yes | Full profile: questions + answers + savedFAQs |
+| `GET` | `/api/health` | No | Health check |
+
+---
+
+## 6. Project Structure
+
+```
+crowdfaq/
+├── package.json # Root: dev, seed, build, start scripts
+├── .gitignore
+├── .gitattributes
+├── README.md
+├── CONTEXT.md # Full development history & decisions
+├── PRODUCT.md # This file
+│
+├── server/
+│ ├── index.js # Express app entry, route mounts
+│ ├── seed.js # Seeds 10 sample internship FAQs
+│ ├── .env.example # Template — copy to .env
+│ ├── middleware/
+│ │ └── auth.js # signToken, requireAuth, optionalAuth
+│ ├── models/
+│ │ ├── User.js
+│ │ ├── FAQ.js
+│ │ ├── Question.js
+│ │ └── Answer.js
+│ └── routes/
+│ ├── auth.js # register, login, me, save-faq
+│ ├── faqs.js # list, vote, related
+│ ├── questions.js # CRUD, similar, status
+│ ├── answers.js # CRUD, upvote, status, confidence
+│ ├── suggest.js # AI keyword-overlap engine
+│ └── users.js # leaderboard, profile
+│
+└── client/
+ ├── index.html # Theme flash-prevention script
+ ├── vite.config.js # Port 3000, /api proxy → :5000
+ ├── tailwind.config.js # darkMode: 'class', Inter font, custom animations
+ ├── postcss.config.js
+ └── src/
+ ├── main.jsx
+ ├── App.jsx # Router, AuthProvider, ThemeProvider
+ ├── index.css # Design tokens, dark variants, utilities
+ ├── context/
+ │ ├── AuthContext.jsx
+ │ └── ThemeContext.jsx
+ ├── services/
+ │ └── api.js # Axios instance + all API functions
+ ├── utils/
+ │ └── constants.js # CATEGORIES, timeAgo(), STATUS_META, CATEGORY_COLORS
+ ├── components/
+ │ ├── Navbar.jsx
+ │ ├── Footer.jsx
+ │ ├── AccordionItem.jsx
+ │ ├── Spinner.jsx
+ │ ├── ErrorMessage.jsx
+ │ └── ProtectedRoute.jsx
+ └── pages/
+ ├── FAQPage.jsx
+ ├── AuthPage.jsx
+ ├── AskQuestionPage.jsx
+ ├── CommunityPage.jsx
+ ├── QuestionDetailPage.jsx
+ ├── LeaderboardPage.jsx
+ └── ProfilePage.jsx
+```
+
+---
+
+## 7. Frontend Pages & Routes
+
+| Route | Auth Required | Description |
+|-------|:---:|-------------|
+| `/` | No | FAQ browser — search, filter, vote, AI sidebar, save |
+| `/auth` | No | Tabbed login / signup |
+| `/ask` | **Yes** | Submit a community question with duplicate detection |
+| `/community` | No | Browse & moderate community questions |
+| `/community/:id` | No (answer: Yes) | Question detail, answers, confidence bars, AI suggest |
+| `/leaderboard` | No | Top contributors ranked by reputation |
+| `/profile` | **Yes** | Personal stats, history, and saved FAQs |
+
+---
+
+## 8. Design System
+
+### Colour Palette
+- **Primary**: Indigo/Violet gradient (`indigo-600` → `violet-600`)
+- **Background (light)**: `slate-50`
+- **Background (dark)**: `gray-900` / `gray-800`
+- **Typography**: [Inter](https://fonts.google.com/specimen/Inter) from Google Fonts
+
+### Utility Classes (`index.css`)
+
+| Class | Purpose |
+|-------|---------|
+| `.btn-primary` | Gradient button with shadow glow, hover lift |
+| `.btn-secondary` | Outlined secondary action button |
+| `.btn-success` / `.btn-danger` | Status action buttons |
+| `.card` | White/dark surface with border and shadow |
+| `.card-hover` | Adds lift + shadow transition on hover |
+| `.stat-card` | Dashboard-style metric tile |
+| `.input-field` | Consistent form input styling |
+| `.select-field` | Dropdown select styling |
+| `.tag-chip` | Small pill for tag display |
+| `.badge` | Inline status badge |
+| `.glass` | Glassmorphism: `bg-white/80 backdrop-blur-md` |
+| `.gradient-text` | Indigo-to-violet gradient text |
+| `.confidence-bar-track` / `-fill` | Animated progress bar |
+| `.glow-primary` | Box-shadow glow in primary colour |
+| `.animate-slide-up` | Subtle entrance animation |
+| `.no-scrollbar` | Hides scrollbar cross-browser |
+
+### Animations (Tailwind config)
+- `fadeIn` — opacity 0→1, 0.3s
+- `slideDown` — translate-y -10px→0 + opacity, 0.3s
+
+---
+
+## 9. Environment Variables
+
+**File**: `server/.env` (gitignored — copy from `server/.env.example`)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MONGO_URI` | `mongodb://localhost:27017/crowdfaq` | MongoDB connection string (local or Atlas) |
+| `PORT` | `5000` | Express API port |
+| `JWT_SECRET` | *(must set)* | Secret for signing auth tokens — **change before deploying** |
+
+---
+
+## 10. Getting Started
+
+### Prerequisites
+
+| Tool | Version |
+|------|---------|
+| Node.js | v18+ |
+| MongoDB | 6+ (local or Atlas) |
+
+### Setup
+
+```bash
+# 1. Clone
+git clone https://github.com/Just-Here-TO-Code/cs-faq.git
+cd cs-faq
+
+# 2. Install all dependencies (root + server + client)
+npm install
+
+# 3. Configure environment
+# macOS/Linux:
+cp server/.env.example server/.env
+# Windows PowerShell:
+Copy-Item server\.env.example server\.env
+
+# 4. Seed sample FAQs (required for AI suggestions to work)
+npm run seed
+
+# 5. Start both servers
+npm run dev
+```
+
+| Service | URL |
+|---------|-----|
+| Frontend (React + Vite) | http://localhost:3000 |
+| Backend (Express API) | http://localhost:5000 |
+
+### npm Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm install` | Install root + server + client dependencies |
+| `npm run dev` | Start API (nodemon) + frontend (Vite) concurrently |
+| `npm run seed` | Seed 10 sample internship FAQs into MongoDB |
+| `npm run build` | Build React app to `client/dist/` |
+| `npm run start` | Run Express in production mode |
+
+---
+
+## 11. Dependencies
+
+### Server
+
+| Package | Purpose |
+|---------|---------|
+| `express ^4.19` | HTTP server framework |
+| `mongoose ^8.4` | MongoDB ODM |
+| `bcryptjs` | Password hashing |
+| `jsonwebtoken` | JWT signing & verification |
+| `cors ^2.8` | CORS headers |
+| `dotenv ^16.4` | `.env` loader |
+| `nodemon ^3.1` (dev) | Auto-restart on file change |
+
+### Client
+
+| Package | Purpose |
+|---------|---------|
+| `react ^18.3` | UI library |
+| `react-dom ^18.3` | DOM renderer |
+| `react-router-dom ^6.24` | Client-side routing |
+| `axios ^1.7` | HTTP client |
+| `vite ^5.3` (dev) | Build tool & dev server |
+| `tailwindcss ^3.4` (dev) | Utility-first CSS |
+| `autoprefixer ^10.4` (dev) | CSS vendor prefixes |
+| `postcss ^8.4` (dev) | CSS processor |
+
+---
+
+## 12. Security Notes
+
+- `server/.env` is gitignored — only `.env.example` is committed
+- Passwords stored as bcrypt hashes (cost factor 10); never returned in API responses (`select: false`)
+- JWT tokens expire after **7 days**
+- Use a strong, randomly-generated `JWT_SECRET` in production
+- The AI suggestion engine runs entirely on the local MongoDB corpus — no external API keys or data sharing
+- For production: build the client (`npm run build`), serve `client/dist/` via a reverse proxy (nginx/Caddy), and run the Express API behind it
+
+---
+
+## 13. Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `MongoDB connection error` | Ensure MongoDB is running; verify `MONGO_URI` in `server/.env` |
+| `Port 5000 already in use` | Change `PORT` in `server/.env` and update Vite proxy in `client/vite.config.js` |
+| `Port 3000 already in use` | Change `server.port` in `client/vite.config.js` |
+| `401` on posting questions/answers | Log in first — JWT is required |
+| Empty FAQ page after install | Run `npm run seed` to populate sample data |
+| AI suggestion returns nothing | Seed must be loaded; try questions about eligibility, stipend, or certificates |
+| `npm install` fails | Use Node.js v18+; delete all `node_modules` folders and retry |
+
+---
+
+## 14. Roadmap
+
+The following features are scoped for future releases:
+
+| # | Feature | Notes |
+|---|---------|-------|
+| 1 | **Pagination** | `?page=` & `?limit=` on all list endpoints; pagination UI components |
+| 2 | **Admin Panel** | Dedicated `/admin` protected route; role-based access; direct FAQ CRUD |
+| 3 | **Email Notifications** | Nodemailer — notify question author when an answer is posted |
+| 4 | **Rich Text Editor** | Markdown support for answers (`react-markdown` + `remark`) |
+| 5 | **Delete Functionality** | Hard-delete questions and answers (currently only status changes supported) |
+
+---
+
+## 15. See Also
+
+- [`README.md`](./README.md) — Quick-start guide for developers
+- [`CONTEXT.md`](./CONTEXT.md) — Full development history, session log, and architecture decisions
+
+---
+
+*Last updated: 2026-06-28 — CrowdFAQ v1.0.0*
diff --git a/README.md b/README.md
index edec17a..343c644 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,324 @@
-# cs53
\ No newline at end of file
+# CrowdFAQ
+
+A crowd-sourced FAQ platform built with the **MERN stack** (MongoDB, Express, React, Node.js) and **Tailwind CSS v3**.
+
+Browse FAQs and community questions without an account. **Sign up or log in** to ask questions and submit answers. Includes dark mode, voting, categories, duplicate detection, a moderation workflow, AI-powered answer suggestions, and a reputation/leaderboard system.
+
+---
+
+## ✨ Features
+### Core
+- **FAQ browser** — search, filter by category, sort by latest / helpful / views, yes/no voting
+- **Community Q&A** — ask questions, view answers, moderation (approve / reject / pending)
+- **Authentication** — JWT login & signup; protected question and answer submission
+- **Dark mode** — toggle with persistence across sessions
+
+### Smart Features
+- **Duplicate detection** — warns when similar FAQs or questions already exist before submitting
+- **Spam prevention** — one question per account per hour (server-side enforcement)
+- **Multi-field search** — searches question text, answer text, tags, keywords, and category simultaneously
+- **Sort modes** — sort FAQs by Latest, Most Helpful, or Most Viewed
+
+### Moderation
+- **Question moderation** — Approve / Reject / Mark Pending on any community question
+- **Answer moderation** — Approve / Reject / Mark Pending on any individual answer
+- **Status tabs** — filter questions and answers by status (all / pending / approved / rejected)
+
+### 🤖 AI-Powered Suggested Answers
+- When a logged-in user opens a pending question, an **AI Suggest** panel appears above the answer form
+- Analyses question text against all approved FAQs using keyword-overlap scoring
+- Displays the best-matching FAQ answer with a **confidence percentage bar**
+- Admin/user can click **"Use this suggestion"** to pre-fill the answer textarea
+
+### 🎯 AI Confidence Scores on Answers
+- Every submitted answer receives a computed **confidence score (0–100%)**
+- Score blends: keyword coverage of the question (60%) + alignment with existing FAQ content (40%)
+- Displayed as a colour-coded bar under each answer (🟢 ≥70%, 🟡 ≥40%, 🔴 <40%)
+- Visible on the question detail page and on the user's profile page
+
+### 🏆 Reputation System
+- **Points** awarded for contributions:
+
+ | Action | Points |
+ |--------|--------|
+ | Ask a question | +2 pts |
+ | Submit an answer | +5 pts |
+ | Answer gets approved | +15 pts |
+ | Answer receives an upvote | +10 pts |
+
+- **Levels** based on total points: 🌱 Beginner (0–49) · ⭐ Contributor (50–199) · 🏆 Expert (200+)
+- **Upvote buttons** on each answer (toggle; logged-in users only)
+- **Leaderboard page** (`/leaderboard`) ranks top contributors with progress bars, level badges, and stats
+
+### 👤 User Profile Page
+- Beautiful profile page at `/profile` with gradient banner matching the user's level
+- **Level progress bar** — shows current points and points needed for next level
+- **4-stat grid**: Questions Asked, Answers Given, Answers Approved, Upvotes Received
+- **Tabbed sections**:
+ - ❓ **Questions** — all questions asked, with status badges, links to detail page
+ - 💬 **Answers** — all answers given, with confidence score bars, status, upvote count
+ - ❤️ **Saved FAQs** — all bookmarked FAQs with full content preview
+- Navbar avatar is now a clickable link to the profile page
+
+### ❤️ Save FAQs
+- Heart icon on every FAQ card (visible when logged in)
+- Toggles save/unsave; saved state persisted in database (User model)
+- Saved FAQs appear in the profile page's **Saved FAQs** tab
+
+### 👥 People Like You Also Asked
+- Sidebar panel on the FAQ page that appears when a FAQ is expanded
+- Shows up to 4 related FAQs sharing the same **category** or **tags**
+- On desktop (large screens) as a sticky right rail
+- Login CTA card shown to guests to encourage saving FAQs
+
+### 🎨 Modernised UI
+- `btn-primary` now uses gradient + shadow glow
+- `card-hover` adds lift on hover with shadow transition
+- `stat-card` component for dashboard-style stat tiles
+- `confidence-bar` utility classes for animated progress bars
+- No-scrollbar utility, `glow-primary`, `slide-up` animation
+- FAQ hero has decorative blur blobs and quick-stats bar with progress bars, level badges, and stats
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Frontend | React 18, Vite, React Router, Tailwind CSS v3, Axios |
+| Backend | Node.js, Express 4, Mongoose |
+| Database | MongoDB |
+| Auth | JWT + bcrypt |
+
+---
+
+## Prerequisites
+
+Install these before cloning:
+
+| Tool | Version | Notes |
+|------|---------|-------|
+| [Node.js](https://nodejs.org/) | v18+ | Includes npm |
+| [MongoDB](https://www.mongodb.com/try/download/community) | 6+ | Local install **or** [MongoDB Atlas](https://www.mongodb.com/atlas) free tier |
+
+**MongoDB must be reachable** before starting the server.
+
+| Platform | Start MongoDB locally |
+|----------|----------------------|
+| Windows | `net start MongoDB` or open MongoDB Compass |
+| macOS | `brew services start mongodb-community` |
+| Linux | `sudo systemctl start mongod` |
+
+---
+
+## Getting Started (Clone & Run)
+
+### 1. Clone the repository
+
+```bash
+git clone https://github.com/Just-Here-TO-Code/cs-faq.git
+cd cs-faq
+```
+
+### 2. Install dependencies
+
+From the project root:
+
+```bash
+npm install
+```
+
+This installs root, `server/`, and `client/` packages automatically via the `postinstall` script.
+
+### 3. Configure environment variables
+
+Copy the example env file and edit if needed:
+
+**macOS / Linux**
+```bash
+cp server/.env.example server/.env
+```
+
+**Windows (PowerShell)**
+```powershell
+Copy-Item server\.env.example server\.env
+```
+
+Default `server/.env` values work for local development:
+
+```env
+MONGO_URI=mongodb://localhost:27017/crowdfaq
+PORT=5000
+JWT_SECRET=your-super-secret-jwt-key-change-me
+```
+
+| Variable | Description |
+|----------|-------------|
+| `MONGO_URI` | MongoDB connection string (local or Atlas) |
+| `PORT` | Express API port (default `5000`) |
+| `JWT_SECRET` | Secret for signing auth tokens — **change in production** |
+
+**Using MongoDB Atlas?** Replace `MONGO_URI` with your Atlas connection string, e.g.:
+
+```env
+MONGO_URI=mongodb+srv://<user>:<password>@<cluster>.mongodb.net/crowdfaq
+```
+
+### 4. Seed sample data
+
+Populates the database with 10 sample FAQs (required for AI suggestions to work):
+
+```bash
+npm run seed
+```
+
+### 5. Start the development servers
+
+```bash
+npm run dev
+```
+
+| Service | URL |
+|---------|-----|
+| **Frontend** (React + Vite) | http://localhost:3000 |
+| **Backend** (Express API) | http://localhost:5000 |
+
+The Vite dev server proxies `/api/*` to the Express server, so no extra CORS setup is needed during development.
+
+### 6. Try it out
+
+1. Open http://localhost:3000 — browse FAQs
+2. Go to **Log In** → **Sign Up** to create an account
+3. Visit **Ask Question** to submit a community question
+4. Open **Community** to view and moderate questions
+5. Click a question → answer it → see the 🤖 AI suggestion panel
+6. Check **🏆 Leaderboard** to see top contributors
+
+---
+
+## Project Structure
+
+```
+crowdfaq/
+├── package.json # Root scripts (dev, seed, build)
+├── .gitignore
+├── README.md
+├── CONTEXT.md # Development history & decisions
+│
+├── server/ # Express API
+│ ├── index.js
+│ ├── seed.js
+│ ├── .env.example # Template — copy to .env (not committed)
+│ ├── middleware/auth.js
+│ ├── models/ # User, FAQ, Question, Answer
+│ └── routes/ # auth, faqs, questions, answers, users, suggest
+│
+└── client/ # React + Vite frontend
+ ├── vite.config.js # Dev proxy: /api → localhost:5000
+ └── src/
+ ├── pages/ # FAQ, Auth, Ask, Community, Detail, Leaderboard
+ ├── components/
+ ├── context/ # Theme + Auth providers
+ └── services/api.js
+```
+
+---
+
+## npm Scripts
+
+Run all commands from the **project root**:
+
+| Script | Description |
+|--------|-------------|
+| `npm install` | Install dependencies (root + server + client) |
+| `npm run dev` | Start API (nodemon) + frontend (Vite) together |
+| `npm run seed` | Seed 10 sample FAQs into MongoDB |
+| `npm run build` | Build React app to `client/dist/` |
+| `npm run start` | Run Express in production mode (`node index.js`) |
+
+---
+
+## Pages & Routes
+
+| Route | Auth | Description |
+|-------|------|-------------|
+| `/` | No | FAQ page with search, filters, voting, People-like-you sidebar |
+| `/auth` | No | Login & signup |
+| `/ask` | Yes | Submit a community question |
+| `/community` | No | Browse questions with moderation tabs |
+| `/community/:id` | No (answer: Yes) | Question detail + answers + confidence scores + AI suggestion |
+| `/leaderboard` | No | Top contributors ranked by reputation points |
+| `/profile` | Yes | Personal profile: stats, questions, answers, saved FAQs |
+
+---
+
+## API Overview
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| `POST` | `/api/auth/register` | No | Create account |
+| `POST` | `/api/auth/login` | No | Log in |
+| `GET` | `/api/auth/me` | Yes | Current user |
+| `GET` | `/api/faqs` | No | List FAQs (`?search`, `?category`, `?sort`) |
+| `POST` | `/api/faqs/:id/vote` | No | Vote helpful / not helpful |
+| `GET` | `/api/questions` | No | List community questions |
+| `POST` | `/api/questions` | Yes | Create question (+2 pts) |
+| `GET` | `/api/answers/:questionId` | No | List answers |
+| `POST` | `/api/answers` | Yes | Submit answer (+5 pts) |
+| `PATCH` | `/api/answers/:id/status` | No | Approve answer (+15 pts to author) |
+| `POST` | `/api/answers/:id/upvote` | Yes | Toggle upvote (+10 pts to author) |
+| `GET` | `/api/suggest?q=` | No | AI-suggested answer from FAQ data |
+| `GET` | `/api/users/leaderboard` | No | Top contributors by points |
+| `GET` | `/api/health` | No | Health check |
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `MongoDB connection error` | Ensure MongoDB is running; check `MONGO_URI` in `server/.env` |
+| `Port 5000 already in use` | Change `PORT` in `server/.env` and update Vite proxy in `client/vite.config.js` |
+| `Port 3000 already in use` | Change `server.port` in `client/vite.config.js` |
+| `401` when posting questions | Log in first — auth token is required |
+| Empty FAQ page | Run `npm run seed` to populate sample data |
+| AI suggestion returns nothing | The seeded FAQs need to match some keywords; try questions about eligibility, stipend, certificates, etc. |
+| `npm install` fails | Use Node.js v18+; delete `node_modules` folders and retry |
+
+---
+
+## Publishing to GitHub
+
+When you are ready to push this project:
+
+```bash
+git init
+git add .
+git status # verify .env and node_modules are NOT listed
+git commit -m "Initial commit: CrowdFAQ MERN app"
+git branch -M main
+git remote add origin https://github.com/Just-Here-TO-Code/cs-faq.git
+git push -u origin main
+```
+
+> **Never commit** `server/.env` — it is listed in `.gitignore`. Only `server/.env.example` is tracked.
+
+---
+
+## Environment & Security Notes
+
+- `server/.env` is gitignored; each developer copies from `.env.example`
+- Use a strong, unique `JWT_SECRET` in production
+- For production deployment, build the client (`npm run build`) and serve `client/dist/` behind a reverse proxy alongside the API
+
+---
+
+## License
+
+This project is provided as-is for learning and portfolio use.
+
+---
+
+## See Also
+
+- [`PRODUCT.md`](./PRODUCT.md) — full product specification, architecture, API reference, and feature catalogue
diff --git a/client/index.html b/client/index.html
new file mode 100644
index 0000000..b89d2b1
--- /dev/null
+++ b/client/index.html
@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+ <meta charset="UTF-8" />
+ <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <meta name="description"
+ content="CrowdFAQ — A community-driven platform to ask questions and share knowledge together." />
+ <title>CrowdFAQ — Community Knowledge Base
+
+
+
+
+
+
+
+
+
+
+
+