docs: Update environment configuration and README with comprehensive setup guide

- Enhance `.env.example` with more detailed and organized configuration options
- Refactor README to provide clearer setup instructions and system architecture overview
- Add new `scripts/setup-env.sh` for flexible environment configuration management
- Update `docs/configuration.md` with detailed environment loading strategy and best practices
- Improve documentation for speech features, client integration, and development workflows

.env.example

@@ -1,43 +1,15 @@
-# Home Assistant Configuration
-# The URL of your Home Assistant instance
-HASS_HOST=http://homeassistant.local:8123
-
-# Long-lived access token from Home Assistant
-# Generate from Profile -> Long-Lived Access Tokens
-HASS_TOKEN=your_long_lived_token
-
-# WebSocket URL for real-time updates
-HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
-
 # Server Configuration
-# Port for the MCP server (default: 3000)
-PORT=3000
-
-# Environment (development/production/test)
 NODE_ENV=development
-
-# Debug mode (true/false)
+PORT=3000
 DEBUG=false
-
-# Logging level (debug/info/warn/error)
 LOG_LEVEL=info
 
-# AI Configuration
-# Natural Language Processor type (claude/gpt4/custom)
-PROCESSOR_TYPE=claude
-
-# OpenAI API Key (required for GPT-4 analysis)
-OPENAI_API_KEY=your_openai_api_key
-
-# Rate Limiting
-# Requests per minute per IP for regular endpoints
-RATE_LIMIT_REGULAR=100
-
-# Requests per minute per IP for WebSocket connections
-RATE_LIMIT_WEBSOCKET=1000
+# Home Assistant Configuration
+HASS_HOST=http://homeassistant.local:8123
+HASS_TOKEN=your_long_lived_token
+HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
 
 # Security Configuration
-# JWT Configuration
 JWT_SECRET=your_jwt_secret_key_min_32_chars
 JWT_EXPIRY=86400000
 JWT_MAX_AGE=2592000000
@@ -46,11 +18,8 @@ JWT_ALGORITHM=HS256
 # Rate Limiting
 RATE_LIMIT_WINDOW=900000
 RATE_LIMIT_MAX_REQUESTS=100
-
-# Token Security
-TOKEN_MIN_LENGTH=32
-MAX_FAILED_ATTEMPTS=5
-LOCKOUT_DURATION=900000
+RATE_LIMIT_REGULAR=100
+RATE_LIMIT_WEBSOCKET=1000
 
 # CORS Configuration
 CORS_ORIGINS=http://localhost:3000,http://localhost:8123
@@ -60,17 +29,6 @@ CORS_EXPOSED_HEADERS=
 CORS_CREDENTIALS=true
 CORS_MAX_AGE=86400
 
-# Content Security Policy
-CSP_ENABLED=true
-CSP_REPORT_ONLY=false
-CSP_REPORT_URI=
-
-# SSL/TLS Configuration
-REQUIRE_HTTPS=true
-HSTS_MAX_AGE=31536000
-HSTS_INCLUDE_SUBDOMAINS=true
-HSTS_PRELOAD=true
-
 # Cookie Security
 COOKIE_SECRET=your_cookie_secret_key_min_32_chars
 COOKIE_SECURE=true
@@ -81,27 +39,12 @@ COOKIE_SAME_SITE=Strict
 MAX_REQUEST_SIZE=1048576
 MAX_REQUEST_FIELDS=1000
 
-# SSE Configuration
-SSE_MAX_CLIENTS=1000
-SSE_PING_INTERVAL=30000
-
-# Logging Configuration
-LOG_LEVEL=info
-LOG_DIR=logs
-LOG_MAX_SIZE=20m
-LOG_MAX_DAYS=14d
-LOG_COMPRESS=true
-LOG_REQUESTS=true
-
-# Version
-VERSION=0.1.0
-
-# Test Configuration
-# Only needed if running tests
-TEST_HASS_HOST=http://localhost:8123
-TEST_HASS_TOKEN=test_token
-TEST_HASS_SOCKET_URL=ws://localhost:8123/api/websocket
-TEST_PORT=3001
+# AI Configuration
+PROCESSOR_TYPE=claude
+OPENAI_API_KEY=your_openai_api_key
+OPENAI_MODEL=gpt-3.5-turbo
+MAX_RETRIES=3
+ANALYSIS_TIMEOUT=30000
 
 # Speech Features Configuration
 ENABLE_SPEECH_FEATURES=false
@@ -110,5 +53,30 @@ ENABLE_SPEECH_TO_TEXT=false
 WHISPER_MODEL_PATH=/models
 WHISPER_MODEL_TYPE=tiny
 
+# Audio Configuration
+NOISE_THRESHOLD=0.05
+MIN_SPEECH_DURATION=1.0
+SILENCE_DURATION=0.5
+SAMPLE_RATE=16000
+CHANNELS=1
+CHUNK_SIZE=1024
+PULSE_SERVER=unix:/run/user/1000/pulse/native
+
+# SSE Configuration
+SSE_MAX_CLIENTS=50
+SSE_RECONNECT_TIMEOUT=5000
+
+# Development Flags
+HOT_RELOAD=true
+
+# Test Configuration (only needed for running tests)
+TEST_HASS_HOST=http://localhost:8123
+TEST_HASS_TOKEN=test_token
+TEST_HASS_SOCKET_URL=ws://localhost:8123/api/websocket
+TEST_PORT=3001
+
+# Version
+VERSION=0.1.0
+
 # Advanced (Docker)
 COMPOSE_PROJECT_NAME=mcp