diff --git a/CLAUDE.md b/CLAUDE.md
index 3bd7873..b2ff9ba 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -77,6 +77,8 @@ npm run test         # Run tests
 ```bash
 cd packages/worker
 npm run deploy       # builds the tracker bundle, then wrangler deploy
+# wrangler.toml must list every custom domain the worker serves (api. and
+# analytics.). A deploy detaches any custom domain that is not declared.
 
 cd packages/dashboard
 npx wrangler pages deploy dist  # Deploy dashboard
diff --git a/packages/worker/wrangler.toml.example b/packages/worker/wrangler.toml.example
index e3a78fd..24f445a 100644
--- a/packages/worker/wrangler.toml.example
+++ b/packages/worker/wrangler.toml.example
@@ -13,9 +13,17 @@ enabled = true
 # auto-creates the DNS record + cert on `wrangler deploy` when the apex is a zone
 # on this account. Put the dashboard on a sibling subdomain (app.<domain>) so the
 # session cookie (COOKIE_DOMAIN=<domain>) is first-party same-site.
+#
+# List EVERY custom domain the worker serves. Wrangler replaces the worker's
+# custom-domain set with the ones declared here on each deploy, so a hostname
+# left out (for example the tracking origin your sites' tracker.js points at)
+# is detached and its DNS record removed the next time you deploy.
 # [[routes]]
 # pattern = "api.yoursite.com"
 # custom_domain = true
+# [[routes]]
+# pattern = "analytics.yoursite.com"
+# custom_domain = true
 
 # Legacy v0 dataset — still bound, dual-emitted to during the v0 → v1 migration.
 [[analytics_engine_datasets]]