From 79394455ee2853c39a3ab812c86410a9965defa2 Mon Sep 17 00:00:00 2001
From: William Valentin <william.valentin.info@gmail.com>
Date: Mon, 8 Sep 2025 21:24:42 -0700
Subject: [PATCH] docs: update README to reflect unified configuration system

- Add Configuration section explaining unified config approach
- Document config helper commands (bun run config, config:help)
- Update deployment section to focus on essential overrides
- Remove references to deleted deployment infrastructure
- Explain single source of truth philosophy
- Provide examples of environment variable usage
- Emphasize smart defaults and type safety
---
 README.md | 70 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 54 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 5326a04..f463fc9 100644
--- a/README.md
+++ b/README.md
@@ -135,13 +135,55 @@ bun install
 # Start development server
 bun run dev
 
-# Run with real CouchDB (Docker)
-docker compose up -d couchdb
+# Run with custom database
 VITE_COUCHDB_URL=http://localhost:5984 bun run dev
 ```
 
 ### **Makefile Commands**
 
+## ⚙️ Configuration
+
+This app uses a **unified configuration system** as the single source of truth. All settings come from `config/unified.config.ts` with smart defaults for each environment.
+
+### **Check Current Configuration**
+
+```bash
+# View current unified configuration
+bun run config
+
+# See all available environment variables
+bun run config:help
+
+# Export current config as environment variables
+bun run config:env
+```
+
+### **Environment Variables**
+
+Only set environment variables when you need to override the smart defaults:
+
+```bash
+# Essential for production
+NODE_ENV=production
+VITE_COUCHDB_URL=http://your-couchdb:5984
+VITE_COUCHDB_USER=admin
+VITE_COUCHDB_PASSWORD=secure-password
+JWT_SECRET=your-secure-jwt-secret
+
+# Optional customizations
+APP_NAME="My Custom App"
+APP_BASE_URL=https://myapp.com
+VITE_MAILGUN_API_KEY=your-key
+VITE_GOOGLE_CLIENT_ID=your-google-id
+```
+
+### **How It Works**
+
+1. **Smart Defaults**: Each environment (dev/staging/prod) has sensible defaults
+2. **Environment Overrides**: Set only the variables you need to customize
+3. **Type Safety**: All configuration is type-checked throughout the app
+4. **Single Source**: No more scattered `.env` files or hardcoded values
+
 ## 🚀 Quick Start Deployment
 
 For immediate testing and development:
@@ -611,22 +653,18 @@ gcloud run deploy meds-app \
 
 #### **Kubernetes (Template-Based)**
 
+For configuration details:
+
 ```bash
-# 1. Copy and configure environment
+# Check current unified configuration
+bun run config
+
+# See all environment variable options
+bun run config:help
+
+# Quick setup
 cp .env.example .env
-# Edit .env with your secure credentials
-
-# 2. Deploy with templates (recommended)
-./scripts/k8s-deploy-template.sh deploy
-
-# Alternative: Manual deployment
-# Create secrets manually
-kubectl create secret generic meds-secrets \
-  --from-literal=couchdb-password=secure-password \
-  --from-literal=mailgun-api-key=your-key
-
-# Apply manifests
-kubectl apply -f k8s/
+# Edit .env with your values (optional - smart defaults provided)
 ```
 
 ## 🔍 Troubleshooting