feat(#swarm): Add Docker Swarm deployment with AI provider configuration

- Add setup-wizard.sh for interactive configuration
- Add docker-compose.swarm.yml optimized for swarm deployment
- Make CLAUDE_API_KEY optional based on AI_PROVIDER setting
- Support multiple AI providers: Ollama, Claude API, OpenAI
- Add BETTER_AUTH_SECRET to .env.example
- Update deploy-swarm.sh to validate AI provider config
- Add comprehensive documentation (DOCKER-SWARM.md, SWARM-QUICKREF.md)

Changes:
- AI_PROVIDER env var controls which AI backend to use
- Ollama is default (no API key required)
- Claude API and OpenAI require respective API keys
- Deployment script validates based on selected provider
- Removed Authentik services from swarm compose (using external)
- Configured for upstream Traefik integration

deploy-swarm.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+set -euo pipefail
+
+# Mosaic Stack - Docker Swarm Deployment Script
+# Usage: ./deploy-swarm.sh [stack-name]
+
+STACK_NAME="${1:-mosaic}"
+COMPOSE_FILE="docker-compose.swarm.yml"
+
+echo "🚀 Deploying Mosaic Stack to Docker Swarm..."
+echo "Stack name: $STACK_NAME"
+echo "Compose file: $COMPOSE_FILE"
+echo ""
+
+# Check if .env exists
+if [ ! -f .env ]; then
+    echo "❌ Error: .env file not found"
+    echo "📝 Run the setup wizard to create it:"
+    echo "   ./setup-wizard.sh"
+    echo ""
+    echo "Or copy from example:"
+    echo "   cp .env.example .env"
+    echo "   nano .env"
+    exit 1
+fi
+
+# Check required environment variables
+echo "🔍 Checking required environment variables..."
+missing_vars=()
+
+# Check critical variables
+for var in POSTGRES_PASSWORD JWT_SECRET OIDC_CLIENT_ID OIDC_CLIENT_SECRET ENCRYPTION_KEY BETTER_AUTH_SECRET; do
+    if ! grep -q "^${var}=" .env || grep -q "^${var}=.*REPLACE" .env || [ -z "$(grep "^${var}=" .env | cut -d= -f2)" ]; then
+        missing_vars+=("$var")
+    fi
+done
+
+# Check AI provider configuration
+AI_PROVIDER=$(grep "^AI_PROVIDER=" .env 2>/dev/null | cut -d= -f2 || echo "ollama")
+
+if [ "$AI_PROVIDER" = "claude" ]; then
+    if ! grep -q "^CLAUDE_API_KEY=" .env || grep -q "^CLAUDE_API_KEY=.*REPLACE" .env; then
+        missing_vars+=("CLAUDE_API_KEY (required when AI_PROVIDER=claude)")
+    fi
+elif [ "$AI_PROVIDER" = "openai" ]; then
+    if ! grep -q "^OPENAI_API_KEY=" .env || grep -q "^OPENAI_API_KEY=.*REPLACE" .env; then
+        missing_vars+=("OPENAI_API_KEY (required when AI_PROVIDER=openai)")
+    fi
+fi
+
+if [ ${#missing_vars[@]} -gt 0 ]; then
+    echo "❌ Missing or placeholder values for:"
+    printf "   - %s\n" "${missing_vars[@]}"
+    echo ""
+    echo "Run the setup wizard to configure:"
+    echo "   ./setup-wizard.sh"
+    echo ""
+    echo "Or manually edit .env"
+    exit 1
+fi
+
+echo "✅ All required variables configured"
+echo "   AI Provider: $AI_PROVIDER"
+echo ""
+
+# Check if traefik-public network exists
+if ! docker network ls --filter name=traefik-public --format '{{.Name}}' | grep -q '^traefik-public$'; then
+    echo "⚠️  traefik-public network not found. Creating it..."
+    docker network create --driver=overlay traefik-public
+    echo "✅ traefik-public network created"
+else
+    echo "✅ traefik-public network already exists"
+fi
+
+# Build images (optional - uncomment if you want to build before deploying)
+# echo ""
+# echo "🔨 Building images..."
+# docker compose -f $COMPOSE_FILE build
+
+# Deploy the stack
+echo ""
+echo "📦 Deploying stack..."
+docker stack deploy -c $COMPOSE_FILE --with-registry-auth $STACK_NAME
+
+echo ""
+echo "✅ Stack deployed successfully!"
+echo ""
+echo "📊 Stack status:"
+docker stack ps $STACK_NAME --format "table {{.Name}}\t{{.CurrentState}}\t{{.Error}}"
+
+echo ""
+echo "🔍 To check stack services:"
+echo "   docker stack services $STACK_NAME"
+echo ""
+echo "🔍 To check stack logs:"
+echo "   docker service logs ${STACK_NAME}_api"
+echo "   docker service logs ${STACK_NAME}_web"
+echo "   docker service logs ${STACK_NAME}_postgres"
+echo ""
+echo "🗑️  To remove the stack:"
+echo "   docker stack rm $STACK_NAME"