diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6a3aa64
--- /dev/null
+++ b/README.md
@@ -0,0 +1,72 @@
+# skyworks-Nix-infra
+
+NixOS configurations for the two NixOS hosts. Flake-based (`flake.nix`)
+with `disko` for disk layout, `agenix` for secrets, `deploy-rs` defined
+but not consistently used (most ops do `git pull && nixos-rebuild switch`
+on the box).
+
+## Hosts
+
+| Host | IP (mgmt) | Role |
+|---|---|---|
+| `xlab-gateway` | 10.253.254.1 | Lab gateway / WAN router. Bond + VLANs (lan254, wan99, mgmt) + WireGuard tunnels with policy routing, NAT/masquerade. Kea DHCP4/6, radvd, fail2ban. |
+| `skydick` | 10.0.1.1 | Storage server. ZFS data pool with hot spares, Samba+LDAP gateway. Heavy use of jumbo frames + bonded 100G. |
+
+## Layout
+
+```
+flake.nix              # entrypoint, defines both hosts + deploy-rs nodes
+hosts/
+  xlab-gateway/
+    default.nix          # host config (boot, users, packages, smartd)
+    networking.nix       # bond/VLAN/WG/nftables/services.resolved
+    dhcp.nix             # Kea DHCP4/6 + DDNS
+    disko.nix            # ZFS root layout
+    hardware-configuration.nix
+  skydick/
+    default.nix          # host config + most networking inline
+    datapool.nix         # ZFS pool layout, Samba + LDAP integration
+    disko.nix            # boot disk layout
+    samba-ldap-bootstrap.ldif
+modules/
+  common.nix             # locale, packages, sshd hardening defaults
+  users.nix              # ldx user + ssh keys
+  ssh.nix                # sshd hardening
+  monitoring.nix         # node-exporter, smart, etc.
+secrets/                 # agenix-encrypted (.age files)
+```
+
+## Deploy (the simple way, from the box)
+
+```sh
+ssh ldx@<host>
+cd /etc/nixos && sudo git pull && sudo nixos-rebuild switch --flake /etc/nixos#<host>
+```
+
+## Deploy via deploy-rs (from a workstation)
+
+```sh
+nix develop  # if there's a devShell, otherwise install deploy-rs
+deploy .#<host>
+```
+
+## Common gotchas
+
+- **DNS**: both hosts route DNS via `10.0.0.1` (mosdns) with a fallback set
+  in `services.resolved.fallbackDns`. Don't add a co-primary nameserver to
+  `networking.nameservers` — systemd-resolved load-balances and bypasses
+  the analytics filter on 10.0.0.1.
+
+- **IPv6 RA**: `networking.enableIPv6 = false` only stops IPv6 *use*, not
+  RA *acceptance*. Both `boot.kernel.sysctl."net.ipv6.conf.*.accept_ra"=0`
+  and `systemd.network.networks."40-bondX".networkConfig.IPv6AcceptRA = false`
+  are needed if upstream radvd is announcing DNS.
+
+- **deploy-rs ssh user**: defined as `ldx` with sudo escalation to root.
+  Make sure the host key in `secrets.nix` matches reality after a reinstall
+  (rekey all secrets if the host key changes).
+
+## Remote
+
+`gitbucket.skyw.top/Skyworks/skyworks-Nix-infra` is canonical. No GitHub
+remote configured.