diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..2ae2d0e
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,54 @@
+# Paper Dynasty Discord Bot - Environment Configuration
+# Copy this file to .env and fill in your actual values.
+# DO NOT commit .env to version control!
+
+# =============================================================================
+# BOT CONFIGURATION
+# =============================================================================
+
+# Discord bot token (from Discord Developer Portal)
+BOT_TOKEN=your-discord-bot-token-here
+
+# Discord server (guild) ID
+GUILD_ID=your-guild-id-here
+
+# Channel ID for scoreboard messages
+SCOREBOARD_CHANNEL=your-scoreboard-channel-id-here
+
+# =============================================================================
+# API CONFIGURATION
+# =============================================================================
+
+# Paper Dynasty API authentication token
+API_TOKEN=your-api-token-here
+
+# Target database environment: 'dev' or 'prod'
+# Default: dev
+DATABASE=dev
+
+# =============================================================================
+# APPLICATION CONFIGURATION
+# =============================================================================
+
+# Logging level: DEBUG, INFO, WARNING, ERROR
+# Default: INFO
+LOG_LEVEL=INFO
+
+# Python hash seed (set for reproducibility in tests)
+PYTHONHASHSEED=0
+
+# =============================================================================
+# DATABASE CONFIGURATION (PostgreSQL — used by gameplay_models.py)
+# =============================================================================
+
+DB_USERNAME=your_db_username
+DB_PASSWORD=your_db_password
+DB_URL=localhost
+DB_NAME=postgres
+
+# =============================================================================
+# WEBHOOKS
+# =============================================================================
+
+# Discord webhook URL for restart notifications
+RESTART_WEBHOOK_URL=https://discord.com/api/webhooks/your-webhook-id/your-webhook-token