changes

docs/v2.0/configuration-advanced.md

@@ -88,6 +88,17 @@ If built-in integration mode is enabled, the integration and topology compiler o
 - Use WebUI/manual edits for short operational adjustments only.
 - Put permanent changes in your integration system, integration overrides, or declared external source of truth workflow.
 
+#### Topology compile mode for DIY/manual files
+
+For DIY/manual deployments that maintain `network.json` and `ShapedDevices.csv`, use a hierarchy-preserving mode when circuits should shape under the `Parent Node` names from `network.json`:
+
+```toml
+[topology]
+compile_mode = "full"
+```
+
+Use `compile_mode = "flat"` only when hierarchy is not part of the shaping plan. In flat mode, LibreQoS assigns circuits to generated CPU bucket queues such as `Generated_PN_1`; the original `Parent Node` remains a logical reference, but the effective shaping parent in `shaping_inputs.json` will be a generated bucket with `resolution_source: "flat_bucket"`.
+
 #### Static queue visibility policy
 
 Current builds separate logical topology from queue-visible topology.

docs/v2.0/operating-modes.md

@@ -43,6 +43,8 @@ Key behavior:
 - Your external workflow is where permanent changes belong.
 - WebUI edits are fine for quick operational changes.
 - Keep your long-term changes in your own scripts or automation.
+- Use `topology.compile_mode = "full"` when the `Parent Node` values in `ShapedDevices.csv` should shape under the named hierarchy in `network.json`.
+- Use `flat` only when generated CPU bucket queues such as `Generated_PN_1` are the intended queue layout.
 
 ## Manual Files Mode
 
@@ -52,6 +54,8 @@ Key behavior:
 - Best fit for small networks, short pilots, or temporary workarounds.
 - WebUI helps you validate what LibreQoS is using.
 - Manual discipline matters because there is no upstream system keeping those files in sync for you.
+- Use `topology.compile_mode = "full"` when top-level or AP/Site parent shaping should follow `network.json`.
+- If `shaping_inputs.json` shows `resolution_source: "flat_bucket"`, LibreQoS is in flat mode and circuits will show generated parent queues instead of the names from `network.json`.
 
 ## Mode Declaration Checklist (Before Go-Live)
 

docs/v2.0/quickstart.md

@@ -102,7 +102,10 @@ Choose this only if another internal process already writes LibreQoS-compatible
 Do this now:
 1. Configure shared topology behavior under `Integration - Common`.
 2. Publish `network.json` and `ShapedDevices.csv` from your own process.
-3. Reload or wait for the scheduler so LibreQoS can validate and use those files.
+3. Use `topology.compile_mode = "full"` if circuits should shape under the named `Parent Node` hierarchy from `network.json`.
+4. Reload or wait for the scheduler so LibreQoS can validate and use those files.
+
+Do not use `topology.compile_mode = "flat"` when you expect `Parent Node` values from `ShapedDevices.csv` to create top-level shaping queues. In flat mode, LibreQoS intentionally assigns circuits to generated CPU bucket queues such as `Generated_PN_1`.
 
 Next:
 - [Operating Modes and Source of Truth](operating-modes.md)
@@ -115,8 +118,11 @@ Choose this only if you intentionally want LibreQoS to own the files directly.
 Do this now:
 1. Build `network.json`.
 2. Build `ShapedDevices.csv`.
-3. Use the WebUI editors or file-based workflow to maintain them.
-4. Confirm the scheduler accepts the data and the expected topology appears.
+3. Set `topology.compile_mode = "full"` if the `Parent Node` column should shape under the named nodes in `network.json`.
+4. Use the WebUI editors or file-based workflow to maintain them.
+5. Confirm the scheduler accepts the data and the expected topology appears.
+
+Use `flat` only when you want generated CPU bucket queues instead of hierarchy-based parent queues.
 
 Next:
 - [Advanced Configuration Reference](configuration-advanced.md)

docs/v2.0/topology-data-flow.md

@@ -110,6 +110,15 @@ Operator-managed files remain the ingress contract.
   - `network.effective.json`
   - `shaping_inputs.json`
 
+For DIY/manual deployments that expect the `Parent Node` column in `ShapedDevices.csv` to shape under named nodes from `network.json`, use a hierarchy-preserving topology mode such as:
+
+```toml
+[topology]
+compile_mode = "full"
+```
+
+Do not use `compile_mode = "flat"` for hierarchy-based parent shaping. Flat mode intentionally assigns circuits to generated CPU bucket queues such as `Generated_PN_1`; `shaping_inputs.json` will show `resolution_source: "flat_bucket"` for those circuits.
+
 ```{mermaid}
 flowchart LR
     A[Built-in Integration Mode] --> B[topology_import.json]
@@ -143,6 +152,8 @@ flowchart LR
 
 When a circuit references a parent or anchor that is not present in the queue-visible effective topology, LibreQoS still shapes the circuit under a generated parent node. Scheduler output summarizes those fallbacks by reason and includes a few example circuits instead of printing one warning per circuit. Review the examples in Topology Manager or the source integration when those circuits should attach to a specific real site, AP, or parent node.
 
+This is different from explicit flat mode. If `shaping_inputs.json` shows `resolution_source: "flat_bucket"`, the generated parent node is expected flat-mode behavior. Switch `topology.compile_mode` away from `flat` when circuits should follow `network.json` parent names.
+
 ## Consumer Map
 
 ```{mermaid}

docs/v2.0/troubleshooting.md

@@ -283,6 +283,25 @@ journalctl -u lqosd --since "10 minutes ago"
 
 If still blank under normal traffic, collect recent logs and open an issue.
 
+### Circuits show Generated_PN instead of network.json node names
+
+If a DIY/manual deployment uses `network.json` and `ShapedDevices.csv`, but the Circuit page shows parents such as `Generated_PN_1`, check the runtime shaping inputs:
+
+```bash
+jq '.circuits[] | {circuit_id, logical_parent_node_name, effective_parent_node_name, resolution_source}' /opt/libreqos/state/shaping/shaping_inputs.json
+```
+
+If `resolution_source` is `flat_bucket`, LibreQoS is in flat topology mode. That mode intentionally assigns circuits to generated CPU bucket queues instead of shaping them under the named `Parent Node` hierarchy.
+
+To shape circuits under the node names from `network.json`, set:
+
+```toml
+[topology]
+compile_mode = "full"
+```
+
+Then reload or wait for the scheduler to regenerate `network.effective.json` and `shaping_inputs.json`.
+
 ### Site Map appears blank or slow
 
 Site Map has one extra dependency beyond normal WebUI data feeds: current builds fetch bbox/bootstrap data and raster tiles from `https://insight.libreqos.com`.