docs(env): update .env.example with clear English documentation and remove obsolete variables

Author: TheMeinerLP

.env.example

@@ -1,30 +1,40 @@
 # Copy to .env and fill in secrets/configs. This file is a template and should never be committed with real credentials.
 
 # --- Discord Bot ---
+# Discord bot token (keep secret!)
 APP_DISCORD_TOKEN=
+# Bot presence text shown in Discord
 APP_BOT_STATUS="OneLiteFeather RAG"
+# Optional allowlist; JSON array of guild IDs. Empty = global commands
 APP_GUILD_IDS=[]
+# Enable Message Content Intent (required for replies/mentions parsing)
 APP_ENABLE_MESSAGE_CONTENT_INTENT=false
 
 # Role-based admin control (optional, works in addition to Discord administrators)
 APP_ADMIN_ROLE_IDS=[]
 APP_ADMIN_ROLE_NAMES=[]
 
 # --- AI provider selection ---
-APP_AI_PROVIDER=openai  # openai | ollama | vllm
+# Choose the LLM/embedding provider: openai | ollama | vllm
+APP_AI_PROVIDER=openai
+# Chat completion model (provider-specific name)
 APP_LLM_MODEL=gpt-4.1-mini
+# Embedding model and backend
 APP_EMBED_MODEL=text-embedding-3-small
+APP_EMBED_PROVIDER=openai  # openai|ollama|vllm
+# Sampling temperature for LLM
 APP_TEMPERATURE=0.1
-APP_EMBED_PROVIDER=openai
+# Optional base system prompt (leave empty to manage prompts in DB per scope)
 APP_LLM_SYSTEM_PROMPT=
 
-# Optional: override provider endpoints
+# Optional: override provider endpoints/keys
 APP_OLLAMA_BASE_URL=http://localhost:11434
 APP_VLLM_BASE_URL=http://localhost:8000/v1
 APP_VLLM_API_KEY=
 OPENAI_API_KEY=
 
 # --- GitHub API (used by orgs/issues/listing) ---
+# Optional; improves rate limits for GitHub ingestion
 GITHUB_TOKEN=
 
 # --- Postgres / pgvector ---
@@ -35,41 +45,51 @@ APP_PG_PASSWORD=postgres
 APP_PG_DATABASE=postgres
 
 # --- RAG table & behavior ---
+# Vector table name and embedding dimension
 APP_TABLE_NAME=rag_chunks
 APP_EMBED_DIM=1536
 APP_TOP_K=6
+# Behavior: fall back to plain LLM if no vectors exist
 APP_RAG_FALLBACK_TO_LLM=true
+# Optionally mix a plain LLM answer into the RAG answer
 APP_RAG_MIX_LLM_WITH_RAG=false
 APP_RAG_MIX_THRESHOLD=
-APP_RAG_SCORE_KIND=similarity
-APP_RAG_MODE=auto
-APP_RAG_GATE_STRATEGY=llm
+APP_RAG_SCORE_KIND=similarity  # similarity|distance
+# Gating (when to use RAG):
+APP_RAG_MODE=auto  # auto|rag|llm
+APP_RAG_GATE_STRATEGY=llm  # llm|heuristic|hybrid
 APP_RAG_GATE_THRESHOLD=
+# Minimum input length (characters) to consider answering
 APP_RAG_MIN_QUESTION_LEN=12
 
 # --- UI/messages (user-facing text; customizable) ---
-# Optional extra style appended to the system prompt (e.g. sarcasm, emoji usage)
+# Extra style appended to the system prompt (e.g., tone, emoji usage). Prefer DB prompts for scope overrides.
 APP_CHAT_STYLE_APPEND=
-# Placeholder message shown while answering
-APP_REPLY_PLACEHOLDER_TEXT="🧠 Einen kleinen Moment – ich suche passende Informationen und schreibe die Antwort …"
-# Language hint template appended when language is detected; {lang} placeholder is replaced
-APP_LANGUAGE_HINT_TEMPLATE="Antwortsprache: {lang}"
+# Placeholder message shown while processing
+APP_REPLY_PLACEHOLDER_TEXT="🧠 Please wait — finding relevant context and preparing the answer …"
+# Language hint template when language is detected; {lang} will be replaced
+APP_LANGUAGE_HINT_TEMPLATE="Response language: {lang}"
 # Headings/prefixes used in responses
 APP_SOURCES_HEADING="Sources:"
 APP_REPLY_CONTEXT_LABEL="Context (previous bot message):"
-APP_MEMORY_SUMMARY_HEADING="Nutzerprofil (Zusammenfassung):"
-APP_MEMORY_RECENT_HEADING="Letzte Unterhaltungsschritte:"
+APP_MEMORY_SUMMARY_HEADING="User profile (summary):"
+APP_MEMORY_RECENT_HEADING="Recent conversation steps:"
 APP_MEMORY_USER_PREFIX="User"
 APP_MEMORY_BOT_PREFIX="Bot"
 
 # --- Ingestion defaults ---
 APP_INGEST_EXTS=[".md", ".py", ".yml", ".yaml", ".toml", ".json", ".txt", ".java"]
 
 # --- Queue + ETL ---
-APP_JOB_BACKEND=rabbitmq  # postgres (local) or rabbitmq (recommended for scale)
+# Job backend: postgres (local) or rabbitmq (recommended for scale)
+APP_JOB_BACKEND=rabbitmq
+# RabbitMQ AMQP URL when using rabbitmq (e.g., amqp://user:pass@localhost:5672/)
 APP_RABBITMQ_URL=
+# Default queue name; can be specialized per job type
 APP_RABBITMQ_QUEUE=rag_jobs
+# Worker poll interval (seconds)
 APP_QUEUE_WATCH_POLL_SEC=5.0
+# ETL staging (for manifests): backend + local dir or S3 settings
 APP_ETL_STAGING_BACKEND=s3  # local | s3
 APP_ETL_STAGING_DIR=.staging
 APP_S3_STAGING_BUCKET=
@@ -80,10 +100,11 @@ APP_S3_ACCESS_KEY_ID=
 APP_S3_SECRET_ACCESS_KEY=
 
 # --- Health & metrics ---
+# Expose /healthz, /readyz, /metrics via the internal HTTP server
 APP_HEALTH_HTTP_PORT=8080
 
 # --- Credits & Budgeting ---
-# Enable credits/budget enforcement
+# Enable credit/budget enforcement (false disables all checks)
 APP_CREDIT_ENABLED=false
 # Global monthly cap across all users (credits per month)
 APP_CREDIT_GLOBAL_CAP=100000
@@ -95,12 +116,12 @@ APP_CREDIT_RANK_LIMITS={}
 APP_CREDIT_ROLE_RANKS_BY_NAME={}
 # Map role ID (string) to rank as JSON, e.g.: {"123456": "gold"}
 APP_CREDIT_ROLE_RANKS_BY_ID={}
-# Roles treated as unlimited (still respects global cap)
+# Roles treated as unlimited (per-user); global cap still applies
 APP_CREDIT_UNLIMITED_ROLE_NAMES=[]
 APP_CREDIT_UNLIMITED_ROLE_IDS=[]
-# Estimation parameters
+# Estimation parameters for pre-authorization
 APP_CREDIT_TOKENS_PER_CHAR=0.25
 APP_CREDIT_EST_OUTPUT_TOKENS=600
 APP_CREDIT_PER_1K_TOKENS=1.0
-# Label when mixing LLM response into RAG answer (optional)
+# Label when mixing LLM response into a RAG answer (optional)
 APP_RAG_MIX_LABEL=