feat: authoritative plugin fields - fix devFQDN + docs + allow filters and columns on new fields

Signed-off-by: jokob-sk <jokob.sk@gmail.com>

docs/API_DEVICE_FIELD_LOCK.md

@@ -138,36 +138,6 @@ The Device Edit form displays lock/unlock buttons for all tracked fields:
 2. **Unlock Button** (🔓): Click to allow plugin overwrites again
 3. **Source Indicator**: Shows current field source (USER, LOCKED, NEWDEV, or plugin name)
 
-## UI Workflow
-
-### Locking a Field via UI
-
-1. Navigate to Device Details
-2. Find the field you want to protect
-3. Click the lock button (🔒) next to the field
-4. Button changes to unlock (🔓) and source indicator turns red (LOCKED)
-5. Field is now protected from plugin overwrites
-
-### Unlocking a Field via UI
-
-1. Find the locked field (button shows 🔓)
-2. Click the unlock button
-3. Button changes back to lock (🔒) and source resets to NEWDEV
-4. Plugins can now update this field again
-
-## Authorization
-
-All lock/unlock operations require:
-- Valid API token in `Authorization: Bearer {token}` header
-- User must be authenticated to the NetAlertX instance
-
-## Implementation Details
-
-### Backend Logic
-The lock/unlock feature is implemented in:
-- **API Endpoint**: `/server/api_server/api_server_start.py` - `api_device_field_lock()`
-- **Data Model**: `/server/models/device_instance.py` - Authorization checks in `setDeviceData()`
-- **Database**: Devices table with `*Source` columns tracking field origins
 
 ### Authorization Handler
 
@@ -179,6 +149,9 @@ The authoritative field update logic prevents plugin overwrites:
 4. If source is `NEWDEV` or plugin name, plugin update is accepted
 
 ## See Also
+
+- [Device locking](./DEVICE_FIELD_LOCK.md)
+- [Device source fields](./DEVICE_SOURCE_FIELDS.md)
 - [API Device Endpoints Documentation](./API_DEVICE.md)
 - [Authoritative Field Updates System](./PLUGINS_DEV.md#authoritative-fields)
 - [Plugin Configuration Reference](./PLUGINS_DEV_CONFIG.md)

docs/DEVICE_FIELD_LOCK.md

@@ -37,7 +37,12 @@ Each locked field has a "source" indicator that shows you why the value is prote
 | 📡 **NEWDEV** | Default/unset value | Yes, plugins can update |
 | 📡 **Plugin name** | Last updated by a plugin (e.g., UNIFIAPI) | Yes, plugins can update if field in SET_ALWAYS |
 
-## How to Use
+Overwrite rules are
+
+> [!TIP]
+> You can bulk-unlock devices in the [Multi-edit](./DEVICES_BULK_EDITING.md) dialog. This removes all `USER` and `LOCKED` values from all `*Source` fields of selected devices.
+
+## Usage Examples
 
 ### Lock a Field (Prevent Plugin Changes)
 
@@ -147,13 +152,13 @@ Each locked field has a "source" indicator that shows you why the value is prote
 - Check if you accidentally unlocked it
 - Open an issue if it persists
 
-## For More Information
+## See also
 
-- **Technical details:** See [API_DEVICE_FIELD_LOCK.md](API_DEVICE_FIELD_LOCK.md)
-- **Plugin configuration:** See [PLUGINS_DEV_CONFIG.md](PLUGINS_DEV_CONFIG.md)
-- **Admin guide:** See [DEVICE_MANAGEMENT.md](DEVICE_MANAGEMENT.md)
-
----
-
-**Quick Start:** Find a device field you want to protect → Click the lock icon → That's it! The field won't change until you unlock it.
+- [Device locking](./DEVICE_FIELD_LOCK.md)
+- [Device source fields](./DEVICE_SOURCE_FIELDS.md)
+- [API Device Endpoints Documentation](./API_DEVICE.md)
+- [Authoritative Field Updates System](./PLUGINS_DEV.md#authoritative-fields)
+- [Plugin Configuration Reference](./PLUGINS_DEV_CONFIG.md)
+- [Device locking APIs](API_DEVICE_FIELD_LOCK.md)
+- [Device management](DEVICE_MANAGEMENT.md)
 

docs/DEVICE_SOURCE_FIELDS.md

@@ -0,0 +1,67 @@
+# Understanding Device Source Fields and Field Updates
+
+When the system scans a network, it finds various details about devices (like names, IP addresses, and manufacturers). To ensure the data remains accurate without accidentally overwriting manual changes, the system uses a set of "Source Rules."
+
+![Field source and locks](./img/DEVICE_MANAGEMENT/field_sources_and_locks.png)
+
+---
+
+## The "Protection" Levels
+
+Every piece of information for a device has a **Source**. This source determines whether a new scan is allowed to change that value.
+
+| Source Status | Description | Can a Scan Overwrite it? |
+| --- | --- | --- |
+| **USER** | You manually entered this value. | **Never** |
+| **LOCKED** | This value is pinned and protected. | **Never** |
+| **NEWDEV** | This value was initialized from `NEWDEV` plugin settings. | **Always** |
+| **(Plugin Name)** | The value was found by a specific scanner (e.g., `NBTSCAN`). | **Only if specific rules are met** |
+
+---
+
+## How Scans Update Information
+
+If a field is **not** protected by a `USER` or `LOCKED` status, the system follows these rules to decide if it should update the info:
+
+### 1. The "Empty Field" Rule (Default)
+
+By default, the system is cautious. It will only fill in a piece of information if the current field is **empty** (showing as "unknown," "0.0.0.0," or blank). It won't change for example an existing name unless you tell it to.
+
+### 2. SET_ALWAYS
+
+Some plugins are configured to be "authoritative." If a field is in the **SET_ALWAYS** setting of a plugin:
+
+* The scanner will **always** overwrite the current value with the new one.
+* *Note: It will still never overwrite a `USER` or `LOCKED` field.*
+
+### 3. SET_EMPTY
+
+If a field is in the **SET_EMPTY** list:
+
+* The scanner will **only** provide a value if the current field is currently empty.
+* This is used for fields where we want to "fill in the blanks" but never change a value once it has been established by any source.
+
+### 4. Automatic Overrides (Live Tracking)
+
+Some fields, like **IP Addresses** (`devLastIP`) and **Full Domain Names** (`devFQDN`), are set to automatically update whenever they change. This ensures that if a device moves to a new IP on your network, the system reflects that change immediately without you having to do anything.
+
+---
+
+## Summary of Field Logic
+
+| If the current value is... | And the Scan finds... | Does it update? |
+| --- | --- | --- |
+| **USER / LOCKED** | Anything | **No** |
+| **Empty** | A new value | **Yes** |
+| **A "Plugin" value** | A different value | **No** (Unless `SET_ALWAYS` is on) |
+| **An IP Address** | A different IP | **Yes** (Updates automatically) |
+
+## See also:
+
+- [Device locking](./DEVICE_FIELD_LOCK.md)
+- [Device source fields](./DEVICE_SOURCE_FIELDS.md)
+- [API Device Endpoints Documentation](./API_DEVICE.md)
+- [Authoritative Field Updates System](./PLUGINS_DEV.md#authoritative-fields)
+- [Plugin Configuration Reference](./PLUGINS_DEV_CONFIG.md)
+- [Device locking APIs](API_DEVICE_FIELD_LOCK.md)
+- [Device management](DEVICE_MANAGEMENT.md)