diff --git a/.env.uomysticmoon.example b/.env.uomysticmoon.example
index e1a5d58..c0750a9 100644
--- a/.env.uomysticmoon.example
+++ b/.env.uomysticmoon.example
@@ -28,3 +28,36 @@ TOTP_ISSUER=UOMysticmoon
 DB_NAME=uomysticmoon
 DB_USER=uomm
 COOKIE_NAME=uomm_token
+
+# ── The UO module — REQUIRED for this instance, not optional like the vars above.
+#
+# Core is game-agnostic (docs/website/MODULE_SYSTEM.md): every shard-facing
+# surface this instance runs — the shard pages, the player's characters, vendors
+# and houses, Admin → Shard, and the uo-link connection itself — lives in
+# RunicGateway/Module-uo and reaches the deployment through this line. Without
+# it, the same image is a perfectly working site with no game on it.
+#
+# It is declared here rather than left to Admin → Modules because a compose host
+# should arrive at its own set at boot, and because this instance has a shard to
+# be down for: the panel path would leave the site game-less between the image
+# roll and someone clicking install.
+#
+# Bump the version deliberately, and read Module-uo's release notes when you do —
+# the container resolves this at every start, so changing the version here is
+# what upgrades the module. A version already unpacked is a no-op that makes no
+# network call at all.
+#
+# This owns what is ON the volume, never whether the module RUNS: disabling it in
+# Admin → Modules keeps it disabled across restarts even though its files return.
+MODULES=uo@0.3.0=https://gitea.whitlocktech.com/RunicGateway/Module-uo/releases/download/v0.3.0/module-uo-0.3.0.json
+
+# Module-uo reads these as the DEFAULTS for its uo-link connection, used only
+# until Admin → Shard has been saved once — after that the encrypted DB config
+# (`uo_link_config`) is authoritative and these are ignored. Left unset here on
+# purpose: an instance that has already saved Admin → Shard keeps that config
+# across the extraction (the module's schema fragment is CREATE TABLE IF NOT
+# EXISTS, so the existing row is untouched), and setting them would suggest they
+# still decide something. Module-uo's README documents them.
+# UOLINK_BASE_URL=
+# UOLINK_WS_URL=
+# UOLINK_PROTOCOL=