diff --git a/swarm.md b/swarm.md
new file mode 100644
index 0000000..69bab76
--- /dev/null
+++ b/swarm.md
@@ -0,0 +1,112 @@
+# Iron Legion Docker Swarm — Fleet Reference
+
+## Cluster Topology
+
+| Node | Hostname | Role | Tailscale | LAN IP |
+|------|----------|------|-----------|--------|
+| MK7 | `mark-vii.ai.home` | **Manager (Leader)** | `100.66.70.51` | `192.168.7.7` |
+| MK33 | `mk-33` | Worker | — | `192.168.0.190` |
+| MK34 | `mk-34` | Worker | — | `192.168.0.123` |
+| MK39 | `mk-39` | Worker | — | `192.168.0.106` |
+| MK42 | `mk-42` | Worker | — | `192.168.0.196` |
+
+**Worker join token:**
+```
+SWMTKN-1-01759qgxz7d4x0bl32shlyjed540fgqjhggx0nyrw04d3zt017-blujv5tley9ukl8ke60dvz0ec
+```
+
+## Service Catalog
+
+All services deployed on MK7 manager via `docker stack deploy`.
+
+| Stack | Service | Mode | Replicas | Published Ports | Traefik Host |
+|-------|---------|------|----------|-----------------|--------------|
+| `traefik` | Traefik v3 | global | 1/1 | `80`, `8080` (dashboard) | — |
+| `node-exporter` | Node Exporter | **global** | 5/5 | — | — |
+| `beszel` | Beszel Hub | replicated | 1/1 | — | `beszel.ai.home` |
+| `homepage` | Homepage Dashboard | replicated | 1/1 | — | `home.ai.home` |
+| `dozzle` | Dozzle Logs | replicated | 1/1 | — | `dozzle.ai.home` |
+| `portainer` | Portainer CE | replicated | 1/1 | `9000` | `portainer.ai.home` |
+| `prometheus` | Prometheus | replicated | 1/1 | `9090` | `prom.ai.home` |
+| `technitium` | Technitium DNS | replicated | 1/1 | `53/tcp`, `53/udp`, `5380` | `dns.ai.home` |
+| `adguard` | AdGuard Home | replicated | 1/1 | `3000`, `30053` | `adguard.ai.home` |
+| ~~authelia~~ | ~~Authelia~~ | ~~deferred~~ | — | — | ~~`auth.ai.home`~~ |
+
+> **Note:** Authelia deferred until local TLS is available (requires `https://auth.ai.home`).
+
+## Network Architecture
+
+| Network | Driver | Scope | Attachable | Note |
+|---------|--------|-------|------------|------|
+| `traefik-public` | overlay | swarm | ✅ | Attachable overlay for all web-facing services |
+| `ingress` | overlay | swarm | — | Built-in swarm ingress |
+| `node-exporter_default` | overlay | swarm | — | Created by node-exporter stack deploy |
+
+## Directory Structure (MK7)
+
+```
+/opt/iron-legion/docker-swarm/
+├── deploy.sh                  # Master deployment script
+├── traefik/compose.yml
+├── node-exporter/compose.yml
+├── technitium/compose.yml
+├── technitium/prometheus.yml  # Prometheus scrape targets
+├── adguard/compose.yml
+├── prometheus/compose.yml
+├── beszel/compose.yml
+├── portainer/compose.yml
+├── dozzle/compose.yml
+├── homepage/compose.yml
+├── homepage/config/settings.yaml
+└── authelia/
+    ├── compose.yml            # Deferred — needs TLS
+    ├── config/
+    │   ├── configuration.yml
+    │   └── users_database.yml
+```
+
+Synced to all workers (`/opt/iron-legion/docker-swarm`) for failover redundancy. Workers do not execute `docker stack deploy` — only MK7 manager orchestrates services.
+
+## Deploy / Re-Deploy
+
+On MK7:
+```bash
+cd /opt/iron-legion/docker-swarm
+./deploy.sh
+```
+
+Or single stack:
+```bash
+cd /opt/iron-legion/docker-swarm
+docker stack deploy -c traefik/compose.yml traefik
+```
+
+## Worker Join (if node rebuilt)
+
+```bash
+# On worker node
+docker swarm join --token SWMTKN-1-01759qgxz7d4x0bl32shlyjed540fgqjhggx0nyrw04d3zt017-blujv5tley9ukl8ke60dvz0ec 192.168.7.7:2377
+```
+
+Ensure worker has `/opt/iron-legion/docker-swarm/` synced for config parity.
+
+## Known Issues / Decisions
+
+| Item | Status | Detail |
+|------|--------|--------|
+| `systemd-resolved` | **Disabled** on MK7 | Port 53 freed for Technitium |
+| Standalone Portainer | **Removed** | Data backed up to `/tmp/portainer-data-backup-20260526-000125.tar.gz` on MK7 |
+| Authelia | **Deferred** | Requires TLS (https://auth.ai.home) |
+| Beszel Agents | **Pending** | Global agent stack to be added across all workers |
+| DNS resolution | **Pending** | `*.ai.home` requires Technitium configured as LAN resolver |
+
+## External Services (NOT in Swarm)
+
+| Service | Node | URL | Note |
+|---------|------|-----|------|
+| Nextcloud AIO | Neo (`100.99.123.16`) | `https://nextcloud.ai.home` | Production, unmanaged |
+| Vaultwarden | Neo (`100.99.123.16`) | `https://vault.ai.home` | Production, unmanaged |
+
+---
+*Last updated: 2026-05-26*
+*Gitea repo: `Iron-Legion/documentation` — push this file there*