rebase

.env.example

@@ -1,38 +1,62 @@
+# ============================================================
+# AI-RPG environment configuration
+# Copy to .env and edit before running `docker compose up`.
+# ============================================================
+
 # === Database ===
 POSTGRES_USER=airpg
 POSTGRES_PASSWORD=airpg
 POSTGRES_DB=airpg
-DATABASE_URL=postgresql+asyncpg://airpg:airpg@db:5432/airpg
-DATABASE_URL_SYNC=postgresql+psycopg2://airpg:airpg@db:5432/airpg
+# Used by backend when running OUTSIDE docker (local dev). Inside docker-compose
+# this is overridden in docker-compose.yml to point at the `db` service.
+DATABASE_URL=postgresql+asyncpg://airpg:airpg@localhost:5432/airpg
+DATABASE_URL_SYNC=postgresql+psycopg2://airpg:airpg@localhost:5432/airpg
 
 # === Qdrant ===
-QDRANT_URL=http://qdrant:6333
+QDRANT_URL=http://localhost:6333
 QDRANT_API_KEY=
 
-# === LLM ===
+# === LLM (OpenAI-compatible) ===
+# Examples:
+#   OpenAI:       https://api.openai.com/v1
+#   Ollama (host): http://host.docker.internal:11434/v1   ← for docker
+#   Ollama (local): http://localhost:11434/v1             ← for non-docker dev
+#   vLLM:         http://localhost:8000/v1
+# Leave empty to use MockLlmClient (replay-based, for dev/tests).
 LLM_API_URL=http://host.docker.internal:11434/v1
 LLM_API_KEY=
 LLM_MODEL=qwen2.5-7b-instruct
 LLM_TIMEOUT_SECONDS=60
 
 # === Embeddings ===
+# Provider: "offline_hash" (deterministic, dev-only, no HTTP) or "openai"
 EMBEDDINGS_PROVIDER=offline_hash
+# If provider=openai and these are empty, falls back to LLM_API_URL / LLM_API_KEY
 EMBEDDINGS_API_URL=
 EMBEDDINGS_API_KEY=
 EMBEDDINGS_MODEL=text-embedding-3-small
+# For offline_hash: 256. For openai text-embedding-3-small: 1536.
+# Use admin "Probe dimension" button to auto-detect.
 EMBEDDINGS_DIMENSION=256
 
 # === Application ===
-SECRET_KEY=change-me-in-production-32-bytes-long-min
+# Generate with: python -c "import secrets; print(secrets.token_urlsafe(48))"
+SECRET_KEY=change-me-to-a-random-32-byte-string-min
 DEBUG=false
 LOG_LEVEL=INFO
-CORS_ORIGINS=http://localhost,http://localhost:5173
+# Comma-separated list of allowed CORS origins (or * for any)
+CORS_ORIGINS=http://localhost:8080,http://localhost:5173,http://localhost
 
 # === Admin setup ===
+# Leave empty to auto-generate on first startup (will be printed in backend logs).
+# Or set explicitly to control the URL: /register/admin?token=<ADMIN_SETUP_TOKEN>
 ADMIN_SETUP_TOKEN=
 
 # === Storage ===
 DATA_DIR=/app/data
 
-# === Frontend (Vite dev) ===
-VITE_API_BASE_URL=http://localhost/api
+# === Frontend (Vite — ONLY used by `npm run dev`, ignored by docker build) ===
+# The docker build bakes "/api" (relative) into the bundle so the browser
+# uses the same origin + nginx proxies /api → backend:8000.
+# For local `npm run dev` (outside docker), set this to the backend URL.
+VITE_API_BASE_URL=http://localhost:8000/api