changes

docs/v2.0/integrations-reference.md

@@ -25,16 +25,16 @@ If you use your own scripts as the source of truth for `network.json` and `Shape
 
 ## What these integrations do
 
-These integrations work by synchronizing with your CRM/NMS system to produce the two files LibreQoS requires for shaping - [network.json](configuration.md#network-hierarchy) and [ShapedDevices.csv](configuration.md#circuits).
+These integrations synchronize with your CRM/NMS system to produce integration-owned topology and shaping artifacts for LibreQoS.
 
 Important behavior when integrations are enabled:
-- `ShapedDevices.csv` is typically regenerated by integration sync jobs.
-- `network.json` overwrite behavior depends on your integration settings (for example `always_overwrite_network_json`).
+- Built-in integrations publish integration-owned topology and shaping artifacts.
+- `network.json` remains a DIY/manual ingress file and is not written by built-in integrations.
 - Manual edits may be overwritten on the next refresh cycle.
 
 ## Splynx Integration
 
-> **⚠️ Breaking Change Notice**: Prior to v1.5-RC-2, the default Splynx strategy was `full`. Starting with v1.5-RC-2, the default strategy is `ap_only` for improved CPU performance. If you require the previous behavior, explicitly set `strategy = "full"` in your Splynx configuration section.
+> **⚠️ Breaking Change Notice**: Prior to v1.5-RC-2, the default Splynx strategy was `full`. The default shared topology mode is now `ap_site` as the best balance of structure and operator clarity. If you require the previous behavior, explicitly set `strategy = "full"` in your Splynx configuration section.
 
 First, set the relevant parameters for Splynx (splynx_api_key, splynx_api_secret, etc.) in `/etc/lqos.conf`.
 
@@ -45,8 +45,8 @@ LibreQoS supports multiple topology strategies for Splynx integration to balance
 | Strategy | Description | CPU Impact | Use Case |
 |----------|-------------|------------|----------|
 | `flat` | Only shapes subscribers, no hierarchy | Lowest | Maximum performance, simple subscriber-only shaping |
-| `ap_only` | Single layer: AP → Clients | Low | **Default**. Best balance of performance and structure |
-| `ap_site` | Two layers: Site → AP → Clients | Medium | Site-level aggregation with moderate complexity |
+| `ap_only` | Single layer: AP → Clients | Low | Lowest overhead when site-level grouping is not needed |
+| `ap_site` | Two layers: Site → AP → Clients | Medium | **Default**. Best balance of structure and operator clarity |
 | `full` | Complete topology mapping | Highest | Full network hierarchy representation |
 
 Configure the strategy in `/etc/lqos.conf` under the `[splynx_integration]` section:
@@ -54,12 +54,12 @@ Configure the strategy in `/etc/lqos.conf` under the `[splynx_integration]` sect
 ```ini
 [splynx_integration]
 # ... other splynx settings ...
-strategy = "ap_only"
+strategy = "ap_site"
 ```
 
 **Performance Considerations:**
 - `flat` and `ap_only` strategies significantly reduce CPU load by limiting network depth
-- Choose `ap_only` for most deployments unless you need site-level traffic aggregation
+- Choose `ap_site` by default, and move to `ap_only` only when you want lower overhead and can give up site-level grouping
 - Only use `full` if you require complete network topology representation and have adequate CPU resources
 
 ### Promote to Root Nodes (Performance Optimization)
@@ -122,12 +122,8 @@ To test the Splynx Integration, use
 python3 integrationSplynx.py
 ```
 
-On the first successful run, it will create a ShapedDevices.csv file and network.json.
-ShapedDevices.csv will be overwritten every time the Splynx integration is run.
-
-To ensure the network.json is always overwritten with the newest version pulled in by the integration, please edit `/etc/lqos.conf` with the command `sudo nano /etc/lqos.conf`.
-Edit the file to set the value of `always_overwrite_network_json` to `true`.
-Then, run `sudo systemctl restart lqosd`.
+On the first successful run, it will create integration-owned shaping data.
+Built-in integrations do not overwrite `network.json`; keep DIY `network.json` operator-owned.
 
 You have the option to run integrationSplynx.py automatically on boot and every X minutes (set by the parameter `queue_refresh_interval_mins`), which is highly recommended. This can be enabled by setting ```enable_splynx = true``` under the ```[splynx_integration]``` section in `/etc/lqos.conf`.
 Once set, run `sudo systemctl restart lqos_scheduler`.
@@ -167,7 +163,7 @@ Run a manual import with:
 python3 integrationNetzur.py
 ```
 
-The integration regenerates `ShapedDevices.csv` and, unless `always_overwrite_network_json` is disabled, updates `network.json`. Adjust the Integration → Common settings if you need to preserve an existing network map between Netzur syncs.
+The integration regenerates `ShapedDevices.csv` for its legacy DIY-style path, but built-in integrations no longer write `network.json`. Keep DIY `network.json` operator-owned.
 
 ## VISP Integration
 
@@ -190,7 +186,7 @@ timeout_secs = 20
 Notes:
 - VISP import is GraphQL-based and currently defaults to a flat topology strategy.
 - The integration writes `ShapedDevices.csv` every run.
-- `network.json` is only overwritten when `always_overwrite_network_json = true` (under `[integration_common]`).
+- `network.json` remains a DIY/manual ingress file; built-in integrations do not overwrite it.
 - VISP auth tokens are cached in `<lqos_directory>/.visp_token_cache_*.json`.
 
 Run a manual import with:
@@ -223,7 +219,7 @@ LibreQoS supports multiple topology strategies for UISP integration to balance C
 | `full` | Shapes entire network including backhauls, Sites, APs, and clients | Highest | Best after topology/overrides are validated and stable |
 
 **Choosing the Right Strategy:**
-- Start with `ap_only` for new deployments and initial validation
+- Start with `ap_site` for new deployments and initial validation
 - Move to `ap_site` when you need site-level control but not backhaul shaping
 - Move to `full` after topology quality and overrides are validated, and CPU headroom is confirmed
 - Use `flat` only when maximum performance is critical and you don't need any hierarchy
@@ -278,7 +274,7 @@ url = "https://uisp.your_domain.com"
 site = "Root_Site_Name"  # Root site for topology perspective
 
 # Topology Strategy (see table above)
-strategy = "ap_only"  # Recommended starting point for new UISP deployments
+strategy = "ap_site"  # Recommended starting point for new UISP deployments
 
 # Suspension Handling (see table above)
 suspended_strategy = "none"
@@ -300,7 +296,6 @@ commit_bandwidth_multiplier = 0.98  # Set minimum to 98% of maximum (CIR)
 
 # Advanced Options
 ipv6_with_mikrotik = false  # Enable if using DHCPv6 with MikroTik
-always_overwrite_network_json = true  # Recommended for integration-driven deployments
 exception_cpes = []  # CPE exceptions in ["cpe:parent"] format
 squash_sites = []  # Optional: sites to squash
 do_not_squash_sites = []  # Optional: keep these site names unsquashed in the runtime/export tree
@@ -341,15 +336,13 @@ sudo /opt/libreqos/src/bin/uisp_integration
 ```
 
 On the first successful run, it will create a network.json and ShapedDevices.csv file.
-If a network.json file exists, it will not be overwritten, unless you set ```always_overwrite_network_json = true```.
+Built-in integrations do not overwrite an existing `network.json`; keep DIY `network.json` operator-owned.
 
 ShapedDevices.csv will be overwritten every time the UISP integration is run.
 
 If UISP exposes a site and an AP with the same visible name in the same topology, current builds keep the site name stable in `network.json` and disambiguate the AP name during export so the site branch is not dropped from the tree.
 
-To ensure the network.json is always overwritten with the newest version pulled in by the integration, please edit `/etc/lqos.conf` with the command `sudo nano /etc/lqos.conf`.
-Edit the file to set the value of `always_overwrite_network_json` to `true`.
-Then, run `sudo systemctl restart lqosd`.
+Built-in integrations do not overwrite `network.json`; keep DIY `network.json` operator-owned.
 
 You have the option to run `uisp_integration` automatically on boot and every X minutes (set by the parameter `queue_refresh_interval_mins`), which is highly recommended. This can be enabled by setting ```enable_uisp = true``` in `/etc/lqos.conf`. Once set, run `sudo systemctl restart lqos_scheduler`.
 
@@ -394,9 +387,7 @@ python3 integrationWISPGate.py
 On the first successful run, it will create a ShapedDevices.csv file and network.json.
 ShapedDevices.csv will be overwritten every time the WISPGate integration is run.
 
-To ensure the network.json is always overwritten with the newest version pulled in by the integration, please edit `/etc/lqos.conf` with the command `sudo nano /etc/lqos.conf`.
-Edit the file to set the value of `always_overwrite_network_json` to `true`.
-Then, run `sudo systemctl restart lqosd`.
+Built-in integrations do not overwrite `network.json`; keep DIY `network.json` operator-owned.
 
 You have the option to run integrationWISPGate.py automatically on boot and every X minutes (set by the parameter `queue_refresh_interval_mins`), which is highly recommended. This can be enabled by setting ```enable_wispgate = true``` in `/etc/lqos.conf`.
 Once set, run `sudo systemctl restart lqos_scheduler`.
@@ -427,7 +418,7 @@ python3 integrationSonar.py
 ```
 
 On the first successful run, it will create a ShapedDevices.csv file.
-If a network.json file exists, it will not be overwritten, unless you set ```always_overwrite_network_json = true```.
+Built-in integrations do not overwrite an existing `network.json`; keep DIY `network.json` operator-owned.
 You can modify the network.json file to more accurately reflect bandwidth limits.
 ShapedDevices.csv will be overwritten every time the Sonar integration is run.
 You have the option to run integrationSonar.py automatically on boot and every X minutes (set by the parameter `queue_refresh_interval_mins`), which is highly recommended. This can be enabled by setting ```enable_sonar = true``` in `/etc/lqos.conf`.