Alert on genuinely new (never-seen-before) devices

New seen_macs table: permanent, insert-only, MAC-keyed record of the
first time each device was ever seen -- deliberately decoupled from
devices.first_seen (IP-keyed, would false-positive on every DHCP
lease change). Bootstrap-safe: first call seeds the baseline from
whatever's currently on the network without alerting on all 71+
existing devices at once. Verified locally: bootstrap call reports
nothing new, repeat calls with the same MACs report nothing new, one
genuinely new MAC gets reported exactly once.

Pushes a Home Assistant persistent_notification when a new MAC
appears (gated behind HOME_ASSISTANT_TOKEN + homeAssistant.url in
hosts.yaml -- missing config just means no push, detection still
runs). Also surfaced directly in the dashboard as a blue "new" badge
for anything first seen in the last 24h, independent of HA config.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs/device-discovery.md

@@ -116,6 +116,33 @@ ssh homelab-monitor "chmod +x /opt/homelab-monitor/scripts/*.sh && \
 (In practice, `git pull` on CT122 already updates the script files at their deployed
 path — the above is only needed for the systemd units or a from-scratch setup.)
 
+## New-device alerting
+
+Separate from known/unknown labeling: whenever a MAC address is seen on the network for
+the **very first time ever**, the dashboard pushes a `persistent_notification` to Home
+Assistant (config: `homeAssistant.url` in `config/hosts.yaml` + `HOME_ASSISTANT_TOKEN`
+in `.env`, a long-lived access token from HA's Profile > Security). The idea: "unknown"
+by itself isn't a useful alert signal (plenty of legitimate IoT gear stays permanently
+unknown), but a MAC nobody's ever seen before showing up is worth a heads-up.
+
+- `seen_macs` table (`apps/api/src/db/index.ts`) is a permanent, insert-only, MAC-keyed
+  record — deliberately **not** derived from `devices.first_seen`, which is keyed by
+  **IP** and would generate a false "new device" alert every time an existing device's
+  DHCP lease just happened to change.
+- **Bootstrap-safe**: the very first call (empty `seen_macs` table) seeds the baseline
+  from whatever's currently on the network and reports nothing as new — otherwise
+  turning this on for the first time would alert on the entire existing device
+  population (71+ devices) all at once.
+- `apps/api/src/discovery/homeAssistant.ts` posts to
+  `{url}/api/services/persistent_notification/create` — chosen over a specific
+  mobile-push `notify.*` service since it's guaranteed to work regardless of which
+  notify integrations happen to be configured in the user's Home Assistant instance.
+- Also surfaced in the dashboard itself: a blue "new" badge next to the status badge
+  for any device first seen within the last 24h (`isNew` in the `/api/devices`
+  response), independent of whether Home Assistant notifications are configured.
+- Optional and gated: missing config, an HA API error, etc. don't affect discovery
+  itself — only whether a push notification goes out.
+
 ## Known limitations
 
 - `knownDevices` in `config/hosts.yaml` is matched by **IP**, not MAC — fine as long as