Revise network topology section with verified Tailscale/NetBird facts; add topology diagram (.mmd + .svg)

README.md

@@ -111,13 +111,25 @@ Your ansible-pull CI/CD pattern as a standalone template: systemd auto-update ti
 
 ## Network Topology Note
 
-The Iron Legion fleet uses **two distinct overlay networks** with zero overlap:
+The Iron Legion fleet runs **two completely separate mesh VPN overlays** managed by different companies, on different coordination servers, with zero interoperability between them.
 
-- **Tailscale (`100.x.x.x`)** — Strictly for admin/management traffic. Used by Artemis (AI Foreman), Mark44 (Ollama backend), Mark5 (research agent), and MK7 (swarm manager) for SSH access, monitoring, and agent orchestration. Not exposed to end-user services.
+| Overlay | Technology | Company | IP Range | Use Case |
-- **NetBird (`100.x.x.x`, separate tailnet)** — Used for user-facing services on Neo: Nextcloud AIO, Vaultwarden, Dockhand, and Trilium Notes. These services are reachable by crew members via NetBird, not Tailscale. Separate tailnet from the Tailscale mesh; both use CGNAT `100.x.x.x` ranges.
+|---------|-----------|---------|----------|----------|
-- **LAN (`192.168.0.0/18`)** — Fleet subnet via Beryl router. Swarm nodes (MK33–42, MK7) communicate here. External services on Neo do NOT bridge into this subnet.
+| **Admin/Management** | **Tailscale** | Tailscale Inc. (Canada) | `100.64.0.0/10` (CGNAT) | SSH access, monitoring, agent orchestration between Artemis, Mark44, Mark5, and MK7. Called a **"tailnet"** in Tailscale terminology. |
+| **User-facing services** | **NetBird** | WireTrustee SA (Latvia/EU) | `100.64.0.0/10` (CGNAT, configurable) | Access to Nextcloud AIO, Vaultwarden, Dockhand, and Trilium Notes on Neo. Called a **"NetBird network"** in NetBird terminology. |
+| **LAN backbone** | Beryl router (OpenWrt) | N/A | `192.168.0.0/18` | Internal swarm node-to-node traffic (MK33–42, MK7). No VPN involved. |
 
-**Implication for the blueprint buyer:** The Swarm stack (Path A) is entirely self-contained on the LAN segment. Technitium handles internal DNS. Traefik routes HTTP internally. If a buyer wants NetBird-style user-facing services, those are a separate deployment pattern not covered here.
+**Critical clarifications:**
+
+1. **"Tailnet" is Tailscale's proprietary term.** NetBird does not call its mesh a "tailnet" — it uses "network." These are separate, non-interoperable systems from different vendors.
+
+2. **Same CGNAT range does not mean same network.** Both Tailscale and NetBird default to `100.64.0.0/10` for overlay addressing, but devices on one cannot reach devices on the other. The coordination servers (Tailscale Inc. cloud vs. NetBird cloud/self-hosted) are completely isolated.
+
+3. **Neo is the boundary.** Neo runs the NetBird client for user-facing services. Neo does **not** participate in the Tailscale tailnet. User-facing services are isolated from the admin/management plane by design.
+
+4. **The Swarm stack (Path A) is LAN-contained.** Traefik on MK7 routes HTTP internally. Technitium handles LAN DNS. Neither Tailscale nor NetBird is required for the blueprint buyer's stack to function.
+
+**Buyer implication:** If a homelaber wants the Iron Legion admin/management pattern (Tailscale) AND the user-facing services pattern (NetBird), those are two separate deployments, two separate vendor accounts, and two separate documentation paths. Path A covers only the LAN self-contained stack.
 
 ---
 

iron-legion-topology.mmd

@@ -0,0 +1,53 @@
+flowchart TB
+    subgraph TAILSCALE["🛡️ Tailscale Overlay — Tailscale Inc. (Admin/Management)"]
+        direction TB
+        TSCOORD["Tailscale Coordination Server<br/>(proprietary SaaS)"]
+        TSART["🤖 Artemis (AI Foreman)<br/>100.100.97.18"]
+        TSM44["🔧 Mark44 (Ollama)<br/>100.75.26.83"]
+        TSM5["📚 Mark5 (Research)<br/>100.118.67.105"]
+        TSM7["⚡ MK7 Swarm Manager<br/>100.66.70.51"]
+    end
+
+    subgraph NETBIRD["🕊️ NetBird Overlay — WireTrustee SA (User-facing)"]
+        direction TB
+        NBCOORD["NetBird Coordination Server<br/>(cloud or self-hosted)"]
+        NBNEO["🖥️ Neo (Nebuchadnezzar)<br/>100.92.224.74"]
+        NBNC["☁️ Nextcloud AIO"]
+        NBVW["🔐 Vaultwarden"]
+        NBDOCK["🐳 Dockhand"]
+        NBTRIL["📝 Trilium Notes"]
+    end
+
+    subgraph LAN["🏠 LAN Backbone — Beryl Router (OpenWrt)"]
+        direction TB
+        BERYL["🌐 Beryl 7<br/>Gateway + DHCP<br/>192.168.0.0/18"]
+        MK7LAN["⚡ MK7<br/>Traefik | Technitium | Prometheus<br/>Beszel Hub | Portainer CE | Dozzle | Homepage<br/>192.168.7.7"]
+        WORKERS["🔩 MK33 / MK34 / MK39 / MK42<br/>Swarm Workers (G9 nodes)<br/>192.168.0.x"]
+    end
+
+    %% Tailscale connections
+    TSCOORD ---|"admin mesh<br/>WireGuard tunnel"| TSART
+    TSCOORD ---|"admin mesh"| TSM44
+    TSCOORD ---|"admin mesh"| TSM5
+    TSCOORD ---|"admin mesh"| TSM7
+
+    %% NetBird connections
+    NBCOORD ---|"user mesh<br/>WireGuard tunnel"| NBNEO
+    NBNEO ---|"Docker Compose"| NBNC
+    NBNEO ---|"Docker Compose"| NBVW
+    NBNEO ---|"Docker Compose"| NBDOCK
+    NBNEO ---|"Docker Compose"| NBTRIL
+
+    %% LAN connections
+    BERYL -.->|"DHCP lease"| MK7LAN
+    BERYL -.->|"DHCP lease"| WORKERS
+    MK7LAN ---|"swarm overlay"| WORKERS
+
+    %% Cross-plane: management SSH from Tailscale to LAN
+    TSM7 --"SSH mgmt"--> MK7LAN
+    TSART --"SSH mgmt"--> MK7LAN
+
+    %% Isolation boundaries
+    NBNEO -.-x|"🔒 ISOLATED<br/>no route"| LAN
+    TSART -.-x|"🔒 ISOLATED<br/>no route"| NBNEO
+    TSM7 -.-x|"🔒 ISOLATED<br/>no route"| NBNEO