docs(swarm): comprehensive Docker Swarm deployment documentation

- Update docker-compose.swarm.yml with external Authentik configuration
  - Comment out Authentik services (using external OIDC provider)
  - Comment out Authentik volumes
  - Add header with deployment instructions and current configuration

- Create comprehensive SWARM-DEPLOYMENT.md guide
  - Prerequisites and swarm initialization
  - Manual OpenBao initialization (critical - no auto-init in swarm)
  - External service configuration examples
  - Scaling, updates, rollbacks
  - Troubleshooting and maintenance procedures
  - Backup and restore instructions

- Update .env.swarm.example
  - Add note about external vs internal Authentik
  - Update default OIDC_ISSUER to use https
  - Clarify which variables are needed for internal Authentik

- Update README.md Docker Swarm section
  - Fix deploy script path (./scripts/deploy-swarm.sh)
  - Add note about manual OpenBao initialization
  - Add warning about no profile support in swarm
  - Update documentation references to docs/ directory

- Update documentation cross-references
  - Add deprecation notice to old DOCKER-SWARM.md
  - Add deployment guide reference to SWARM-QUICKREF.md
  - Update DOCKER-COMPOSE-GUIDE.md See Also section

Key changes for swarm deployment:
- Swarm does NOT support docker-compose profiles
- External services must be manually commented out
- OpenBao requires manual initialization (no sidecar)
- All documentation updated with correct paths

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -164,7 +164,7 @@ Deploy to a Docker Swarm cluster with integrated Traefik reverse proxy:
 
 ```bash
 # 1. Initialize swarm (if not already done)
-docker swarm init
+docker swarm init --advertise-addr <your-ip>
 
 # 2. Create Traefik network
 docker network create --driver=overlay traefik-public
@@ -174,16 +174,19 @@ cp .env.swarm.example .env
 nano .env  # Configure domains, passwords, API keys
 
 # 4. Deploy stack
-./deploy-swarm.sh mosaic
+./scripts/deploy-swarm.sh mosaic
 
 # 5. Check deployment status
 docker stack services mosaic
 docker stack ps mosaic
 
+# 6. CRITICAL: Initialize OpenBao manually (see docs)
+# Unlike docker-compose, swarm requires manual OpenBao initialization
+
 # Access services via Traefik
 # Web:  http://mosaic.mosaicstack.dev
 # API:  http://api.mosaicstack.dev
-# Auth: http://auth.mosaicstack.dev
+# Auth: http://auth.mosaicstack.dev (if using bundled Authentik)
 ```
 
 **Key features:**
@@ -193,8 +196,15 @@ docker stack ps mosaic
 - Built-in health checks and rolling updates
 - Horizontal scaling for web and API services
 - Zero-downtime deployments
+- Service orchestration across multiple nodes
 
-See [Docker Swarm Deployment Guide](DOCKER-SWARM.md) and [Quick Reference](SWARM-QUICKREF.md) for complete documentation.
+**Important Notes:**
+
+- Swarm does NOT support docker-compose profiles
+- To use external services (PostgreSQL, Authentik, etc.), manually comment them out in `docker/docker-compose.swarm.yml`
+- OpenBao requires manual initialization (no auto-init sidecar in swarm mode)
+
+See [Docker Swarm Deployment Guide](docs/SWARM-DEPLOYMENT.md) and [Quick Reference](docs/SWARM-QUICKREF.md) for complete documentation.
 
 ## Project Structure