CLAUDE: Add .env.example with comprehensive configuration guide

- Documents all environment variables
- Includes SQLite and PostgreSQL configurations
- Provides example configurations for different environments
- Adds security notes and best practices
- Includes migration notes for PostgreSQL transition

.env.example

@@ -0,0 +1,175 @@
+# Paper Dynasty Database API - Environment Configuration
+# Copy this file to .env and update with your actual values
+# DO NOT commit .env to version control!
+
+# =============================================================================
+# DATABASE CONFIGURATION
+# =============================================================================
+
+# Database type: 'sqlite' or 'postgresql'
+# Default: sqlite
+DATABASE_TYPE=sqlite
+
+# -----------------------------------------------------------------------------
+# SQLite Configuration (used when DATABASE_TYPE=sqlite)
+# -----------------------------------------------------------------------------
+# SQLite uses the file: storage/pd_master.db
+# No additional configuration needed for SQLite
+
+# -----------------------------------------------------------------------------
+# PostgreSQL Configuration (used when DATABASE_TYPE=postgresql)
+# -----------------------------------------------------------------------------
+
+# PostgreSQL host (hostname or IP address)
+# Default: localhost
+POSTGRES_HOST=localhost
+
+# PostgreSQL port
+# Default: 5432
+POSTGRES_PORT=5432
+
+# PostgreSQL database name
+# Default: pd_master
+POSTGRES_DB=pd_master
+
+# PostgreSQL username
+# Default: pd_admin
+POSTGRES_USER=pd_admin
+
+# PostgreSQL password (REQUIRED for PostgreSQL, no default)
+POSTGRES_PASSWORD=your_secure_password_here
+
+# =============================================================================
+# APPLICATION CONFIGURATION
+# =============================================================================
+
+# Logging level: 'INFO' or 'WARN'
+# Default: WARN
+# Set to INFO for detailed logging during development
+LOG_LEVEL=WARN
+
+# API authentication token
+# Used for Bearer token authentication on protected endpoints
+# Generate a secure random token for production
+API_TOKEN=your_api_token_here
+
+# Include private endpoints in OpenAPI schema
+# Set to any non-empty value to include private endpoints in /docs
+# Leave empty or omit to exclude private endpoints
+# PRIVATE_IN_SCHEMA=true
+
+# Testing mode
+# Set to 'False' to use development database URL (pddev.manticorum.com)
+# Leave unset or set to any other value for production
+# TESTING=False
+
+# =============================================================================
+# EXAMPLE CONFIGURATIONS
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Example 1: Local Development with SQLite (Default)
+# -----------------------------------------------------------------------------
+# DATABASE_TYPE=sqlite
+# LOG_LEVEL=INFO
+# API_TOKEN=dev_token_12345
+
+# -----------------------------------------------------------------------------
+# Example 2: Local Development with PostgreSQL
+# -----------------------------------------------------------------------------
+# DATABASE_TYPE=postgresql
+# POSTGRES_HOST=localhost
+# POSTGRES_PORT=5432
+# POSTGRES_DB=pd_master_dev
+# POSTGRES_USER=pd_admin
+# POSTGRES_PASSWORD=dev_password_123
+# LOG_LEVEL=INFO
+# API_TOKEN=dev_token_12345
+
+# -----------------------------------------------------------------------------
+# Example 3: Production with PostgreSQL
+# -----------------------------------------------------------------------------
+# DATABASE_TYPE=postgresql
+# POSTGRES_HOST=db.example.com
+# POSTGRES_PORT=5432
+# POSTGRES_DB=pd_master_prod
+# POSTGRES_USER=pd_prod_user
+# POSTGRES_PASSWORD=strong_random_password_here
+# LOG_LEVEL=WARN
+# API_TOKEN=prod_secure_token_here
+
+# -----------------------------------------------------------------------------
+# Example 4: Docker Development with PostgreSQL
+# -----------------------------------------------------------------------------
+# DATABASE_TYPE=postgresql
+# POSTGRES_HOST=postgres  # Docker service name
+# POSTGRES_PORT=5432
+# POSTGRES_DB=pd_master
+# POSTGRES_USER=pd_admin
+# POSTGRES_PASSWORD=docker_dev_password
+# LOG_LEVEL=INFO
+# API_TOKEN=docker_dev_token
+
+# =============================================================================
+# SECURITY NOTES
+# =============================================================================
+#
+# 1. NEVER commit .env files to version control
+#    - .env is already in .gitignore
+#    - Only commit .env.example (this file)
+#
+# 2. Use strong passwords in production
+#    - Generate random passwords: openssl rand -base64 32
+#    - Minimum 20 characters for PostgreSQL password
+#
+# 3. Rotate API tokens regularly
+#    - Generate secure tokens: python -c "import secrets; print(secrets.token_urlsafe(32))"
+#
+# 4. Restrict database access
+#    - Use firewall rules to limit PostgreSQL access
+#    - Create separate database users for different environments
+#    - Grant only necessary privileges
+#
+# 5. Use environment-specific configurations
+#    - Development: Relaxed settings, verbose logging
+#    - Staging: Production-like settings, moderate logging
+#    - Production: Strict settings, minimal logging
+#
+# =============================================================================
+# MIGRATION NOTES
+# =============================================================================
+#
+# When migrating from SQLite to PostgreSQL:
+#
+# 1. Keep SQLite running during migration
+#    - Set DATABASE_TYPE=sqlite
+#    - Application continues to work normally
+#
+# 2. Set up PostgreSQL
+#    - Install PostgreSQL server
+#    - Create database and user
+#    - Grant privileges
+#
+# 3. Test PostgreSQL connection
+#    - Set DATABASE_TYPE=postgresql
+#    - Set POSTGRES_* variables
+#    - Test: python -c "from app.db_engine import db; db.connect(); print('✓ Connected'); db.close()"
+#
+# 4. Run data migration script
+#    - Use scripts/migrate_sqlite_to_postgres.py
+#    - Verify data integrity
+#    - Compare record counts
+#
+# 5. Switch to PostgreSQL
+#    - Update .env: DATABASE_TYPE=postgresql
+#    - Restart application
+#    - Monitor logs for errors
+#
+# 6. Rollback plan (if needed)
+#    - Update .env: DATABASE_TYPE=sqlite
+#    - Restart application
+#    - SQLite backup: storage/pd_master_backup_YYYYMMDD.db
+#
+# See POSTGRES_MIGRATION_PLAN.md for detailed migration instructions
+#
+# =============================================================================