diff --git a/README.md b/README.md
index b4e3162..cef9dbe 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,257 @@
-# compose-files
+# Homelab Infrastructure Repository - Docker Swarm Compose Files
 
-Docker Swarm compose files for homelab services
\ No newline at end of file
+This Gitea repository contains **Docker Swarm compose files** for all services running in the homelab.
+
+**For operational scripts** (backup hooks, prune watchdog, network configuration), see the separate **`homelab-scripts`** repository.
+
+---
+
+## 📁 Directory Structure
+
+```
+├── traefik.yaml               # Reverse proxy & load balancer
+├── auth.yaml                  # Authentik authentication
+├── postgresql.yaml            # PostgreSQL database
+├── maintenance.yaml           # Cronicle scheduler, Uptime Kuma
+├── ... (other service stacks)
+└── README.md                  # This file
+```
+
+---
+
+## 🚀 Quick Start
+
+### Deploy a Stack
+
+```bash
+# SSH into a Docker LXC (docker-1, docker-2, or docker-3)
+ssh root@docker-1
+
+# Clone this repo locally
+cd /volume1/docker
+git clone https://git.bryanmail.net/admin/compose-files.git repo
+cd repo
+
+# Deploy a stack
+docker stack deploy -c traefik.yaml traefik
+docker stack deploy -c auth.yaml auth
+docker stack deploy -c postgresql.yaml postgresql
+```
+
+### Update a Stack
+
+```bash
+# Pull latest changes
+git pull origin main
+
+# Re-deploy (applies changes)
+docker stack deploy -c traefik.yaml traefik
+
+# View status
+docker stack ps traefik
+docker service ls
+```
+
+### Remove a Stack
+
+```bash
+docker stack rm traefik
+```
+
+---
+
+## 📋 Available Stacks
+
+| Stack | File | Purpose |
+|-------|------|---------|
+| Traefik | traefik.yaml | Reverse proxy, load balancer, TLS termination |
+| Authentik | auth.yaml | Authentication & authorization |
+| PostgreSQL | postgresql.yaml | Database backend |
+| Maintenance | maintenance.yaml | Cronicle jobs, Uptime Kuma monitoring |
+| ... | ... | (Add more as you create them) |
+
+---
+
+## 🛠️ Common Tasks
+
+### Deploy a New Service
+
+1. **Create compose file** in this repo: `myservice.yaml`
+2. **Test locally** (on single host):
+   ```bash
+   docker-compose -f myservice.yaml up -d
+   ```
+3. **Convert to Swarm format** (remove `container_name`, use `services:` for Swarm)
+4. **Deploy to Swarm**:
+   ```bash
+   docker stack deploy -c myservice.yaml myservice
+   ```
+5. **Commit & push**:
+   ```bash
+   git add myservice.yaml
+   git commit -m "Add myservice stack"
+   git push origin main
+   ```
+
+### Check Service Status
+
+```bash
+# List all services
+docker service ls
+
+# Get details about a service
+docker service inspect traefik_reverse-proxy
+
+# View service logs
+docker service logs -f traefik_reverse-proxy
+
+# Check tasks (containers)
+docker service ps traefik_reverse-proxy
+```
+
+### Monitor Disk Space
+
+```bash
+df -h /volume1/docker-root
+
+# Docker prune watchdog handles auto-cleanup (see homelab-scripts repo)
+```
+
+---
+
+## 🔐 Secrets Management
+
+**DO NOT commit secrets, passwords, or API keys to this repo.**
+
+Use one of these approaches:
+
+### Option 1: Docker Secrets (Recommended for Swarm)
+```yaml
+services:
+  myapp:
+    secrets:
+      - db_password
+
+secrets:
+  db_password:
+    external: true
+```
+
+Create the secret:
+```bash
+echo "mysecretpassword" | docker secret create db_password -
+```
+
+### Option 2: Environment Files (Not tracked by git)
+```bash
+# Create .env (add to .gitignore)
+echo "DB_PASSWORD=mysecretpassword" > .env
+
+# Use in compose
+env_file: .env
+```
+
+---
+
+## 📚 Architecture
+
+### Swarm Cluster
+```
+nuck7-1 (Hypervisor)        nuck7-2 (Hypervisor)        nuck7-3 (Hypervisor)
+├─ docker-1 (LXC 4031)      ├─ docker-2 (LXC 4032)      ├─ docker-3 (LXC 4033)
+│  └─ Swarm Manager         │  └─ Swarm Leader          │  └─ Swarm Manager
+└─ ...                      └─ ...                      └─ ...
+```
+
+### Storage
+- **CephFS** mounted at `/volume1/docker/` (shared across all nodes)
+- **Compose files**: `/volume1/docker/compose-files/`
+- **Service data**: Named volumes or `/volume1/docker/` mounts
+
+### Networking
+- **VIP**: 192.168.4.30 (Keepalived)
+- **Docker hosts**: 192.168.4.31-33
+- **Traefik**: Reverse proxy with Let's Encrypt TLS
+- **Domain**: bryanmail.net
+
+---
+
+## 🔗 Related Repositories
+
+- **[homelab-scripts](https://git.bryanmail.net/admin/homelab-scripts)** - Operational scripts (backup hooks, monitoring, network config)
+- **Proxmox MCP Setup** - Documented in notes
+- **Architecture Decision Records (ADRs)** - Documented in notes
+
+---
+
+## 🐛 Troubleshooting
+
+### Stack won't deploy
+```bash
+# Check syntax
+docker-compose config -f myservice.yaml
+
+# Check node availability
+docker node ls
+
+# Check disk space
+df -h /volume1/docker-root
+```
+
+### Service keeps crashing
+```bash
+# View logs
+docker service logs -f myservice_name
+
+# Inspect container
+docker ps -a | grep myservice
+```
+
+### Network issues
+```bash
+# List networks
+docker network ls --filter driver=overlay
+
+# Test connectivity
+docker run --rm --network traefik_backend alpine ping traefik_reverse-proxy
+```
+
+---
+
+## 📞 Contributing
+
+When adding new services:
+
+1. Use **Swarm-compatible YAML** (no `container_name`)
+2. Document requirements in compose file comments
+3. Test on non-production first
+4. Add notes about volumes, secrets, networking
+5. Update this README with stack description
+
+---
+
+## 📝 Git Workflow
+
+```bash
+# Before starting work
+git pull origin main
+
+# Create feature branch for new service
+git checkout -b feature/new-service
+
+# Make changes and commit
+git add .
+git commit -m "Add new-service stack"
+
+# Push
+git push origin feature/new-service
+```
+
+---
+
+## Version Control Best Practices
+
+- **Keep compose files in sync** with deployed state
+- **Pin image versions** (avoid `latest` tag)
+- **Document breaking changes** in commit messages
+- **Use meaningful commit messages** for audit trail