docs: OpenAPI 3.0 spec with Mintlify documentation site

docs/authentication.mdx

@@ -0,0 +1,37 @@
+---
+title: Authentication
+description: 'How to authenticate with the Volvox Bot API'
+---
+
+# Authentication
+
+The API supports two authentication methods:
+
+## API Key
+
+Pass your API secret in the `x-api-secret` header:
+
+```bash
+curl -H "x-api-secret: YOUR_SECRET" https://your-domain.com/api/v1/health
+```
+
+Set via the `BOT_API_SECRET` environment variable.
+
+## OAuth2 Session (Bearer JWT)
+
+The web dashboard uses Discord OAuth2:
+
+1. User clicks "Login with Discord"
+2. Discord redirects to `/api/v1/auth/discord/callback` with an authorization code
+3. Server exchanges code for tokens and returns a signed JWT
+4. Subsequent requests must include the `Authorization: Bearer <jwt>` header
+
+## Public Endpoints
+
+These endpoints require no authentication:
+
+- `GET /health` — Basic health check
+- `GET /community/{guildId}/leaderboard` — Public leaderboard
+- `GET /community/{guildId}/showcases` — Public showcases
+- `GET /community/{guildId}/stats` — Public server stats
+- `GET /community/{guildId}/profile/{userId}` — Public user profile

docs/introduction.mdx

@@ -0,0 +1,35 @@
+---
+title: Introduction
+description: 'Volvox Bot API documentation'
+---
+
+# Volvox Bot API
+
+The Volvox Bot REST API powers the web dashboard and provides programmatic access to guild management, moderation, analytics, AI conversations, and community features.
+
+## Base URL
+
+```
+https://your-domain.com/api/v1
+```
+
+> **Deployment note:** `your-domain.com` is a placeholder. Replace it with your production API domain before publishing these docs.
+
+## Features
+
+- **Guild Management** — Server settings, analytics, member management
+- **Moderation** — Cases, warnings, bans, timeouts
+- **AI Conversations** — Chat history, flagging, search
+- **Community** — Leaderboards, showcases, public profiles
+- **Tickets** — Support ticket system
+- **Config** — Bot configuration CRUD
+
+## Rate Limiting
+
+All endpoints return rate limit headers:
+
+| Header | Description |
+|--------|-------------|
+| `X-RateLimit-Limit` | Max requests per window |
+| `X-RateLimit-Remaining` | Requests remaining |
+| `X-RateLimit-Reset` | Unix timestamp when window resets |

docs/mint.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://mintlify.com/schema.json",
+  "name": "Volvox Bot",
+  "colors": {
+    "primary": "#22c55e",
+    "light": "#4ade80",
+    "dark": "#16a34a",
+    "anchors": {
+      "from": "#22c55e",
+      "to": "#16a34a"
+    }
+  },
+  "navigation": [
+    {
+      "group": "Getting Started",
+      "pages": [
+        "introduction",
+        "authentication"
+      ]
+    },
+    {
+      "group": "API Reference",
+      "pages": [
+        {
+          "group": "Health",
+          "icon": "heart-pulse",
+          "pages": [
+            "api-reference/health/get-health"
+          ]
+        },
+        {
+          "group": "Auth",
+          "icon": "key",
+          "pages": [
+            "api-reference/auth/callback",
+            "api-reference/auth/session",
+            "api-reference/auth/logout"
+          ]
+        },
+        {
+          "group": "Config",
+          "icon": "gear",
+          "pages": [
+            "api-reference/config/get-config",
+            "api-reference/config/update-config"
+          ]
+        },
+        {
+          "group": "Guilds",
+          "icon": "server",
+          "pages": [
+            "api-reference/guilds/list-guilds",
+            "api-reference/guilds/get-guild",
+            "api-reference/guilds/list-channels",
+            "api-reference/guilds/list-roles",
+            "api-reference/guilds/get-config",
+            "api-reference/guilds/update-config",
+            "api-reference/guilds/stats",
+            "api-reference/guilds/analytics",
+            "api-reference/guilds/moderation-cases",
+            "api-reference/guilds/actions"
+          ]
+        },
+        {
+          "group": "Members",
+          "icon": "users",
+          "pages": [
+            "api-reference/members/list-members",
+            "api-reference/members/export-members",
+            "api-reference/members/get-member",
+            "api-reference/members/member-cases",
+            "api-reference/members/adjust-member-xp"
+          ]
+        },
+        {
+          "group": "Moderation",
+          "icon": "shield",
+          "pages": [
+            "api-reference/moderation/list-cases",
+            "api-reference/moderation/get-case",
+            "api-reference/moderation/stats",
+            "api-reference/moderation/user-history"
+          ]
+        },
+        {
+          "group": "Conversations",
+          "icon": "message",
+          "pages": [
+            "api-reference/conversations/list",
+            "api-reference/conversations/analytics",
+            "api-reference/conversations/flagged",
+            "api-reference/conversations/get-detail",
+            "api-reference/conversations/flag-message"
+          ]
+        },
+        {
+          "group": "Tickets",
+          "icon": "ticket",
+          "pages": [
+            "api-reference/tickets/stats",
+            "api-reference/tickets/get-ticket",
+            "api-reference/tickets/list-tickets"
+          ]
+        },
+        {
+          "group": "Community",
+          "icon": "people-group",
+          "pages": [
+            "api-reference/community/leaderboard",
+            "api-reference/community/showcases",
+            "api-reference/community/stats"
+          ]
+        },
+        {
+          "group": "Webhooks",
+          "icon": "webhook",
+          "pages": [
+            "api-reference/webhooks/config-update"
+          ]
+        }
+      ]
+    }
+  ],
+  "openapi": "openapi.json",
+  "api": {
+    "baseUrl": "/api/v1"
+  },
+  "footerSocials": {
+    "github": "https://github.com/VolvoxLLC/volvox-bot",
+    "discord": "https://discord.gg/volvox"
+  },
+  "logo": {
+    "dark": "/logo/dark.svg",
+    "light": "/logo/light.svg"
+  },
+  "favicon": "/favicon.svg"
+}