docs: improve .env.example documentation with detailed comments

- Add comprehensive header explaining the file purpose
- Group variables into required and optional sections
- Provide step-by-step instructions for obtaining Discord token
- Add examples for database URL and extensions
- Include security warnings for token handling
- Make all explanations beginner-friendly

Fixes #20

Author: Agent

.env.example

@@ -1,21 +1,105 @@
-# Get your bot token from: https://discord.com/developers/applications
+# ===========================================
+# Miku Discord Bot Configuration
+# ===========================================
+# This file contains all the environment variables needed to run Miku.
+# Copy this file to .env and fill in your actual values.
+# 
+# For detailed setup instructions, see:
+# - README.md: Basic bot setup
+# - CONTRIBUTING.md: Development guidelines
+
+# ===========================================
+# REQUIRED VARIABLES
+# ===========================================
+# The bot will NOT start without these!
+
+# DISCORD_TOKEN
+# Your Discord bot's authentication token. This is required for the bot to connect to Discord.
+# 
+# How to get one:
+# 1. Go to: https://discord.com/developers/applications
+# 2. Create a new application or select an existing one
+# 3. Navigate to "Bot" section in the left sidebar
+# 4. Click "Add Bot" if you haven't created one yet
+# 5. Click "Reset Token" to generate a new token
+# 6. Copy the token and paste it here
+# 
+# IMPORTANT: Keep this token secret! Never share it or commit it to GitHub.
+# If your token is leaked, reset it immediately in the Discord Developer Portal.
 DISCORD_TOKEN=your_bot_token_here
 
-# You can get a free PostgreSQL database from neon.tech, supabase.com, or render.com
-# Format (Postgres): postgresql+asyncpg://user:password@host:port/database
-# For local development, you might prefer to run postgres using Docker.
+# DATABASE_URL
+# The connection URL for your PostgreSQL database. Miku uses this to store user XP, levels, and settings.
+# 
+# Database providers (free tiers available):
+# - neon.tech: Free PostgreSQL with generous limits
+# - supabase.com: Free PostgreSQL with additional features
+# - render.com: Free PostgreSQL databases
+# 
+# URL Format: postgresql+asyncpg://username:password@host:port/database_name
+# Example: postgresql+asyncpg://miku_user:[email protected]:5432/miku_db
+# 
+# For local development:
+# - You can run PostgreSQL locally using Docker
+# - Or use SQLite by changing the URL format (not recommended for production)
 DATABASE_URL=postgresql+asyncpg://user:password@host:5432/database
 
-# Extensions that MUST load - The bot won't start without them (defaults to an empty list)
+# ===========================================
+# OPTIONAL VARIABLES
+# ===========================================
+# These have default values and can be customized if needed.
+
+# CORE_EXTENSIONS (default: [])
+# List of extensions that MUST be loaded. The bot will fail to start if any of these fail to load.
+# Extensions are Python modules that add features to the bot (e.g., leveling, moderation, music).
+# 
+# Format: JSON array of extension names
+# Example: ["leveling", "admin"] - Both extensions must load successfully
+# 
+# Leave empty [] if you want all extensions to be optional.
 CORE_EXTENSIONS=[]
 
-# Extensions that can but don't have to load (defaults to an empty list)
-# Any other extension not listed here (or in core extensions) won't be loaded, even if it is discovered by the bot.
+# ADDITIONAL_EXTENSIONS (default: [])
+# List of extensions that SHOULD load but won't crash the bot if they fail.
+# Extensions not listed here (or in CORE_EXTENSIONS) won't be loaded at all.
+# 
+# This is useful for:
+# - Optional features you want but don't require
+# - Testing new extensions without breaking the bot
+# 
+# Format: JSON array of extension names
+# Example: ["music", "games", "fun"] - Nice-to-have features
 ADDITIONAL_EXTENSIONS=[]
 
-# The prefix to use for prefix commands (defaults to "&"" if not set)
+# COMMAND_PREFIX (default: "&")
+# The prefix character used for text commands (not slash commands).
+# 
+# Examples:
+# - COMMAND_PREFIX=& means users type "&rank" for the rank command
+# - COMMAND_PREFIX=! means users type "!rank"
+# - COMMAND_PREFIX=miku means users type "miku rank"
+# 
+# Note: Slash commands (/rank) work regardless of this setting.
+# Choose a prefix that doesn't conflict with other bots in your server.
 COMMAND_PREFIX=&
 
-# Optional: GitHub token for higher API rate limits (5000/hr vs 60/hr)
-# Get one at: https://github.com/settings/tokens (no scopes needed for public data)
+# ===========================================
+# OPTIONAL EXTERNAL SERVICES
+# ===========================================
+
+# GITHUB_TOKEN (optional)
+# A GitHub personal access token for accessing GitHub API with higher rate limits.
+# 
+# Without this: 60 requests per hour
+# With this: 5000 requests per hour
+# 
+# This is useful if Miku integrates with GitHub features (e.g., fetching repo info).
+# 
+# How to get one:
+# 1. Go to: https://github.com/settings/tokens
+# 2. Click "Generate new token (classic)"
+# 3. No scopes needed for public data access
+# 4. Copy the token and paste it here
+# 
+# Leave empty if you don't need GitHub integration.
 GITHUB_TOKEN=