gamification

# Gamification & XP System

Turn productivity into a game with XP, levels, badges, streaks, and achievements. Every completed task, habit, and goal milestone earns XP toward leveling up.

## ClawdBot Integration

This skill is designed for **ClawdBot** - it provides the prompt interface for ClawdBot's gamification API server which stores data in Supabase.

**Architecture:**
```
User → ClawdBot Gateway → ClawdBot API Server → Supabase (Postgres)
                         (Railway)              (user_gamification, xp_transactions tables)
```

The backend implementation lives in `api-server/src/routes/gamification.ts` and `api-server/src/lib/xp-engine.ts`.

## Features

- **XP System**: Earn XP for habits, tasks, and goal milestones
- **Leveling**: Level up with formula `XP = 50 * (level^2)`
- **Streak Bonuses**: Up to 2.0x multiplier for consistent habits
- **Badges**: Earn badges for achievements and milestones
- **Leaderboard**: Compare progress (multi-user support)
- **Accountability**: Track commitment and earn-back system

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SUPABASE_URL` | Yes | Supabase project URL |
| `SUPABASE_SERVICE_KEY` | Yes | Supabase service role key |

## API Endpoints

All endpoints are relative to the ClawdBot API server (`{CLAWDBOT_API_URL}/api/gamification/`).

### Get User Stats
```
GET /api/gamification/stats/:userId
```

Response:
```json
{
  "totalXp": 2450,
  "currentLevel": 7,
  "weeklyXp": 350,
  "monthlyXp": 1200,
  "progress": {
    "xpInLevel": 150,
    "xpNeeded": 450,
    "percent": 33
  },
  "accountability": {
    "balance": 50,
    "totalSlashed": 10,
    "totalEarnedBack": 60
  }
}
```

### Get Recent Transactions
```
GET /api/gamification/transactions/:userId?limit=20
```

### Get User Badges
```
GET /api/gamification/badges/:userId
```

### Award XP (Internal)
```
POST /api/gamification/award
{
  "userId": "302137836",
  "amount": 50,
  "source": "habit",
  "sourc...