> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lootroute.volvox.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# File map

> Per-file responsibilities of the Gatherer layer, in load order.

All `Gatherer/` files load through the repo-root `loadorder.json` (there is no `Gatherer/loadorder.json`). The framework layer loads first, then the bot core executes top-to-bottom as contiguous slices of the former monolith.

## Framework layer

| File            | Responsibility                                                                                                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Module`        | `volvox.Gatherer = volvox.Module:New("Gatherer", "none")`; declares all `gatherer.*` config defaults; publishes `GathererState` and `GathererConfigKeys`; owns the status frame |
| `ModuleActions` | Route and blacklist methods (`Start`, `Stop`, `LoadRoute`, `BlacklistAdd`, …)                                                                                                   |
| `Gui`           | Settings UI setup + the General page (via `volvox.GuiBuilder`)                                                                                                                  |
| `GuiTabs`       | The remaining settings pages; shares the `volvox.GathererGui` load guard with `Gui`                                                                                             |

## Bot core (load order)

| File           | Responsibility                                                                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Core`         | WGG-to-global wrappers (`ObjectPosition`, `ObjectInteract`, `MoveTo`, …), config read helpers, anti-AFK, death/spirit-healer, item/aura/spell use, food, node interaction |
| `NodeTracking` | Debug, GUID blacklist, safe-object accessors, handled/depleted/flee/mob-blocked tracking, scan ranges                                                                     |
| `Navigation`   | Node geometry/height/environment checks, `MoveTo`/nav, file-path I/O wrappers, object scan, `Draw` init, data roots                                                       |
| `Data`         | Object scanning, runtime state init, consumables, node/consumable decision logic                                                                                          |
| `NodeData`     | Static-data tail sliced from `Data`: `KPNodeIDs`, per-expansion node databases (`VANIL`…`MID`), area/traceline flag masks                                                 |
| `Movement`     | Tracelines, start/stop entry points, math helpers, HSwalk/waterjump/anti-AFK movement, `SettingsGatherer`                                                                 |
| `Persistence`  | Route/blacklist/whitelist file persistence, `FetchAndSave`                                                                                                                |
| `ConfigUI`     | `SyncFromFrameworkConfig` bridge, `LoadingGui`, professions/enchants, route recording                                                                                     |
| `Combat`       | Node landing/pitch/traceline, unit safety/threat, elite avoidance, blacklist checks                                                                                       |
| `GatherLogic`  | Flasks, node visibility, spore, looting, metamorph, fishing, `scan`, `nodecheck`                                                                                          |
| `FlightTasks`  | Mailbox, flight/overload checks, profession-tree build, surge/skyriding charges, fight/agro/dead/flee handlers                                                            |
| `Routine`      | Mail/guild-bank, `FlyPitch`, the central **`Routine`** dispatcher, event frame                                                                                            |
| `ObjectDebug`  | Optional object-inspection helpers loaded after the main routine                                                                                                          |

## Load-guard conventions

Every file is idempotent against double-loading with a distinct flag, unless it is a continuation file that must reload-skip as a pair with its base file:

* `Module` → `__GathererModuleLoaded`
* `ModuleActions` → `__GathererModuleActionsLoaded`
* `Gui` + `GuiTabs` deliberately **share** `volvox.GathererGui`, set `= true` only at the very end of `GuiTabs.lua`

## Adding a file

Before inserting a new `Gatherer/<name>` entry at position `N` in `loadorder.json`:

1. List every global / `volvox.*` symbol the new file reads.
2. Search each symbol's definition and read sites (`rg`).
3. Confirm every symbol it reads is defined by a file loaded before `N`.
4. Confirm no file before `N` reads a symbol first defined by the new file.
5. If a check fails, move the file later, expose the symbol earlier, or keep the code in an existing file.