FE+DOCS: custom props icon select fix + docs cleanup

.claude/skills/plugin-readme/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: plugin-readme
+description: Write or review a NetAlertX plugin's README.md (server/plugins/<code_name>/README.md). Use this when asked to create, enhance, audit, or clean up a plugin README, or plugin docs generally.
+---
+
+# Plugin README Documentation
+
+## Structure
+
+- `## Overview` — prose: what the plugin does and why, 1-3 sentences. Link out to a full guide under `docs/*.md` if one exists for this topic.
+- `### Requirements` / `### Prerequisites` (optional) — only when there's a real precondition beyond installing the app (credentials, specific hardware/firmware, host networking, a third-party account).
+- `### Usage` — how a user actually engages with the plugin: where to enable it, the overall flow, which non-obvious values they need to go find elsewhere (e.g. "grab your API key from your provider's dashboard"). Not a settings reference table.
+- `### Notes` (optional) — caveats, gotchas, limitations, similar/related plugins worth cross-linking.
+- `## Other info` (optional) — Version / Author / Maintainer(s) / Release Date. **Never drop this when rewriting a README** - if it's there, carry it forward verbatim even if you're rewriting everything else.
+
+## The core rule: don't re-document settings
+
+Every setting already gets a name and description shown directly in the Settings UI, generated straight from `config.json`. A README that re-lists each setting with its key and default value duplicates that and drifts out of sync the moment `config.json` changes — the UI is the single source of truth for field-level docs, not the README.
+
+Exception: call out a *specific* setting by name, in prose, only when its behavior is genuinely non-obvious - e.g. a setting whose name doesn't match what it actually holds (`_publisher_telegram`'s `HOST` setting is actually the chat ID, `URL` is the bot token), a recommended value or schedule, or an upstream bug tied to a specific value (see `unifi_import`'s `UNFIMP_version`/`UNFIMP_port` note). Don't turn this into a table of every field "just in case" - if you're listing more than one or two settings, ask whether that content belongs in the UI's per-field description instead.
+
+## Verify against the actual code first
+
+Read `config.json` (`unique_prefix`, `plugin_type`, `data_source`, `settings`) and the plugin's script before writing anything - don't guess at mechanism from the plugin's name alone. Real bugs found this way during a past audit: `dig_scan/README.md` described the `nbtscan` utility (copy-paste from a sibling plugin); `adguard_import/README.md` was a byte-for-byte copy of `__template/README.md`, never actually written.
+
+## Backfilling missing "Other info"
+
+Before concluding a plugin has no attribution to record, grep its script for a credit comment (e.g. `grep -rn "Based on\|Author:" server/plugins/<code_name>/*.py`) - two plugins (`dhcp_servers`, `website_monitor`) had `# Based on the work of https://github.com/leiweibau/Pi.Alert` in the script that nothing in the README reflected. Do **not** use `git log --diff-filter=A` "who first added this file" as an attribution source - `server/plugins/` has at least one bulk restructuring commit, so several unrelated plugins share the same "first added" date/author despite having nothing to do with each other. If you can't verify authorship from an in-source comment or an existing (already-correct) README, leave the section out rather than guess - most first-party/core plugins (`maintenance`, `custom_props`, `db_cleanup`, `set_password`, etc.) simply don't have one, which is the correct, honest state.
+
+## Cross-linking convention
+
+- Link to a top-level docs page: `https://docs.netalertx.com/PAGE_NAME`. Never `/docs/PAGE_NAME.md` or a `github.com/.../tree/main/...` URL - both break once the README is rendered inside the docs site (`docs/gen_plugin_pages.py` generates it at a different path than the repo, so repo-relative and GitHub-tree links don't resolve there).
+- Link to *another plugin's* README: `https://docs.netalertx.com/plugins/<code_name>` (matches the page `docs/gen_plugin_pages.py` generates for it). Never a GitHub tree URL.
+- If a `docs/*.md` guide is dedicated to (or shared by) this plugin, link both directions - plugin → guide, and guide → plugin. Check the other side actually links back; it's easy to add one direction and forget the other (e.g. `PIHOLE_GUIDE.md` linked to four Pi-hole plugins, none of which linked back, until this was audited).
+- If a sibling plugin is easily confused with this one (`unifi_import` vs `unifi_api_import`, `dig_scan` vs `nslookup_scan`, `adguard_export` vs `adguard_import`), say so in one sentence and link it - which one to prefer and why.
+
+## Common defects to check for when auditing existing READMEs
+
+- Template leftovers: grep for `Plugin name`, `<your github handle>`, `Some tip.`, `PREF_RUN` - a sign the README was never actually written. Diff against `server/plugins/__template/README.md` if unsure.
+- Content copy-pasted from a sibling plugin without updating the tool/utility name.
+- `TBC` or similarly empty content, especially for a prominent feature.
+- Duplicate or orphaned sections (e.g. two `### Usage` headings) - usually a merge/edit artifact.
+- Sibling non-README files (a provider-specific sub-guide, a translated `README_<LANG>.md`) that aren't linked from the plugin's own `README.md` - `docs/gen_plugin_pages.py` generates a page for every `*.md` in the plugin folder, but only reachable if something links to it.
+
+## Reference
+
+- Repo-wide plugin catalog with icon/type legend: `docs/PLUGINS.md`
+- Full plugin authoring reference (settings schema, execution phases, data contract): `docs/PLUGINS_DEV.md` and the `plugin-development` skill.

.gemini/skills/plugin-readme/plugin-readme-skill.md

@@ -0,0 +1,48 @@
+---
+name: netalertx-plugin-readme
+description: Write or review a NetAlertX plugin's README.md (server/plugins/<code_name>/README.md). Use this when asked to create, enhance, audit, or clean up a plugin README, or plugin docs generally.
+---
+
+# Plugin README Documentation
+
+## Structure
+
+- `## Overview` — prose: what the plugin does and why, 1-3 sentences. Link out to a full guide under `docs/*.md` if one exists for this topic.
+- `### Requirements` / `### Prerequisites` (optional) — only when there's a real precondition beyond installing the app (credentials, specific hardware/firmware, host networking, a third-party account).
+- `### Usage` — how a user actually engages with the plugin: where to enable it, the overall flow, which non-obvious values they need to go find elsewhere (e.g. "grab your API key from your provider's dashboard"). Not a settings reference table.
+- `### Notes` (optional) — caveats, gotchas, limitations, similar/related plugins worth cross-linking.
+- `## Other info` (optional) — Version / Author / Maintainer(s) / Release Date. **Never drop this when rewriting a README** - if it's there, carry it forward verbatim even if you're rewriting everything else.
+
+## The core rule: don't re-document settings
+
+Every setting already gets a name and description shown directly in the Settings UI, generated straight from `config.json`. A README that re-lists each setting with its key and default value duplicates that and drifts out of sync the moment `config.json` changes — the UI is the single source of truth for field-level docs, not the README.
+
+Exception: call out a *specific* setting by name, in prose, only when its behavior is genuinely non-obvious - e.g. a setting whose name doesn't match what it actually holds (`_publisher_telegram`'s `HOST` setting is actually the chat ID, `URL` is the bot token), a recommended value or schedule, or an upstream bug tied to a specific value (see `unifi_import`'s `UNFIMP_version`/`UNFIMP_port` note). Don't turn this into a table of every field "just in case" - if you're listing more than one or two settings, ask whether that content belongs in the UI's per-field description instead.
+
+## Verify against the actual code first
+
+Read `config.json` (`unique_prefix`, `plugin_type`, `data_source`, `settings`) and the plugin's script before writing anything - don't guess at mechanism from the plugin's name alone. Real bugs found this way during a past audit: `dig_scan/README.md` described the `nbtscan` utility (copy-paste from a sibling plugin); `adguard_import/README.md` was a byte-for-byte copy of `__template/README.md`, never actually written.
+
+## Backfilling missing "Other info"
+
+Before concluding a plugin has no attribution to record, grep its script for a credit comment (e.g. `grep -rn "Based on\|Author:" server/plugins/<code_name>/*.py`) - two plugins (`dhcp_servers`, `website_monitor`) had `# Based on the work of https://github.com/leiweibau/Pi.Alert` in the script that nothing in the README reflected. Do **not** use `git log --diff-filter=A` "who first added this file" as an attribution source - `server/plugins/` has at least one bulk restructuring commit, so several unrelated plugins share the same "first added" date/author despite having nothing to do with each other. If you can't verify authorship from an in-source comment or an existing (already-correct) README, leave the section out rather than guess - most first-party/core plugins (`maintenance`, `custom_props`, `db_cleanup`, `set_password`, etc.) simply don't have one, which is the correct, honest state.
+
+## Cross-linking convention
+
+- Link to a top-level docs page: `https://docs.netalertx.com/PAGE_NAME`. Never `/docs/PAGE_NAME.md` or a `github.com/.../tree/main/...` URL - both break once the README is rendered inside the docs site (`docs/gen_plugin_pages.py` generates it at a different path than the repo, so repo-relative and GitHub-tree links don't resolve there).
+- Link to *another plugin's* README: `https://docs.netalertx.com/plugins/<code_name>` (matches the page `docs/gen_plugin_pages.py` generates for it). Never a GitHub tree URL.
+- If a `docs/*.md` guide is dedicated to (or shared by) this plugin, link both directions - plugin → guide, and guide → plugin. Check the other side actually links back; it's easy to add one direction and forget the other (e.g. `PIHOLE_GUIDE.md` linked to four Pi-hole plugins, none of which linked back, until this was audited).
+- If a sibling plugin is easily confused with this one (`unifi_import` vs `unifi_api_import`, `dig_scan` vs `nslookup_scan`, `adguard_export` vs `adguard_import`), say so in one sentence and link it - which one to prefer and why.
+
+## Common defects to check for when auditing existing READMEs
+
+- Template leftovers: grep for `Plugin name`, `<your github handle>`, `Some tip.`, `PREF_RUN` - a sign the README was never actually written. Diff against `server/plugins/__template/README.md` if unsure.
+- Content copy-pasted from a sibling plugin without updating the tool/utility name.
+- `TBC` or similarly empty content, especially for a prominent feature.
+- Duplicate or orphaned sections (e.g. two `### Usage` headings) - usually a merge/edit artifact.
+- Sibling non-README files (a provider-specific sub-guide, a translated `README_<LANG>.md`) that aren't linked from the plugin's own `README.md` - `docs/gen_plugin_pages.py` generates a page for every `*.md` in the plugin folder, but only reachable if something links to it.
+
+## Reference
+
+- Repo-wide plugin catalog with icon/type legend: `docs/PLUGINS.md`
+- Full plugin authoring reference (settings schema, execution phases, data contract): `docs/PLUGINS_DEV.md` and the `plugin-development` skill.

.gemini/skills/skills-index/SKILL.md

@@ -24,6 +24,7 @@ Skills with the same purpose exist in more than one, sometimes under different n
 | MCP activation | `mcp-activation` | `mcp-activation` | — | Gemini version covers Gemini CLI session restart; Copilot version covers VS Code window reload |
 | Project navigation | `project-navigation` | `project-navigation` | — | Copilot version has full path tables and env vars; Gemini version is a brief reference |
 | Plugin dev | `plugin-development` | `plugin-run-development` | `plugin-development` | All three cover data contract, phases, formats, the `RUN_TIMEOUT` kill-timer gotcha (`timeoutMultiplier`/`per_item_timeout()`), and a pre-PR pointer to the Conventions Checklist in `docs/PLUGINS_DEV.md` |
+| Plugin README docs | `plugin-readme` | `plugin-readme` | `plugin-readme` | All three cover README structure, the "don't re-document settings" rule, the `docs.netalertx.com` cross-linking convention, and common defects (template leftovers, copy-paste errors) found during a full-repo audit |
 | Devcontainer | `devcontainer-management` | `devcontainer-services` + `devcontainer-setup` + `devcontainer-configs` | — | Gemini combines into one (uses `docker exec`); Copilot splits into 3 focused skills |
 | PR review | `pr-analysis` | `pr-analysis` | `pr-analysis` | How to classify and respond to PR comments; pre-flight skill loading checklist |
 | Logging | `logging-standards` | `logging-standards` | — | `mylog` levels, message format, what not to log |

.github/copilot-instructions.md

@@ -35,6 +35,7 @@ Procedural knowledge lives in `.github/skills/`. Load the appropriate skill when
 | Build Docker images | `docker-build` |
 | Reprovision devcontainer | `devcontainer-setup` |
 | Create or run plugins | `plugin-run-development` |
+| Write or review a plugin README | `plugin-readme` |
 | Analyze PR comments | `pr-analysis` |
 | Clean Docker resources | `docker-prune` |
 | Generate devcontainer configs | `devcontainer-configs` |

.github/skills/plugin-readme/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: netalertx-plugin-readme
+description: Write or review a NetAlertX plugin's README.md (server/plugins/<code_name>/README.md). Use this when asked to create, enhance, audit, or clean up a plugin README, or plugin docs generally.
+---
+
+# Plugin README Documentation
+
+## Structure
+
+- `## Overview` — prose: what the plugin does and why, 1-3 sentences. Link out to a full guide under `docs/*.md` if one exists for this topic.
+- `### Requirements` / `### Prerequisites` (optional) — only when there's a real precondition beyond installing the app (credentials, specific hardware/firmware, host networking, a third-party account).
+- `### Usage` — how a user actually engages with the plugin: where to enable it, the overall flow, which non-obvious values they need to go find elsewhere (e.g. "grab your API key from your provider's dashboard"). Not a settings reference table.
+- `### Notes` (optional) — caveats, gotchas, limitations, similar/related plugins worth cross-linking.
+- `## Other info` (optional) — Version / Author / Maintainer(s) / Release Date. **Never drop this when rewriting a README** - if it's there, carry it forward verbatim even if you're rewriting everything else.
+
+## The core rule: don't re-document settings
+
+Every setting already gets a name and description shown directly in the Settings UI, generated straight from `config.json`. A README that re-lists each setting with its key and default value duplicates that and drifts out of sync the moment `config.json` changes — the UI is the single source of truth for field-level docs, not the README.
+
+Exception: call out a *specific* setting by name, in prose, only when its behavior is genuinely non-obvious - e.g. a setting whose name doesn't match what it actually holds (`_publisher_telegram`'s `HOST` setting is actually the chat ID, `URL` is the bot token), a recommended value or schedule, or an upstream bug tied to a specific value (see `unifi_import`'s `UNFIMP_version`/`UNFIMP_port` note). Don't turn this into a table of every field "just in case" - if you're listing more than one or two settings, ask whether that content belongs in the UI's per-field description instead.
+
+## Verify against the actual code first
+
+Read `config.json` (`unique_prefix`, `plugin_type`, `data_source`, `settings`) and the plugin's script before writing anything - don't guess at mechanism from the plugin's name alone. Real bugs found this way during a past audit: `dig_scan/README.md` described the `nbtscan` utility (copy-paste from a sibling plugin); `adguard_import/README.md` was a byte-for-byte copy of `__template/README.md`, never actually written.
+
+## Backfilling missing "Other info"
+
+Before concluding a plugin has no attribution to record, grep its script for a credit comment (e.g. `grep -rn "Based on\|Author:" server/plugins/<code_name>/*.py`) - two plugins (`dhcp_servers`, `website_monitor`) had `# Based on the work of https://github.com/leiweibau/Pi.Alert` in the script that nothing in the README reflected. Do **not** use `git log --diff-filter=A` "who first added this file" as an attribution source - `server/plugins/` has at least one bulk restructuring commit, so several unrelated plugins share the same "first added" date/author despite having nothing to do with each other. If you can't verify authorship from an in-source comment or an existing (already-correct) README, leave the section out rather than guess - most first-party/core plugins (`maintenance`, `custom_props`, `db_cleanup`, `set_password`, etc.) simply don't have one, which is the correct, honest state.
+
+## Cross-linking convention
+
+- Link to a top-level docs page: `https://docs.netalertx.com/PAGE_NAME`. Never `/docs/PAGE_NAME.md` or a `github.com/.../tree/main/...` URL - both break once the README is rendered inside the docs site (`docs/gen_plugin_pages.py` generates it at a different path than the repo, so repo-relative and GitHub-tree links don't resolve there).
+- Link to *another plugin's* README: `https://docs.netalertx.com/plugins/<code_name>` (matches the page `docs/gen_plugin_pages.py` generates for it). Never a GitHub tree URL.
+- If a `docs/*.md` guide is dedicated to (or shared by) this plugin, link both directions - plugin → guide, and guide → plugin. Check the other side actually links back; it's easy to add one direction and forget the other (e.g. `PIHOLE_GUIDE.md` linked to four Pi-hole plugins, none of which linked back, until this was audited).
+- If a sibling plugin is easily confused with this one (`unifi_import` vs `unifi_api_import`, `dig_scan` vs `nslookup_scan`, `adguard_export` vs `adguard_import`), say so in one sentence and link it - which one to prefer and why.
+
+## Common defects to check for when auditing existing READMEs
+
+- Template leftovers: grep for `Plugin name`, `<your github handle>`, `Some tip.`, `PREF_RUN` - a sign the README was never actually written. Diff against `server/plugins/__template/README.md` if unsure.
+- Content copy-pasted from a sibling plugin without updating the tool/utility name.
+- `TBC` or similarly empty content, especially for a prominent feature.
+- Duplicate or orphaned sections (e.g. two `### Usage` headings) - usually a merge/edit artifact.
+- Sibling non-README files (a provider-specific sub-guide, a translated `README_<LANG>.md`) that aren't linked from the plugin's own `README.md` - `docs/gen_plugin_pages.py` generates a page for every `*.md` in the plugin folder, but only reachable if something links to it.
+
+## Reference
+
+- Repo-wide plugin catalog with icon/type legend: `docs/PLUGINS.md`
+- Full plugin authoring reference (settings schema, execution phases, data contract): `docs/PLUGINS_DEV.md` and the `plugin-development` skill.

.github/skills/skills-overview/SKILL.md

@@ -24,6 +24,7 @@ Skills with the same purpose exist in more than one, sometimes under different n
 | MCP activation | `mcp-activation` | `mcp-activation` | — | Copilot version covers VS Code window reload; Gemini version covers Gemini CLI session restart |
 | Project navigation | `project-navigation` | `project-navigation` | — | Copilot version has full path tables and env vars; Gemini version is a brief reference |
 | Plugin dev | `plugin-run-development` | `plugin-development` | `plugin-development` | All three cover data contract, phases, formats, the `RUN_TIMEOUT` kill-timer gotcha (`timeoutMultiplier`/`per_item_timeout()`), and a pre-PR pointer to the Conventions Checklist in `docs/PLUGINS_DEV.md` |
+| Plugin README docs | `plugin-readme` | `plugin-readme` | `plugin-readme` | All three cover README structure, the "don't re-document settings" rule, the `docs.netalertx.com` cross-linking convention, and common defects (template leftovers, copy-paste errors) found during a full-repo audit |
 | Devcontainer | `devcontainer-services` + `devcontainer-setup` + `devcontainer-configs` | `devcontainer-management` | — | Copilot splits into 3 focused skills; Gemini combines into one (uses `docker exec`) |
 | PR review | `pr-analysis` | `pr-analysis` | `pr-analysis` | How to classify and respond to PR comments; pre-flight skill loading checklist |
 | Logging | `logging-standards` | `logging-standards` | — | `mylog` levels, message format, what not to log |

.github/workflows/mkdocs.yml

@@ -26,7 +26,9 @@ jobs:
             mkdocs==1.6.0 \
             mkdocs-material==9.5.21 \
             mkdocs-github-admonitions-plugin==0.1.1 \
-            mkdocs-glightbox
+            mkdocs-glightbox \
+            mkdocs-gen-files \
+            mkdocs-literate-nav
 
       - name: Build MkDocs
         run: mkdocs build

docs/ADVISORY_MULTI_NETWORK.md

@@ -8,7 +8,7 @@ Effective multi-network monitoring starts with understanding how NetAlertX "sees
 * **B. Plan Subnet & Scan Interfaces:** Explicitly configure each accessible segment in `SCAN_SUBNETS` with the corresponding interfaces.
 * **C. Remote & Inaccessible Networks:** For networks unreachable via ARP, use these strategies:
 * **Alternate Plugins:** Supplement discovery with [SNMPDSC](https://docs.netalertx.com/PLUGINS/?h=SNMPDSC#available-plugins) or [DHCP lease imports](https://docs.netalertx.com/PLUGINS/?h=DHCPLSS#available-plugins).
-* **Sync Hub for MSP & Multi-Site Deployments:** Run secondary NetAlertX instances on isolated networks and aggregate data using the **SYNC plugin**. Use the [`SYNC_BEHAVIOR`](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/sync/README.md#hub-device-write-behavior-sync_behavior) setting on the hub to control whether the hub inherits device config from nodes or manages it independently.
+* **Sync Hub for MSP & Multi-Site Deployments:** Run secondary NetAlertX instances on isolated networks and aggregate data using the **SYNC plugin**. Use the [`SYNC_BEHAVIOR`](https://docs.netalertx.com/plugins/sync#hub-device-write-behavior-sync_behavior) setting on the hub to control whether the hub inherits device config from nodes or manages it independently.
 * **Manual Entry:** For static assets where only ICMP (ping) status is needed.
 
 > [!TIP]

docs/ADVISORY_MULTI_SITE_MONITORING.md

@@ -127,7 +127,7 @@ For best results in multi-site environments:
 ## Related Documentation
 
 * [Remote Networks](./REMOTE_NETWORKS.md)
-* [Sync Hub Plugin](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/sync/README.md)
+* [Sync Hub Plugin](https://docs.netalertx.com/plugins/sync)
 * [Workflows](./WORKFLOWS.md)
 * [Metrics API](./API_METRICS.md)
 * [Eyes on Glass / NOC Dashboard](./ADVISORY_EYES_ON_GLASS.md)

docs/API_SYNC.md

@@ -135,5 +135,5 @@ The `SYNC_BEHAVIOR` setting controls how the hub writes devices received from no
 | `carbon-copy` | | All MACs every sync (UPSERT) |
 | `hub-defaults` | | None — hub pipeline handles it |
 
-For full details and per-mode behaviour, see [SYNC plugin README — Hub Device-Write Behavior](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/sync/README.md#hub-device-write-behavior-sync_behavior).
+For full details and per-mode behaviour, see [SYNC plugin README — Hub Device-Write Behavior](https://docs.netalertx.com/plugins/sync#hub-device-write-behavior-sync_behavior).
 

docs/BACKUPS.md

@@ -37,7 +37,7 @@ This includes settings for:
 
 ### Device Data
 
-Stored in `/data/config/devices_<timestamp>.csv` or `/data/config/devices.csv`, created by the [CSV Backup `CSVBCKP` Plugin](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/csv_backup).
+Stored in `/data/config/devices_<timestamp>.csv` or `/data/config/devices.csv`, created by the [CSV Backup `CSVBCKP` Plugin](https://docs.netalertx.com/plugins/csv_backup).
 Contains:
 
 * Device names, icons, and categories

docs/HOME_ASSISTANT.md

@@ -9,7 +9,7 @@ NetAlertX includes MQTT support, allowing detected devices to appear as devices
 >
 > * Device discovery in Home Assistant takes approximately 10 seconds **per device**.
 > * Devices removed from NetAlertX are not automatically removed from Home Assistant. Use [MQTT Explorer](https://mqtt-explorer.com/) to delete them from the MQTT broker if required.
-> * For performance reasons, device definitions are not always fully synchronized. To force a complete synchronization, delete the MQTT Plugin Objects as described in the [MQTT plugin](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/_publisher_mqtt#forcing-an-update) documentation.
+> * For performance reasons, device definitions are not always fully synchronized. To force a complete synchronization, delete the MQTT Plugin Objects as described in the [MQTT plugin](https://docs.netalertx.com/plugins/_publisher_mqtt#forcing-an-update) documentation.
 
 ## Mosquitto MQTT setup
 

docs/INITIAL_SETUP.md

@@ -25,7 +25,7 @@ Get **NetAlertX** up and running in a few simple steps.
 
 > [!NOTE]
 > Configure your SMTP settings or enable additional `▶️ publisher` plugins to send alerts.
-> For more flexibility, try [📚 `_publisher_apprise`](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/_publisher_apprise/), which supports over 80 notification services.
+> For more flexibility, try [📚 `_publisher_apprise`](https://docs.netalertx.com/plugins/_publisher_apprise), which supports over 80 notification services.
 
 ---
 

docs/NOTIFICATIONS.md

@@ -50,7 +50,7 @@ In Notification Processing settings, you can specify blanket rules. These allow
 2. Alert down after (`NTFPRCS_alert_down_time`) is useful if you want to wait for some time before the system sends out a down notification for a device. This is related to the on-device **Alert down** setting and only devices with this checked will trigger a down notification.
 3. Alert down after (sleep) (`NTFPRCS_sleep_time`) sets the **sleep window** in minutes. If a device has **Can Sleep** enabled and goes offline, it is shown as **Sleeping** (aqua 🌙 badge) for this many minutes before down-alert logic kicks in. Default is `30` minutes. Changing this setting takes effect after saving — no restart required.
 
-You can filter out unwanted notifications globally. This could be because of a misbehaving device (GoogleNest/GoogleHub (See also [ARPSAN docs and the `--exclude-broadcast` flag](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/arp_scan#ip-flipping-on-google-nest-devices))) which flips between IP addresses, or because you want to ignore new device notifications of a certain pattern.
+You can filter out unwanted notifications globally. This could be because of a misbehaving device (GoogleNest/GoogleHub (See also [ARPSAN docs and the `--exclude-broadcast` flag](https://docs.netalertx.com/plugins/arp_scan#ip-flipping-on-google-nest-devices))) which flips between IP addresses, or because you want to ignore new device notifications of a certain pattern.
 
 1. Events Filter (`NTFPRCS_event_condition`) - Filter out Events from notifications.
 2. New Devices Filter (`NTFPRCS_new_dev_condition`) - Filter out New Devices from notifications, but log and keep a new device in the system.

docs/PERFORMANCE.md

@@ -39,14 +39,14 @@ Two plugins help maintain the system’s performance:
 ### **1. Database Cleanup (DBCLNP)**
 
 * Handles database maintenance and cleanup.
-* See the [DB Cleanup Plugin Docs](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/db_cleanup/README.md).
+* See the [DB Cleanup Plugin Docs](https://docs.netalertx.com/plugins/db_cleanup).
 * Ensure it’s not failing by checking logs.
 * Adjust the schedule (`DBCLNP_RUN_SCHD`) and timeout (`DBCLNP_RUN_TIMEOUT`) if necessary.
 
 ### **2. Maintenance (MAINT)**
 
 * Cleans logs and performs general maintenance tasks.
-* See the [Maintenance Plugin Docs](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/maintenance/README.md).
+* See the [Maintenance Plugin Docs](https://docs.netalertx.com/plugins/maintenance).
 * Verify proper operation via logs.
 * Adjust the schedule (`MAINT_RUN_SCHD`) and timeout (`MAINT_RUN_TIMEOUT`) if needed.
 

docs/PIHOLE_GUIDE.md

@@ -19,7 +19,7 @@ To use this approach, make sure a Web UI password is configured in **Pi-hole**.
 | `PIHOLEAPI_API_MAXCLIENTS` | Maximum number of devices to request from Pi-hole. The default value is usually sufficient.      | `500`                       |
 | `PIHOLEAPI_FAKE_MAC`       | Generate a deterministic fake MAC address from the IP address.                                   | `False`                     |
 
-Check the [PIHOLEAPI plugin README](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/pihole_api_scan/) for additional details and troubleshooting.
+Check the [PIHOLEAPI plugin README](https://docs.netalertx.com/plugins/pihole_api_scan) for additional details and troubleshooting.
 
 ### docker-compose changes
 
@@ -41,7 +41,7 @@ This approach requires mounting the Pi-hole DHCP leases file (`dhcp.leases`) int
 | `DHCPLSS_RUN_SCHD`       | If you run multiple device scanner plugins, configure them to use the same schedule.                                                               | `*/5 * * * *`                 |
 | `DHCPLSS_paths_to_check` | Path to the mapped `dhcp.leases` file inside the container. The path must include `pihole` so the plugin can identify it as a Pi-hole leases file. | `['/etc/pihole/dhcp.leases']` |
 
-Check the [DHCPLSS plugin README](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/dhcp_leases#overview) for additional details.
+Check the [DHCPLSS plugin README](https://docs.netalertx.com/plugins/dhcp_leases#overview) for additional details.
 
 ### docker-compose changes
 
@@ -65,7 +65,7 @@ This approach requires mounting the Pi-hole database file into the NetAlertX con
 | `PIHOLE_RUN_SCHD` | If you run multiple device scanner plugins, configure them to use the same schedule. | `*/5 * * * *`               |
 | `PIHOLE_DB_PATH`  | Path to the mapped Pi-hole database file inside the container.                       | `/etc/pihole/pihole-FTL.db` |
 
-Check the [PIHOLE plugin README](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/pihole_scan) for additional details.
+Check the [PIHOLE plugin README](https://docs.netalertx.com/plugins/pihole_scan) for additional details.
 
 ### docker-compose changes
 
@@ -85,7 +85,7 @@ This plugin's main job is different from the other three above: it watches each
 * **Two Pi-hole instances, not one.** A primary and an optional secondary/failover are both checked and their results combined under one set of settings - useful if you run more than one Pi-hole (e.g. two resolvers for redundancy) and want a single device list and a single anomaly baseline across both, instead of a blind spot on whichever instance isn't being watched.
 * **Choose `PIHOLEAPI`** if you only run one Pi-hole and just want device import - it's the simpler, more focused option. **Choose `PIHOLEMON`** if you want the anomaly detection, or run two Pi-holes needing one configuration, or both.
 
-Check the [PIHOLEMON plugin README](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/pihole_monitor/) for the full settings reference, the `http://` vs `https://` trade-off, and troubleshooting.
+Check the [PIHOLEMON plugin README](https://docs.netalertx.com/plugins/pihole_monitor) for the full settings reference, the `http://` vs `https://` trade-off, and troubleshooting.
 
 ### docker-compose changes
 

docs/PLUGINS.md

@@ -43,57 +43,59 @@ NetAlertX supports additional plugins to extend its functionality, each with its
 
 Device-detecting plugins insert values into the `CurrentScan` database table.  The plugins that are not required are safe to ignore, however, it makes sense to have at least some device-detecting plugins enabled, such as `ARPSCAN` or `NMAPDEV`.
 
+The **Plugin docs** links below open each plugin's README rendered as part of this site (see the [Plugins reference](./plugins/) section) - generated automatically from `server/plugins/<name>/README.md`.
+
 | ID              | Plugin docs                                                                                                      | Type     | Description                               | Features | Required |
 | --------------- | ------------------------------------------------------------------------------------------------------------------ | -------- | ----------------------------------------- | -------- | -------- |
-| `APPRISE`       | [_publisher_apprise](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/_publisher_apprise/)          | ▶️       | Apprise notification proxy                |          |          |
-| `ARPSCAN`       | [arp_scan](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/arp_scan/)                               | 🔍       | ARP-scan on current network               |          |          |
-| `AVAHISCAN`     | [avahi_scan](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/avahi_scan/)                           | 🆎       | Avahi (mDNS-based) name resolution        |          |          |
-| `ASUSWRT`       | [asuswrt_import](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/asuswrt_import/)                   | 📥       | Import connected devices from AsusWRT     |          |          |
-| `CSVBCKP`       | [csv_backup](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/csv_backup/)                           | ⚙        | CSV devices backup                        |          |          |
-| `CUSTPROP`      | [custom_props](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/custom_props/)                       | ⚙        | Managing custom device properties values  |          | Yes      |
-| `DBCLNP`        | [db_cleanup](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/db_cleanup/)                           | ⚙        | Database cleanup                          |          | Yes\*    |
-| `DDNS`          | [ddns_update](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/ddns_update/)                         | ⚙        | DDNS update                               |          |          |
-| `DHCPLSS`       | [dhcp_leases](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/dhcp_leases/)                         | 📥/🆎   | Import devices from DHCP leases           |          |          |
-| `DHCPSRVS`      | [dhcp_servers](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/dhcp_servers/)                       | ♻        | DHCP servers                              |          |          |
-| `DIGSCAN`       | [dig_scan](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/dig_scan/)                               | 🆎       | Dig (DNS) Name resolution                 |          |          |
-| `FREEBOX`       | [freebox](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/freebox/)                                  |📥/♻/🆎  | Pull data and names from Freebox/Iliadbox |          |          |
-| `FRITZBOX`      | [fritzbox](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/fritzbox/)                                | 📥       | Fritz!Box device scanner via TR-064       |          |          |
-| `ICMP`          | [icmp_scan](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/icmp_scan/)                             | ♻        | ICMP (ping) status checker                |          |          |
-| `INTRNT`        | [internet_ip](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/internet_ip/)                         | 🔍       | Internet IP scanner                       |          |          |
-| `INTRSPD`       | [internet_speedtest](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/internet_speedtest/)           | ♻        | Internet speed test                       |          |          |
-| `IPNEIGH`       | [ipneigh](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/ipneigh/)                                  | 🔍       | Scan ARP (IPv4) and NDP (IPv6) tables     |          |          |
-| `KEALSS`        | [kea_api](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/kea_api/)                                  | 📥/🆎     | Pull lease data from the Kea DHCP API   |          |          |
-| `LUCIRPC`       | [luci_import](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/luci_import/)                         | 📥       | Import connected devices from OpenWRT     |          |          |
-| `MAINT`         | [maintenance](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/maintenance/)                          | ⚙        | Maintenance of logs, etc.                 |          |          |
-| `MQTT`          | [_publisher_mqtt](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/_publisher_mqtt/)                | ▶️       | MQTT for syncing to Home Assistant         |          |          |
-| `MTSCAN`        | [mikrotik_scan](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/mikrotik_scan/)                    | 🔍       | Mikrotik device import & sync              |          |          |
-| `NBTSCAN`       | [nbtscan_scan](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/nbtscan_scan/)                       | 🆎       | Nbtscan (NetBIOS-based) name resolution   |          |          |
-| `NEWDEV`        | [newdev_template](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/newdev_template/)                 | ⚙        | New device template                       |          | Yes      |
-| `NMAP`          | [nmap_scan](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/nmap_scan/)                             | ♻        | Nmap port scanning & discovery            |          |          |
-| `NMAPDEV`       | [nmap_dev_scan](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/nmap_dev_scan/)                    | 🔍       | Nmap dev scan on current network           |          |          |
-| `NSLOOKUP`      | [nslookup_scan](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/nslookup_scan/)                     | 🆎       | NSLookup (DNS-based) name resolution      |          |          |
-| `NTFPRCS`       | [notification_processing](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/notification_processing/) | ⚙        | Notification processing                   |          | Yes      |
-| `NTFY`          | [_publisher_ntfy](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/_publisher_ntfy/)                | ▶️       | NTFY notifications                        |          |          |
-| `OMDSDN`        | [omada_sdn_imp](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/omada_sdn_imp/)                    | 📥/🆎 ❌  | UNMAINTAINED use `OMDSDNOPENAPI`        | 🖧 🔄    |          |
-| `OMDSDNOPENAPI` | [omada_sdn_openapi](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/omada_sdn_openapi/)            | 📥/🆎    | OMADA TP-Link import via OpenAPI          | 🖧       |          |
-| `PIHOLE`        | [pihole_scan](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/pihole_scan/)                         | 🆎/📥 | Pi-hole device import & sync               |          |          |
-| `PIHOLEAPI`     | [pihole_api_scan](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/pihole_api_scan/)                 | 🆎/📥 | Pi-hole device import & sync via API v6+   |          |          |
-| `PIHOLEMON`     | [pihole_monitor](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/pihole_monitor/)                   | 🆎/📥 | Blocked-query anomaly detection (includes primary and secondary DNS import from Pi-hole) |          |          |
-| `PUSHSAFER`     | [_publisher_pushsafer](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/_publisher_pushsafer/)      | ▶️       | Pushsafer notifications                   |          |          |
-| `PUSHOVER`      | [_publisher_pushover](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/_publisher_pushover/)        | ▶️       | Pushover notifications                    |          |          |
-| `RSTIMPRT`      | [rest_import](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/rest_import/)                        | 📥/🆎   | Import via a REST API endpoint             |  🖧      |          |
-| `SETPWD`        | [set_password](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/set_password/)                       | ⚙        | Set password                              |          | Yes      |
-| `SMTP`          | [_publisher_email](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/_publisher_email/)              | ▶️       | Email notifications                       |          |          |
-| `SNMPDSC`       | [snmp_discovery](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/snmp_discovery/)                   | 🔍/📥    | SNMP device import & sync                 |          |          |
-| `SYNC`          | [sync](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/sync/)                                      | ⚙/📥     | Sync & import from NetAlertX instances    | 🖧 🔄    | Yes      |
-| `TELEGRAM`      | [_publisher_telegram](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/_publisher_telegram/)        | ▶️       | Telegram notifications                    |          |          |
-| `UI`            | [ui_settings](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/ui_settings/)                         | ♻        | UI specific settings                      |          | Yes      |
-| `UNFIMP`        | [unifi_import](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/unifi_import/)                       | 📥/🆎 | UniFi device import & sync                  | 🖧       |          |
-| `UNIFIAPI`      | [unifi_api_import](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/unifi_api_import/)               | 📥/🆎 | UniFi device import (SM API, multi-site)   |           |         |
-| `VNDRPDT`       | [vendor_update](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/vendor_update/)                     | ⚙        | Vendor database update                    |          |          |
-| `WEBHOOK`       | [_publisher_webhook](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/_publisher_webhook/)          | ▶️       | Webhook notifications                     |          |          |
-| `WEBMON`        | [website_monitor](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/website_monitor/)                 | ♻        | Website down monitoring                   |          |          |
-| `WOL`           | [wake_on_lan](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/wake_on_lan/)                        | ♻        | Automatic wake-on-lan                     |          |          |
+| `APPRISE`       | [_publisher_apprise](plugins/_publisher_apprise.md)          | ▶️       | Apprise notification proxy                |          |          |
+| `ARPSCAN`       | [arp_scan](plugins/arp_scan.md)                               | 🔍       | ARP-scan on current network               |          |          |
+| `AVAHISCAN`     | [avahi_scan](plugins/avahi_scan.md)                           | 🆎       | Avahi (mDNS-based) name resolution        |          |          |
+| `ASUSWRT`       | [asuswrt_import](plugins/asuswrt_import.md)                   | 📥       | Import connected devices from AsusWRT     |          |          |
+| `CSVBCKP`       | [csv_backup](plugins/csv_backup.md)                           | ⚙        | CSV devices backup                        |          |          |
+| `CUSTPROP`      | [custom_props](plugins/custom_props.md)                       | ⚙        | Managing custom device properties values  |          | Yes      |
+| `DBCLNP`        | [db_cleanup](plugins/db_cleanup.md)                           | ⚙        | Database cleanup                          |          | Yes\*    |
+| `DDNS`          | [ddns_update](plugins/ddns_update.md)                         | ⚙        | DDNS update                               |          |          |
+| `DHCPLSS`       | [dhcp_leases](plugins/dhcp_leases.md)                         | 📥/🆎   | Import devices from DHCP leases           |          |          |
+| `DHCPSRVS`      | [dhcp_servers](plugins/dhcp_servers.md)                       | ♻        | DHCP servers                              |          |          |
+| `DIGSCAN`       | [dig_scan](plugins/dig_scan.md)                               | 🆎       | Dig (DNS) Name resolution                 |          |          |
+| `FREEBOX`       | [freebox](plugins/freebox.md)                                  |📥/♻/🆎  | Pull data and names from Freebox/Iliadbox |          |          |
+| `FRITZBOX`      | [fritzbox](plugins/fritzbox.md)                                | 📥       | Fritz!Box device scanner via TR-064       |          |          |
+| `ICMP`          | [icmp_scan](plugins/icmp_scan.md)                             | ♻        | ICMP (ping) status checker                |          |          |
+| `INTRNT`        | [internet_ip](plugins/internet_ip.md)                         | 🔍       | Internet IP scanner                       |          |          |
+| `INTRSPD`       | [internet_speedtest](plugins/internet_speedtest.md)           | ♻        | Internet speed test                       |          |          |
+| `IPNEIGH`       | [ipneigh](plugins/ipneigh.md)                                  | 🔍       | Scan ARP (IPv4) and NDP (IPv6) tables     |          |          |
+| `KEALSS`        | [kea_api](plugins/kea_api.md)                                  | 📥/🆎     | Pull lease data from the Kea DHCP API   |          |          |
+| `LUCIRPC`       | [luci_import](plugins/luci_import.md)                         | 📥       | Import connected devices from OpenWRT     |          |          |
+| `MAINT`         | [maintenance](plugins/maintenance.md)                          | ⚙        | Maintenance of logs, etc.                 |          |          |
+| `MQTT`          | [_publisher_mqtt](plugins/_publisher_mqtt.md)                | ▶️       | MQTT for syncing to Home Assistant         |          |          |
+| `MTSCAN`        | [mikrotik_scan](plugins/mikrotik_scan.md)                    | 🔍       | Mikrotik device import & sync              |          |          |
+| `NBTSCAN`       | [nbtscan_scan](plugins/nbtscan_scan.md)                       | 🆎       | Nbtscan (NetBIOS-based) name resolution   |          |          |
+| `NEWDEV`        | [newdev_template](plugins/newdev_template.md)                 | ⚙        | New device template                       |          | Yes      |
+| `NMAP`          | [nmap_scan](plugins/nmap_scan.md)                             | ♻        | Nmap port scanning & discovery            |          |          |
+| `NMAPDEV`       | [nmap_dev_scan](plugins/nmap_dev_scan.md)                    | 🔍       | Nmap dev scan on current network           |          |          |
+| `NSLOOKUP`      | [nslookup_scan](plugins/nslookup_scan.md)                     | 🆎       | NSLookup (DNS-based) name resolution      |          |          |
+| `NTFPRCS`       | [notification_processing](plugins/notification_processing.md) | ⚙        | Notification processing                   |          | Yes      |
+| `NTFY`          | [_publisher_ntfy](plugins/_publisher_ntfy.md)                | ▶️       | NTFY notifications                        |          |          |
+| `OMDSDN`        | [omada_sdn_imp](plugins/omada_sdn_imp.md)                    | 📥/🆎 ❌  | UNMAINTAINED use `OMDSDNOPENAPI`        | 🖧 🔄    |          |
+| `OMDSDNOPENAPI` | [omada_sdn_openapi](plugins/omada_sdn_openapi.md)            | 📥/🆎    | OMADA TP-Link import via OpenAPI          | 🖧       |          |
+| `PIHOLE`        | [pihole_scan](plugins/pihole_scan.md)                         | 🆎/📥 | Pi-hole device import & sync               |          |          |
+| `PIHOLEAPI`     | [pihole_api_scan](plugins/pihole_api_scan.md)                 | 🆎/📥 | Pi-hole device import & sync via API v6+   |          |          |
+| `PIHOLEMON`     | [pihole_monitor](plugins/pihole_monitor.md)                   | 🆎/📥 | Blocked-query anomaly detection (includes primary and secondary DNS import from Pi-hole) |          |          |
+| `PUSHSAFER`     | [_publisher_pushsafer](plugins/_publisher_pushsafer.md)      | ▶️       | Pushsafer notifications                   |          |          |
+| `PUSHOVER`      | [_publisher_pushover](plugins/_publisher_pushover.md)        | ▶️       | Pushover notifications                    |          |          |
+| `RSTIMPRT`      | [rest_import](plugins/rest_import.md)                        | 📥/🆎   | Import via a REST API endpoint             |  🖧      |          |
+| `SETPWD`        | [set_password](plugins/set_password.md)                       | ⚙        | Set password                              |          | Yes      |
+| `SMTP`          | [_publisher_email](plugins/_publisher_email.md)              | ▶️       | Email notifications                       |          |          |
+| `SNMPDSC`       | [snmp_discovery](plugins/snmp_discovery.md)                   | 🔍/📥    | SNMP device import & sync                 |          |          |
+| `SYNC`          | [sync](plugins/sync.md)                                      | ⚙/📥     | Sync & import from NetAlertX instances    | 🖧 🔄    | Yes      |
+| `TELEGRAM`      | [_publisher_telegram](plugins/_publisher_telegram.md)        | ▶️       | Telegram notifications                    |          |          |
+| `UI`            | [ui_settings](plugins/ui_settings.md)                         | ♻        | UI specific settings                      |          | Yes      |
+| `UNFIMP`        | [unifi_import](plugins/unifi_import.md)                       | 📥/🆎 | UniFi device import & sync                  | 🖧       |          |
+| `UNIFIAPI`      | [unifi_api_import](plugins/unifi_api_import.md)               | 📥/🆎 | UniFi device import (SM API, multi-site)   |           |         |
+| `VNDRPDT`       | [vendor_update](plugins/vendor_update.md)                     | ⚙        | Vendor database update                    |          |          |
+| `WEBHOOK`       | [_publisher_webhook](plugins/_publisher_webhook.md)          | ▶️       | Webhook notifications                     |          |          |
+| `WEBMON`        | [website_monitor](plugins/website_monitor.md)                 | ♻        | Website down monitoring                   |          |          |
+| `WOL`           | [wake_on_lan](plugins/wake_on_lan.md)                        | ♻        | Automatic wake-on-lan                     |          |          |
 
 
 > \* The database cleanup plugin (`DBCLNP`) is not _required_ but the app will become unusable after a while if not executed.
@@ -121,4 +123,4 @@ Plugins can be enabled via Settings, and can be disabled as needed.
 
 ## 🆕 Developing new custom plugins
 
-If you want to develop a custom plugin, please read this [Plugin development guide](./PLUGINS_DEV.md).
+If you want to develop a custom plugin, please read this [Plugin development guide](./PLUGINS_DEV.md).

docs/REMOTE_NETWORKS.md

@@ -58,10 +58,10 @@ Using supplementing plugins that employ alternate discovery methods is one of th
 
 ### Workaround: Multiple NetAlertX Instances if you have servers in all networks
 
-If you have servers in different networks, you can set up separate NetAlertX instances on those subnets and synchronize the results into one instance using the [`SYNC` plugin](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/sync).
+If you have servers in different networks, you can set up separate NetAlertX instances on those subnets and synchronize the results into one instance using the [`SYNC` plugin](https://docs.netalertx.com/plugins/sync).
 
 > [!TIP]
-> The [`SYNC_BEHAVIOR`](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/sync/README.md#hub-device-write-behavior-sync_behavior) setting controls how the hub handles newly discovered devices from nodes - whether it inherits node config, overwrites on every sync, or applies its own `NEWDEV` defaults.
+> The [`SYNC_BEHAVIOR`](https://docs.netalertx.com/plugins/sync#hub-device-write-behavior-sync_behavior) setting controls how the hub handles newly discovered devices from nodes - whether it inherits node config, overwrites on every sync, or applies its own `NEWDEV` defaults.
 
 ### Workaround: Manual Entry for devices you can `ping`
 
@@ -78,4 +78,4 @@ Scanning remote networks with NMAP is possible (via the `NMAPDEV` plugin), but s
 
 Because the generated MAC address is derived from the IP address, changing the IP can cause the device to appear as a new device or create duplicate records. If this setting is disabled, devices with a missing MAC addresses will be skipped.
 
-Check the [NMAPDEV plugin](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/nmap_dev_scan) for details.
+Check the [NMAPDEV plugin](https://docs.netalertx.com/plugins/nmap_dev_scan) for details.

docs/REST_IMPORT.md

@@ -3,7 +3,7 @@
 This guide shows you how to configure **OPNsense/Dnsmasq** in the **RSTIMPRT** plugin.
 
 > [!NOTE]
-> See the [detailed documentation for the REST import plugin](https://github.com/netalertx/NetAlertX/tree/main/server/plugins/rest_import/) for additional details.
+> See the [detailed documentation for the REST import plugin](https://docs.netalertx.com/plugins/rest_import) for additional details.
 
 ## 1. Create an OPNsense user
 1. In OPNsense, navigate to **System** → **Access** → **Users**

docs/gen_plugin_pages.py

@@ -0,0 +1,140 @@
+"""Generate docs pages for each plugin from its own README.md (and extras).
+
+Runs at `mkdocs build`/`mkdocs serve` time via the `gen-files` plugin
+(see mkdocs.yml). Every server/plugins/<name>/README.md becomes a virtual
+page at plugins/<name>.md, so the docs site always mirrors the current
+README instead of the two drifting out of sync or docs linking out to
+GitHub. A plugins/SUMMARY.md is generated alongside them for the
+`literate-nav` plugin, which turns it into the "Plugins reference" nav
+section referenced from mkdocs.yml (`plugins/`).
+
+Two things beyond the README text itself get carried over, since a plugin
+folder can contain more than just README.md:
+  - Sibling images (screenshots) are copied to plugins/<slug>/<file>, and
+    any reference to them in the README - absolute repo path, `./relative`,
+    or bare filename - is rewritten to point at the copied location.
+  - Any other *.md file in the same folder (e.g. a provider-specific
+    sub-guide) gets its own generated page at plugins/<slug>/<file>.md,
+    added to the nav under its own first H1 heading (or the filename if it
+    has none).
+
+To exclude a plugin from the generated reference (e.g. a dev scaffold,
+not a real plugin), prefix its folder name with double underscores -
+see the __template skip below.
+"""
+
+import json
+import re
+from pathlib import Path
+
+import mkdocs_gen_files
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+PLUGINS_DIR = REPO_ROOT / "server" / "plugins"
+GITHUB_BLOB_BASE = "https://github.com/netalertx/NetAlertX/blob/main"
+IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"}
+
+nav = mkdocs_gen_files.Nav()
+
+
+def generated_note(source_rel_to_repo):
+    return (
+        "!!! note \"Generated page\"\n"
+        f"    This page mirrors [`{source_rel_to_repo}`]"
+        f"({GITHUB_BLOB_BASE}/{source_rel_to_repo}) and is regenerated on every docs build.\n\n"
+    )
+
+
+for readme_path in sorted(PLUGINS_DIR.glob("*/README.md")):
+    plugin_dir = readme_path.parent
+    slug = plugin_dir.name
+
+    if slug.startswith("__"):
+        continue  # dev scaffolding (e.g. __template), not a real plugin
+
+    config_path = plugin_dir / "config.json"
+    display_name = slug
+    unique_prefix = None
+    if config_path.exists():
+        try:
+            config = json.loads(config_path.read_text(encoding="utf-8"))
+        except (ValueError, OSError):
+            config = {}
+        names = config.get("display_name") or []
+        for entry in names:
+            if entry.get("language_code") == "en_us" and entry.get("string"):
+                display_name = entry["string"]
+                break
+        unique_prefix = config.get("unique_prefix")
+
+    title = f"{display_name} ({unique_prefix})" if unique_prefix else display_name
+
+    doc_path = f"{slug}.md"  # relative to plugins/SUMMARY.md
+    full_doc_path = f"plugins/{doc_path}"
+    source_rel_to_repo = readme_path.relative_to(REPO_ROOT).as_posix()
+
+    nav[title] = doc_path
+
+    readme_text = readme_path.read_text(encoding="utf-8")
+
+    # Copy sibling image assets and rewrite whatever form the README uses to
+    # reference them (absolute repo path, ./relative, or bare filename) to
+    # the copied location - only the README's *text* is otherwise pulled
+    # into the site, so a plugin's local screenshots would 404 silently.
+    for asset_path in sorted(plugin_dir.iterdir()):
+        if asset_path.suffix.lower() not in IMAGE_EXTENSIONS:
+            continue
+        asset_name = asset_path.name
+        with mkdocs_gen_files.open(f"plugins/{slug}/{asset_name}", "wb") as out:
+            out.write(asset_path.read_bytes())
+        readme_text = re.sub(
+            rf'\]\((?:\./|/server/plugins/{re.escape(slug)}/)?{re.escape(asset_name)}\)',
+            f']({slug}/{asset_name})',
+            readme_text,
+        )
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as f:
+        f.write(f"# {title}\n\n")
+        f.write(generated_note(source_rel_to_repo))
+        f.write(readme_text)
+
+    # Point the theme's "edit this page" button at the real source file
+    # instead of the virtual doc path, which doesn't exist in the repo.
+    mkdocs_gen_files.set_edit_path(full_doc_path, f"../{source_rel_to_repo}")
+
+    # Any other markdown file alongside the README is a plugin-specific
+    # sub-guide (e.g. dhcp_leases/ASUS_ROUTERS.md) - give it its own page
+    # too, rather than leaving it undiscoverable outside GitHub.
+    for extra_md in sorted(plugin_dir.glob("*.md")):
+        if extra_md.name == "README.md":
+            continue
+
+        extra_text = extra_md.read_text(encoding="utf-8")
+        lines = extra_text.lstrip("\n").split("\n", 1)
+        first_line = lines[0]
+        if first_line.startswith("# "):
+            extra_title = first_line[2:].strip()
+            body = lines[1].lstrip("\n") if len(lines) > 1 else ""
+        else:
+            extra_title = extra_md.stem.replace("_", " ").title()
+            body = extra_text
+
+        extra_doc_path = f"{slug}/{extra_md.stem}.md"
+        extra_full_doc_path = f"plugins/{extra_doc_path}"
+        extra_source_rel = extra_md.relative_to(REPO_ROOT).as_posix()
+
+        nav[extra_title] = extra_doc_path
+
+        with mkdocs_gen_files.open(extra_full_doc_path, "w") as f:
+            f.write(f"# {extra_title}\n\n")
+            f.write(generated_note(extra_source_rel))
+            f.write(body)
+
+        # edit_path is concatenated directly after the fixed `edit_uri: blob/main/docs/`
+        # prefix (it is NOT relative to this generated file's own directory), so it
+        # always needs exactly one `../` to escape "docs/" regardless of how deeply
+        # nested the virtual page itself is - same as the top-level README case above.
+        mkdocs_gen_files.set_edit_path(extra_full_doc_path, f"../{extra_source_rel}")
+
+with mkdocs_gen_files.open("plugins/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

front/js/settings_utils.js

@@ -265,9 +265,31 @@ function cloneDataTableRow(el){
   // Clone the row (including its data and controls)
   let clonedRow = $(row).clone(true, true); // The true arguments copy the data and event handlers
 
+  // Use max(my-index) + 1, not rows().count(), so a clone made after a row was
+  // removed can't collide with a surviving row's index (count() shrinks on removal,
+  // indices don't get renumbered).
+  let newIndex = 0;
+  table.rows().nodes().to$().each(function () {
+    const idx = parseInt($(this).attr("my-index"));
+    if (!isNaN(idx) && idx >= newIndex) { newIndex = idx + 1; }
+  });
 
-  $(clonedRow).attr("my-index",table.rows().count())
+  $(clonedRow).attr("my-index", newIndex);
 
+  // jQuery's clone() copies every descendant id/name/data-* attribute verbatim,
+  // so the clone's inputs/select/action-icons still carry the SOURCE row's
+  // "<key>_<myIndex>" identifiers - e.g. two elements now share the same id.
+  // That breaks anything that looks an element up by id (e.g. the icon picker's
+  // document.getElementById(setKey) in showIconSelection()), which then always
+  // resolves to the first (source) row instead of the new clone. Re-key every
+  // such attribute on the clone to use the new index instead.
+  const idxSuffix = new RegExp(`_${myIndex}(?!\\d)`, 'g');
+  clonedRow.find('[id], [name], [data-myparam-setkey], [data-myparam]').each(function () {
+    ['id', 'name', 'data-myparam-setkey', 'data-myparam'].forEach(attr => {
+      const v = $(this).attr(attr);
+      if (v) { $(this).attr(attr, v.replace(idxSuffix, `_${newIndex}`)); }
+    });
+  });
 
   console.log(clonedRow);
 

mkdocs.yml

@@ -43,6 +43,7 @@ nav:
       - Getting started:
         - Subnets: SUBNETS.md
         - Enable Plugins: PLUGINS.md
+        - Plugins reference: plugins/
         - Backups: BACKUPS.md
         - Security features: SECURITY_FEATURES.md
         - Security considerations: SECURITY.md
@@ -227,6 +228,11 @@ plugins:
   - gh-admonitions
   - search
   - glightbox
+  - gen-files:
+      scripts:
+        - docs/gen_plugin_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md
 
 # Custom CSS
 extra_css:

scripts/check_skill_pairs.py

@@ -25,6 +25,7 @@ import sys
 # Copilot); a few skills are also mirrored to .claude/skills/ as a 3rd member.
 GROUPS = [
     [".gemini/skills/plugin-development/plugin-skill.md", ".github/skills/plugin-run-development/SKILL.md", ".claude/skills/plugin-development/SKILL.md"],
+    [".gemini/skills/plugin-readme/plugin-readme-skill.md", ".github/skills/plugin-readme/SKILL.md", ".claude/skills/plugin-readme/SKILL.md"],
     [".gemini/skills/testing-workflow/SKILL.md", ".github/skills/testing-workflow/SKILL.md", ".claude/skills/testing-workflow/SKILL.md"],
     [".gemini/skills/pr-analysis/SKILL.md", ".github/skills/pr-analysis/SKILL.md", ".claude/skills/pr-analysis/SKILL.md"],
     [".gemini/skills/settings/SKILL.md", ".github/skills/settings-management/SKILL.md"],

server/plugins/_publisher_pushover/README.md

@@ -1,8 +1,7 @@
 ## Overview
 
-A plugin to publish a notification via the Pushover gateway. Enable sending notifications via <a target="_blank" href="https://www.pushover.net/">Pushover</a>.
+A plugin to publish notifications via the [Pushover](https://pushover.net/) gateway.
 
 ### Usage
 
-- Go to settings and fill in relevant details.
-
+- Go to settings and provide your Pushover application token and user key (both come from your Pushover account/app dashboard).

server/plugins/_publisher_pushsafer/README.md

@@ -1,8 +1,7 @@
 ## Overview
 
-A plugin to publish a notification via the Pushsafer gateway. Enable sending notifications via <a target="_blank" href="https://www.pushsafer.com/">Pushsafer</a>.
+A plugin to publish notifications via the [Pushsafer](https://www.pushsafer.com/) gateway.
 
 ### Usage
 
-- Go to settings and fill in relevant details.
-
+- Go to settings and provide your Pushsafer API key (from your Pushsafer account dashboard).

server/plugins/_publisher_telegram/README.md

@@ -1,12 +1,11 @@
 ## Overview
 
-You can send notifications via Telegram
-## Notes
-
-You need Telegram bot to send notifications
+A plugin to publish notifications via a Telegram bot.
 
 ### Usage
 
-- Go to settings and fill in relevant details.
+- Create a bot via [BotFather](https://t.me/BotFather) and grab its token.
+- Find the chat ID to send messages to (a user ID for a DM, or a group/channel ID).
+- Enter both in settings; long messages are truncated to the configured size limit, with a `(text was truncated)` note appended.
 
 Made by [@doctorixx](https://github.com/doctorixx) 🙏

server/plugins/adguard_import/README.md

@@ -1,27 +1,14 @@
 ## Overview
 
-Plugin functionality overview and links to external resources if relevant. Include use cases if available. 
+Imports devices *from* AdGuard Home *into* NetAlertX. On each run it pulls AdGuard Home's auto-discovered clients (devices AdGuard has seen via DNS activity, not the manually-configured persistent client list) and cross-references its DHCP leases to resolve a MAC address for each one.
 
-> [!TIP]
-> Some tip.
-
-### Quick setup guide
-
-To set up the plugin correctly, make sure...
-
-#### Required Settings
-
-- When to run `PREF_RUN`
-- 
+This is the reverse direction of the [`adguard_export`](https://docs.netalertx.com/plugins/adguard_export) plugin, which pushes NetAlertX's known devices *to* AdGuard Home as persistent clients.
 
 ### Usage
 
-- Head to **Settings** > **Plugin name** to adjust the default values.
+- Enable the `ADGUARDIMP` plugin and point it at your AdGuard Home instance's address and credentials.
+- If a client has no MAC in AdGuard's DHCP leases (e.g. it was seen only via DNS, not DHCP), enable the fake-MAC option to still import it under a deterministic synthetic MAC rather than skipping it.
 
 ### Notes
 
-- Additional notes, limitations, Author info. 
-
-- Version: 1.0.0
-- Author: `<your github handle>`
-- Release Date: `<release date>`
+- Requires AdGuard Home's REST API to be reachable from the NetAlertX container.

server/plugins/asuswrt_import/README.md

@@ -13,7 +13,7 @@ This Plugin is using awesome [asusrouter](https://github.com/Vaskivskyi/asusrout
 ### Notes
 
 - In case an existing imported device is renamed in Asus Router it will not be renamed in NetAlertX. In this case it has to be done manually or the device should be removed and it will appear on the next scan. 
-- Only clients listed in the main AsusWRT interface are imported. If using plugins, such as the `YazFi plugin`, check the [Asus routers DHCPLSS guide](/server/plugins/dhcp_leases/ASUS_ROUTERS.md) for a possible workaround.
+- Only clients listed in the main AsusWRT interface are imported. If using plugins, such as the `YazFi plugin`, check the [Asus routers DHCPLSS guide](https://docs.netalertx.com/plugins/dhcp_leases/ASUS_ROUTERS) for a possible workaround.
 
 ## Other info
 

server/plugins/avahi_scan/README.md

@@ -1,7 +1,11 @@
 ## Overview
 
-Plugin for device name discovery via the [avahi](https://wiki.alpinelinux.org/wiki/MDNS) network utility supporting mDNS.
+Plugin for device name discovery via the [avahi](https://wiki.alpinelinux.org/wiki/MDNS) network utility, using mDNS. Runs against IPs already discovered by a device scanner - it doesn't discover devices itself, only tries to attach a name to ones that don't have one yet. Generally the most reliable naming source for local devices that advertise themselves over mDNS (most consumer IoT, Apple/Chromecast-style devices).
 
 ### Usage
 
 - Check the Settings page for details.
+
+### Notes
+
+- See the [Name resolution guide](https://docs.netalertx.com/NAME_RESOLUTION) for how this fits alongside the other naming plugins (`NBTSCAN`, `NSLOOKUP`, `DIGSCAN`).

server/plugins/csv_backup/README.md

@@ -1,6 +1,6 @@
 ## Overview
 
-Plugin generating CSV backups of your Devices database table, including the network mappings. Can be used for importing your setup via the Maintenance > Backup / Restore > CSV Import feature (See also: [Devices Bulk Editing](https://docs.netalertx.com/DEVICES_BULK_EDITING)).
+Plugin generating CSV backups of your Devices database table, including the network mappings. Can be used for importing your setup via the Maintenance > Backup / Restore > CSV Import feature (See also: [Devices Bulk Editing](https://docs.netalertx.com/DEVICES_BULK_EDITING)). For the full backup/restore picture across NetAlertX (not just this plugin), see the [Backups guide](https://docs.netalertx.com/BACKUPS).
 
 ### Usage
 

server/plugins/custom_props/README.md

@@ -1,8 +1,14 @@
 ## Overview
 
-Settings related to the custom properties functionality on a device. A user guide can be found here: [Custom Properties](/docs/CUSTOM_PROPERTIES.md)
+Backs the **Custom Properties** feature on devices - interactive icons (links, notes, delete, run-plugin, etc.) shown in the device list. This plugin doesn't scan or collect anything itself; it only defines the field types and default option lists used wherever a `devCustomProps` table is edited: directly on a device (Device Details > Custom Properties) and via the `NEWDEV_devCustomProps` setting that seeds the default for newly discovered devices. Full usage guide: [Custom Properties](https://docs.netalertx.com/CUSTOM_PROPERTIES).
+
+### Settings
+
+- `CUSTPROP_icon`: the pool of icons offered by the icon picker when adding/editing a custom property. This is a shared list, not per-property - edit it to add or remove choices available everywhere.
+- `CUSTPROP_type`: the list of available property types. The built-in ones each drive specific behavior when the property's icon is clicked - see [Available Action Types](https://docs.netalertx.com/CUSTOM_PROPERTIES#available-action-types) for exactly what `link`, `link_new_tab`, `show_notes`, `delete_dev`, and `run_plugin` each do; `none`/`data` are non-interactive.
+- `CUSTPROP_args`, `CUSTPROP_name`, `CUSTPROP_notes`, `CUSTPROP_show`, `CUSTPROP_actions`: column definitions for a single custom-property row (the action's arguments, display name, tooltip notes, visibility toggle, and row action buttons). These aren't values you set once - they're the schema every Custom Properties table (per-device or `NEWDEV_devCustomProps`) is built from.
 
 ### Usage
 
-- Head to **Settings** > **Custom Properties** to adjust the default values.
-
+- Head to **Settings** > **Custom properties** to adjust the icon and type pools available to every device.
+- Individual property rows are added/edited per device (Device Details > Custom Properties) or as the new-device default via `NEWDEV_devCustomProps` - not here.

server/plugins/ddns_update/README.md

@@ -1,6 +1,18 @@
 ## Overview
 
-Plugin to run regular DDNS update tasks.
+Keeps a Dynamic DNS (DDNS) hostname pointed at your current public IP. On each run, the plugin resolves the IP currently published for `DDNS_DOMAIN` (via `dig`) and compares it to the IP NetAlertX already has recorded for the special `Internet` device. If they differ, it calls `DDNS_UPDATE_URL` with your `DDNS_USER`/`DDNS_PASSWORD`/`DDNS_DOMAIN` - the DDNS provider is expected to detect the new IP from the request's own source address, which is how most `username=&password=&hostname=`-style DDNS update APIs work. The default `DDNS_UPDATE_URL` targets Dynu, but any provider using that same query-string convention works by changing the URL.
+
+### Requirements
+
+- A device with MAC `Internet` and an up-to-date `devLastIP` - normally maintained by the `internet_ip` (`INTRNT`) plugin. Without it, the "previous IP" the comparison relies on stays empty and every run looks like a change.
+- `dig` and `curl` available in the container (already present in the default image).
+
+### Settings
+
+- `DDNS_DOMAIN` / `DDNS_USER` / `DDNS_PASSWORD`: your DDNS provider's hostname and login credentials.
+- `DDNS_UPDATE_URL`: the provider's update endpoint. Defaults to Dynu's `https://api.dynu.com/nic/update?`; swap it for another provider that accepts the same query-string update format.
+- `DDNS_RUN`: when to run. Since this only needs to catch a WAN IP change (not run on every scan), an hourly or daily `schedule` is the recommended value over `always_after_scan`.
+- `DDNS_WATCH` / `DDNS_REPORT_ON`: control whether and when a notification is sent for this plugin's activity.
 
 ### Usage
 

server/plugins/ddns_update/README_DE.md

@@ -1,7 +0,0 @@
-## Übersicht
-
-Ein Plugin zur regelmäßigen Aktualisierung eines DynDNS-Eintrags.
-
-### Verwendung
-
-- Einstellungen-Seite für Details ansehen.

server/plugins/dhcp_leases/README.md

@@ -2,6 +2,8 @@
 
 A plugin allowing for importing devices from DHCP.leases files.  
 
+See the [Pi-hole guide](https://docs.netalertx.com/PIHOLE_GUIDE) for a walkthrough covering this plugin alongside the other Pi-hole integrations (`PIHOLE`, `PIHOLEAPI`, `PIHOLEMON`). If you're using an ASUS router with the YazFi plugin, see [Configuring the DHCPLSS plugin to import clients from the YazFi plugin](https://docs.netalertx.com/plugins/dhcp_leases/ASUS_ROUTERS) for a workaround to import guest-network clients.
+
 ### Usage
 
 - Specify full paths of all `dhcp.leases` files you want to import and watch in the `DHCPLSS_paths_to_check`setting.

server/plugins/dhcp_servers/README.md

@@ -1,11 +1,15 @@
 ## Overview
 
-A simple sample plugin allowing for detecting rogue DHCP servers on the network.  
+Detects DHCP servers answering on your network, using NMAP's `broadcast-dhcp-discover` probe - it broadcasts a DHCP discover request and lists every server that responds, the same way a rogue-DHCP detector would. NetAlertX doesn't know which responses are "expected" (your router) versus "rogue" (a misconfigured device, a second router, or something malicious) - that judgment call is yours; the plugin just gives you the full list so you can spot an unexpected one.
 
 ### Usage
 
-- No specific configuration needed.
+- Check the Settings page for details.
 
 ### Notes
 
-- No specific configuration needed.
+- Requires the container to send/receive broadcast traffic on the scanned network (host networking or an equivalent setup) - a bridged/isolated network namespace will prevent the probe from seeing real responses.
+
+### Other info
+
+- Based on the work of [leiweibau](https://github.com/leiweibau/Pi.Alert)

server/plugins/dig_scan/README.md

@@ -1,7 +1,12 @@
 ## Overview
 
-Plugin for device name discovery via the [nbtscan](https://linuxcommandlibrary.com/man/nbtscan) network utility supporting NetBIOS.
+Plugin for device name discovery via reverse DNS (PTR) lookups, using the [dig](https://linux.die.net/man/1/dig) utility (`dig +short -x <ip>`). Runs against IPs already discovered by a device scanner - it doesn't discover devices itself, only tries to attach a name to ones that don't have one yet. Functionally similar to `NSLOOKUP` (both do a reverse DNS lookup, just via a different tool) - enabling both is redundant, pick whichever behaves better against your DNS server.
 
 ### Usage
 
 - Check the Settings page for details.
+
+### Notes
+
+- Only useful if your network's DNS server actually has PTR records for local devices (e.g. via your router's DHCP-to-DNS integration); many home networks don't, in which case this plugin will find little to nothing.
+- See the [Name resolution guide](https://docs.netalertx.com/NAME_RESOLUTION) for how this fits alongside the other naming plugins (`AVAHISCAN`, `NBTSCAN`, `NSLOOKUP`).

server/plugins/luci_import/README.md

@@ -1,10 +1,14 @@
 ## Overview
 
-The plugin is used to import connected devices from OpenWRT
+Imports connected devices from an OpenWRT router via its LuCI RPC API.
+
+### Usage
+
+- Point the plugin at your router's address and a login with access to LuCI RPC. A read-only user is recommended over using your admin account.
+- If your router uses a self-signed HTTPS certificate, you'll need to disable certificate verification for the import to succeed.
 
 ### Other info
 
 - Version: 1.0
 - Author: [vaga9938](https://github.com/vaga9938)
 - Release Date: 28-Dec-2024
-

server/plugins/maintenance/README.md

@@ -1,9 +1,7 @@
 ## Overview
 
-A plugin responsible for general maintenance tasks. These currently include:
-
-- **`MAINT_LOG_LENGTH`**: app.log cleanup. Recommended value: `10000` lines. Increase if debugging an issue.
+Handles routine housekeeping so long-running logs and in-app notifications don't grow unbounded: trims `app.log` down to a configured line count, and purges old in-app notification entries past a configured count.
 
 ### Usage
 
-- N/A
+- Runs automatically once configured - no manual action needed beyond setting a schedule and the retention values on the Settings page.

server/plugins/nbtscan_scan/README.md

@@ -1,7 +1,11 @@
 ## Overview
 
-Plugin for device name discovery via the [nbtscan](https://linuxcommandlibrary.com/man/nbtscan) network utility supporting NetBIOS.
+Plugin for device name discovery via the [nbtscan](https://linuxcommandlibrary.com/man/nbtscan) network utility, using NetBIOS. Runs against IPs already discovered by a device scanner - it doesn't discover devices itself, only tries to attach a name to ones that don't have one yet. Mainly useful for older/Windows-family devices that respond to NetBIOS name queries; most modern devices won't.
 
 ### Usage
 
 - Check the Settings page for details.
+
+### Notes
+
+- See the [Name resolution guide](https://docs.netalertx.com/NAME_RESOLUTION) for how this fits alongside the other naming plugins (`AVAHISCAN`, `NSLOOKUP`, `DIGSCAN`).

server/plugins/nmap_scan/README.md

@@ -1,7 +1,11 @@
 ## Overview
 
-This plugin scans your network for open ports. Only IPs are scanned that are accessible by the app container. 
+Scans your known devices for open ports and the services running on them, using NMAP. Only IPs reachable from the app container are scanned. Results show up as a per-device list of open ports/services, and can optionally trigger a notification when a device's port list changes (e.g. a new service appears).
+
+### Usage
+
+- Check the Settings page for details.
 
 ### Notes
 
-![Screenshot](nmap_ports_services.png)
+![Screenshot](nmap_ports_services.png)

server/plugins/nslookup_scan/README.md

@@ -1,7 +1,11 @@
 ## Overview
 
-Plugin for device name discovery via the [nslookup](https://linux.die.net/man/1/nslookup) network utility.
+Plugin for device name discovery via reverse DNS (PTR) lookups, using the [nslookup](https://linux.die.net/man/1/nslookup) utility. Runs against IPs already discovered by a device scanner - it doesn't discover devices itself, only tries to attach a name to ones that don't have one yet. Functionally similar to `DIGSCAN` (both do a reverse DNS lookup, just via a different tool) - enabling both is redundant, pick whichever behaves better against your DNS server.
 
 ### Usage
 
 - Check the Settings page for details.
+
+### Notes
+
+- See the [Name resolution guide](https://docs.netalertx.com/NAME_RESOLUTION) for how this fits alongside the other naming plugins (`AVAHISCAN`, `NBTSCAN`, `DIGSCAN`).

server/plugins/pihole_api_scan/README.md

@@ -13,6 +13,8 @@ The plugin connects to your Pi-hole’s API and retrieves:
 
 NetAlertX then uses this information to match or create devices in your system.
 
+See the [Pi-hole guide](https://docs.netalertx.com/PIHOLE_GUIDE) for a walkthrough covering this plugin alongside the other Pi-hole integrations (`PIHOLE`, `PIHOLEMON`, `DHCPLSS`).
+
 ### Quick setup guide
 
 * You are running **Pi-hole v6** or newer.

server/plugins/pihole_monitor/README.md

@@ -7,6 +7,8 @@ The **PIHOLEMON** plugin does two jobs against the same Pi-hole connection(s):
 
 Both share one login per Pi-hole instance and one settings page, instead of being two separately configured pieces that happen to need the same credentials.
 
+See the [Pi-hole guide](https://docs.netalertx.com/PIHOLE_GUIDE) for a walkthrough covering this plugin alongside the other Pi-hole integrations (`PIHOLE`, `PIHOLEAPI`, `DHCPLSS`).
+
 Two design choices worth knowing about:
 
 * **Both a primary and an optional secondary/failover Pi-hole are checked, and their results combined.** Watching only one leaves an obvious blind spot for the anomaly detection - a device can simply point at the other resolver and never show up. Leave the secondary URL blank if you only run one Pi-hole; most setups do.

server/plugins/pihole_scan/README.md

@@ -2,6 +2,8 @@
 
 A plugin allowing for importing devices from the PiHole database. This is an import plugin using an SQLite database as a source.
 
+See the [Pi-hole guide](https://docs.netalertx.com/PIHOLE_GUIDE) for a walkthrough covering this plugin alongside the other Pi-hole integrations (`PIHOLEAPI`, `PIHOLEMON`, `DHCPLSS`).
+
 ### Usage
 
 - You need to specify the following settings:

server/plugins/ui_settings/README.md

@@ -1,8 +1,18 @@
 ## Overview
 
-UI-related settings.
+Settings that control the look, layout, and live behavior of the web UI — the Devices page, device icons, locale/date formatting, and how/when the UI polls or waits on the backend. None of these affect what data is scanned or stored, only how it's displayed and interacted with.
+
+### What each group changes
+
+- **Devices page layout** (`device_columns`, `columns_filters`, `shown_cards`, `hide_empty`, `PRESENCE`, `MY_DEVICES`, `DEV_SECTIONS`): which columns/filters/tiles appear on the Devices list and in what order, which device statuses populate the presence chart and the default *My devices* view, and which page sections can be hidden entirely.
+- **Device filtering** (`hide_rel_types`): excludes devices whose parent relationship matches one of the given types (e.g. `nic`, `virtual`) from most device lists — useful for hiding virtual/container interfaces that would otherwise clutter the list.
+- **Appearance** (`theme`, `ICONS`, `LOCALE`): the UI color theme (with a `System` option that follows the OS/browser), the pool of pre-defined icons offered in the device icon picker, and the locale used to format dates across the UI.
+- **Live/refresh behavior** (`REFRESH`, `SCAN_PAUSE`, `DEFAULT_PAGE_SIZE`, `WAIT_FOR_SETTINGS`): how often the UI auto-reloads itself (`0` disables auto-refresh), how long a manual scan pause lasts, the default table page size, and whether saving settings blocks the UI until the backend finishes reloading — it only actually blocks when a plugin's configuration changed; other changes return immediately regardless of this setting.
+- **Network page** (`TOPOLOGY_ORDER`): sort order for nodes in the Network topology view.
+- **MAC handling** (`NOT_RANDOM_MAC`): MAC prefixes that should never be flagged as a randomized/private MAC, even if they'd otherwise match the randomization heuristic.
+
+Setting names and tooltips in the Settings UI are the source of truth for exact behavior and accepted values — this README only orients you to what each group is for.
 
 ### Usage
 
 - Head to **Settings** > **UI Settings** to adjust the default values.
-

server/plugins/unifi_api_import/README.md

@@ -1,6 +1,6 @@
 ## Overview
 
-Unifi import plugin using the Site Manager API.
+UniFi import plugin using the newer, API-key-based Site Manager API - the successor to the username/password controller login used by the older [`unifi_import`](https://docs.netalertx.com/plugins/unifi_import) plugin. Prefer this one where available; fall back to `unifi_import` if your controller doesn't expose the Site Manager integration API yet.
 
 > [!TIP]
 > The Site Manager API doesn't seems to have feature parity with the old API yet, so certain limitations apply.  
@@ -16,7 +16,7 @@ Navigate to your UniFi Site Manager _Settings -> Control Plane -> Integrations_.
 
 ### Usage
 
-- Head to **Settings** > **Plugin name** to adjust the default values.
+- Head to **Settings** > **UniFi import (API)** to adjust the default values.
 
 ### Notes
 

server/plugins/vendor_update/README.md

@@ -1,7 +1,7 @@
 ## Overview
 
-A plugin to retrieve a MAC and vendor database to identify vendors for devices. The Plugin result objects will be a list of vendors mapped to the devices where the vendor was previously unknown.
+Keeps the local MAC-vendor lookup database current by downloading the [IEEE OUI registry](http://standards-oui.ieee.org/oui/oui.txt), then re-resolves the vendor for any device whose vendor is still unknown. This is what fills in the `devVendor` field for devices your scanners couldn't already identify.
 
 ### Usage
 
-- Check the Settings page for details.
+- Check the Settings page for details. A daily or weekly `schedule` is plenty - the OUI registry doesn't change often enough to warrant running this on every scan.

server/plugins/wake_on_lan/README.md

@@ -1,37 +1,12 @@
-# Wake-on-LAN Plugin User Guide
-
 ## Overview
-The Wake-on-LAN (WOL) plugin allows you to remotely wake devices on your network that support Wake-on-LAN functionality. This plugin sends a "magic packet" to the specified devices, which powers them on, provided they are configured to accept WOL requests.
 
-## Configuration
-All settings for the plugin can be configured via the user interface. The key settings include:
-
-- **Broadcast IPs (`WOL_broadcast_ips`)**: 
-  A list of IP addresses to use for broadcasting the WOL packet. Ensure these are valid network broadcast addresses for your environment.
-  
-- **Devices to Wake (`WOL_devices_to_wake`)**: 
-  Defines the group of devices to be woken. You can choose from:
-  - `offline`: Wake devices that are currently offline.
-  - `down`: Wake devices that are in a "down" state.
-
-- **Ports (`WOL_ports`)**: 
-  A list of ports to use when sending the WOL packet. The default is usually port 9.
-
-## Usage
-1. Configure the settings through the UI.
-2. The plugin will automatically detect devices based on the selected criteria (offline or down) and attempt to wake them by sending WOL magic packets.
-3. The plugin logs the outcome of each attempt and processes results for monitoring and notifications.
-
-## Logs
-Logs for each run of the plugin are stored in the specified log path, where you can track:
-- WOL packet sending attempts.
-- Success or failure of waking devices.
-
-## Notes
-- Ensure the devices are configured to allow Wake-on-LAN in BIOS and the network adapter supports WOL when powered off.
-- Make sure your network is configured to allow broadcast packets.
+Automatically wakes devices on your network by sending them a Wake-on-LAN "magic packet" - useful for bringing machines back online on a schedule without touching them manually. On each run, the plugin picks devices matching your selected status (e.g. `offline` or `down`) and broadcasts a magic packet to each.
 
 ### Usage
 
-- Head to **Settings** > **Plugin name** to adjust the default values.
+- Head to **Settings** > **Wake on Lan (WOL)** to adjust the default values.
 
+### Notes
+
+- The target device must have Wake-on-LAN enabled in its BIOS/UEFI and network adapter settings - the plugin can only send the packet, it can't enable WOL support on a device that doesn't have it turned on.
+- Your network must allow broadcast packets between the NetAlertX container and the target devices (same broadcast domain, or a broadcast IP configured for the right subnet).

server/plugins/website_monitor/README.md

@@ -9,4 +9,8 @@ A simple sample plugin allowing for monitoring web services or urls. The status
 ### Notes
 
 - Setting `(WEBMON_)SQL_internet_ip` is not used and specified for demonstration purposes only.
-- Parameters `macs` and `internet_ip` in the `config.json` file are not used and specified for demonstration purposes only.
+- Parameters `macs` and `internet_ip` in the `config.json` file are not used and specified for demonstration purposes only.
+
+### Other info
+
+- Based on the work of [leiweibau](https://github.com/leiweibau/Pi.Alert)

server/plugins/workflows/README.md

@@ -1,6 +1,8 @@
 ## Overview
 
-TBC
+Backing settings plugin for the Workflows automation engine (trigger → conditions → actions rules that react to device/scan events). The engine itself lives in `server/workflows/` and is configured on its own **Workflows** page, not through a settings tab - this plugin only holds the setting that controls how much Application Events history is kept, since that history feeds the Workflows UI.
+
+See the [Workflows guide](https://docs.netalertx.com/WORKFLOWS) for how to build rules, and [Workflow examples](https://docs.netalertx.com/WORKFLOW_EXAMPLES) for ready-made ones.
 
 ### Usage