diff --git a/docs/v2.0/components.md b/docs/v2.0/components.md
index 397b3a53..8d3a2b82 100644
--- a/docs/v2.0/components.md
+++ b/docs/v2.0/components.md
@@ -43,6 +43,9 @@ flowchart LR
 ### lqos_topology runtime contract
 
 - `lqos_topology` continuously builds runtime-effective topology artifacts from current source inputs and attachment health.
+- Current builds keep two distinct topology views:
+  - `compatibility_network_json` remains the local compatibility tree used as the base for `network.effective.json`
+  - Insight topology submission derives a separate logical-parent tree from canonical topology state so sites are grouped by logical site hierarchy rather than immediate attachment hops
 - After a successful publish, it writes `/opt/libreqos/src/topology_runtime_status.json` with:
   - `source_generation`
   - `ready`
diff --git a/docs/v2.0/troubleshooting.md b/docs/v2.0/troubleshooting.md
index 650d6e43..31e55845 100644
--- a/docs/v2.0/troubleshooting.md
+++ b/docs/v2.0/troubleshooting.md
@@ -162,6 +162,8 @@ ls -lh /opt/libreqos/src/topology_effective_state.json /opt/libreqos/src/network
 journalctl -u lqos_scheduler --since "30 minutes ago"
 ```
 
+If Insight shows sites buried under AP/backhaul chains or only a narrow subset of sites loads cleanly, check whether the host is on a build before the separate Insight logical-topology export. Current builds submit an Insight-only logical-parent tree derived from canonical topology state, while `compatibility_network_json` remains reserved for local compatibility and `network.effective.json` generation.
+
 If an integration subprocess fails, current builds keep the scheduler alive, publish a shortened output preview to the scheduler status/error surfaces, and save the full captured output to a timestamped file under `/tmp` such as `lqos_scheduler_uisp_integration_YYYYMMDD_HHMMSS.log`.
 
 ### Scheduler status in WebUI looks unhealthy