refactor: simplify env configuration workflow

.gitignore

@@ -13,11 +13,13 @@ package-lock.json
 .env.production.local
 
 # Centralized config (keep .example files, ignore actual configs)
+config/local/.env
 config/local/.env.*
-!config/local/.env.*.example
+!config/local/.env.example
 config/local/flow-sources.yaml
+config/dev/.env
 config/dev/.env.*
-!config/dev/.env.*.example
+!config/dev/.env.example
 config/dev/flow-sources.yaml
 
 # IDE and Editors
@@ -73,12 +75,6 @@ config/dev/namespace-admins.txt
 helm/*/secrets-*.yaml
 !helm/*/secrets-*.yaml.example
 
-# Flow sources config (keep .example, ignore actual config)
-config/flow-sources.yaml
-
-# LangFlow env vars (API keys for global variables — keep .example)
-config/langflow.env
-
 # Local development overrides
 .local/
 

CLAUDE.md

@@ -42,7 +42,7 @@ make setup && make services-start && make db-seed && make dev
 - Deploy to prod: `make deploy-prod`
 
 **Troubleshooting:**
-- API not working? Check `/api/v1/utils/health-check` → Verify `config/local/.env.*` files → Check CORS settings
+- API not working? Check `/api/v1/utils/health-check` → Verify `config/local/.env` → Check CORS settings
 - Database issues? `make db-status` → `make db-logs` → `make db-shell`
 
 ## Project Structure
@@ -63,8 +63,8 @@ make setup && make services-start && make db-seed && make dev
 │   ├── vite.config.ts  # Vite configuration with /api proxy
 │   └── Dockerfile      # Frontend container (nginx-based)
 ├── config/              # Centralized configuration (source of truth)
-│   ├── local/          # Local development configs (.env.*.example)
-│   └── dev/            # Cluster deployment configs (.env.*.example)
+│   ├── local/          # Local development config (.env.example)
+│   └── dev/            # Cluster deployment config (.env.example)
 ├── k8s/                # Kubernetes/OpenShift manifests
 │   ├── base/          # Base kustomize resources
 │   └── overlays/      # Environment-specific overlays (dev/prod)
@@ -113,7 +113,7 @@ make setup && make services-start && make db-seed && make dev
 ### Local Development
 ```bash
 make setup             # Install all dependencies
-make env-setup         # Copy config/local/.env.*.example to service dirs
+make config-setup      # Copy config/local/.env.example to config/local/.env
 make dev              # Run both frontend and backend
 make dev-frontend     # Run React dev server (port 8080)
 make dev-backend      # Run FastAPI server (port 8000)
@@ -302,7 +302,7 @@ This application uses **OAuth2 Proxy** for authentication. See [docs/AUTHENTICAT
 
 - ❌ Missing CORS configuration → Add origins to `backend/app/core/config.py`
 - ❌ Not using Pydantic models for validation → **ALWAYS** define request/response schemas
-- ❌ Hardcoding URLs or sensitive values → Use environment variables (`config/local/.env.*` files for local dev)
+- ❌ Hardcoding URLs or sensitive values → Use environment variables (`config/local/.env` for local dev)
 - ❌ Wrong HTTP status codes → 400 (bad input) vs 404 (not found) vs 409 (conflict)
 
 ### Frontend (React/PatternFly)
@@ -321,13 +321,13 @@ This application uses **OAuth2 Proxy** for authentication. See [docs/AUTHENTICAT
 ### Git/Commits
 
 - ❌ Not following Conventional Commits → Use `feat:`, `fix:`, `refactor:`, etc.
-- ❌ Committing `.env` files with secrets → Use `config/local/.env.*.example` templates
+- ❌ Committing `.env` files with secrets → Use `config/local/.env.example` template
 
 ## Development Workflow
 
 ### Initial Setup
 1. Install dependencies: `make setup`
-2. Configure environment: `make env-setup` (copies from `config/local/`)
+2. Configure environment: `make config-setup` (copies from `config/local/.env.example`)
 3. Start all services: `make services-start`
 4. Seed test data: `make db-seed`
 5. Start development servers: `make dev`

Makefile

@@ -17,7 +17,7 @@ include makefiles/helm.mk
 include makefiles/test.mk
 
 .PHONY: help setup setup-frontend setup-backend dev dev-frontend dev-backend dev-2 dev-frontend-2 dev-backend-2
-.PHONY: env-setup sync-version bump-version show-version health-backend health-frontend
+.PHONY: config-setup config-reset env-setup sync-version bump-version show-version health-backend health-frontend
 .PHONY: clean clean-all fresh-start quick-start
 
 # Default target
@@ -66,36 +66,14 @@ dev-frontend-2: ## Run second frontend instance (port 8081)
 dev-backend-2: ## Run second backend instance (port 8001)
 	cd backend && uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8001
 
-# Environment Setup
-env-setup: ## Copy config example files for local development
-	@echo "Setting up environment files from config/local/..."
-	@for example in config/local/.env.*.example; do \
-		actual=$${example%.example}; \
-		if [ ! -f "$$actual" ]; then \
-			cp "$$example" "$$actual"; \
-			echo "  Created $$(basename $$actual)"; \
-		fi; \
-	done
-	@if [ ! -f config/local/flow-sources.yaml ]; then \
-		cp config/local/flow-sources.yaml.example config/local/flow-sources.yaml; \
-		echo "  Created flow-sources.yaml"; \
-	fi
-	@echo ""
-	@echo "Copying component configs..."
-	@if [ ! -f backend/.env ]; then \
-		cp config/local/.env.backend backend/.env 2>/dev/null || true; \
-		echo "  Created backend/.env"; \
-	fi
-	@if [ ! -f frontend/.env ]; then \
-		cp config/local/.env.frontend frontend/.env 2>/dev/null || true; \
-		echo "  Created frontend/.env"; \
-	fi
-	@echo ""
-	@echo "Config files are in config/local/. Edit them to configure:"
-	@echo "  .env.backend   - Database, OAuth, Langflow settings"
-	@echo "  .env.postgres  - Database credentials"
-	@echo "  .env.langflow  - LLM API keys for Langflow"
-	@echo "  .env.langfuse  - Langfuse service credentials"
+# Config Setup (local by default, use config-setup-dev for cluster)
+config-setup: ## Setup local config from examples
+	@./scripts/generate-config.sh local
+
+config-reset: ## Delete all local config (run config-setup after editing .env)
+	@./scripts/generate-config.sh reset local
+
+env-setup: config-setup ## Alias for config-setup
 
 # Version Management
 sync-version: ## Sync VERSION to pyproject.toml and package.json
@@ -128,7 +106,7 @@ clean: ## Clean build artifacts and dependencies
 clean-all: clean ## Clean everything
 
 # Development Workflow
-fresh-start: clean setup env-setup ## Clean setup for new development
+fresh-start: clean setup config-setup ## Clean setup for new development
 	@echo "Fresh development environment ready!"
 
-quick-start: setup env-setup dev ## Quick start for development
+quick-start: setup config-setup dev ## Quick start for development

README.md

@@ -59,7 +59,7 @@ A platform for hosting and orchestrating multiple LangFlow workflows, built on R
 git clone https://github.com/cfchase/multi-agent-platform
 cd multi-agent-platform
 make setup
-make env-setup              # Copy config from config/local/
+make config-setup           # Copy config from config/local/
 make services-start
 make db-seed  # optional: load sample data
 make dev
@@ -79,7 +79,7 @@ OAuth is enabled by default. Access app at <http://localhost:4180>.
 - **No OAuth credentials**: Uses mock OAuth server (any username/password works)
 - **With OAuth credentials**: Uses configured provider (Google, GitHub, Keycloak)
 
-Configure OAuth in `config/local/.env.oauth-proxy` (local) or `config/dev/.env.oauth-proxy` (cluster):
+Configure OAuth in `config/local/.env` (local) or `config/dev/.env` (cluster):
 
 ```bash
 OAUTH_CLIENT_ID=your-client-id
@@ -98,16 +98,16 @@ For setup details, see [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md).
 # 1. Login to your cluster
 oc login --server=https://your-cluster
 
-# 2. Set up deployment config (creates config/dev/ files, auto-generates secrets)
-make config-setup
+# 2. Set up deployment config (creates config/dev/ files)
+make config-setup-cluster
 
-# 3. Configure OAuth credentials (required)
-#    Edit config/dev/.env.oauth-proxy with your Google OAuth Client ID and Secret
-#    Edit config/dev/.env.backend with the same OAuth credentials
+# 3. Configure credentials (required)
+#    Edit config/dev/.env with OAuth, LLM keys, etc.
 #    Edit config/dev/allowed-emails.txt with authorized email addresses
 #    Edit config/dev/namespace-admins.txt with OpenShift usernames for admin access
 
-# 4. Deploy everything
+# 4. Generate deployment artifacts and deploy
+make config-generate
 make deploy
 
 # 5. Verify deployment

backend/CLAUDE.md

@@ -571,7 +571,7 @@ class Settings(BaseSettings):
 settings = Settings()
 ```
 
-**IMPORTANT**: Never commit `.env` files with secrets! Config source of truth is in `config/local/.env.backend.example`. Copy to `config/local/.env.backend` and then to `backend/.env` via `make env-setup`. Templates are in `config/local/.env.*.example`.
+**IMPORTANT**: Never commit `.env` files with secrets! Config source of truth is `config/local/.env.example`. Run `make config-setup` to copy it to `config/local/.env` and `backend/.env`.
 
 ## Additional Resources
 

config/dev/.env.example

@@ -0,0 +1,63 @@
+# Multi-Agent Platform - Cluster (Dev) Configuration
+# Copy to .env and fill in your values.
+# Run: make config-setup-cluster  (then: make config-generate to create deployment artifacts)
+#
+# Auto-generated values (secrets, internal URLs) go directly into deployment
+# artifacts (k8s overlays, Helm secrets). This file is NEVER mutated by scripts.
+
+# ========================================
+# OAuth (REQUIRED for cluster deployment)
+# ========================================
+# Google OAuth Setup:
+#   1. Go to https://console.cloud.google.com/apis/credentials
+#   2. Create OAuth 2.0 Client ID (Web application)
+#   3. Add redirect URI: https://<app-route>/oauth2/callback
+#   4. Copy Client ID and Client Secret below
+# See docs/AUTHENTICATION.md for detailed walkthrough
+OAUTH_CLIENT_ID=your-client-id
+OAUTH_CLIENT_SECRET=your-client-secret
+# OAUTH_ISSUER_URL=         # Set for OIDC providers (Keycloak, Okta)
+
+# ========================================
+# LLM API Keys (set at least one)
+# ========================================
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+# GEMINI_API_KEY=
+
+# ========================================
+# Google Drive Integration (optional)
+# ========================================
+# Uses a DIFFERENT redirect URI than the OAuth2 Proxy login.
+# Add redirect URI: https://<app-route>/api/v1/integrations/oauth/callback/google_drive
+# Can use the same client ID as OAuth above if both redirect URIs are added.
+# GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
+# GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+# ========================================
+# Langfuse Admin User (optional)
+# ========================================
+# Set to real email/name for the Langfuse web UI admin login.
+# Password is auto-generated if not set. Also used for Langflow superuser.
+# LANGFUSE_INIT_USER_EMAIL=admin@your-domain.com
+# LANGFUSE_INIT_USER_NAME=Admin
+# LANGFUSE_INIT_USER_PASSWORD=
+
+# ========================================
+# Langflow Configuration (optional)
+# ========================================
+# LANGFLOW_DEFAULT_FLOW=My Chat Flow
+
+# ========================================
+# Database Password (optional - auto-generated if not set)
+# ========================================
+# Set this only if you need a specific password.
+# If left empty or "changethis", generate-config.sh auto-generates one.
+# POSTGRES_PASSWORD=
+
+# ========================================
+# Web Search APIs (optional)
+# ========================================
+# TAVILY_API_KEY=
+# GOOGLE_API_KEY=
+# GOOGLE_CSE_ID=