diff --git a/docs/user-guide/external.md b/docs/user-guide/external.md
index e0f53653..098bc941 100644
--- a/docs/user-guide/external.md
+++ b/docs/user-guide/external.md
@@ -16,7 +16,9 @@ Border Leaves (or Borders) can connect to several Edge Devices.
 !!! note
     External Peering is only available on switch devices that support sub-interfaces.
 
-Hedgehog Fabric supports both BGP-speaking and static externals.
+Hedgehog Fabric supports both BGP-speaking and static externals. This choice is made per attachment, not per
+`External`, so a single `External` can have both kinds of attachment at once; see
+[Migrating a Static Attachment to BGP](#migrating-a-static-attachment-to-bgp).
 
 ### Connect a Border Leaf to an Edge Device
 
@@ -173,6 +175,34 @@ spec:
     ip:       # IP address (with prefix length) to be configured on the switch when not using Proxy mode, empty otherwise
 ```
 
+### Migrating a Static Attachment to BGP
+
+Static-ness is a property of the `ExternalAttachment`, not of the `External`. This means a single `External` can have
+both static and BGP-speaking attachments at the same time, which allows a static uplink to be migrated to BGP:
+
+1. Add a BGP `ExternalAttachment` on a second Border Leaf, pointing at the same `External`.
+2. Convert the original attachment from static to BGP (remove its `static` block, add `neighbor` and `switch`).
+3. Clear `spec.static.prefixes` on the `External` itself, and set `inboundCommunity`/`outboundCommunity` to match
+   whatever community policy the Edge Device applies (see
+   [BGP-speaking External object](#bgp-speaking-external-object) above). The API refuses both changes while any
+   attachment referencing the `External` is still static, so step 3 can only happen after step 2.
+
+While a static attachment and a BGP attachment on the same `External` coexist, the static path always wins, so
+traffic keeps flowing over it during steps 1 and 2.
+
+!!! warning
+    Once step 2 removes the last static attachment, traffic has to use the BGP path, but that path cannot carry
+    `outboundCommunity` yet: the API forbids setting it while `spec.static.prefixes` is still present, to protect the
+    static route from being dropped by a community-based route-map while it still exists. If the Edge Device filters
+    inbound routes by community, as recommended above, every route the Fabric advertises over the new BGP session
+    gets silently dropped until step 3 completes, so this is a real traffic gap, not a hitless cutover. The gap is
+    bound by how long the switch's control plane takes to reconcile the change, typically on the order of a minute,
+    regardless of how quickly the API calls themselves are issued.
+
+    Since this is a new BGP session (there was no prior BGP config on the Edge Device for this External), this is
+    avoidable: ask the Edge Device operator to accept routes without a community for this session until step 3
+    completes, then add their community-based filter afterward.
+
 ### External VPC Peering
 
 To allow a specific VPC to have access to prefixes reachable via an Edge Device, bind the VPC to the corresponding