diff --git a/skills/devops/atproto-site-deployment/SKILL.md b/skills/devops/atproto-site-deployment/SKILL.md
index 3e0fb6d..34646df 100644
--- a/skills/devops/atproto-site-deployment/SKILL.md
+++ b/skills/devops/atproto-site-deployment/SKILL.md
@@ -188,6 +188,22 @@ wispctl domain add-site --db "$HOME/.config/wispctl/state.sqlite" <domain>
 # Prompts for the site rkey (e.g., "zodiac")
 ```
 
+**PITFALL — claim/add-site CLI is broken; the working path is the wisp.place
+web dashboard.** The reliable flow for binding a custom domain to a site is
+a MANUAL web-UI step: log in at wisp.place, open the site, and attach the
+domain there. wispctl deploy alone does NOT bind an existing custom domain
+to the site.
+
+**PITFALL — deployed but domain still 404s (timer, 2026-09):** after a
+successful `wispctl deploy`, the site serves immediately at
+`sites.wisp.place/<handle>/<site>` (200, correct title), but
+`https://<site>.psingletary.com/` AND `<site>.psingletary.com/client-metadata.json`
+both 404 until the owner logs into wisp.place and sets the site to the
+domain. The OAuth metadata check is the canary: if the app shell + bundle
+serve on the custom domain but the metadata path 404s (or vice versa), the
+domain binding is incomplete — tell the owner the dashboard step is
+required (do not retry wispctl add-site silently).
+
 ### Verify
 
 DNS + claim + map can take a few minutes. Check: