chore: bump version to 3.2.0

ha-relevant: no

.env.example

@@ -1,16 +1,37 @@
 # Backend - server-side only (NEVER commit .env)
+# Generate: python3 -c "import secrets; print(secrets.token_hex(32))"
 SECRET_KEY=change_me_in_production
 SQLITE_PATH=./data/homelab.db
+# Uploaded media (floor plans) folder. Optional — defaults to <SQLITE_PATH dir>/uploads,
+# which sits on the same persistent volume as the DB.
+# UPLOAD_DIR=./data/uploads
 # Set this to the URL(s) you use to access Homelable in your browser.
 CORS_ORIGINS=["http://localhost:5173","http://localhost:3000"]
 
-# Auth — default credentials: admin / admin
+# Auth — local mode is the backward-compatible default.
+AUTH_MODE=local
+# Local credentials: admin / admin by default.
 # ⚠️  Change before exposing on a network.
-# Generate a new hash: python3 -c "from passlib.context import CryptContext; print(CryptContext(schemes=['bcrypt']).hash('yourpassword'))"
+# Generate a new hash: python3 -c "import bcrypt; print(bcrypt.hashpw(b'yourpassword', bcrypt.gensalt()).decode())"
 # ⚠️  Keep the single quotes around the hash — bcrypt hashes contain \$ which Docker misinterprets without them.
 AUTH_USERNAME=admin
 AUTH_PASSWORD_HASH='$2b$12$RtMbyw17l4N5UGzeXMNAWuzCaVV.XFBY7ZetWheQhxcBDcxahapkG'
 
+# OpenID Connect (optional alternative to local auth).
+# Set AUTH_MODE=oidc and configure every value below. The callback must be
+# registered exactly at the identity provider. Keep CORS_ORIGINS restricted to
+# the Homelable browser origin; wildcard CORS is rejected in OIDC mode. OIDC
+# also requires SECRET_KEY to contain at least 32 bytes.
+# AUTH_MODE=oidc
+# OIDC_DISCOVERY_URL=https://idp.example/application/o/homelable/.well-known/openid-configuration
+# OIDC_CLIENT_ID=homelable
+# OIDC_CLIENT_SECRET=replace-with-a-secret
+# OIDC_REDIRECT_URI=https://homelable.example/api/v1/auth/oidc/callback
+# OIDC_SCOPES="openid profile email"
+# OIDC_COOKIE_SECURE=true
+# OIDC_SESSION_EXPIRE_MINUTES=480
+# OIDC_TRANSACTION_EXPIRE_SECONDS=600
+
 # Scanner — JSON array of CIDR ranges to scan
 SCANNER_RANGES=["192.168.1.0/24"]
 
@@ -43,3 +64,38 @@ MCP_SERVICE_KEY=svc_changeme
 # the same value in the `X-API-Key` header.
 # Generate: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
 # HOMEPAGE_API_KEY=
+
+# Proxmox VE import — pull hosts/VMs/LXC from the Proxmox REST API.
+# The token is a credential: kept in memory only, never written to disk by the
+# app, never returned by any API. Create it under Datacenter → Permissions →
+# API Tokens and grant the read-only PVEAuditor role at path "/".
+# Token id format: user@realm!tokenname (e.g. root@pam!homelable).
+# Required only for auto-sync; one-off imports can pass the token in the dialog.
+# PROXMOX_TOKEN_ID=root@pam!homelable
+# PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+# PROXMOX_HOST=192.168.1.10
+# PROXMOX_PORT=8006
+# PROXMOX_VERIFY_TLS=true          # set false only for self-signed certs
+
+# Zigbee2MQTT auto-sync — pull the mesh from an MQTT broker on a schedule.
+# MQTT credentials are secrets: kept in memory only, never written to disk by
+# the app, never returned by any API. Manual imports (the Zigbee dialog) are
+# unaffected — this block only powers Settings → Zigbee auto-sync and /sync-now.
+# Required only for auto-sync; one-off imports pass their config in the dialog.
+# ZIGBEE_MQTT_HOST=192.168.1.20
+# ZIGBEE_MQTT_PORT=1883
+# ZIGBEE_MQTT_USERNAME=mqttuser        # optional
+# ZIGBEE_MQTT_PASSWORD=mqttpass        # optional
+# ZIGBEE_BASE_TOPIC=zigbee2mqtt
+# ZIGBEE_MQTT_TLS=false                # true for TLS brokers (typically port 8883)
+# ZIGBEE_MQTT_TLS_INSECURE=false       # skip cert verify (self-signed only; requires TLS)
+
+# Z-Wave JS UI (zwavejs2mqtt) auto-sync — same MQTT secret/env rules as Zigbee.
+# ZWAVE_MQTT_HOST=192.168.1.20
+# ZWAVE_MQTT_PORT=1883
+# ZWAVE_MQTT_USERNAME=mqttuser         # optional
+# ZWAVE_MQTT_PASSWORD=mqttpass         # optional
+# ZWAVE_PREFIX=zwave
+# ZWAVE_GATEWAY_NAME=zwavejs2mqtt
+# ZWAVE_MQTT_TLS=false                 # true for TLS brokers (typically port 8883)
+# ZWAVE_MQTT_TLS_INSECURE=false        # skip cert verify (self-signed only; requires TLS)

.github/workflows/quality.yml

@@ -60,3 +60,20 @@ jobs:
       - run: ruff check .
       - run: mypy app/
       - run: pytest
+
+  # Also guards the NODE_TYPES / EDGE_TYPES enums in mcp/app/tools.py against
+  # drift from frontend/src/types/index.ts (test_node_types_sync.py,
+  # test_edge_types_sync.py) — those tests need the frontend sources, so this
+  # job runs from a full checkout rather than the mcp Docker context.
+  mcp:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: mcp
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - run: pip install -r requirements.txt
+      - run: pytest

.github/workflows/security.yml

@@ -22,6 +22,12 @@ jobs:
         uses: trufflesecurity/trufflehog@main
         with:
           path: ./
+          # Lob (a direct-mail API this project does not use) matches any
+          # `test_`-prefixed identifier of ~35 chars and reports it verified,
+          # because Lob test keys authenticate unconditionally. Every pytest
+          # function named at that length trips it — the first was
+          # `test_updates_an_existing_device_in_place`.
+          extra_args: --exclude-detectors=Lob
 
   dependency-audit:
     runs-on: ubuntu-latest
@@ -31,11 +37,12 @@ jobs:
         with:
           node-version: '20'
       - name: NPM Audit
-        run: cd frontend && npm audit --audit-level=high
+        # --omit=dev: only ship-time deps gate the build. Dev-only tooling
+        # (shadcn CLI and its transitive tree: hono, fast-uri, …) is never
+        # bundled or served, so its advisories must not fail release CI.
+        run: cd frontend && npm audit --omit=dev --audit-level=high
       - uses: actions/setup-python@v5
         with:
           python-version: '3.11'
       - name: Pip audit
-        # CVE-2024-23342 (ecdsa): timing attack on ECDSA — not exploitable (app uses HS256/HMAC only).
-        # python-jose forces ecdsa as a dependency with no fixed version available.
-        run: pip install pip-audit && pip-audit -r backend/requirements.txt --ignore-vuln CVE-2024-23342
+        run: pip install pip-audit && pip-audit -r backend/requirements.txt

.gitignore

@@ -1,6 +1,5 @@
 # Claude / project meta — never commit
 CLAUDE.md
-FEATURES.md
 .claude/
 _project_specs/
 
@@ -51,3 +50,9 @@ htmlcov/
 # Docker
 .docker/
 Ideas.md
+
+# Local dev/test utilities (never commit)
+scripts/zwave-mock-gateway.py
+
+# Docs (local only)
+docs/database-model.md

CHANGELOG.md

@@ -0,0 +1,698 @@
+# Changelog
+
+All notable changes to **Homelable** are documented here.
+
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [3.2.0] - 2026-08-10
+
+### Features
+
+- Rack canvas: a third design type, next to network and electrical, with racks, mounted devices and port-to-port patching. (#315)
+- Declarative SVG faceplates picked from a visual catalog, including desktop NAS enclosures in 2, 4 and 5 bays. (#315)
+- Rack gear is filed in the Device Inventory, and a mount can be picked from the rackable entries. (#315)
+- Cables carry a type, colour, label and properties, printed on the canvas at the midpoint of the run. (#315)
+- Mounted devices follow the status check of the logical node they match, and links can be imported from the logical canvas. (#315)
+- Getting Started walkthrough covers the rack canvas. (#315)
+- Show the logical view of a mounted device, and link a mount to any Device Inventory entry. (#323)
+
+### Fixes
+
+- Guard rack rows against cross-design saves and half-applied faceplates. (#315)
+- A rack height edit no longer orphans its mounts; height and colour commit on blur, and a blanked field no longer shrinks the rack. (#315)
+- Import links is idempotent, and stays usable after a run that matched nothing. (#315)
+- Stop the device modal losing cables, status and inventory rows. (#315)
+- Name rack inventory entries the way the Device Inventory does. (#315)
+- Stamp the linked node's last-seen with an offset. (#323)
+- Bump js-yaml to 4.3.1 for CVE-2026-59870. (#315)
+- CI: stop the secret scan reporting pytest names as Lob keys. (#315)
+
+### Docs
+
+- Document the rack canvas for users. (#315)
+
+## [3.1.2] - 2026-08-01
+
+### Features
+
+- Generic OIDC authentication: backend sessions and browser login flow. Thanks @autogpt-elendir. (#306)
+- Brand icon picker for services, in a dedicated add/edit modal. (#313)
+- MCP: lightweight node lookup tools. Thanks @Nebesz. (#312)
+
+### Fixes
+
+- Sync the MCP node and edge type enums with the frontend, gated in CI against drift. Thanks @Nebesz. (#311)
+- Harden OIDC callback validation. (#306)
+- Use the official Homelable logo on the login page. (#306)
+- Clear the seven open dependabot alerts and refresh vulnerable frontend packages. (#317, #306)
+
+### Docs
+
+- Document OIDC setup and configuration. (#306)
+
+## [3.1.1] - 2026-07-19
+
+### Features
+
+- Drag to reorder services in the node detail panel. Thanks @Isilla. (#302)
+- Getting Started walkthrough tour with first-run canvas detection. (#300)
+
+### Fixes
+
+- Round-trip Show Port Numbers on YAML export/import. (#301)
+- Render error toasts on a red surface. (#300)
+
+### Docs
+
+- Rework README header with logo, badges, and nav links. (#300)
+
+## [3.1.0] - 2026-07-18
+
+### Features
+
+- Drag to reorder node properties. (#296)
+- Search for nodes and properties. Thanks @Floyddotnet. (#294)
+- Widen zone modal into two columns. (#293)
+- Autosave canvas after a configurable inactivity delay (opt-in). Thanks @nicolabottini. (#289)
+- MCP: `design_id` on approve_device + `delete_design` tool. Thanks @nicolabottini. (#281)
+
+### Fixes
+
+- Scanner: decouple port discovery from version detection. (#295, #277)
+- Allow undo after Auto Layout and YAML import. (#290)
+- Move edge waypoints when the connected node or its container is dragged. (#288)
+- Keep container host height when editing an unrelated field. (#287)
+- Keep container children in place when editing a host node. Thanks @nicolabottini. (#286)
+- `list_pending_devices` MCP tool leaked approved/hidden inventory rows. Thanks @MikeSviblov. (#273)
+
+### Docs
+
+- Fix MCP client transport to http (was sse). (#275)
+
+## [3.0.0] - 2026-07-10
+
+### Added
+
+- Proxmox VE import: pull hosts, VMs and LXC into inventory, with optional scheduled auto-sync and a manual re-sync button (connection config is now env-only). (#253, #259)
+- Scheduled auto-sync for Zigbee & Z-Wave imports. (#270)
+- Floor plan map background, LQI-based edge coloring, and Zigbee path highlighting. Thanks @pranjal-joshi. (#207)
+- Customizable connection points per node side. (#249)
+- Configurable edge line style + width per type and per edge, plus selectable endpoint marker shapes. (#250, #252)
+- Create a new canvas by copying an existing one. (#257)
+- Prompt on duplicate device instead of silently blocking/merging on approve. (#261)
+- Active design synced to URL for refresh/share. (#263)
+- MCP can target a specific design/canvas, create canvases, and auto-position nodes with auto-assigned edge handles. Thanks @nicolabottini. (#266)
+
+### Fixed
+
+- Mesh (Zigbee/Z-Wave) import: duplicate-node crash and coordinator now routed to pending. (#247)
+- Keep mesh/cluster links so edges resolve onto a second canvas. (#254)
+- Preserve edge connection points in YAML export/import. (#255, #208)
+- Harden media path handling against path injection. (#256)
+- Match scanned devices to canvas nodes by ip-token and MAC. (#262, #258)
+- Record ScanRun for scheduled Proxmox auto-sync. (#269)
+
+### Docs
+
+- User-facing FEATURES.md. (#248)
+- CHANGELOG with full release history. (#264)
+
+## [2.6.1] - 2026-06-30
+
+### Added
+
+- Z-Wave nodes can be added/edited manually. A Z-Wave group (Controller / Router / End Device) is now in the Add/Edit node type selector, matching Zigbee. Mesh-radio nodes default to no status check.
+
+### Fixed
+
+- Standalone (frontend-only) multi-canvas (designs) support, originally merged in #244 after the 2.6.0 tag with no version bump.
+
+## [2.6.0] - 2026-06-28
+
+Device Pending is gone — replaced by **Device Inventory**: devices stay in an inventory, can be placed in multiple canvases, rescanned and updated. New **Z-Wave** section: scan, import and store Z-Wave devices like Zigbee.
+
+### Added
+
+- SVG export option in the canvas export modal, alongside PNG (#238).
+- Deep-scan HTTP probe + Device Inventory: scans probe HTTP services and surface a per-device inventory (#222, closes #195).
+- Z-Wave network scan via the MQTT bridge (#224).
+- Inventory timestamps on nodes — nodes show when their inventory was last collected (#233).
+- New nodes drop at the centre of the visible canvas instead of off-screen (#234).
+- Expanded MAC OUI database: router, switch, AP, NAS and camera vendor prefixes (#220).
+
+### Fixed
+
+- Optional white background on export and working downloads in Firefox (#239, closes #165).
+- MCP-created nodes/edges attach to the active design instead of floating (#237, closes #225).
+- Stopping a scan interrupts the running nmap range immediately (#236, closes #218).
+- Auto-layout orders Proxmox children by parent port number (#235).
+- Copy-to-clipboard for Markdown works on non-secure HTTP origins (#219).
+
+### Docs
+
+- Documented the `SCANNER_HTTP_RANGES` port-spec format (#232).
+
+## [2.5.1] - 2026-06-18
+
+### Fixed
+
+- Manually resized nodes — including VM/LXC nodes nested inside a Proxmox container — keep their size on reload instead of snapping back to content-fit.
+- Node detail panel has a Size section for pixel-exact width/height; fields resync live when dragging a corner handle.
+- Adding an LXC/VM under a non-container-mode Proxmox node no longer confines it to a tiny box — it stays a free, draggable node.
+
+### Security
+
+- Resolved high-severity npm audit advisories (`esbuild`, `form-data`, `vite` → 7.3.5).
+- Bumped `python-multipart` to 0.0.31 (CVE-2026-53538/53539/53540).
+
+## [2.5.0] - 2026-06-11
+
+### Added
+
+- Scan History modal with run duration, finished timestamp, and kind/status filters (#203).
+- Container nesting: drag a node onto a container node to nest it; detach/re-parent via an editable container selector (#202).
+- Editable node groups: add/remove members and edit the group description directly (#200).
+- Multi-line edge labels (#199).
+- Per-service status checks with offline colouring (#198).
+
+### Fixed
+
+- Reduce status flapping, add IPv6 ping, colour manually-added web services (#198).
+- Keep non-HTTP services grey instead of red (#198).
+- Idempotent WebSocket connection removal — release the slot on any error (#198).
+- Persist group description with Ctrl+S, not only on blur (#200).
+
+### Security
+
+- Resolve Dependabot and code-scanning alerts; bump hono to 4.12.21+ (#197).
+- Bump zeroconf to 0.149.12 for CVE-2026-48045 (#202).
+
+## [2.4.0] - 2026-06-05
+
+### Added
+
+- Multiple designs (canvases): build and switch between separate diagrams, plus a new electrical-device node type (#177).
+- Copy & paste nodes between designs (#189).
+- Switch port numbers (up to 64 ports) plus a new fibre-optic link style (#172).
+- Read-only Live View link in the header for sharing or wall displays (#185).
+- Scans keep discovered MAC addresses when a device is approved (#178).
+- Richer AI/MCP control: assistants can set the full set of node fields on create/update (#180).
+
+### Changed
+
+- Settings moved into a dedicated window for a cleaner sidebar (#188).
+- "Hide IP" option now lives in Settings and is remembered between sessions (#189).
+- Smoother link animations for flowing/snake styles (#187).
+
+### Fixed
+
+- "Show Port Numbers" now persists after reload (#191).
+- The Save button works again (previously only Ctrl/Cmd+S) (#190).
+- Zigbee re-import correctly brings back already-approved devices (#176).
+
+### Security
+
+- Dependency updates: zeroconf, qs, brace-expansion (#175, #182).
+
+## [2.3.0] - 2026-05-31
+
+### Added
+
+- Full node schema over MCP: `create_node` / `update_node` expose the complete backend schema (`os`, `notes`, `mac`, `services`, `cpu_count`, `cpu_model`, `ram_gb`, `disk_gb`, `properties`, …); `get_canvas` round-trips the same fields (#174).
+- MAC carried onto approved nodes from a scan (#168).
+- Richer switch & edge modeling: switch port cap raised to 64, port numbers shown, new fibre edge type.
+
+### Fixed
+
+- Canvas includes the MAC property on the approved node so it shows immediately after approval (#168).
+- Zigbee: revive orphaned approved devices on re-import instead of dropping them (#167).
+
+### Security
+
+- Bump `zeroconf` 0.131.0 → 0.149.7 for CVE fixes.
+
+## [2.2.0] - 2026-05-29
+
+### Added
+
+- Laptop & mobile node types with theme-coherent styling (#166).
+- Collapsible / expandable zones — `collapsed` is now a first-class `NodeData` field with edge rewiring and read-only liveview support (#158).
+- LXC / bare-metal MCP install script `lxc-mcp-install.sh` with env-var overrides and repo-clone fallback; MCP image published to GHCR (#163).
+
+## [2.1.1] - 2026-05-16
+
+### Fixed
+
+- LiveView: nest Docker container children under their host node; apply saved theme & custom style on load.
+
+## [2.1.0] - 2026-05-16
+
+### Added
+
+- Draggable edge endpoints — reconnect either end of an edge to another node/handle; Proxmox containers gain snap points (#150).
+- Docker containers can live inside VMs, Proxmox hosts or LXCs; parent auto-cleaned on type change (#153, #154).
+- Group node side handles (top/right/bottom/left) for proper edge attachment (#152).
+- Multiple IPs per node — paste several IPs separated by comma/space/newline, each clickable individually (#136).
+- Zigbee device properties (IEEE, Vendor, Model, LQI) auto-populated on approve / re-import (#148).
+- Homepage widget stats endpoint: new `/stats` API for gethomepage integration (closes #131, #149).
+- Zone modal polish: centered opacity thumb, fixed font casing, full keyboard + ARIA support (#106).
+
+### Security
+
+- Dropped `passlib` in favour of direct `bcrypt`; status-check targets reject CLI-flag injection.
+
+## [2.0.3] - 2026-05-13
+
+### Changed
+
+- Remove check method for Zigbee nodes.
+
+## [2.0.2] - 2026-05-11
+
+### Added
+
+- Activated dashboardicons icons — brand-new icons selectable for nodes.
+
+### Fixed
+
+- Various modal fixes.
+
+## [2.0.1] - 2026-05-11
+
+### Added
+
+- New Zigbee nodes available in the new/edit node modal.
+
+## [2.0.0] - 2026-05-11
+
+A major milestone: Zigbee2MQTT integration, a new pending-devices modal, text nodes and alignment guides.
+
+### Added
+
+- **Zigbee2MQTT integration** (thanks @pranjal-joshi): import a full Zigbee network map from Z2M as a background scan run; three new node types (Coordinator, Router, End Device); MQTT TLS with optional cert-verify skip; imported devices flow through the pending section with edge persistence.
+- **New pending devices modal**: full-screen grid with cards, filters (IP / Zigbee / all), search, multi-select and bulk restore.
+- **Text node type** for free-form annotations (#138).
+- **Alignment guides + snap** while dragging nodes, built on `OnNodeDrag` (#139).
+- **Per-node services toggle** to show/hide the services list on the node (thanks @findthelorax) (#107).
+- Zigbee node types exposed in the Custom Style editor.
+
+### Fixed
+
+- Status checker: ms timeout for ping on macOS.
+- Scan: default `check_method='ping'` for approved devices.
+- Detail panel: handle non-Z timezone offsets in Last Seen.
+- Groups: preserve children + size on edit; fix status WebSocket proxy.
+- Pending: drop dangling `onNodeApproved` call; null-safe pending IP in SearchModal.
+- Text node: persist text in `label` across reloads.
+
+### Security
+
+- Bump `fast-uri` (GHSA-q3j6-qgpj-74h6, GHSA-v39h-62p7-jpjc), `axios` ^1.15.2, `python-multipart`.
+- Sanitize MQTT error messages to prevent credential leakage.
+
+## [1.13.0] - 2026-05-03
+
+### Added
+
+- New **Firewall** node type under Add Node → Hardware, with distinct flame icon and red accent.
+- Up to **48 bottom connection points** per node (slider, previously capped at 4); the node card grows wider as handles are added.
+
+### Fixed
+
+- Sidebar no longer freezes on Scan History after starting a scan.
+- Delete confirmation respects Cancel — clicking Cancel keeps the modal open.
+
+## [1.12.0] - 2026-04-24
+
+### Added
+
+- **Custom Style Editor**: per-node-type border/background/icon colour + opacity, per-edge colour/opacity/path/animation, default size per type, "Apply to existing nodes" and "Apply All to Canvas"; saved with the canvas.
+
+### Changed
+
+- Accessibility overhaul: consistent hover/focus borders, pointer cursors, keyboard navigation and Enter-to-apply across all modals (#108).
+- IP address hint moved below the field; hover border colour toned down.
+
+### Fixed
+
+- Edge labels and the `+` waypoint handle stay on the routed path when waypoints are used (#94).
+- Edge type select displays its full label (e.g. "IoT / Zigbee") instead of the raw value.
+- Status dot overlapping IP address in node cards.
+- Canvas style modal layout on smaller screens.
+- MCP session manager routing.
+
+## [1.11.0] - 2026-04-23
+
+### Added
+
+- **Docker Host** node type with container mode support (visual group for containers).
+- **Docker Container** node type, nestable inside a Docker Host.
+- Container mode now works for `docker_host`, `vm` and `lxc` (was Proxmox-only).
+
+### Changed
+
+- Service badges prioritise the service name; path truncates gracefully with a hover tooltip.
+- Node resizer handle hit area enlarged (8px → 16px).
+
+### Fixed
+
+- Container mode not persisting after save/reload for non-Proxmox types.
+- Container mode toggle having no visual effect on `docker_host` nodes.
+- Status dot overlapping node content; consistent top-right placement.
+- Missing icon/label gap in ProxmoxGroupNode container header.
+- IP shown unmasked in ProxmoxGroupNode when hide-IP is enabled.
+
+## [1.10.2] - 2026-04-21
+
+### Added
+
+- **Logout button** at the bottom of the sidebar (normal mode only).
+
+### Fixed
+
+- Pending Devices checkbox click no longer opens the approval modal.
+- NaN sent to the API when the status-check interval input is cleared.
+- Potential open-redirect in the update badge (release URL scheme now validated).
+
+## [1.10.1] - 2026-04-20
+
+### Added
+
+- PNG export quality selector: Standard (1×), High (2×, default), Ultra (4×) (#89).
+- Zone colour opacity sliders for text/border/background (#72).
+- Optional service paths (e.g. `/admin`) appended to the clickable URL; port optional when a path is set (thanks @findthelorax) (#86).
+
+### Fixed
+
+- Bulk-approved nodes appear on canvas immediately (node IDs were null before DB flush).
+- Proxmox container mode: visible properties now shown; custom icon now applied.
+- `approve_device` returns 404 on missing device, 409 on double-approve (was 200).
+- Node form no longer retains previous-session values when reopened in Add mode (#87).
+
+## [1.10.0] - 2026-04-19
+
+### Added
+
+- Bulk approve/hide pending devices (#70).
+- IPv6 support & multiple comma-separated IPs per node (#60).
+- Clickable IP addresses in the detail panel (#78).
+- Connection handles on zone/group rect nodes (#58).
+- Automatic DB backup before schema migrations.
+- Drag group from its title (#76); double-click a node to open its edit modal (#65).
+
+### Fixed
+
+- Node width no longer expands when long content overflows after a user resize.
+- Proxmox nodes with `container_mode=false` restore their saved width on reload.
+- Added curl to the backend image for the default healthcheck.
+
+## [1.9.0] - 2026-04-09
+
+### Added
+
+- **Node properties system**: dynamic key/value/icon/visible properties replacing static hardware fields; visible ones shown on the node card; 20 Lucide icons; existing hardware data auto-migrated.
+- **Edge waypoints**: click `+` to add, drag to move, double-click to remove; Bezier and Smooth step supported; persisted to backend.
+- **Basic edge animation** mode (native moving-dash), alongside Snake and Flow.
+- App version shown in sidebar with a GitHub release update check.
+
+### Fixed
+
+- Node height no longer overflows when properties are added to a resized node.
+- Dot grid alignment with the snap grid.
+- Node selection layout shift.
+
+## [1.8.3] - 2026-04-06
+
+### Added
+
+- Finer canvas grid: snap reduced from 16px to 8px.
+
+### Changed
+
+- Updated frontend npm dependencies; upgraded lucide-react; removed unused Proxmox/LXC install scripts.
+
+## [1.8.2] - 2026-04-05
+
+### Fixed
+
+- Scan no longer starts before confirmation — "Scan Network" opens the config modal first.
+- Windows ping compatibility (`-n 1 -w 1000` instead of Linux/macOS flags).
+
+## [1.8.1] - 2026-04-05
+
+### Added
+
+- Search now includes pending devices in both the canvas search bar (Ctrl+F) and command palette (Ctrl+K).
+
+### Fixed
+
+- Timestamps (scan history, discovery time, Last Seen) now show local time instead of UTC.
+
+## [1.8.0] - 2026-04-04
+
+### Added
+
+- Configurable 1–4 bottom connection points per node.
+- Fit view on load.
+- Inline Type and Icon pickers in the node modal.
+
+### Changed
+
+- **Scanner rewrite**: Phase 1 concurrent asyncio ping sweep (50 parallel pings) supplemented by `/proc/net/arp`; Phase 2 explicit `-sS`/`-sT` scan type with 60s host-timeout; resilient gather so one failing host no longer aborts the batch.
+
+### Fixed
+
+- Root logger StreamHandler so `app.*` logs are visible in Docker.
+- CIDR validation on frontend and backend to prevent nmap argument injection.
+- Pre-fetch canvas/hidden IPs before the scan loop (no N+1 queries); ARP table read off the event loop.
+- Hide/ignore on a missing device returns 404 instead of 500.
+
+## [1.7.1] - 2026-04-02
+
+### Added
+
+- Concurrent status checks via `asyncio.gather`, ending "maximum instances reached" spam.
+- Improved IoT detection: two-phase nmap scan finds Shelly, Sonoff, Tapo devices with no open TCP ports.
+- mDNS/Bonjour discovery (`_shelly._tcp`, `_esphomelib._tcp`, `_hap._tcp`, `_mqtt._tcp`, …) in parallel with nmap.
+- 20+ IoT vendor MAC OUIs and CoAP ports added; IoT ranked above generic server.
+
+### Fixed
+
+- LXC/VM container mode: attaching to a Proxmox no longer creates a spurious edge; nesting is instant.
+- Scheduler reliability: DetachedInstanceError, duplicate timestamps, shutdown handling, interval validation.
+
+### Dependencies
+
+- Added `zeroconf==0.131.0` for mDNS discovery.
+
+## [1.7.0] - 2026-04-01
+
+### Added
+
+- **Lasso / box selection** — draw a rectangle to select multiple nodes; hold Space to pan; lasso/pan toggle in the controls.
+- **Named groups** — group 2+ nodes into a resizable, renamable container with hide-border option and per-member navigation; persisted across save/reload.
+- **Canvas search (Ctrl+F)** — filter nodes by label, IP, hostname, service; live match count; click to fly the camera.
+
+### Fixed
+
+- LXC install script: `apt-get update` runs verbosely with `--fix-missing` to handle stale Debian mirrors (fixes #36).
+- Group parent/child relationships restore after save + reload.
+- Removed React Flow's default grey background from container node types.
+
+## [1.6.0] - 2026-03-30
+
+### Added
+
+- Scan deduplication — pending devices already on canvas or hidden are skipped on rescan; stale entries purged at scan start.
+- Dedicated Settings panel (status-check interval moved out of the Scan Config modal).
+- Live interval update without a server restart.
+- Separate `/api/v1/settings` endpoint for the check interval.
+
+### Fixed
+
+- DEL key deletes selected nodes (previously Backspace only).
+- Node deletion via shortcut/detail panel is undoable with Ctrl+Z.
+- APScheduler guards against double-start and unguarded reschedule calls.
+
+## [1.5.0] - 2026-03-29
+
+### Added
+
+- Inline service editing in the detail panel (pencil icon).
+- Edge animation modes: None, Snake, Flow — fully persisted.
+- Zone improvements: rename Rectangle → Zone, border-width selector, label position, text-size options.
+
+### Fixed
+
+- Edge animation not saved on new connections.
+- Backend 422 when saving canvas with string animation values.
+- Snake and Flow animations rendering identically in production.
+- Login returned 500 instead of 401 when a bcrypt hash had `$` stripped by the shell (#21).
+- Hardcoded CORS in docker-compose; clearer login error messages.
+
+## [1.4.0] - 2026-03-28
+
+### Added
+
+- **Live View** — share a read-only view of the canvas on your network, no login required.
+- Resizable nodes with persisted width/height.
+
+### Fixed
+
+- QEMU arm64 crash during Docker image build (`npm ci` illegal instruction on ARM64).
+- nginx `reload-or-start` fallback broken on fresh LXC installs.
+
+### CI
+
+- ShellCheck + hadolint linting; Docker smoke tests and full-stack integration tests.
+
+## [1.3.3] - 2026-03-27
+
+### Fixed
+
+- Scan failures on fresh Docker installs — `service_signatures.json` moved into the app package so the volume mount no longer overwrites it.
+- Missing `ping` on Docker (`iputils-ping` added).
+- Thread-safe signature-file loading; clear error if the file is missing.
+- CORS restricted to the HTTP methods/headers the frontend uses.
+
+## [1.3.2] - 2026-03-27
+
+### Fixed
+
+- Ping check method on fresh Docker installs — `iputils-ping` added to the backend image (`python:3.13-slim` ships without `ping`).
+
+## [1.3.1] - 2026-03-27
+
+### Added
+
+- **YAML import/export** of the full canvas topology (nodes, edges, hardware specs, connections); import merges without overwriting; Dagre auto-layout on import; toolbar Import/Export buttons.
+
+### Fixed
+
+- ESLint 10 incompatibility from `npm audit fix` — pinned back to ESLint 9.x.
+
+### Docs
+
+- Split installation into `INSTALLATION.md`; documented the network scanner and dev mode.
+
+## [1.3.0] - 2026-03-21
+
+### Added
+
+- Hardware specs per node (CPU model, cores, RAM, Disk) with "Show on node" and GB → TB formatting.
+- `Docker Host` node type (Anchor icon), themed across all 5 themes.
+- Group rectangle border style: Solid, Dashed, Dotted, Double, None.
+- Categorized node-type selector (Hardware / Virtualization / IoT / Generic).
+
+## [1.2.2] - 2026-03-17
+
+### Added
+
+- `scripts/update.sh` for fast in-place LXC updates (never touches `.env` or DB).
+
+### Fixed
+
+- `crypto.randomUUID` crash on HTTP/LXC installs — polyfill fallback.
+- WebSocket failure on LXC (hardcoded port 8000 bypassing Nginx); added `/api/v1/status/ws/` upgrade block.
+- Production build crash on LXC (test files in `tsconfig.app.json`).
+
+### Security
+
+- JWT no longer exposed in the WebSocket URL — sent as the first message after connect.
+
+## [1.2.1] - 2026-03-16
+
+### Added
+
+- **MCP server** with HTTP/SSE transport for AI integration (Claude Code compatible); `parent_id` exposed in `update_node`; service-key auth for MCP → backend.
+
+### Fixed
+
+- "Add node" appeared broken with an empty Label — native validation doesn't render in Radix Dialog portals; now shows an inline error.
+- SSE streaming crash; reduced `get_canvas` token usage.
+
+## [1.2.0] - 2026-03-13
+
+### Added
+
+- Edge flow animation (per-edge toggle); Proxmox cluster edges animate bidirectionally.
+- Keyboard shortcuts: Undo/Redo, Ctrl+K search, copy/paste, Ctrl+S save, `?` reference.
+- Canvas history (50-entry undo/redo stack) with toolbar buttons.
+- Node search spotlight (Ctrl+K) with fuzzy match and fly-to.
+- Copy/paste nodes (Ctrl+C / Ctrl+V) with 50px offset and fresh IDs.
+- Markdown table export of the node inventory.
+- Clickable hostname in the detail panel.
+- Shortcuts reference modal.
+
+## [1.1.1] - 2026-03-11
+
+### Added
+
+- New logo and favicon; page title updated to Homelable.
+- **Hide IPs** toggle in the sidebar — masks the last two octets.
+
+### Fixed
+
+- Auto-layout: peer nodes placed on the same row (no staircase); correct left-to-right ordering; child nodes always below their parent.
+
+## [1.1.0] - 2026-03-10
+
+### Added
+
+- **Group rectangles** — decorative resizable zones with configurable label/font/position/colours and z-order; saved with the canvas.
+- Add/remove services manually in the detail panel.
+- All TCP services now clickable (HTTPS auto-detected for 443/8443; non-web ports excluded).
+
+## [1.0.0] - 2026-03-09
+
+First stable public release of **Homelable**, a self-hosted homelab visualization tool.
+
+### Added
+
+- **Canvas**: interactive React Flow diagram; 11 node types; 5 edge types; Proxmox nested nodes; Dagre auto-layout; zoom/pan; snap-to-grid; PNG export.
+- **Network discovery**: nmap scanner over CIDR ranges; pending-device queue (approve/hide/ignore); service fingerprinting; MAC OUI detection for QEMU/Proxmox/VMware.
+- **Status monitoring**: per-node ping/http/https/tcp/ssh/prometheus/health checks; live WebSocket updates; scheduled background checks.
+- **Auth & persistence**: single-user JWT auth (bcrypt in `.env`); SQLite canvas state with an explicit Save button.
+- **Standalone mode**: backend-free diagram editor with localStorage persistence.
+- **Install options**: Docker Compose, Proxmox LXC, manual Debian/Ubuntu script.
+
+[2.6.1]: https://github.com/Pouzor/homelable/compare/v2.6.0...v2.6.1
+[2.6.0]: https://github.com/Pouzor/homelable/compare/v2.5.1...v2.6.0
+[2.5.1]: https://github.com/Pouzor/homelable/compare/v2.5.0...v2.5.1
+[2.5.0]: https://github.com/Pouzor/homelable/compare/v2.4.0...v2.5.0
+[2.4.0]: https://github.com/Pouzor/homelable/compare/v2.3.0...v2.4.0
+[2.3.0]: https://github.com/Pouzor/homelable/compare/v2.2.0...v2.3.0
+[2.2.0]: https://github.com/Pouzor/homelable/compare/v2.1.1...v2.2.0
+[2.1.1]: https://github.com/Pouzor/homelable/compare/v2.1.0...v2.1.1
+[2.1.0]: https://github.com/Pouzor/homelable/compare/v2.0.3...v2.1.0
+[2.0.3]: https://github.com/Pouzor/homelable/compare/v2.0.2...v2.0.3
+[2.0.2]: https://github.com/Pouzor/homelable/compare/v2.0.1...v2.0.2
+[2.0.1]: https://github.com/Pouzor/homelable/compare/v2.0.0...v2.0.1
+[2.0.0]: https://github.com/Pouzor/homelable/compare/v1.13.0...v2.0.0
+[1.13.0]: https://github.com/Pouzor/homelable/compare/v1.12.0...v1.13.0
+[1.12.0]: https://github.com/Pouzor/homelable/compare/v1.11.0...v1.12.0
+[1.11.0]: https://github.com/Pouzor/homelable/compare/v1.10.2...v1.11.0
+[1.10.2]: https://github.com/Pouzor/homelable/compare/v1.10.1...v1.10.2
+[1.10.1]: https://github.com/Pouzor/homelable/compare/v1.10.0...v1.10.1
+[1.10.0]: https://github.com/Pouzor/homelable/compare/v1.9.0...v1.10.0
+[1.9.0]: https://github.com/Pouzor/homelable/compare/v1.8.3...v1.9.0
+[1.8.3]: https://github.com/Pouzor/homelable/compare/v1.8.2...v1.8.3
+[1.8.2]: https://github.com/Pouzor/homelable/compare/v1.8.1...v1.8.2
+[1.8.1]: https://github.com/Pouzor/homelable/compare/v1.8.0...v1.8.1
+[1.8.0]: https://github.com/Pouzor/homelable/compare/v1.7.1...v1.8.0
+[1.7.1]: https://github.com/Pouzor/homelable/compare/v1.7.0...v1.7.1
+[1.7.0]: https://github.com/Pouzor/homelable/compare/v1.6.0...v1.7.0
+[1.6.0]: https://github.com/Pouzor/homelable/compare/v1.5.0...v1.6.0
+[1.5.0]: https://github.com/Pouzor/homelable/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/Pouzor/homelable/compare/v1.3.3...v1.4.0
+[1.3.3]: https://github.com/Pouzor/homelable/compare/v1.3.2...v1.3.3
+[1.3.2]: https://github.com/Pouzor/homelable/compare/v1.3.1...v1.3.2
+[1.3.1]: https://github.com/Pouzor/homelable/compare/v1.3.0...v1.3.1
+[1.3.0]: https://github.com/Pouzor/homelable/compare/v1.2.2...v1.3.0
+[1.2.2]: https://github.com/Pouzor/homelable/compare/v1.2.1...v1.2.2
+[1.2.1]: https://github.com/Pouzor/homelable/compare/v1.2.0...v1.2.1
+[1.2.0]: https://github.com/Pouzor/homelable/compare/v1.1.1...v1.2.0
+[1.1.1]: https://github.com/Pouzor/homelable/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/Pouzor/homelable/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/Pouzor/homelable/releases/tag/v1.0.0

FEATURES.md

@@ -0,0 +1,293 @@
+# Homelable Features
+
+Here's what Homelable can do. One line on what each feature is, then how to switch it on and use it.
+
+> **Two modes.** Same UI, two ways to run it:
+> - **Full mode**, with the backend (Docker/LXC). Everything works.
+> - **Standalone mode** (`VITE_STANDALONE=true`), no backend, canvas lives in your browser's `localStorage`. Great for just drawing; anything that needs a server (scanning, imports, device inventory, floor-plan upload, live view) is hidden.
+>
+> Features marked 🔒 need Full mode.
+
+---
+
+## Table of Contents
+
+1. [Zones](#1-zones)
+2. [Groups & Nesting](#2-groups--nesting)
+3. [Text Annotations](#3-text-annotations)
+4. [Multiple Canvases](#4-multiple-canvases)
+5. [Rack Canvas](#5-rack-canvas)
+6. [Customize Style](#6-customize-style)
+7. [Floor Plan](#7-floor-plan-)
+8. [Network Scanner (IP import)](#8-network-scanner-ip-import-)
+9. [Zigbee Import](#9-zigbee-import-)
+10. [Z-Wave Import](#10-z-wave-import-)
+11. [Proxmox VE Import](#11-proxmox-ve-import-)
+12. [Device Inventory](#12-device-inventory-)
+13. [Live Status Monitoring](#13-live-status-monitoring-)
+14. [Export (PNG / SVG / YAML / Markdown)](#14-export)
+15. [Live View (read-only public canvas)](#15-live-view-)
+16. [Gethomepage Widget](#16-gethomepage-widget-)
+17. [MCP Server (AI integration)](#17-mcp-server-)
+18. [Settings & Shortcuts](#18-settings--shortcuts)
+19. [Authentication (Local / OpenID Connect)](#19-authentication-local--openid-connect-)
+
+---
+
+## 1. Zones
+
+**What:** Labeled boxes to group devices by area: "Living room", "Rack 1", "DMZ", whatever makes sense to you.
+
+**Use:**
+- Sidebar → **Add Zone**. Give it a title and a color, then drag it around and resize it.
+- Drop nodes onto a zone and Homelable asks if you want to add them to it.
+- Zones sit behind your nodes and move on their own. They're just there to keep things tidy.
+
+---
+
+## 2. Groups & Nesting
+
+**What:** Some devices hold others, like a **Proxmox** host with its **VMs** and **LXCs** inside. Those show up as an expandable container.
+
+**Use:**
+- Drag a `vm` or `lxc` onto a `proxmox` node, confirm **Add to container**, and it becomes a child.
+- Click the container header to fold it open or shut; it resizes itself around what's inside.
+- The Zigbee and Z-Wave imports build the same kind of hierarchy for you (coordinator → routers → end devices).
+
+---
+
+## 3. Text Annotations
+
+**What:** Loose text labels for notes, section titles, or anything you want to call out on the canvas.
+
+**Use:** Sidebar → **Add Text**, type, drop it where you want, style it.
+
+---
+
+## 4. Multiple Canvases
+
+**What:** More than one diagram in a single install, say "Network", "Home automation", "Rack layout", each with its own nodes, links, floor plan, and style.
+
+**Use:**
+- The **canvas switcher** is at the top of the sidebar. Click to jump between canvases, or **New Canvas** to start a fresh one.
+- Hover a canvas to **Edit** it (name, icon, floor plan) or **Delete** it. You can't delete the last one.
+- Each canvas saves on its own, so hit **Save Canvas** after you change something.
+
+---
+
+## 5. Rack Canvas
+
+**What:** The physical side of the lab, as its own kind of canvas: racks, the gear mounted in them, and the patch cables between their ports. Where a diagram says what talks to what, a rack says what sits in which U, and which switch port the uplink lands on.
+
+**Use:**
+- **Canvas switcher** → **New Canvas** → Kind **Rack**. A canvas cannot change kind afterwards.
+- **Add Rack** in the header drops a rack; double-click its frame for U height, 19"/10" width, numbering direction, colours and the enclosed/open look.
+- **+ Device** in the sidebar mounts something: an entry from your **Device Inventory** 🔒, a **new device** (which joins the inventory tagged *Rack devices*), or a rack-only **accessory** (blank, shelf, cable manager). Double-click a plate to edit it, and **Unmount** to take it out — the device itself stays in the inventory.
+- Gear occupies a U range and part of a 12-column width grid, so half- and third-width machines share a U. A drop snaps to the nearest free slot, an impossible one previews red, and growing a device relocates it to the nearest slot that fits.
+- The **Faceplate** field opens a visual catalog — servers, switches, routers, patch panels, UPS and PDUs, desktop NAS towers, shelves and blanks — drawn as vector artwork that scales with the rack and follows your theme.
+- **Patch**: drag from one port to another (or click both in turn) to cable them, across racks if you need to. Click a cable to select it, then **Delete** or **Unplug**. A header select controls whether cables show on hover, always, or not at all.
+- **Status**: pin a mount's colour, or set **Check device** 🔒 so it follows the status check already configured on the matching diagram node.
+- **Import links** 🔒 derives patches from the physical links already drawn on your diagrams. Run it again after racking more gear — pairs already cabled are left alone.
+- Saving is explicit — **Save Rack** — like any other canvas.
+
+> **Full documentation:** [docs/rack-canvas.md](./docs/rack-canvas.md)
+
+---
+
+## 6. Customize Style
+
+**What:** Repaint the whole thing with a preset theme, or roll your own node and edge colors.
+
+**Use:**
+- Toolbar → **Style**. Pick a preset: **Default**, **Dark**, **Light**, **Neon**, or **Matrix**.
+- Or pick **Custom** and hit its **Edit** button to set border/background colors per node type and link colors per edge type.
+- Theme and custom colors are saved **per canvas** on your next **Save Canvas**.
+
+---
+
+## 7. Floor Plan 🔒
+
+**What:** Put a background image (a house plan, an office layout, a rack diagram) behind a canvas and lay your devices out on top of it.
+
+**Use:**
+- Open the **canvas switcher** → **Edit** the active canvas (or double-click the floor plan already on the canvas).
+- In the **Floor Plan** section, upload an image and set its size and lock state.
+- The image lives on the backend and is loaded by URL, never baked into the canvas, so your canvases stay light. *(See ADR-001; floor plans are Full mode only.)*
+
+---
+
+## 8. Network Scanner (IP import) 🔒
+
+**What:** Point `nmap` at your network, fingerprint the services it finds, and turn hosts into nodes.
+
+**Use:**
+1. Sidebar → **Scan Network**. Scan History opens and keeps refreshing until it's done.
+2. Set the CIDR ranges you want in `SCANNER_RANGES` (`.env`), or override them per scan in the dialog.
+3. Whatever it finds shows up in the **Device Inventory** (below) to approve, hide, or ignore.
+
+**Deep scan (custom ports):** to catch services on odd ports, add them in `.env`:
+```env
+SCANNER_HTTP_RANGES=["8080","9000-9100"]
+SCANNER_HTTP_PROBE_ENABLED=true
+SCANNER_HTTP_VERIFY_TLS=false
+```
+
+**Root note:** SYN scans and OS detection need root. If a scan trips on permissions, run `scripts/run_scan.py` with `sudo`, or on Linux give nmap the `NET_RAW` capability. Full details in the [README](./README.md#network-scanner).
+
+---
+
+## 9. Zigbee Import 🔒
+
+**What:** Pull your **Zigbee2MQTT** topology in over MQTT and drop every device on the canvas as a typed node.
+
+**Use:**
+1. Sidebar → **Zigbee Import**.
+2. Enter broker host/port (default `1883`), any credentials, and the base topic (default `zigbee2mqtt`).
+3. **Test Connection** → **Fetch Devices** → pick from the grouped list → **Add N to Canvas**.
+
+Nodes come in as `zigbee_coordinator` / `zigbee_router` / `zigbee_enddevice`. The hierarchy (coordinator → routers → end devices) and **LQI** are filled in automatically. More: [docs/zigbee-import.md](./docs/zigbee-import.md).
+
+---
+
+## 10. Z-Wave Import 🔒
+
+**What:** Same idea for **Z-Wave JS UI**, over the same MQTT broker.
+
+**Use:**
+1. Sidebar → **Z-Wave Import**.
+2. Enter broker host/port, any credentials, the MQTT prefix (default `zwave`), and the gateway name (default `zwavejs2mqtt`).
+3. **Test Connection** → send them to **Pending** or straight to the **Canvas** → import → pick devices → **Add N to Canvas**.
+
+Nodes: `zwave_coordinator` / `zwave_router` / `zwave_enddevice`. The hierarchy comes from each node's neighbor list (Z-Wave has no LQI). More: [docs/zwave-import.md](./docs/zwave-import.md).
+
+---
+
+## 11. Proxmox VE Import 🔒
+
+**What:** Pull your **Proxmox VE** inventory (hosts, VMs, LXC) in over the Proxmox REST API — typed, named nodes with run state and hardware specs. Optional scheduled **auto-sync**; guest IPs already found by a scan are merged, not duplicated.
+
+**Use:**
+1. Create a read-only API token in Proxmox (Datacenter → Permissions → API Tokens, role `PVEAuditor`).
+2. Sidebar → **Proxmox Import**.
+3. Enter host, port (default `8006`), and the token (`user@realm!tokenid` + secret) — or leave blank to use the server token.
+4. **Test Connection** → send to **Pending** or the **Canvas** → import → pick devices → **Add N to Canvas**.
+
+Nodes: `proxmox` (host) / `vm` / `lxc`, linked host→guest by a `virtual` edge. The token is env-only, never stored on disk, never returned by the API. Enable auto-sync from **Settings** once `PROXMOX_TOKEN_ID` / `PROXMOX_TOKEN_SECRET` are set. More: [docs/proxmox-import.md](./docs/proxmox-import.md).
+
+---
+
+## 12. Device Inventory 🔒
+
+**What:** The holding pen for everything found by a scan or import that isn't on the canvas yet, plus a separate **Hidden Devices** list.
+
+**Use:**
+- Sidebar → **Device Inventory**. Each entry shows IP, MAC, hostname, and any OS and services detected.
+- Per device: **Approve** to drop a typed node on the canvas, **Hide** to stash it (you can get it back), or **Ignore** to dismiss it.
+- **Hidden Devices** is the sidebar entry where you review and restore anything you've hidden.
+
+---
+
+## 13. Live Status Monitoring 🔒
+
+**What:** Keeps checking each node and shows its status (🟢 online / 🔴 offline / ⚫ unknown) right on the canvas.
+
+**Use:**
+- Pick a **check method** per node when you add or edit it:
+
+  | Method | Checks |
+  |--------|--------|
+  | `ping` | ICMP reachability |
+  | `http` | GET, OK if status < 500 |
+  | `https` | GET with TLS verify |
+  | `tcp` | TCP connect to `host:port` |
+  | `ssh` | TCP connect to port 22 |
+  | `prometheus` | GET `/metrics` |
+  | `health` | GET `/health` |
+
+- Checks run on a timer (`STATUS_CHECKER_INTERVAL`, 60s by default) and stream to the UI over WebSocket, no refresh. The sidebar footer keeps a running online/offline tally.
+
+---
+
+## 14. Export
+
+**What:** Get your canvas out as a picture or as structured data.
+
+**Use (toolbar):**
+- **PNG**, a snapshot of the canvas, quality of your choice. Works in standalone too.
+- **SVG**, vector export, keeps fonts, icons, and colors crisp. Same dialog as PNG.
+- **Export (YAML)**, the whole canvas (nodes + links) as YAML you can re-import.
+- **Markdown**, copies your device inventory as a Markdown table, handy for docs or a README.
+
+---
+
+## 15. Live View 🔒
+
+**What:** A read-only, no-login snapshot of a canvas you can share on your LAN. Off by default.
+
+**Use:**
+1. Add `LIVEVIEW_KEY=your-secret-key` to `.env`, then `docker compose restart backend`.
+2. Open `http://<your-homelab-ip>/view?key=your-secret-key`.
+
+Pan and zoom only, no editing. Click a node with an IP and it opens in a new tab.
+
+---
+
+## 16. Gethomepage Widget 🔒
+
+**What:** A tiny JSON stats endpoint for [gethomepage](https://gethomepage.dev)'s `customapi` widget. Off by default.
+
+**Use:**
+1. Add `HOMEPAGE_API_KEY=your-secret-key` to `.env`, restart the backend.
+2. `GET /api/v1/stats/summary` with header `X-API-Key: your-secret-key` returns node counts, online/offline, pending, zigbee, and last scan time.
+
+Widget snippet lives in the [README](./README.md#gethomepage-widget-read-only-stats).
+
+---
+
+## 17. MCP Server 🔒
+
+**What:** A [Model Context Protocol](https://modelcontextprotocol.io) server so an MCP client (Claude Code, Claude Desktop, Open WebUI…) can read and change your topology. Optional, runs as its own service.
+
+**Use:**
+1. Add the keys to `.env`:
+   ```env
+   MCP_API_KEY=mcp_sk_changeme      # AI client -> MCP server
+   MCP_SERVICE_KEY=svc_changeme     # MCP server -> backend (internal only)
+   # generate: python3 -c "import secrets; print(secrets.token_hex(32))"
+   ```
+2. `docker compose up -d mcp` (listens on `:8001`). No Docker? `sudo bash scripts/lxc-mcp-install.sh`.
+3. Point your client at `http://<your-homelab-ip>:8001/mcp` with header `X-API-Key: <your key>`.
+
+The AI can list nodes/edges/canvas/pending/scans, add/update/delete nodes and edges, kick off scans, and approve or hide devices. Keep port 8001 firewalled to your LAN. Full setup in the [README](./README.md#mcp-server-ai-integration-optional).
+
+---
+
+## 18. Settings & Shortcuts
+
+**What:** App config and keyboard shortcuts.
+
+**Use:**
+- Sidebar → **Settings** for app-level config.
+- **Search** to find nodes fast.
+- Open the **Shortcuts** modal for the full key list (Save `Ctrl/Cmd+S`, undo/redo, and the rest).
+
+---
+
+## 19. Authentication (Local / OpenID Connect) 🔒
+
+**What:** Homelable protects the app behind a login. Two exclusive modes, set once in `.env` with `AUTH_MODE`:
+- **`local`** (default) — a single username + bcrypt-hashed password. Nothing changes for existing installs.
+- **`oidc`** — sign in through your own identity provider (Authentik, Keycloak, Authelia, Google, …) via **Authorization Code + PKCE**. Good for SSO, per-user accounts at the IdP, MFA, and central account management.
+
+**Use (OIDC):**
+1. Register Homelable as a **confidential** client at your IdP and set the redirect URI to `https://<your-host>/api/v1/auth/oidc/callback`.
+2. In `.env` set `AUTH_MODE=oidc` and the `OIDC_*` values (discovery URL, client id/secret, redirect URI, scopes), keep `CORS_ORIGINS` pinned to your browser origin, and give `SECRET_KEY` at least 32 bytes.
+3. Restart the backend. The login screen now shows **Sign in with OpenID Connect**.
+
+**How it protects you:** provider tokens are exchanged server-side and never touch the browser — Homelable issues its own short-lived, `__Host-`, HttpOnly, `SameSite=Lax` session cookie. Discovery metadata, issuer, audience, signature, expiry, nonce, state and PKCE are all validated; cookie-authenticated writes require a CSRF token and an allowed `Origin`; the status WebSocket authenticates from the cookie and validates `Origin`. Local Bearer auth and the MCP service key keep working unchanged. Full config, provider examples and troubleshooting: [docs/oidc-auth.md](./docs/oidc-auth.md).
+
+> OIDC is Full-mode only — the no-backend standalone build has no login.
+
+---
+
+*Installing (Docker, Proxmox LXC, source) is covered in [INSTALLATION.md](./INSTALLATION.md). Running Home Assistant? See [homelable-hacs](https://github.com/Pouzor/homelable-hacs).*

INSTALLATION.md

@@ -13,7 +13,7 @@ Open **http://localhost:3000** — login with `admin` / `admin`.
 >
 Generate a new hash: 
 ```bash 
-docker compose exec backend python -c "from passlib.context import CryptContext; print(CryptContext(schemes=['bcrypt']).hash('yourpassword'))"
+docker compose exec backend python -c 'import bcrypt; print(bcrypt.hashpw(b"yourpassword", bcrypt.gensalt()).decode())'
 ```
 
 
@@ -21,7 +21,7 @@ docker compose exec backend python -c "from passlib.context import CryptContext;
  - **`.env` file** (recommended): wrap the hash in single quotes → `AUTH_PASSWORD_HASH='$2b$12$...'`
  - **`docker-compose.yml` `environment:` block**: escape every `$` as `$$` — use this command to generate a pre-escaped hash:
    ```bash
-   docker compose exec backend python -c "from passlib.context import CryptContext; print(CryptContext(schemes=['bcrypt']).hash('yourpassword').replace('\$', '\$\$'))"
+   docker compose exec backend python -c 'import bcrypt; print(bcrypt.hashpw(b"yourpassword", bcrypt.gensalt()).decode().replace("$", "$$"))'
    ```
 
 ## Quick Start — Frontend only
@@ -69,6 +69,7 @@ bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/Proxmo
 All configuration is done via `.env` (copied from `.env.example`):
 
 ```env
+# Generate with: python3 -c "import secrets; print(secrets.token_hex(32))"
 SECRET_KEY=change_me_in_production
 
 # Auth — default: admin / admin
@@ -82,6 +83,29 @@ SCANNER_RANGES=["192.168.1.0/24"]
 STATUS_CHECKER_INTERVAL=60
 ```
 
+### OpenID Connect (optional)
+
+OIDC is an exclusive alternative to the local password. Existing installs stay
+in `AUTH_MODE=local` unless explicitly changed.
+
+```env
+AUTH_MODE=oidc
+CORS_ORIGINS=["https://homelable.example"]
+OIDC_DISCOVERY_URL=https://idp.example/application/o/homelable/.well-known/openid-configuration
+OIDC_CLIENT_ID=homelable
+OIDC_CLIENT_SECRET=replace-with-a-secret
+OIDC_REDIRECT_URI=https://homelable.example/api/v1/auth/oidc/callback
+OIDC_SCOPES="openid profile email"
+OIDC_COOKIE_SECURE=true
+OIDC_SESSION_EXPIRE_MINUTES=480
+```
+
+Register `OIDC_REDIRECT_URI` exactly at the identity provider. Production OIDC
+requires HTTPS, a non-wildcard `CORS_ORIGINS`, and a confidential client. The
+backend uses Authorization Code with PKCE and keeps provider tokens out of the
+browser. `SECRET_KEY` must contain at least 32 bytes in OIDC mode. Do not expose
+`OIDC_CLIENT_SECRET` in Compose YAML or commit it to Git.
+
 All settings are also editable in-app via the **Scan Network** button.
 
 ---

README.md

@@ -1,4 +1,35 @@
-# Homelable
+<h1 align="center"><img src="docs/logo/icon-inline.svg" alt="Homelable" width="58" align="middle" />&nbsp;Homelable</h1>
+
+<p align="center">
+  <strong>Self-hosted homelab infrastructure visualization, scanning &amp; live monitoring</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Pouzor/homelable/releases/latest"><img src="https://img.shields.io/github/v/release/Pouzor/homelable" alt="Latest release" /></a>
+  <a href="https://github.com/Pouzor/homelable/actions/workflows/docker-ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Pouzor/homelable/docker-ci.yml?branch=main&amp;label=build" alt="Build status" /></a>
+  <a href="https://github.com/Pouzor/homelable/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" /></a>
+  <a href="https://github.com/Pouzor/homelable/issues"><img src="https://img.shields.io/github/issues/Pouzor/homelable" alt="Issues" /></a>
+  <a href="https://github.com/Pouzor/homelable/stargazers"><img src="https://img.shields.io/github/stars/Pouzor/homelable?style=social" alt="Stars" /></a>
+  <a href="https://github.com/Pouzor/homelable/network/members"><img src="https://img.shields.io/github/forks/Pouzor/homelable?style=social" alt="Forks" /></a>
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/24461?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-24461" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/24461/daily?language=TypeScript" alt="Pouzor%2Fhomelable | Trendshift" width="130" /></a>
+</p>
+
+<p align="center">
+  <a href="#screenshots">Screenshots</a> ·
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#rack-canvas">Rack Canvas</a> ·
+  <a href="#network-scanner">Network Scanner</a> ·
+  <a href="#zigbee2mqtt-import">Zigbee / Z-Wave</a> ·
+  <a href="#proxmox-ve-import">Proxmox</a> ·
+  <a href="#live-view-read-only-public-canvas">Live View</a> ·
+  <a href="#mcp-server-ai-integration-optional">MCP Server</a>
+</p>
+
+## About
 
 Homelable is a self-hosted infrastructure visualization solution. It provides a network/zigbee scanning feature to accelerate the identification of machines, devices and services deployed on your local infrastructure.
 
@@ -8,8 +39,7 @@ You can also select some pre-built design styles, or personalize each device in
 
 If you just like the design, you can only run the frontend and export your design as PNG.
 
-If you are running  <img width="35" height="35" align="middle" alt="New_Home_Assistant_logo" src="https://github.com/user-attachments/assets/3bb17686-c706-40ce-a2d3-57e02378f37c" />  Homeassistant, check the [Homelable HA version](https://github.com/Pouzor/homelable-hacs) (via HACS)
-
+If you are running  <img width="22" height="22" align="top" alt="New_Home_Assistant_logo" src="https://github.com/user-attachments/assets/3bb17686-c706-40ce-a2d3-57e02378f37c" />  Homeassistant, check the [Homelable HA version](https://github.com/Pouzor/homelable-hacs) (via HACS)
 
 ---
 
@@ -17,20 +47,46 @@ If you are running  <img width="35" height="35" align="middle" alt="New_Home_Ass
 
 <p align="center">
   <img src="docs/homelable1.png" alt="Homelable canvas overview" width="100%" />
-  <img src="docs/homelable2.png" alt="Homelable node detail" width="100%" />
-  <img src="docs/homelable4.png" alt="Homelable edit pannel" width="48%" />
-  <img width="48%" alt="Homelable Zigbee Network" src="https://github.com/user-attachments/assets/06caab68-6637-4dda-ab16-7e83f63d3972" />
+  <img  alt="Homelable Device inventory" src="https://github.com/user-attachments/assets/f3903ac8-354d-4873-81ba-1914971890ed" />
+  <img width="49.5%" alt="Homelable Custom node" src="https://github.com/user-attachments/assets/813725b1-376b-4bad-bb1f-0985f3bc7546" />
+  <img width="49.5%"  alt="Homelable Zigbee Network" src="https://github.com/user-attachments/assets/35e18d11-8363-498d-ae3d-642685cac76d" />
 
 </p>
 
 ---
 
+## Features
+
+From one-click **network scans** and **Proxmox / Zigbee / Z-Wave** imports to **live status monitoring**, floor plans, **rack canvases** with port-to-port patching, multi-canvas layouts and an **MCP server** for AI assistants — Homelable maps and watches your whole homelab.
+
+Every feature, with how to turn it on and use it, is described in **[FEATURES.md](./FEATURES.md)**.
+
+---
+
 ## Installation
 
 Docker, Proxmox LXC, build from source, configuration, and development setup are all covered in **[INSTALLATION.md](./INSTALLATION.md)**.
 
 ---
 
+## Rack Canvas
+
+Next to the network diagram, Homelable draws the **physical** side of your lab: racks, the gear mounted in them, and the patch cables between their ports. It is a canvas kind of its own — create it from the canvas switcher, **New Canvas → Kind → Rack**.
+
+### Usage
+
+1. **Add Rack** in the header drops a rack; double-click its frame to set U height, 19"/10" width, numbering direction and colours
+2. **+ Device** in the sidebar mounts something — an entry from your Device Inventory, a new device (which joins the inventory), or an accessory (blank, shelf, cable manager)
+3. Pick a **faceplate** from the visual catalog: servers, switches, routers, patch panels, UPS and PDUs, desktop NAS towers, shelves and blanks
+4. Click **Patch**, then drag from one port to another to cable them — across racks if you need to. Click a cable and press Delete to unplug it
+5. **Save Rack** when you're happy; nothing is written behind your back
+
+Gear sits in a U range and part of a 12-column width grid, so half- and third-width machines share a U; a drop snaps to the nearest free slot. A mount can follow the status check of its matching diagram node, and **Import links** derives patches from the links already drawn on your diagrams.
+
+> **Full documentation:** [docs/rack-canvas.md](./docs/rack-canvas.md)
+
+---
+
 ## Network Scanner
 
 The scanner runs `nmap -sV --open` on your configured CIDR ranges and populates a **Pending Devices** queue. From the sidebar you can then approve (adds a node to the canvas), hide, or ignore each discovered device.
@@ -123,6 +179,68 @@ LQI (Link Quality Indicator) is stored as a node property.
 
 ---
 
+## Z-Wave Import
+
+Homelable can also import your **Z-Wave** network from **Z-Wave JS UI** (formerly `zwavejs2mqtt`) over the same MQTT broker, dropping each node on the canvas as a typed node.
+
+### Prerequisites
+
+- A running **MQTT broker** (e.g. Mosquitto) accessible from the Homelable host
+- **Z-Wave JS UI** connected to the broker with its MQTT gateway enabled and at least one node included
+
+### Usage
+
+1. Click **Z-Wave Import** in the left sidebar (below "Zigbee Import")
+2. Enter your broker host, port (default `1883`), optional credentials, MQTT prefix (default `zwave`), and gateway name (default `zwavejs2mqtt`)
+3. Click **Test Connection** to verify reachability
+4. Choose a target — **Pending section** or **Canvas directly** — then **Import to Pending** / **Fetch Devices**
+5. Select the devices you want from the grouped list (Controller / Router / End Device) and click **Add N to Canvas**
+
+### Node Types
+
+| Type | Z-Wave Role | Icon |
+|------|-------------|------|
+| `zwave_coordinator` | Controller | Network hub |
+| `zwave_router` | Routing (mains-powered) node | Radio |
+| `zwave_enddevice` | End Device (battery) | Antenna |
+
+Hierarchy is set automatically: controller → routers → end devices (`parent_id`), derived from each node's neighbor list. Z-Wave has no LQI, so that property is omitted.
+
+> **Full documentation:** [docs/zwave-import.md](./docs/zwave-import.md)
+
+---
+
+## Proxmox VE Import
+
+Homelable can import your **Proxmox VE** inventory over the Proxmox REST API — hosts, VMs and LXC containers arrive as typed, named nodes with run state and hardware specs, and can auto-sync on a schedule. Guest IPs that were already found by a network scan are merged in place (no duplicates).
+
+### Prerequisites
+
+- A reachable **Proxmox VE** host (default API port `8006`)
+- A **Proxmox API token** with the read-only **`PVEAuditor`** role (Datacenter → Permissions → API Tokens)
+
+### Usage
+
+1. Click **Proxmox Import** in the left sidebar (below "Z-Wave Import")
+2. Enter the host, port (default `8006`), and API token (`user@realm!tokenid` + secret) — or leave the token blank to use the server-configured one
+3. Click **Test Connection** to verify reachability + token
+4. Choose a target — **Pending section** or **Canvas directly** — then **Import to Pending** / **Fetch Inventory**
+5. Select the devices from the grouped list (Hosts / Virtual Machines / LXC Containers) and click **Add N to Canvas**
+
+### Node Types
+
+| Type | Proxmox object | Icon |
+|------|----------------|------|
+| `proxmox` | Host / cluster member | Layers |
+| `vm` | QEMU virtual machine | Box |
+| `lxc` | LXC container | Container |
+
+Each host is linked to its guests with a `virtual` edge. vCPU / RAM / disk are imported as node properties (hidden by default). Enable **auto-sync** from Settings once a server token is configured (`PROXMOX_TOKEN_ID` / `PROXMOX_TOKEN_SECRET`).
+
+> **Full documentation:** [docs/proxmox-import.md](./docs/proxmox-import.md)
+
+---
+
 ## Live View (read-only public canvas)
 
 Live View lets you share a read-only snapshot of your canvas with anyone on your network — no login required. It is disabled by default.
@@ -247,7 +365,7 @@ docker compose up -d mcp
 
 **Claude Code** — run this command in your terminal:
 ```bash
-claude mcp add --transport sse homelable http://<your-homelab-ip>:8001/mcp \
+claude mcp add --transport http homelable http://<your-homelab-ip>:8001/mcp/ \
   --header "X-API-Key: mcp_sk_yourkey"
 ```
 
@@ -256,8 +374,8 @@ Or add it manually to `~/.claude.json`:
 {
   "mcpServers": {
     "homelable": {
-      "type": "sse",
-      "url": "http://<your-homelab-ip>:8001/mcp",
+      "type": "http",
+      "url": "http://<your-homelab-ip>:8001/mcp/",
       "headers": {
         "X-API-Key": "mcp_sk_yourkey"
       }
@@ -271,8 +389,8 @@ Or add it manually to `~/.claude.json`:
 {
   "mcpServers": {
     "homelable": {
-      "type": "sse",
-      "url": "http://<your-homelab-ip>:8001/mcp",
+      "type": "http",
+      "url": "http://<your-homelab-ip>:8001/mcp/",
       "headers": {
         "X-API-Key": "mcp_sk_yourkey"
       }

VERSION

@@ -1 +1 @@
-2.6.0
+3.2.0

backend/app/api/deps.py

@@ -1,31 +1,66 @@
 import hmac
+from dataclasses import dataclass
 
 from fastapi import Depends, Header, HTTPException, Request, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 
 from app.core.config import settings
-from app.core.security import decode_token
+from app.core.security import decode_token, get_oidc_session
 
 bearer = HTTPBearer(auto_error=False)
 
 
-def get_current_user(
+@dataclass(frozen=True)
+class AuthContext:
+    subject: str
+    display_name: str
+    auth_method: str
+    issuer: str | None = None
+    csrf_token: str | None = None
+
+
+def get_auth_context(
     request: Request,
     credentials: HTTPAuthorizationCredentials | None = Depends(bearer),
     x_mcp_service_key: str | None = Header(default=None),
-) -> str:
+) -> AuthContext:
     # 1. MCP service key (Docker-internal only — backend port is not externally exposed)
     if x_mcp_service_key is not None:
         if not settings.mcp_service_key:
             raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="MCP service key not configured")
         if not hmac.compare_digest(x_mcp_service_key.encode(), settings.mcp_service_key.encode()):
             raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid MCP service key")
-        return "__mcp_service__"
+        return AuthContext(
+            subject="__mcp_service__",
+            display_name="MCP service",
+            auth_method="mcp",
+        )
 
     # 2. Standard JWT bearer token
-    if credentials is None:
-        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Not authenticated")
-    username = decode_token(credentials.credentials)
-    if not username:
-        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")
-    return username
+    if credentials is not None:
+        username = decode_token(credentials.credentials)
+        if not username:
+            raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")
+        return AuthContext(
+            subject=username,
+            display_name=username,
+            auth_method="local",
+        )
+
+    # 3. OIDC session cookie (only active in exclusive OIDC mode)
+    if settings.auth_mode == "oidc":
+        oidc_session = get_oidc_session(request)
+        if oidc_session is not None:
+            return AuthContext(
+                subject=oidc_session.subject,
+                display_name=oidc_session.display_name,
+                auth_method="oidc",
+                issuer=oidc_session.issuer,
+                csrf_token=oidc_session.csrf_token,
+            )
+
+    raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Not authenticated")
+
+
+def get_current_user(context: AuthContext = Depends(get_auth_context)) -> str:
+    return context.subject

backend/app/api/routes/auth.py

@@ -1,12 +1,27 @@
 import hmac
+import logging
+from collections.abc import Mapping
+from typing import cast
 
-from fastapi import APIRouter, HTTPException, status
+from authlib.integrations.base_client.errors import OAuthError
+from authlib.jose.errors import JoseError
+from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
 from pydantic import BaseModel
+from starlette.responses import RedirectResponse
 
+from app.api.deps import AuthContext, get_auth_context
 from app.core.config import settings
-from app.core.security import create_access_token, verify_password
+from app.core.security import (
+    clear_oidc_session_cookie,
+    create_access_token,
+    create_oidc_session_token,
+    get_oidc_client,
+    set_oidc_session_cookie,
+    verify_password,
+)
 
 router = APIRouter()
+logger = logging.getLogger(__name__)
 
 
 class LoginRequest(BaseModel):
@@ -19,8 +34,36 @@ class TokenResponse(BaseModel):
     token_type: str = "bearer"
 
 
+class AuthConfigResponse(BaseModel):
+    mode: str
+    oidc_login_url: str | None = None
+
+
+class CurrentUserResponse(BaseModel):
+    subject: str
+    display_name: str
+    auth_method: str
+    issuer: str | None = None
+    csrf_token: str | None = None
+
+
+def _require_oidc_mode() -> None:
+    if settings.auth_mode != "oidc":
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="OIDC login is disabled")
+
+
+@router.get("/config", response_model=AuthConfigResponse)
+async def auth_config() -> AuthConfigResponse:
+    return AuthConfigResponse(
+        mode=settings.auth_mode,
+        oidc_login_url="/api/v1/auth/oidc/login" if settings.auth_mode == "oidc" else None,
+    )
+
+
 @router.post("/login", response_model=TokenResponse)
 async def login(body: LoginRequest) -> TokenResponse:
+    if settings.auth_mode != "local":
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Local login is disabled")
     # Always run both checks to prevent timing-based username enumeration.
     # hmac.compare_digest is constant-time; verify_password (bcrypt) always runs.
     username_ok = hmac.compare_digest(body.username, settings.auth_username)
@@ -29,3 +72,55 @@ async def login(body: LoginRequest) -> TokenResponse:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid credentials")
     token = create_access_token(body.username)
     return TokenResponse(access_token=token)
+
+
+@router.get("/oidc/login")
+async def oidc_login(request: Request) -> Response:
+    _require_oidc_mode()
+    client = get_oidc_client()
+    return cast(Response, await client.authorize_redirect(request, settings.oidc_redirect_uri))
+
+
+@router.get("/oidc/callback")
+async def oidc_callback(request: Request) -> Response:
+    _require_oidc_mode()
+    client = get_oidc_client()
+    try:
+        token = await client.authorize_access_token(request)
+    except (OAuthError, JoseError) as exc:
+        logger.warning("OIDC callback rejected: %s", exc.error)
+        request.session.clear()
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="OIDC authentication failed") from None
+
+    userinfo = token.get("userinfo")
+    if not isinstance(userinfo, Mapping):
+        request.session.clear()
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="OIDC authentication failed")
+    try:
+        session_token = create_oidc_session_token(userinfo)
+    except ValueError:
+        request.session.clear()
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="OIDC authentication failed") from None
+
+    request.session.clear()
+    response = RedirectResponse(url="/", status_code=status.HTTP_303_SEE_OTHER)
+    set_oidc_session_cookie(response, session_token)
+    return response
+
+
+@router.get("/me", response_model=CurrentUserResponse)
+async def current_user(context: AuthContext = Depends(get_auth_context)) -> CurrentUserResponse:
+    return CurrentUserResponse(
+        subject=context.subject,
+        display_name=context.display_name,
+        auth_method=context.auth_method,
+        issuer=context.issuer,
+        csrf_token=context.csrf_token,
+    )
+
+
+@router.post("/logout", status_code=status.HTTP_204_NO_CONTENT)
+async def logout(_: AuthContext = Depends(get_auth_context)) -> Response:
+    response = Response(status_code=status.HTTP_204_NO_CONTENT)
+    clear_oidc_session_cookie(response)
+    return response

backend/app/api/routes/canvas.py

@@ -37,6 +37,9 @@ async def load_canvas(
         edges=[EdgeResponse.model_validate(e) for e in edges],
         viewport=viewport,
         custom_style=state.custom_style if state else None,
+        # A CanvasState row exists only after a save (or explicit design create),
+        # so its presence marks an intentional canvas vs. a never-touched one.
+        initialized=state is not None,
     )
 
 

backend/app/api/routes/designs.py

@@ -1,14 +1,21 @@
+import uuid
+
 from fastapi import APIRouter, Depends, HTTPException
-from sqlalchemy import select
+from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.deps import get_current_user
 from app.db.database import get_db
-from app.db.models import CanvasState, Design, Edge, Node
-from app.schemas.designs import DesignCreate, DesignResponse, DesignUpdate
+from app.db.models import CanvasState, Design, Edge, Node, Rack, RackCable, RackDevice
+from app.schemas.designs import DesignCopy, DesignCreate, DesignResponse, DesignUpdate
 
 router = APIRouter()
 
+# Node.type values that are canvas annotations rather than real devices. Kept in
+# sync with the frontend (Sidebar counts, canvasSerializer types).
+_GROUP_TYPE = "groupRect"
+_TEXT_TYPE = "text"
+
 
 @router.get("", response_model=list[DesignResponse])
 async def list_designs(
@@ -16,7 +23,31 @@ async def list_designs(
     _: str = Depends(get_current_user),
 ) -> list[DesignResponse]:
     designs = (await db.execute(select(Design).order_by(Design.created_at))).scalars().all()
-    return [DesignResponse.model_validate(d) for d in designs]
+    # One grouped query for all designs → node/group/text counts per design.
+    rows = (
+        await db.execute(select(Node.design_id, Node.type, func.count()).group_by(Node.design_id, Node.type))
+    ).all()
+    counts: dict[str, dict[str, int]] = {}
+    for design_id, node_type, count in rows:
+        if design_id is None:
+            continue
+        bucket = counts.setdefault(design_id, {"node": 0, "group": 0, "text": 0})
+        if node_type == _GROUP_TYPE:
+            bucket["group"] += count
+        elif node_type == _TEXT_TYPE:
+            bucket["text"] += count
+        else:
+            bucket["node"] += count
+
+    result = []
+    for d in designs:
+        resp = DesignResponse.model_validate(d)
+        c = counts.get(d.id, {"node": 0, "group": 0, "text": 0})
+        resp.node_count = c["node"]
+        resp.group_count = c["group"]
+        resp.text_count = c["text"]
+        result.append(resp)
+    return result
 
 
 @router.post("", response_model=DesignResponse, status_code=201)
@@ -35,6 +66,123 @@ async def create_design(
     return DesignResponse.model_validate(design)
 
 
+@router.post("/{source_id}/copy", response_model=DesignResponse, status_code=201)
+async def copy_design(
+    source_id: str,
+    body: DesignCopy,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> DesignResponse:
+    """Create a new design that deep-copies the source's nodes, edges and canvas state."""
+    source = await db.get(Design, source_id)
+    if not source:
+        raise HTTPException(404, "Source design not found")
+
+    new_design = Design(name=body.name, icon=body.icon, design_type=source.design_type)
+    db.add(new_design)
+    await db.flush()
+
+    src_nodes = (await db.execute(select(Node).where(Node.design_id == source_id))).scalars().all()
+    src_edges = (await db.execute(select(Edge).where(Edge.design_id == source_id))).scalars().all()
+
+    # New id per source node so edges and parent links can be re-pointed at the copy.
+    id_map = {n.id: str(uuid.uuid4()) for n in src_nodes}
+
+    # Columns we set explicitly or let the DB default — never copy verbatim.
+    node_skip = {"id", "design_id", "parent_id", "created_at", "updated_at"}
+    for n in src_nodes:
+        cols = {c.name: getattr(n, c.name) for c in Node.__table__.columns if c.name not in node_skip}
+        db.add(Node(id=id_map[n.id], design_id=new_design.id, parent_id=None, **cols))
+    await db.flush()  # nodes must exist before we wire self-referential parent_id
+
+    # Second pass: re-point parent links inside the copy.
+    for n in src_nodes:
+        if n.parent_id and n.parent_id in id_map:
+            child = await db.get(Node, id_map[n.id])
+            if child:
+                child.parent_id = id_map[n.parent_id]
+
+    edge_skip = {"id", "design_id", "source", "target", "created_at"}
+    for e in src_edges:
+        # Skip edges whose endpoints aren't part of this design (dangling FKs).
+        if e.source not in id_map or e.target not in id_map:
+            continue
+        cols = {c.name: getattr(e, c.name) for c in Edge.__table__.columns if c.name not in edge_skip}
+        db.add(
+            Edge(
+                id=str(uuid.uuid4()),
+                design_id=new_design.id,
+                source=id_map[e.source],
+                target=id_map[e.target],
+                **cols,
+            )
+        )
+
+    # Copy the rack canvas, if the source has one. Racks, mounted gear and patches
+    # all get new ids; the inventory / node links are carried over untouched, since
+    # a copy documents the same hardware.
+    src_racks = (await db.execute(select(Rack).where(Rack.design_id == source_id))).scalars().all()
+    rack_id_map = {r.id: str(uuid.uuid4()) for r in src_racks}
+    rack_skip = {"id", "design_id", "created_at", "updated_at"}
+    for r in src_racks:
+        cols = {c.name: getattr(r, c.name) for c in Rack.__table__.columns if c.name not in rack_skip}
+        db.add(Rack(id=rack_id_map[r.id], design_id=new_design.id, **cols))
+
+    src_rack_devices = (
+        await db.execute(select(RackDevice).where(RackDevice.design_id == source_id))
+    ).scalars().all()
+    rack_device_id_map = {d.id: str(uuid.uuid4()) for d in src_rack_devices}
+    rack_device_skip = {"id", "design_id", "rack_id", "created_at", "updated_at"}
+    for d in src_rack_devices:
+        if d.rack_id not in rack_id_map:
+            continue
+        cols = {
+            c.name: getattr(d, c.name)
+            for c in RackDevice.__table__.columns
+            if c.name not in rack_device_skip
+        }
+        db.add(
+            RackDevice(
+                id=rack_device_id_map[d.id],
+                design_id=new_design.id,
+                rack_id=rack_id_map[d.rack_id],
+                **cols,
+            )
+        )
+
+    src_cables = (await db.execute(select(RackCable).where(RackCable.design_id == source_id))).scalars().all()
+    cable_skip = {"id", "design_id", "from_device_id", "to_device_id", "created_at"}
+    for c_row in src_cables:
+        if c_row.from_device_id not in rack_device_id_map or c_row.to_device_id not in rack_device_id_map:
+            continue
+        cols = {
+            c.name: getattr(c_row, c.name) for c in RackCable.__table__.columns if c.name not in cable_skip
+        }
+        db.add(
+            RackCable(
+                id=str(uuid.uuid4()),
+                design_id=new_design.id,
+                from_device_id=rack_device_id_map[c_row.from_device_id],
+                to_device_id=rack_device_id_map[c_row.to_device_id],
+                **cols,
+            )
+        )
+
+    # Copy canvas state (viewport, custom style, and the floor plan carried in viewport).
+    src_state = await db.get(CanvasState, source_id)
+    db.add(
+        CanvasState(
+            design_id=new_design.id,
+            viewport=src_state.viewport if src_state else {},
+            custom_style=src_state.custom_style if src_state else None,
+        )
+    )
+
+    await db.commit()
+    await db.refresh(new_design)
+    return DesignResponse.model_validate(new_design)
+
+
 @router.put("/{design_id}", response_model=DesignResponse)
 async def update_design(
     design_id: str,
@@ -67,10 +215,20 @@ async def delete_design(
     count = (await db.execute(select(Design))).scalars().all()
     if len(count) <= 1:
         raise HTTPException(400, "Cannot delete the only design")
-    # Delete associated canvas state, edges, nodes
+    # Delete associated canvas state, rack rows, edges, nodes. SQLite does not
+    # always enforce the ON DELETE CASCADE, so unwind by hand — cables before
+    # devices before racks.
     cs = await db.get(CanvasState, design_id)
     if cs:
         await db.delete(cs)
+    for cable in (await db.execute(select(RackCable).where(RackCable.design_id == design_id))).scalars().all():
+        await db.delete(cable)
+    for rack_device in (
+        await db.execute(select(RackDevice).where(RackDevice.design_id == design_id))
+    ).scalars().all():
+        await db.delete(rack_device)
+    for rack in (await db.execute(select(Rack).where(Rack.design_id == design_id))).scalars().all():
+        await db.delete(rack)
     edges = (await db.execute(select(Edge).where(Edge.design_id == design_id))).scalars().all()
     for e in edges:
         await db.delete(e)

backend/app/api/routes/edges.py

@@ -4,11 +4,56 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.deps import get_current_user
 from app.db.database import get_db
-from app.db.models import Design, Edge
+from app.db.models import Design, Edge, Node
 from app.schemas.edges import EdgeCreate, EdgeResponse, EdgeUpdate
 
 router = APIRouter()
 
+# ---------------------------------------------------------------------------
+# Auto-handle helpers
+# ---------------------------------------------------------------------------
+
+
+async def _abs_y(db: AsyncSession, node_id: str) -> float | None:
+    """Resolve the approximate absolute canvas Y of a node.
+
+    Walks up the parent chain (up to 8 levels) and accumulates pos_y offsets so
+    that children inside containers are compared correctly against top-level nodes.
+    Returns None when the node is not found.
+    """
+    node = await db.get(Node, node_id)
+    if node is None:
+        return None
+    y = node.pos_y
+    current = node
+    for _ in range(8):
+        if current.parent_id is None:
+            break
+        parent = await db.get(Node, current.parent_id)
+        if parent is None:
+            break
+        y += parent.pos_y
+        current = parent
+    return y
+
+
+async def _auto_handles(
+    db: AsyncSession, source_id: str, target_id: str
+) -> tuple[str, str]:
+    """Return (source_handle, target_handle) that reflect the upstream/downstream
+    relationship between two nodes.
+
+    - Source above target (lower Y value) → downstream flow: exit bottom, enter top
+    - Source below target → upstream flow: exit top, enter bottom
+    - Equal or unknown → default to bottom/top-t (most common topology direction)
+    """
+    src_y = await _abs_y(db, source_id)
+    tgt_y = await _abs_y(db, target_id)
+
+    if src_y is None or tgt_y is None or src_y <= tgt_y:
+        return "bottom", "top-t"
+    return "top", "bottom-t"
+
 
 @router.get("", response_model=list[EdgeResponse])
 async def list_edges(db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> list[Edge]:
@@ -25,6 +70,18 @@ async def create_edge(body: EdgeCreate, db: AsyncSession = Depends(get_db), _: s
     if data.get("design_id") is None:
         first_design = (await db.execute(select(Design).order_by(Design.created_at).limit(1))).scalar()
         data["design_id"] = first_design.id if first_design else None
+
+    # Auto-assign source/target handles when the caller omits them.
+    # Compares the canvas Y positions of both nodes so that the edge always exits
+    # the upstream node's bottom and enters the downstream node's top (or vice versa
+    # for reverse flows), matching the UI convention for top-to-bottom topologies.
+    if data.get("source_handle") is None or data.get("target_handle") is None:
+        auto_src, auto_tgt = await _auto_handles(db, data["source"], data["target"])
+        if data.get("source_handle") is None:
+            data["source_handle"] = auto_src
+        if data.get("target_handle") is None:
+            data["target_handle"] = auto_tgt
+
     edge = Edge(**data)
     db.add(edge)
     await db.commit()

backend/app/api/routes/media.py

@@ -0,0 +1,100 @@
+"""Generic media upload/serve endpoint.
+
+Images are stored on disk (see `Settings.media_dir`) with server-generated
+UUID filenames — never in the DB, and the client filename is never trusted.
+Upload/delete require auth; GET is public so plain <img> tags and the read-only
+live view can load images (filenames are unguessable).
+
+Currently used by the floor-plan feature; kept deliberately generic so future
+raw-image uploads reuse the same endpoint.
+"""
+
+import re
+import uuid
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException, UploadFile, status
+from fastapi.responses import FileResponse
+
+from app.api.deps import get_current_user
+from app.core.config import settings
+
+router = APIRouter()
+
+# content-type → extension. Also the allowlist of accepted uploads.
+ALLOWED_TYPES: dict[str, str] = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/webp": ".webp",
+}
+
+# Magic-byte signatures for defense-in-depth (don't trust content-type alone).
+_MAGIC: dict[str, tuple[bytes, ...]] = {
+    ".png": (b"\x89PNG\r\n\x1a\n",),
+    ".jpg": (b"\xff\xd8\xff",),
+    ".webp": (b"RIFF",),  # RIFF....WEBP; RIFF prefix is enough to reject non-images
+}
+
+MAX_BYTES = 10 * 1024 * 1024  # 10 MB
+
+# Only ever serve/delete files we created: 32 hex chars + known extension.
+_NAME_RE = re.compile(r"[0-9a-f]{32}\.(png|jpg|webp)")
+
+
+def _resolve_media_path(filename: str) -> Path:
+    """Return the existing media file named `filename`, or raise 404.
+
+    `filename` is validated against `_NAME_RE` (no separators, no `..`), then
+    matched by name against the actual directory listing. The user string is
+    only ever compared with `==` against trusted `iterdir()` entries — it never
+    builds a path — so a crafted value cannot escape the media dir.
+    """
+    if not _NAME_RE.fullmatch(filename):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Not found")
+    base = settings.media_dir()
+    if base.is_dir():
+        for entry in base.iterdir():
+            if entry.name == filename and entry.is_file():
+                return entry
+    raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Not found")
+
+
+@router.post("/upload")
+async def upload_media(file: UploadFile, _user: str = Depends(get_current_user)) -> dict[str, str]:
+    ext = ALLOWED_TYPES.get(file.content_type or "")
+    if ext is None:
+        raise HTTPException(
+            status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
+            detail="Unsupported media type — PNG, JPEG, or WebP only",
+        )
+    # Read one byte past the cap so we can detect oversize without loading more.
+    data = await file.read(MAX_BYTES + 1)
+    if len(data) > MAX_BYTES:
+        raise HTTPException(
+            status_code=status.HTTP_413_CONTENT_TOO_LARGE,
+            detail="File too large (max 10 MB)",
+        )
+    if not data:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Empty file")
+    if not any(data.startswith(sig) for sig in _MAGIC[ext]):
+        raise HTTPException(
+            status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
+            detail="File content does not match its type",
+        )
+
+    media_dir = settings.media_dir()
+    media_dir.mkdir(parents=True, exist_ok=True)
+    name = f"{uuid.uuid4().hex}{ext}"
+    (media_dir / name).write_bytes(data)
+    return {"filename": name, "url": f"/api/v1/media/{name}"}
+
+
+@router.get("/{filename}")
+async def get_media(filename: str) -> FileResponse:
+    # _resolve_media_path returns only an existing file, else raises 404.
+    return FileResponse(_resolve_media_path(filename))
+
+
+@router.delete("/{filename}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_media(filename: str, _user: str = Depends(get_current_user)) -> None:
+    _resolve_media_path(filename).unlink()

backend/app/api/routes/nodes.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, Query, status
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -6,19 +6,71 @@ from app.api.deps import get_current_user
 from app.db.database import get_db
 from app.db.models import Design, Node
 from app.schemas.nodes import NodeCreate, NodeResponse, NodeUpdate
+from app.services.node_dedupe import find_duplicate_node
 
 router = APIRouter()
 
+# ---------------------------------------------------------------------------
+# Auto-positioning helpers
+# ---------------------------------------------------------------------------
+
+# Canvas grid used when placing nodes without explicit coordinates.
+# Each slot is wide/tall enough that a normal node card fits without overlap.
+_SLOT_W = 200.0
+_SLOT_H = 100.0
+_MAX_COLS = 7
+
+
+async def _find_free_position(db: AsyncSession, design_id: str | None) -> tuple[float, float]:
+    """Return (x, y) for a new root-level node that doesn't collide with existing ones.
+
+    Snaps existing root nodes to a virtual grid and returns the first unoccupied
+    cell, scanning left-to-right then top-to-bottom.
+    """
+    result = await db.execute(
+        select(Node.pos_x, Node.pos_y).where(
+            Node.design_id == design_id,
+            Node.parent_id.is_(None),
+        )
+    )
+    positions = list(result.all())
+    if not positions:
+        return 0.0, 0.0
+
+    # Snap each existing node to its true grid cell (negatives kept as-is). The
+    # search below only visits col >= 0 / row >= 0, so nodes parked in negative
+    # space never falsely block — or falsely free — a positive slot.
+    occupied: set[tuple[int, int]] = set()
+    for (px, py) in positions:
+        col = round(px / _SLOT_W)
+        row = round(py / _SLOT_H)
+        occupied.add((col, row))
+
+    for row in range(10_000):
+        for col in range(_MAX_COLS):
+            if (col, row) not in occupied:
+                return col * _SLOT_W, row * _SLOT_H
+
+    return 0.0, 0.0  # unreachable in practice
+
 
 @router.get("", response_model=list[NodeResponse])
-async def list_nodes(db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> list[Node]:
-    result = await db.execute(select(Node))
-    return list(result.scalars().all())
+async def list_nodes(
+    label: str | None = Query(None, description="Case-insensitive substring filter on node label"),
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> list[Node]:
+    query = select(Node)
+    if label:
+        query = query.where(Node.label.ilike(f"%{label}%"))
+    return list((await db.execute(query)).scalars().all())
 
 
 @router.post("", response_model=NodeResponse, status_code=status.HTTP_201_CREATED)
 async def create_node(body: NodeCreate, db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> Node:
     data = body.model_dump()
+    # `force` bypasses the duplicate guard below; it is not a Node column.
+    force = data.pop("force", False)
     # Attach to a design so the node lands on a canvas. Clients that don't send a
     # design_id (e.g. the MCP write tools) would otherwise create design_id=null
     # nodes that exist in the DB but never render in the UI until a container
@@ -26,6 +78,31 @@ async def create_node(body: NodeCreate, db: AsyncSession = Depends(get_db), _: s
     if data.get("design_id") is None:
         first_design = (await db.execute(select(Design).order_by(Design.created_at).limit(1))).scalar()
         data["design_id"] = first_design.id if first_design else None
+
+    # Reject a silent duplicate: a node with the same ip OR mac already on the
+    # target design. Scripts/MCP clients get a clear 409 (with the existing id)
+    # instead of a second card for the same host. Pass force=True to override.
+    if not force:
+        dup = await find_duplicate_node(db, data["design_id"], data.get("ip"), data.get("mac"))
+        if dup is not None:
+            raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=dup)
+
+    # Auto-position: when pos_x / pos_y are omitted (None), find a free canvas
+    # slot so the new node doesn't land on top of an existing one.
+    # Child nodes (parent_id set) use (0, 0) relative to their parent instead.
+    if data["pos_x"] is None or data["pos_y"] is None:
+        if data.get("parent_id") is None:
+            auto_x, auto_y = await _find_free_position(db, data["design_id"])
+            if data["pos_x"] is None:
+                data["pos_x"] = auto_x
+            if data["pos_y"] is None:
+                data["pos_y"] = auto_y
+        else:
+            if data["pos_x"] is None:
+                data["pos_x"] = 0.0
+            if data["pos_y"] is None:
+                data["pos_y"] = 0.0
+
     node = Node(**data)
     db.add(node)
     await db.commit()

backend/app/api/routes/proxmox.py

@@ -0,0 +1,512 @@
+"""FastAPI router for Proxmox VE import + auto-sync config.
+
+Fetches hosts/VMs/LXC from the Proxmox REST API and upserts them into the
+pending inventory (same review→approve flow as scans and mesh imports).
+
+Credentials: the API token comes from the request body when provided, else
+falls back to the server-configured env token (``settings.proxmox_token_*``).
+The token is never persisted by the app and never returned by any endpoint.
+"""
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
+from sqlalchemy import delete as sa_delete
+from sqlalchemy import or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_current_user
+from app.core.config import settings
+from app.core.scheduler import reschedule_proxmox_sync, set_proxmox_sync_enabled
+from app.db.database import AsyncSessionLocal, get_db
+from app.db.models import InventoryDevice, InventoryDeviceLink, Node, ScanRun
+from app.schemas.proxmox import (
+    ProxmoxConfig,
+    ProxmoxConnectionRequest,
+    ProxmoxEdgeOut,
+    ProxmoxImportPendingResponse,
+    ProxmoxImportResponse,
+    ProxmoxNodeOut,
+    ProxmoxSyncConfig,
+    ProxmoxTestConnectionResponse,
+)
+from app.schemas.scan import ScanRunResponse
+from app.services.discovery_sources import add_source
+from app.services.mac_utils import normalize_mac
+from app.services.node_dedupe import dedupe_nodes_by_ieee
+from app.services.proxmox_service import (
+    build_proxmox_cluster_links,
+    build_proxmox_properties,
+    fetch_proxmox_inventory,
+    merge_proxmox_properties,
+    test_proxmox_connection,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+# Discovery sources for the two proxmox link shapes. Host→guest links render as
+# 'virtual' edges; host↔host cluster links render as 'cluster' edges.
+_PROXMOX_GUEST_SOURCE = "proxmox"
+_PROXMOX_CLUSTER_SOURCE = "proxmox_cluster"
+
+
+def _resolve_credentials(payload: ProxmoxConnectionRequest) -> tuple[str, str]:
+    """Pick the API token: request body first, else server env config.
+
+    Raises HTTP 400 when neither carries a token.
+    """
+    token_id = payload.token_id or settings.proxmox_token_id
+    token_secret = payload.token_secret or settings.proxmox_token_secret
+    if not token_id or not token_secret:
+        raise HTTPException(
+            status_code=400,
+            detail="No Proxmox API token provided and none configured on the server.",
+        )
+    return token_id, token_secret
+
+
+@router.post("/test-connection", response_model=ProxmoxTestConnectionResponse)
+async def test_connection_endpoint(
+    payload: ProxmoxConnectionRequest,
+    _: str = Depends(get_current_user),
+) -> ProxmoxTestConnectionResponse:
+    """Validate host reachability + token before importing."""
+    token_id, token_secret = _resolve_credentials(payload)
+    connected, message = await test_proxmox_connection(
+        host=payload.host,
+        port=payload.port,
+        token_id=token_id,
+        token_secret=token_secret,
+        verify_tls=payload.verify_tls,
+    )
+    return ProxmoxTestConnectionResponse(connected=connected, message=message)
+
+
+@router.post("/import", response_model=ProxmoxImportResponse)
+async def import_proxmox(
+    payload: ProxmoxConnectionRequest,
+    _: str = Depends(get_current_user),
+) -> ProxmoxImportResponse:
+    """Fetch the inventory and return nodes + edges ready for canvas drop."""
+    token_id, token_secret = _resolve_credentials(payload)
+    try:
+        nodes_raw, edges_raw = await fetch_proxmox_inventory(
+            host=payload.host,
+            port=payload.port,
+            token_id=token_id,
+            token_secret=token_secret,
+            verify_tls=payload.verify_tls,
+        )
+    except ConnectionError as exc:
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    except Exception as exc:
+        logger.exception("Unexpected error during Proxmox import")
+        raise HTTPException(status_code=500, detail="Unexpected error during Proxmox import") from exc
+
+    nodes = [ProxmoxNodeOut(**n) for n in nodes_raw]
+    edges = [ProxmoxEdgeOut(**e) for e in edges_raw]
+    return ProxmoxImportResponse(nodes=nodes, edges=edges, device_count=len(nodes))
+
+
+@router.post("/import-pending", response_model=ScanRunResponse)
+async def import_proxmox_to_pending(
+    payload: ProxmoxConnectionRequest,
+    background_tasks: BackgroundTasks,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> ScanRun:
+    """Queue a Proxmox pending import as a background scan run (kind=proxmox)."""
+    token_id, token_secret = _resolve_credentials(payload)
+    run = ScanRun(
+        status="running",
+        kind="proxmox",
+        ranges=[f"{payload.host}:{payload.port}"],
+    )
+    db.add(run)
+    await db.commit()
+    await db.refresh(run)
+    background_tasks.add_task(
+        _background_proxmox_import,
+        run.id,
+        payload.host,
+        payload.port,
+        token_id,
+        token_secret,
+        payload.verify_tls,
+    )
+    return run
+
+
+@router.post("/sync-now", response_model=ScanRunResponse)
+async def sync_proxmox_now(
+    background_tasks: BackgroundTasks,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> ScanRun:
+    """Trigger an immediate Proxmox inventory sync using the server env config.
+
+    Same background flow as ``/import-pending`` but sources host + token from
+    ``settings`` (env) rather than the request body — the manual counterpart to
+    the scheduled auto-sync job. Requires the env token to be configured.
+    """
+    if not (settings.proxmox_host and settings.proxmox_token_id and settings.proxmox_token_secret):
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot sync: no Proxmox host/token configured on the server.",
+        )
+    run = ScanRun(
+        status="running",
+        kind="proxmox",
+        ranges=[f"{settings.proxmox_host}:{settings.proxmox_port}"],
+    )
+    db.add(run)
+    await db.commit()
+    await db.refresh(run)
+    background_tasks.add_task(
+        _background_proxmox_import,
+        run.id,
+        settings.proxmox_host,
+        settings.proxmox_port,
+        settings.proxmox_token_id,
+        settings.proxmox_token_secret,
+        settings.proxmox_verify_tls,
+    )
+    return run
+
+
+async def _background_proxmox_import(
+    run_id: str,
+    host: str,
+    port: int,
+    token_id: str,
+    token_secret: str,
+    verify_tls: bool,
+) -> None:
+    async with AsyncSessionLocal() as db:
+        try:
+            nodes_raw, edges_raw = await fetch_proxmox_inventory(
+                host=host,
+                port=port,
+                token_id=token_id,
+                token_secret=token_secret,
+                verify_tls=verify_tls,
+            )
+            result = await _persist_pending_import(db, nodes_raw, edges_raw)
+            run = await db.get(ScanRun, run_id)
+            if run:
+                run.status = "done"
+                run.devices_found = result.device_count
+                run.finished_at = datetime.now(timezone.utc)
+                run.error = _guest_visibility_advisory(nodes_raw)
+                await db.commit()
+            # Nudge the frontend to reload the inventory (same signal the IP scan
+            # emits) so imported/merged devices appear without a manual refresh.
+            from app.api.routes.status import broadcast_scan_update
+            await broadcast_scan_update(run_id=run_id, devices_found=result.device_count)
+        except Exception as exc:
+            logger.exception("Proxmox import %s failed", run_id)
+            await db.rollback()
+            run = await db.get(ScanRun, run_id)
+            if run:
+                run.status = "error"
+                run.error = str(exc)[:500]
+                run.finished_at = datetime.now(timezone.utc)
+                await db.commit()
+
+
+def _guest_visibility_advisory(nodes_raw: list[dict[str, Any]]) -> str | None:
+    """Non-fatal advisory when hosts import but no VMs/LXC were visible.
+
+    A Proxmox API token that lacks ``VM.Audit`` sees empty ``qemu``/``lxc`` lists
+    (HTTP 200, no error), so only host nodes come through. The usual cause is a
+    privilege-separated token whose effective rights are the *intersection* with
+    the user's rights — granting PVEAuditor to the token alone is not enough when
+    the user has none. Surface that instead of a silent success.
+    """
+    hosts = sum(1 for n in nodes_raw if n.get("type") == "proxmox")
+    guests = len(nodes_raw) - hosts
+    if hosts and not guests:
+        return (
+            f"Imported {hosts} host(s) but no VMs or LXC were visible to the API "
+            "token. Grant the PVEAuditor role at path '/' to BOTH the token and "
+            "the user (privilege-separated tokens get the intersection of token "
+            "and user rights), then re-import."
+        )
+    return None
+
+
+async def _persist_pending_import(
+    db: AsyncSession,
+    nodes_raw: list[dict[str, Any]],
+    edges_raw: list[dict[str, Any]],
+) -> ProxmoxImportPendingResponse:
+    """Upsert Proxmox nodes/edges into device_inventory + device_inventory_links.
+
+    Two-tier identity (order matters):
+      1. Match an existing canvas Node or pending row by **IP** (merge into a
+         device previously found by a scan) — never duplicate.
+      2. Else match by synthetic ``ieee_address`` (``pve-...``).
+
+    Update-in-place only. Nothing is ever deleted; hidden rows stay hidden.
+    """
+    await dedupe_nodes_by_ieee(db)
+
+    cluster_pairs = build_proxmox_cluster_links(nodes_raw)
+    cluster_members = {ieee for pair in cluster_pairs for ieee in pair}
+
+    pending_created = 0
+    pending_updated = 0
+
+    for n in nodes_raw:
+        ieee = n.get("ieee_address")
+        if not ieee:
+            continue
+        ip = n.get("ip")
+        mac = normalize_mac(n.get("mac"))
+        props = build_proxmox_properties(n)
+
+        # 1) Already on a canvas? Match by ieee OR ip OR mac (the cross-source
+        # dedup key — a stopped VM has no IP but its configured NIC MAC still
+        # matches an ARP-scanned node). Refresh in place: merge properties, adopt
+        # the pve identity onto a scanned node, backfill blank specs/hostname/mac.
+        # Do NOT stomp user-set type/status.
+        node_filter = [Node.ieee_address == ieee]
+        if ip:
+            node_filter.append(Node.ip == ip)
+        if mac:
+            node_filter.append(Node.mac == mac)
+        existing_nodes = (
+            await db.execute(select(Node).where(or_(*node_filter)).order_by(Node.id))
+        ).scalars().all()
+
+        if existing_nodes:
+            for en in existing_nodes:
+                en.properties = merge_proxmox_properties(en.properties, props)
+                if not en.ieee_address:
+                    en.ieee_address = ieee
+                if ip and not en.ip:
+                    en.ip = ip
+                if mac and not en.mac:
+                    en.mac = mac
+                en.hostname = en.hostname or n.get("hostname")
+                en.cpu_count = en.cpu_count or n.get("cpu_count")
+                en.ram_gb = en.ram_gb or n.get("ram_gb")
+                en.disk_gb = en.disk_gb or n.get("disk_gb")
+                # A cluster host needs one left + one right handle for the
+                # cluster edge endpoints (both default to 0).
+                if ieee in cluster_members:
+                    en.left_handles = max(en.left_handles or 0, 1)
+                    en.right_handles = max(en.right_handles or 0, 1)
+            await _ensure_inventory_row(db, ieee, ip, mac, n, props, approved=True)
+            pending_updated += 1
+            continue
+
+        # 2) Not on canvas — upsert the pending inventory row.
+        pending = await _find_pending(db, ieee, ip, mac)
+        if pending is None:
+            db.add(_new_pending(ieee, ip, mac, n, props, status="pending"))
+            pending_created += 1
+        else:
+            _refresh_pending(pending, ieee, ip, mac, n, props)
+            pending_updated += 1
+
+    links_recorded = await _replace_links(db, edges_raw, cluster_pairs)
+    await db.commit()
+
+    return ProxmoxImportPendingResponse(
+        pending_created=pending_created,
+        pending_updated=pending_updated,
+        links_recorded=links_recorded,
+        device_count=len(nodes_raw),
+    )
+
+
+async def _find_pending(
+    db: AsyncSession, ieee: str, ip: str | None, mac: str | None
+) -> InventoryDevice | None:
+    filters = [InventoryDevice.ieee_address == ieee]
+    if ip:
+        filters.append(InventoryDevice.ip == ip)
+    if mac:
+        filters.append(InventoryDevice.mac == mac)
+    return (
+        await db.execute(select(InventoryDevice).where(or_(*filters)))
+    ).scalars().first()
+
+
+def _new_pending(
+    ieee: str,
+    ip: str | None,
+    mac: str | None,
+    n: dict[str, Any],
+    props: list[dict[str, Any]],
+    status: str,
+) -> InventoryDevice:
+    return InventoryDevice(
+        ieee_address=ieee,
+        ip=ip,
+        mac=mac,
+        hostname=n.get("hostname"),
+        friendly_name=n.get("label"),
+        suggested_type=n.get("type"),
+        vendor=n.get("vendor"),
+        model=n.get("model"),
+        properties=props,
+        status=status,
+        discovery_source=_PROXMOX_GUEST_SOURCE,
+        discovery_sources=[_PROXMOX_GUEST_SOURCE],
+    )
+
+
+def _sources_after_merge(row: InventoryDevice) -> list[str]:
+    """Discovery sources for an inventory row after a Proxmox import merges in.
+
+    Must run BEFORE the ``pve-`` ieee is adopted onto the row, so it can tell
+    whether the row was originally a scanned device. Preserves the prior scan
+    origin — including legacy rows created before ``discovery_sources`` existed
+    (empty list) and possibly with a NULL ``discovery_source`` — so the IP tag
+    survives the merge. A row that carries an IP but was not itself a Proxmox
+    device (no ``pve-`` ieee) was found by a scan; keep an IP-scan source.
+    """
+    sources = add_source(row.discovery_sources, row.discovery_source)
+    was_scanned = not (row.ieee_address or "").startswith("pve-")
+    if was_scanned and row.ip and not any(s in ("arp", "mdns") for s in sources):
+        sources = add_source(sources, "arp")
+    return add_source(sources, _PROXMOX_GUEST_SOURCE)
+
+
+def _refresh_pending(
+    pending: InventoryDevice,
+    ieee: str,
+    ip: str | None,
+    mac: str | None,
+    n: dict[str, Any],
+    props: list[dict[str, Any]],
+) -> None:
+    # Compute sources before adopting the pve ieee (needs the pre-merge origin).
+    pending.discovery_sources = _sources_after_merge(pending)
+    pending.ieee_address = pending.ieee_address or ieee
+    pending.ip = ip or pending.ip
+    pending.mac = pending.mac or mac
+    pending.hostname = n.get("hostname") or pending.hostname
+    pending.friendly_name = n.get("label") or pending.friendly_name
+    pending.suggested_type = n.get("type") or pending.suggested_type
+    pending.vendor = n.get("vendor") or pending.vendor
+    pending.model = n.get("model") or pending.model
+    pending.properties = merge_proxmox_properties(list(pending.properties or []), props)
+    if pending.status == "approved":
+        # Approved earlier but the canvas Node is gone — revive so it reappears.
+        pending.status = "pending"
+    # hidden stays hidden.
+
+
+async def _ensure_inventory_row(
+    db: AsyncSession,
+    ieee: str,
+    ip: str | None,
+    mac: str | None,
+    n: dict[str, Any],
+    props: list[dict[str, Any]],
+    approved: bool,
+) -> None:
+    """Ensure an inventory row exists for a device already on a canvas, so it
+    shows in the inventory with an 'In N canvas' badge. Never changes status."""
+    inv = await _find_pending(db, ieee, ip, mac)
+    if inv is None:
+        db.add(_new_pending(ieee, ip, mac, n, props, status="approved" if approved else "pending"))
+    else:
+        # Compute sources before adopting the pve ieee (needs the pre-merge origin).
+        inv.discovery_sources = _sources_after_merge(inv)
+        inv.ieee_address = inv.ieee_address or ieee
+        inv.ip = ip or inv.ip
+        inv.mac = inv.mac or mac
+        inv.hostname = n.get("hostname") or inv.hostname
+        inv.suggested_type = n.get("type") or inv.suggested_type
+        inv.properties = merge_proxmox_properties(list(inv.properties or []), props)
+
+
+async def _replace_links(
+    db: AsyncSession,
+    edges_raw: list[dict[str, Any]],
+    cluster_pairs: list[tuple[str, str]],
+) -> int:
+    """Wipe all proxmox-source links and re-insert the freshly discovered set.
+
+    Two link shapes: host→guest (``proxmox`` → 'virtual' edges) and host↔host
+    (``proxmox_cluster`` → 'cluster' edges).
+    """
+    await db.execute(
+        sa_delete(InventoryDeviceLink).where(
+            InventoryDeviceLink.discovery_source.in_([_PROXMOX_GUEST_SOURCE, _PROXMOX_CLUSTER_SOURCE])
+        )
+    )
+    recorded = 0
+    seen: set[tuple[str, str]] = set()
+
+    def _add(src: str | None, tgt: str | None, source: str) -> None:
+        nonlocal recorded
+        if not src or not tgt or (src, tgt) in seen:
+            return
+        seen.add((src, tgt))
+        db.add(InventoryDeviceLink(source_ieee=src, target_ieee=tgt, discovery_source=source))
+        recorded += 1
+
+    for e in edges_raw:
+        _add(e.get("source"), e.get("target"), _PROXMOX_GUEST_SOURCE)
+    for src, tgt in cluster_pairs:
+        _add(src, tgt, _PROXMOX_CLUSTER_SOURCE)
+
+    return recorded
+
+
+@router.get("/config", response_model=ProxmoxConfig)
+async def get_proxmox_config(_: str = Depends(get_current_user)) -> ProxmoxConfig:
+    """Return non-secret Proxmox config. Never includes the token — only whether
+    one is configured on the server."""
+    return ProxmoxConfig(
+        host=settings.proxmox_host,
+        port=settings.proxmox_port,
+        verify_tls=settings.proxmox_verify_tls,
+        sync_enabled=settings.proxmox_sync_enabled,
+        sync_interval=settings.proxmox_sync_interval,
+        token_configured=bool(settings.proxmox_token_id and settings.proxmox_token_secret),
+    )
+
+
+@router.post("/config", response_model=ProxmoxConfig)
+async def save_proxmox_config(
+    payload: ProxmoxSyncConfig,
+    _: str = Depends(get_current_user),
+) -> ProxmoxConfig:
+    """Persist the auto-sync activation (enabled + interval) and apply it live.
+
+    This is the ONLY Proxmox config the app writes. Connection settings
+    (host, port, token, verify_tls) are env-only and are never accepted or
+    persisted here — enabling auto-sync requires host + token already set in the
+    server env, since the scheduled job reads them from there.
+    """
+    if payload.sync_enabled and not (
+        settings.proxmox_host and settings.proxmox_token_id and settings.proxmox_token_secret
+    ):
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot enable auto-sync: no Proxmox host/token configured in the server env.",
+        )
+    try:
+        settings.proxmox_sync_enabled = payload.sync_enabled
+        settings.proxmox_sync_interval = payload.sync_interval
+        settings.save_overrides()
+        set_proxmox_sync_enabled(payload.sync_enabled)
+        if payload.sync_enabled:
+            reschedule_proxmox_sync(payload.sync_interval)
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    return await get_proxmox_config()

backend/app/api/routes/racks.py

@@ -0,0 +1,349 @@
+from datetime import datetime, timezone
+from typing import Any, TypeVar
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_current_user
+from app.db.database import get_db
+from app.db.models import CanvasState, Design, InventoryDevice, Node, Rack, RackCable, RackDevice
+from app.schemas.racks import (
+    RackCableResponse,
+    RackDeviceResponse,
+    RackInventoryItem,
+    RackInventoryResponse,
+    RackResponse,
+    RackSaveRequest,
+    RackServiceInfo,
+    RackStateResponse,
+)
+
+router = APIRouter()
+
+# Device kinds that cannot be racked. An exclusion list rather than an allow list:
+# new hardware types should show up in the tray by default, and only the obviously
+# virtual / mesh / annotation kinds need to opt out.
+_UNRACKABLE_TYPES = {
+    "vm",
+    "lxc",
+    "docker_container",
+    "mobile",
+    "laptop",
+    "light",
+    "socket",
+    "load",
+    "groupRect",
+    "group",
+    "text",
+    "zigbee_coordinator",
+    "zigbee_router",
+    "zigbee_enddevice",
+    "zwave_coordinator",
+    "zwave_router",
+    "zwave_enddevice",
+}
+
+
+_COMMON_PORTS = {22, 80, 443}
+
+
+def _service_name(device: InventoryDevice) -> str | None:
+    """Name a device after the app it runs, the way the Device Inventory does.
+
+    Ports everyone exposes (ssh, http, https) say nothing, and the generic web
+    category loses to a real match, so "jellyfin" wins over "http".
+    """
+    candidates = [
+        s
+        for s in (device.services or [])
+        if isinstance(s, dict)
+        and s.get("category")
+        and s.get("service_name")
+        # A service with no port is not a fingerprint the inventory names a
+        # device after either — and `None not in _COMMON_PORTS` is True.
+        and s.get("port") is not None
+        and s.get("port") not in _COMMON_PORTS
+    ]
+    if not candidates:
+        return None
+    named = next((s for s in candidates if str(s["category"]).lower() != "web"), candidates[0])
+    name = named.get("service_name")
+    return str(name) if name else None
+
+
+def _device_label(device: InventoryDevice) -> str:
+    """Inventory naming, mirrored: friendly name, host, app, IP, IEEE, id.
+
+    Must stay in step with `deviceLabel` in `InventoryDevicesModal.tsx` — a device
+    the user picked out of the inventory by one name should not turn up in the
+    rack picker under another.
+    """
+    return (
+        device.friendly_name
+        or device.hostname
+        or _service_name(device)
+        or device.ip
+        or device.ieee_address
+        or device.id
+    )
+
+
+# A mount prints its services as a short list, not a port scan dump.
+_MAX_SERVICES = 12
+
+
+def _services(raw: Any) -> list[RackServiceInfo]:
+    """Fingerprinted services, deduped and trimmed for the rack's info panel."""
+    out: list[RackServiceInfo] = []
+    seen: set[tuple[int | None, str | None]] = set()
+    for entry in raw or []:
+        if not isinstance(entry, dict):
+            continue
+        raw_port = entry.get("port")
+        port = raw_port if isinstance(raw_port, int) else None
+        raw_name = entry.get("service_name") or entry.get("name")
+        name = str(raw_name) if raw_name else None
+        if port is None and name is None:
+            continue
+        if (port, name) in seen:
+            continue
+        seen.add((port, name))
+        out.append(RackServiceInfo(port=port, name=name))
+        if len(out) == _MAX_SERVICES:
+            break
+    return out
+
+
+def _ip_tokens(ip: str | None) -> list[str]:
+    """Split a device ``ip`` field into individual addresses.
+
+    Mirrors the scan routes: the canvas stores multiple addresses in one
+    comma-separated string, so matching must compare per-address.
+    """
+    return [t.strip() for t in ip.split(",") if t.strip()] if ip else []
+
+
+_Row = TypeVar("_Row", Rack, RackDevice, RackCable)
+
+
+async def _owned(
+    db: AsyncSession, model: type[_Row], row_id: str, design_id: str
+) -> _Row | None:
+    """Fetch a rack row by id, refusing one that belongs to another design.
+
+    The upsert below sets `design_id` from the payload, so without this a save
+    carrying an id from design A would quietly move A's rack — devices and
+    cables included — into design B, and A would lose it with no error. Ids come
+    from the client, so a copied design or a stale tab is enough to collide.
+    """
+    row = await db.get(model, row_id)
+    if row is not None and row.design_id != design_id:
+        raise HTTPException(409, f"{model.__name__} {row_id} belongs to another design")
+    return row
+
+
+async def _require_design(db: AsyncSession, design_id: str) -> Design:
+    design = await db.get(Design, design_id)
+    if not design:
+        raise HTTPException(404, "Design not found")
+    return design
+
+
+@router.get("", response_model=RackStateResponse)
+async def load_racks(
+    design_id: str = Query(..., description="Rack design to load"),
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> RackStateResponse:
+    await _require_design(db, design_id)
+
+    racks = (await db.execute(select(Rack).where(Rack.design_id == design_id))).scalars().all()
+    devices = (
+        await db.execute(select(RackDevice).where(RackDevice.design_id == design_id))
+    ).scalars().all()
+    cables = (await db.execute(select(RackCable).where(RackCable.design_id == design_id))).scalars().all()
+    state = await db.get(CanvasState, design_id)
+
+    return RackStateResponse(
+        racks=[RackResponse.model_validate(r) for r in racks],
+        devices=[RackDeviceResponse.model_validate(d) for d in devices],
+        cables=[RackCableResponse.model_validate(c) for c in cables],
+        viewport=state.viewport if state else {"x": 0, "y": 0, "zoom": 1},
+    )
+
+
+@router.post("/save")
+async def save_racks(
+    body: RackSaveRequest,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> dict[str, bool]:
+    """Persist the full rack state of one design: upsert what is sent, prune the rest."""
+    await _require_design(db, body.design_id)
+
+    rack_ids = {r.id for r in body.racks}
+    device_ids = {d.id for d in body.devices}
+
+    # A device must land in a rack that is part of the same payload, and a cable
+    # must join two devices in it — otherwise the prune below would orphan them.
+    for device in body.devices:
+        if device.rack_id not in rack_ids:
+            raise HTTPException(400, f"Device {device.id} references unknown rack {device.rack_id}")
+    for cable in body.cables:
+        if cable.from_device_id not in device_ids or cable.to_device_id not in device_ids:
+            raise HTTPException(400, f"Cable {cable.id} references a device outside this payload")
+
+    # Prune first (cables, then devices, then racks) so freed rows never collide
+    # with an upsert that reuses their geometry.
+    for existing_cable in (
+        await db.execute(select(RackCable).where(RackCable.design_id == body.design_id))
+    ).scalars().all():
+        if existing_cable.id not in {c.id for c in body.cables}:
+            await db.delete(existing_cable)
+    for existing_device in (
+        await db.execute(select(RackDevice).where(RackDevice.design_id == body.design_id))
+    ).scalars().all():
+        if existing_device.id not in device_ids:
+            await db.delete(existing_device)
+    for existing_rack in (
+        await db.execute(select(Rack).where(Rack.design_id == body.design_id))
+    ).scalars().all():
+        if existing_rack.id not in rack_ids:
+            await db.delete(existing_rack)
+    await db.flush()
+
+    for rack_data in body.racks:
+        payload: dict[str, Any] = rack_data.model_dump()
+        payload["design_id"] = body.design_id
+        db_rack = await _owned(db, Rack, rack_data.id, body.design_id)
+        if db_rack:
+            for field, value in payload.items():
+                setattr(db_rack, field, value)
+        else:
+            db.add(Rack(**payload))
+    await db.flush()  # racks must exist before devices point at them
+
+    for device_data in body.devices:
+        payload = device_data.model_dump()
+        payload["design_id"] = body.design_id
+        db_device = await _owned(db, RackDevice, device_data.id, body.design_id)
+        if db_device:
+            for field, value in payload.items():
+                setattr(db_device, field, value)
+        else:
+            db.add(RackDevice(**payload))
+    await db.flush()  # devices must exist before cables point at them
+
+    for cable_data in body.cables:
+        payload = cable_data.model_dump()
+        payload["design_id"] = body.design_id
+        db_cable = await _owned(db, RackCable, cable_data.id, body.design_id)
+        if db_cable:
+            for field, value in payload.items():
+                setattr(db_cable, field, value)
+        else:
+            db.add(RackCable(**payload))
+
+    # Viewport lives on the design's shared CanvasState row, like the logical canvas.
+    state = await db.get(CanvasState, body.design_id)
+    if state:
+        state.viewport = body.viewport
+        state.saved_at = datetime.now(timezone.utc)
+    else:
+        db.add(CanvasState(design_id=body.design_id, viewport=body.viewport))
+
+    await db.commit()
+    return {"saved": True}
+
+
+@router.get("/inventory", response_model=RackInventoryResponse)
+async def rack_inventory(
+    design_id: str = Query(..., description="Rack design the tray is for"),
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> RackInventoryResponse:
+    """Device Inventory entries that can be racked, flagged with what is already mounted.
+
+    Reads `device_inventory` — the inventory survives approval and node deletion,
+    so unracking or deleting a canvas node never removes the entry here.
+    """
+    await _require_design(db, design_id)
+
+    devices = (
+        await db.execute(select(InventoryDevice).where(InventoryDevice.status != "hidden"))
+    ).scalars().all()
+    mounts = (
+        await db.execute(
+            select(RackDevice.device_id, RackDevice.node_id).where(
+                RackDevice.design_id == design_id
+            )
+        )
+    ).all()
+    mounted = {device_id for device_id, _ in mounts if device_id}
+    # A mount can name its canvas node itself, when the user linked one by hand
+    # in the rack. That beats the IEEE/IP guess below: the guess is what failed
+    # to find anything in the first place.
+    pinned = {device_id: node_id for device_id, node_id in mounts if device_id and node_id}
+
+    # Correlate against canvas nodes for live status: IEEE first (stable), then IP.
+    nodes = (await db.execute(select(Node))).scalars().all()
+    by_id = {n.id: n for n in nodes}
+    by_ieee = {n.ieee_address: n for n in nodes if n.ieee_address}
+    by_ip: dict[str, Node] = {}
+    for node in nodes:
+        for token in _ip_tokens(node.ip):
+            by_ip.setdefault(token, node)
+    # Which canvas the matched node lives on — the rack prints it so the user
+    # knows where the logical twin of a mount is drawn.
+    design_names = {
+        d.id: d.name for d in (await db.execute(select(Design))).scalars().all()
+    }
+
+    items = []
+    for device in devices:
+        if device.suggested_type in _UNRACKABLE_TYPES:
+            continue
+        # A node the user linked by hand wins; a deleted one falls back to the
+        # guess rather than reporting a node that no longer exists.
+        linked: Node | None = by_id.get(pinned.get(device.id) or "")
+        if linked is None and device.ieee_address:
+            linked = by_ieee.get(device.ieee_address)
+        if linked is None:
+            linked = next((by_ip[t] for t in _ip_tokens(device.ip) if t in by_ip), None)
+        # The node is the richer record once a device has been approved onto a
+        # canvas; the inventory row is what discovery last saw. Report both and
+        # let the panel prefer the node.
+        services = _services(device.services) or (
+            _services(linked.services) if linked else []
+        )
+        items.append(
+            RackInventoryItem(
+                id=device.id,
+                label=_device_label(device),
+                suggested_type=device.suggested_type,
+                ip=device.ip,
+                status=device.status,
+                discovery_source=device.discovery_source,
+                mac=device.mac or device.ieee_address,
+                hostname=device.hostname,
+                os=device.os,
+                services=services,
+                node_id=linked.id if linked else None,
+                node_status=linked.status if linked else None,
+                node_label=linked.label if linked else None,
+                node_type=linked.type if linked else None,
+                node_ip=linked.ip if linked else None,
+                node_mac=(linked.mac or linked.ieee_address) if linked else None,
+                node_hostname=linked.hostname if linked else None,
+                node_os=linked.os if linked else None,
+                node_check_method=linked.check_method if linked else None,
+                node_design_id=linked.design_id if linked else None,
+                node_design_name=(
+                    design_names.get(linked.design_id) if linked and linked.design_id else None
+                ),
+                node_last_seen=linked.last_seen if linked else None,
+                racked=device.id in mounted,
+            )
+        )
+    return RackInventoryResponse(items=items)

backend/app/api/routes/scan.py

@@ -12,17 +12,50 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from app.api.deps import get_current_user
 from app.core.config import settings
 from app.db.database import AsyncSessionLocal, get_db
-from app.db.models import Design, Edge, Node, PendingDevice, PendingDeviceLink, ScanRun
+from app.db.models import (
+    Design,
+    Edge,
+    InventoryDevice,
+    InventoryDeviceLink,
+    Node,
+    RackDevice,
+    ScanRun,
+)
 from app.schemas.nodes import NodeCreate
-from app.schemas.scan import PendingDeviceResponse, ScanRunResponse
+from app.schemas.scan import InventoryDeviceCreate, InventoryDeviceResponse, ScanRunResponse
+from app.services.mac_utils import normalize_mac
+from app.services.node_dedupe import dedupe_nodes_by_ieee, find_duplicate_node
 from app.services.scanner import DeepScanOptions, _valid_port_range, request_cancel, run_scan
-from app.services.zigbee_service import build_zigbee_properties
+from app.services.zigbee_service import (
+    build_zigbee_properties,
+    merge_zigbee_properties,
+)
 from app.services.zwave_service import build_zwave_properties
 
 _ZIGBEE_TYPES = {"zigbee_coordinator", "zigbee_router", "zigbee_enddevice"}
 _ZWAVE_TYPES = {"zwave_coordinator", "zwave_router", "zwave_enddevice"}
 
 
+def _ip_tokens(ip: str | None) -> list[str]:
+    """Split a Node/device ``ip`` field into individual addresses.
+
+    The canvas stores multiple addresses in one comma-separated string (e.g.
+    ``"fe80::1, 192.168.1.5"`` once a user adds an IPv6 address). Matching a
+    scanned device against that field must compare per-address, not against the
+    whole string, or the device looks absent from the canvas (issue #258).
+    """
+    return [t.strip() for t in ip.split(",") if t.strip()] if ip else []
+
+
+def _is_rack_only(device: InventoryDevice) -> bool:
+    """True for inventory entries created from a rack canvas.
+
+    They describe a mount — a patch panel, a shelf, a chassis — not a host to
+    document on a logical canvas, so they are never approved onto one.
+    """
+    return device.discovery_source == "rack" or "rack" in (device.discovery_sources or [])
+
+
 def _is_wireless(node_type: str | None) -> bool:
     """Zigbee + Z-Wave mesh devices share online status / no ICMP check."""
     return node_type in _ZIGBEE_TYPES or node_type in _ZWAVE_TYPES
@@ -209,14 +242,20 @@ def _agg(values: list[datetime], *, newest: bool) -> datetime | None:
 
 
 async def _canvas_correlation(
-    db: AsyncSession, devices: list[PendingDevice]
+    db: AsyncSession, devices: list[InventoryDevice]
 ) -> dict[str, dict[str, Any]]:
-    """Correlate each device to existing canvas nodes by ``ieee_address`` or ``ip``.
+    """Correlate each device to existing canvas nodes by ``ieee_address``, ``mac``
+    or ``ip``.
 
     Returns, per device id: the number of distinct canvases (designs) it appears
     on, plus aggregated timestamps from every matching node — created_at (oldest),
     last_scan / updated_at / last_seen (newest). One node query, grouped in Python
     (node counts are small for a homelab), so no N+1 per device.
+
+    IP matching is per-address: a node's ``ip`` may hold several comma-separated
+    addresses (e.g. an IPv6 added before the IPv4), so we index each token, not
+    the raw string. MAC is a stable identifier immune to such IP edits, so it is
+    matched too — cumulatively with ieee/ip (issue #258).
     """
     if not devices:
         return {}
@@ -224,6 +263,7 @@ async def _canvas_correlation(
         await db.execute(
             select(
                 Node.ip,
+                Node.mac,
                 Node.ieee_address,
                 Node.design_id,
                 Node.created_at,
@@ -233,12 +273,15 @@ async def _canvas_correlation(
             ).where(Node.design_id.isnot(None))
         )
     ).all()
-    # Index matching nodes by ip and by ieee so a device can look up both.
+    # Index matching nodes by ip token, mac and ieee so a device can look up any.
     by_ip: dict[str, list[Any]] = {}
+    by_mac: dict[str, list[Any]] = {}
     by_ieee: dict[str, list[Any]] = {}
     for row in rows:
-        if row.ip:
-            by_ip.setdefault(row.ip, []).append(row)
+        for tok in _ip_tokens(row.ip):
+            by_ip.setdefault(tok, []).append(row)
+        if row.mac:
+            by_mac.setdefault(row.mac, []).append(row)
         if row.ieee_address:
             by_ieee.setdefault(row.ieee_address, []).append(row)
 
@@ -247,9 +290,11 @@ async def _canvas_correlation(
         matched = []
         if d.ieee_address:
             matched += by_ieee.get(d.ieee_address, [])
-        if d.ip:
-            matched += by_ip.get(d.ip, [])
-        # De-duplicate nodes matched by both ip and ieee.
+        if d.mac:
+            matched += by_mac.get(d.mac, [])
+        for tok in _ip_tokens(d.ip):
+            matched += by_ip.get(tok, [])
+        # De-duplicate nodes matched by more than one identifier.
         matched = list({id(m): m for m in matched}.values())
         designs = {m.design_id for m in matched}
         info[d.id] = {
@@ -263,8 +308,8 @@ async def _canvas_correlation(
 
 
 async def _with_canvas_counts(
-    db: AsyncSession, devices: list[PendingDevice]
-) -> list[PendingDevice]:
+    db: AsyncSession, devices: list[InventoryDevice]
+) -> list[InventoryDevice]:
     """Attach transient canvas count + linked-node timestamps for the response."""
     info = await _canvas_correlation(db, devices)
     for d in devices:
@@ -277,28 +322,91 @@ async def _with_canvas_counts(
     return devices
 
 
-@router.get("/pending", response_model=list[PendingDeviceResponse])
-async def list_pending(db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> list[PendingDevice]:
+@router.get("/pending", response_model=list[InventoryDeviceResponse])
+async def list_pending(db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> list[InventoryDevice]:
     # Inventory: every scanned device except the user-hidden ones. Approved devices
     # stay listed so they keep showing with a canvas-presence badge.
-    result = await db.execute(select(PendingDevice).where(PendingDevice.status != "hidden"))
+    result = await db.execute(select(InventoryDevice).where(InventoryDevice.status != "hidden"))
     return await _with_canvas_counts(db, list(result.scalars().all()))
 
 
+@router.post("/pending", response_model=InventoryDeviceResponse, status_code=201)
+async def create_pending(
+    body: InventoryDeviceCreate,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> InventoryDevice:
+    """Add an inventory entry by hand, for hardware no scan can discover.
+
+    Lands as ``status="pending"`` like a discovery would, so the existing approve
+    / hide / restore flows apply unchanged.
+    """
+    device = InventoryDevice(
+        hostname=body.hostname,
+        ip=body.ip,
+        # Canonical form, like every other write path: dedup compares MACs by
+        # equality, so a hand-typed "AA-BB-CC-11-22-33" would never match the
+        # scanned "aa:bb:cc:11:22:33" and approve would build a duplicate node.
+        mac=normalize_mac(body.mac),
+        suggested_type=body.suggested_type,
+        model=body.model,
+        vendor=body.vendor,
+        properties=body.properties,
+        status="pending",
+        discovery_source=body.discovery_source,
+        discovery_sources=[body.discovery_source],
+    )
+    db.add(device)
+    await db.commit()
+    await db.refresh(device)
+    return (await _with_canvas_counts(db, [device]))[0]
+
+
 @router.delete("/pending", response_model=dict)
 async def clear_pending(
     db: AsyncSession = Depends(get_db),
     _: str = Depends(get_current_user),
 ) -> dict[str, int]:
     from sqlalchemy import delete as sa_delete
-    result = await db.execute(sa_delete(PendingDevice).where(PendingDevice.status == "pending"))
+    result = await db.execute(sa_delete(InventoryDevice).where(InventoryDevice.status == "pending"))
     await db.commit()
     return {"deleted": result.rowcount}
 
 
-@router.get("/hidden", response_model=list[PendingDeviceResponse])
-async def list_hidden(db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> list[PendingDevice]:
-    result = await db.execute(select(PendingDevice).where(PendingDevice.status == "hidden"))
+@router.delete("/pending/{device_id}", response_model=dict)
+async def delete_pending(
+    device_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> dict[str, bool]:
+    """Remove one inventory entry.
+
+    Used by the rack canvas to drop the placeholder it created for a plate once
+    that plate is pointed at a real inventory row. Refuses while a rack still
+    mounts the device: SQLite runs with foreign keys off here, so the mount's
+    ``device_id`` would be left naming a row that no longer exists rather than
+    being cleared by the ``ON DELETE SET NULL`` the schema declares.
+    """
+    device = (
+        await db.execute(select(InventoryDevice).where(InventoryDevice.id == device_id))
+    ).scalar_one_or_none()
+    if not device:
+        raise HTTPException(status_code=404, detail="Device not found")
+
+    mounted = (
+        await db.execute(select(RackDevice.id).where(RackDevice.device_id == device_id).limit(1))
+    ).scalar_one_or_none()
+    if mounted:
+        raise HTTPException(status_code=409, detail="Device is mounted in a rack")
+
+    await db.delete(device)
+    await db.commit()
+    return {"deleted": True}
+
+
+@router.get("/hidden", response_model=list[InventoryDeviceResponse])
+async def list_hidden(db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> list[InventoryDevice]:
+    result = await db.execute(select(InventoryDevice).where(InventoryDevice.status == "hidden"))
     return await _with_canvas_counts(db, list(result.scalars().all()))
 
 
@@ -308,6 +416,9 @@ async def bulk_approve_devices(
     db: AsyncSession = Depends(get_db),
     _: str = Depends(get_current_user),
 ) -> dict[str, Any]:
+    # Repair any legacy same-canvas duplicate nodes before placing more.
+    await dedupe_nodes_by_ieee(db)
+
     # Target the design the user is on; fall back to the first design.
     default_design_id = payload.design_id
     if default_design_id is None:
@@ -320,35 +431,73 @@ async def bulk_approve_devices(
     # node was later deleted) must still be placeable on THIS design. Duplicates
     # are guarded per-design below, not by the global status flag.
     result = await db.execute(
-        select(PendingDevice).where(
-            PendingDevice.id.in_(payload.device_ids),
-            PendingDevice.status != "hidden",
+        select(InventoryDevice).where(
+            InventoryDevice.id.in_(payload.device_ids),
+            InventoryDevice.status != "hidden",
         )
     )
     devices = result.scalars().all()
 
     # What already sits on the target canvas, so we skip devices already placed
-    # here (by ip or ieee_address) instead of creating duplicate nodes.
+    # here (by ip, mac or ieee_address) instead of creating duplicate nodes. We
+    # map to the existing node id so the skip report can point the user at it. A
+    # value may be a Node still pending flush (in-batch duplicate) — resolved to
+    # its id after the flush below. IPs are indexed per comma-separated token so
+    # a node whose ip is "fe80::1, 192.168.1.5" still matches a device scanned as
+    # 192.168.1.5 (issue #258).
     existing = (
         await db.execute(
-            select(Node.ip, Node.ieee_address).where(Node.design_id == default_design_id)
+            select(Node.id, Node.ip, Node.mac, Node.ieee_address).where(
+                Node.design_id == default_design_id
+            )
         )
     ).all()
-    placed_ips = {ip for ip, _ in existing if ip}
-    placed_ieee = {ieee for _, ieee in existing if ieee}
+    placed_ips: dict[str, Any] = {
+        tok: nid for nid, ip, _, _ in existing for tok in _ip_tokens(ip)
+    }
+    placed_mac: dict[str, Any] = {mac: nid for nid, _, mac, _ in existing if mac}
+    placed_ieee: dict[str, Any] = {ieee: nid for nid, _, _, ieee in existing if ieee}
 
     created_nodes: list[Node] = []
-    approved_devices: list[PendingDevice] = []
+    approved_devices: list[InventoryDevice] = []
+    skipped_devices: list[dict[str, Any]] = []
     for device in devices:
-        already_here = (
-            (device.ip is not None and device.ip in placed_ips)
-            or (device.ieee_address is not None and device.ieee_address in placed_ieee)
-        )
-        if already_here:
+        # Rack-only gear belongs to a rack canvas, never to a logical one.
+        if _is_rack_only(device):
+            skipped_devices.append({
+                "device_id": device.id,
+                "label": device.hostname or device.friendly_name or "device",
+                "match": "rack", "value": "rack device", "_ref": None,
+            })
+            continue
+        # Record which identifier collided so the caller can explain each skip
+        # (and, for existing on-canvas nodes, link to the node already there).
+        ip_hit = next((t for t in _ip_tokens(device.ip) if t in placed_ips), None)
+        if ip_hit is not None:
+            skipped_devices.append({
+                "device_id": device.id,
+                "label": device.hostname or device.friendly_name or device.ip or "device",
+                "match": "ip", "value": ip_hit, "_ref": placed_ips[ip_hit],
+            })
+            continue
+        if device.ieee_address is not None and device.ieee_address in placed_ieee:
+            skipped_devices.append({
+                "device_id": device.id,
+                "label": device.hostname or device.friendly_name or device.ieee_address or "device",
+                "match": "ieee", "value": device.ieee_address, "_ref": placed_ieee[device.ieee_address],
+            })
+            continue
+        if device.mac is not None and device.mac in placed_mac:
+            skipped_devices.append({
+                "device_id": device.id,
+                "label": device.hostname or device.friendly_name or device.mac or "device",
+                "match": "mac", "value": device.mac, "_ref": placed_mac[device.mac],
+            })
             continue
         device.status = "approved"
         node_type = device.suggested_type or "generic"
         is_wireless = _is_wireless(node_type)
+        cluster_host = await _is_proxmox_cluster_member(db, device.ieee_address)
         node = Node(
             label=device.hostname or device.friendly_name or device.ip or "device",
             type=node_type,
@@ -360,29 +509,43 @@ async def bulk_approve_devices(
             ieee_address=device.ieee_address,
             properties=_wireless_properties(
                 node_type, device.ieee_address, device.vendor, device.model, device.lqi
-            ) if is_wireless else build_mac_property(device.mac),
+            ) if is_wireless else merge_mac_property(list(device.properties or []), device.mac),
             # Default to ping so the status checker actually polls the new node.
             # Without this the scheduler skips it (check_method NULL → no check).
             check_method="none" if is_wireless else ("ping" if device.ip else None),
+            # Cluster hosts get side handles for their host↔host cluster edge.
+            left_handles=1 if cluster_host else 0,
+            right_handles=1 if cluster_host else 0,
             design_id=default_design_id,
         )
         db.add(node)
         created_nodes.append(node)
         approved_devices.append(device)
-        # Track within this batch so a duplicate selection (same ip/ieee) is not
-        # placed twice on the same canvas.
-        if device.ip:
-            placed_ips.add(device.ip)
+        # Track within this batch so a duplicate selection (same ip/mac/ieee) is
+        # not placed twice on the same canvas. Store the Node so a later in-batch
+        # skip can resolve to its id after flush.
+        for tok in _ip_tokens(device.ip):
+            placed_ips[tok] = node
+        if device.mac:
+            placed_mac[device.mac] = node
         if device.ieee_address:
-            placed_ieee.add(device.ieee_address)
+            placed_ieee[device.ieee_address] = node
     await db.flush()  # populates node.id from Python-side default before reading
     # node_ids and approved_device_ids stay index-aligned for the client's mapping.
     node_ids = [n.id for n in created_nodes]
     approved_device_ids = [d.id for d in approved_devices]
 
+    # Resolve each skip's existing-node reference to a concrete id now that any
+    # in-batch nodes have been flushed, and expose it under a clean key.
+    for entry in skipped_devices:
+        ref = entry.pop("_ref")
+        entry["existing_node_id"] = ref.id if isinstance(ref, Node) else ref
+
     all_edges: list[dict[str, str]] = []
     for device in approved_devices:
-        all_edges.extend(await _resolve_pending_links_for_ieee(db, device.ieee_address))
+        all_edges.extend(
+            await _resolve_pending_links_for_ieee(db, device.ieee_address, default_design_id)
+        )
 
     await db.commit()
     return {
@@ -392,6 +555,7 @@ async def bulk_approve_devices(
         "edges_created": len(all_edges),
         "edges": all_edges,
         "skipped": len(payload.device_ids) - len(node_ids),
+        "skipped_devices": skipped_devices,
     }
 
 
@@ -402,9 +566,9 @@ async def bulk_hide_devices(
     _: str = Depends(get_current_user),
 ) -> dict[str, Any]:
     result = await db.execute(
-        select(PendingDevice).where(
-            PendingDevice.id.in_(payload.device_ids),
-            PendingDevice.status == "pending",
+        select(InventoryDevice).where(
+            InventoryDevice.id.in_(payload.device_ids),
+            InventoryDevice.status == "pending",
         )
     )
     devices = result.scalars().all()
@@ -420,7 +584,7 @@ async def restore_device(
     db: AsyncSession = Depends(get_db),
     _: str = Depends(get_current_user),
 ) -> dict[str, Any]:
-    device = await db.get(PendingDevice, device_id)
+    device = await db.get(InventoryDevice, device_id)
     if not device:
         raise HTTPException(status_code=404, detail="Device not found")
     if device.status != "hidden":
@@ -437,9 +601,9 @@ async def bulk_restore_devices(
     _: str = Depends(get_current_user),
 ) -> dict[str, Any]:
     result = await db.execute(
-        select(PendingDevice).where(
-            PendingDevice.id.in_(payload.device_ids),
-            PendingDevice.status == "hidden",
+        select(InventoryDevice).where(
+            InventoryDevice.id.in_(payload.device_ids),
+            InventoryDevice.status == "hidden",
         )
     )
     devices = result.scalars().all()
@@ -462,16 +626,47 @@ async def approve_device(
         first = (await db.execute(select(Design).order_by(Design.created_at).limit(1))).scalar()
         node_design_id = first.id if first else None
 
-    device = await db.get(PendingDevice, device_id)
+    device = await db.get(InventoryDevice, device_id)
     if not device:
         raise HTTPException(status_code=404, detail="Device not found")
-    if device.status != "pending":
-        raise HTTPException(status_code=409, detail="Device already processed")
-    device.status = "approved"
+    # A device's status is GLOBAL — it flips to "approved" the moment it lands on
+    # ANY canvas — but canvas membership is per-design. Approving onto a NEW
+    # design must therefore work even when the device already sits on another
+    # one (mirroring bulk_approve_devices, which deliberately does not filter on
+    # status == "pending"). Same-design duplicates are caught by the per-design
+    # IEEE/ip/mac guards below, not by this global flag. Only a user-hidden
+    # device is off-limits here.
+    if device.status == "hidden":
+        raise HTTPException(status_code=409, detail="Device is hidden")
+    if _is_rack_only(device):
+        raise HTTPException(
+            status_code=409,
+            detail="Rack devices cannot be placed on a logical canvas",
+        )
     wireless = _is_wireless(node_data.type)
+
+    # A device already on THIS design (matched by ieee, ip OR mac) is NOT placed
+    # again automatically: the user might genuinely want a second card, or might
+    # be re-approving by mistake. Reject with 409 + the existing node so the UI
+    # can ask — identical handling for IEEE (Zigbee/Z-Wave) and plain IP/ARP
+    # hosts. force=True (set after the user confirms) skips this and creates it.
+    # The same device on a *different* design is valid (one Node per canvas), so
+    # this is scoped to node_design_id.
+    if not node_data.force:
+        conflict = await find_duplicate_node(
+            db, node_design_id,
+            node_data.ip or device.ip,
+            node_data.mac or device.mac,
+            ieee=device.ieee_address,
+        )
+        if conflict is not None:
+            raise HTTPException(status_code=409, detail=conflict)
+
+    device.status = "approved"
     # Prefer the MAC discovered during the scan (stored on the pending device);
     # fall back to whatever the approve payload carried.
     _mac = device.mac or node_data.mac
+    cluster_host = await _is_proxmox_cluster_member(db, device.ieee_address)
     node = Node(
         label=node_data.label,
         type=node_data.type,
@@ -483,16 +678,22 @@ async def approve_device(
         ieee_address=device.ieee_address,
         properties=_wireless_properties(
             node_data.type, device.ieee_address, device.vendor, device.model, device.lqi
-        ) if wireless else merge_mac_property(node_data.properties, _mac),
+        ) if wireless else merge_mac_property(
+            merge_zigbee_properties(list(device.properties or []), node_data.properties or []),
+            _mac,
+        ),
         check_method="none" if wireless else (node_data.check_method or ("ping" if node_data.ip else None)),
         check_target=None if wireless else node_data.check_target,
+        # Cluster hosts get side handles for their host↔host cluster edge.
+        left_handles=1 if cluster_host else 0,
+        right_handles=1 if cluster_host else 0,
         design_id=node_design_id,
     )
     db.add(node)
     await db.flush()
     node_id = node.id
 
-    edges = await _resolve_pending_links_for_ieee(db, device.ieee_address)
+    edges = await _resolve_pending_links_for_ieee(db, device.ieee_address, node_design_id)
 
     await db.commit()
     return {
@@ -503,37 +704,67 @@ async def approve_device(
     }
 
 
-async def _resolve_pending_links_for_ieee(
-    db: AsyncSession, ieee: str | None
-) -> list[dict[str, str]]:
-    """Materialize edges for any pending_device_links involving ``ieee``.
+async def _is_proxmox_cluster_member(db: AsyncSession, ieee: str | None) -> bool:
+    """True if ``ieee`` participates in a proxmox_cluster link (host↔host).
 
-    For each link where the other endpoint already exists as a canvas Node
-    (matched by ``Node.ieee_address``), create the Edge and drop the link
-    row. Links where the other endpoint is still pending are kept so they
-    can resolve when that endpoint is approved later.
+    Such a host needs one left + one right handle for the cluster edge endpoints
+    (both default to 0). Checked at approve time, before the link is consumed by
+    ``_resolve_pending_links_for_ieee``.
+    """
+    if not ieee:
+        return False
+    found = (
+        await db.execute(
+            select(InventoryDeviceLink.id)
+            .where(
+                InventoryDeviceLink.discovery_source == "proxmox_cluster",
+                (InventoryDeviceLink.source_ieee == ieee) | (InventoryDeviceLink.target_ieee == ieee),
+            )
+            .limit(1)
+        )
+    ).scalar()
+    return found is not None
+
+
+async def _resolve_pending_links_for_ieee(
+    db: AsyncSession, ieee: str | None, design_id: str | None
+) -> list[dict[str, str]]:
+    """Materialize edges for any device_inventory_links involving ``ieee`` on the
+    canvas identified by ``design_id``.
+
+    For each link where the other endpoint already exists as a Node *on this
+    design* (matched by ``Node.ieee_address`` + ``Node.design_id``), create the
+    Edge. Links are **never** deleted here: they describe the discovered mesh /
+    cluster topology and are wiped+reinserted wholesale on the next import
+    (zigbee/zwave/proxmox). Keeping them lets the same devices be re-approved
+    onto a second canvas with their edges intact.
     """
     if not ieee:
         return []
 
     links_q = await db.execute(
-        select(PendingDeviceLink).where(
-            (PendingDeviceLink.source_ieee == ieee)
-            | (PendingDeviceLink.target_ieee == ieee)
+        select(InventoryDeviceLink).where(
+            (InventoryDeviceLink.source_ieee == ieee)
+            | (InventoryDeviceLink.target_ieee == ieee)
         )
     )
     links = list(links_q.scalars().all())
     if not links:
         return []
 
-    # Map every relevant ieee → Node (single query).
+    # Map every relevant ieee → Node *on the target design* (single query).
+    # Scoping by design is what makes a re-approve onto a second canvas link the
+    # nodes of THAT canvas, not stale nodes left on another one.
     other_ieees = {
         link.target_ieee if link.source_ieee == ieee else link.source_ieee
         for link in links
     }
     other_ieees.add(ieee)
     nodes_q = await db.execute(
-        select(Node).where(Node.ieee_address.in_(other_ieees))
+        select(Node).where(
+            Node.ieee_address.in_(other_ieees),
+            Node.design_id == design_id,
+        )
     )
     by_ieee = {n.ieee_address: n for n in nodes_q.scalars().all() if n.ieee_address}
 
@@ -564,28 +795,48 @@ async def _resolve_pending_links_for_ieee(
             src_id, tgt_id = self_node.id, other_node.id
         else:
             src_id, tgt_id = other_node.id, self_node.id
-        # Skip if either direction already exists.
+        # Skip if either direction already exists on this design (re-approve or
+        # a manually drawn link). The link row is kept for other designs.
         if (src_id, tgt_id) in existing_pairs or (tgt_id, src_id) in existing_pairs:
-            await db.delete(link)
             continue
-        # Use the source node's design_id for the edge
-        edge_design_id = self_node.design_id if self_node else None
-        if edge_design_id is None:
-            first = (await db.execute(select(Design).order_by(Design.created_at).limit(1))).scalar()
-            edge_design_id = first.id if first else None
+        # Edge lands on the design we're approving into (the nodes above are
+        # already scoped to it).
+        edge_design_id = design_id or (self_node.design_id if self_node else None)
+        # Edge shape by link source. Handle IDs are the *bare* slot-0 side names
+        # (the canonical stored form — the save path normalizes '<side>-t' → the
+        # bare source id, and React Flow resolves the bare id to that side). A
+        # '-t' target id does not resolve here and RF falls back to the top
+        # handle, so never emit one.
+        #   proxmox         → 'virtual' host→guest, vertical (bottom → top)
+        #   proxmox_cluster → 'cluster' host↔host, horizontal (right → left)
+        #   anything else   → 'iot' mesh link, vertical
+        if link.discovery_source == "proxmox":
+            edge_type, src_handle, tgt_handle = "virtual", "bottom", "top"
+        elif link.discovery_source == "proxmox_cluster":
+            edge_type, src_handle, tgt_handle = "cluster", "right", "left"
+        else:
+            edge_type, src_handle, tgt_handle = "iot", "bottom", "top"
         edge = Edge(
             source=src_id,
             target=tgt_id,
-            type="iot",
-            source_handle="bottom",
-            target_handle="top-t",
+            type=edge_type,
+            source_handle=src_handle,
+            target_handle=tgt_handle,
             design_id=edge_design_id,
         )
         db.add(edge)
         await db.flush()
         existing_pairs.add((src_id, tgt_id))
-        created.append({"id": edge.id, "source": src_id, "target": tgt_id})
-        await db.delete(link)
+        # Return the edge's type + handles so the client injects it faithfully
+        # (a cluster edge must keep its right→left handles, not the iot default).
+        created.append({
+            "id": edge.id,
+            "source": src_id,
+            "target": tgt_id,
+            "type": edge_type,
+            "source_handle": src_handle,
+            "target_handle": tgt_handle,
+        })
 
     return created
 
@@ -594,7 +845,7 @@ async def _resolve_pending_links_for_ieee(
 async def hide_device(
     device_id: str, db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)
 ) -> dict[str, bool]:
-    device = await db.get(PendingDevice, device_id)
+    device = await db.get(InventoryDevice, device_id)
     if not device:
         raise HTTPException(status_code=404, detail="Device not found")
     device.status = "hidden"
@@ -606,7 +857,7 @@ async def hide_device(
 async def ignore_device(
     device_id: str, db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)
 ) -> dict[str, bool]:
-    device = await db.get(PendingDevice, device_id)
+    device = await db.get(InventoryDevice, device_id)
     if not device:
         raise HTTPException(status_code=404, detail="Device not found")
     await db.delete(device)

backend/app/api/routes/stats.py

@@ -6,7 +6,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.config import settings
 from app.db.database import get_db
-from app.db.models import Node, PendingDevice, ScanRun
+from app.db.models import InventoryDevice, Node, ScanRun
 
 router = APIRouter()
 
@@ -38,8 +38,8 @@ async def summary(
     pending = (
         await db.execute(
             select(func.count())
-            .select_from(PendingDevice)
-            .where(PendingDevice.status == "pending")
+            .select_from(InventoryDevice)
+            .where(InventoryDevice.status == "pending")
         )
     ).scalar_one()
 
@@ -58,6 +58,8 @@ async def summary(
         "online": counts.get("online", 0),
         "offline": counts.get("offline", 0),
         "unknown": counts.get("unknown", 0),
+        # Wire key kept from before the table was renamed to `device_inventory`:
+        # the stats payload is a published contract, and the MCP server reads it.
         "pending_devices": pending,
         "zigbee_devices": zigbee,
         "last_scan_at": last_scan_at.isoformat() if last_scan_at else None,

backend/app/api/routes/status.py

@@ -3,7 +3,13 @@ import json
 
 from fastapi import APIRouter, WebSocket, WebSocketDisconnect
 
-from app.core.security import decode_token
+from app.core.config import settings
+from app.core.security import (
+    decode_oidc_session_token,
+    decode_token,
+    oidc_session_cookie_name,
+    origin_is_allowed,
+)
 
 router = APIRouter()
 
@@ -21,19 +27,29 @@ def _drop(websocket: WebSocket) -> None:
 async def ws_status(websocket: WebSocket) -> None:
     # Accept first so we can send a close frame with a reason code
     await websocket.accept()
-    try:
-        # Expect the first message to be a JSON auth payload: {"token": "<jwt>"}
-        raw = await websocket.receive_text()
-        try:
-            payload = json.loads(raw)
-            token = payload.get("token", "")
-        except (json.JSONDecodeError, AttributeError):
-            token = ""
-        if not token or not decode_token(token):
+    if not origin_is_allowed(websocket.headers.get("origin")):
+        await websocket.close(code=1008)  # Policy Violation
+        return
+
+    if settings.auth_mode == "oidc":
+        cookie_token = websocket.cookies.get(oidc_session_cookie_name(), "")
+        if not cookie_token or decode_oidc_session_token(cookie_token) is None:
             await websocket.close(code=1008)  # Policy Violation
             return
-    except WebSocketDisconnect:
-        return
+    else:
+        # Local mode keeps the existing first-message bearer protocol.
+        try:
+            raw = await websocket.receive_text()
+            try:
+                payload = json.loads(raw)
+                token = payload.get("token", "")
+            except (json.JSONDecodeError, AttributeError):
+                token = ""
+            if not token or not decode_token(token):
+                await websocket.close(code=1008)  # Policy Violation
+                return
+        except WebSocketDisconnect:
+            return
 
     _connections.append(websocket)
     try:

backend/app/api/routes/zigbee.py

@@ -10,19 +10,24 @@ from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.deps import get_current_user
+from app.core.config import settings
+from app.core.scheduler import reschedule_zigbee_sync, set_zigbee_sync_enabled
 from app.db.database import AsyncSessionLocal, get_db
-from app.db.models import Design, Node, PendingDevice, PendingDeviceLink, ScanRun
+from app.db.models import InventoryDevice, InventoryDeviceLink, Node, ScanRun
 from app.schemas.scan import ScanRunResponse
 from app.schemas.zigbee import (
+    ZigbeeConfig,
     ZigbeeCoordinatorOut,
     ZigbeeEdgeOut,
     ZigbeeImportPendingResponse,
     ZigbeeImportRequest,
     ZigbeeImportResponse,
     ZigbeeNodeOut,
+    ZigbeeSyncConfig,
     ZigbeeTestConnectionRequest,
     ZigbeeTestConnectionResponse,
 )
+from app.services.node_dedupe import dedupe_nodes_by_ieee
 from app.services.zigbee_service import (
     build_zigbee_properties,
     fetch_networkmap,
@@ -98,6 +103,53 @@ async def import_zigbee_to_pending(
     return run
 
 
+def env_import_request() -> ZigbeeImportRequest:
+    """Build an import request from the server env config (for auto-sync).
+
+    MQTT credentials live in the env only — never in the request body or any
+    API response. The scheduled auto-sync job and ``/sync-now`` both source
+    their connection settings here so there is a single source of truth."""
+    return ZigbeeImportRequest(
+        mqtt_host=settings.zigbee_mqtt_host,
+        mqtt_port=settings.zigbee_mqtt_port,
+        mqtt_username=settings.zigbee_mqtt_username or None,
+        mqtt_password=settings.zigbee_mqtt_password or None,
+        base_topic=settings.zigbee_base_topic,
+        mqtt_tls=settings.zigbee_mqtt_tls,
+        mqtt_tls_insecure=settings.zigbee_mqtt_tls_insecure,
+    )
+
+
+@router.post("/sync-now", response_model=ScanRunResponse)
+async def sync_zigbee_now(
+    background_tasks: BackgroundTasks,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> ScanRun:
+    """Trigger an immediate Zigbee import using the server env config.
+
+    Same background flow as ``/import-pending`` but sources the MQTT connection
+    from ``settings`` (env) rather than the request body — the manual
+    counterpart to the scheduled auto-sync job. Requires the env host to be set.
+    """
+    if not settings.zigbee_mqtt_host:
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot sync: no Zigbee MQTT host configured on the server.",
+        )
+    payload = env_import_request()
+    run = ScanRun(
+        status="running",
+        kind="zigbee",
+        ranges=[f"{payload.mqtt_host}:{payload.mqtt_port}"],
+    )
+    db.add(run)
+    await db.commit()
+    await db.refresh(run)
+    background_tasks.add_task(_background_zigbee_import, run.id, payload)
+    return run
+
+
 async def _background_zigbee_import(run_id: str, payload: ZigbeeImportRequest) -> None:
     async with AsyncSessionLocal() as db:
         try:
@@ -133,15 +185,17 @@ async def _persist_pending_import(
     nodes_raw: list[dict[str, Any]],
     edges_raw: list[dict[str, Any]],
 ) -> ZigbeeImportPendingResponse:
-    """Upsert nodes/edges into pending_devices + pending_device_links.
+    """Upsert nodes/edges into device_inventory + device_inventory_links.
 
     Coordinator auto-approves to a canvas Node. Other devices upsert by IEEE.
     All zigbee-source links are wiped and re-inserted from the new map.
     """
-    # Determine target design (use first design as fallback)
-    first_design = (await db.execute(select(Design).order_by(Design.created_at).limit(1))).scalar()
-    default_design_id = first_design.id if first_design else None
+    # Repair any pre-existing duplicate nodes (same IEEE) before upserting, so
+    # the by-IEEE lookups below resolve to a single row.
+    await dedupe_nodes_by_ieee(db)
 
+    # Coordinator is no longer auto-placed, so the response's coordinator fields
+    # stay unset — retained for backward-compatible response shape.
     coordinator_out: ZigbeeCoordinatorOut | None = None
     coordinator_existed = False
     pending_created = 0
@@ -155,58 +209,66 @@ async def _persist_pending_import(
             ieee, n.get("vendor"), n.get("model"), n.get("lqi")
         )
 
-        if n.get("device_type") == "Coordinator":
-            existing = await db.execute(select(Node).where(Node.ieee_address == ieee))
-            existing_node = existing.scalar_one_or_none()
-            if existing_node:
+        # The coordinator is no longer auto-placed on the canvas — it flows to
+        # the pending inventory like every other device, so the user approves it
+        # explicitly. Only the shared paths below run for it.
+
+        # If the device has already been approved as a canvas Node, refresh its
+        # properties on every canvas it sits on. Still ensure the discovery
+        # inventory carries a row for it (status="approved") so it shows in the
+        # inventory list with an "In N canvas" badge — legacy auto-placed
+        # coordinators never got a pending row, which is why they went missing.
+        existing_nodes = (
+            await db.execute(
+                select(Node).where(Node.ieee_address == ieee).order_by(Node.id)
+            )
+        ).scalars().all()
+        if existing_nodes:
+            for existing_node in existing_nodes:
                 existing_node.properties = merge_zigbee_properties(
                     existing_node.properties, props
                 )
-                coordinator_out = ZigbeeCoordinatorOut(
-                    id=existing_node.id,
-                    label=existing_node.label,
-                    ieee_address=ieee,
+            inv = (
+                await db.execute(
+                    select(InventoryDevice).where(InventoryDevice.ieee_address == ieee)
                 )
-                coordinator_existed = True
-                continue
-            label = n.get("friendly_name") or ieee
-            node = Node(
-                label=label,
-                type=n.get("type") or "zigbee_coordinator",
-                status="online",
-                check_method="none",
-                ieee_address=ieee,
-                services=[],
-                properties=props,
-                design_id=default_design_id,
-            )
-            db.add(node)
-            await db.flush()
-            coordinator_out = ZigbeeCoordinatorOut(
-                id=node.id, label=label, ieee_address=ieee
-            )
-            continue
-
-        # If the device has already been approved as a canvas Node, refresh
-        # its properties and skip creating a pending row (keeps approved
-        # devices out of pending/hidden modals on re-import).
-        existing_node_q = await db.execute(
-            select(Node).where(Node.ieee_address == ieee)
-        )
-        existing_node = existing_node_q.scalar_one_or_none()
-        if existing_node:
-            existing_node.properties = merge_zigbee_properties(
-                existing_node.properties, props
-            )
+            ).scalar_one_or_none()
+            if inv is None:
+                db.add(
+                    InventoryDevice(
+                        ieee_address=ieee,
+                        friendly_name=n.get("friendly_name"),
+                        hostname=n.get("friendly_name"),
+                        suggested_type=n.get("type"),
+                        device_subtype=n.get("device_type"),
+                        model=n.get("model"),
+                        vendor=n.get("vendor"),
+                        lqi=n.get("lqi"),
+                        status="approved",
+                        discovery_source="zigbee",
+                    )
+                )
+                pending_created += 1
+            else:
+                # Refresh metadata but never change the row's status (an approved
+                # device stays approved; a hidden one stays hidden).
+                inv.friendly_name = n.get("friendly_name") or inv.friendly_name
+                inv.suggested_type = n.get("type") or inv.suggested_type
+                inv.device_subtype = n.get("device_type") or inv.device_subtype
+                inv.model = n.get("model") or inv.model
+                inv.vendor = n.get("vendor") or inv.vendor
+                if n.get("lqi") is not None:
+                    inv.lqi = n.get("lqi")
+                pending_updated += 1
             continue
 
         result = await db.execute(
-            select(PendingDevice).where(PendingDevice.ieee_address == ieee)
+            select(InventoryDevice).where(InventoryDevice.ieee_address == ieee)
         )
         pending = result.scalar_one_or_none()
         if pending is None:
             db.add(
-                PendingDevice(
+                InventoryDevice(
                     ieee_address=ieee,
                     friendly_name=n.get("friendly_name"),
                     hostname=n.get("friendly_name"),
@@ -241,7 +303,7 @@ async def _persist_pending_import(
 
     # Replace all zigbee-source links with the freshly discovered set.
     await db.execute(
-        sa_delete(PendingDeviceLink).where(PendingDeviceLink.discovery_source == "zigbee")
+        sa_delete(InventoryDeviceLink).where(InventoryDeviceLink.discovery_source == "zigbee")
     )
 
     links_recorded = 0
@@ -253,7 +315,7 @@ async def _persist_pending_import(
             continue
         seen.add((src, tgt))
         db.add(
-            PendingDeviceLink(
+            InventoryDeviceLink(
                 source_ieee=src,
                 target_ieee=tgt,
                 discovery_source="zigbee",
@@ -296,3 +358,50 @@ async def test_zigbee_connection(
     except Exception:
         logger.exception("Unexpected error during connection test")
         return ZigbeeTestConnectionResponse(connected=False, message="Unexpected error")
+
+
+@router.get("/config", response_model=ZigbeeConfig)
+async def get_zigbee_config(_: str = Depends(get_current_user)) -> ZigbeeConfig:
+    """Return non-secret Zigbee config. Never includes MQTT credentials — only
+    whether a host is configured on the server for auto-sync."""
+    return ZigbeeConfig(
+        mqtt_host=settings.zigbee_mqtt_host,
+        mqtt_port=settings.zigbee_mqtt_port,
+        base_topic=settings.zigbee_base_topic,
+        mqtt_tls=settings.zigbee_mqtt_tls,
+        sync_enabled=settings.zigbee_sync_enabled,
+        sync_interval=settings.zigbee_sync_interval,
+        host_configured=bool(settings.zigbee_mqtt_host),
+    )
+
+
+@router.post("/config", response_model=ZigbeeConfig)
+async def save_zigbee_config(
+    payload: ZigbeeSyncConfig,
+    _: str = Depends(get_current_user),
+) -> ZigbeeConfig:
+    """Persist the auto-sync activation (enabled + interval) and apply it live.
+
+    This is the ONLY Zigbee config the app writes. Connection settings
+    (host/port/credentials/topic/tls) are env-only and are never accepted or
+    persisted here — enabling auto-sync requires the MQTT host already set in
+    the server env, since the scheduled job reads it from there.
+    """
+    if payload.sync_enabled and not settings.zigbee_mqtt_host:
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot enable auto-sync: no Zigbee MQTT host configured in the server env.",
+        )
+    try:
+        settings.zigbee_sync_enabled = payload.sync_enabled
+        settings.zigbee_sync_interval = payload.sync_interval
+        settings.save_overrides()
+        set_zigbee_sync_enabled(payload.sync_enabled)
+        if payload.sync_enabled:
+            reschedule_zigbee_sync(payload.sync_interval)
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    return await get_zigbee_config()

backend/app/api/routes/zwave.py

@@ -10,19 +10,24 @@ from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.deps import get_current_user
+from app.core.config import settings
+from app.core.scheduler import reschedule_zwave_sync, set_zwave_sync_enabled
 from app.db.database import AsyncSessionLocal, get_db
-from app.db.models import Design, Node, PendingDevice, PendingDeviceLink, ScanRun
+from app.db.models import InventoryDevice, InventoryDeviceLink, Node, ScanRun
 from app.schemas.scan import ScanRunResponse
 from app.schemas.zwave import (
+    ZwaveConfig,
     ZwaveCoordinatorOut,
     ZwaveEdgeOut,
     ZwaveImportPendingResponse,
     ZwaveImportRequest,
     ZwaveImportResponse,
     ZwaveNodeOut,
+    ZwaveSyncConfig,
     ZwaveTestConnectionRequest,
     ZwaveTestConnectionResponse,
 )
+from app.services.node_dedupe import dedupe_nodes_by_ieee
 from app.services.zwave_service import (
     build_zwave_properties,
     fetch_zwave_network,
@@ -93,6 +98,54 @@ async def import_zwave_to_pending(
     return run
 
 
+def env_import_request() -> ZwaveImportRequest:
+    """Build an import request from the server env config (for auto-sync).
+
+    MQTT credentials live in the env only — never in the request body or any
+    API response. The scheduled auto-sync job and ``/sync-now`` both source
+    their connection settings here so there is a single source of truth."""
+    return ZwaveImportRequest(
+        mqtt_host=settings.zwave_mqtt_host,
+        mqtt_port=settings.zwave_mqtt_port,
+        mqtt_username=settings.zwave_mqtt_username or None,
+        mqtt_password=settings.zwave_mqtt_password or None,
+        prefix=settings.zwave_prefix,
+        gateway_name=settings.zwave_gateway_name,
+        mqtt_tls=settings.zwave_mqtt_tls,
+        mqtt_tls_insecure=settings.zwave_mqtt_tls_insecure,
+    )
+
+
+@router.post("/sync-now", response_model=ScanRunResponse)
+async def sync_zwave_now(
+    background_tasks: BackgroundTasks,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> ScanRun:
+    """Trigger an immediate Z-Wave import using the server env config.
+
+    Same background flow as ``/import-pending`` but sources the MQTT connection
+    from ``settings`` (env) rather than the request body — the manual
+    counterpart to the scheduled auto-sync job. Requires the env host to be set.
+    """
+    if not settings.zwave_mqtt_host:
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot sync: no Z-Wave MQTT host configured on the server.",
+        )
+    payload = env_import_request()
+    run = ScanRun(
+        status="running",
+        kind="zwave",
+        ranges=[f"{payload.mqtt_host}:{payload.mqtt_port}"],
+    )
+    db.add(run)
+    await db.commit()
+    await db.refresh(run)
+    background_tasks.add_task(_background_zwave_import, run.id, payload)
+    return run
+
+
 async def _background_zwave_import(run_id: str, payload: ZwaveImportRequest) -> None:
     async with AsyncSessionLocal() as db:
         try:
@@ -129,14 +182,17 @@ async def _persist_pending_import(
     nodes_raw: list[dict[str, Any]],
     edges_raw: list[dict[str, Any]],
 ) -> ZwaveImportPendingResponse:
-    """Upsert nodes/edges into pending_devices + pending_device_links.
+    """Upsert nodes/edges into device_inventory + device_inventory_links.
 
     Coordinator auto-approves to a canvas Node. Other devices upsert by Z-Wave
     identity. All zwave-source links are wiped and re-inserted from the new map.
     """
-    first_design = (await db.execute(select(Design).order_by(Design.created_at).limit(1))).scalar()
-    default_design_id = first_design.id if first_design else None
+    # Repair any pre-existing same-canvas duplicate nodes before upserting, so
+    # the by-IEEE lookups below resolve cleanly.
+    await dedupe_nodes_by_ieee(db)
 
+    # Coordinator is no longer auto-placed, so the response's coordinator fields
+    # stay unset — retained for backward-compatible response shape.
     coordinator_out: ZwaveCoordinatorOut | None = None
     coordinator_existed = False
     pending_created = 0
@@ -148,56 +204,65 @@ async def _persist_pending_import(
             continue
         props = build_zwave_properties(ieee, n.get("vendor"), n.get("model"))
 
-        if n.get("type") == "zwave_coordinator":
-            existing = await db.execute(select(Node).where(Node.ieee_address == ieee))
-            existing_node = existing.scalar_one_or_none()
-            if existing_node:
+        # The coordinator is no longer auto-placed on the canvas — it flows to
+        # the pending inventory like every other device, so the user approves it
+        # explicitly. Only the shared paths below run for it.
+
+        # Already approved as a canvas Node → refresh props on every canvas it
+        # sits on. Still ensure the discovery inventory carries a row for it
+        # (status="approved") so it shows in the inventory list with an
+        # "In N canvas" badge — legacy auto-placed coordinators never got a
+        # pending row, which is why they went missing.
+        existing_nodes = (
+            await db.execute(
+                select(Node).where(Node.ieee_address == ieee).order_by(Node.id)
+            )
+        ).scalars().all()
+        if existing_nodes:
+            for existing_node in existing_nodes:
                 existing_node.properties = merge_zwave_properties(
                     existing_node.properties, props
                 )
-                coordinator_out = ZwaveCoordinatorOut(
-                    id=existing_node.id,
-                    label=existing_node.label,
-                    ieee_address=ieee,
+            inv = (
+                await db.execute(
+                    select(InventoryDevice).where(InventoryDevice.ieee_address == ieee)
                 )
-                coordinator_existed = True
-                continue
-            label = n.get("friendly_name") or ieee
-            node = Node(
-                label=label,
-                type=n.get("type") or "zwave_coordinator",
-                status="online",
-                check_method="none",
-                ieee_address=ieee,
-                services=[],
-                properties=props,
-                design_id=default_design_id,
-            )
-            db.add(node)
-            await db.flush()
-            coordinator_out = ZwaveCoordinatorOut(
-                id=node.id, label=label, ieee_address=ieee
-            )
-            continue
-
-        # Already approved as a canvas Node → refresh props, skip pending row.
-        existing_node_q = await db.execute(
-            select(Node).where(Node.ieee_address == ieee)
-        )
-        existing_node = existing_node_q.scalar_one_or_none()
-        if existing_node:
-            existing_node.properties = merge_zwave_properties(
-                existing_node.properties, props
-            )
+            ).scalar_one_or_none()
+            if inv is None:
+                db.add(
+                    InventoryDevice(
+                        ieee_address=ieee,
+                        friendly_name=n.get("friendly_name"),
+                        hostname=n.get("friendly_name"),
+                        suggested_type=n.get("type"),
+                        device_subtype=n.get("device_type"),
+                        model=n.get("model"),
+                        vendor=n.get("vendor"),
+                        lqi=n.get("lqi"),
+                        status="approved",
+                        discovery_source="zwave",
+                    )
+                )
+                pending_created += 1
+            else:
+                # Refresh metadata but never change the row's status.
+                inv.friendly_name = n.get("friendly_name") or inv.friendly_name
+                inv.suggested_type = n.get("type") or inv.suggested_type
+                inv.device_subtype = n.get("device_type") or inv.device_subtype
+                inv.model = n.get("model") or inv.model
+                inv.vendor = n.get("vendor") or inv.vendor
+                if n.get("lqi") is not None:
+                    inv.lqi = n.get("lqi")
+                pending_updated += 1
             continue
 
         result = await db.execute(
-            select(PendingDevice).where(PendingDevice.ieee_address == ieee)
+            select(InventoryDevice).where(InventoryDevice.ieee_address == ieee)
         )
         pending = result.scalar_one_or_none()
         if pending is None:
             db.add(
-                PendingDevice(
+                InventoryDevice(
                     ieee_address=ieee,
                     friendly_name=n.get("friendly_name"),
                     hostname=n.get("friendly_name"),
@@ -227,7 +292,7 @@ async def _persist_pending_import(
 
     # Replace all zwave-source links with the freshly discovered set.
     await db.execute(
-        sa_delete(PendingDeviceLink).where(PendingDeviceLink.discovery_source == "zwave")
+        sa_delete(InventoryDeviceLink).where(InventoryDeviceLink.discovery_source == "zwave")
     )
 
     links_recorded = 0
@@ -239,7 +304,7 @@ async def _persist_pending_import(
             continue
         seen.add((src, tgt))
         db.add(
-            PendingDeviceLink(
+            InventoryDeviceLink(
                 source_ieee=src,
                 target_ieee=tgt,
                 discovery_source="zwave",
@@ -282,3 +347,51 @@ async def test_connection_endpoint(
     except Exception:
         logger.exception("Unexpected error during connection test")
         return ZwaveTestConnectionResponse(connected=False, message="Unexpected error")
+
+
+@router.get("/config", response_model=ZwaveConfig)
+async def get_zwave_config(_: str = Depends(get_current_user)) -> ZwaveConfig:
+    """Return non-secret Z-Wave config. Never includes MQTT credentials — only
+    whether a host is configured on the server for auto-sync."""
+    return ZwaveConfig(
+        mqtt_host=settings.zwave_mqtt_host,
+        mqtt_port=settings.zwave_mqtt_port,
+        prefix=settings.zwave_prefix,
+        gateway_name=settings.zwave_gateway_name,
+        mqtt_tls=settings.zwave_mqtt_tls,
+        sync_enabled=settings.zwave_sync_enabled,
+        sync_interval=settings.zwave_sync_interval,
+        host_configured=bool(settings.zwave_mqtt_host),
+    )
+
+
+@router.post("/config", response_model=ZwaveConfig)
+async def save_zwave_config(
+    payload: ZwaveSyncConfig,
+    _: str = Depends(get_current_user),
+) -> ZwaveConfig:
+    """Persist the auto-sync activation (enabled + interval) and apply it live.
+
+    This is the ONLY Z-Wave config the app writes. Connection settings
+    (host/port/credentials/prefix/gateway/tls) are env-only and are never
+    accepted or persisted here — enabling auto-sync requires the MQTT host
+    already set in the server env, since the scheduled job reads it from there.
+    """
+    if payload.sync_enabled and not settings.zwave_mqtt_host:
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot enable auto-sync: no Z-Wave MQTT host configured in the server env.",
+        )
+    try:
+        settings.zwave_sync_enabled = payload.sync_enabled
+        settings.zwave_sync_interval = payload.sync_interval
+        settings.save_overrides()
+        set_zwave_sync_enabled(payload.sync_enabled)
+        if payload.sync_enabled:
+            reschedule_zwave_sync(payload.sync_interval)
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    return await get_zwave_config()

backend/app/core/config.py

@@ -1,8 +1,9 @@
 import json
 import logging
 from pathlib import Path
+from typing import Literal
 
-from pydantic import model_validator
+from pydantic import Field, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 logger = logging.getLogger(__name__)
@@ -24,6 +25,10 @@ class Settings(BaseSettings):
 
     secret_key: str  # Required — set SECRET_KEY in .env
     sqlite_path: str = "./data/homelab.db"
+    # Uploaded media (floor plans, and future raw image uploads) live on disk,
+    # not in the DB. Defaults to a `uploads/` folder next to the SQLite DB so it
+    # sits on the same persistent Docker volume. Override with UPLOAD_DIR.
+    upload_dir: str = ""
     cors_origins: list[str] = ["http://localhost:5173", "http://localhost:3000"]
 
     # JWT
@@ -31,11 +36,22 @@ class Settings(BaseSettings):
     access_token_expire_minutes: int = 1440  # 24h
 
     # Auth — set AUTH_USERNAME and AUTH_PASSWORD_HASH in .env
+    auth_mode: Literal["local", "oidc"] = "local"
     auth_username: str = "admin"
     auth_password_hash: str = ""
 
+    # OpenID Connect — required only when AUTH_MODE=oidc.
+    oidc_discovery_url: str = ""
+    oidc_client_id: str = ""
+    oidc_client_secret: str = ""
+    oidc_redirect_uri: str = ""
+    oidc_scopes: str = "openid profile email"
+    oidc_cookie_secure: bool = True
+    oidc_session_expire_minutes: int = Field(default=480, ge=5, le=1440)
+    oidc_transaction_expire_seconds: int = Field(default=600, ge=60, le=3600)
+
     @model_validator(mode="after")
-    def check_password_hash(self) -> "Settings":
+    def validate_auth_settings(self) -> "Settings":
         h = self.auth_password_hash
         if h and not h.startswith("$2"):
             logger.error(
@@ -43,11 +59,45 @@ class Settings(BaseSettings):
                 "bcrypt hashes contain '$' signs — wrap the value in single quotes "
                 "in your .env file: AUTH_PASSWORD_HASH='$2b$12$...'"
             )
+        if self.auth_mode == "oidc":
+            required = {
+                "OIDC_DISCOVERY_URL": self.oidc_discovery_url,
+                "OIDC_CLIENT_ID": self.oidc_client_id,
+                "OIDC_CLIENT_SECRET": self.oidc_client_secret,
+                "OIDC_REDIRECT_URI": self.oidc_redirect_uri,
+            }
+            missing = [name for name, value in required.items() if not value]
+            if missing:
+                raise ValueError(f"AUTH_MODE=oidc requires: {', '.join(missing)}")
+            if len(self.secret_key.encode("utf-8")) < 32:
+                raise ValueError("SECRET_KEY must be at least 32 bytes when AUTH_MODE=oidc")
+            if "openid" not in self.oidc_scopes.split():
+                raise ValueError("OIDC_SCOPES must contain 'openid'")
+            for name, value in {
+                "OIDC_DISCOVERY_URL": self.oidc_discovery_url,
+                "OIDC_REDIRECT_URI": self.oidc_redirect_uri,
+            }.items():
+                if not value.startswith(("https://", "http://")):
+                    raise ValueError(f"{name} must be an HTTP(S) URL")
+            if self.oidc_cookie_secure:
+                for name, value in {
+                    "OIDC_DISCOVERY_URL": self.oidc_discovery_url,
+                    "OIDC_REDIRECT_URI": self.oidc_redirect_uri,
+                }.items():
+                    if not value.startswith("https://"):
+                        raise ValueError(f"{name} must use HTTPS when OIDC_COOKIE_SECURE=true")
+            if "*" in self.cors_origins:
+                raise ValueError("CORS_ORIGINS cannot contain '*' when AUTH_MODE=oidc")
         return self
 
     # Scanner
     scanner_ranges: list[str] = ["192.168.1.0/24"]
 
+    # Phase-2 version-detection (-sV) host timeout, seconds. Bounds the version
+    # pass so a stalling TLS port (e.g. Proxmox 8006) can't hang it. Discovered
+    # ports survive a timeout regardless; raise this on slow/overlay networks.
+    scanner_version_host_timeout: int = 60
+
     # Deep scan — persisted defaults (overridable per-scan from the scan dialog).
     # http_ranges: extra nmap port ranges, opt-in, no default. Probe + TLS off by default.
     scanner_http_ranges: list[str] = []
@@ -76,9 +126,55 @@ class Settings(BaseSettings):
     # Leave empty to keep the feature disabled (default).
     homepage_api_key: str = ""
 
+    # Proxmox VE import.
+    # Token = a real credential → env/.env ONLY, never persisted by the app to
+    # scan_config.json and never returned by the API. token_id is
+    # 'user@realm!tokenname'; use a read-only PVEAuditor role.
+    proxmox_token_id: str = ""
+    proxmox_token_secret: str = ""
+    # Non-secret connection + auto-sync config (persisted via save_overrides).
+    proxmox_host: str = ""
+    proxmox_port: int = 8006
+    proxmox_verify_tls: bool = True
+    proxmox_sync_enabled: bool = False
+    proxmox_sync_interval: int = 3600  # seconds (floor 300 enforced on write)
+
+    # Zigbee2MQTT auto-sync import.
+    # MQTT credentials are secrets → env/.env ONLY, never persisted by the app to
+    # scan_config.json and never returned by the API. Only the auto-sync
+    # activation (enabled + interval) is persisted; connection config is env-only.
+    zigbee_mqtt_host: str = ""
+    zigbee_mqtt_port: int = 1883
+    zigbee_mqtt_username: str = ""
+    zigbee_mqtt_password: str = ""
+    zigbee_base_topic: str = "zigbee2mqtt"
+    zigbee_mqtt_tls: bool = False
+    zigbee_mqtt_tls_insecure: bool = False
+    zigbee_sync_enabled: bool = False
+    zigbee_sync_interval: int = 3600  # seconds (floor 300 enforced on write)
+
+    # Z-Wave JS UI (zwavejs2mqtt) auto-sync import. Same secret/env rules.
+    zwave_mqtt_host: str = ""
+    zwave_mqtt_port: int = 1883
+    zwave_mqtt_username: str = ""
+    zwave_mqtt_password: str = ""
+    zwave_prefix: str = "zwave"
+    zwave_gateway_name: str = "zwavejs2mqtt"
+    zwave_mqtt_tls: bool = False
+    zwave_mqtt_tls_insecure: bool = False
+    zwave_sync_enabled: bool = False
+    zwave_sync_interval: int = 3600  # seconds (floor 300 enforced on write)
+
     def _override_path(self) -> Path:
         return Path(self.sqlite_path).parent / "scan_config.json"
 
+    def media_dir(self) -> Path:
+        """On-disk folder for uploaded media. Sits on the same persistent
+        volume as the SQLite DB unless UPLOAD_DIR is set."""
+        if self.upload_dir:
+            return Path(self.upload_dir)
+        return Path(self.sqlite_path).parent / "uploads"
+
     def load_overrides(self) -> None:
         """Load runtime scan config overrides written by the API."""
         try:
@@ -97,6 +193,25 @@ class Settings(BaseSettings):
                 self.scanner_http_probe_enabled = bool(data["scanner_http_probe_enabled"])
             if "scanner_http_verify_tls" in data:
                 self.scanner_http_verify_tls = bool(data["scanner_http_verify_tls"])
+            # Proxmox auto-sync activation only. Connection config (host, port,
+            # token, verify_tls) is env-only by design — never read from or
+            # written to this file. Persisting host here previously created a
+            # dual source of truth that silently clobbered PROXMOX_HOST.
+            if "proxmox_sync_enabled" in data:
+                self.proxmox_sync_enabled = bool(data["proxmox_sync_enabled"])
+            if "proxmox_sync_interval" in data:
+                self.proxmox_sync_interval = int(data["proxmox_sync_interval"])
+            # Zigbee/Z-Wave: only the auto-sync activation is persisted. MQTT
+            # connection config (host, port, credentials, topic, tls) is env-only
+            # by design — never read from or written to this file.
+            if "zigbee_sync_enabled" in data:
+                self.zigbee_sync_enabled = bool(data["zigbee_sync_enabled"])
+            if "zigbee_sync_interval" in data:
+                self.zigbee_sync_interval = int(data["zigbee_sync_interval"])
+            if "zwave_sync_enabled" in data:
+                self.zwave_sync_enabled = bool(data["zwave_sync_enabled"])
+            if "zwave_sync_interval" in data:
+                self.zwave_sync_interval = int(data["zwave_sync_interval"])
         except Exception:
             pass
 
@@ -111,6 +226,17 @@ class Settings(BaseSettings):
             "scanner_http_ranges": self.scanner_http_ranges,
             "scanner_http_probe_enabled": self.scanner_http_probe_enabled,
             "scanner_http_verify_tls": self.scanner_http_verify_tls,
+            # Proxmox: only the auto-sync activation is persisted. Connection
+            # config (host, port, token, verify_tls) is env-only and must never
+            # be written to disk — that is the single source of truth.
+            "proxmox_sync_enabled": self.proxmox_sync_enabled,
+            "proxmox_sync_interval": self.proxmox_sync_interval,
+            # Zigbee/Z-Wave: only the auto-sync activation is persisted. MQTT
+            # connection config (host/port/credentials/topic/tls) is env-only.
+            "zigbee_sync_enabled": self.zigbee_sync_enabled,
+            "zigbee_sync_interval": self.zigbee_sync_interval,
+            "zwave_sync_enabled": self.zwave_sync_enabled,
+            "zwave_sync_interval": self.zwave_sync_interval,
         }))
 
 

backend/app/core/scheduler.py

@@ -1,7 +1,9 @@
 """APScheduler setup for background scan and status check jobs."""
 import asyncio
 import logging
+from collections.abc import Awaitable, Callable
 from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
 
 from apscheduler.schedulers.asyncio import AsyncIOScheduler
 from sqlalchemy import select
@@ -11,6 +13,10 @@ from app.db.database import AsyncSessionLocal
 from app.db.models import Node
 from app.services.status_checker import check_node, check_services
 
+if TYPE_CHECKING:
+    from app.schemas.zigbee import ZigbeeImportRequest
+    from app.schemas.zwave import ZwaveImportRequest
+
 logger = logging.getLogger(__name__)
 
 scheduler: AsyncIOScheduler = AsyncIOScheduler()
@@ -106,6 +112,97 @@ async def _run_service_checks() -> None:
             logger.error("Service checks failed for node %s: %s", node_id, exc)
 
 
+async def _run_proxmox_sync() -> None:
+    """Fetch the Proxmox inventory and upsert it into pending (auto-sync).
+
+    Records a ScanRun (kind=proxmox) so the scheduled sync shows in Scan
+    history, exactly like the manual /sync-now and /import-pending paths.
+    """
+    if not settings.proxmox_sync_enabled:
+        return
+    if not (settings.proxmox_host and settings.proxmox_token_id and settings.proxmox_token_secret):
+        logger.warning("Proxmox auto-sync enabled but host/token not configured — skipping")
+        return
+    # Lazy import to avoid a circular import at module load.
+    from app.api.routes.proxmox import _background_proxmox_import
+    from app.db.models import ScanRun
+
+    async with AsyncSessionLocal() as db:
+        run = ScanRun(
+            status="running",
+            kind="proxmox",
+            ranges=[f"{settings.proxmox_host}:{settings.proxmox_port}"],
+        )
+        db.add(run)
+        await db.commit()
+        await db.refresh(run)
+        run_id = run.id
+
+    # Shares the manual-sync flow: fetch + persist + mark the run done/error +
+    # broadcast the inventory-reload signal.
+    await _background_proxmox_import(
+        run_id,
+        settings.proxmox_host,
+        settings.proxmox_port,
+        settings.proxmox_token_id,
+        settings.proxmox_token_secret,
+        settings.proxmox_verify_tls,
+    )
+
+
+async def _run_mesh_sync(kind: str) -> None:
+    """Shared auto-sync for the MQTT mesh imports (Zigbee / Z-Wave).
+
+    Records a ScanRun (kind=zigbee|zwave) so the scheduled sync shows in Scan
+    history, then delegates to the exact same background import the manual
+    /sync-now and /import-pending paths use. Connection config comes from the
+    server env only (credentials never leave it).
+    """
+    from app.db.models import ScanRun
+
+    payload: ZigbeeImportRequest | ZwaveImportRequest
+    background: Callable[[str, Any], Awaitable[None]]
+
+    if kind == "zigbee":
+        if not settings.zigbee_sync_enabled:
+            return
+        if not settings.zigbee_mqtt_host:
+            logger.warning("Zigbee auto-sync enabled but MQTT host not configured — skipping")
+            return
+        from app.api.routes.zigbee import _background_zigbee_import
+        from app.api.routes.zigbee import env_import_request as _zigbee_env_request
+        host, port = settings.zigbee_mqtt_host, settings.zigbee_mqtt_port
+        payload = _zigbee_env_request()
+        background = _background_zigbee_import
+    else:
+        if not settings.zwave_sync_enabled:
+            return
+        if not settings.zwave_mqtt_host:
+            logger.warning("Z-Wave auto-sync enabled but MQTT host not configured — skipping")
+            return
+        from app.api.routes.zwave import _background_zwave_import
+        from app.api.routes.zwave import env_import_request as _zwave_env_request
+        host, port = settings.zwave_mqtt_host, settings.zwave_mqtt_port
+        payload = _zwave_env_request()
+        background = _background_zwave_import
+    async with AsyncSessionLocal() as db:
+        run = ScanRun(status="running", kind=kind, ranges=[f"{host}:{port}"])
+        db.add(run)
+        await db.commit()
+        await db.refresh(run)
+        run_id = run.id
+
+    await background(run_id, payload)
+
+
+async def _run_zigbee_sync() -> None:
+    await _run_mesh_sync("zigbee")
+
+
+async def _run_zwave_sync() -> None:
+    await _run_mesh_sync("zwave")
+
+
 def _add_service_check_job() -> None:
     scheduler.add_job(
         _run_service_checks,
@@ -117,6 +214,39 @@ def _add_service_check_job() -> None:
     )
 
 
+def _add_proxmox_sync_job() -> None:
+    scheduler.add_job(
+        _run_proxmox_sync,
+        "interval",
+        seconds=settings.proxmox_sync_interval,
+        id="proxmox_sync",
+        max_instances=1,
+        coalesce=True,
+    )
+
+
+def _add_zigbee_sync_job() -> None:
+    scheduler.add_job(
+        _run_zigbee_sync,
+        "interval",
+        seconds=settings.zigbee_sync_interval,
+        id="zigbee_sync",
+        max_instances=1,
+        coalesce=True,
+    )
+
+
+def _add_zwave_sync_job() -> None:
+    scheduler.add_job(
+        _run_zwave_sync,
+        "interval",
+        seconds=settings.zwave_sync_interval,
+        id="zwave_sync",
+        max_instances=1,
+        coalesce=True,
+    )
+
+
 def start_scheduler() -> None:
     global scheduler
     if scheduler.running:
@@ -135,6 +265,12 @@ def start_scheduler() -> None:
     )
     if settings.service_check_enabled:
         _add_service_check_job()
+    if settings.proxmox_sync_enabled:
+        _add_proxmox_sync_job()
+    if settings.zigbee_sync_enabled:
+        _add_zigbee_sync_job()
+    if settings.zwave_sync_enabled:
+        _add_zwave_sync_job()
     scheduler.start()
     logger.info("Scheduler started — status checks every %ds", settings.status_checker_interval)
 
@@ -175,6 +311,81 @@ def set_service_checks_enabled(enabled: bool) -> None:
         logger.info("Service checks disabled")
 
 
+def reschedule_proxmox_sync(interval_seconds: int) -> None:
+    """Update the Proxmox auto-sync interval on the running scheduler (if enabled)."""
+    if interval_seconds < 300:
+        raise ValueError(f"interval_seconds must be >= 300, got {interval_seconds}")
+    if not scheduler.running:
+        logger.warning("Scheduler not running, skipping reschedule")
+        return
+    if scheduler.get_job("proxmox_sync"):
+        scheduler.reschedule_job("proxmox_sync", trigger="interval", seconds=interval_seconds)
+        logger.info("Proxmox auto-sync rescheduled to every %ds", interval_seconds)
+
+
+def set_proxmox_sync_enabled(enabled: bool) -> None:
+    """Add or remove the Proxmox auto-sync job on the running scheduler."""
+    if not scheduler.running:
+        return
+    job = scheduler.get_job("proxmox_sync")
+    if enabled and not job:
+        _add_proxmox_sync_job()
+        logger.info("Proxmox auto-sync enabled — every %ds", settings.proxmox_sync_interval)
+    elif not enabled and job:
+        scheduler.remove_job("proxmox_sync")
+        logger.info("Proxmox auto-sync disabled")
+
+
+def reschedule_zigbee_sync(interval_seconds: int) -> None:
+    """Update the Zigbee auto-sync interval on the running scheduler (if enabled)."""
+    if interval_seconds < 300:
+        raise ValueError(f"interval_seconds must be >= 300, got {interval_seconds}")
+    if not scheduler.running:
+        logger.warning("Scheduler not running, skipping reschedule")
+        return
+    if scheduler.get_job("zigbee_sync"):
+        scheduler.reschedule_job("zigbee_sync", trigger="interval", seconds=interval_seconds)
+        logger.info("Zigbee auto-sync rescheduled to every %ds", interval_seconds)
+
+
+def set_zigbee_sync_enabled(enabled: bool) -> None:
+    """Add or remove the Zigbee auto-sync job on the running scheduler."""
+    if not scheduler.running:
+        return
+    job = scheduler.get_job("zigbee_sync")
+    if enabled and not job:
+        _add_zigbee_sync_job()
+        logger.info("Zigbee auto-sync enabled — every %ds", settings.zigbee_sync_interval)
+    elif not enabled and job:
+        scheduler.remove_job("zigbee_sync")
+        logger.info("Zigbee auto-sync disabled")
+
+
+def reschedule_zwave_sync(interval_seconds: int) -> None:
+    """Update the Z-Wave auto-sync interval on the running scheduler (if enabled)."""
+    if interval_seconds < 300:
+        raise ValueError(f"interval_seconds must be >= 300, got {interval_seconds}")
+    if not scheduler.running:
+        logger.warning("Scheduler not running, skipping reschedule")
+        return
+    if scheduler.get_job("zwave_sync"):
+        scheduler.reschedule_job("zwave_sync", trigger="interval", seconds=interval_seconds)
+        logger.info("Z-Wave auto-sync rescheduled to every %ds", interval_seconds)
+
+
+def set_zwave_sync_enabled(enabled: bool) -> None:
+    """Add or remove the Z-Wave auto-sync job on the running scheduler."""
+    if not scheduler.running:
+        return
+    job = scheduler.get_job("zwave_sync")
+    if enabled and not job:
+        _add_zwave_sync_job()
+        logger.info("Z-Wave auto-sync enabled — every %ds", settings.zwave_sync_interval)
+    elif not enabled and job:
+        scheduler.remove_job("zwave_sync")
+        logger.info("Z-Wave auto-sync disabled")
+
+
 def stop_scheduler() -> None:
     if scheduler.running:
         scheduler.shutdown(wait=False)

backend/app/core/security.py

@@ -1,10 +1,33 @@
+import hmac
+import secrets
+from collections.abc import Mapping
+from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
+from functools import lru_cache
+from typing import Any
 
 import bcrypt
-from jose import JWTError, jwt
+import jwt
+from authlib.integrations.starlette_client import OAuth, StarletteOAuth2App
+from fastapi import Request, Response, status
+from jwt import InvalidTokenError
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.responses import JSONResponse
 
 from app.core.config import settings
 
+ACCESS_TOKEN_USE = "access"
+OIDC_SESSION_TOKEN_USE = "oidc_session"
+SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "TRACE"})
+
+
+@dataclass(frozen=True)
+class OIDCSession:
+    subject: str
+    issuer: str
+    display_name: str
+    csrf_token: str
+
 
 def verify_password(plain: str, hashed: str) -> bool:
     if not plain or not hashed:
@@ -21,14 +44,169 @@ def hash_password(password: str) -> str:
 
 def create_access_token(subject: str) -> str:
     expire = datetime.now(timezone.utc) + timedelta(minutes=settings.access_token_expire_minutes)
-    payload = {"sub": subject, "exp": expire}
+    payload = {"sub": subject, "exp": expire, "token_use": ACCESS_TOKEN_USE}
     return str(jwt.encode(payload, settings.secret_key, algorithm=settings.algorithm))
 
 
 def decode_token(token: str) -> str | None:
     try:
         payload = jwt.decode(token, settings.secret_key, algorithms=[settings.algorithm])
+        if payload.get("token_use") not in (None, ACCESS_TOKEN_USE):
+            return None
         sub = payload.get("sub")
         return str(sub) if sub is not None else None
-    except JWTError:
+    except InvalidTokenError:
         return None
+
+
+def create_oidc_session_token(userinfo: Mapping[str, Any]) -> str:
+    subject = userinfo.get("sub")
+    issuer = userinfo.get("iss")
+    if not isinstance(subject, str) or not subject or not isinstance(issuer, str) or not issuer:
+        raise ValueError("OIDC userinfo must contain non-empty 'sub' and 'iss' claims")
+
+    display_name = next(
+        (
+            value
+            for value in (
+                userinfo.get("preferred_username"),
+                userinfo.get("name"),
+                userinfo.get("email"),
+                subject,
+            )
+            if isinstance(value, str) and value
+        ),
+        subject,
+    )
+    now = datetime.now(timezone.utc)
+    payload = {
+        "sub": subject,
+        "oidc_issuer": issuer,
+        "name": display_name,
+        "csrf": secrets.token_urlsafe(32),
+        "iat": now,
+        "exp": now + timedelta(minutes=settings.oidc_session_expire_minutes),
+        "token_use": OIDC_SESSION_TOKEN_USE,
+    }
+    return str(jwt.encode(payload, settings.secret_key, algorithm=settings.algorithm))
+
+
+def decode_oidc_session_token(token: str) -> OIDCSession | None:
+    try:
+        payload = jwt.decode(token, settings.secret_key, algorithms=[settings.algorithm])
+        if payload.get("token_use") != OIDC_SESSION_TOKEN_USE:
+            return None
+        subject = payload.get("sub")
+        issuer = payload.get("oidc_issuer")
+        display_name = payload.get("name")
+        csrf_token = payload.get("csrf")
+        if not isinstance(subject, str) or not subject:
+            return None
+        if not isinstance(issuer, str) or not issuer:
+            return None
+        if not isinstance(display_name, str) or not display_name:
+            return None
+        if not isinstance(csrf_token, str) or not csrf_token:
+            return None
+        return OIDCSession(
+            subject=subject,
+            issuer=issuer,
+            display_name=display_name,
+            csrf_token=csrf_token,
+        )
+    except InvalidTokenError:
+        return None
+
+
+def oidc_session_cookie_name() -> str:
+    return "__Host-homelable-session" if settings.oidc_cookie_secure else "homelable-session"
+
+
+def set_oidc_session_cookie(response: Response, token: str) -> None:
+    response.set_cookie(
+        key=oidc_session_cookie_name(),
+        value=token,
+        max_age=settings.oidc_session_expire_minutes * 60,
+        secure=settings.oidc_cookie_secure,
+        httponly=True,
+        samesite="lax",
+        path="/",
+    )
+
+
+def clear_oidc_session_cookie(response: Response) -> None:
+    response.delete_cookie(
+        key=oidc_session_cookie_name(),
+        secure=settings.oidc_cookie_secure,
+        httponly=True,
+        samesite="lax",
+        path="/",
+    )
+
+
+def get_oidc_session(request: Request) -> OIDCSession | None:
+    token = request.cookies.get(oidc_session_cookie_name())
+    return decode_oidc_session_token(token) if token else None
+
+
+def origin_is_allowed(origin: str | None) -> bool:
+    if not origin:
+        return False
+    allowed_origins = {value.rstrip("/") for value in settings.cors_origins}
+    return origin.rstrip("/") in allowed_origins
+
+
+class OIDCCSRFMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        if settings.auth_mode != "oidc" or request.method in SAFE_METHODS:
+            return await call_next(request)
+
+        # Explicit non-cookie credentials take precedence in get_current_user,
+        # so their requests keep the existing CSRF-free API behavior.
+        if request.headers.get("Authorization") or request.headers.get("X-MCP-Service-Key"):
+            return await call_next(request)
+
+        oidc_session = get_oidc_session(request)
+        if oidc_session is None:
+            return await call_next(request)
+
+        csrf_token = request.headers.get("X-Homelable-CSRF", "")
+        csrf_valid = hmac.compare_digest(csrf_token.encode(), oidc_session.csrf_token.encode())
+        if not csrf_valid or not origin_is_allowed(request.headers.get("Origin")):
+            return JSONResponse(
+                status_code=status.HTTP_403_FORBIDDEN,
+                content={"detail": "CSRF validation failed"},
+            )
+        return await call_next(request)
+
+
+@lru_cache(maxsize=8)
+def _build_oidc_client(
+    discovery_url: str,
+    client_id: str,
+    client_secret: str,
+    scopes: str,
+) -> StarletteOAuth2App:
+    oauth = OAuth()
+    client = oauth.register(
+        name="oidc",
+        client_id=client_id,
+        client_secret=client_secret,
+        server_metadata_url=discovery_url,
+        client_kwargs={
+            "scope": scopes,
+            "code_challenge_method": "S256",
+        },
+    )
+    if client is None:
+        raise RuntimeError("Failed to register OIDC client")
+    return client
+
+
+def get_oidc_client() -> StarletteOAuth2App:
+    return _build_oidc_client(
+        settings.oidc_discovery_url,
+        settings.oidc_client_id,
+        settings.oidc_client_secret,
+        settings.oidc_scopes,
+    )

backend/app/db/database.py

@@ -60,9 +60,67 @@ def _backup_db() -> None:
         logger.warning("Could not create DB backup at %s", backup_path)
 
 
+# Tables renamed in 3.2.0. "Pending devices" was the scanner's word for a queue
+# of finds awaiting approval; the same rows outlive approval, are edited by hand
+# and are what a rack mounts, so the product calls them the Device Inventory.
+# Only the names moved — every column, every row and every route is unchanged.
+_RENAMED_TABLES: list[tuple[str, str]] = [
+    ("pending_devices", "device_inventory"),
+    ("pending_device_links", "device_inventory_links"),
+]
+
+
+async def _rename_legacy_tables(conn: AsyncConnection) -> None:
+    """Rename the pre-3.2.0 inventory tables. Must run before `create_all`.
+
+    Order matters: `create_all` would otherwise create an empty
+    `device_inventory` beside the populated `pending_devices`, and every device
+    the user ever scanned would look lost.
+
+    Foreign keys are switched on for the rename so SQLite rewrites the
+    ``REFERENCES pending_devices`` clause in `rack_devices` too; enforcement is
+    off at runtime, so a missed rewrite costs nothing today, but it would leave
+    the schema naming a table that no longer exists.
+    """
+    for old, new in _RENAMED_TABLES:
+        rows = (
+            await conn.exec_driver_sql(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name IN (?, ?)",
+                (old, new),
+            )
+        ).fetchall()
+        names = {r[0] for r in rows}
+        if old not in names:
+            continue  # Fresh install, or already migrated.
+        if new in names:
+            # A start that ran `create_all` before this migration existed left an
+            # empty new table beside the populated old one, and the app read the
+            # empty one. Clear it out of the way rather than stranding the data;
+            # a new table with rows in it means the rename already happened and
+            # something re-created the old one, which is not ours to resolve.
+            count = (await conn.exec_driver_sql(f"SELECT COUNT(*) FROM {new}")).scalar()
+            if count:
+                logger.warning(
+                    "Both %s and %s hold rows; leaving them alone. Merge them by hand.", old, new
+                )
+                continue
+            logger.info("Dropping the empty %s left by an earlier start", new)
+            await _try_migrate(conn, f"DROP TABLE {new}", label=f"{new}.drop_empty")
+        logger.info("Migrating table %s -> %s", old, new)
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("PRAGMA foreign_keys = ON")
+        await _try_migrate(conn, f"ALTER TABLE {old} RENAME TO {new}", label=f"{new}.rename")
+    # The index rides the rename under its old name; the model asks for the new
+    # one, so drop the stale duplicate rather than carrying both.
+    await _try_migrate(
+        conn, "DROP INDEX IF EXISTS ix_pending_devices_ieee_address", label="device_inventory.index",
+    )
+
+
 async def init_db() -> None:
     _backup_db()
     async with engine.begin() as conn:
+        await _rename_legacy_tables(conn)
         await conn.run_sync(Base.metadata.create_all)
         # Add columns introduced after initial schema (idempotent)
         with suppress(OperationalError):
@@ -81,6 +139,14 @@ async def init_db() -> None:
             await conn.exec_driver_sql("ALTER TABLE edges ADD COLUMN target_handle TEXT")
         with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE edges ADD COLUMN animated BOOLEAN NOT NULL DEFAULT 0")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE edges ADD COLUMN marker_start TEXT NOT NULL DEFAULT 'none'")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE edges ADD COLUMN marker_end TEXT NOT NULL DEFAULT 'none'")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE edges ADD COLUMN line_style TEXT")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE edges ADD COLUMN width_mult REAL")
         with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN cpu_count INTEGER")
         with suppress(OperationalError):
@@ -100,7 +166,17 @@ async def init_db() -> None:
         with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN bottom_handles INTEGER NOT NULL DEFAULT 1")
         with suppress(OperationalError):
-            await conn.exec_driver_sql("ALTER TABLE pending_devices ADD COLUMN discovery_source TEXT")
+            await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN top_handles INTEGER NOT NULL DEFAULT 1")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN left_handles INTEGER NOT NULL DEFAULT 0")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN right_handles INTEGER NOT NULL DEFAULT 0")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE device_inventory ADD COLUMN discovery_source TEXT")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE device_inventory ADD COLUMN properties JSON")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("UPDATE device_inventory SET properties = '[]' WHERE properties IS NULL")
         with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE scan_runs ADD COLUMN kind TEXT NOT NULL DEFAULT 'ip'")
         # --- Zigbee schema migrations (logged variant per CLAUDE.md feedback) ---
@@ -110,32 +186,32 @@ async def init_db() -> None:
                 "nodes.ieee_address.index",
                 "CREATE INDEX IF NOT EXISTS ix_nodes_ieee_address ON nodes(ieee_address)",
             ),
-            ("pending_devices.ieee_address", "ALTER TABLE pending_devices ADD COLUMN ieee_address TEXT"),
+            ("device_inventory.ieee_address", "ALTER TABLE device_inventory ADD COLUMN ieee_address TEXT"),
             (
-                "pending_devices.ieee_address.index",
-                "CREATE INDEX IF NOT EXISTS ix_pending_devices_ieee_address "
-                "ON pending_devices(ieee_address)",
+                "device_inventory.ieee_address.index",
+                "CREATE INDEX IF NOT EXISTS ix_device_inventory_ieee_address "
+                "ON device_inventory(ieee_address)",
             ),
-            ("pending_devices.friendly_name", "ALTER TABLE pending_devices ADD COLUMN friendly_name TEXT"),
-            ("pending_devices.device_subtype", "ALTER TABLE pending_devices ADD COLUMN device_subtype TEXT"),
-            ("pending_devices.model", "ALTER TABLE pending_devices ADD COLUMN model TEXT"),
-            ("pending_devices.vendor", "ALTER TABLE pending_devices ADD COLUMN vendor TEXT"),
-            ("pending_devices.lqi", "ALTER TABLE pending_devices ADD COLUMN lqi INTEGER"),
+            ("device_inventory.friendly_name", "ALTER TABLE device_inventory ADD COLUMN friendly_name TEXT"),
+            ("device_inventory.device_subtype", "ALTER TABLE device_inventory ADD COLUMN device_subtype TEXT"),
+            ("device_inventory.model", "ALTER TABLE device_inventory ADD COLUMN model TEXT"),
+            ("device_inventory.vendor", "ALTER TABLE device_inventory ADD COLUMN vendor TEXT"),
+            ("device_inventory.lqi", "ALTER TABLE device_inventory ADD COLUMN lqi INTEGER"),
         ]
         for label, sql in zigbee_migrations:
             await _try_migrate(conn, sql, label=label)
-        # Drop NOT NULL on pending_devices.ip (Zigbee devices have no IP).
+        # Drop NOT NULL on device_inventory.ip (Zigbee devices have no IP).
         # SQLite can't ALTER column nullability — rebuild the table if needed.
         try:
-            info = await conn.exec_driver_sql("PRAGMA table_info(pending_devices)")
+            info = await conn.exec_driver_sql("PRAGMA table_info(device_inventory)")
             cols = info.fetchall()
             ip_col = next((c for c in cols if c[1] == "ip"), None)
             # PRAGMA table_info row layout: (cid, name, type, notnull, dflt, pk)
             if ip_col and ip_col[3] == 1:
-                logger.info("Migrating pending_devices: dropping NOT NULL on ip column")
+                logger.info("Migrating device_inventory: dropping NOT NULL on ip column")
                 await conn.exec_driver_sql("PRAGMA foreign_keys = OFF")
                 await conn.exec_driver_sql(
-                    "CREATE TABLE pending_devices_new ("
+                    "CREATE TABLE device_inventory_new ("
                     "id VARCHAR PRIMARY KEY,"
                     "ip VARCHAR,"
                     "mac VARCHAR, hostname VARCHAR, os VARCHAR, services JSON,"
@@ -148,29 +224,30 @@ async def init_db() -> None:
                     "model VARCHAR,"
                     "vendor VARCHAR,"
                     "lqi INTEGER,"
+                    "properties JSON,"
                     "discovered_at DATETIME"
                     ")"
                 )
                 await conn.exec_driver_sql(
-                    "INSERT INTO pending_devices_new "
+                    "INSERT INTO device_inventory_new "
                     "(id, ip, mac, hostname, os, services, suggested_type, status, "
                     "discovery_source, ieee_address, friendly_name, device_subtype, "
                     "model, vendor, lqi, discovered_at) "
                     "SELECT id, ip, mac, hostname, os, services, suggested_type, status, "
                     "discovery_source, ieee_address, friendly_name, device_subtype, "
-                    "model, vendor, lqi, discovered_at FROM pending_devices"
+                    "model, vendor, lqi, discovered_at FROM device_inventory"
                 )
-                await conn.exec_driver_sql("DROP TABLE pending_devices")
+                await conn.exec_driver_sql("DROP TABLE device_inventory")
                 await conn.exec_driver_sql(
-                    "ALTER TABLE pending_devices_new RENAME TO pending_devices"
+                    "ALTER TABLE device_inventory_new RENAME TO device_inventory"
                 )
                 await conn.exec_driver_sql(
-                    "CREATE INDEX IF NOT EXISTS ix_pending_devices_ieee_address "
-                    "ON pending_devices(ieee_address)"
+                    "CREATE INDEX IF NOT EXISTS ix_device_inventory_ieee_address "
+                    "ON device_inventory(ieee_address)"
                 )
                 await conn.exec_driver_sql("PRAGMA foreign_keys = ON")
         except OperationalError as exc:
-            logger.warning("pending_devices ip-nullable rebuild failed: %s", exc)
+            logger.warning("device_inventory ip-nullable rebuild failed: %s", exc)
         # --- end Zigbee schema migrations -------------------------------------
         # --- Electrical designs schema migrations -----------------------------
         # Create designs table (idempotent)
@@ -267,6 +344,22 @@ async def init_db() -> None:
             logger.warning("canvas_state migration failed: %s", exc)
         # --- end Electrical designs schema migrations --------------------------
 
+        # Rack cables gained editable annotations: a label the user can print on
+        # the canvas, plus the same free-form property records nodes carry.
+        rack_cable_migrations: list[tuple[str, str]] = [
+            (
+                "rack_cables.label_visible",
+                "ALTER TABLE rack_cables ADD COLUMN label_visible BOOLEAN NOT NULL DEFAULT 0",
+            ),
+            ("rack_cables.properties", "ALTER TABLE rack_cables ADD COLUMN properties JSON"),
+        ]
+        for label, sql in rack_cable_migrations:
+            await _try_migrate(conn, sql, label=label)
+        with suppress(OperationalError):
+            await conn.exec_driver_sql(
+                "UPDATE rack_cables SET properties = '[]' WHERE properties IS NULL"
+            )
+
         with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE edges ADD COLUMN waypoints JSON")
         with suppress(OperationalError):
@@ -302,6 +395,37 @@ async def init_db() -> None:
         with suppress(OperationalError):
             sql = "UPDATE edges SET animated = 'none' WHERE animated = '0' OR animated = 0 OR animated IS NULL"
             await conn.exec_driver_sql(sql)
+        # Multi-source discovery tags: a device found by both an IP scan and a
+        # Proxmox import carries every source. Backfill from the legacy single
+        # discovery_source so existing rows show under their filter.
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE device_inventory ADD COLUMN discovery_sources JSON")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql(
+                "UPDATE device_inventory SET discovery_sources = json_array(discovery_source) "
+                "WHERE discovery_sources IS NULL AND discovery_source IS NOT NULL"
+            )
+        # Legacy IP-scanned rows predating discovery_source have a NULL scalar
+        # but a real IP — treat them as an ARP scan so they keep the IP tag.
+        with suppress(OperationalError):
+            await conn.exec_driver_sql(
+                "UPDATE device_inventory SET discovery_sources = json_array('arp') "
+                "WHERE discovery_sources IS NULL AND discovery_source IS NULL AND ip IS NOT NULL"
+            )
+        with suppress(OperationalError):
+            await conn.exec_driver_sql(
+                "UPDATE device_inventory SET discovery_sources = '[]' WHERE discovery_sources IS NULL"
+            )
+        # Canonicalize stored MACs (lowercase, ':' separators) so cross-source
+        # dedup can match a Proxmox NIC MAC against an ARP-scanned one by equality.
+        with suppress(OperationalError):
+            await conn.exec_driver_sql(
+                "UPDATE device_inventory SET mac = lower(replace(mac, '-', ':')) WHERE mac IS NOT NULL"
+            )
+        with suppress(OperationalError):
+            await conn.exec_driver_sql(
+                "UPDATE nodes SET mac = lower(replace(mac, '-', ':')) WHERE mac IS NOT NULL"
+            )
 
 
 async def get_db() -> AsyncGenerator[AsyncSession, None]:

backend/app/db/models.py

@@ -59,6 +59,9 @@ class Node(Base):
     width: Mapped[float | None] = mapped_column(Float, nullable=True)
     height: Mapped[float | None] = mapped_column(Float, nullable=True)
     bottom_handles: Mapped[int] = mapped_column(Integer, default=1)
+    top_handles: Mapped[int] = mapped_column(Integer, default=1)
+    left_handles: Mapped[int] = mapped_column(Integer, default=0)
+    right_handles: Mapped[int] = mapped_column(Integer, default=0)
     ieee_address: Mapped[str | None] = mapped_column(String, index=True, nullable=True)
     last_seen: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
     last_scan: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
@@ -82,7 +85,11 @@ class Edge(Base):
     speed: Mapped[str | None] = mapped_column(String)
     custom_color: Mapped[str | None] = mapped_column(String)
     path_style: Mapped[str | None] = mapped_column(String)
+    line_style: Mapped[str | None] = mapped_column(String)
+    width_mult: Mapped[float | None] = mapped_column(Float)
     animated: Mapped[str] = mapped_column(String, nullable=False, default='none')
+    marker_start: Mapped[str] = mapped_column(String, nullable=False, default='none')
+    marker_end: Mapped[str] = mapped_column(String, nullable=False, default='none')
     source_handle: Mapped[str | None] = mapped_column(String)
     target_handle: Mapped[str | None] = mapped_column(String)
     waypoints: Mapped[list[dict[str, float]] | None] = mapped_column(JSON, nullable=True)
@@ -98,8 +105,106 @@ class CanvasState(Base):
     saved_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
 
 
-class PendingDevice(Base):
-    __tablename__ = "pending_devices"
+class Rack(Base):
+    """A physical rack on a `design_type='rack'` canvas.
+
+    Racks live per design, like nodes and edges. Geometry is expressed in rack
+    units: `u_height` is the number of mountable U, and a device's `u_start` is
+    always counted from the bottom rail — `numbering` only changes the printed
+    labels.
+    """
+
+    __tablename__ = "racks"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
+    design_id: Mapped[str] = mapped_column(String, ForeignKey("designs.id", ondelete="CASCADE"), nullable=False)
+    name: Mapped[str] = mapped_column(String, nullable=False)
+    u_height: Mapped[int] = mapped_column(Integer, default=42)
+    # "19" or "10" (inches). Drives the drawn inner width.
+    width_standard: Mapped[str] = mapped_column(String, default="19")
+    # "bottom-up" or "top-down" — printed U labels only, never storage order.
+    numbering: Mapped[str] = mapped_column(String, default="bottom-up")
+    location: Mapped[str | None] = mapped_column(String, nullable=True)
+    # Frame/rail/interior colours + showNumbers/enclosed flags.
+    style: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict)
+    pos_x: Mapped[float] = mapped_column(Float, default=0)
+    pos_y: Mapped[float] = mapped_column(Float, default=0)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now, onupdate=_now)
+
+
+class RackDevice(Base):
+    """A piece of gear mounted in a rack.
+
+    Two independent, both-optional links back to the rest of the app:
+
+    * `device_id` — the Device Inventory entry (`device_inventory`). This is the
+      primary link: inventory rows survive approval *and* node deletion, so
+      unracking or deleting a canvas node never removes the inventory entry.
+    * `node_id` — the logical-canvas node, when one exists. Only used to resolve
+      live status and to seed cables from the network design's edges.
+
+    Both are ``SET NULL`` on delete and `label` is denormalized, so a rack keeps
+    rendering after an inventory purge.
+    """
+
+    __tablename__ = "rack_devices"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
+    design_id: Mapped[str] = mapped_column(String, ForeignKey("designs.id", ondelete="CASCADE"), nullable=False)
+    rack_id: Mapped[str] = mapped_column(String, ForeignKey("racks.id", ondelete="CASCADE"), nullable=False)
+    device_id: Mapped[str | None] = mapped_column(
+        String, ForeignKey("device_inventory.id", ondelete="SET NULL"), nullable=True
+    )
+    node_id: Mapped[str | None] = mapped_column(String, ForeignKey("nodes.id", ondelete="SET NULL"), nullable=True)
+    label: Mapped[str] = mapped_column(String, nullable=False)
+    # 1-based, counted from the bottom rail.
+    u_start: Mapped[int] = mapped_column(Integer, default=1)
+    u_height: Mapped[int] = mapped_column(Integer, default=1)
+    # 12-column horizontal grid: full = 12, half = 6, third = 4, quarter = 3.
+    col_start: Mapped[int] = mapped_column(Integer, default=0)
+    col_span: Mapped[int] = mapped_column(Integer, default=12)
+    faceplate_id: Mapped[str] = mapped_column(String, nullable=False, default="blank-1u")
+    color: Mapped[str | None] = mapped_column(String, nullable=True)
+    status: Mapped[str] = mapped_column(String, default="unknown")
+    # [{id, label, type, x, y}] — positions are unit coordinates on the plate.
+    ports: Mapped[list[Any]] = mapped_column(JSON, default=list)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now, onupdate=_now)
+
+
+class RackCable(Base):
+    """A patch between two rack device ports.
+
+    Not an `Edge`: rack cables are port-to-port and may cross racks, so they are
+    their own relation rather than a canvas edge.
+    """
+
+    __tablename__ = "rack_cables"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
+    design_id: Mapped[str] = mapped_column(String, ForeignKey("designs.id", ondelete="CASCADE"), nullable=False)
+    from_device_id: Mapped[str] = mapped_column(
+        String, ForeignKey("rack_devices.id", ondelete="CASCADE"), nullable=False
+    )
+    from_port_id: Mapped[str] = mapped_column(String, nullable=False)
+    to_device_id: Mapped[str] = mapped_column(
+        String, ForeignKey("rack_devices.id", ondelete="CASCADE"), nullable=False
+    )
+    to_port_id: Mapped[str] = mapped_column(String, nullable=False)
+    type: Mapped[str] = mapped_column(String, default="ethernet")
+    color: Mapped[str] = mapped_column(String, default="#39d353")
+    label: Mapped[str | None] = mapped_column(String, nullable=True)
+    # Print the label next to the run on the canvas.
+    label_visible: Mapped[bool] = mapped_column(Boolean, default=False)
+    # [{key, value, icon, visible}] — same records nodes carry; the visible ones
+    # are drawn beside the cable.
+    properties: Mapped[list[Any]] = mapped_column(JSON, default=list)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
+
+
+class InventoryDevice(Base):
+    __tablename__ = "device_inventory"
     # Permit the plain (non-Mapped[]) annotations on the transient request-only
     # attributes below; without this SQLAlchemy 2.0 tries to map them as columns.
     __allow_unmapped__ = True
@@ -112,13 +217,23 @@ class PendingDevice(Base):
     services: Mapped[list[Any]] = mapped_column(JSON, default=list)
     suggested_type: Mapped[str | None] = mapped_column(String)
     status: Mapped[str] = mapped_column(String, default="pending")
+    # Origin/primary source (first discovery): "arp"/"mdns"/"zigbee"/"zwave"/
+    # "proxmox". Kept for back-compat; `discovery_sources` is the full set.
     discovery_source: Mapped[str | None] = mapped_column(String)
+    # All sources that have observed this device. A device found by both an IP
+    # scan and a Proxmox import carries e.g. ["arp", "proxmox"] and shows under
+    # both inventory filters. Source of truth for the frontend source badges.
+    discovery_sources: Mapped[list[Any]] = mapped_column(JSON, default=list)
     ieee_address: Mapped[str | None] = mapped_column(String, index=True, nullable=True, unique=True)
     friendly_name: Mapped[str | None] = mapped_column(String, nullable=True)
     device_subtype: Mapped[str | None] = mapped_column(String, nullable=True)
     model: Mapped[str | None] = mapped_column(String, nullable=True)
     vendor: Mapped[str | None] = mapped_column(String, nullable=True)
     lqi: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # Display properties carried from discovery (e.g. Proxmox specs: CPU/RAM/Disk,
+    # VMID). Generic NodeProperty shape {key,value,icon,visible}; merged into the
+    # Node's properties on approve. Empty for scan/mesh sources that don't set it.
+    properties: Mapped[list[Any]] = mapped_column(JSON, default=list)
     discovered_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
 
     # Transient (not persisted): populated per-request by the scan routes to report
@@ -132,16 +247,16 @@ class PendingDevice(Base):
     node_last_seen: datetime | None = None
 
 
-class PendingDeviceLink(Base):
+class InventoryDeviceLink(Base):
     """Link between two Zigbee endpoints discovered during import.
 
     Endpoints are addressed by IEEE (stable across re-imports). Either side may
     already exist as a canvas Node (resolved via Node.ieee_address) or still be
-    a PendingDevice. On approval, the matching Edge is auto-created when both
+    a InventoryDevice. On approval, the matching Edge is auto-created when both
     endpoints exist as canvas Nodes.
     """
 
-    __tablename__ = "pending_device_links"
+    __tablename__ = "device_inventory_links"
 
     id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
     source_ieee: Mapped[str] = mapped_column(String, nullable=False, index=True)

backend/app/main.py

@@ -6,11 +6,28 @@ from typing import Any
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
+from starlette.middleware.sessions import SessionMiddleware
 
-from app.api.routes import auth, canvas, designs, edges, liveview, nodes, scan, stats, status, zigbee, zwave
+from app.api.routes import (
+    auth,
+    canvas,
+    designs,
+    edges,
+    liveview,
+    media,
+    nodes,
+    proxmox,
+    racks,
+    scan,
+    stats,
+    status,
+    zigbee,
+    zwave,
+)
 from app.api.routes import settings as settings_routes
 from app.core.config import settings
 from app.core.scheduler import start_scheduler, stop_scheduler
+from app.core.security import OIDCCSRFMiddleware
 from app.db.database import init_db
 
 
@@ -39,12 +56,21 @@ app = FastAPI(
     lifespan=lifespan,
 )
 
+app.add_middleware(OIDCCSRFMiddleware)
+app.add_middleware(
+    SessionMiddleware,
+    secret_key=settings.secret_key,
+    session_cookie=("__Host-homelable-oidc-flow" if settings.oidc_cookie_secure else "homelable-oidc-flow"),
+    max_age=settings.oidc_transaction_expire_seconds,
+    same_site="lax",
+    https_only=settings.oidc_cookie_secure,
+)
 app.add_middleware(
     CORSMiddleware,
     allow_origins=settings.cors_origins,
     allow_credentials=True,
     allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
-    allow_headers=["Authorization", "Content-Type"],
+    allow_headers=["Authorization", "Content-Type", "X-Homelable-CSRF", "X-MCP-Service-Key"],
 )
 
 app.include_router(auth.router, prefix="/api/v1/auth", tags=["auth"])
@@ -52,13 +78,16 @@ app.include_router(nodes.router, prefix="/api/v1/nodes", tags=["nodes"])
 app.include_router(edges.router, prefix="/api/v1/edges", tags=["edges"])
 app.include_router(canvas.router, prefix="/api/v1/canvas", tags=["canvas"])
 app.include_router(designs.router, prefix="/api/v1/designs", tags=["designs"])
+app.include_router(racks.router, prefix="/api/v1/racks", tags=["racks"])
 app.include_router(scan.router, prefix="/api/v1/scan", tags=["scan"])
 app.include_router(status.router, prefix="/api/v1/status", tags=["status"])
 app.include_router(settings_routes.router, prefix="/api/v1/settings", tags=["settings"])
 app.include_router(liveview.router, prefix="/api/v1/liveview", tags=["liveview"])
 app.include_router(zigbee.router, prefix="/api/v1/zigbee", tags=["zigbee"])
 app.include_router(zwave.router, prefix="/api/v1/zwave", tags=["zwave"])
+app.include_router(proxmox.router, prefix="/api/v1/proxmox", tags=["proxmox"])
 app.include_router(stats.router, prefix="/api/v1/stats", tags=["stats"])
+app.include_router(media.router, prefix="/api/v1/media", tags=["media"])
 
 
 @app.get("/api/v1/health")

backend/app/schemas/canvas.py

@@ -4,7 +4,7 @@ from pydantic import BaseModel, field_validator
 
 from app.schemas.edges import EdgeResponse
 from app.schemas.nodes import NodeResponse
-from app.schemas.utils import normalize_animated
+from app.schemas.utils import normalize_animated, normalize_marker
 
 
 class NodeSave(BaseModel):
@@ -34,6 +34,9 @@ class NodeSave(BaseModel):
     width: float | None = None
     height: float | None = None
     bottom_handles: int = 1
+    top_handles: int = 1
+    left_handles: int = 0
+    right_handles: int = 0
     pos_x: float = 0
     pos_y: float = 0
 
@@ -48,7 +51,11 @@ class EdgeSave(BaseModel):
     speed: str | None = None
     custom_color: str | None = None
     path_style: str | None = None
+    line_style: str | None = None
+    width_mult: float | None = None
     animated: str = 'none'
+    marker_start: str = 'none'
+    marker_end: str = 'none'
     source_handle: str | None = None
     target_handle: str | None = None
     waypoints: list[dict[str, float]] | None = None
@@ -58,6 +65,11 @@ class EdgeSave(BaseModel):
     def validate_animated(cls, v: object) -> str:
         return normalize_animated(v)
 
+    @field_validator('marker_start', 'marker_end', mode='before')
+    @classmethod
+    def validate_marker(cls, v: object) -> str:
+        return normalize_marker(v)
+
 
 class CanvasSaveRequest(BaseModel):
     nodes: list[NodeSave] = []
@@ -72,3 +84,8 @@ class CanvasStateResponse(BaseModel):
     edges: list[EdgeResponse]
     viewport: dict[str, Any]
     custom_style: dict[str, Any] | None = None
+    # True once this design's canvas has ever been persisted (a CanvasState row
+    # exists). Lets the frontend tell a brand-new user (show demo) apart from one
+    # who intentionally cleared their canvas (keep it empty). False also for a
+    # missing/uninitialized design.
+    initialized: bool = False

backend/app/schemas/designs.py

@@ -1,21 +1,40 @@
 from datetime import datetime
 
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
+
+# Kept in sync with DesignType in frontend/src/types.
+# "network" and "electrical" render the same React Flow canvas and differ only by
+# palette and node set — the icon drives their presentation. "rack" is a genuinely
+# different renderer (racks, mounted gear, port-to-port cables), so the frontend
+# does branch on this field.
+DESIGN_TYPES = {"network", "electrical", "rack"}
 
 
 class DesignCreate(BaseModel):
     name: str
     icon: str = "dashboard"
-    # Vestigial: kept for backward compatibility. The UI no longer branches on it;
-    # the chosen icon now drives presentation. Defaults to a generic canvas.
     design_type: str = "network"
 
+    @field_validator("design_type")
+    @classmethod
+    def _known_type(cls, v: str) -> str:
+        if v not in DESIGN_TYPES:
+            raise ValueError(f"design_type must be one of {sorted(DESIGN_TYPES)}")
+        return v
+
 
 class DesignUpdate(BaseModel):
     name: str | None = None
     icon: str | None = None
 
 
+class DesignCopy(BaseModel):
+    """Create a new design by deep-copying an existing one's canvas."""
+
+    name: str
+    icon: str = "dashboard"
+
+
 class DesignResponse(BaseModel):
     id: str
     name: str
@@ -23,5 +42,10 @@ class DesignResponse(BaseModel):
     icon: str | None = None
     created_at: datetime
     updated_at: datetime
+    # Populated by list_designs so the "copy from existing" picker can show what
+    # each canvas holds. None on create/update/copy responses (not computed there).
+    node_count: int | None = None
+    group_count: int | None = None
+    text_count: int | None = None
 
     model_config = {"from_attributes": True}

backend/app/schemas/edges.py

@@ -2,7 +2,7 @@ from datetime import datetime
 
 from pydantic import BaseModel, field_validator
 
-from app.schemas.utils import normalize_animated
+from app.schemas.utils import normalize_animated, normalize_marker
 
 
 class EdgeBase(BaseModel):
@@ -14,7 +14,11 @@ class EdgeBase(BaseModel):
     speed: str | None = None
     custom_color: str | None = None
     path_style: str | None = None
+    line_style: str | None = None
+    width_mult: float | None = None
     animated: str = 'none'
+    marker_start: str = 'none'
+    marker_end: str = 'none'
     source_handle: str | None = None
     target_handle: str | None = None
     waypoints: list[dict[str, float]] | None = None
@@ -24,6 +28,11 @@ class EdgeBase(BaseModel):
     def validate_animated(cls, v: object) -> str:
         return normalize_animated(v)
 
+    @field_validator('marker_start', 'marker_end', mode='before')
+    @classmethod
+    def validate_marker(cls, v: object) -> str:
+        return normalize_marker(v)
+
 
 class EdgeCreate(EdgeBase):
     design_id: str | None = None
@@ -36,7 +45,11 @@ class EdgeUpdate(BaseModel):
     speed: str | None = None
     custom_color: str | None = None
     path_style: str | None = None
+    line_style: str | None = None
+    width_mult: float | None = None
     animated: str | None = None
+    marker_start: str | None = None
+    marker_end: str | None = None
     source_handle: str | None = None
     target_handle: str | None = None
     waypoints: list[dict[str, float]] | None = None
@@ -48,6 +61,13 @@ class EdgeUpdate(BaseModel):
             return None
         return normalize_animated(v)
 
+    @field_validator('marker_start', 'marker_end', mode='before')
+    @classmethod
+    def validate_marker(cls, v: object) -> str | None:
+        if v is None:
+            return None
+        return normalize_marker(v)
+
 
 class EdgeResponse(EdgeBase):
     id: str

backend/app/schemas/nodes.py

@@ -32,10 +32,21 @@ class NodeBase(BaseModel):
     width: float | None = None
     height: float | None = None
     bottom_handles: int = 1
+    top_handles: int = 1
+    left_handles: int = 0
+    right_handles: int = 0
 
 
 class NodeCreate(NodeBase):
+    # Override pos_x/pos_y so callers can omit them; None signals "auto-place".
+    # The create_node route resolves None to a free grid slot before persisting.
+    pos_x: float | None = None  # type: ignore[assignment]
+    pos_y: float | None = None  # type: ignore[assignment]
     design_id: str | None = None
+    # When a node with the same ip/mac already exists on the target design, the
+    # create/approve endpoints reject with 409 so the UI can ask the user. Set
+    # force=True to bypass that guard and create the duplicate deliberately.
+    force: bool = False
 
 
 class NodeUpdate(BaseModel):
@@ -66,6 +77,9 @@ class NodeUpdate(BaseModel):
     width: float | None = None
     height: float | None = None
     bottom_handles: int | None = None
+    top_handles: int | None = None
+    left_handles: int | None = None
+    right_handles: int | None = None
 
 
 class NodeResponse(NodeBase):

backend/app/schemas/proxmox.py

@@ -0,0 +1,87 @@
+"""Pydantic v2 schemas for Proxmox VE import.
+
+Token fields are accepted on requests only and are optional — when omitted the
+backend falls back to the server-configured token (env). No response schema ever
+carries a token; secrets are kept out of responses by structural omission.
+"""
+
+from pydantic import BaseModel, Field
+
+
+class ProxmoxConnectionRequest(BaseModel):
+    host: str = Field(..., description="Proxmox VE host or IP")
+    port: int = Field(8006, ge=1, le=65535, description="Proxmox API port")
+    token_id: str | None = Field(
+        None, description="API token id 'user@realm!tokenname' (falls back to server env)"
+    )
+    token_secret: str | None = Field(
+        None, description="API token secret (falls back to server env)"
+    )
+    verify_tls: bool = Field(True, description="Verify the Proxmox TLS certificate")
+
+
+class ProxmoxTestConnectionResponse(BaseModel):
+    connected: bool
+    message: str
+
+
+class ProxmoxNodeOut(BaseModel):
+    """A homelable-ready node representation of a Proxmox host / VM / LXC."""
+
+    id: str
+    label: str
+    type: str  # proxmox | vm | lxc
+    ieee_address: str
+    hostname: str | None = None
+    ip: str | None = None
+    status: str
+    cpu_count: int | None = None
+    ram_gb: float | None = None
+    disk_gb: float | None = None
+    vendor: str | None = None
+    model: str | None = None
+    parent_ieee: str | None = None
+
+
+class ProxmoxEdgeOut(BaseModel):
+    source: str
+    target: str
+
+
+class ProxmoxImportResponse(BaseModel):
+    nodes: list[ProxmoxNodeOut]
+    edges: list[ProxmoxEdgeOut]
+    device_count: int
+
+
+class ProxmoxImportPendingResponse(BaseModel):
+    """Result of importing a Proxmox inventory into the pending section."""
+
+    pending_created: int
+    pending_updated: int
+    links_recorded: int
+    device_count: int
+
+
+class ProxmoxConfig(BaseModel):
+    """Non-secret Proxmox connection + auto-sync config (GET response).
+
+    Connection fields (host/port/verify_tls) are env-only and read-only here —
+    surfaced for display. ``token_configured`` reflects whether a server-side
+    token is present. Never carries the token itself."""
+
+    host: str = ""
+    port: int = Field(8006, ge=1, le=65535)
+    verify_tls: bool = True
+    sync_enabled: bool = False
+    sync_interval: int = Field(3600, ge=300)
+    token_configured: bool = False
+
+
+class ProxmoxSyncConfig(BaseModel):
+    """User-editable auto-sync config (POST body). The ONLY persisted Proxmox
+    settings. Connection fields (host/port/token/verify_tls) are env-only and
+    are deliberately not accepted here."""
+
+    sync_enabled: bool = False
+    sync_interval: int = Field(3600, ge=300)

backend/app/schemas/racks.py

@@ -0,0 +1,302 @@
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, field_validator, model_validator
+
+# Kept in sync with the frontend rack model (frontend/src/types).
+WIDTH_STANDARDS = {"19", "10"}
+NUMBERINGS = {"bottom-up", "top-down"}
+CABLE_TYPES = {"ethernet", "fiber"}
+# 12-column horizontal grid: full = 12, half = 6, third = 4, quarter = 3.
+RACK_COLUMNS = 12
+
+
+class RackSave(BaseModel):
+    id: str
+    name: str
+    u_height: int = 42
+    width_standard: str = "19"
+    numbering: str = "bottom-up"
+    location: str | None = None
+    style: dict[str, Any] = {}
+    pos_x: float = 0
+    pos_y: float = 0
+
+    @field_validator("u_height")
+    @classmethod
+    def _positive_height(cls, v: int) -> int:
+        if not 1 <= v <= 100:
+            raise ValueError("u_height must be between 1 and 100")
+        return v
+
+    @field_validator("width_standard")
+    @classmethod
+    def _known_width(cls, v: str) -> str:
+        if v not in WIDTH_STANDARDS:
+            raise ValueError(f"width_standard must be one of {sorted(WIDTH_STANDARDS)}")
+        return v
+
+    @field_validator("numbering")
+    @classmethod
+    def _known_numbering(cls, v: str) -> str:
+        if v not in NUMBERINGS:
+            raise ValueError(f"numbering must be one of {sorted(NUMBERINGS)}")
+        return v
+
+
+class RackDeviceSave(BaseModel):
+    id: str
+    rack_id: str
+    device_id: str | None = None
+    node_id: str | None = None
+    label: str
+    u_start: int = 1
+    u_height: int = 1
+    col_start: int = 0
+    col_span: int = RACK_COLUMNS
+    faceplate_id: str = "blank-1u"
+    color: str | None = None
+    status: str = "unknown"
+    ports: list[Any] = []
+
+    @field_validator("u_start", "u_height")
+    @classmethod
+    def _positive(cls, v: int) -> int:
+        if v < 1:
+            raise ValueError("u_start and u_height are 1-based and must be >= 1")
+        return v
+
+    @field_validator("col_start")
+    @classmethod
+    def _column_in_grid(cls, v: int) -> int:
+        if not 0 <= v < RACK_COLUMNS:
+            raise ValueError(f"col_start must be within the {RACK_COLUMNS}-column grid")
+        return v
+
+    @field_validator("col_span")
+    @classmethod
+    def _span_in_grid(cls, v: int) -> int:
+        if not 1 <= v <= RACK_COLUMNS:
+            raise ValueError(f"col_span must be between 1 and {RACK_COLUMNS}")
+        return v
+
+    @model_validator(mode="after")
+    def _fits_the_column_grid(self) -> "RackDeviceSave":
+        """`col_start` and `col_span` are legal apart and still illegal together.
+
+        11 + 12 spans to column 23 of a 12-column grid — each field passes its
+        own check, and the frontend serializer clamps them independently, so
+        nothing caught it before this.
+        """
+        if self.col_start + self.col_span > RACK_COLUMNS:
+            raise ValueError(
+                f"col_start + col_span must not exceed the {RACK_COLUMNS}-column grid"
+            )
+        return self
+
+
+class RackCableSave(BaseModel):
+    id: str
+    from_device_id: str
+    from_port_id: str
+    to_device_id: str
+    to_port_id: str
+    type: str = "ethernet"
+    color: str = "#39d353"
+    label: str | None = None
+    label_visible: bool = False
+    # [{key, value, icon, visible}] — free-form, same shape as node properties.
+    properties: list[dict[str, Any]] = []
+
+    @field_validator("type")
+    @classmethod
+    def _known_type(cls, v: str) -> str:
+        if v not in CABLE_TYPES:
+            raise ValueError(f"type must be one of {sorted(CABLE_TYPES)}")
+        return v
+
+    @field_validator("properties", mode="before")
+    @classmethod
+    def _clean_properties(cls, v: Any) -> list[dict[str, Any]]:
+        """Keep only usable records — a property with no key draws an empty badge."""
+        if not isinstance(v, list):
+            return []
+        return [p for p in v if isinstance(p, dict) and str(p.get("key", "")).strip()]
+
+
+class RackSaveRequest(BaseModel):
+    """Full rack state for one design — upserted, with anything missing pruned.
+
+    Same contract as ``POST /api/v1/canvas/save``: the client owns the state and
+    sends all of it on an explicit Save.
+    """
+
+    design_id: str
+    racks: list[RackSave] = []
+    devices: list[RackDeviceSave] = []
+    cables: list[RackCableSave] = []
+    # Pan/zoom, stored on the design's shared CanvasState row like the logical canvas.
+    viewport: dict[str, Any] = {}
+
+    @model_validator(mode="after")
+    def _devices_fit_their_rack(self) -> "RackSaveRequest":
+        """A mount must fit inside the rack it names.
+
+        `RackDeviceSave` validates each field in isolation and never sees the
+        rack, so `u_start: 40` in a 12U rack passed. A mount above the top rail
+        draws outside the chassis and nothing in the UI can drag it back, so the
+        server refuses to store it. Rack membership itself is checked in the
+        route, which knows what is already persisted.
+        """
+        heights = {r.id: r.u_height for r in self.racks}
+        for device in self.devices:
+            u_height = heights.get(device.rack_id)
+            if u_height is None:
+                continue  # unknown rack — the route reports that with a 400
+            if device.u_start + device.u_height - 1 > u_height:
+                raise ValueError(
+                    f"Device {device.id} does not fit in rack {device.rack_id}: "
+                    f"U {device.u_start}–{device.u_start + device.u_height - 1} "
+                    f"of {u_height}U"
+                )
+        return self
+
+
+class RackResponse(BaseModel):
+    id: str
+    design_id: str
+    name: str
+    u_height: int
+    width_standard: str
+    numbering: str
+    location: str | None = None
+    style: dict[str, Any] = {}
+    pos_x: float
+    pos_y: float
+
+    @field_validator("style", mode="before")
+    @classmethod
+    def _coerce_style(cls, v: Any) -> dict[str, Any]:
+        return v if isinstance(v, dict) else {}
+
+    model_config = {"from_attributes": True}
+
+
+class RackDeviceResponse(BaseModel):
+    id: str
+    design_id: str
+    rack_id: str
+    device_id: str | None = None
+    node_id: str | None = None
+    label: str
+    u_start: int
+    u_height: int
+    col_start: int
+    col_span: int
+    faceplate_id: str
+    color: str | None = None
+    status: str
+    ports: list[Any] = []
+
+    @field_validator("ports", mode="before")
+    @classmethod
+    def _coerce_ports(cls, v: Any) -> list[Any]:
+        return v if isinstance(v, list) else []
+
+    model_config = {"from_attributes": True}
+
+
+class RackCableResponse(BaseModel):
+    id: str
+    design_id: str
+    from_device_id: str
+    from_port_id: str
+    to_device_id: str
+    to_port_id: str
+    type: str
+    color: str
+    label: str | None = None
+    label_visible: bool = False
+    properties: list[dict[str, Any]] = []
+
+    @field_validator("properties", mode="before")
+    @classmethod
+    def _list_properties(cls, v: Any) -> list[dict[str, Any]]:
+        """Rows written before the column existed read back as NULL."""
+        return v if isinstance(v, list) else []
+
+    @field_validator("label_visible", mode="before")
+    @classmethod
+    def _bool_label_visible(cls, v: Any) -> bool:
+        return bool(v)
+
+    model_config = {"from_attributes": True}
+
+
+class RackStateResponse(BaseModel):
+    racks: list[RackResponse]
+    devices: list[RackDeviceResponse]
+    cables: list[RackCableResponse]
+    viewport: dict[str, Any] = {}
+
+
+class RackServiceInfo(BaseModel):
+    """One service fingerprinted on a device, as the rack view prints it."""
+
+    port: int | None = None
+    name: str | None = None
+
+
+class RackInventoryItem(BaseModel):
+    """A Device Inventory entry offered to the rack tray.
+
+    Carries the technical facts the logical canvas already knows about the same
+    hardware (`node_*`), so a mount can print them without the user leaving the
+    rack. Everything node-side is read-only here: the logical canvas owns it.
+    """
+
+    id: str
+    label: str
+    suggested_type: str | None = None
+    ip: str | None = None
+    status: str
+    discovery_source: str | None = None
+    # Inventory-side technical detail, from discovery.
+    mac: str | None = None
+    hostname: str | None = None
+    os: str | None = None
+    services: list[RackServiceInfo] = []
+    # Live status of the matching canvas node, when the device is on one.
+    node_id: str | None = None
+    node_status: str | None = None
+    # What that node holds — the logical view of the same box.
+    node_label: str | None = None
+    node_type: str | None = None
+    node_ip: str | None = None
+    node_mac: str | None = None
+    node_hostname: str | None = None
+    node_os: str | None = None
+    node_check_method: str | None = None
+    node_design_id: str | None = None
+    node_design_name: str | None = None
+    node_last_seen: datetime | None = None
+    # True when this device is already mounted somewhere in this design.
+    racked: bool = False
+
+    @field_validator("node_last_seen")
+    @classmethod
+    def _utc(cls, v: datetime | None) -> datetime | None:
+        """Stamp UTC on a naive timestamp before it goes on the wire.
+
+        SQLite has no timezone type: an aware datetime written to `last_seen`
+        reads back naive, and Pydantic then serializes it without an offset.
+        `new Date("2026-08-08T10:00:00")` in the browser is *local* time, so the
+        rack printed a last-seen shifted by the viewer's offset.
+        """
+        if v is not None and v.tzinfo is None:
+            return v.replace(tzinfo=timezone.utc)
+        return v
+
+
+class RackInventoryResponse(BaseModel):
+    items: list[RackInventoryItem]

backend/app/schemas/scan.py

@@ -1,10 +1,10 @@
 from datetime import datetime
 from typing import Any
 
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
 
 
-class PendingDeviceResponse(BaseModel):
+class InventoryDeviceResponse(BaseModel):
     id: str
     ip: str | None
     mac: str | None
@@ -14,12 +14,18 @@ class PendingDeviceResponse(BaseModel):
     suggested_type: str | None
     status: str
     discovery_source: str | None
+    # All sources that have observed this device (e.g. ["arp", "proxmox"]). Drives
+    # the inventory source filter + badges; falls back to [discovery_source].
+    discovery_sources: list[str] = []
     ieee_address: str | None = None
     friendly_name: str | None = None
     device_subtype: str | None = None
     model: str | None = None
     vendor: str | None = None
     lqi: int | None = None
+    # Display properties carried from discovery (e.g. Proxmox specs). Merged into
+    # the node on approve; empty for scan/mesh sources that don't set them.
+    properties: list[Any] = []
     discovered_at: datetime
     # Number of distinct canvases (designs) this device already appears on,
     # correlated by ip / ieee_address against existing nodes. Computed per-request.
@@ -32,9 +38,50 @@ class PendingDeviceResponse(BaseModel):
     node_last_modified: datetime | None = None
     node_last_seen: datetime | None = None
 
+    @field_validator("properties", "discovery_sources", mode="before")
+    @classmethod
+    def _coerce_list(cls, v: Any) -> list[Any]:
+        # Legacy rows (columns added by migration) have these = NULL.
+        return v if isinstance(v, list) else []
+
     model_config = {"from_attributes": True}
 
 
+"""Sources a hand-made inventory entry may claim.
+
+``rack`` marks gear created from a rack canvas. Those rows live in the Device
+Inventory like any other, but they describe a physical mount rather than a host
+on the network, so they are never placed on a logical canvas.
+"""
+MANUAL_SOURCES = {"manual", "rack"}
+
+
+class InventoryDeviceCreate(BaseModel):
+    """Manually add an entry to the Device Inventory.
+
+    Used when the user documents hardware no scan can find — a dumb switch, a
+    patch panel, a machine that is powered off. Lands with
+    `discovery_source="manual"` (or `"rack"`) so the inventory filters can tell
+    it apart.
+    """
+
+    hostname: str
+    ip: str | None = None
+    mac: str | None = None
+    suggested_type: str | None = None
+    model: str | None = None
+    vendor: str | None = None
+    properties: list[Any] = []
+    discovery_source: str = "manual"
+
+    @field_validator("discovery_source")
+    @classmethod
+    def _known_source(cls, v: str) -> str:
+        if v not in MANUAL_SOURCES:
+            raise ValueError(f"discovery_source must be one of {sorted(MANUAL_SOURCES)}")
+        return v
+
+
 class ScanRunResponse(BaseModel):
     id: str
     status: str

backend/app/schemas/utils.py

@@ -7,3 +7,21 @@ def normalize_animated(v: object) -> str:
     if v in ('snake', 'flow', 'basic'):
         return str(v)
     return 'none'
+
+
+MARKER_SHAPES = {'none', 'arrow', 'arrow-open', 'circle', 'diamond', 'square'}
+
+
+def normalize_marker(v: object) -> str:
+    """Normalize an edge endpoint marker to a shape string.
+
+    Legacy saves stored a boolean (True = filled arrow); coerce those and any
+    unknown value to a valid MarkerShape ('none' when off/unknown).
+    """
+    if v is True or v == 1 or v == '1':
+        return 'arrow'
+    if v is False or v == 0 or v == '0' or v is None:
+        return 'none'
+    if isinstance(v, str) and v in MARKER_SHAPES:
+        return v
+    return 'none'

backend/app/schemas/zigbee.py

@@ -93,3 +93,29 @@ class ZigbeeImportPendingResponse(BaseModel):
     coordinator_already_existed: bool = False
     links_recorded: int
     device_count: int
+
+
+class ZigbeeConfig(BaseModel):
+    """Non-secret Zigbee connection + auto-sync config (GET response).
+
+    MQTT connection fields (host/port/base_topic/tls) are env-only and
+    read-only here — surfaced for display. ``host_configured`` reflects whether
+    a server-side MQTT host is set (required for auto-sync). MQTT credentials
+    (username/password) are never carried."""
+
+    mqtt_host: str = ""
+    mqtt_port: int = Field(1883, ge=1, le=65535)
+    base_topic: str = "zigbee2mqtt"
+    mqtt_tls: bool = False
+    sync_enabled: bool = False
+    sync_interval: int = Field(3600, ge=300)
+    host_configured: bool = False
+
+
+class ZigbeeSyncConfig(BaseModel):
+    """User-editable auto-sync config (POST body). The ONLY persisted Zigbee
+    settings. Connection fields (host/port/credentials/topic/tls) are env-only
+    and are deliberately not accepted here."""
+
+    sync_enabled: bool = False
+    sync_interval: int = Field(3600, ge=300)

backend/app/schemas/zwave.py

@@ -83,3 +83,30 @@ class ZwaveImportPendingResponse(BaseModel):
     coordinator_already_existed: bool = False
     links_recorded: int
     device_count: int
+
+
+class ZwaveConfig(BaseModel):
+    """Non-secret Z-Wave connection + auto-sync config (GET response).
+
+    MQTT connection fields (host/port/prefix/gateway_name/tls) are env-only and
+    read-only here — surfaced for display. ``host_configured`` reflects whether
+    a server-side MQTT host is set (required for auto-sync). MQTT credentials
+    (username/password) are never carried."""
+
+    mqtt_host: str = ""
+    mqtt_port: int = Field(1883, ge=1, le=65535)
+    prefix: str = "zwave"
+    gateway_name: str = "zwavejs2mqtt"
+    mqtt_tls: bool = False
+    sync_enabled: bool = False
+    sync_interval: int = Field(3600, ge=300)
+    host_configured: bool = False
+
+
+class ZwaveSyncConfig(BaseModel):
+    """User-editable auto-sync config (POST body). The ONLY persisted Z-Wave
+    settings. Connection fields (host/port/credentials/prefix/gateway/tls) are
+    env-only and are deliberately not accepted here."""
+
+    sync_enabled: bool = False
+    sync_interval: int = Field(3600, ge=300)

backend/app/services/discovery_sources.py

@@ -0,0 +1,19 @@
+"""Helpers for the multi-valued ``InventoryDevice.discovery_sources`` set.
+
+A device discovered by more than one path (e.g. an IP scan *and* a Proxmox
+import) accumulates every source that has seen it, so it surfaces under each
+matching inventory filter. Order is preserved (origin first) and duplicates are
+dropped.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+
+def add_source(sources: Iterable[str] | None, source: str | None) -> list[str]:
+    """Return ``sources`` with ``source`` appended if not already present."""
+    out = [s for s in (sources or []) if s]
+    if source and source not in out:
+        out.append(source)
+    return out

backend/app/services/mac_utils.py

@@ -0,0 +1,18 @@
+"""MAC-address normalization, shared by the scan + Proxmox persist paths.
+
+Different discovery sources emit MACs in different casing/separators (ARP is
+lowercase ``bc:24:11:..``, Proxmox config is often uppercase ``BC:24:11:..``).
+Canonicalizing on write *and* on compare lets cross-source dedup match a device
+by MAC with a plain ``==`` — the join key for merging an IP-scanned row with a
+Proxmox-imported one.
+"""
+
+from __future__ import annotations
+
+
+def normalize_mac(mac: str | None) -> str | None:
+    """Canonical MAC: lowercase, ``-`` → ``:``, stripped. Blank/None → None."""
+    if not mac:
+        return None
+    normalized = mac.strip().lower().replace("-", ":")
+    return normalized or None

backend/app/services/node_dedupe.py

@@ -0,0 +1,241 @@
+"""Collapse *true* duplicate canvas nodes: same ``ieee_address`` **and** same
+``design_id`` (i.e. the same device placed twice on the *same* canvas).
+
+The same device legitimately appears on multiple canvases — placing a device on
+another design creates a second :class:`Node` for that IEEE by design (see the
+per-design guard in ``bulk_approve_devices``). Those cross-design rows are NOT
+duplicates and must be preserved. Only two rows sharing both the IEEE *and* the
+design are corrupt, and only those are collapsed here.
+
+This module provides an idempotent, **loss-free** repair: per ``(ieee,
+design_id)`` group with >1 node it keeps the oldest as canonical, merges the
+extras' data into it (properties, missing scalar fields, services), re-points
+every edge and ``parent_id`` reference onto the canonical node, then deletes the
+extras. Edges are de-duplicated and self-loops dropped after re-pointing so no
+dangling or redundant links remain.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from sqlalchemy import or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import Edge, Node
+from app.services.zigbee_service import merge_zigbee_properties
+
+logger = logging.getLogger(__name__)
+
+
+def _ip_tokens(ip: str | None) -> list[str]:
+    """Split a Node ``ip`` field into individual, whitespace-trimmed addresses.
+
+    The canvas stores several addresses in one comma-separated string once a
+    user adds e.g. an IPv6 address, so identity matching must compare per token.
+    """
+    return [t.strip() for t in ip.split(",") if t.strip()] if ip else []
+
+
+async def find_duplicate_node(
+    db: AsyncSession,
+    design_id: str | None,
+    ip: str | None,
+    mac: str | None,
+    ieee: str | None = None,
+) -> dict[str, Any] | None:
+    """Return conflict details if an equivalent node (same ieee, ip OR mac)
+    already sits on ``design_id``, else ``None``.
+
+    Scoped to a single design on purpose: the same device may legitimately
+    appear on several canvases (one :class:`Node` per design). Only a second
+    node for the same ieee/ip/mac on the *same* design is a duplicate — which
+    the create/approve endpoints turn into a 409 so the UI can offer "go to
+    existing" vs "add duplicate anyway", uniformly for IEEE (Zigbee/Z-Wave) and
+    plain IP/ARP hosts.
+
+    (:func:`dedupe_nodes_by_ieee` still repairs *pre-existing* same-canvas IEEE
+    duplicates; this guard prevents new ones unless the user forces them.)
+    """
+    ip_toks = _ip_tokens(ip)
+    conds = []
+    if ieee:
+        conds.append(Node.ieee_address == ieee)
+    # A node's ip may hold several comma-separated addresses (e.g. an IPv6 added
+    # before the IPv4), so narrow with a substring match then confirm per-token
+    # in Python — exact ``Node.ip == ip`` would miss those rows (issue #258).
+    for tok in ip_toks:
+        conds.append(Node.ip.contains(tok))
+    if mac:
+        conds.append(Node.mac == mac)
+    if not conds:
+        return None
+    candidates = (
+        await db.execute(
+            select(Node).where(Node.design_id == design_id, or_(*conds))
+        )
+    ).scalars().all()
+
+    # Confirm a real match (the ip ``contains`` above can false-positive, e.g.
+    # "1.2.3.4" inside "1.2.3.40"), preferring ieee > ip > mac.
+    def _matches(node: Node) -> tuple[str, str | None] | None:
+        if ieee and node.ieee_address == ieee:
+            return "ieee", node.ieee_address
+        node_toks = set(_ip_tokens(node.ip))
+        hit = next((t for t in ip_toks if t in node_toks), None)
+        if hit is not None:
+            return "ip", hit
+        if mac and node.mac == mac:
+            return "mac", mac
+        return None
+
+    existing = None
+    matched: tuple[str, str | None] | None = None
+    for node in candidates:
+        m = _matches(node)
+        if m is not None:
+            existing, matched = node, m
+            break
+    if existing is None or matched is None:
+        return None
+    match, value = matched
+    return {
+        "duplicate": True,
+        "existing_node_id": existing.id,
+        "existing_label": existing.label,
+        "match": match,
+        "value": value,
+    }
+
+# Scalar Node fields worth carrying over from a duplicate when the canonical
+# node has no value. Positions, design, parent and identity fields are left on
+# the canonical node untouched (that's the row the user actually placed).
+_FILLABLE_FIELDS = (
+    "hostname",
+    "ip",
+    "mac",
+    "os",
+    "check_method",
+    "check_target",
+    "notes",
+    "cpu_count",
+    "cpu_model",
+    "ram_gb",
+    "disk_gb",
+    "custom_icon",
+    "last_seen",
+    "last_scan",
+)
+
+
+def _merge_services(
+    a: list[Any] | None, b: list[Any] | None
+) -> list[Any]:
+    """Union two service lists, de-duplicated, order-stable."""
+    out: list[Any] = list(a or [])
+    seen = {repr(s) for s in out}
+    for s in b or []:
+        if repr(s) not in seen:
+            out.append(s)
+            seen.add(repr(s))
+    return out
+
+
+def _merge_into_canonical(canonical: Node, dup: Node) -> None:
+    """Fold ``dup``'s data into ``canonical`` in place (no field lost)."""
+    canonical.properties = merge_zigbee_properties(
+        canonical.properties, dup.properties or []
+    )
+    canonical.services = _merge_services(canonical.services, dup.services)
+    for field in _FILLABLE_FIELDS:
+        if getattr(canonical, field, None) in (None, "") and getattr(dup, field, None) not in (None, ""):
+            setattr(canonical, field, getattr(dup, field))
+    # Prefer a human label over a bare IEEE/hex fallback.
+    if (not canonical.label or canonical.label == canonical.ieee_address) and dup.label:
+        canonical.label = dup.label
+
+
+async def dedupe_nodes_by_ieee(db: AsyncSession) -> int:
+    """Merge duplicate nodes sharing an ``ieee_address`` AND ``design_id``.
+
+    Returns the number of nodes removed. Idempotent: a no-op when every
+    ``(ieee, design)`` pair maps to at most one node. Nodes with the same IEEE
+    on *different* designs are left untouched (valid cross-canvas placement).
+    Does not commit — the caller owns the transaction.
+    """
+    rows = (
+        await db.execute(
+            select(Node)
+            .where(Node.ieee_address.is_not(None))
+            .order_by(Node.ieee_address, Node.created_at, Node.id)
+        )
+    ).scalars().all()
+
+    groups: dict[tuple[str, str | None], list[Node]] = {}
+    for node in rows:
+        groups.setdefault((node.ieee_address, node.design_id), []).append(node)  # type: ignore[arg-type]
+
+    removed = 0
+    for (ieee, _design), nodes in groups.items():
+        if len(nodes) < 2:
+            continue
+        canonical, *dups = nodes  # oldest first (ordered above)
+        dup_ids = {d.id for d in dups}
+
+        for dup in dups:
+            _merge_into_canonical(canonical, dup)
+
+        # Re-point edges + parents, then drop self-loops / duplicates.
+        edges = (
+            await db.execute(
+                select(Edge).where(
+                    Edge.source.in_(dup_ids) | Edge.target.in_(dup_ids)
+                )
+            )
+        ).scalars().all()
+        for edge in edges:
+            if edge.source in dup_ids:
+                edge.source = canonical.id
+            if edge.target in dup_ids:
+                edge.target = canonical.id
+
+        # Re-point children whose parent was a duplicate.
+        children = (
+            await db.execute(select(Node).where(Node.parent_id.in_(dup_ids)))
+        ).scalars().all()
+        for child in children:
+            child.parent_id = canonical.id
+
+        # Collapse self-loops and now-redundant parallel edges.
+        all_edges = (
+            await db.execute(
+                select(Edge).where(
+                    (Edge.source == canonical.id) | (Edge.target == canonical.id)
+                )
+            )
+        ).scalars().all()
+        seen_pairs: set[tuple[str, str, str]] = set()
+        for edge in all_edges:
+            if edge.source == edge.target:
+                await db.delete(edge)
+                continue
+            key = (edge.source, edge.target, edge.type)
+            if key in seen_pairs:
+                await db.delete(edge)
+                continue
+            seen_pairs.add(key)
+
+        await db.flush()
+        for dup in dups:
+            await db.delete(dup)
+            removed += 1
+
+        logger.info(
+            "Deduped IEEE %s: merged %d duplicate node(s) into %s",
+            ieee, len(dups), canonical.id,
+        )
+
+    if removed:
+        await db.flush()
+    return removed

backend/app/services/proxmox_service.py

@@ -0,0 +1,424 @@
+"""Proxmox VE inventory service: fetch hosts + VMs + LXC via the PVE REST API.
+
+Mirrors the Zigbee/Z-Wave import pipeline, but talks to the Proxmox VE REST API
+(``/api2/json``) over HTTPS with an API token instead of MQTT. It returns plain
+homelable node dicts + parent→child edge hints; DB persistence lives in the
+route layer (``app.api.routes.proxmox``).
+
+Auth uses a Proxmox **API token** (never a password):
+``Authorization: PVEAPIToken=<token_id>=<secret>`` where ``token_id`` looks like
+``user@realm!tokenname``. A read-only ``PVEAuditor`` role is all that is needed.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+import httpx
+
+from app.services.mac_utils import normalize_mac
+from app.services.zigbee_service import merge_zigbee_properties
+
+logger = logging.getLogger(__name__)
+
+# Reuse the zigbee property-merge contract verbatim (same NodeProperty shape +
+# visibility-preservation rules) for re-sync updates.
+merge_proxmox_properties = merge_zigbee_properties
+
+_CONNECT_TIMEOUT = 8.0
+_READ_TIMEOUT = 20.0
+_BYTES_PER_GB = 1024 ** 3
+
+# net0 config line: "name=eth0,bridge=vmbr0,ip=192.168.1.5/24,gw=..."
+_LXC_IP_RE = re.compile(r"(?:^|,)ip=([0-9]{1,3}(?:\.[0-9]{1,3}){3})(?:/\d+)?")
+# NIC MAC inside a net0 string — qemu "virtio=BC:24:11:..,bridge=.." or lxc
+# "..,hwaddr=BC:24:11:..,..". A bare 6-octet MAC match works for both forms.
+_NET_MAC_RE = re.compile(r"([0-9a-fA-F]{2}(?::[0-9a-fA-F]{2}){5})")
+
+
+def _sanitize_proxmox_error(exc: BaseException) -> str:
+    """Return a generic, credential-free message for a Proxmox/HTTP error.
+
+    Raw httpx errors can echo the request URL and, worse, an
+    ``Authorization: PVEAPIToken=...=<secret>`` header in some stacks. Map known
+    patterns to coarse categories so the token never reaches an API client. The
+    original exception is logged at WARNING for operators.
+    """
+    logger.warning("Proxmox error (sanitized for client): %r", exc)
+    if isinstance(exc, httpx.HTTPStatusError):
+        code = exc.response.status_code
+        if code in (401, 403):
+            return "Authentication failed — check the API token and its permissions"
+        if code == 404:
+            return "Proxmox API path not found — is this a Proxmox VE host?"
+        return f"Proxmox API returned HTTP {code}"
+    raw = str(exc).lower()
+    if "name or service not known" in raw or "getaddrinfo" in raw or "nodename nor servname" in raw:
+        return "Proxmox host could not be resolved"
+    if "refused" in raw:
+        return "Connection refused by Proxmox host"
+    if "certificate" in raw or "ssl" in raw or "tls" in raw:
+        return "TLS verification failed — enable 'skip TLS verify' for self-signed certs"
+    if "timed out" in raw or "timeout" in raw:
+        return "Connection to Proxmox host timed out"
+    return "Proxmox connection failed"
+
+
+def _auth_header(token_id: str, token_secret: str) -> dict[str, str]:
+    return {"Authorization": f"PVEAPIToken={token_id}={token_secret}"}
+
+
+def _gb(value: Any) -> float | None:
+    """Convert a byte count to GB (1 decimal). None/0 → None."""
+    try:
+        num = float(value)
+    except (TypeError, ValueError):
+        return None
+    if num <= 0:
+        return None
+    return round(num / _BYTES_PER_GB, 1)
+
+
+def _int_or_none(value: Any) -> int | None:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _guest_type_to_homelable(kind: str) -> str:
+    """qemu → vm, lxc → lxc (both existing homelable node types)."""
+    return "vm" if kind == "qemu" else "lxc"
+
+
+def _extract_qemu_ip(agent_payload: dict[str, Any] | None) -> str | None:
+    """Pull the first non-loopback IPv4 from a qemu guest-agent interfaces reply."""
+    if not agent_payload:
+        return None
+    result = agent_payload.get("result")
+    if not isinstance(result, list):
+        return None
+    for iface in result:
+        if not isinstance(iface, dict):
+            continue
+        for addr in iface.get("ip-addresses") or []:
+            if not isinstance(addr, dict):
+                continue
+            if addr.get("ip-address-type") != "ipv4":
+                continue
+            ip = addr.get("ip-address")
+            if isinstance(ip, str) and ip and not ip.startswith("127."):
+                return ip
+    return None
+
+
+def _extract_lxc_ip(config_payload: dict[str, Any] | None) -> str | None:
+    """Parse a static IPv4 from an LXC ``net0`` config string (skip dhcp)."""
+    if not config_payload:
+        return None
+    net0 = config_payload.get("net0")
+    if not isinstance(net0, str):
+        return None
+    match = _LXC_IP_RE.search(net0)
+    return match.group(1) if match else None
+
+
+def _extract_net_mac(config_payload: dict[str, Any] | None) -> str | None:
+    """Parse the NIC MAC from a qemu/lxc ``net0`` config string (normalized).
+
+    Works agent-free for both guest kinds and for stopped guests — the sole
+    identity we can reliably cross-match against an ARP-scanned device.
+    """
+    if not config_payload:
+        return None
+    net0 = config_payload.get("net0")
+    if not isinstance(net0, str):
+        return None
+    match = _NET_MAC_RE.search(net0)
+    return normalize_mac(match.group(1)) if match else None
+
+
+def _host_node(raw: dict[str, Any]) -> dict[str, Any] | None:
+    """Build a homelable ``proxmox`` host node from a ``/nodes`` entry."""
+    name = raw.get("node")
+    if not name:
+        return None
+    ieee = f"pve-node-{name}"
+    return {
+        "id": ieee,
+        "label": name,
+        "type": "proxmox",
+        "ieee_address": ieee,
+        "hostname": name,
+        "ip": raw.get("ip") or None,
+        "status": "online" if raw.get("status") == "online" else "offline",
+        "cpu_count": _int_or_none(raw.get("maxcpu")),
+        "ram_gb": _gb(raw.get("maxmem")),
+        "disk_gb": _gb(raw.get("maxdisk")),
+        "vendor": "Proxmox VE",
+        "model": None,
+        "parent_ieee": None,
+    }
+
+
+def _guest_node(
+    raw: dict[str, Any], host_name: str, kind: str, ip: str | None, mac: str | None = None
+) -> dict[str, Any] | None:
+    """Build a homelable vm/lxc node from a ``/qemu`` or ``/lxc`` list entry."""
+    vmid = raw.get("vmid")
+    if vmid is None:
+        return None
+    ieee = f"pve-{host_name}-{vmid}"
+    node_type = _guest_type_to_homelable(kind)
+    name = raw.get("name") or f"{node_type}-{vmid}"
+    return {
+        "id": ieee,
+        "label": name,
+        "type": node_type,
+        "ieee_address": ieee,
+        "hostname": name,
+        "ip": ip,
+        "mac": mac,
+        "status": "online" if raw.get("status") == "running" else "offline",
+        "cpu_count": _int_or_none(raw.get("maxcpu") or raw.get("cpus")),
+        "ram_gb": _gb(raw.get("maxmem")),
+        "disk_gb": _gb(raw.get("maxdisk")),
+        "vendor": "Proxmox VE",
+        "model": kind.upper(),
+        "vmid": vmid,
+        "parent_ieee": f"pve-node-{host_name}",
+    }
+
+
+def build_proxmox_properties(node: dict[str, Any]) -> list[dict[str, Any]]:
+    """Build a NodeProperty list for a Proxmox device (specs + identity).
+
+    Icons match the existing hardware-property convention (``Cpu`` /
+    ``MemoryStick`` / ``HardDrive``). All rows default ``visible=False`` — the
+    user opts in from the right panel, same as the mesh importers."""
+    props: list[dict[str, Any]] = []
+    vmid = node.get("vmid")
+    if vmid is not None:
+        props.append({"key": "VMID", "value": str(vmid), "icon": None, "visible": False})
+    if node.get("model"):
+        props.append({"key": "Kind", "value": node["model"], "icon": None, "visible": False})
+    if node.get("cpu_count") is not None:
+        props.append({"key": "CPU Cores", "value": str(node["cpu_count"]), "icon": "Cpu", "visible": False})
+    if node.get("ram_gb") is not None:
+        props.append({"key": "RAM", "value": f"{node['ram_gb']} GB", "icon": "MemoryStick", "visible": False})
+    if node.get("disk_gb") is not None:
+        props.append({"key": "Disk", "value": f"{node['disk_gb']} GB", "icon": "HardDrive", "visible": False})
+    props.append({"key": "Source", "value": "Proxmox VE", "icon": None, "visible": False})
+    return props
+
+
+def build_proxmox_cluster_links(nodes: list[dict[str, Any]]) -> list[tuple[str, str]]:
+    """Chain host nodes (``type == 'proxmox'``) into cluster links.
+
+    Hosts from one import belong to the same cluster, so they are linked
+    host↔host (rendered as ``cluster`` edges via left/right handles, distinct
+    from the vertical host→guest ``virtual`` edges). Returns consecutive
+    ``(source_ieee, target_ieee)`` pairs, or ``[]`` for a single host. Mirrors
+    the frontend ``buildProxmoxClusterEdges``.
+    """
+    hosts = [n["ieee_address"] for n in nodes if n.get("type") == "proxmox" and n.get("ieee_address")]
+    if len(hosts) < 2:
+        return []
+    return [(hosts[i], hosts[i + 1]) for i in range(len(hosts) - 1)]
+
+
+def _parse_inventory(
+    hosts_raw: list[dict[str, Any]],
+    guests_by_host: dict[str, list[dict[str, Any]]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Assemble (nodes, edges) from fetched host + guest data.
+
+    ``guests_by_host`` maps host name → list of already-normalized guest node
+    dicts. Edges are one host→guest link per guest (materialized as canvas
+    edges on approval, mirroring the zigbee/zwave link mechanism).
+    """
+    nodes: list[dict[str, Any]] = []
+    edges: list[dict[str, Any]] = []
+    seen: set[str] = set()
+
+    for raw in hosts_raw:
+        host = _host_node(raw)
+        if host is None or host["id"] in seen:
+            continue
+        seen.add(host["id"])
+        nodes.append(host)
+
+    for host_name, guests in guests_by_host.items():
+        host_ieee = f"pve-node-{host_name}"
+        for guest in guests:
+            if guest["id"] in seen:
+                continue
+            seen.add(guest["id"])
+            nodes.append(guest)
+            edges.append({"source": host_ieee, "target": guest["id"]})
+
+    return nodes, edges
+
+
+async def _get_json(client: httpx.AsyncClient, path: str) -> Any:
+    resp = await client.get(path)
+    resp.raise_for_status()
+    return resp.json().get("data")
+
+
+async def _token_has_permissions(client: httpx.AsyncClient) -> bool:
+    """True if the API token holds *any* ACL.
+
+    Proxmox list endpoints (``/qemu``, ``/lxc``) silently return an empty
+    ``200`` when the token lacks ``VM.Audit`` — indistinguishable from a host
+    that genuinely has no guests. ``GET /access/permissions`` returns ``{}`` for
+    a token with no ACL at all, which is the common misconfiguration (a
+    privilege-separated token created without its own permission). Best-effort:
+    on any error assume permissions exist so we never block a valid import.
+    """
+    try:
+        perms = await _get_json(client, "/access/permissions")
+    except httpx.HTTPError:
+        return True
+    return bool(perms) if isinstance(perms, dict) else True
+
+
+async def fetch_proxmox_inventory(
+    host: str,
+    port: int,
+    token_id: str,
+    token_secret: str,
+    verify_tls: bool = True,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Fetch hosts + VMs + LXC from a Proxmox VE host, return (nodes, edges).
+
+    Raises:
+        ConnectionError: transport/DNS/TLS failures (sanitized message).
+        ValueError: malformed API response.
+    """
+    base_url = f"https://{host}:{port}/api2/json"
+    timeout = httpx.Timeout(_READ_TIMEOUT, connect=_CONNECT_TIMEOUT)
+    guests_by_host: dict[str, list[dict[str, Any]]] = {}
+
+    try:
+        async with httpx.AsyncClient(
+            base_url=base_url,
+            headers=_auth_header(token_id, token_secret),
+            verify=verify_tls,
+            timeout=timeout,
+        ) as client:
+            hosts_raw = await _get_json(client, "/nodes")
+            if not isinstance(hosts_raw, list):
+                raise ValueError("Malformed /nodes response")
+
+            for host_entry in hosts_raw:
+                name = host_entry.get("node")
+                if not name or host_entry.get("status") != "online":
+                    # Offline nodes can't be queried for guests; still shown as host.
+                    continue
+                guests_by_host[name] = await _fetch_host_guests(client, name)
+    except httpx.HTTPStatusError as exc:
+        raise ConnectionError(_sanitize_proxmox_error(exc)) from exc
+    except httpx.HTTPError as exc:
+        raise ConnectionError(_sanitize_proxmox_error(exc)) from exc
+
+    return _parse_inventory(hosts_raw, guests_by_host)
+
+
+async def _fetch_host_guests(
+    client: httpx.AsyncClient, host_name: str
+) -> list[dict[str, Any]]:
+    """Fetch qemu + lxc guests for one host, resolving guest IPs best-effort."""
+    guests: list[dict[str, Any]] = []
+
+    for kind in ("qemu", "lxc"):
+        try:
+            entries = await _get_json(client, f"/nodes/{host_name}/{kind}")
+        except httpx.HTTPError as exc:
+            logger.warning("Proxmox %s list failed for %s: %s", kind, host_name, exc)
+            continue
+        if not isinstance(entries, list):
+            continue
+        for raw in entries:
+            ip, mac = await _resolve_guest_net(client, host_name, kind, raw)
+            node = _guest_node(raw, host_name, kind, ip, mac)
+            if node:
+                guests.append(node)
+
+    return guests
+
+
+async def _resolve_guest_net(
+    client: httpx.AsyncClient, host_name: str, kind: str, raw: dict[str, Any]
+) -> tuple[str | None, str | None]:
+    """Best-effort (ip, mac) for a guest. Never raises.
+
+    - MAC comes from the guest ``/config`` net0 line for both kinds (agent-free,
+      works for stopped guests) — the cross-source dedup key.
+    - IP: qemu → guest agent (running only); lxc → static net0 config.
+    Partial results are returned even if a later call fails (e.g. config MAC is
+    kept when the qemu agent call errors).
+    """
+    vmid = raw.get("vmid")
+    if vmid is None:
+        return None, None
+    ip: str | None = None
+    mac: str | None = None
+    try:
+        if kind == "qemu":
+            config = await _get_json(client, f"/nodes/{host_name}/qemu/{vmid}/config")
+            mac = _extract_net_mac(config)
+            if raw.get("status") == "running":
+                data = await _get_json(
+                    client, f"/nodes/{host_name}/qemu/{vmid}/agent/network-get-interfaces"
+                )
+                ip = _extract_qemu_ip(data)
+        else:
+            config = await _get_json(client, f"/nodes/{host_name}/lxc/{vmid}/config")
+            ip = _extract_lxc_ip(config)
+            mac = _extract_net_mac(config)
+    except httpx.HTTPError:
+        # Guest agent not installed / container stopped / no perms. Keep whatever
+        # was resolved before the failure.
+        pass
+    return ip, mac
+
+
+async def test_proxmox_connection(
+    host: str,
+    port: int,
+    token_id: str,
+    token_secret: str,
+    verify_tls: bool = True,
+) -> tuple[bool, str]:
+    """Quick reachability + auth check via ``GET /version``.
+
+    Returns (connected, message). Never raises credentials outward.
+    """
+    base_url = f"https://{host}:{port}/api2/json"
+    timeout = httpx.Timeout(_READ_TIMEOUT, connect=_CONNECT_TIMEOUT)
+    try:
+        async with httpx.AsyncClient(
+            base_url=base_url,
+            headers=_auth_header(token_id, token_secret),
+            verify=verify_tls,
+            timeout=timeout,
+        ) as client:
+            data = await _get_json(client, "/version")
+            has_perms = await _token_has_permissions(client)
+        version = (data or {}).get("version", "?") if isinstance(data, dict) else "?"
+        message = f"Connected to Proxmox VE {version}"
+        if not has_perms:
+            message += (
+                " — warning: this API token has no permissions, so VMs and LXC "
+                "will not be visible. Assign the PVEAuditor role at path '/' to the "
+                "token in Proxmox (Datacenter → Permissions → API Token Permission)."
+            )
+        return True, message
+    except httpx.HTTPError as exc:
+        return False, _sanitize_proxmox_error(exc)
+    except Exception as exc:  # noqa: BLE001 — surface a safe message, log the rest
+        logger.exception("Unexpected error during Proxmox connection test")
+        return False, _sanitize_proxmox_error(exc)

backend/app/services/scanner.py

@@ -14,9 +14,12 @@ from typing import Any
 from sqlalchemy import or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.db.models import Node, PendingDevice, ScanRun
+from app.core.config import settings
+from app.db.models import InventoryDevice, Node, ScanRun
+from app.services.discovery_sources import add_source
 from app.services.fingerprint import fingerprint_ports, suggest_node_type
 from app.services.http_probe import probe_open_ports
+from app.services.mac_utils import normalize_mac
 
 logger = logging.getLogger(__name__)
 
@@ -238,6 +241,14 @@ def _nmap_scan_single(host_dict: dict[str, Any], port_spec: str = _EXTRA_PORTS)
     """
     Phase 2 — single-IP port scan with service detection.
     Runs in a thread (blocking). Returns the host dict enriched with open_ports.
+
+    Two decoupled nmap passes (issue #277):
+      Pass A — port discovery only (``--open``, no ``-sV``). Fast and reliable;
+               its open ports are authoritative and are never discarded.
+      Pass B — version detection (``-sV``) scoped to the ports Pass A found,
+               bounded by ``--host-timeout``. Best-effort: if it times out or
+               fails (e.g. a TLS port stalls plaintext probes), the Pass A ports
+               are kept with empty banners instead of the whole host being lost.
     """
     ip = host_dict["ip"]
     logger.info("[Phase 2] Scanning %s ...", ip)
@@ -246,48 +257,76 @@ def _nmap_scan_single(host_dict: dict[str, Any], port_spec: str = _EXTRA_PORTS)
         logger.warning("[Phase 2] nmap not available, skipping %s", ip)
         return host_dict
 
-    is_root = os.geteuid() == 0
-    if is_root:
-        # SYN scan + version detection (fastest, most accurate)
-        scan_args = f"-sS -sV --open -T4 -Pn --host-timeout 60s -p {port_spec}"
-    else:
-        # TCP connect scan (-sT) — no raw sockets needed, works without root.
-        # nmap auto-selects -sT without root but being explicit avoids edge cases.
-        scan_args = f"-sT -sV --open -T4 -Pn --host-timeout 60s -p {port_spec}"
+    # -sS (SYN) needs root; -sT (connect) works without it. nmap auto-selects
+    # -sT without root but being explicit avoids edge cases.
+    scan_type = "-sS" if os.geteuid() == 0 else "-sT"
 
-    logger.debug("[Phase 2] %s args: %s", ip, scan_args)
-    nm = nmap.PortScanner()
+    # --- Pass A: port discovery (no -sV, no host-timeout) ---
+    discovery_args = f"{scan_type} --open -T4 -Pn -p {port_spec}"
+    logger.debug("[Phase 2] %s discovery args: %s", ip, discovery_args)
+    nm_disc = nmap.PortScanner()
     try:
-        nm.scan(hosts=ip, arguments=scan_args)
+        nm_disc.scan(hosts=ip, arguments=discovery_args)
     except Exception as exc:
-        logger.warning("[Phase 2] nmap FAILED for %s (%s: %s) — skipping port scan", ip, type(exc).__name__, exc)
+        logger.warning("[Phase 2] nmap discovery FAILED for %s (%s: %s) — skipping port scan",
+                       ip, type(exc).__name__, exc)
         return host_dict
 
-    all_scanned = nm.all_hosts()
-    logger.debug("[Phase 2] %s — nmap returned %d host(s) in results", ip, len(all_scanned))
-    if ip not in all_scanned:
+    if ip not in nm_disc.all_hosts():
         logger.info("[Phase 2] %s — no open ports found (all closed/filtered or nmap had no results)", ip)
         return host_dict
 
     open_ports = []
-    for proto in nm[ip].all_protocols():
-        for port, info in nm[ip][proto].items():
+    for proto in nm_disc[ip].all_protocols():
+        for port, info in nm_disc[ip][proto].items():
             if info["state"] == "open":
-                banner = (info.get("product", "") + " " + info.get("version", "")).strip()
-                open_ports.append({"port": port, "protocol": proto, "banner": banner})
+                open_ports.append({"port": port, "protocol": proto, "banner": ""})
 
-    if open_ports:
-        port_summary = ", ".join(
-            f"{p['port']}/{p['protocol']} ({p['banner'] or 'unknown'})" for p in open_ports
-        )
-        logger.info("[Phase 2] %s — %d open port(s): %s", ip, len(open_ports), port_summary)
-    else:
+    if not open_ports:
         logger.info("[Phase 2] %s — 0 open ports detected", ip)
+        host_dict["open_ports"] = []
+        if not host_dict["mac"]:
+            host_dict["mac"] = nm_disc[ip].get("addresses", {}).get("mac")
+        return host_dict
+
+    # --- Pass B: version detection on the discovered ports (best-effort) ---
+    port_list = ",".join(str(p["port"]) for p in open_ports)
+    timeout = settings.scanner_version_host_timeout
+    version_args = f"{scan_type} -sV -T4 -Pn --host-timeout {timeout}s -p {port_list}"
+    logger.debug("[Phase 2] %s version args: %s", ip, version_args)
+    nm_ver = nmap.PortScanner()
+    banners: dict[tuple[str, int], str] = {}
+    ver_os = None
+    ver_mac = None
+    try:
+        nm_ver.scan(hosts=ip, arguments=version_args)
+        if ip in nm_ver.all_hosts():
+            for proto in nm_ver[ip].all_protocols():
+                for port, info in nm_ver[ip][proto].items():
+                    banner = (info.get("product", "") + " " + info.get("version", "")).strip()
+                    if banner:
+                        banners[(proto, port)] = banner
+            ver_os = _extract_os(nm_ver, ip)
+            ver_mac = nm_ver[ip].get("addresses", {}).get("mac")
+        else:
+            logger.info("[Phase 2] %s — version detection returned no results, keeping %d port(s) without banners",
+                        ip, len(open_ports))
+    except Exception as exc:
+        logger.info("[Phase 2] %s — version detection failed (%s: %s), keeping %d port(s) without banners",
+                    ip, type(exc).__name__, exc, len(open_ports))
+
+    for p in open_ports:
+        p["banner"] = banners.get((p["protocol"], p["port"]), "")
+
+    port_summary = ", ".join(
+        f"{p['port']}/{p['protocol']} ({p['banner'] or 'unknown'})" for p in open_ports
+    )
+    logger.info("[Phase 2] %s — %d open port(s): %s", ip, len(open_ports), port_summary)
 
     host_dict["open_ports"] = open_ports
     if not host_dict["mac"]:
-        host_dict["mac"] = nm[ip].get("addresses", {}).get("mac")
-    host_dict["os"] = _extract_os(nm, ip)
+        host_dict["mac"] = ver_mac or nm_disc[ip].get("addresses", {}).get("mac")
+    host_dict["os"] = ver_os
     return host_dict
 
 
@@ -437,12 +476,12 @@ async def _dedupe_pending_by_ip(db: AsyncSession) -> int:
     otherwise the oldest row, and deletes the rest. Returns the number deleted.
     """
     rows = (await db.execute(
-        select(PendingDevice)
-        .where(PendingDevice.status != "hidden", PendingDevice.ip.isnot(None))
-        .order_by(PendingDevice.discovered_at)
+        select(InventoryDevice)
+        .where(InventoryDevice.status != "hidden", InventoryDevice.ip.isnot(None))
+        .order_by(InventoryDevice.discovered_at)
     )).scalars().all()
 
-    by_ip: dict[str, list[PendingDevice]] = {}
+    by_ip: dict[str, list[InventoryDevice]] = {}
     for row in rows:
         if row.ip is None:  # guarded by the query, but keeps the type checker happy
             continue
@@ -468,7 +507,7 @@ async def run_scan(
     run_id: str,
     deep_scan: DeepScanOptions | None = None,
 ) -> None:
-    """Execute scan for given CIDR ranges and populate pending_devices."""
+    """Execute scan for given CIDR ranges and populate device_inventory."""
     from app.api.routes.status import broadcast_scan_update
 
     deep_scan = deep_scan or DeepScanOptions()
@@ -488,7 +527,7 @@ async def run_scan(
         # Devices already on a canvas are intentionally NOT suppressed: they stay
         # in the inventory and are badged "In N canvas" via per-request correlation.
         hidden_ips_result = await db.execute(
-            select(PendingDevice.ip).where(PendingDevice.status == "hidden")
+            select(InventoryDevice.ip).where(InventoryDevice.status == "hidden")
         )
         hidden_ips: set[str] = {row[0] for row in hidden_ips_result.fetchall()}
 
@@ -522,17 +561,22 @@ async def run_scan(
                     ip, open_ports, verify_tls=deep_scan.verify_tls
                 )
 
+            norm_mac = normalize_mac(host.get("mac"))
             services = fingerprint_ports(open_ports)
-            suggested_type = suggest_node_type(open_ports, host.get("mac"))
+            suggested_type = suggest_node_type(open_ports, norm_mac)
 
-            # One inventory row per device (by IP). Match across pending AND
-            # approved so a re-scan of an already-approved device refreshes its
-            # row instead of spawning a fresh "pending" duplicate. Hidden rows
-            # are already skipped above.
+            # One inventory row per device. Match by IP OR MAC across pending AND
+            # approved so a re-scan refreshes the existing row instead of spawning
+            # a duplicate — and so a device previously imported from Proxmox (which
+            # may have no IP but a known NIC MAC) reconciles with this scan instead
+            # of doubling up. Hidden rows are already skipped above.
+            match_cond = [InventoryDevice.ip == ip]
+            if norm_mac:
+                match_cond.append(InventoryDevice.mac == norm_mac)
             existing_rows = (await db.execute(
-                select(PendingDevice)
-                .where(PendingDevice.ip == ip, PendingDevice.status != "hidden")
-                .order_by(PendingDevice.discovered_at)
+                select(InventoryDevice)
+                .where(or_(*match_cond), InventoryDevice.status != "hidden")
+                .order_by(InventoryDevice.discovered_at)
             )).scalars().all()
 
             if existing_rows:
@@ -543,32 +587,41 @@ async def run_scan(
                 for dup in existing_rows:
                     if dup is not keep:
                         await db.delete(dup)
-                keep.mac = host.get("mac") or keep.mac
+                keep.ip = keep.ip or ip  # fill an IP a Proxmox import lacked
+                keep.mac = norm_mac or keep.mac
                 keep.hostname = host.get("hostname") or keep.hostname
                 keep.os = host.get("os") or keep.os
                 keep.services = services
-                keep.suggested_type = suggested_type
+                # Don't downgrade a Proxmox-typed guest (vm/lxc) to the generic
+                # scan guess; the importer knows the true type.
+                if not (keep.ieee_address or "").startswith("pve-"):
+                    keep.suggested_type = suggested_type
+                # Merged row carries both sources (e.g. ["proxmox", "arp"]).
+                keep.discovery_sources = add_source(keep.discovery_sources, discovery_source)
                 # status preserved — an approved device stays approved.
             else:
-                db.add(PendingDevice(
+                db.add(InventoryDevice(
                     ip=ip,
-                    mac=host.get("mac"),
+                    mac=norm_mac,
                     hostname=host.get("hostname"),
                     os=host.get("os"),
                     services=services,
                     suggested_type=suggested_type,
                     status="pending",
                     discovery_source=discovery_source,
+                    discovery_sources=[discovery_source],
                 ))
                 devices_found += 1
 
             # Stamp last_scan on any canvas node that matches this device by IP
             # (or MAC, when known) so the inventory shows when the scanner last
-            # observed it. Matches across designs.
-            host_mac = host.get("mac")
+            # observed it. Match both the normalized and raw MAC so a legacy
+            # canvas node whose mac predates normalization still matches. Across
+            # designs.
             node_match = [Node.ip == ip]
-            if host_mac:
-                node_match.append(Node.mac == host_mac)
+            for m in {norm_mac, host.get("mac")}:
+                if m:
+                    node_match.append(Node.mac == m)
             matching_nodes = (await db.execute(
                 select(Node).where(or_(*node_match))
             )).scalars().all()

backend/requirements.txt

@@ -6,8 +6,10 @@ aiosqlite==0.20.0
 alembic==1.13.3
 pydantic==2.9.2
 pydantic-settings==2.5.2
-python-jose[cryptography]==3.5.0
+PyJWT==2.13.0
 bcrypt==4.2.1
+authlib==1.7.2
+itsdangerous==2.2.0
 python-multipart==0.0.31
 apscheduler==3.10.4
 python-nmap==0.7.1

backend/tests/conftest.py

@@ -44,10 +44,7 @@ async def client(db_session: AsyncSession):
 
 
 @pytest.fixture
-def auth_headers(client):
-    """Returns a coroutine that logs in and returns auth headers."""
-    async def _get():
-        res = await client.post("/api/v1/auth/login", json={"username": "admin", "password": "admin"})
-        token = res.json()["access_token"]
-        return {"Authorization": f"Bearer {token}"}
-    return _get
+async def headers(client: AsyncClient):
+    """Authenticated Bearer headers for the default admin test user."""
+    res = await client.post("/api/v1/auth/login", json={"username": "admin", "password": "admin"})
+    return {"Authorization": f"Bearer {res.json()['access_token']}"}

backend/tests/scan/conftest.py

@@ -0,0 +1,84 @@
+"""Fixtures shared across the scan test modules."""
+import uuid
+
+import pytest
+
+from app.db.models import InventoryDevice
+
+
+@pytest.fixture
+async def pending_device(db_session):
+    import uuid
+    device = InventoryDevice(
+        id=str(uuid.uuid4()),
+        ip="192.168.1.100",
+        mac="aa:bb:cc:dd:ee:ff",
+        hostname="my-server",
+        os="Linux",
+        services=[{"port": 22, "name": "ssh"}],
+        suggested_type="server",
+        status="pending",
+    )
+    db_session.add(device)
+    await db_session.commit()
+    await db_session.refresh(device)
+    return device
+
+
+@pytest.fixture
+async def mem_db():
+    from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+
+    from app.db.database import Base
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    factory = async_sessionmaker(engine, expire_on_commit=False)
+    yield factory
+    await engine.dispose()
+
+
+@pytest.fixture
+async def two_device_inventory(db_session):
+    devices = []
+    for i in range(2):
+        d = InventoryDevice(
+            id=str(uuid.uuid4()),
+            ip=f"192.168.1.{10 + i}",
+            mac=None,
+            hostname=f"host-{i}",
+            os=None,
+            services=[],
+            suggested_type="generic",
+            status="pending",
+        )
+        db_session.add(d)
+        devices.append(d)
+    await db_session.commit()
+    for d in devices:
+        await db_session.refresh(d)
+    return devices
+
+
+@pytest.fixture
+async def zigbee_pending_device(db_session):
+    device = InventoryDevice(
+        id=str(uuid.uuid4()),
+        ip=None,
+        mac=None,
+        hostname=None,
+        friendly_name="bulb_1",
+        services=[],
+        suggested_type="zigbee_enddevice",
+        device_subtype="EndDevice",
+        ieee_address="0xABCDEF",
+        vendor="IKEA",
+        model="TRADFRI",
+        lqi=180,
+        status="pending",
+        discovery_source="zigbee",
+    )
+    db_session.add(device)
+    await db_session.commit()
+    await db_session.refresh(device)
+    return device

backend/tests/scan/helpers.py

@@ -0,0 +1,52 @@
+"""Shared builders for scan test suite (pure helpers, no fixtures)."""
+import uuid
+
+from app.db.models import Design, InventoryDevice, Node
+
+
+async def _add_design(db_session, name: str) -> str:
+    design = Design(id=str(uuid.uuid4()), name=name)
+    db_session.add(design)
+    await db_session.commit()
+    return design.id
+
+
+def _node(design_id: str, *, ip=None, ieee=None, mac=None) -> Node:
+    return Node(
+        id=str(uuid.uuid4()), label="n", type="server", status="online",
+        ip=ip, mac=mac, ieee_address=ieee, services=[], pos_x=0.0, pos_y=0.0,
+        design_id=design_id,
+    )
+
+
+async def _seed_zigbee_pending_pair(db_session):
+    """Create a coordinator Node + a pending device + a link between them."""
+    from app.db.models import InventoryDeviceLink, Node
+
+    coord = Node(
+        label="Coordinator",
+        type="zigbee_coordinator",
+        status="unknown",
+        ieee_address="0xCOORD",
+    )
+    db_session.add(coord)
+
+    pending = InventoryDevice(
+        ieee_address="0xR1",
+        friendly_name="router_1",
+        suggested_type="zigbee_router",
+        device_subtype="Router",
+        status="pending",
+        discovery_source="zigbee",
+    )
+    db_session.add(pending)
+
+    db_session.add(
+        InventoryDeviceLink(
+            source_ieee="0xCOORD",
+            target_ieee="0xR1",
+            discovery_source="zigbee",
+        )
+    )
+    await db_session.commit()
+    return coord, pending

backend/tests/scan/test_scan_approve.py

@@ -0,0 +1,723 @@
+"""Approve / hide / restore / ignore / bulk device flows and conflict handling."""
+import uuid
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy import select
+
+from app.db.models import Design, InventoryDevice, Node
+from tests.scan.helpers import _add_design, _node
+
+
+@pytest.mark.asyncio
+async def test_canvas_count_ignores_nodes_without_design(client, headers, db_session, pending_device):
+    # A node with no design_id is not "on a canvas".
+    db_session.add(_node(None, ip="192.168.1.100"))
+    await db_session.commit()
+
+    res = await client.get("/api/v1/scan/pending", headers=headers)
+    assert res.json()[0]["canvas_count"] == 0
+
+
+@pytest.mark.asyncio
+async def test_approve_device(client: AsyncClient, headers, pending_device):
+    node_payload = {
+        "label": "My Server",
+        "type": "server",
+        "ip": "192.168.1.100",
+        "hostname": "my-server",
+        "status": "unknown",
+        "services": [],
+    }
+    res = await client.post(
+        f"/api/v1/scan/pending/{pending_device.id}/approve",
+        json=node_payload,
+        headers=headers,
+    )
+    assert res.status_code == 200
+    data = res.json()
+    assert data["approved"] is True
+    assert "node_id" in data
+
+    # Approved devices stay in the inventory (status != "hidden") so they keep
+    # showing with an "In N canvas" badge — they are no longer dropped.
+    pending_res = await client.get("/api/v1/scan/pending", headers=headers)
+    inventory = pending_res.json()
+    assert len(inventory) == 1
+    assert inventory[0]["id"] == pending_device.id
+    assert inventory[0]["status"] == "approved"
+
+
+@pytest.mark.asyncio
+async def test_approve_device_conflicts_on_existing_ieee_same_design(
+    client: AsyncClient, headers, db_session
+):
+    """Approving a device whose IEEE is already on the target design prompts the
+    user (409) instead of silently merging/replacing — same UX as ip/mac."""
+    design = Design(name="d1")
+    db_session.add(design)
+    await db_session.flush()
+    existing = Node(
+        label="sensor", type="zigbee_enddevice", ieee_address="0xZZZ",
+        services=[], design_id=design.id,
+    )
+    db_session.add(existing)
+    device = InventoryDevice(
+        id=str(uuid.uuid4()), ieee_address="0xZZZ", suggested_type="zigbee_enddevice",
+        status="pending", discovery_source="zigbee",
+    )
+    db_session.add(device)
+    await db_session.commit()
+
+    res = await client.post(
+        f"/api/v1/scan/pending/{device.id}/approve",
+        json={
+            "label": "sensor", "type": "zigbee_enddevice",
+            "status": "online", "services": [], "design_id": design.id,
+        },
+        headers=headers,
+    )
+    assert res.status_code == 409
+    detail = res.json()["detail"]
+    assert detail["duplicate"] is True
+    assert detail["existing_node_id"] == existing.id
+    assert detail["match"] == "ieee"
+    assert detail["value"] == "0xZZZ"
+
+    # No second node created; device stays pending until the user decides.
+    nodes = (
+        await db_session.execute(select(Node).where(Node.ieee_address == "0xZZZ"))
+    ).scalars().all()
+    assert len(nodes) == 1
+
+
+@pytest.mark.asyncio
+async def test_approve_device_force_creates_duplicate_ieee(
+    client: AsyncClient, headers, db_session
+):
+    """force=True lets the user place a second card for the same IEEE."""
+    design = Design(name="d1")
+    db_session.add(design)
+    await db_session.flush()
+    db_session.add(Node(
+        label="sensor", type="zigbee_enddevice", ieee_address="0xZZZ",
+        services=[], design_id=design.id,
+    ))
+    device = InventoryDevice(
+        id=str(uuid.uuid4()), ieee_address="0xZZZ", suggested_type="zigbee_enddevice",
+        status="pending", discovery_source="zigbee",
+    )
+    db_session.add(device)
+    await db_session.commit()
+
+    res = await client.post(
+        f"/api/v1/scan/pending/{device.id}/approve",
+        json={
+            "label": "sensor", "type": "zigbee_enddevice", "status": "online",
+            "services": [], "design_id": design.id, "force": True,
+        },
+        headers=headers,
+    )
+    assert res.status_code == 200
+    nodes = (
+        await db_session.execute(select(Node).where(Node.ieee_address == "0xZZZ"))
+    ).scalars().all()
+    assert len(nodes) == 2
+
+
+@pytest.mark.asyncio
+async def test_approve_device_conflicts_on_existing_ip(
+    client: AsyncClient, headers, db_session, pending_device
+):
+    """An ordinary host whose ip already sits on the target design is NOT
+    silently duplicated: the approve returns 409 with the existing node so the
+    UI can ask the user."""
+    design = await _add_design(db_session, "Home")
+    existing = _node(design, ip="192.168.1.100")
+    db_session.add(existing)
+    await db_session.commit()
+
+    res = await client.post(
+        f"/api/v1/scan/pending/{pending_device.id}/approve",
+        json={"label": "dup", "type": "server", "ip": "192.168.1.100",
+              "status": "unknown", "services": [], "design_id": design},
+        headers=headers,
+    )
+    assert res.status_code == 409
+    detail = res.json()["detail"]
+    assert detail["duplicate"] is True
+    assert detail["existing_node_id"] == existing.id
+    assert detail["match"] == "ip"
+    assert detail["value"] == "192.168.1.100"
+
+    # No node created, device left pending (user hasn't decided yet).
+    nodes = (await db_session.execute(select(Node).where(Node.design_id == design))).scalars().all()
+    assert len(nodes) == 1
+    await db_session.refresh(pending_device)
+    assert pending_device.status == "pending"
+
+
+@pytest.mark.asyncio
+async def test_approve_device_conflicts_on_existing_mac(
+    client: AsyncClient, headers, db_session, pending_device
+):
+    """MAC match (device re-IP'd via DHCP) also triggers the duplicate guard."""
+    design = await _add_design(db_session, "Home")
+    existing = Node(id=str(uuid.uuid4()), label="n", type="server", status="online",
+                    ip="10.0.0.9", mac="aa:bb:cc:dd:ee:ff", services=[], design_id=design)
+    db_session.add(existing)
+    await db_session.commit()
+
+    # pending_device carries mac aa:bb:cc:dd:ee:ff but a different ip.
+    res = await client.post(
+        f"/api/v1/scan/pending/{pending_device.id}/approve",
+        json={"label": "dup", "type": "server", "ip": "192.168.1.55",
+              "mac": "aa:bb:cc:dd:ee:ff", "status": "unknown", "services": [],
+              "design_id": design},
+        headers=headers,
+    )
+    assert res.status_code == 409
+    assert res.json()["detail"]["match"] == "mac"
+
+
+@pytest.mark.asyncio
+async def test_approve_device_conflicts_on_ip_in_comma_list(
+    client: AsyncClient, headers, db_session, pending_device
+):
+    """The existing node's ip holds an IPv6 before the IPv4 the device scanned
+    as. Exact-string matching missed it (issue #258); per-token matching catches
+    the duplicate."""
+    design = await _add_design(db_session, "Home")
+    existing = _node(design, ip="fe80::1, 192.168.1.100")
+    db_session.add(existing)
+    await db_session.commit()
+
+    res = await client.post(
+        f"/api/v1/scan/pending/{pending_device.id}/approve",
+        json={"label": "dup", "type": "server", "ip": "192.168.1.100",
+              "status": "unknown", "services": [], "design_id": design},
+        headers=headers,
+    )
+    assert res.status_code == 409
+    detail = res.json()["detail"]
+    assert detail["existing_node_id"] == existing.id
+    assert detail["match"] == "ip"
+    assert detail["value"] == "192.168.1.100"
+
+
+@pytest.mark.asyncio
+async def test_approve_device_no_conflict_on_ip_substring(
+    client: AsyncClient, headers, db_session, pending_device
+):
+    """The ip guard must match whole addresses, not substrings: a node at
+    10.0.0.40 is not a duplicate of a device at 10.0.0.4."""
+    design = await _add_design(db_session, "Home")
+    db_session.add(_node(design, ip="10.0.0.40"))
+    await db_session.commit()
+
+    res = await client.post(
+        f"/api/v1/scan/pending/{pending_device.id}/approve",
+        json={"label": "new", "type": "server", "ip": "10.0.0.4",
+              "mac": None, "status": "unknown", "services": [], "design_id": design},
+        headers=headers,
+    )
+    assert res.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_approve_device_force_creates_duplicate(
+    client: AsyncClient, headers, db_session, pending_device
+):
+    """force=True (user confirmed) bypasses the guard and creates the node."""
+    design = await _add_design(db_session, "Home")
+    db_session.add(_node(design, ip="192.168.1.100"))
+    await db_session.commit()
+
+    res = await client.post(
+        f"/api/v1/scan/pending/{pending_device.id}/approve",
+        json={"label": "dup", "type": "server", "ip": "192.168.1.100",
+              "status": "unknown", "services": [], "design_id": design, "force": True},
+        headers=headers,
+    )
+    assert res.status_code == 200
+    nodes = (await db_session.execute(select(Node).where(Node.design_id == design))).scalars().all()
+    assert len(nodes) == 2  # duplicate deliberately created
+
+
+@pytest.mark.asyncio
+async def test_approve_device_allows_same_ip_on_other_design(
+    client: AsyncClient, headers, db_session, pending_device
+):
+    """The guard is per-design: the same host on a different canvas is fine."""
+    other = await _add_design(db_session, "Lab")
+    target = await _add_design(db_session, "Home")
+    db_session.add(_node(other, ip="192.168.1.100"))  # exists on a DIFFERENT design
+    await db_session.commit()
+
+    res = await client.post(
+        f"/api/v1/scan/pending/{pending_device.id}/approve",
+        json={"label": "ok", "type": "server", "ip": "192.168.1.100",
+              "status": "unknown", "services": [], "design_id": target},
+        headers=headers,
+    )
+    assert res.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_approve_device_places_already_approved_on_another_design(
+    client: AsyncClient, headers, db_session
+):
+    """A device already approved on ANOTHER canvas (global status="approved")
+    must still be placeable on a new design — status is global, canvas
+    membership is per-design (mirrors bulk_approve)."""
+    other = await _add_design(db_session, "Other")
+    target = await _add_design(db_session, "Network Topology")
+    # Device is on `other` already (its global status is "approved").
+    db_session.add(_node(other, ieee="0x00158d0005292b83"))
+    device = InventoryDevice(
+        id=str(uuid.uuid4()), ieee_address="0x00158d0005292b83",
+        suggested_type="zigbee_enddevice", status="approved",
+        discovery_source="zigbee",
+    )
+    db_session.add(device)
+    await db_session.commit()
+
+    res = await client.post(
+        f"/api/v1/scan/pending/{device.id}/approve",
+        json={"label": "sensor", "type": "zigbee_enddevice", "status": "online",
+              "services": [], "design_id": target},
+        headers=headers,
+    )
+    assert res.status_code == 200
+    # A node now exists on the target design too (one per canvas).
+    nodes = (
+        await db_session.execute(
+            select(Node).where(Node.ieee_address == "0x00158d0005292b83")
+        )
+    ).scalars().all()
+    assert {n.design_id for n in nodes} == {other, target}
+
+
+@pytest.mark.asyncio
+async def test_approve_device_rejects_hidden(client: AsyncClient, headers, db_session, pending_device):
+    """A user-hidden device is not approvable via this endpoint."""
+    pending_device.status = "hidden"
+    db_session.add(pending_device)
+    await db_session.commit()
+    res = await client.post(
+        f"/api/v1/scan/pending/{pending_device.id}/approve",
+        json={"label": "x", "type": "server", "status": "unknown", "services": []},
+        headers=headers,
+    )
+    assert res.status_code == 409
+
+
+@pytest.mark.asyncio
+async def test_approve_nonexistent_device(client: AsyncClient, headers):
+    node_payload = {
+        "label": "Ghost",
+        "type": "generic",
+        "ip": "10.0.0.1",
+        "status": "unknown",
+        "services": [],
+    }
+    res = await client.post(
+        "/api/v1/scan/pending/nonexistent-id/approve",
+        json=node_payload,
+        headers=headers,
+    )
+    assert res.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_hide_device(client: AsyncClient, headers, pending_device):
+    res = await client.post(f"/api/v1/scan/pending/{pending_device.id}/hide", headers=headers)
+    assert res.status_code == 200
+    assert res.json()["hidden"] is True
+
+    # Should no longer appear in pending
+    pending_res = await client.get("/api/v1/scan/pending", headers=headers)
+    assert pending_res.json() == []
+
+    # Should appear in hidden
+    hidden_res = await client.get("/api/v1/scan/hidden", headers=headers)
+    assert len(hidden_res.json()) == 1
+
+
+@pytest.mark.asyncio
+async def test_restore_device(client: AsyncClient, headers, pending_device):
+    # Hide first
+    await client.post(f"/api/v1/scan/pending/{pending_device.id}/hide", headers=headers)
+
+    # Restore
+    res = await client.post(f"/api/v1/scan/pending/{pending_device.id}/restore", headers=headers)
+    assert res.status_code == 200
+    assert res.json()["restored"] is True
+
+    # Now back in pending, gone from hidden
+    pending_res = await client.get("/api/v1/scan/pending", headers=headers)
+    assert len(pending_res.json()) == 1
+    hidden_res = await client.get("/api/v1/scan/hidden", headers=headers)
+    assert hidden_res.json() == []
+
+
+@pytest.mark.asyncio
+async def test_restore_device_rejects_non_hidden(client: AsyncClient, headers, pending_device):
+    res = await client.post(f"/api/v1/scan/pending/{pending_device.id}/restore", headers=headers)
+    assert res.status_code == 409
+
+
+@pytest.mark.asyncio
+async def test_bulk_restore_devices(client: AsyncClient, headers, pending_device):
+    # Hide
+    await client.post(f"/api/v1/scan/pending/{pending_device.id}/hide", headers=headers)
+
+    res = await client.post(
+        "/api/v1/scan/pending/bulk-restore",
+        headers=headers,
+        json={"device_ids": [pending_device.id]},
+    )
+    assert res.status_code == 200
+    assert res.json()["restored"] == 1
+    assert res.json()["skipped"] == 0
+
+    pending_res = await client.get("/api/v1/scan/pending", headers=headers)
+    assert len(pending_res.json()) == 1
+
+
+@pytest.mark.asyncio
+async def test_ignore_device(client: AsyncClient, headers, pending_device):
+    res = await client.post(f"/api/v1/scan/pending/{pending_device.id}/ignore", headers=headers)
+    assert res.status_code == 200
+    assert res.json()["ignored"] is True
+
+    # Device should be gone from both pending and hidden
+    pending_res = await client.get("/api/v1/scan/pending", headers=headers)
+    assert pending_res.json() == []
+    hidden_res = await client.get("/api/v1/scan/hidden", headers=headers)
+    assert hidden_res.json() == []
+
+
+@pytest.mark.asyncio
+async def test_bulk_approve_approves_devices(client: AsyncClient, headers, two_device_inventory):
+    ids = [d.id for d in two_device_inventory]
+    res = await client.post("/api/v1/scan/pending/bulk-approve", json={"device_ids": ids}, headers=headers)
+    assert res.status_code == 200
+    data = res.json()
+    assert data["approved"] == 2
+    assert len(data["node_ids"]) == 2
+    assert all(nid is not None for nid in data["node_ids"]), "node_ids must be non-null UUIDs"
+    assert len(data["device_ids"]) == 2
+    assert data["skipped"] == 0
+    # Approved devices stay in the inventory, now marked "approved".
+    pending_res = await client.get("/api/v1/scan/pending", headers=headers)
+    inventory = pending_res.json()
+    assert len(inventory) == 2
+    assert all(d["status"] == "approved" for d in inventory)
+
+
+@pytest.mark.asyncio
+async def test_bulk_approve_places_already_approved_device_on_another_design(
+    client: AsyncClient, headers, db_session, two_device_inventory
+):
+    """Regression: a device already approved (status='approved', e.g. placed on
+    another canvas) must still get a node on the design being approved onto.
+
+    Previously bulk-approve filtered status=='pending', so selecting an
+    already-approved device created no node — the user saw fewer nodes than
+    they selected."""
+    ids = [d.id for d in two_device_inventory]
+    design_a = await _add_design(db_session, "Canvas A")
+    design_b = await _add_design(db_session, "Canvas B")
+
+    # Approve both onto design A.
+    res_a = await client.post(
+        "/api/v1/scan/pending/bulk-approve",
+        json={"device_ids": ids, "design_id": design_a},
+        headers=headers,
+    )
+    assert res_a.json()["approved"] == 2
+
+    # Re-approve the same (now status='approved') devices onto design B.
+    res_b = await client.post(
+        "/api/v1/scan/pending/bulk-approve",
+        json={"device_ids": ids, "design_id": design_b},
+        headers=headers,
+    )
+    data_b = res_b.json()
+    assert data_b["approved"] == 2, "already-approved devices must place onto the new canvas"
+    assert data_b["skipped"] == 0
+
+    # Two nodes now exist on each design.
+    from app.db.models import Node as NodeModel
+    nodes_b = (
+        await db_session.execute(select(NodeModel).where(NodeModel.design_id == design_b))
+    ).scalars().all()
+    assert len(nodes_b) == 2
+
+
+@pytest.mark.asyncio
+async def test_bulk_approve_skips_device_already_on_target_design(
+    client: AsyncClient, headers, db_session, two_device_inventory
+):
+    """A device already on the target canvas (same ip) is not placed twice."""
+    ids = [d.id for d in two_device_inventory]
+    design = await _add_design(db_session, "Canvas")
+    # First device already sits on the canvas (matched by ip).
+    db_session.add(_node(design, ip="192.168.1.10"))
+    await db_session.commit()
+
+    res = await client.post(
+        "/api/v1/scan/pending/bulk-approve",
+        json={"device_ids": ids, "design_id": design},
+        headers=headers,
+    )
+    data = res.json()
+    assert data["approved"] == 1   # only the second device (192.168.1.11)
+    assert data["skipped"] == 1
+
+    from app.db.models import Node as NodeModel
+    nodes = (
+        await db_session.execute(select(NodeModel).where(NodeModel.design_id == design))
+    ).scalars().all()
+    # The pre-existing node plus the one newly approved — no duplicate for .10.
+    assert len(nodes) == 2
+    assert sorted(n.ip for n in nodes) == ["192.168.1.10", "192.168.1.11"]
+
+
+@pytest.mark.asyncio
+async def test_bulk_approve_skips_device_matching_ip_in_comma_list(
+    client: AsyncClient, headers, db_session, two_device_inventory
+):
+    """The on-canvas node's ip holds an IPv6 before the IPv4; the device scanned
+    as the plain IPv4 is still recognised as already placed (issue #258)."""
+    ids = [d.id for d in two_device_inventory]
+    design = await _add_design(db_session, "Canvas")
+    db_session.add(_node(design, ip="fe80::1, 192.168.1.10"))
+    await db_session.commit()
+
+    res = await client.post(
+        "/api/v1/scan/pending/bulk-approve",
+        json={"device_ids": ids, "design_id": design},
+        headers=headers,
+    )
+    data = res.json()
+    assert data["approved"] == 1   # only the second device (192.168.1.11)
+    assert data["skipped"] == 1
+    assert data["skipped_devices"][0]["value"] == "192.168.1.10"
+
+
+@pytest.mark.asyncio
+async def test_bulk_approve_reports_skipped_devices(
+    client: AsyncClient, headers, db_session, two_device_inventory
+):
+    """Bulk can't prompt per-device, so it reports each duplicate it skipped
+    (with the existing node id) instead of silently dropping it."""
+    ids = [d.id for d in two_device_inventory]
+    design = await _add_design(db_session, "Canvas")
+    existing = _node(design, ip="192.168.1.10")
+    db_session.add(existing)
+    await db_session.commit()
+
+    res = await client.post(
+        "/api/v1/scan/pending/bulk-approve",
+        json={"device_ids": ids, "design_id": design},
+        headers=headers,
+    )
+    data = res.json()
+    assert data["approved"] == 1
+    skipped = data["skipped_devices"]
+    assert len(skipped) == 1
+    entry = skipped[0]
+    assert entry["match"] == "ip"
+    assert entry["value"] == "192.168.1.10"
+    assert entry["existing_node_id"] == existing.id
+    assert entry["device_id"] in ids
+
+
+@pytest.mark.asyncio
+async def test_approve_device_copies_mac_to_node_and_properties(
+    client: AsyncClient, headers, pending_device, db_session
+):
+    """Approving a scanned device must carry its MAC onto the node + properties."""
+    from sqlalchemy import select
+
+    from app.db.models import Node as NodeModel
+    # Payload intentionally omits mac — it must come from the pending device.
+    res = await client.post(
+        f"/api/v1/scan/pending/{pending_device.id}/approve",
+        json={"label": "My Server", "type": "server", "ip": "192.168.1.100", "status": "unknown", "services": []},
+        headers=headers,
+    )
+    assert res.status_code == 200
+    node = (
+        await db_session.execute(select(NodeModel).where(NodeModel.ip == "192.168.1.100"))
+    ).scalar_one()
+    assert node.mac == "aa:bb:cc:dd:ee:ff"
+    mac_props = [p for p in node.properties if p["key"] == "MAC"]
+    assert mac_props == [
+        {"key": "MAC", "value": "aa:bb:cc:dd:ee:ff", "icon": None, "visible": False}
+    ]
+
+
+@pytest.mark.asyncio
+async def test_bulk_approve_copies_mac_to_node_and_properties(
+    client: AsyncClient, headers, db_session
+):
+    """Bulk approve must also propagate the scanned MAC to node + properties."""
+    from sqlalchemy import select
+
+    from app.db.models import Node as NodeModel
+    device = InventoryDevice(
+        id=str(uuid.uuid4()),
+        ip="192.168.1.55",
+        mac="11:22:33:44:55:66",
+        hostname="host-mac",
+        services=[],
+        suggested_type="generic",
+        status="pending",
+    )
+    db_session.add(device)
+    await db_session.commit()
+
+    res = await client.post(
+        "/api/v1/scan/pending/bulk-approve",
+        json={"device_ids": [device.id]},
+        headers=headers,
+    )
+    assert res.status_code == 200
+    node = (
+        await db_session.execute(select(NodeModel).where(NodeModel.ip == "192.168.1.55"))
+    ).scalar_one()
+    assert node.mac == "11:22:33:44:55:66"
+    mac_props = [p for p in node.properties if p["key"] == "MAC"]
+    assert mac_props == [
+        {"key": "MAC", "value": "11:22:33:44:55:66", "icon": None, "visible": False}
+    ]
+
+
+@pytest.mark.asyncio
+async def test_bulk_approve_sets_default_check_method(client: AsyncClient, headers, two_device_inventory, db_session):
+    """Approved devices with an IP must default to ping; otherwise scheduler skips them."""
+    from sqlalchemy import select
+
+    from app.db.models import Node as NodeModel
+    ids = [d.id for d in two_device_inventory]
+    res = await client.post("/api/v1/scan/pending/bulk-approve", json={"device_ids": ids}, headers=headers)
+    assert res.status_code == 200
+    nodes = (await db_session.execute(select(NodeModel))).scalars().all()
+    for n in nodes:
+        if n.ip:
+            assert n.check_method == "ping", f"node {n.id} created without check_method"
+
+
+@pytest.mark.asyncio
+async def test_approve_device_sets_default_check_method(client: AsyncClient, headers, pending_device, db_session):
+    from sqlalchemy import select
+
+    from app.db.models import Node as NodeModel
+    res = await client.post(
+        f"/api/v1/scan/pending/{pending_device.id}/approve",
+        json={"label": "h", "type": "generic", "ip": "192.168.1.10", "status": "unknown", "services": []},
+        headers=headers,
+    )
+    assert res.status_code == 200
+    node = (await db_session.execute(select(NodeModel))).scalars().first()
+    assert node is not None
+    assert node.check_method == "ping"
+
+
+@pytest.mark.asyncio
+async def test_bulk_approve_skips_already_approved(client: AsyncClient, headers, two_device_inventory):
+    ids = [d.id for d in two_device_inventory]
+    # Approve first device individually first
+    await client.post(
+        f"/api/v1/scan/pending/{ids[0]}/approve",
+        json={"label": "h", "type": "generic", "ip": "192.168.1.10", "status": "unknown", "services": []},
+        headers=headers,
+    )
+    # Bulk approve both — first one is already approved (not pending), should be skipped
+    res = await client.post("/api/v1/scan/pending/bulk-approve", json={"device_ids": ids}, headers=headers)
+    assert res.status_code == 200
+    data = res.json()
+    assert data["approved"] == 1
+    assert data["skipped"] == 1
+
+
+@pytest.mark.asyncio
+async def test_bulk_approve_requires_auth(client: AsyncClient, two_device_inventory):
+    ids = [d.id for d in two_device_inventory]
+    res = await client.post("/api/v1/scan/pending/bulk-approve", json={"device_ids": ids})
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_bulk_hide_hides_devices(client: AsyncClient, headers, two_device_inventory):
+    ids = [d.id for d in two_device_inventory]
+    res = await client.post("/api/v1/scan/pending/bulk-hide", json={"device_ids": ids}, headers=headers)
+    assert res.status_code == 200
+    data = res.json()
+    assert data["hidden"] == 2
+    assert data["skipped"] == 0
+    # Should appear in hidden list
+    hidden_res = await client.get("/api/v1/scan/hidden", headers=headers)
+    assert len(hidden_res.json()) == 2
+
+
+@pytest.mark.asyncio
+async def test_bulk_hide_skips_non_pending(client: AsyncClient, headers, two_device_inventory):
+    ids = [d.id for d in two_device_inventory]
+    # Hide first device individually first
+    await client.post(f"/api/v1/scan/pending/{ids[0]}/hide", headers=headers)
+    # Bulk hide both — first is already hidden (not pending anymore)
+    res = await client.post("/api/v1/scan/pending/bulk-hide", json={"device_ids": ids}, headers=headers)
+    assert res.status_code == 200
+    data = res.json()
+    assert data["hidden"] == 1
+    assert data["skipped"] == 1
+
+
+@pytest.mark.asyncio
+async def test_bulk_hide_requires_auth(client: AsyncClient, two_device_inventory):
+    ids = [d.id for d in two_device_inventory]
+    res = await client.post("/api/v1/scan/pending/bulk-hide", json={"device_ids": ids})
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_bulk_approve_targets_requested_design(client, headers, db_session):
+    """bulk-approve must place nodes on the design_id sent by the UI, not the
+    first design — otherwise approved devices land on the wrong canvas."""
+    first = await _add_design(db_session, "Default")  # first design (fallback)
+    active = await _add_design(db_session, "zwave")    # the design the user is on
+    dev = InventoryDevice(
+        id=str(uuid.uuid4()),
+        ieee_address="zwave-H-2",
+        friendly_name="Living Room Plug",
+        suggested_type="zwave_router",
+        device_subtype="Router",
+        vendor="Aeotec",
+        model="ZW096",
+        status="pending",
+        discovery_source="zwave",
+    )
+    db_session.add(dev)
+    await db_session.commit()
+
+    res = await client.post(
+        "/api/v1/scan/pending/bulk-approve",
+        json={"device_ids": [dev.id], "design_id": active},
+        headers=headers,
+    )
+    assert res.status_code == 200
+    assert res.json()["approved"] == 1
+
+    node = (
+        await db_session.execute(select(Node).where(Node.ieee_address == "zwave-H-2"))
+    ).scalar_one()
+    assert node.design_id == active
+    assert node.design_id != first
+    # Z-Wave device → online + Z-Wave property rows, no ICMP check.
+    assert node.status == "online"
+    assert node.check_method == "none"
+    assert {p["key"] for p in node.properties} == {"Z-Wave ID", "Vendor", "Model"}

backend/tests/scan/test_scan_properties.py

@@ -0,0 +1,336 @@
+"""MAC-property builders and Zigbee/Z-Wave property population on approve."""
+import uuid
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy import select
+
+from app.db.models import InventoryDevice, Node
+from tests.scan.helpers import _add_design, _seed_zigbee_pending_pair
+
+
+@pytest.mark.asyncio
+async def test_approve_zigbee_device_populates_properties(
+    client: AsyncClient, headers, zigbee_pending_device, db_session
+):
+    """Approving a zigbee device must populate IEEE/Vendor/Model/LQI in properties."""
+    from sqlalchemy import select
+
+    from app.db.models import Node as NodeModel
+    payload = {
+        "label": "bulb_1",
+        "type": "zigbee_enddevice",
+        "status": "online",
+        "services": [],
+        "check_method": "none",
+    }
+    res = await client.post(
+        f"/api/v1/scan/pending/{zigbee_pending_device.id}/approve",
+        json=payload,
+        headers=headers,
+    )
+    assert res.status_code == 200
+    node = (
+        await db_session.execute(select(NodeModel).where(NodeModel.ieee_address == "0xABCDEF"))
+    ).scalar_one()
+    keys = {p["key"]: p["value"] for p in node.properties}
+    assert keys == {
+        "IEEE": "0xABCDEF",
+        "Vendor": "IKEA",
+        "Model": "TRADFRI",
+        "LQI": "180",
+    }
+
+
+@pytest.mark.asyncio
+async def test_bulk_approve_zigbee_populates_properties(
+    client: AsyncClient, headers, zigbee_pending_device, db_session
+):
+    from sqlalchemy import select
+
+    from app.db.models import Node as NodeModel
+    res = await client.post(
+        "/api/v1/scan/pending/bulk-approve",
+        json={"device_ids": [zigbee_pending_device.id]},
+        headers=headers,
+    )
+    assert res.status_code == 200
+    node = (
+        await db_session.execute(select(NodeModel).where(NodeModel.ieee_address == "0xABCDEF"))
+    ).scalar_one()
+    keys = {p["key"]: p["value"] for p in node.properties}
+    assert keys["IEEE"] == "0xABCDEF"
+    assert keys["Vendor"] == "IKEA"
+    assert keys["Model"] == "TRADFRI"
+    assert keys["LQI"] == "180"
+    assert node.check_method == "none"
+
+
+def test_build_mac_property_returns_hidden_row():
+    from app.api.routes.scan import build_mac_property
+
+    assert build_mac_property("aa:bb:cc:dd:ee:ff") == [
+        {"key": "MAC", "value": "aa:bb:cc:dd:ee:ff", "icon": None, "visible": False}
+    ]
+
+
+def test_build_mac_property_empty_when_no_mac():
+    from app.api.routes.scan import build_mac_property
+
+    assert build_mac_property(None) == []
+    assert build_mac_property("") == []
+
+
+def test_merge_mac_property_appends_when_absent():
+    from app.api.routes.scan import merge_mac_property
+
+    existing = [{"key": "Custom", "value": "x", "icon": None, "visible": True}]
+    merged = merge_mac_property(existing, "aa:bb:cc:dd:ee:ff")
+    assert {"key": "MAC", "value": "aa:bb:cc:dd:ee:ff", "icon": None, "visible": False} in merged
+    # Existing prop preserved untouched.
+    assert existing[0] in merged
+
+
+def test_merge_mac_property_idempotent_and_preserves_visibility():
+    from app.api.routes.scan import merge_mac_property
+
+    existing = [{"key": "MAC", "value": "aa:bb:cc:dd:ee:ff", "icon": None, "visible": True}]
+    merged = merge_mac_property(existing, "aa:bb:cc:dd:ee:ff")
+    # No duplicate MAC row; user's visible=True choice kept.
+    macs = [p for p in merged if p["key"] == "MAC"]
+    assert len(macs) == 1
+    assert macs[0]["visible"] is True
+
+
+def test_merge_mac_property_noop_without_mac():
+    from app.api.routes.scan import merge_mac_property
+
+    existing = [{"key": "Custom", "value": "x", "icon": None, "visible": True}]
+    assert merge_mac_property(existing, None) == existing
+
+
+@pytest.mark.asyncio
+async def test_approve_device_does_not_duplicate_mac_property(
+    client: AsyncClient, headers, pending_device, db_session
+):
+    """If the approve payload already carries a MAC prop, don't add a second one."""
+    from sqlalchemy import select
+
+    from app.db.models import Node as NodeModel
+    res = await client.post(
+        f"/api/v1/scan/pending/{pending_device.id}/approve",
+        json={
+            "label": "My Server",
+            "type": "server",
+            "ip": "192.168.1.100",
+            "status": "unknown",
+            "services": [],
+            "properties": [
+                {"key": "MAC", "value": "aa:bb:cc:dd:ee:ff", "icon": None, "visible": True}
+            ],
+        },
+        headers=headers,
+    )
+    assert res.status_code == 200
+    node = (
+        await db_session.execute(select(NodeModel).where(NodeModel.ip == "192.168.1.100"))
+    ).scalar_one()
+    mac_props = [p for p in node.properties if p["key"] == "MAC"]
+    assert len(mac_props) == 1
+    # User's visibility choice is preserved.
+    assert mac_props[0]["visible"] is True
+
+
+@pytest.mark.asyncio
+async def test_approve_zigbee_creates_edge_when_other_endpoint_is_node(
+    client: AsyncClient, headers, db_session
+):
+    from sqlalchemy import select
+
+    from app.db.models import Edge
+
+    coord, pending = await _seed_zigbee_pending_pair(db_session)
+
+    res = await client.post(
+        f"/api/v1/scan/pending/{pending.id}/approve",
+        json={
+            "label": "router_1",
+            "type": "zigbee_router",
+            "ip": None,
+            "status": "unknown",
+            "services": [],
+        },
+        headers=headers,
+    )
+    assert res.status_code == 200
+    data = res.json()
+    assert data["approved"] is True
+    assert data["edges_created"] == 1
+
+    edges = (await db_session.execute(select(Edge))).scalars().all()
+    assert len(edges) == 1
+    assert edges[0].source == coord.id
+    assert edges[0].target == data["node_id"]
+    assert edges[0].source_handle == "bottom"
+    # Bare side name (canonical stored form); renders at the top like before.
+    assert edges[0].target_handle == "top"
+    assert edges[0].type == "iot"
+
+
+@pytest.mark.asyncio
+async def test_approve_zigbee_skips_duplicate_edge(
+    client: AsyncClient, headers, db_session
+):
+    """Re-running the resolution does not create a second edge for the same pair."""
+    from sqlalchemy import select
+
+    from app.db.models import Edge, InventoryDevice, InventoryDeviceLink
+
+    coord, pending = await _seed_zigbee_pending_pair(db_session)
+    body = {"label": "router_1", "type": "zigbee_router", "ip": None, "status": "unknown", "services": []}
+    await client.post(f"/api/v1/scan/pending/{pending.id}/approve", json=body, headers=headers)
+
+    # Simulate a second pending row + link between same coord and a new device,
+    # but keep an existing edge in place to verify dedupe also handles
+    # the swapped-direction case.
+    new_pending = InventoryDevice(
+        ieee_address="0xR1B",
+        friendly_name="r1b",
+        suggested_type="zigbee_router",
+        status="pending",
+        discovery_source="zigbee",
+    )
+    db_session.add(new_pending)
+    db_session.add(
+        InventoryDeviceLink(source_ieee="0xCOORD", target_ieee="0xR1B", discovery_source="zigbee")
+    )
+    await db_session.commit()
+    res = await client.post(
+        f"/api/v1/scan/pending/{new_pending.id}/approve", json=body, headers=headers
+    )
+    assert res.json()["edges_created"] == 1  # only the new pair
+    edges = (await db_session.execute(select(Edge))).scalars().all()
+    assert len(edges) == 2  # original + new, no duplicate
+
+
+@pytest.mark.asyncio
+async def test_approve_zigbee_skips_when_other_endpoint_still_pending(
+    client: AsyncClient, headers, db_session
+):
+    """Both endpoints pending → no edge yet, link row preserved for later."""
+    from sqlalchemy import select
+
+    from app.db.models import Edge, InventoryDevice, InventoryDeviceLink
+
+    a = InventoryDevice(
+        ieee_address="0xA",
+        friendly_name="a",
+        suggested_type="zigbee_router",
+        status="pending",
+        discovery_source="zigbee",
+    )
+    b = InventoryDevice(
+        ieee_address="0xB",
+        friendly_name="b",
+        suggested_type="zigbee_enddevice",
+        status="pending",
+        discovery_source="zigbee",
+    )
+    db_session.add_all([a, b])
+    db_session.add(
+        InventoryDeviceLink(source_ieee="0xA", target_ieee="0xB", discovery_source="zigbee")
+    )
+    await db_session.commit()
+
+    res = await client.post(
+        f"/api/v1/scan/pending/{a.id}/approve",
+        json={
+            "label": "a",
+            "type": "zigbee_router",
+            "ip": None,
+            "status": "unknown",
+            "services": [],
+        },
+        headers=headers,
+    )
+    assert res.status_code == 200
+    assert res.json()["edges_created"] == 0
+
+    edges = (await db_session.execute(select(Edge))).scalars().all()
+    assert edges == []
+    links = (await db_session.execute(select(InventoryDeviceLink))).scalars().all()
+    assert len(links) == 1  # preserved for later resolution
+
+
+@pytest.mark.asyncio
+async def test_approve_zigbee_resolves_link_after_second_approval(
+    client: AsyncClient, headers, db_session
+):
+    """First approval keeps link (other endpoint pending); second approval
+    creates the edge. The link row is retained afterwards so the same pair can
+    be re-approved onto another canvas — it's topology, wiped only on reimport."""
+    from sqlalchemy import select
+
+    from app.db.models import Edge, InventoryDevice, InventoryDeviceLink
+
+    a = InventoryDevice(
+        ieee_address="0xA",
+        friendly_name="a",
+        suggested_type="zigbee_router",
+        status="pending",
+        discovery_source="zigbee",
+    )
+    b = InventoryDevice(
+        ieee_address="0xB",
+        friendly_name="b",
+        suggested_type="zigbee_enddevice",
+        status="pending",
+        discovery_source="zigbee",
+    )
+    db_session.add_all([a, b])
+    db_session.add(
+        InventoryDeviceLink(source_ieee="0xA", target_ieee="0xB", discovery_source="zigbee")
+    )
+    await db_session.commit()
+
+    body = {"label": "x", "type": "zigbee_router", "ip": None, "status": "unknown", "services": []}
+    await client.post(f"/api/v1/scan/pending/{a.id}/approve", json=body, headers=headers)
+    res = await client.post(f"/api/v1/scan/pending/{b.id}/approve", json=body, headers=headers)
+    assert res.json()["edges_created"] == 1
+
+    edges = (await db_session.execute(select(Edge))).scalars().all()
+    assert len(edges) == 1
+    links = (await db_session.execute(select(InventoryDeviceLink))).scalars().all()
+    assert len(links) == 1  # retained for re-approval onto other canvases
+
+
+@pytest.mark.asyncio
+async def test_single_approve_zwave_sets_wireless_fields(client, headers, db_session):
+    active = await _add_design(db_session, "zwave")
+    dev = InventoryDevice(
+        id=str(uuid.uuid4()),
+        ieee_address="zwave-H-9",
+        friendly_name="Door Sensor",
+        suggested_type="zwave_enddevice",
+        vendor="Aeotec",
+        model="ZW120",
+        status="pending",
+        discovery_source="zwave",
+    )
+    db_session.add(dev)
+    await db_session.commit()
+
+    res = await client.post(
+        f"/api/v1/scan/pending/{dev.id}/approve",
+        json={"label": "Door Sensor", "type": "zwave_enddevice", "design_id": active},
+        headers=headers,
+    )
+    assert res.status_code == 200
+
+    node = (
+        await db_session.execute(select(Node).where(Node.ieee_address == "zwave-H-9"))
+    ).scalar_one()
+    assert node.design_id == active
+    assert node.status == "online"
+    assert node.check_method == "none"
+    assert any(p["key"] == "Z-Wave ID" for p in node.properties)

backend/tests/scan/test_scan_routes.py

@@ -0,0 +1,370 @@
+"""Scan API routes: trigger, pending list, canvas-count correlation, timestamps, config."""
+import uuid
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from httpx import AsyncClient
+
+from app.db.models import InventoryDevice
+from tests.scan.helpers import _add_design, _node
+
+
+@pytest.mark.asyncio
+async def test_trigger_scan_requires_auth(client: AsyncClient):
+    res = await client.post("/api/v1/scan/trigger")
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_trigger_scan_creates_run(client: AsyncClient, headers):
+    with (
+        patch("app.api.routes.scan._background_scan", new_callable=AsyncMock),
+        patch("app.api.routes.scan.settings") as mock_settings,
+    ):
+        mock_settings.scanner_ranges = ["192.168.1.0/24"]
+        res = await client.post("/api/v1/scan/trigger", headers=headers)
+    assert res.status_code == 200
+    data = res.json()
+    assert data["status"] == "running"
+    assert data["ranges"] == ["192.168.1.0/24"]
+    assert "id" in data
+
+
+@pytest.mark.asyncio
+async def test_list_pending_empty(client: AsyncClient, headers):
+    res = await client.get("/api/v1/scan/pending", headers=headers)
+    assert res.status_code == 200
+    assert res.json() == []
+
+
+@pytest.mark.asyncio
+async def test_list_pending_returns_device(client: AsyncClient, headers, pending_device):
+    res = await client.get("/api/v1/scan/pending", headers=headers)
+    assert res.status_code == 200
+    data = res.json()
+    assert len(data) == 1
+    assert data[0]["ip"] == "192.168.1.100"
+    assert data[0]["hostname"] == "my-server"
+    # No matching node → not on any canvas.
+    assert data[0]["canvas_count"] == 0
+
+
+@pytest.mark.asyncio
+async def test_canvas_count_matches_ip_in_comma_list(client, headers, db_session, pending_device):
+    # Node.ip holds several comma-separated addresses (IPv6 added first). The
+    # device scanned as the plain IPv4 must still correlate (issue #258).
+    d1 = await _add_design(db_session, "Home")
+    db_session.add(_node(d1, ip="fe80::1, 192.168.1.100"))
+    await db_session.commit()
+
+    data = (await client.get("/api/v1/scan/pending", headers=headers)).json()
+    assert data[0]["canvas_count"] == 1
+
+
+@pytest.mark.asyncio
+async def test_canvas_count_correlates_by_mac(client, headers, db_session, pending_device):
+    # Node's ip differs entirely (user edited it) but the MAC still matches:
+    # the device is on the canvas (issue #258, MAC is the stable identifier).
+    d1 = await _add_design(db_session, "Home")
+    db_session.add(_node(d1, ip="10.9.9.9", mac="aa:bb:cc:dd:ee:ff"))
+    await db_session.commit()
+
+    data = (await client.get("/api/v1/scan/pending", headers=headers)).json()
+    assert data[0]["canvas_count"] == 1
+
+
+@pytest.mark.asyncio
+async def test_canvas_count_counts_distinct_designs_by_ip(client, headers, db_session, pending_device):
+    # Same IP placed on two different canvases → canvas_count == 2.
+    d1 = await _add_design(db_session, "Home")
+    d2 = await _add_design(db_session, "Lab")
+    db_session.add(_node(d1, ip="192.168.1.100"))
+    db_session.add(_node(d2, ip="192.168.1.100"))
+    await db_session.commit()
+
+    res = await client.get("/api/v1/scan/pending", headers=headers)
+    data = res.json()
+    assert len(data) == 1
+    assert data[0]["canvas_count"] == 2
+
+
+@pytest.mark.asyncio
+async def test_canvas_count_correlates_by_ieee(client, headers, db_session):
+    device = InventoryDevice(
+        id=str(uuid.uuid4()), ieee_address="0x00124b001", discovery_source="zigbee",
+        suggested_type="zigbee_enddevice", services=[], status="pending",
+    )
+    db_session.add(device)
+    d1 = await _add_design(db_session, "Zigbee")
+    db_session.add(_node(d1, ieee="0x00124b001"))
+    await db_session.commit()
+
+    res = await client.get("/api/v1/scan/pending", headers=headers)
+    by_id = {d["id"]: d for d in res.json()}
+    assert by_id[device.id]["canvas_count"] == 1
+
+
+@pytest.mark.asyncio
+async def test_pending_device_without_node_has_null_node_timestamps(client, headers, pending_device):
+    # No matching canvas node → node_* timestamps are all null; the device still
+    # carries its own discovered_at for the "Discovered" fallback on the tile.
+    data = (await client.get("/api/v1/scan/pending", headers=headers)).json()[0]
+    assert data["discovered_at"] is not None
+    assert data["node_created_at"] is None
+    assert data["node_last_scan"] is None
+    assert data["node_last_modified"] is None
+    assert data["node_last_seen"] is None
+
+
+@pytest.mark.asyncio
+async def test_pending_device_exposes_linked_node_timestamps(client, headers, db_session, pending_device):
+    d1 = await _add_design(db_session, "Home")
+    node = _node(d1, ip="192.168.1.100")
+    node.last_scan = datetime(2026, 6, 1, 8, 30, tzinfo=timezone.utc)
+    node.last_seen = datetime(2026, 6, 25, 9, 15, tzinfo=timezone.utc)
+    db_session.add(node)
+    await db_session.commit()
+
+    data = (await client.get("/api/v1/scan/pending", headers=headers)).json()[0]
+    assert data["node_created_at"] is not None      # defaulted on insert
+    assert data["node_last_modified"] is not None    # updated_at defaulted on insert
+    assert data["node_last_scan"].startswith("2026-06-01")
+    assert data["node_last_seen"].startswith("2026-06-25")
+
+
+@pytest.mark.asyncio
+async def test_node_timestamps_aggregate_across_matches(client, headers, db_session, pending_device):
+    # Two canvas nodes share the device IP: created_at takes the OLDEST,
+    # last_scan takes the NEWEST.
+    d1 = await _add_design(db_session, "Home")
+    d2 = await _add_design(db_session, "Lab")
+    older = _node(d1, ip="192.168.1.100")
+    older.created_at = datetime(2026, 1, 1, 0, 0, tzinfo=timezone.utc)
+    older.last_scan = datetime(2026, 3, 1, 0, 0, tzinfo=timezone.utc)
+    newer = _node(d2, ip="192.168.1.100")
+    newer.created_at = datetime(2026, 5, 1, 0, 0, tzinfo=timezone.utc)
+    newer.last_scan = datetime(2026, 6, 1, 0, 0, tzinfo=timezone.utc)
+    db_session.add_all([older, newer])
+    await db_session.commit()
+
+    data = (await client.get("/api/v1/scan/pending", headers=headers)).json()[0]
+    assert data["node_created_at"].startswith("2026-01-01")  # oldest
+    assert data["node_last_scan"].startswith("2026-06-01")   # newest
+
+
+@pytest.mark.asyncio
+async def test_resolve_deep_scan_falls_back_to_settings():
+    from app.api.routes.scan import TriggerScanRequest, _resolve_deep_scan
+
+    with patch("app.api.routes.scan.settings") as mock_settings:
+        mock_settings.scanner_http_ranges = ["7000-7100"]
+        mock_settings.scanner_http_probe_enabled = True
+        mock_settings.scanner_http_verify_tls = False
+        # Empty payload → all values come from settings defaults
+        ds = _resolve_deep_scan(TriggerScanRequest())
+    assert ds.http_ranges == ["7000-7100"]
+    assert ds.http_probe_enabled is True
+    assert ds.verify_tls is False
+
+
+@pytest.mark.asyncio
+async def test_resolve_deep_scan_override_wins():
+    from app.api.routes.scan import TriggerScanRequest, _resolve_deep_scan
+
+    with patch("app.api.routes.scan.settings") as mock_settings:
+        mock_settings.scanner_http_ranges = []
+        mock_settings.scanner_http_probe_enabled = False
+        mock_settings.scanner_http_verify_tls = False
+        ds = _resolve_deep_scan(
+            TriggerScanRequest(http_ranges=["9000"], http_probe_enabled=True, verify_tls=True)
+        )
+    assert ds.http_ranges == ["9000"]
+    assert ds.http_probe_enabled is True
+    assert ds.verify_tls is True
+
+
+@pytest.mark.asyncio
+async def test_trigger_scan_passes_deep_scan_options(client: AsyncClient, headers):
+    captured = {}
+
+    async def fake_bg(run_id, ranges, deep_scan):
+        captured["deep_scan"] = deep_scan
+
+    with (
+        patch("app.api.routes.scan._background_scan", new=fake_bg),
+        patch("app.api.routes.scan.settings") as mock_settings,
+    ):
+        mock_settings.scanner_ranges = ["192.168.1.0/24"]
+        mock_settings.scanner_http_ranges = []
+        mock_settings.scanner_http_probe_enabled = False
+        mock_settings.scanner_http_verify_tls = False
+        res = await client.post(
+            "/api/v1/scan/trigger",
+            json={"http_probe_enabled": True, "http_ranges": ["8000-8100"]},
+            headers=headers,
+        )
+    assert res.status_code == 200
+    assert captured["deep_scan"].http_probe_enabled is True
+    assert captured["deep_scan"].http_ranges == ["8000-8100"]
+
+
+@pytest.mark.asyncio
+async def test_trigger_scan_rejects_invalid_port_range(client: AsyncClient, headers):
+    with patch("app.api.routes.scan.settings") as mock_settings:
+        mock_settings.scanner_ranges = ["192.168.1.0/24"]
+        res = await client.post(
+            "/api/v1/scan/trigger",
+            json={"http_ranges": ["70000-80000"]},
+            headers=headers,
+        )
+    assert res.status_code == 422
+
+
+@pytest.mark.asyncio
+async def test_get_scan_config_includes_deep_scan(client: AsyncClient, headers):
+    with patch("app.api.routes.scan.settings") as mock_settings:
+        mock_settings.scanner_ranges = ["192.168.1.0/24"]
+        mock_settings.scanner_http_ranges = ["8000-8100"]
+        mock_settings.scanner_http_probe_enabled = True
+        mock_settings.scanner_http_verify_tls = False
+        res = await client.get("/api/v1/scan/config", headers=headers)
+    assert res.status_code == 200
+    data = res.json()
+    assert data["http_ranges"] == ["8000-8100"]
+    assert data["http_probe_enabled"] is True
+
+
+@pytest.mark.asyncio
+async def test_update_scan_config_persists_deep_scan(client: AsyncClient, headers):
+    saved = {}
+
+    with patch("app.api.routes.scan.settings") as mock_settings:
+        mock_settings.scanner_ranges = ["192.168.1.0/24"]
+        mock_settings.scanner_http_ranges = []
+        mock_settings.scanner_http_probe_enabled = False
+        mock_settings.scanner_http_verify_tls = False
+        mock_settings.save_overrides = lambda: saved.update(
+            http_ranges=mock_settings.scanner_http_ranges,
+            probe=mock_settings.scanner_http_probe_enabled,
+        )
+        res = await client.post(
+            "/api/v1/scan/config",
+            json={
+                "ranges": ["192.168.1.0/24"],
+                "http_ranges": ["9000-9100"],
+                "http_probe_enabled": True,
+                "verify_tls": True,
+            },
+            headers=headers,
+        )
+    assert res.status_code == 200
+    assert saved == {"http_ranges": ["9000-9100"], "probe": True}
+
+
+@pytest.mark.asyncio
+async def test_create_pending_normalizes_the_mac(client: AsyncClient, headers):
+    # Dedup compares MACs by equality, so a hand-typed entry in any other
+    # notation would never match the scanned row and approve would build a
+    # duplicate node.
+    res = await client.post(
+        "/api/v1/scan/pending",
+        json={
+            "hostname": "printer",
+            "mac": "AA-BB-CC-11-22-33",
+            "discovery_source": "manual",
+        },
+        headers=headers,
+    )
+    assert res.status_code == 201, res.text
+    assert res.json()["mac"] == "aa:bb:cc:11:22:33"
+
+
+@pytest.mark.asyncio
+async def test_create_pending_keeps_a_missing_mac_null(client: AsyncClient, headers):
+    res = await client.post(
+        "/api/v1/scan/pending",
+        json={"hostname": "no-mac", "discovery_source": "manual"},
+        headers=headers,
+    )
+    assert res.status_code == 201, res.text
+    assert res.json()["mac"] is None
+
+
+@pytest.mark.asyncio
+async def test_delete_pending_removes_one_entry(client: AsyncClient, headers, pending_device):
+    # The rack canvas drops the placeholder it created for a plate once that
+    # plate is pointed at a real inventory row.
+    res = await client.delete(f"/api/v1/scan/pending/{pending_device.id}", headers=headers)
+    assert res.status_code == 200, res.text
+    assert res.json() == {"deleted": True}
+
+    listed = (await client.get("/api/v1/scan/pending", headers=headers)).json()
+    assert listed == []
+
+
+@pytest.mark.asyncio
+async def test_delete_pending_unknown_is_404(client: AsyncClient, headers):
+    res = await client.delete(f"/api/v1/scan/pending/{uuid.uuid4()}", headers=headers)
+    assert res.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_delete_pending_requires_auth(client: AsyncClient, pending_device):
+    res = await client.delete(f"/api/v1/scan/pending/{pending_device.id}")
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_delete_pending_refuses_a_mounted_device(client: AsyncClient, headers, pending_device):
+    # `rack_devices.device_id` is ON DELETE SET NULL: without this guard the
+    # delete would strip the mount of its device instead of erroring.
+    design = (
+        await client.post(
+            "/api/v1/designs",
+            json={"name": "Rack Room", "icon": "server", "design_type": "rack"},
+            headers=headers,
+        )
+    ).json()["id"]
+    saved = await client.post(
+        "/api/v1/racks/save",
+        json={
+            "design_id": design,
+            "racks": [
+                {
+                    "id": "rack-1",
+                    "name": "Main",
+                    "u_height": 12,
+                    "width_standard": "19",
+                    "numbering": "bottom-up",
+                    "style": {},
+                    "pos_x": 0,
+                    "pos_y": 0,
+                }
+            ],
+            "devices": [
+                {
+                    "id": "dev-1",
+                    "rack_id": "rack-1",
+                    "device_id": pending_device.id,
+                    "label": "my-server",
+                    "u_start": 1,
+                    "u_height": 1,
+                    "col_start": 0,
+                    "col_span": 12,
+                    "faceplate_id": "server-1u",
+                    "status": "unknown",
+                    "ports": [],
+                }
+            ],
+            "cables": [],
+            "viewport": {"x": 0, "y": 0, "zoom": 1},
+        },
+        headers=headers,
+    )
+    assert saved.status_code == 200, saved.text
+
+    res = await client.delete(f"/api/v1/scan/pending/{pending_device.id}", headers=headers)
+    assert res.status_code == 409
+    listed = (await client.get("/api/v1/scan/pending", headers=headers)).json()
+    assert [d["id"] for d in listed] == [pending_device.id]

backend/tests/scan/test_scan_run.py

@@ -0,0 +1,431 @@
+"""run_scan service persistence, _background_scan lifecycle, stop/cancel."""
+import uuid
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import InventoryDevice, Node, ScanRun
+from app.services.scanner import _cancelled_runs, request_cancel, run_scan
+
+
+@pytest.mark.asyncio
+async def test_background_scan_marks_run_failed_on_exception(mem_db):
+    """If run_scan() raises, the ScanRun must transition running → failed and the
+    session rollback path must execute without a follow-on exception."""
+    from app.api.routes.scan import _background_scan
+
+    async with mem_db() as session:
+        run = ScanRun(status="running", ranges=["10.0.0.0/24"])
+        session.add(run)
+        await session.commit()
+        run_id = run.id
+
+    with (
+        patch("app.api.routes.scan.AsyncSessionLocal", mem_db),
+        patch(
+            "app.api.routes.scan.run_scan",
+            new_callable=AsyncMock,
+            side_effect=RuntimeError("boom"),
+        ),
+    ):
+        await _background_scan(run_id, ["10.0.0.0/24"])
+
+    async with mem_db() as session:
+        refreshed = await session.get(ScanRun, run_id)
+        assert refreshed is not None
+        assert refreshed.status == "failed"
+
+
+@pytest.mark.asyncio
+async def test_background_scan_leaves_non_running_status_alone(mem_db):
+    """If the run was already stopped/cancelled before run_scan failed, _background_scan
+    must NOT overwrite that terminal status with 'failed'."""
+    from app.api.routes.scan import _background_scan
+
+    async with mem_db() as session:
+        run = ScanRun(status="cancelled", ranges=["10.0.0.0/24"])
+        session.add(run)
+        await session.commit()
+        run_id = run.id
+
+    with (
+        patch("app.api.routes.scan.AsyncSessionLocal", mem_db),
+        patch(
+            "app.api.routes.scan.run_scan",
+            new_callable=AsyncMock,
+            side_effect=RuntimeError("boom"),
+        ),
+    ):
+        await _background_scan(run_id, ["10.0.0.0/24"])
+
+    async with mem_db() as session:
+        refreshed = await session.get(ScanRun, run_id)
+        assert refreshed is not None
+        assert refreshed.status == "cancelled"
+
+
+@pytest.mark.asyncio
+async def test_background_scan_success_path_invokes_run_scan(mem_db):
+    from app.api.routes.scan import _background_scan
+
+    async with mem_db() as session:
+        run = ScanRun(status="running", ranges=["10.0.0.0/24"])
+        session.add(run)
+        await session.commit()
+        run_id = run.id
+
+    with (
+        patch("app.api.routes.scan.AsyncSessionLocal", mem_db),
+        patch("app.api.routes.scan.run_scan", new_callable=AsyncMock) as mock_run_scan,
+    ):
+        from app.services.scanner import DeepScanOptions
+        await _background_scan(run_id, ["10.0.0.0/24"], DeepScanOptions())
+        mock_run_scan.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_list_runs_empty(client: AsyncClient, headers):
+    res = await client.get("/api/v1/scan/runs", headers=headers)
+    assert res.status_code == 200
+    assert res.json() == []
+
+
+# --- run_scan: re-scan updates existing pending devices ---
+
+MOCK_HOST = {
+    "ip": "192.168.1.50",
+    "mac": "aa:bb:cc:dd:ee:ff",
+    "hostname": "myhost.lan",
+    "os": "Linux",
+    "open_ports": [{"port": 8096, "protocol": "tcp", "banner": "Jellyfin"}],
+}
+
+
+@pytest.mark.asyncio
+async def test_run_scan_creates_new_pending_device(db_session: AsyncSession):
+    run_id = str(uuid.uuid4())
+    run = ScanRun(id=run_id, status="running", ranges=["192.168.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    with (
+        patch("app.services.scanner._nmap_scan", return_value=[MOCK_HOST]),
+        patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock),
+    ):
+        await run_scan(["192.168.1.0/24"], db_session, run_id)
+
+    result = await db_session.execute(
+        select(InventoryDevice).where(InventoryDevice.ip == "192.168.1.50")
+    )
+    device = result.scalar_one_or_none()
+    assert device is not None
+    assert device.hostname == "myhost.lan"
+    assert any(s["port"] == 8096 for s in device.services)
+    assert device.suggested_type == "server"
+
+
+@pytest.mark.asyncio
+async def test_run_scan_keeps_stale_pending_for_canvas_nodes(db_session: AsyncSession):
+    """Pending devices whose IP is already on a canvas are NOT purged — they stay
+    in the inventory and are surfaced with an "In N canvas" badge."""
+    node = Node(
+        id=str(uuid.uuid4()),
+        label="Existing Server",
+        type="server",
+        ip="192.168.1.50",
+        status="online",
+        services=[],
+        pos_x=0.0,
+        pos_y=0.0,
+    )
+    stale = InventoryDevice(
+        id=str(uuid.uuid4()),
+        ip="192.168.1.50",
+        mac=None,
+        hostname=None,
+        os=None,
+        services=[],
+        suggested_type="generic",
+        status="pending",
+    )
+    db_session.add(node)
+    db_session.add(stale)
+    await db_session.commit()
+
+    run_id = str(uuid.uuid4())
+    run = ScanRun(id=run_id, status="running", ranges=["192.168.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    with (
+        patch("app.services.scanner._nmap_scan", return_value=[]),
+        patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock),
+    ):
+        await run_scan(["192.168.1.0/24"], db_session, run_id)
+
+    result = await db_session.execute(
+        select(InventoryDevice).where(InventoryDevice.ip == "192.168.1.50")
+    )
+    assert result.scalar_one_or_none() is not None
+
+
+@pytest.mark.asyncio
+async def test_run_scan_records_ip_already_in_canvas(db_session: AsyncSession):
+    """A scanned IP that already exists as a canvas Node still produces a pending
+    device (no longer suppressed)."""
+    node = Node(
+        id=str(uuid.uuid4()),
+        label="Existing Server",
+        type="server",
+        ip="192.168.1.50",
+        status="online",
+        services=[],
+        pos_x=0.0,
+        pos_y=0.0,
+    )
+    db_session.add(node)
+    await db_session.commit()
+
+    run_id = str(uuid.uuid4())
+    run = ScanRun(id=run_id, status="running", ranges=["192.168.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    with (
+        patch("app.services.scanner._nmap_scan", return_value=[MOCK_HOST]),
+        patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock),
+    ):
+        await run_scan(["192.168.1.0/24"], db_session, run_id)
+
+    result = await db_session.execute(
+        select(InventoryDevice).where(InventoryDevice.ip == "192.168.1.50")
+    )
+    device = result.scalar_one_or_none()
+    assert device is not None
+    assert device.status == "pending"
+
+
+@pytest.mark.asyncio
+async def test_run_scan_refreshes_approved_device_without_duplicating(db_session: AsyncSession):
+    """Re-scanning an already-approved device updates its row in place instead of
+    spawning a fresh pending duplicate, and keeps it approved."""
+    approved = InventoryDevice(
+        id=str(uuid.uuid4()), ip="192.168.1.50", mac=None, hostname="old",
+        os=None, services=[], suggested_type="server", status="approved",
+    )
+    db_session.add(approved)
+    run_id = str(uuid.uuid4())
+    db_session.add(ScanRun(id=run_id, status="running", ranges=["192.168.1.0/24"]))
+    await db_session.commit()
+
+    with (
+        patch("app.services.scanner._nmap_scan", return_value=[MOCK_HOST]),
+        patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock),
+    ):
+        await run_scan(["192.168.1.0/24"], db_session, run_id)
+
+    rows = (await db_session.execute(
+        select(InventoryDevice).where(InventoryDevice.ip == "192.168.1.50")
+    )).scalars().all()
+    assert len(rows) == 1
+    assert rows[0].status == "approved"
+    assert rows[0].hostname == "myhost.lan"  # refreshed from the scan
+
+
+@pytest.mark.asyncio
+async def test_run_scan_collapses_existing_duplicate_rows(db_session: AsyncSession):
+    """Pre-existing duplicate inventory rows for one IP are collapsed to a single
+    row at scan start, even if the device is not re-discovered."""
+    for status in ("approved", "pending", "pending"):
+        db_session.add(InventoryDevice(
+            id=str(uuid.uuid4()), ip="192.168.1.77", mac=None, hostname=None,
+            os=None, services=[], suggested_type="server", status=status,
+        ))
+    run_id = str(uuid.uuid4())
+    db_session.add(ScanRun(id=run_id, status="running", ranges=["192.168.1.0/24"]))
+    await db_session.commit()
+
+    with (
+        patch("app.services.scanner._nmap_scan", return_value=[]),
+        patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock),
+    ):
+        await run_scan(["192.168.1.0/24"], db_session, run_id)
+
+    rows = (await db_session.execute(
+        select(InventoryDevice).where(InventoryDevice.ip == "192.168.1.77")
+    )).scalars().all()
+    assert len(rows) == 1
+    assert rows[0].status == "approved"  # approved row is the one kept
+
+
+@pytest.mark.asyncio
+async def test_run_scan_skips_hidden_device(db_session: AsyncSession):
+    """Devices previously hidden by the user must not re-appear in pending on re-scan."""
+    hidden = InventoryDevice(
+        id=str(uuid.uuid4()),
+        ip="192.168.1.50",
+        mac=None,
+        hostname=None,
+        os=None,
+        services=[],
+        suggested_type="generic",
+        status="hidden",
+    )
+    db_session.add(hidden)
+    await db_session.commit()
+
+    run_id = str(uuid.uuid4())
+    run = ScanRun(id=run_id, status="running", ranges=["192.168.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    with (
+        patch("app.services.scanner._nmap_scan", return_value=[MOCK_HOST]),
+        patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock),
+    ):
+        await run_scan(["192.168.1.0/24"], db_session, run_id)
+
+    result = await db_session.execute(
+        select(InventoryDevice).where(
+            InventoryDevice.ip == "192.168.1.50",
+            InventoryDevice.status == "pending",
+        )
+    )
+    assert result.scalar_one_or_none() is None
+
+
+@pytest.mark.asyncio
+async def test_stop_scan_requires_auth(client: AsyncClient):
+    res = await client.post("/api/v1/scan/fake-id/stop")
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_stop_scan_not_found(client: AsyncClient, headers):
+    import uuid as _uuid
+    res = await client.post(f"/api/v1/scan/{_uuid.uuid4()}/stop", headers=headers)
+    assert res.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_stop_scan_not_running(client: AsyncClient, headers, db_session: AsyncSession):
+    run = ScanRun(id=str(uuid.uuid4()), status="done", ranges=["192.168.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    res = await client.post(f"/api/v1/scan/{run.id}/stop", headers=headers)
+    assert res.status_code == 409
+
+
+@pytest.mark.asyncio
+async def test_stop_scan_success(client: AsyncClient, headers, db_session: AsyncSession):
+    run = ScanRun(id=str(uuid.uuid4()), status="running", ranges=["192.168.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    res = await client.post(f"/api/v1/scan/{run.id}/stop", headers=headers)
+    assert res.status_code == 200
+    assert res.json() == {"stopping": True}
+    # run_id added to cancel set
+    assert run.id in _cancelled_runs
+    # status flipped eagerly so the UI reacts without waiting for a checkpoint
+    await db_session.refresh(run)
+    assert run.status == "cancelled"
+    assert run.finished_at is not None
+    # cleanup for other tests
+    _cancelled_runs.discard(run.id)
+
+
+@pytest.mark.asyncio
+async def test_run_scan_cancelled_marks_status(db_session: AsyncSession):
+    """When cancel is requested before the scan starts, status becomes 'cancelled'."""
+    run_id = str(uuid.uuid4())
+    run = ScanRun(id=run_id, status="running", ranges=["192.168.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    request_cancel(run_id)
+
+    with (
+        patch("app.services.scanner._nmap_scan", return_value=[MOCK_HOST]) as mock_nmap,
+        patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock),
+    ):
+        await run_scan(["192.168.1.0/24"], db_session, run_id)
+        # nmap should not have been called — cancelled before first range
+        mock_nmap.assert_not_called()
+
+    await db_session.refresh(run)
+    assert run.status == "cancelled"
+    assert run.finished_at is not None
+
+
+@pytest.mark.asyncio
+async def test_run_scan_cancelled_mid_scan_skips_remaining_cidrs(db_session: AsyncSession):
+    """Cancel flag set after first CIDR is started prevents processing of the second CIDR."""
+    run_id = str(uuid.uuid4())
+    run = ScanRun(id=run_id, status="running", ranges=["10.0.0.0/24", "10.0.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    call_count = 0
+
+    def nmap_side_effect(target: str, port_spec: str | None = None, run_id: str | None = None):
+        nonlocal call_count
+        call_count += 1
+        # Signal cancellation after the first CIDR scan completes
+        if call_count == 1:
+            request_cancel(run_id)
+        return []
+
+    with (
+        patch("app.services.scanner._nmap_scan", side_effect=nmap_side_effect),
+        patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock),
+    ):
+        await run_scan(["10.0.0.0/24", "10.0.1.0/24"], db_session, run_id)
+
+    assert call_count == 1  # second CIDR was skipped
+    await db_session.refresh(run)
+    assert run.status == "cancelled"
+
+
+@pytest.mark.asyncio
+async def test_run_scan_updates_existing_pending_device(db_session: AsyncSession):
+    """Re-scanning the same IP updates services instead of creating a duplicate."""
+    # Pre-existing pending device with no services
+    existing = InventoryDevice(
+        id=str(uuid.uuid4()),
+        ip="192.168.1.50",
+        mac=None,
+        hostname=None,
+        os=None,
+        services=[],
+        suggested_type="generic",
+        status="pending",
+    )
+    db_session.add(existing)
+    await db_session.commit()
+
+    run_id = str(uuid.uuid4())
+    run = ScanRun(id=run_id, status="running", ranges=["192.168.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    with (
+        patch("app.services.scanner._nmap_scan", return_value=[MOCK_HOST]),
+        patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock),
+    ):
+        await run_scan(["192.168.1.0/24"], db_session, run_id)
+
+    # Should still be only one device
+    result = await db_session.execute(
+        select(InventoryDevice).where(InventoryDevice.ip == "192.168.1.50")
+    )
+    devices = list(result.scalars().all())
+    assert len(devices) == 1
+    device = devices[0]
+    # Services and hostname should be updated
+    assert device.hostname == "myhost.lan"
+    assert any(s["port"] == 8096 for s in device.services)

backend/tests/test_auth.py

@@ -1,5 +1,56 @@
+import time
+from unittest.mock import AsyncMock, patch
+from urllib.parse import parse_qs, urlparse
+
 import pytest
+from authlib.integrations.base_client.errors import OAuthError
+from authlib.jose.errors import ExpiredTokenError, JoseError
+from fastapi import WebSocketDisconnect
 from httpx import AsyncClient
+from starlette.responses import RedirectResponse
+from starlette.testclient import TestClient
+
+
+class FakeOIDCClient:
+    def __init__(self, token=None, error: OAuthError | JoseError | None = None):
+        self.token = token or {}
+        self.error = error
+        self.redirect_uri: str | None = None
+
+    async def authorize_redirect(self, _request, redirect_uri: str):
+        self.redirect_uri = redirect_uri
+        return RedirectResponse("https://idp.example/application/o/authorize/?state=test", status_code=302)
+
+    async def authorize_access_token(self, _request):
+        if self.error is not None:
+            raise self.error
+        return self.token
+
+
+@pytest.fixture
+def oidc_settings():
+    from app.core.config import settings
+    from app.core.security import _build_oidc_client
+
+    values = {
+        "auth_mode": "oidc",
+        "oidc_discovery_url": "https://idp.example/application/o/homelable/.well-known/openid-configuration",
+        "oidc_client_id": "homelable",
+        "oidc_client_secret": "test-client-secret",
+        "oidc_redirect_uri": "http://test/api/v1/auth/oidc/callback",
+        "oidc_scopes": "openid profile email",
+        "oidc_cookie_secure": False,
+        "oidc_session_expire_minutes": 60,
+        "cors_origins": ["http://test"],
+    }
+    original = {name: getattr(settings, name) for name in values}
+    for name, value in values.items():
+        setattr(settings, name, value)
+    _build_oidc_client.cache_clear()
+    yield settings
+    for name, value in original.items():
+        setattr(settings, name, value)
+    _build_oidc_client.cache_clear()
 
 
 async def test_login_success(client: AsyncClient):
@@ -10,6 +61,12 @@ async def test_login_success(client: AsyncClient):
     assert data["token_type"] == "bearer"
 
 
+async def test_auth_config_defaults_to_local(client: AsyncClient):
+    res = await client.get("/api/v1/auth/config")
+    assert res.status_code == 200
+    assert res.json() == {"mode": "local", "oidc_login_url": None}
+
+
 async def test_login_wrong_password(client: AsyncClient):
     res = await client.post("/api/v1/auth/login", json={"username": "admin", "password": "wrong"})
     assert res.status_code == 401
@@ -76,7 +133,7 @@ async def test_expired_token_rejected(client: AsyncClient):
     """A JWT whose `exp` is in the past must be refused."""
     from datetime import datetime, timedelta, timezone
 
-    from jose import jwt
+    import jwt
 
     from app.core.config import settings
     payload = {
@@ -97,14 +154,14 @@ async def test_token_signed_with_wrong_secret_rejected(client: AsyncClient):
     """A token signed with a different key must not be accepted."""
     from datetime import datetime, timedelta, timezone
 
-    from jose import jwt
+    import jwt
 
     from app.core.config import settings
     payload = {
         "sub": "admin",
         "exp": datetime.now(timezone.utc) + timedelta(minutes=5),
     }
-    forged = jwt.encode(payload, "different-secret", algorithm=settings.algorithm)
+    forged = jwt.encode(payload, "different-secret-that-is-at-least-32-bytes", algorithm=settings.algorithm)
     res = await client.get("/api/v1/nodes", headers={"Authorization": f"Bearer {forged}"})
     assert res.status_code == 401
 
@@ -136,3 +193,231 @@ def test_verify_password_handles_empty_inputs():
     assert verify_password("", h) is False
     assert verify_password("hunter2", "") is False
     assert verify_password("", "") is False
+
+
+# --- OpenID Connect ---
+
+async def test_oidc_config_exposes_login_url(client: AsyncClient, oidc_settings):
+    res = await client.get("/api/v1/auth/config")
+    assert res.status_code == 200
+    assert res.json() == {
+        "mode": "oidc",
+        "oidc_login_url": "/api/v1/auth/oidc/login",
+    }
+
+
+async def test_local_login_is_disabled_in_oidc_mode(client: AsyncClient, oidc_settings):
+    res = await client.post("/api/v1/auth/login", json={"username": "admin", "password": "admin"})
+    assert res.status_code == 404
+
+
+async def test_oidc_login_is_hidden_in_local_mode(client: AsyncClient):
+    res = await client.get("/api/v1/auth/oidc/login")
+    assert res.status_code == 404
+
+
+async def test_oidc_login_uses_configured_callback(client: AsyncClient, oidc_settings):
+    fake_client = FakeOIDCClient()
+    with patch("app.api.routes.auth.get_oidc_client", return_value=fake_client):
+        res = await client.get("/api/v1/auth/oidc/login")
+    assert res.status_code == 302
+    assert res.headers["location"].startswith("https://idp.example/")
+    assert fake_client.redirect_uri == "http://test/api/v1/auth/oidc/callback"
+
+
+async def test_oidc_client_enables_pkce_s256_and_nonce(oidc_settings):
+    from app.core.security import get_oidc_client
+
+    oidc_client = get_oidc_client()
+    metadata = {"authorization_endpoint": "https://idp.example/application/o/authorize/"}
+    with patch.object(oidc_client, "load_server_metadata", AsyncMock(return_value=metadata)):
+        authorization = await oidc_client.create_authorization_url(oidc_settings.oidc_redirect_uri)
+
+    query = parse_qs(urlparse(authorization["url"]).query)
+    assert query["response_type"] == ["code"]
+    assert query["code_challenge_method"] == ["S256"]
+    assert "code_challenge" in query
+    assert "code_verifier" not in query
+    assert query["nonce"] == [authorization["nonce"]]
+    assert authorization["code_verifier"]
+
+
+async def test_oidc_callback_creates_session_for_api(client: AsyncClient, oidc_settings):
+    fake_client = FakeOIDCClient(token={
+        "userinfo": {
+            "iss": "https://idp.example/application/o/homelable/",
+            "sub": "user-123",
+            "preferred_username": "alice",
+        },
+    })
+    with patch("app.api.routes.auth.get_oidc_client", return_value=fake_client):
+        callback = await client.get("/api/v1/auth/oidc/callback")
+
+    assert callback.status_code == 303
+    assert callback.headers["location"] == "/"
+    cookie = callback.headers["set-cookie"]
+    assert "homelable-session=" in cookie
+    assert "HttpOnly" in cookie
+    assert "SameSite=lax" in cookie
+
+    me = await client.get("/api/v1/auth/me")
+    assert me.status_code == 200
+    assert me.json()["subject"] == "user-123"
+    assert me.json()["display_name"] == "alice"
+    assert me.json()["auth_method"] == "oidc"
+    assert me.json()["issuer"] == "https://idp.example/application/o/homelable/"
+    assert me.json()["csrf_token"]
+
+    protected = await client.get("/api/v1/nodes")
+    assert protected.status_code == 200
+
+
+@pytest.mark.parametrize("userinfo", [None, {}, {"sub": "user-123"}, {"iss": "https://idp.example/"}])
+async def test_oidc_callback_rejects_missing_identity_claims(client: AsyncClient, oidc_settings, userinfo):
+    token = {} if userinfo is None else {"userinfo": userinfo}
+    fake_client = FakeOIDCClient(token=token)
+    with patch("app.api.routes.auth.get_oidc_client", return_value=fake_client):
+        res = await client.get("/api/v1/auth/oidc/callback")
+    assert res.status_code == 401
+    assert res.json() == {"detail": "OIDC authentication failed"}
+
+
+async def test_oidc_callback_hides_protocol_error_details(client: AsyncClient, oidc_settings):
+    fake_client = FakeOIDCClient(error=OAuthError(error="invalid_grant", description="sensitive detail"))
+    with patch("app.api.routes.auth.get_oidc_client", return_value=fake_client):
+        res = await client.get("/api/v1/auth/oidc/callback")
+    assert res.status_code == 401
+    assert res.json() == {"detail": "OIDC authentication failed"}
+    assert "sensitive detail" not in res.text
+
+
+async def test_oidc_callback_hides_claim_validation_error_details(client: AsyncClient, oidc_settings):
+    fake_client = FakeOIDCClient(error=ExpiredTokenError())
+    with patch("app.api.routes.auth.get_oidc_client", return_value=fake_client):
+        res = await client.get("/api/v1/auth/oidc/callback")
+    assert res.status_code == 401
+    assert res.json() == {"detail": "OIDC authentication failed"}
+    assert "expired" not in res.text.lower()
+
+
+async def test_oidc_session_token_cannot_be_used_as_bearer(client: AsyncClient, oidc_settings):
+    from app.core.security import create_oidc_session_token
+
+    token = create_oidc_session_token({"iss": "https://idp.example/", "sub": "user-123"})
+    res = await client.get("/api/v1/nodes", headers={"Authorization": f"Bearer {token}"})
+    assert res.status_code == 401
+
+
+async def test_oidc_cookie_mutations_require_csrf_and_allowed_origin(client: AsyncClient, oidc_settings):
+    fake_client = FakeOIDCClient(token={
+        "userinfo": {
+            "iss": "https://idp.example/application/o/homelable/",
+            "sub": "user-123",
+            "preferred_username": "alice",
+        },
+    })
+    with patch("app.api.routes.auth.get_oidc_client", return_value=fake_client):
+        await client.get("/api/v1/auth/oidc/callback")
+    csrf_token = (await client.get("/api/v1/auth/me")).json()["csrf_token"]
+
+    missing = await client.post("/api/v1/auth/logout")
+    assert missing.status_code == 403
+    wrong_origin = await client.post(
+        "/api/v1/auth/logout",
+        headers={"Origin": "https://evil.example", "X-Homelable-CSRF": csrf_token},
+    )
+    assert wrong_origin.status_code == 403
+    valid = await client.post(
+        "/api/v1/auth/logout",
+        headers={"Origin": "http://test", "X-Homelable-CSRF": csrf_token},
+    )
+    assert valid.status_code == 204
+    assert "Max-Age=0" in valid.headers["set-cookie"]
+    assert (await client.get("/api/v1/auth/me")).status_code == 401
+
+
+async def test_local_bearer_logout_does_not_require_csrf(client: AsyncClient, headers):
+    res = await client.post("/api/v1/auth/logout", headers=headers)
+    assert res.status_code == 204
+
+
+# --- WebSocket authentication ---
+
+def _wait_for_connection_count(expected: int) -> None:
+    from app.api.routes import status as status_routes
+
+    deadline = time.monotonic() + 1
+    while len(status_routes._connections) != expected and time.monotonic() < deadline:
+        time.sleep(0.01)
+    assert len(status_routes._connections) == expected
+
+
+def test_local_websocket_keeps_first_message_bearer_flow():
+    from app.core.security import create_access_token
+    from app.main import app
+
+    test_client = TestClient(app)
+    try:
+        with test_client.websocket_connect(
+            "/api/v1/status/ws/status",
+            headers={"Origin": "http://localhost:3000"},
+        ) as websocket:
+            websocket.send_json({"token": create_access_token("admin")})
+            _wait_for_connection_count(1)
+        _wait_for_connection_count(0)
+    finally:
+        test_client.close()
+
+
+def test_websocket_rejects_untrusted_origin_before_auth():
+    from app.main import app
+
+    test_client = TestClient(app)
+    try:
+        with (
+            pytest.raises(WebSocketDisconnect) as caught,
+            test_client.websocket_connect(
+                "/api/v1/status/ws/status",
+                headers={"Origin": "https://evil.example"},
+            ) as websocket,
+        ):
+            websocket.receive_text()
+        assert caught.value.code == 1008
+    finally:
+        test_client.close()
+
+
+def test_oidc_websocket_uses_session_cookie_without_javascript_token(oidc_settings):
+    from app.core.security import create_oidc_session_token, oidc_session_cookie_name
+    from app.main import app
+
+    session_token = create_oidc_session_token({"iss": "https://idp.example/", "sub": "user-123"})
+    test_client = TestClient(app)
+    test_client.cookies.set(oidc_session_cookie_name(), session_token)
+    try:
+        with test_client.websocket_connect(
+            "/api/v1/status/ws/status",
+            headers={"Origin": "http://test"},
+        ):
+            _wait_for_connection_count(1)
+        _wait_for_connection_count(0)
+    finally:
+        test_client.close()
+
+
+def test_oidc_websocket_rejects_missing_session_cookie(oidc_settings):
+    from app.main import app
+
+    test_client = TestClient(app)
+    try:
+        with (
+            pytest.raises(WebSocketDisconnect) as caught,
+            test_client.websocket_connect(
+                "/api/v1/status/ws/status",
+                headers={"Origin": "http://test"},
+            ) as websocket,
+        ):
+            websocket.receive_text()
+        assert caught.value.code == 1008
+    finally:
+        test_client.close()

backend/tests/test_canvas.py

@@ -1,15 +1,8 @@
 import uuid
 
-import pytest
 from httpx import AsyncClient
 
 
-@pytest.fixture
-async def headers(client: AsyncClient):
-    res = await client.post("/api/v1/auth/login", json={"username": "admin", "password": "admin"})
-    return {"Authorization": f"Bearer {res.json()['access_token']}"}
-
-
 def node_payload(**kwargs):
     return {"id": str(uuid.uuid4()), "type": "server", "label": "N", "status": "unknown", "pos_x": 0, "pos_y": 0, **kwargs}
 
@@ -29,6 +22,23 @@ async def test_load_canvas_empty(client: AsyncClient, headers: dict):
     assert data["viewport"] == {"x": 0, "y": 0, "zoom": 1}
 
 
+async def test_load_canvas_uninitialized_reports_initialized_false(client: AsyncClient, headers: dict):
+    # A never-saved canvas has no CanvasState row → initialized False. The frontend
+    # uses this to show the demo canvas only to genuinely new users.
+    data = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert data["initialized"] is False
+
+
+async def test_load_canvas_initialized_true_after_save(client: AsyncClient, headers: dict):
+    # Saving an EMPTY canvas still creates a CanvasState row, so a subsequently
+    # loaded empty canvas is reported initialized — the user cleared it on purpose
+    # and must not get the demo re-seeded.
+    await client.post("/api/v1/canvas/save", json={"nodes": [], "edges": [], "viewport": {}}, headers=headers)
+    data = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert data["nodes"] == []
+    assert data["initialized"] is True
+
+
 async def test_load_canvas_requires_auth(client: AsyncClient):
     res = await client.get("/api/v1/canvas")
     assert res.status_code == 401
@@ -51,6 +61,76 @@ async def test_save_canvas_creates_nodes_and_edges(client: AsyncClient, headers:
     assert canvas["viewport"] == {"x": 1, "y": 2, "zoom": 1.5}
 
 
+async def test_save_canvas_round_trips_marker_shapes(client: AsyncClient, headers: dict):
+    n1 = node_payload(label="Router", type="router")
+    n2 = node_payload(label="Switch", type="switch")
+    e1 = edge_payload(n1["id"], n2["id"], marker_start="diamond", marker_end="arrow")
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1, n2], "edges": [e1], "viewport": {}}, headers=headers)
+
+    edge = (await client.get("/api/v1/canvas", headers=headers)).json()["edges"][0]
+    assert edge["marker_start"] == "diamond"
+    assert edge["marker_end"] == "arrow"
+
+
+async def test_save_canvas_round_trips_line_style_and_width(client: AsyncClient, headers: dict):
+    n1 = node_payload(label="Router", type="router")
+    n2 = node_payload(label="Switch", type="switch")
+    e1 = edge_payload(n1["id"], n2["id"], type="wifi", line_style="dotted", width_mult=3)
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1, n2], "edges": [e1], "viewport": {}}, headers=headers)
+
+    edge = (await client.get("/api/v1/canvas", headers=headers)).json()["edges"][0]
+    assert edge["line_style"] == "dotted"
+    assert edge["width_mult"] == 3
+
+
+async def test_save_canvas_coerces_legacy_boolean_marker(client: AsyncClient, headers: dict):
+    n1 = node_payload(label="Router", type="router")
+    n2 = node_payload(label="Switch", type="switch")
+    e1 = edge_payload(n1["id"], n2["id"], marker_start=True, marker_end=False)
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1, n2], "edges": [e1], "viewport": {}}, headers=headers)
+
+    edge = (await client.get("/api/v1/canvas", headers=headers)).json()["edges"][0]
+    assert edge["marker_start"] == "arrow"
+    assert edge["marker_end"] == "none"
+
+
+async def test_save_canvas_defaults_markers_none(client: AsyncClient, headers: dict):
+    n1 = node_payload(label="Router", type="router")
+    n2 = node_payload(label="Switch", type="switch")
+    e1 = edge_payload(n1["id"], n2["id"])
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1, n2], "edges": [e1], "viewport": {}}, headers=headers)
+
+    edge = (await client.get("/api/v1/canvas", headers=headers)).json()["edges"][0]
+    assert edge["marker_start"] == "none"
+    assert edge["marker_end"] == "none"
+
+
+async def test_save_canvas_round_trips_per_side_handles(client: AsyncClient, headers: dict):
+    # Regression (#243): top/left/right_handles must persist across save+reload,
+    # not just bottom_handles.
+    n1 = node_payload(label="Cam", type="camera", top_handles=2, bottom_handles=3, left_handles=1, right_handles=4)
+    res = await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {"x": 0, "y": 0, "zoom": 1}}, headers=headers)
+    assert res.status_code == 200
+
+    node = (await client.get("/api/v1/canvas", headers=headers)).json()["nodes"][0]
+    assert node["top_handles"] == 2
+    assert node["bottom_handles"] == 3
+    assert node["left_handles"] == 1
+    assert node["right_handles"] == 4
+
+
+async def test_save_canvas_defaults_per_side_handles(client: AsyncClient, headers: dict):
+    # Nodes saved without the new fields fall back to top/bottom=1, left/right=0.
+    n1 = node_payload(label="Srv", type="server")
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {"x": 0, "y": 0, "zoom": 1}}, headers=headers)
+
+    node = (await client.get("/api/v1/canvas", headers=headers)).json()["nodes"][0]
+    assert node["top_handles"] == 1
+    assert node["bottom_handles"] == 1
+    assert node["left_handles"] == 0
+    assert node["right_handles"] == 0
+
+
 async def test_load_canvas_exposes_inventory_timestamps(client: AsyncClient, headers: dict):
     n1 = node_payload(label="Router", type="router")
     await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)

backend/tests/test_db_migrations.py

@@ -0,0 +1,131 @@
+"""The pending_devices -> device_inventory rename, run at startup.
+
+It is the one migration that must happen *before* `create_all`, so it gets its
+own suite: get the order wrong and every device a user ever scanned reads as
+gone, because the app looks at a freshly created empty table.
+"""
+import pytest
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from app.db.database import _rename_legacy_tables
+
+pytestmark = pytest.mark.asyncio
+
+
+def _legacy_ddl(table: str) -> str:
+    return f"CREATE TABLE {table} (id VARCHAR PRIMARY KEY, hostname VARCHAR)"
+
+
+async def _engine(tmp_path, *, statements: list[str]):
+    engine = create_async_engine(f"sqlite+aiosqlite:///{tmp_path / 'test.db'}")
+    async with engine.begin() as conn:
+        for sql in statements:
+            await conn.exec_driver_sql(sql)
+    return engine
+
+
+async def _tables(engine) -> set[str]:
+    async with engine.begin() as conn:
+        rows = (
+            await conn.exec_driver_sql("SELECT name FROM sqlite_master WHERE type='table'")
+        ).fetchall()
+    return {r[0] for r in rows}
+
+
+async def _rename(engine) -> None:
+    async with engine.begin() as conn:
+        await _rename_legacy_tables(conn)
+
+
+async def test_renames_the_legacy_tables_keeping_their_rows(tmp_path):
+    engine = await _engine(
+        tmp_path,
+        statements=[
+            _legacy_ddl("pending_devices"),
+            _legacy_ddl("pending_device_links"),
+            "INSERT INTO pending_devices (id, hostname) VALUES ('d1', 'nas')",
+        ],
+    )
+
+    await _rename(engine)
+
+    assert await _tables(engine) == {"device_inventory", "device_inventory_links"}
+    async with engine.begin() as conn:
+        rows = (await conn.exec_driver_sql("SELECT hostname FROM device_inventory")).fetchall()
+    assert [r[0] for r in rows] == ["nas"]
+    await engine.dispose()
+
+
+async def test_rewrites_the_reference_from_rack_devices(tmp_path):
+    # `rack_devices.device_id` names the inventory table. Left pointing at the
+    # old name, the schema references a table that no longer exists.
+    engine = await _engine(
+        tmp_path,
+        statements=[
+            _legacy_ddl("pending_devices"),
+            "CREATE TABLE rack_devices (id VARCHAR PRIMARY KEY, device_id VARCHAR "
+            "REFERENCES pending_devices(id) ON DELETE SET NULL)",
+        ],
+    )
+
+    await _rename(engine)
+
+    async with engine.begin() as conn:
+        ddl = (
+            await conn.exec_driver_sql(
+                "SELECT sql FROM sqlite_master WHERE name='rack_devices'"
+            )
+        ).scalar()
+    assert "device_inventory" in ddl
+    assert "pending_devices" not in ddl
+    await engine.dispose()
+
+
+async def test_replaces_an_empty_table_left_by_an_earlier_start(tmp_path):
+    # A start that ran `create_all` before this migration existed created the new
+    # table empty, and the app read that one instead of the user's devices.
+    engine = await _engine(
+        tmp_path,
+        statements=[
+            _legacy_ddl("pending_devices"),
+            _legacy_ddl("device_inventory"),
+            "INSERT INTO pending_devices (id, hostname) VALUES ('d1', 'nas')",
+        ],
+    )
+
+    await _rename(engine)
+
+    assert await _tables(engine) == {"device_inventory"}
+    async with engine.begin() as conn:
+        count = (await conn.exec_driver_sql("SELECT COUNT(*) FROM device_inventory")).scalar()
+    assert count == 1
+    await engine.dispose()
+
+
+async def test_leaves_two_populated_tables_alone(tmp_path):
+    # Rows on both sides is not a state this migration created, and dropping
+    # either one would lose data.
+    engine = await _engine(
+        tmp_path,
+        statements=[
+            _legacy_ddl("pending_devices"),
+            _legacy_ddl("device_inventory"),
+            "INSERT INTO pending_devices (id, hostname) VALUES ('d1', 'old')",
+            "INSERT INTO device_inventory (id, hostname) VALUES ('d2', 'new')",
+        ],
+    )
+
+    await _rename(engine)
+
+    assert await _tables(engine) == {"pending_devices", "device_inventory"}
+    await engine.dispose()
+
+
+async def test_is_a_no_op_on_a_fresh_database(tmp_path):
+    engine = await _engine(tmp_path, statements=[_legacy_ddl("device_inventory")])
+
+    await _rename(engine)
+    await _rename(engine)  # And still a no-op the second time round.
+
+    assert await _tables(engine) == {"device_inventory"}
+    await engine.dispose()

backend/tests/test_designs.py

@@ -1,15 +1,8 @@
 import uuid
 
-import pytest
 from httpx import AsyncClient
 
 
-@pytest.fixture
-async def headers(client: AsyncClient):
-    res = await client.post("/api/v1/auth/login", json={"username": "admin", "password": "admin"})
-    return {"Authorization": f"Bearer {res.json()['access_token']}"}
-
-
 def node_payload(**kwargs):
     return {"id": str(uuid.uuid4()), "type": "server", "label": "N", "status": "unknown", "pos_x": 0, "pos_y": 0, **kwargs}
 
@@ -100,6 +93,118 @@ async def test_list_returns_created_designs_ordered(client: AsyncClient, headers
     assert ids == [a["id"], b["id"]]
 
 
+# ── counts in list ──────────────────────────────────────────────────────────
+
+async def test_list_includes_node_group_text_counts(client: AsyncClient, headers: dict):
+    design = await _create(client, headers, name="Counted")
+    server = node_payload(label="S", type="server")
+    group = node_payload(label="G", type="groupRect")
+    text = node_payload(label="T", type="text")
+    save = await client.post(
+        "/api/v1/canvas/save",
+        json={"nodes": [server, group, text], "edges": [], "viewport": {}, "design_id": design["id"]},
+        headers=headers,
+    )
+    assert save.status_code == 200
+    listed = (await client.get("/api/v1/designs", headers=headers)).json()
+    d = next(x for x in listed if x["id"] == design["id"])
+    assert d["node_count"] == 1
+    assert d["group_count"] == 1
+    assert d["text_count"] == 1
+
+
+async def test_list_counts_zero_for_empty_design(client: AsyncClient, headers: dict):
+    design = await _create(client, headers, name="Empty")
+    listed = (await client.get("/api/v1/designs", headers=headers)).json()
+    d = next(x for x in listed if x["id"] == design["id"])
+    assert d["node_count"] == 0
+    assert d["group_count"] == 0
+    assert d["text_count"] == 0
+
+
+# ── copy ──────────────────────────────────────────────────────────────────────
+
+async def test_copy_requires_auth(client: AsyncClient):
+    res = await client.post(f"/api/v1/designs/{uuid.uuid4()}/copy", json={"name": "X"})
+    assert res.status_code == 401
+
+
+async def test_copy_missing_source_returns_404(client: AsyncClient, headers: dict):
+    res = await client.post(f"/api/v1/designs/{uuid.uuid4()}/copy", json={"name": "X"}, headers=headers)
+    assert res.status_code == 404
+
+
+async def test_copy_duplicates_nodes_edges_and_remaps_ids(client: AsyncClient, headers: dict):
+    source = await _create(client, headers, name="Source", icon="server")
+    n1 = node_payload(label="A")
+    n2 = node_payload(label="B")
+    e1 = edge_payload(n1["id"], n2["id"], label="link")
+    save = await client.post(
+        "/api/v1/canvas/save",
+        json={"nodes": [n1, n2], "edges": [e1], "viewport": {"x": 5, "y": 6, "zoom": 2}, "design_id": source["id"]},
+        headers=headers,
+    )
+    assert save.status_code == 200
+
+    res = await client.post(
+        f"/api/v1/designs/{source['id']}/copy", json={"name": "Copy", "icon": "network"}, headers=headers,
+    )
+    assert res.status_code == 201, res.text
+    copy = res.json()
+    assert copy["name"] == "Copy"
+    assert copy["icon"] == "network"
+    assert copy["design_type"] == "network"
+    assert copy["id"] != source["id"]
+
+    # Copied canvas has the same shape but fresh node ids, and edge re-pointed.
+    canvas = (await client.get("/api/v1/canvas", params={"design_id": copy["id"]}, headers=headers)).json()
+    assert {n["label"] for n in canvas["nodes"]} == {"A", "B"}
+    copied_ids = {n["id"] for n in canvas["nodes"]}
+    assert copied_ids.isdisjoint({n1["id"], n2["id"]})
+    assert len(canvas["edges"]) == 1
+    edge = canvas["edges"][0]
+    assert edge["source"] in copied_ids
+    assert edge["target"] in copied_ids
+    assert edge["label"] == "link"
+    assert canvas["viewport"] == {"x": 5, "y": 6, "zoom": 2}
+
+
+async def test_copy_remaps_parent_child_relationship(client: AsyncClient, headers: dict):
+    source = await _create(client, headers, name="Nested")
+    parent = node_payload(label="P", type="proxmox", container_mode=True)
+    child = node_payload(label="C", type="vm", parent_id=parent["id"])
+    save = await client.post(
+        "/api/v1/canvas/save",
+        json={"nodes": [parent, child], "edges": [], "viewport": {}, "design_id": source["id"]},
+        headers=headers,
+    )
+    assert save.status_code == 200
+
+    res = await client.post(f"/api/v1/designs/{source['id']}/copy", json={"name": "Copy"}, headers=headers)
+    assert res.status_code == 201
+    copy = res.json()
+
+    canvas = (await client.get("/api/v1/canvas", params={"design_id": copy["id"]}, headers=headers)).json()
+    by_label = {n["label"]: n for n in canvas["nodes"]}
+    # Child's parent_id points at the COPIED parent, not the original.
+    assert by_label["C"]["parent_id"] == by_label["P"]["id"]
+    assert by_label["C"]["parent_id"] != parent["id"]
+
+
+async def test_copy_leaves_source_untouched(client: AsyncClient, headers: dict):
+    source = await _create(client, headers, name="Source")
+    n1 = node_payload(label="A")
+    await client.post(
+        "/api/v1/canvas/save",
+        json={"nodes": [n1], "edges": [], "viewport": {}, "design_id": source["id"]},
+        headers=headers,
+    )
+    await client.post(f"/api/v1/designs/{source['id']}/copy", json={"name": "Copy"}, headers=headers)
+    src_canvas = (await client.get("/api/v1/canvas", params={"design_id": source["id"]}, headers=headers)).json()
+    assert len(src_canvas["nodes"]) == 1
+    assert src_canvas["nodes"][0]["id"] == n1["id"]
+
+
 # ── update ────────────────────────────────────────────────────────────────────
 
 async def test_update_design_renames(client: AsyncClient, headers: dict):

backend/tests/test_edges.py

@@ -2,13 +2,6 @@ import pytest
 from httpx import AsyncClient
 
 
-@pytest.fixture
-async def headers(client: AsyncClient):
-    res = await client.post("/api/v1/auth/login", json={"username": "admin", "password": "admin"})
-    token = res.json()["access_token"]
-    return {"Authorization": f"Bearer {token}"}
-
-
 @pytest.fixture
 async def two_nodes(client: AsyncClient, headers: dict):
     n1 = (await client.post("/api/v1/nodes", json={"type": "router", "label": "R1", "status": "online"}, headers=headers)).json()
@@ -91,6 +84,70 @@ async def test_update_edge_custom_color_and_path_style(client: AsyncClient, head
     assert res.json()["path_style"] == "smooth"
 
 
+async def test_create_edge_with_line_style_and_width(client: AsyncClient, headers: dict, two_nodes):
+    src, tgt = two_nodes
+    res = await client.post("/api/v1/edges", json={"source": src, "target": tgt, "type": "wifi", "line_style": "dotted", "width_mult": 3}, headers=headers)
+    assert res.status_code == 201
+    assert res.json()["line_style"] == "dotted"
+    assert res.json()["width_mult"] == 3
+
+
+async def test_update_edge_line_style_and_width(client: AsyncClient, headers: dict, two_nodes):
+    src, tgt = two_nodes
+    edge_id = (await client.post("/api/v1/edges", json={"source": src, "target": tgt, "type": "ethernet"}, headers=headers)).json()["id"]
+    res = await client.patch(f"/api/v1/edges/{edge_id}", json={"line_style": "dashed", "width_mult": 2}, headers=headers)
+    assert res.status_code == 200
+    assert res.json()["line_style"] == "dashed"
+    assert res.json()["width_mult"] == 2
+
+
+async def test_create_edge_defaults_line_style_none(client: AsyncClient, headers: dict, two_nodes):
+    src, tgt = two_nodes
+    res = await client.post("/api/v1/edges", json={"source": src, "target": tgt, "type": "ethernet"}, headers=headers)
+    assert res.status_code == 201
+    assert res.json()["line_style"] is None
+    assert res.json()["width_mult"] is None
+
+
+async def test_create_edge_with_marker_shapes(client: AsyncClient, headers: dict, two_nodes):
+    src, tgt = two_nodes
+    res = await client.post("/api/v1/edges", json={"source": src, "target": tgt, "type": "ethernet", "marker_start": "diamond", "marker_end": "arrow"}, headers=headers)
+    assert res.status_code == 201
+    assert res.json()["marker_start"] == "diamond"
+    assert res.json()["marker_end"] == "arrow"
+
+
+async def test_create_edge_defaults_markers_none(client: AsyncClient, headers: dict, two_nodes):
+    src, tgt = two_nodes
+    res = await client.post("/api/v1/edges", json={"source": src, "target": tgt, "type": "ethernet"}, headers=headers)
+    assert res.status_code == 201
+    assert res.json()["marker_start"] == "none"
+    assert res.json()["marker_end"] == "none"
+
+
+async def test_create_edge_coerces_legacy_boolean_marker(client: AsyncClient, headers: dict, two_nodes):
+    src, tgt = two_nodes
+    res = await client.post("/api/v1/edges", json={"source": src, "target": tgt, "type": "ethernet", "marker_end": True}, headers=headers)
+    assert res.status_code == 201
+    assert res.json()["marker_end"] == "arrow"
+
+
+async def test_create_edge_rejects_unknown_marker_shape(client: AsyncClient, headers: dict, two_nodes):
+    src, tgt = two_nodes
+    res = await client.post("/api/v1/edges", json={"source": src, "target": tgt, "type": "ethernet", "marker_end": "bogus"}, headers=headers)
+    assert res.status_code == 201
+    assert res.json()["marker_end"] == "none"
+
+
+async def test_update_edge_marker_shape(client: AsyncClient, headers: dict, two_nodes):
+    src, tgt = two_nodes
+    edge_id = (await client.post("/api/v1/edges", json={"source": src, "target": tgt, "type": "ethernet"}, headers=headers)).json()["id"]
+    res = await client.patch(f"/api/v1/edges/{edge_id}", json={"marker_end": "circle"}, headers=headers)
+    assert res.status_code == 200
+    assert res.json()["marker_end"] == "circle"
+    assert res.json()["marker_start"] == "none"
+
+
 async def test_create_edge_requires_auth(client: AsyncClient, two_nodes):
     src, tgt = two_nodes
     res = await client.post("/api/v1/edges", json={"source": src, "target": tgt, "type": "ethernet"})
@@ -163,3 +220,113 @@ async def test_source_and_target_handle_persist_through_update(client: AsyncClie
     assert data["source_handle"] == "cluster-right"
     assert data["target_handle"] == "cluster-left"
     assert data["label"] == "corosync"
+
+
+# ---------------------------------------------------------------------------
+# Auto edge handles (issue #265): omitting source_handle/target_handle lets
+# the backend infer up/downstream sides from the nodes' absolute canvas Y.
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+async def stacked_nodes(client: AsyncClient, headers: dict):
+    """Two root nodes at known, distinct Y positions (top at y=0, bottom at y=300)."""
+    top = (
+        await client.post(
+            "/api/v1/nodes",
+            json={"type": "router", "label": "Top", "status": "online", "pos_x": 0, "pos_y": 0},
+            headers=headers,
+        )
+    ).json()
+    bottom = (
+        await client.post(
+            "/api/v1/nodes",
+            json={"type": "switch", "label": "Bottom", "status": "online", "pos_x": 0, "pos_y": 300},
+            headers=headers,
+        )
+    ).json()
+    return top["id"], bottom["id"]
+
+
+async def test_create_edge_auto_handles_source_above_target(client: AsyncClient, headers: dict, stacked_nodes):
+    """Source above target -> downstream flow: exit bottom, enter top-t."""
+    top, bottom = stacked_nodes
+    res = await client.post(
+        "/api/v1/edges", json={"source": top, "target": bottom, "type": "ethernet"}, headers=headers
+    )
+    assert res.status_code == 201
+    data = res.json()
+    assert data["source_handle"] == "bottom"
+    assert data["target_handle"] == "top-t"
+
+
+async def test_create_edge_auto_handles_source_below_target(client: AsyncClient, headers: dict, stacked_nodes):
+    """Source below target -> upstream flow: exit top, enter bottom-t."""
+    top, bottom = stacked_nodes
+    res = await client.post(
+        "/api/v1/edges", json={"source": bottom, "target": top, "type": "ethernet"}, headers=headers
+    )
+    assert res.status_code == 201
+    data = res.json()
+    assert data["source_handle"] == "top"
+    assert data["target_handle"] == "bottom-t"
+
+
+async def test_create_edge_auto_handles_equal_y_defaults_downstream(client: AsyncClient, headers: dict, two_nodes):
+    """Same Y (auto-placed side by side) falls back to the default bottom/top-t."""
+    src, tgt = two_nodes
+    res = await client.post(
+        "/api/v1/edges", json={"source": src, "target": tgt, "type": "ethernet"}, headers=headers
+    )
+    assert res.status_code == 201
+    data = res.json()
+    assert data["source_handle"] == "bottom"
+    assert data["target_handle"] == "top-t"
+
+
+async def test_create_edge_partial_handle_auto_fills_the_other(client: AsyncClient, headers: dict, stacked_nodes):
+    """An explicit source_handle is kept; the omitted target_handle is inferred."""
+    top, bottom = stacked_nodes
+    res = await client.post(
+        "/api/v1/edges",
+        json={"source": top, "target": bottom, "type": "ethernet", "source_handle": "cluster-right"},
+        headers=headers,
+    )
+    assert res.status_code == 201
+    data = res.json()
+    assert data["source_handle"] == "cluster-right"
+    assert data["target_handle"] == "top-t"
+
+
+async def test_create_edge_child_node_abs_y_resolved_through_parent(client: AsyncClient, headers: dict):
+    """A child's absolute Y = parent Y + its own pos_y, so a VM low inside a high
+    container still resolves as downstream of a node above the container."""
+    parent = (
+        await client.post(
+            "/api/v1/nodes",
+            json={"type": "proxmox", "label": "PVE", "status": "online", "container_mode": True, "pos_x": 0, "pos_y": 0},
+            headers=headers,
+        )
+    ).json()
+    child = (
+        await client.post(
+            "/api/v1/nodes",
+            json={"type": "vm", "label": "VM", "status": "online", "parent_id": parent["id"], "pos_x": 0, "pos_y": 50},
+            headers=headers,
+        )
+    ).json()
+    below = (
+        await client.post(
+            "/api/v1/nodes",
+            json={"type": "server", "label": "Below", "status": "online", "pos_x": 0, "pos_y": 500},
+            headers=headers,
+        )
+    ).json()
+    # child abs Y = 0 + 50 = 50, below at 500 -> child is upstream.
+    res = await client.post(
+        "/api/v1/edges", json={"source": child["id"], "target": below["id"], "type": "virtual"}, headers=headers
+    )
+    assert res.status_code == 201
+    data = res.json()
+    assert data["source_handle"] == "bottom"
+    assert data["target_handle"] == "top-t"

backend/tests/test_liveview.py

@@ -82,10 +82,9 @@ async def test_liveview_does_not_require_jwt(client: AsyncClient):
 
 
 @pytest.mark.asyncio
-async def test_liveview_returns_saved_canvas(client: AsyncClient, auth_headers):
+async def test_liveview_returns_saved_canvas(client: AsyncClient, headers):
     """Canvas saved via POST /canvas/save appears in liveview response."""
     settings.liveview_key = "test-key"
-    headers = await auth_headers()
 
     # Save a canvas with one node
     payload = {
@@ -115,10 +114,9 @@ async def test_liveview_returns_saved_canvas(client: AsyncClient, auth_headers):
 # ── custom_style + theme propagation ─────────────────────────────────────────
 
 @pytest.mark.asyncio
-async def test_liveview_returns_custom_style_and_theme(client: AsyncClient, auth_headers):
+async def test_liveview_returns_custom_style_and_theme(client: AsyncClient, headers):
     """custom_style and viewport.theme_id from a saved canvas surface in liveview."""
     settings.liveview_key = "test-key"
-    headers = await auth_headers()
     payload = {
         "nodes": [],
         "edges": [],
@@ -159,9 +157,8 @@ async def test_liveview_config_requires_auth(client: AsyncClient):
 
 
 @pytest.mark.asyncio
-async def test_liveview_config_returns_key_when_enabled(client: AsyncClient, auth_headers):
+async def test_liveview_config_returns_key_when_enabled(client: AsyncClient, headers):
     settings.liveview_key = "share-me"
-    headers = await auth_headers()
     res = await client.get("/api/v1/liveview/config", headers=headers)
     assert res.status_code == 200
     body = res.json()
@@ -169,18 +166,16 @@ async def test_liveview_config_returns_key_when_enabled(client: AsyncClient, aut
 
 
 @pytest.mark.asyncio
-async def test_liveview_config_disabled_hides_key(client: AsyncClient, auth_headers):
+async def test_liveview_config_disabled_hides_key(client: AsyncClient, headers):
     settings.liveview_key = None
-    headers = await auth_headers()
     res = await client.get("/api/v1/liveview/config", headers=headers)
     assert res.status_code == 200
     assert res.json() == {"enabled": False, "key": None}
 
 
 @pytest.mark.asyncio
-async def test_liveview_config_empty_key_disabled(client: AsyncClient, auth_headers):
+async def test_liveview_config_empty_key_disabled(client: AsyncClient, headers):
     settings.liveview_key = ""
-    headers = await auth_headers()
     res = await client.get("/api/v1/liveview/config", headers=headers)
     assert res.status_code == 200
     assert res.json() == {"enabled": False, "key": None}
@@ -189,10 +184,9 @@ async def test_liveview_config_empty_key_disabled(client: AsyncClient, auth_head
 # ── design_id selects which canvas is rendered ───────────────────────────────
 
 @pytest.mark.asyncio
-async def test_liveview_design_id_selects_canvas(client: AsyncClient, auth_headers):
+async def test_liveview_design_id_selects_canvas(client: AsyncClient, headers):
     """?design_id=<id> renders that design's canvas, not the first one."""
     settings.liveview_key = "test-key"
-    headers = await auth_headers()
 
     # Create two designs
     d1 = (await client.post("/api/v1/designs", json={"name": "Network"}, headers=headers)).json()

backend/tests/test_mac_utils.py

@@ -0,0 +1,27 @@
+"""Unit tests for MAC normalization (the cross-source dedup key)."""
+
+from __future__ import annotations
+
+from app.services.discovery_sources import add_source
+from app.services.mac_utils import normalize_mac
+
+
+def test_normalize_mac_lowercases_and_unifies_separators() -> None:
+    assert normalize_mac("BC:24:11:AA:BB:CC") == "bc:24:11:aa:bb:cc"
+    assert normalize_mac("bc-24-11-aa-bb-cc") == "bc:24:11:aa:bb:cc"
+    assert normalize_mac("  BC:24:11:AA:BB:CC  ") == "bc:24:11:aa:bb:cc"
+
+
+def test_normalize_mac_blank_is_none() -> None:
+    assert normalize_mac(None) is None
+    assert normalize_mac("") is None
+    assert normalize_mac("   ") is None
+
+
+def test_add_source_unions_without_duplicates() -> None:
+    assert add_source(None, "arp") == ["arp"]
+    assert add_source(["arp"], "proxmox") == ["arp", "proxmox"]
+    assert add_source(["arp", "proxmox"], "proxmox") == ["arp", "proxmox"]
+    assert add_source(["arp"], None) == ["arp"]
+    # Drops falsy members already present.
+    assert add_source(["arp", ""], "proxmox") == ["arp", "proxmox"]

backend/tests/test_media.py

@@ -0,0 +1,94 @@
+import re
+
+import pytest
+
+from app.api.routes import media
+from app.core.config import settings
+
+PNG_BYTES = b"\x89PNG\r\n\x1a\n" + b"0" * 32
+
+
+@pytest.fixture
+def media_dir(tmp_path, monkeypatch):
+    """Point uploads at a temp folder for the duration of a test."""
+    monkeypatch.setattr(settings, "upload_dir", str(tmp_path))
+    return tmp_path
+
+
+async def _upload(client, headers, name="plan.png", data=PNG_BYTES, content_type="image/png"):
+    return await client.post(
+        "/api/v1/media/upload",
+        files={"file": (name, data, content_type)},
+        headers=headers,
+    )
+
+
+@pytest.mark.asyncio
+async def test_upload_requires_auth(client, media_dir):
+    res = await _upload(client, headers={})
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_upload_stores_file_and_returns_url(client, headers, media_dir):
+    res = await _upload(client, headers)
+    assert res.status_code == 200
+    body = res.json()
+    assert re.fullmatch(r"/api/v1/media/[0-9a-f]{32}\.png", body["url"])
+    # File written to disk with the server-generated name (client name ignored).
+    assert (media_dir / body["filename"]).read_bytes() == PNG_BYTES
+    assert body["filename"] != "plan.png"
+
+
+@pytest.mark.asyncio
+async def test_upload_rejects_unsupported_type(client, headers, media_dir):
+    res = await _upload(client, headers, name="a.txt", data=b"hello", content_type="text/plain")
+    assert res.status_code == 415
+
+
+@pytest.mark.asyncio
+async def test_upload_rejects_content_type_magic_mismatch(client, headers, media_dir):
+    # Claims PNG but bytes are not a PNG.
+    res = await _upload(client, headers, data=b"not-a-real-png", content_type="image/png")
+    assert res.status_code == 415
+
+
+@pytest.mark.asyncio
+async def test_upload_rejects_oversize(client, headers, media_dir, monkeypatch):
+    monkeypatch.setattr(media, "MAX_BYTES", 8)
+    res = await _upload(client, headers, data=PNG_BYTES)  # > 8 bytes
+    assert res.status_code == 413
+
+
+@pytest.mark.asyncio
+async def test_get_serves_uploaded_file(client, headers, media_dir):
+    up = await _upload(client, headers)
+    res = await client.get(up.json()["url"])  # public, no auth
+    assert res.status_code == 200
+    assert res.content == PNG_BYTES
+
+
+@pytest.mark.asyncio
+async def test_get_rejects_bad_filename(client, media_dir):
+    res = await client.get("/api/v1/media/..%2f..%2fetc%2fpasswd")
+    assert res.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_delete_rejects_bad_filename(client, headers, media_dir):
+    res = await client.delete("/api/v1/media/..%2f..%2fetc%2fpasswd", headers=headers)
+    assert res.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_delete_requires_auth_and_removes_file(client, headers, media_dir):
+    up = await _upload(client, headers)
+    filename = up.json()["filename"]
+
+    assert (await client.delete(f"/api/v1/media/{filename}")).status_code == 401
+    assert (media_dir / filename).exists()
+
+    res = await client.delete(f"/api/v1/media/{filename}", headers=headers)
+    assert res.status_code == 204
+    assert not (media_dir / filename).exists()
+    assert (await client.get(up.json()["url"])).status_code == 404

backend/tests/test_node_dedupe.py

@@ -0,0 +1,117 @@
+"""Tests for the same-canvas node dedupe repair (app.services.node_dedupe)."""
+
+import pytest
+from sqlalchemy import select
+
+from app.db.models import Design, Edge, Node
+from app.services.node_dedupe import dedupe_nodes_by_ieee
+
+
+async def _design(db, name="d1"):
+    d = Design(name=name)
+    db.add(d)
+    await db.flush()
+    return d
+
+
+@pytest.mark.asyncio
+async def test_collapses_same_ieee_same_design(db_session):
+    d = await _design(db_session)
+    keep = Node(
+        label="Sensor", type="zigbee_enddevice", design_id=d.id,
+        ieee_address="0xAAA", properties=[{"key": "IEEE", "value": "0xAAA", "visible": True}],
+        pos_x=100, pos_y=200,
+    )
+    db_session.add(keep)
+    await db_session.flush()
+    dup = Node(
+        label="Sensor", type="zigbee_enddevice", design_id=d.id,
+        ieee_address="0xAAA", ip="10.0.0.5",
+        properties=[{"key": "LQI", "value": "88", "visible": False}],
+    )
+    db_session.add(dup)
+    await db_session.flush()
+
+    removed = await dedupe_nodes_by_ieee(db_session)
+    assert removed == 1
+
+    nodes = (await db_session.execute(select(Node).where(Node.ieee_address == "0xAAA"))).scalars().all()
+    assert len(nodes) == 1
+    survivor = nodes[0]
+    assert survivor.id == keep.id          # oldest kept
+    assert survivor.pos_x == 100           # canvas position preserved
+    assert survivor.ip == "10.0.0.5"       # missing field filled from dup
+    keys = {p["key"] for p in survivor.properties}
+    assert keys == {"IEEE", "LQI"}         # properties merged
+
+
+@pytest.mark.asyncio
+async def test_preserves_same_ieee_across_designs(db_session):
+    """Same device on two canvases is valid — must NOT be merged."""
+    d1 = await _design(db_session, "d1")
+    d2 = await _design(db_session, "d2")
+    for d in (d1, d2):
+        db_session.add(Node(label="S", type="zigbee_enddevice", design_id=d.id, ieee_address="0xBBB"))
+    await db_session.flush()
+
+    removed = await dedupe_nodes_by_ieee(db_session)
+    assert removed == 0
+
+    nodes = (await db_session.execute(select(Node).where(Node.ieee_address == "0xBBB"))).scalars().all()
+    assert len(nodes) == 2
+
+
+@pytest.mark.asyncio
+async def test_repoints_edges_and_drops_dupes(db_session):
+    d = await _design(db_session)
+    keep = Node(label="A", type="server", design_id=d.id, ieee_address="0xCCC")
+    dup = Node(label="A", type="server", design_id=d.id, ieee_address="0xCCC")
+    other = Node(label="B", type="server", design_id=d.id)
+    db_session.add_all([keep, other])
+    await db_session.flush()
+    db_session.add(dup)
+    await db_session.flush()
+
+    # keep<->other and dup<->other (parallel after repoint), plus dup<->keep (self-loop).
+    db_session.add_all([
+        Edge(source=keep.id, target=other.id, type="ethernet", design_id=d.id),
+        Edge(source=dup.id, target=other.id, type="ethernet", design_id=d.id),
+        Edge(source=dup.id, target=keep.id, type="ethernet", design_id=d.id),
+    ])
+    await db_session.flush()
+
+    removed = await dedupe_nodes_by_ieee(db_session)
+    assert removed == 1
+
+    edges = (await db_session.execute(select(Edge))).scalars().all()
+    # self-loop dropped, parallel edge collapsed -> a single keep<->other edge
+    assert len(edges) == 1
+    e = edges[0]
+    assert {e.source, e.target} == {keep.id, other.id}
+
+
+@pytest.mark.asyncio
+async def test_repoints_child_parent(db_session):
+    d = await _design(db_session)
+    keep = Node(label="Host", type="proxmox", design_id=d.id, ieee_address="0xDDD")
+    dup = Node(label="Host", type="proxmox", design_id=d.id, ieee_address="0xDDD")
+    db_session.add(keep)
+    await db_session.flush()
+    db_session.add(dup)
+    await db_session.flush()
+    child = Node(label="VM", type="vm", design_id=d.id, parent_id=dup.id)
+    db_session.add(child)
+    await db_session.flush()
+
+    await dedupe_nodes_by_ieee(db_session)
+    await db_session.refresh(child)
+    assert child.parent_id == keep.id
+
+
+@pytest.mark.asyncio
+async def test_idempotent_noop_when_unique(db_session):
+    d = await _design(db_session)
+    db_session.add(Node(label="X", type="server", design_id=d.id, ieee_address="0xEEE"))
+    await db_session.flush()
+    assert await dedupe_nodes_by_ieee(db_session) == 0
+    assert await dedupe_nodes_by_ieee(db_session) == 0

backend/tests/test_nodes.py

@@ -1,14 +1,6 @@
-import pytest
 from httpx import AsyncClient
 
 
-@pytest.fixture
-async def headers(client: AsyncClient):
-    res = await client.post("/api/v1/auth/login", json={"username": "admin", "password": "admin"})
-    token = res.json()["access_token"]
-    return {"Authorization": f"Bearer {token}"}
-
-
 async def test_list_nodes_empty(client: AsyncClient, headers: dict):
     res = await client.get("/api/v1/nodes", headers=headers)
     assert res.status_code == 200
@@ -99,6 +91,47 @@ async def test_create_node_respects_explicit_design_id(client: AsyncClient, head
     assert res.json()["design_id"] == second_id
 
 
+async def test_create_node_rejects_duplicate_ip_on_same_design(client: AsyncClient, headers: dict):
+    # A second node with the same ip on the same design is a silent duplicate —
+    # scripts/MCP clients get 409 with the existing node id instead. (#260)
+    design = await client.post("/api/v1/designs", json={"name": "D"}, headers=headers)
+    design_id = design.json()["id"]
+    first = await client.post(
+        "/api/v1/nodes",
+        json={"type": "server", "label": "srv", "ip": "192.168.1.5", "design_id": design_id},
+        headers=headers,
+    )
+    assert first.status_code == 201
+    existing_id = first.json()["id"]
+
+    dup = await client.post(
+        "/api/v1/nodes",
+        json={"type": "server", "label": "srv-again", "ip": "192.168.1.5", "design_id": design_id},
+        headers=headers,
+    )
+    assert dup.status_code == 409
+    detail = dup.json()["detail"]
+    assert detail["duplicate"] is True
+    assert detail["existing_node_id"] == existing_id
+    assert detail["match"] == "ip"
+
+
+async def test_create_node_force_bypasses_duplicate_guard(client: AsyncClient, headers: dict):
+    design = await client.post("/api/v1/designs", json={"name": "D"}, headers=headers)
+    design_id = design.json()["id"]
+    await client.post(
+        "/api/v1/nodes",
+        json={"type": "server", "label": "srv", "ip": "192.168.1.5", "design_id": design_id},
+        headers=headers,
+    )
+    forced = await client.post(
+        "/api/v1/nodes",
+        json={"type": "server", "label": "srv", "ip": "192.168.1.5", "design_id": design_id, "force": True},
+        headers=headers,
+    )
+    assert forced.status_code == 201
+
+
 async def test_create_node_without_any_design_stays_null(client: AsyncClient, headers: dict):
     # No designs exist yet: fallback can't invent one, so design_id stays null
     # rather than erroring.
@@ -253,3 +286,120 @@ async def test_properties_icon_can_be_null(client: AsyncClient, headers: dict):
     )
     assert create.status_code == 201
     assert create.json()["properties"] == props
+
+
+# ---------------------------------------------------------------------------
+# Auto-positioning (issue #265): omitting pos_x/pos_y snaps the node to the
+# first free 200x100 grid slot instead of stacking everything at (0, 0).
+# ---------------------------------------------------------------------------
+
+
+async def test_create_node_auto_positions_first_at_origin(client: AsyncClient, headers: dict):
+    """First root node with no coordinates lands at (0, 0)."""
+    res = await client.post(
+        "/api/v1/nodes", json={"type": "server", "label": "A", "status": "unknown"}, headers=headers
+    )
+    assert res.status_code == 201
+    data = res.json()
+    assert (data["pos_x"], data["pos_y"]) == (0.0, 0.0)
+
+
+async def test_create_node_auto_position_avoids_collision(client: AsyncClient, headers: dict):
+    """A second auto-placed root node takes the next free grid cell, not (0, 0)."""
+    first = await client.post(
+        "/api/v1/nodes", json={"type": "server", "label": "A", "status": "unknown"}, headers=headers
+    )
+    assert (first.json()["pos_x"], first.json()["pos_y"]) == (0.0, 0.0)
+
+    second = await client.post(
+        "/api/v1/nodes", json={"type": "server", "label": "B", "status": "unknown"}, headers=headers
+    )
+    assert second.status_code == 201
+    # Next free cell in row 0 is column 1 -> x = 1 * 200.
+    assert (second.json()["pos_x"], second.json()["pos_y"]) == (200.0, 0.0)
+
+
+async def test_create_node_child_defaults_to_parent_origin(client: AsyncClient, headers: dict):
+    """A child node (parent_id set) with no coordinates defaults to (0, 0) relative to its parent."""
+    parent = (
+        await client.post(
+            "/api/v1/nodes",
+            json={"type": "proxmox", "label": "PVE", "status": "online", "container_mode": True},
+            headers=headers,
+        )
+    ).json()
+    res = await client.post(
+        "/api/v1/nodes",
+        json={"type": "vm", "label": "VM1", "status": "online", "parent_id": parent["id"]},
+        headers=headers,
+    )
+    assert res.status_code == 201
+    data = res.json()
+    assert (data["pos_x"], data["pos_y"]) == (0.0, 0.0)
+
+
+async def test_create_node_explicit_position_preserved(client: AsyncClient, headers: dict):
+    """Explicit coordinates are honored, never auto-placed."""
+    res = await client.post(
+        "/api/v1/nodes",
+        json={"type": "server", "label": "A", "status": "unknown", "pos_x": 512.0, "pos_y": 384.0},
+        headers=headers,
+    )
+    assert res.status_code == 201
+    data = res.json()
+    assert (data["pos_x"], data["pos_y"]) == (512.0, 384.0)
+
+
+async def test_create_node_explicit_zero_position_preserved(client: AsyncClient, headers: dict):
+    """pos=0 is an explicit value, not 'omitted' — auto-position must not treat 0 as None."""
+    await client.post(
+        "/api/v1/nodes", json={"type": "server", "label": "A", "status": "unknown"}, headers=headers
+    )
+    # Second node explicitly pinned to (0, 0) even though the cell is taken.
+    res = await client.post(
+        "/api/v1/nodes",
+        json={"type": "server", "label": "B", "status": "unknown", "pos_x": 0, "pos_y": 0},
+        headers=headers,
+    )
+    assert res.status_code == 201
+    assert (res.json()["pos_x"], res.json()["pos_y"]) == (0.0, 0.0)
+
+
+async def test_list_nodes_filters_by_label_exact(client: AsyncClient, headers: dict):
+    await client.post("/api/v1/nodes", json={"type": "server", "label": "Proxmox", "status": "unknown"}, headers=headers)
+    await client.post("/api/v1/nodes", json={"type": "router", "label": "Router", "status": "unknown"}, headers=headers)
+    res = await client.get("/api/v1/nodes?label=Proxmox", headers=headers)
+    assert res.status_code == 200
+    assert [n["label"] for n in res.json()] == ["Proxmox"]
+
+
+async def test_list_nodes_filters_by_label_substring(client: AsyncClient, headers: dict):
+    await client.post("/api/v1/nodes", json={"type": "server", "label": "pve1-node", "status": "unknown"}, headers=headers)
+    await client.post("/api/v1/nodes", json={"type": "server", "label": "pve2-node", "status": "unknown"}, headers=headers)
+    await client.post("/api/v1/nodes", json={"type": "router", "label": "Router", "status": "unknown"}, headers=headers)
+    res = await client.get("/api/v1/nodes?label=pve", headers=headers)
+    assert res.status_code == 200
+    assert sorted(n["label"] for n in res.json()) == ["pve1-node", "pve2-node"]
+
+
+async def test_list_nodes_filters_by_label_case_insensitive(client: AsyncClient, headers: dict):
+    await client.post("/api/v1/nodes", json={"type": "server", "label": "Proxmox", "status": "unknown"}, headers=headers)
+    res = await client.get("/api/v1/nodes?label=PROXMOX", headers=headers)
+    assert res.status_code == 200
+    assert [n["label"] for n in res.json()] == ["Proxmox"]
+
+
+async def test_list_nodes_filters_by_label_no_match(client: AsyncClient, headers: dict):
+    await client.post("/api/v1/nodes", json={"type": "server", "label": "Proxmox", "status": "unknown"}, headers=headers)
+    res = await client.get("/api/v1/nodes?label=nonexistent", headers=headers)
+    assert res.status_code == 200
+    assert res.json() == []
+
+
+async def test_list_nodes_without_label_param_returns_all(client: AsyncClient, headers: dict):
+    """Omitting label is fully backward compatible with the old unfiltered behavior."""
+    for label in ("A", "B", "C"):
+        await client.post("/api/v1/nodes", json={"type": "generic", "label": label, "status": "unknown"}, headers=headers)
+    res = await client.get("/api/v1/nodes", headers=headers)
+    assert res.status_code == 200
+    assert len(res.json()) == 3

backend/tests/test_proxmox_router.py

@@ -0,0 +1,489 @@
+"""API + persistence tests for /api/v1/proxmox/*."""
+
+from __future__ import annotations
+
+import uuid
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy import select
+
+from app.api.routes.proxmox import (
+    _background_proxmox_import,
+    _guest_visibility_advisory,
+    _persist_pending_import,
+)
+from app.api.routes.scan import _is_proxmox_cluster_member, _resolve_pending_links_for_ieee
+from app.core.config import settings
+from app.db.models import Design, Edge, InventoryDevice, InventoryDeviceLink, Node
+
+
+@pytest.fixture(autouse=True)
+def _clear_env_token():
+    """Ensure a clean token state per test; restore afterwards."""
+    tid, sec = settings.proxmox_token_id, settings.proxmox_token_secret
+    settings.proxmox_token_id = ""
+    settings.proxmox_token_secret = ""
+    yield
+    settings.proxmox_token_id, settings.proxmox_token_secret = tid, sec
+
+
+def _host_node() -> dict:
+    return {
+        "id": "pve-node-pve1", "label": "pve1", "type": "proxmox",
+        "ieee_address": "pve-node-pve1", "hostname": "pve1", "ip": None,
+        "status": "online", "cpu_count": 8, "ram_gb": 16.0, "disk_gb": 500.0,
+        "vendor": "Proxmox VE", "model": None, "parent_ieee": None,
+    }
+
+
+def _guest_node(vmid: int, ip: str | None, status: str = "online", mac: str | None = None) -> dict:
+    return {
+        "id": f"pve-pve1-{vmid}", "label": f"vm{vmid}", "type": "vm",
+        "ieee_address": f"pve-pve1-{vmid}", "hostname": f"vm{vmid}", "ip": ip,
+        "mac": mac,
+        "status": status, "cpu_count": 2, "ram_gb": 4.0, "disk_gb": 32.0,
+        "vendor": "Proxmox VE", "model": "QEMU", "vmid": vmid,
+        "parent_ieee": "pve-node-pve1",
+    }
+
+
+# --- endpoints -------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_test_connection_uses_body_token(client: AsyncClient, headers: dict) -> None:
+    with patch("app.api.routes.proxmox.test_proxmox_connection", new=AsyncMock(return_value=(True, "ok"))):
+        res = await client.post(
+            "/api/v1/proxmox/test-connection",
+            json={"host": "pve", "port": 8006, "token_id": "u@pam!t", "token_secret": "s"},
+            headers=headers,
+        )
+    assert res.status_code == 200
+    assert res.json()["connected"] is True
+
+
+@pytest.mark.asyncio
+async def test_missing_token_is_rejected(client: AsyncClient, headers: dict) -> None:
+    res = await client.post(
+        "/api/v1/proxmox/test-connection",
+        json={"host": "pve", "port": 8006},
+        headers=headers,
+    )
+    assert res.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_import_pending_creates_scan_run(client: AsyncClient, headers: dict) -> None:
+    with patch("app.api.routes.proxmox._background_proxmox_import", new_callable=AsyncMock):
+        res = await client.post(
+            "/api/v1/proxmox/import-pending",
+            json={"host": "pve", "port": 8006, "token_id": "u@pam!t", "token_secret": "s"},
+            headers=headers,
+        )
+    assert res.status_code == 200
+    data = res.json()
+    assert data["kind"] == "proxmox"
+    assert data["status"] == "running"
+
+
+@pytest.mark.asyncio
+async def test_sync_now_creates_scan_run(client: AsyncClient, headers: dict) -> None:
+    settings.proxmox_host = "pve"
+    settings.proxmox_token_id = "u@pam!t"
+    settings.proxmox_token_secret = "s"
+    with patch("app.api.routes.proxmox._background_proxmox_import", new_callable=AsyncMock):
+        res = await client.post("/api/v1/proxmox/sync-now", headers=headers)
+    assert res.status_code == 200
+    data = res.json()
+    assert data["kind"] == "proxmox"
+    assert data["status"] == "running"
+
+
+@pytest.mark.asyncio
+async def test_sync_now_rejected_without_token(client: AsyncClient, headers: dict) -> None:
+    settings.proxmox_host = "pve"
+    # _clear_env_token leaves token empty
+    res = await client.post("/api/v1/proxmox/sync-now", headers=headers)
+    assert res.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_sync_now_requires_auth(client: AsyncClient) -> None:
+    res = await client.post("/api/v1/proxmox/sync-now")
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_requires_auth(client: AsyncClient) -> None:
+    res = await client.post("/api/v1/proxmox/import-pending", json={"host": "pve"})
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_config_omits_token(client: AsyncClient, headers: dict) -> None:
+    settings.proxmox_token_id = "u@pam!t"
+    settings.proxmox_token_secret = "supersecret"
+    res = await client.get("/api/v1/proxmox/config", headers=headers)
+    assert res.status_code == 200
+    body = res.text
+    assert "supersecret" not in body
+    assert res.json()["token_configured"] is True
+
+
+@pytest.mark.asyncio
+async def test_enable_sync_without_token_rejected(client: AsyncClient, headers: dict) -> None:
+    # _clear_env_token leaves token empty → enabling auto-sync is rejected.
+    res = await client.post(
+        "/api/v1/proxmox/config",
+        json={"sync_enabled": True, "sync_interval": 600},
+        headers=headers,
+    )
+    assert res.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_save_config_persists_only_sync_fields(client: AsyncClient, headers: dict) -> None:
+    """Connection config is env-only: even if a client sends host/port/verify,
+    the endpoint ignores them and persists only the sync activation."""
+    settings.proxmox_host = "pve"
+    settings.proxmox_token_id = "u@pam!t"
+    settings.proxmox_token_secret = "s"
+    saved: dict = {}
+    with patch.object(type(settings), "save_overrides", lambda self: saved.update(
+        host=self.proxmox_host, enabled=self.proxmox_sync_enabled, interval=self.proxmox_sync_interval
+    )), patch("app.api.routes.proxmox.set_proxmox_sync_enabled"), \
+            patch("app.api.routes.proxmox.reschedule_proxmox_sync"):
+        res = await client.post(
+            "/api/v1/proxmox/config",
+            json={"host": "attacker", "port": 1, "verify_tls": False, "sync_enabled": True, "sync_interval": 900},
+            headers=headers,
+        )
+    assert res.status_code == 200
+    # host untouched by the request body; sync activation applied.
+    assert settings.proxmox_host == "pve"
+    assert saved == {"host": "pve", "enabled": True, "interval": 900}
+
+
+@pytest.mark.asyncio
+async def test_background_import_broadcasts_refresh() -> None:
+    """After persisting, the import emits a scan update so an open inventory
+    reloads without a manual refresh (same signal the IP scan uses)."""
+    fake_db = AsyncMock()
+    fake_db.get = AsyncMock(return_value=None)  # no ScanRun row → skip status update
+    cm = AsyncMock()
+    cm.__aenter__.return_value = fake_db
+    cm.__aexit__.return_value = False
+
+    with patch("app.api.routes.proxmox.AsyncSessionLocal", MagicMock(return_value=cm)), \
+         patch("app.api.routes.proxmox.fetch_proxmox_inventory", new=AsyncMock(return_value=([], []))), \
+         patch("app.api.routes.proxmox._persist_pending_import",
+               new=AsyncMock(return_value=SimpleNamespace(device_count=3))), \
+         patch("app.api.routes.status.broadcast_scan_update", new=AsyncMock()) as bcast:
+        await _background_proxmox_import("run1", "h", 8006, "u@pam!t", "s", True)
+
+    bcast.assert_awaited_once()
+    assert bcast.await_args.kwargs["devices_found"] == 3
+
+
+# --- guest-visibility advisory ---------------------------------------------
+
+def test_advisory_when_hosts_only() -> None:
+    msg = _guest_visibility_advisory([_host_node()])
+    assert msg is not None
+    assert "PVEAuditor" in msg
+
+
+def test_no_advisory_when_guests_present() -> None:
+    assert _guest_visibility_advisory([_host_node(), _guest_node(101, "10.0.0.5")]) is None
+
+
+def test_no_advisory_when_nothing_imported() -> None:
+    assert _guest_visibility_advisory([]) is None
+
+
+# --- persistence / dedupe --------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_persist_creates_pending(db_session) -> None:
+    nodes = [_host_node(), _guest_node(101, "10.0.0.5")]
+    edges = [{"source": "pve-node-pve1", "target": "pve-pve1-101"}]
+    result = await _persist_pending_import(db_session, nodes, edges)
+    assert result.pending_created == 2
+    assert result.links_recorded == 1
+    rows = (await db_session.execute(select(InventoryDevice))).scalars().all()
+    assert {r.suggested_type for r in rows} == {"proxmox", "vm"}
+    # Specs carried as properties.
+    vm = next(r for r in rows if r.suggested_type == "vm")
+    assert any(p["key"] == "CPU Cores" for p in vm.properties)
+
+
+@pytest.mark.asyncio
+async def test_persist_merges_existing_scanned_node_by_ip(db_session) -> None:
+    # A device previously found by an IP scan (no ieee, no specs).
+    scanned = Node(
+        id=str(uuid.uuid4()), type="generic", label="10.0.0.5",
+        ip="10.0.0.5", status="online", pos_x=0, pos_y=0,
+    )
+    db_session.add(scanned)
+    await db_session.commit()
+
+    await _persist_pending_import(db_session, [_guest_node(101, "10.0.0.5")], [])
+
+    # No duplicate node; identity + specs merged onto the existing one.
+    nodes = (await db_session.execute(select(Node).where(Node.ip == "10.0.0.5"))).scalars().all()
+    assert len(nodes) == 1
+    merged = nodes[0]
+    assert merged.ieee_address == "pve-pve1-101"
+    assert merged.cpu_count == 2
+    assert any(p["key"] == "CPU Cores" for p in (merged.properties or []))
+    # Inventory row exists as approved (already on canvas).
+    inv = (await db_session.execute(select(InventoryDevice).where(InventoryDevice.ieee_address == "pve-pve1-101"))).scalar_one()
+    assert inv.status == "approved"
+
+
+@pytest.mark.asyncio
+async def test_persist_merges_pending_scan_row_by_mac(db_session) -> None:
+    # Device previously found by an IP scan: arp source, MAC known, no ieee.
+    db_session.add(InventoryDevice(
+        id=str(uuid.uuid4()), ip="10.0.0.5", mac="bc:24:11:aa:bb:cc",
+        suggested_type="generic", status="pending",
+        discovery_source="arp", discovery_sources=["arp"],
+    ))
+    await db_session.commit()
+
+    # Proxmox import of the same box (stopped VM → no IP) but same NIC MAC in a
+    # different casing. Must merge, not duplicate.
+    await _persist_pending_import(db_session, [_guest_node(101, None, mac="BC:24:11:AA:BB:CC")], [])
+
+    rows = (await db_session.execute(select(InventoryDevice))).scalars().all()
+    assert len(rows) == 1
+    row = rows[0]
+    assert row.ieee_address == "pve-pve1-101"          # adopted proxmox identity
+    assert row.suggested_type == "vm"                  # kept proxmox type
+    assert set(row.discovery_sources) == {"arp", "proxmox"}  # shows in both filters
+
+
+@pytest.mark.asyncio
+async def test_persist_preserves_ip_tag_for_legacy_null_source_row(db_session) -> None:
+    # Legacy inventory row from an old IP scan, before discovery_source(s) were
+    # recorded: scalar NULL, sources empty — but it has an IP + MAC.
+    db_session.add(InventoryDevice(
+        id=str(uuid.uuid4()), ip="192.168.1.108", mac="bc:24:11:6c:96:52",
+        suggested_type="lxc", status="pending",
+        discovery_source=None, discovery_sources=[],
+    ))
+    await db_session.commit()
+
+    await _persist_pending_import(
+        db_session, [_guest_node(108, "192.168.1.108", mac="BC:24:11:6C:96:52")], []
+    )
+
+    rows = (await db_session.execute(select(InventoryDevice))).scalars().all()
+    assert len(rows) == 1
+    # The IP tag must survive the proxmox merge even with no recorded origin.
+    assert set(rows[0].discovery_sources) == {"arp", "proxmox"}
+
+
+@pytest.mark.asyncio
+async def test_persist_preserves_ip_tag_on_canvas_merge_legacy_row(db_session) -> None:
+    # The immich case: an on-canvas node from an old scan, with a legacy
+    # inventory row (NULL source). Merge must keep the IP tag on the row.
+    node = Node(
+        id=str(uuid.uuid4()), type="lxc", label="immich",
+        ip="192.168.1.108", mac="bc:24:11:6c:96:52",
+        status="online", pos_x=0, pos_y=0,
+    )
+    inv = InventoryDevice(
+        id=str(uuid.uuid4()), ip="192.168.1.108", mac="bc:24:11:6c:96:52",
+        suggested_type="lxc", status="approved",
+        discovery_source=None, discovery_sources=[],
+    )
+    db_session.add_all([node, inv])
+    await db_session.commit()
+
+    await _persist_pending_import(
+        db_session, [_guest_node(108, "192.168.1.108", mac="BC:24:11:6C:96:52")], []
+    )
+
+    inv_row = (await db_session.execute(
+        select(InventoryDevice).where(InventoryDevice.mac == "bc:24:11:6c:96:52")
+    )).scalar_one()
+    assert set(inv_row.discovery_sources) == {"arp", "proxmox"}
+
+
+@pytest.mark.asyncio
+async def test_persist_does_not_add_ip_tag_to_pure_proxmox_guest(db_session) -> None:
+    # A guest first seen via Proxmox (agent IP, pve ieee) must NOT gain a spurious
+    # IP tag on re-sync — it was never IP-scanned.
+    await _persist_pending_import(db_session, [_guest_node(101, "10.0.0.5")], [])
+    await _persist_pending_import(db_session, [_guest_node(101, "10.0.0.5")], [])  # re-sync
+    row = (await db_session.execute(
+        select(InventoryDevice).where(InventoryDevice.ieee_address == "pve-pve1-101")
+    )).scalar_one()
+    assert set(row.discovery_sources) == {"proxmox"}
+
+
+@pytest.mark.asyncio
+async def test_persist_merges_canvas_node_by_mac(db_session) -> None:
+    # A scanned canvas node with a MAC but no IP recorded for the guest.
+    scanned = Node(
+        id=str(uuid.uuid4()), type="generic", label="box",
+        mac="bc:24:11:aa:bb:cc", status="online", pos_x=0, pos_y=0,
+    )
+    db_session.add(scanned)
+    await db_session.commit()
+
+    await _persist_pending_import(db_session, [_guest_node(101, None, mac="BC:24:11:AA:BB:CC")], [])
+
+    nodes = (await db_session.execute(select(Node))).scalars().all()
+    assert len(nodes) == 1                              # no duplicate node
+    merged = nodes[0]
+    assert merged.ieee_address == "pve-pve1-101"
+    assert merged.mac == "bc:24:11:aa:bb:cc"
+    assert merged.cpu_count == 2                        # specs backfilled
+
+
+@pytest.mark.asyncio
+async def test_persist_resync_updates_in_place(db_session) -> None:
+    nodes = [_guest_node(101, "10.0.0.5")]
+    await _persist_pending_import(db_session, nodes, [])
+    # Second sync: same device, new IP. Should update, not duplicate.
+    await _persist_pending_import(db_session, [_guest_node(101, "10.0.0.9")], [])
+    rows = (await db_session.execute(select(InventoryDevice).where(InventoryDevice.ieee_address == "pve-pve1-101"))).scalars().all()
+    assert len(rows) == 1
+    assert rows[0].ip == "10.0.0.9"
+
+
+@pytest.mark.asyncio
+async def test_persist_keeps_hidden_hidden(db_session) -> None:
+    db_session.add(InventoryDevice(
+        id=str(uuid.uuid4()), ieee_address="pve-pve1-101", ip="10.0.0.5",
+        suggested_type="vm", status="hidden", discovery_source="proxmox",
+    ))
+    await db_session.commit()
+    await _persist_pending_import(db_session, [_guest_node(101, "10.0.0.5")], [])
+    row = (await db_session.execute(select(InventoryDevice).where(InventoryDevice.ieee_address == "pve-pve1-101"))).scalar_one()
+    assert row.status == "hidden"
+
+
+@pytest.mark.asyncio
+async def test_pending_endpoint_tolerates_legacy_null_properties(client: AsyncClient, headers: dict, db_session) -> None:
+    # Legacy row: properties column NULL (added by migration on older DBs).
+    dev = InventoryDevice(
+        id=str(uuid.uuid4()), ip="192.168.1.9", suggested_type="server",
+        status="pending", discovery_source="arp",
+    )
+    dev.properties = None
+    db_session.add(dev)
+    await db_session.commit()
+    res = await client.get("/api/v1/scan/pending", headers=headers)
+    assert res.status_code == 200
+    assert res.json()[0]["properties"] == []
+
+
+# --- cluster links ---------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_persist_records_cluster_links_between_hosts(db_session) -> None:
+    # Two hosts + a guest → one host↔host cluster link, one host→guest link.
+    nodes = [
+        {**_host_node(), "id": "pve-node-a", "ieee_address": "pve-node-a", "hostname": "a", "label": "a"},
+        {**_host_node(), "id": "pve-node-b", "ieee_address": "pve-node-b", "hostname": "b", "label": "b"},
+        _guest_node(101, "10.0.0.5"),
+    ]
+    edges = [{"source": "pve-node-pve1", "target": "pve-pve1-101"}]
+    await _persist_pending_import(db_session, nodes, edges)
+
+    links = (await db_session.execute(select(InventoryDeviceLink))).scalars().all()
+    cluster = [ln for ln in links if ln.discovery_source == "proxmox_cluster"]
+    assert len(cluster) == 1
+    assert (cluster[0].source_ieee, cluster[0].target_ieee) == ("pve-node-a", "pve-node-b")
+    # Membership helper sees both endpoints.
+    assert await _is_proxmox_cluster_member(db_session, "pve-node-a") is True
+    assert await _is_proxmox_cluster_member(db_session, "pve-node-b") is True
+    assert await _is_proxmox_cluster_member(db_session, "pve-pve1-101") is False
+
+
+@pytest.mark.asyncio
+async def test_single_host_records_no_cluster_link(db_session) -> None:
+    await _persist_pending_import(db_session, [_host_node()], [])
+    links = (await db_session.execute(
+        select(InventoryDeviceLink).where(InventoryDeviceLink.discovery_source == "proxmox_cluster")
+    )).scalars().all()
+    assert links == []
+
+
+@pytest.mark.asyncio
+async def test_cluster_link_resolves_to_cluster_edge(db_session) -> None:
+    # Two host nodes already on a canvas + a pending cluster link between them.
+    design = Design(id=str(uuid.uuid4()), name="d")
+    db_session.add(design)
+    a = Node(id=str(uuid.uuid4()), type="proxmox", label="a", ieee_address="pve-node-a",
+             status="online", pos_x=0, pos_y=0, design_id=design.id,
+             left_handles=1, right_handles=1)
+    b = Node(id=str(uuid.uuid4()), type="proxmox", label="b", ieee_address="pve-node-b",
+             status="online", pos_x=0, pos_y=0, design_id=design.id,
+             left_handles=1, right_handles=1)
+    db_session.add_all([a, b])
+    db_session.add(InventoryDeviceLink(
+        id=str(uuid.uuid4()), source_ieee="pve-node-a", target_ieee="pve-node-b",
+        discovery_source="proxmox_cluster",
+    ))
+    await db_session.commit()
+
+    await _resolve_pending_links_for_ieee(db_session, "pve-node-a", design.id)
+
+    edge = (await db_session.execute(select(Edge))).scalars().one()
+    assert edge.type == "cluster"
+    assert edge.source_handle == "right"
+    # Bare side name (canonical) so React Flow resolves it to the left side;
+    # a '-t' target would fall back to the top handle.
+    assert edge.target_handle == "left"
+
+
+@pytest.mark.asyncio
+async def test_link_survives_and_resolves_onto_second_design(db_session) -> None:
+    # Regression: approving the same mesh devices onto a second canvas must also
+    # get their edges. The link row is topology, not one-shot — resolving it on
+    # design A must not consume it, so design B resolves too.
+    da = Design(id=str(uuid.uuid4()), name="a")
+    db_ = Design(id=str(uuid.uuid4()), name="b")
+    db_session.add_all([da, db_])
+    # Same two devices placed on BOTH designs (one Node per canvas).
+    for d in (da, db_):
+        db_session.add_all([
+            Node(id=str(uuid.uuid4()), type="iot", label="x", ieee_address="0xAAAA",
+                 status="online", pos_x=0, pos_y=0, design_id=d.id),
+            Node(id=str(uuid.uuid4()), type="iot", label="y", ieee_address="0xBBBB",
+                 status="online", pos_x=0, pos_y=0, design_id=d.id),
+        ])
+    db_session.add(InventoryDeviceLink(
+        id=str(uuid.uuid4()), source_ieee="0xAAAA", target_ieee="0xBBBB",
+        discovery_source="zigbee",
+    ))
+    await db_session.commit()
+
+    first = await _resolve_pending_links_for_ieee(db_session, "0xAAAA", da.id)
+    second = await _resolve_pending_links_for_ieee(db_session, "0xAAAA", db_.id)
+
+    assert len(first) == 1
+    assert len(second) == 1  # would be 0 if the link were consumed on design A
+    # One iot edge per design, each between that design's own nodes.
+    edges = (await db_session.execute(select(Edge))).scalars().all()
+    assert len(edges) == 2
+    assert {e.design_id for e in edges} == {da.id, db_.id}
+    assert all(e.type == "iot" for e in edges)
+    # The link row is still present for any further design.
+    assert (await db_session.execute(select(InventoryDeviceLink))).scalars().one()
+
+
+@pytest.mark.asyncio
+async def test_persist_never_deletes(db_session) -> None:
+    await _persist_pending_import(db_session, [_guest_node(101, "10.0.0.5")], [])
+    # A later sync that no longer includes vm101 must not remove it.
+    await _persist_pending_import(db_session, [_guest_node(202, "10.0.0.6")], [])
+    rows = (await db_session.execute(select(InventoryDevice))).scalars().all()
+    ieees = {r.ieee_address for r in rows}
+    assert "pve-pve1-101" in ieees and "pve-pve1-202" in ieees

backend/tests/test_proxmox_service.py

@@ -0,0 +1,220 @@
+"""Unit tests for the Proxmox VE import service (parsing, props, sanitizer)."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import pytest
+
+from app.services import proxmox_service as svc
+
+
+def test_gb_conversion() -> None:
+    assert svc._gb(1024 ** 3) == 1.0
+    assert svc._gb(2 * 1024 ** 3) == 2.0
+    assert svc._gb(0) is None
+    assert svc._gb(None) is None
+    assert svc._gb("nope") is None
+
+
+def test_extract_qemu_ip_skips_loopback() -> None:
+    payload = {
+        "result": [
+            {"name": "lo", "ip-addresses": [{"ip-address-type": "ipv4", "ip-address": "127.0.0.1"}]},
+            {"name": "eth0", "ip-addresses": [{"ip-address-type": "ipv4", "ip-address": "192.168.1.20"}]},
+        ]
+    }
+    assert svc._extract_qemu_ip(payload) == "192.168.1.20"
+    assert svc._extract_qemu_ip(None) is None
+    assert svc._extract_qemu_ip({"result": []}) is None
+
+
+def test_extract_lxc_ip_parses_net0_static() -> None:
+    cfg = {"net0": "name=eth0,bridge=vmbr0,ip=192.168.1.30/24,gw=192.168.1.1"}
+    assert svc._extract_lxc_ip(cfg) == "192.168.1.30"
+    # DHCP → no static IP
+    assert svc._extract_lxc_ip({"net0": "name=eth0,bridge=vmbr0,ip=dhcp"}) is None
+    assert svc._extract_lxc_ip(None) is None
+
+
+def test_extract_net_mac_parses_qemu_and_lxc_forms() -> None:
+    # qemu: "virtio=<MAC>,bridge=.."
+    assert svc._extract_net_mac({"net0": "virtio=BC:24:11:AA:BB:CC,bridge=vmbr0"}) == "bc:24:11:aa:bb:cc"
+    # lxc: "..,hwaddr=<MAC>,.."
+    assert (
+        svc._extract_net_mac({"net0": "name=eth0,bridge=vmbr0,hwaddr=BC:24:11:11:22:33,ip=dhcp"})
+        == "bc:24:11:11:22:33"
+    )
+    # No MAC / missing net0 / None → None
+    assert svc._extract_net_mac({"net0": "name=eth0,ip=dhcp"}) is None
+    assert svc._extract_net_mac({}) is None
+    assert svc._extract_net_mac(None) is None
+
+
+@pytest.mark.asyncio
+async def test_fetch_inventory_captures_guest_mac_from_config() -> None:
+    """Guests carry a normalized NIC MAC read agent-free from their config."""
+    async def fake_get_json(client, path: str):
+        if path == "/nodes":
+            return [{"node": "pve1", "status": "online", "maxcpu": 8}]
+        if path == "/nodes/pve1/qemu":
+            return [{"vmid": 101, "name": "web", "status": "stopped"}]  # stopped: no agent IP
+        if path == "/nodes/pve1/lxc":
+            return [{"vmid": 200, "name": "db", "status": "running"}]
+        if path == "/nodes/pve1/qemu/101/config":
+            return {"net0": "virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0"}
+        if path == "/nodes/pve1/lxc/200/config":
+            return {"net0": "name=eth0,bridge=vmbr0,hwaddr=11:22:33:44:55:66,ip=10.0.0.6/24"}
+        return None
+
+    with patch.object(svc, "_get_json", new=AsyncMock(side_effect=fake_get_json)):
+        nodes, _ = await svc.fetch_proxmox_inventory("h", 8006, "u@pam!t", "sec")
+
+    vm = next(n for n in nodes if n["type"] == "vm")
+    assert vm["mac"] == "aa:bb:cc:dd:ee:ff"  # captured even though VM is stopped (no IP)
+    assert vm["ip"] is None
+    ct = next(n for n in nodes if n["type"] == "lxc")
+    assert ct["mac"] == "11:22:33:44:55:66"
+    assert ct["ip"] == "10.0.0.6"
+
+
+def test_host_and_guest_node_mapping() -> None:
+    host = svc._host_node({"node": "pve1", "status": "online", "maxcpu": 8, "maxmem": 16 * 1024 ** 3, "maxdisk": 500 * 1024 ** 3})
+    assert host["type"] == "proxmox"
+    assert host["ieee_address"] == "pve-node-pve1"
+    assert host["cpu_count"] == 8
+    assert host["ram_gb"] == 16.0
+    assert host["status"] == "online"
+    assert host["parent_ieee"] is None
+
+    vm = svc._guest_node({"vmid": 101, "name": "web", "status": "running", "maxcpu": 2, "maxmem": 2 * 1024 ** 3, "maxdisk": 32 * 1024 ** 3}, "pve1", "qemu", "10.0.0.5")
+    assert vm["type"] == "vm"
+    assert vm["ieee_address"] == "pve-pve1-101"
+    assert vm["ip"] == "10.0.0.5"
+    assert vm["status"] == "online"
+    assert vm["parent_ieee"] == "pve-node-pve1"
+
+    ct = svc._guest_node({"vmid": 200, "name": "db", "status": "stopped"}, "pve1", "lxc", None)
+    assert ct["type"] == "lxc"
+    assert ct["status"] == "offline"
+
+
+def test_build_properties_includes_specs() -> None:
+    node = {"vmid": 101, "model": "QEMU", "cpu_count": 4, "ram_gb": 8.0, "disk_gb": 40.0}
+    props = svc.build_proxmox_properties(node)
+    keys = {p["key"] for p in props}
+    assert {"VMID", "CPU Cores", "RAM", "Disk", "Source"} <= keys
+    assert all(p["visible"] is False for p in props)
+
+
+def test_parse_inventory_builds_host_guest_edges() -> None:
+    hosts = [{"node": "pve1", "status": "online", "maxcpu": 4}]
+    guests = {"pve1": [svc._guest_node({"vmid": 101, "name": "web", "status": "running"}, "pve1", "qemu", None)]}
+    nodes, edges = svc._parse_inventory(hosts, guests)
+    assert len(nodes) == 2
+    assert edges == [{"source": "pve-node-pve1", "target": "pve-pve1-101"}]
+
+
+def test_build_cluster_links_chains_hosts() -> None:
+    nodes = [
+        svc._host_node({"node": "pve-a", "status": "online"}),
+        svc._guest_node({"vmid": 101, "status": "running"}, "pve-a", "qemu", None),
+        svc._host_node({"node": "pve-b", "status": "online"}),
+        svc._host_node({"node": "pve-c", "status": "online"}),
+    ]
+    pairs = svc.build_proxmox_cluster_links(nodes)
+    assert pairs == [("pve-node-pve-a", "pve-node-pve-b"), ("pve-node-pve-b", "pve-node-pve-c")]
+
+
+def test_build_cluster_links_single_host_is_not_a_cluster() -> None:
+    nodes = [svc._host_node({"node": "pve-a", "status": "online"})]
+    assert svc.build_proxmox_cluster_links(nodes) == []
+    # Guests alone never form a cluster.
+    guest = svc._guest_node({"vmid": 1, "status": "running"}, "pve-a", "qemu", None)
+    assert svc.build_proxmox_cluster_links([guest]) == []
+
+
+def test_sanitize_error_hides_credentials() -> None:
+    exc = httpx.HTTPStatusError(
+        "boom", request=httpx.Request("GET", "https://h/api2/json"),
+        response=httpx.Response(401),
+    )
+    msg = svc._sanitize_proxmox_error(exc)
+    assert "token" not in msg.lower() or "check the api token" in msg.lower()
+    assert "Authentication failed" in msg
+
+
+@pytest.mark.asyncio
+async def test_fetch_inventory_happy_path() -> None:
+    async def fake_get_json(client, path: str):
+        if path == "/nodes":
+            return [{"node": "pve1", "status": "online", "maxcpu": 8, "maxmem": 16 * 1024 ** 3}]
+        if path == "/nodes/pve1/qemu":
+            return [{"vmid": 101, "name": "web", "status": "running", "maxmem": 2 * 1024 ** 3}]
+        if path == "/nodes/pve1/lxc":
+            return [{"vmid": 200, "name": "db", "status": "stopped"}]
+        if path.endswith("/agent/network-get-interfaces"):
+            return {"result": [{"name": "eth0", "ip-addresses": [{"ip-address-type": "ipv4", "ip-address": "10.0.0.5"}]}]}
+        if path.endswith("/config"):
+            return {"net0": "name=eth0,ip=10.0.0.6/24"}
+        return None
+
+    with patch.object(svc, "_get_json", new=AsyncMock(side_effect=fake_get_json)):
+        nodes, edges = await svc.fetch_proxmox_inventory("h", 8006, "u@pam!t", "sec")
+
+    by_type = {n["type"] for n in nodes}
+    assert by_type == {"proxmox", "vm", "lxc"}
+    vm = next(n for n in nodes if n["type"] == "vm")
+    assert vm["ip"] == "10.0.0.5"
+    ct = next(n for n in nodes if n["type"] == "lxc")
+    assert ct["ip"] == "10.0.0.6"
+    assert len(edges) == 2
+
+
+@pytest.mark.asyncio
+async def test_test_connection_returns_message() -> None:
+    async def fake_get_json(client, path: str):
+        if path == "/access/permissions":
+            return {"/": {"VM.Audit": 1}}  # token has an ACL
+        return {"version": "8.2.2"}
+
+    with patch.object(svc, "_get_json", new=AsyncMock(side_effect=fake_get_json)):
+        ok, msg = await svc.test_proxmox_connection("h", 8006, "u@pam!t", "sec")
+    assert ok is True
+    assert "8.2.2" in msg
+    assert "warning" not in msg.lower()
+
+
+@pytest.mark.asyncio
+async def test_test_connection_warns_when_token_has_no_permissions() -> None:
+    async def fake_get_json(client, path: str):
+        if path == "/access/permissions":
+            return {}  # privilege-separated token with no effective ACL
+        return {"version": "8.4.19"}
+
+    with patch.object(svc, "_get_json", new=AsyncMock(side_effect=fake_get_json)):
+        ok, msg = await svc.test_proxmox_connection("h", 8006, "u@pam!t", "sec")
+    # Auth still succeeds; the message flags the permission gap.
+    assert ok is True
+    assert "8.4.19" in msg
+    assert "PVEAuditor" in msg
+
+
+@pytest.mark.asyncio
+async def test_token_has_permissions_treats_empty_as_no_perms() -> None:
+    async def fake_get_json(client, path: str):
+        return {}
+
+    with patch.object(svc, "_get_json", new=AsyncMock(side_effect=fake_get_json)):
+        assert await svc._token_has_permissions(object()) is False
+
+
+@pytest.mark.asyncio
+async def test_token_has_permissions_assumes_ok_on_error() -> None:
+    async def boom(client, path: str):
+        raise httpx.ConnectError("nope")
+
+    with patch.object(svc, "_get_json", new=AsyncMock(side_effect=boom)):
+        # Never block a valid import on a permissions-probe failure.
+        assert await svc._token_has_permissions(object()) is True

backend/tests/test_rackable_sync.py

@@ -0,0 +1,34 @@
+"""The rackable exclusion list is duplicated in the frontend — keep them equal.
+
+`GET /api/v1/racks/inventory` filters on `_UNRACKABLE_TYPES`, while the Device
+Inventory modal's "Rackable" filter (used as the rack picker's default) filters
+on `UNRACKABLE_TYPES` in `frontend/src/utils/rackable.ts`. If the two drift, the
+picker offers devices the rack side then refuses.
+"""
+import re
+from pathlib import Path
+
+from app.api.routes.racks import _UNRACKABLE_TYPES
+
+FRONTEND_FILE = (
+    Path(__file__).resolve().parents[2] / "frontend" / "src" / "utils" / "rackable.ts"
+)
+
+
+def _frontend_unrackable() -> set[str]:
+    src = FRONTEND_FILE.read_text()
+    match = re.search(r"export const UNRACKABLE_TYPES = new Set\(\[(.*?)\]\)", src, re.S)
+    assert match, (
+        "Could not locate UNRACKABLE_TYPES in frontend/src/utils/rackable.ts — "
+        "update this parser if the file's shape changed."
+    )
+    return set(re.findall(r"'([^']+)'", match.group(1)))
+
+
+def test_unrackable_types_in_sync_with_frontend():
+    frontend = _frontend_unrackable()
+    assert frontend == _UNRACKABLE_TYPES, (
+        "racks.py _UNRACKABLE_TYPES is out of sync with frontend rackable.ts.\n"
+        f"Missing from the backend: {sorted(frontend - _UNRACKABLE_TYPES)}\n"
+        f"Missing from the frontend: {sorted(_UNRACKABLE_TYPES - frontend)}"
+    )

backend/tests/test_racks.py

@@ -0,0 +1,798 @@
+import pytest
+from httpx import AsyncClient
+from sqlalchemy import text
+
+from app.db.models import InventoryDevice
+
+pytestmark = pytest.mark.asyncio
+
+
+async def _design(client: AsyncClient, headers: dict, *, name="Rack Room", design_type="rack") -> str:
+    res = await client.post(
+        "/api/v1/designs",
+        json={"name": name, "icon": "server", "design_type": design_type},
+        headers=headers,
+    )
+    assert res.status_code == 201, res.text
+    return res.json()["id"]
+
+
+def _state(design_id: str, **overrides) -> dict:
+    """A minimal but complete rack payload: one rack, two devices, one patch."""
+    payload = {
+        "design_id": design_id,
+        "racks": [
+            {
+                "id": "rack-1",
+                "name": "Main",
+                "u_height": 12,
+                "width_standard": "19",
+                "numbering": "bottom-up",
+                "location": "garage",
+                "style": {"frame": "#1c2129", "showNumbers": True},
+                "pos_x": 40,
+                "pos_y": 60,
+            }
+        ],
+        "devices": [
+            {
+                "id": "dev-sw",
+                "rack_id": "rack-1",
+                "label": "sw-24",
+                "u_start": 10,
+                "u_height": 1,
+                "col_start": 0,
+                "col_span": 12,
+                "faceplate_id": "switch-24",
+                "status": "online",
+                "ports": [{"id": "p1", "label": "1", "type": "rj45", "x": 0.4, "y": 0.5}],
+            },
+            {
+                "id": "dev-nas",
+                "rack_id": "rack-1",
+                "label": "nas",
+                "u_start": 4,
+                "u_height": 2,
+                "col_start": 0,
+                "col_span": 12,
+                "faceplate_id": "nas-2u",
+                "status": "unknown",
+                "ports": [{"id": "p2", "label": "eth0", "type": "rj45", "x": 0.7, "y": 0.5}],
+            },
+        ],
+        "cables": [
+            {
+                "id": "cbl-1",
+                "from_device_id": "dev-sw",
+                "from_port_id": "p1",
+                "to_device_id": "dev-nas",
+                "to_port_id": "p2",
+                "type": "ethernet",
+                "color": "#39d353",
+            }
+        ],
+        "viewport": {"x": 10, "y": 20, "zoom": 1.5},
+    }
+    payload.update(overrides)
+    return payload
+
+
+class TestDesignType:
+    async def test_creates_a_rack_design(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        res = await client.get("/api/v1/designs", headers=headers)
+        design = next(d for d in res.json() if d["id"] == design_id)
+        assert design["design_type"] == "rack"
+
+    async def test_rejects_an_unknown_design_type(self, client: AsyncClient, headers):
+        res = await client.post(
+            "/api/v1/designs",
+            json={"name": "Nope", "design_type": "spaceship"},
+            headers=headers,
+        )
+        assert res.status_code == 422
+
+
+class TestSaveAndLoad:
+    async def test_round_trips_the_full_state(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        res = await client.post("/api/v1/racks/save", json=_state(design_id), headers=headers)
+        assert res.status_code == 200, res.text
+
+        loaded = (await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)).json()
+        assert [r["name"] for r in loaded["racks"]] == ["Main"]
+        assert loaded["racks"][0]["u_height"] == 12
+        assert loaded["racks"][0]["style"]["showNumbers"] is True
+        assert {d["id"] for d in loaded["devices"]} == {"dev-sw", "dev-nas"}
+        assert loaded["devices"][0]["ports"][0]["type"] == "rj45"
+        assert loaded["cables"][0]["from_port_id"] == "p1"
+        assert loaded["viewport"] == {"x": 10, "y": 20, "zoom": 1.5}
+
+    async def test_keeps_a_mount_that_follows_its_node_check(
+        self, client: AsyncClient, headers
+    ):
+        # "Check device" is stored as `auto` on the mount: the rack has no
+        # checker, it reads the linked node's live status at render time. The
+        # status column is free-form, so this only guards it staying that way.
+        design_id = await _design(client, headers)
+        state = _state(design_id)
+        state["devices"][0]["status"] = "auto"
+        res = await client.post("/api/v1/racks/save", json=state, headers=headers)
+        assert res.status_code == 200, res.text
+
+        loaded = (await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)).json()
+        mount = next(d for d in loaded["devices"] if d["id"] == "dev-sw")
+        assert mount["status"] == "auto"
+
+    async def test_prunes_what_the_client_dropped(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        await client.post("/api/v1/racks/save", json=_state(design_id), headers=headers)
+
+        trimmed = _state(design_id)
+        trimmed["devices"] = [d for d in trimmed["devices"] if d["id"] == "dev-sw"]
+        trimmed["cables"] = []
+        await client.post("/api/v1/racks/save", json=trimmed, headers=headers)
+
+        loaded = (await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)).json()
+        assert {d["id"] for d in loaded["devices"]} == {"dev-sw"}
+        assert loaded["cables"] == []
+
+    async def test_updates_an_existing_device_in_place(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        await client.post("/api/v1/racks/save", json=_state(design_id), headers=headers)
+
+        moved = _state(design_id)
+        moved["devices"][1]["u_start"] = 1
+        moved["devices"][1]["label"] = "nas-renamed"
+        await client.post("/api/v1/racks/save", json=moved, headers=headers)
+
+        loaded = (await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)).json()
+        nas = next(d for d in loaded["devices"] if d["id"] == "dev-nas")
+        assert (nas["u_start"], nas["label"]) == (1, "nas-renamed")
+
+    async def test_keeps_designs_isolated(self, client: AsyncClient, headers):
+        first = await _design(client, headers, name="Rack A")
+        second = await _design(client, headers, name="Rack B")
+        await client.post("/api/v1/racks/save", json=_state(first), headers=headers)
+
+        loaded = (await client.get(f"/api/v1/racks?design_id={second}", headers=headers)).json()
+        assert loaded["racks"] == []
+        assert loaded["devices"] == []
+
+    async def test_refuses_to_steal_a_row_from_another_design(
+        self, client: AsyncClient, headers
+    ):
+        """Ids come from the client, so a stale tab or a copy can collide.
+
+        The upsert sets `design_id` from the payload: without a guard, saving
+        design B with an id owned by design A moved A's rack — devices and
+        cables with it — into B, and A silently lost it.
+        """
+        first = await _design(client, headers, name="Rack A")
+        second = await _design(client, headers, name="Rack B")
+        await client.post("/api/v1/racks/save", json=_state(first), headers=headers)
+
+        res = await client.post("/api/v1/racks/save", json=_state(second), headers=headers)
+        assert res.status_code == 409
+
+        kept = (await client.get(f"/api/v1/racks?design_id={first}", headers=headers)).json()
+        assert [r["id"] for r in kept["racks"]] == ["rack-1"]
+        assert len(kept["devices"]) == 2
+
+    async def test_rejects_an_unknown_design(self, client: AsyncClient, headers):
+        res = await client.post("/api/v1/racks/save", json=_state("nope"), headers=headers)
+        assert res.status_code == 404
+
+    async def test_rejects_a_device_pointing_outside_the_payload(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        broken = _state(design_id)
+        broken["devices"][0]["rack_id"] = "rack-ghost"
+        res = await client.post("/api/v1/racks/save", json=broken, headers=headers)
+        assert res.status_code == 400
+
+    async def test_rejects_a_cable_pointing_outside_the_payload(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        broken = _state(design_id)
+        broken["cables"][0]["to_device_id"] = "dev-ghost"
+        res = await client.post("/api/v1/racks/save", json=broken, headers=headers)
+        assert res.status_code == 400
+
+    @pytest.mark.parametrize(
+        "patch",
+        [
+            {"u_height": 0},
+            {"width_standard": "23"},
+            {"numbering": "sideways"},
+        ],
+    )
+    async def test_rejects_invalid_rack_geometry(self, client: AsyncClient, headers, patch):
+        design_id = await _design(client, headers)
+        payload = _state(design_id)
+        payload["racks"][0].update(patch)
+        res = await client.post("/api/v1/racks/save", json=payload, headers=headers)
+        assert res.status_code == 422
+
+    @pytest.mark.parametrize(
+        "patch",
+        [
+            {"u_start": 0},
+            {"col_start": 12},
+            {"col_span": 13},
+        ],
+    )
+    async def test_rejects_invalid_device_geometry(self, client: AsyncClient, headers, patch):
+        design_id = await _design(client, headers)
+        payload = _state(design_id)
+        payload["devices"][0].update(patch)
+        res = await client.post("/api/v1/racks/save", json=payload, headers=headers)
+        assert res.status_code == 422
+
+    async def test_rejects_a_device_taller_than_its_rack(self, client: AsyncClient, headers):
+        # Each field is legal on its own; only the rack says otherwise. A mount
+        # above the top rail draws outside the chassis with no way to drag it back.
+        design_id = await _design(client, headers)
+        payload = _state(design_id)
+        payload["devices"][0]["u_start"] = 40  # rack is 12U
+        res = await client.post("/api/v1/racks/save", json=payload, headers=headers)
+        assert res.status_code == 422
+
+    async def test_rejects_a_device_whose_height_overruns_the_rack(
+        self, client: AsyncClient, headers
+    ):
+        design_id = await _design(client, headers)
+        payload = _state(design_id)
+        payload["devices"][0].update({"u_start": 11, "u_height": 4})  # 11..14 of 12U
+        res = await client.post("/api/v1/racks/save", json=payload, headers=headers)
+        assert res.status_code == 422
+
+    async def test_accepts_a_device_that_ends_on_the_top_rail(
+        self, client: AsyncClient, headers
+    ):
+        design_id = await _design(client, headers)
+        payload = _state(design_id)
+        payload["devices"][0].update({"u_start": 11, "u_height": 2})  # 11..12 of 12U
+        res = await client.post("/api/v1/racks/save", json=payload, headers=headers)
+        assert res.status_code == 200, res.text
+
+    async def test_rejects_a_span_that_overruns_the_column_grid(
+        self, client: AsyncClient, headers
+    ):
+        design_id = await _design(client, headers)
+        payload = _state(design_id)
+        payload["devices"][0].update({"col_start": 11, "col_span": 12})
+        res = await client.post("/api/v1/racks/save", json=payload, headers=headers)
+        assert res.status_code == 422
+
+    async def test_accepts_a_half_width_pair_sharing_one_u(
+        self, client: AsyncClient, headers
+    ):
+        design_id = await _design(client, headers)
+        payload = _state(design_id)
+        payload["devices"][0].update({"col_start": 0, "col_span": 6})
+        payload["devices"][1].update({"col_start": 6, "col_span": 6})
+        res = await client.post("/api/v1/racks/save", json=payload, headers=headers)
+        assert res.status_code == 200, res.text
+
+    async def test_rejects_an_unknown_cable_type(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        payload = _state(design_id)
+        payload["cables"][0]["type"] = "power"
+        res = await client.post("/api/v1/racks/save", json=payload, headers=headers)
+        assert res.status_code == 422
+
+    async def test_round_trips_cable_annotations(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        payload = _state(design_id)
+        payload["cables"][0].update(
+            {
+                "label": "Uplink to core",
+                "label_visible": True,
+                "properties": [
+                    {"key": "Length", "value": "2 m", "icon": None, "visible": True},
+                    {"key": "VLAN", "value": "20", "icon": None, "visible": False},
+                ],
+            }
+        )
+        assert (
+            await client.post("/api/v1/racks/save", json=payload, headers=headers)
+        ).status_code == 200
+
+        cable = (
+            await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)
+        ).json()["cables"][0]
+        assert cable["label"] == "Uplink to core"
+        assert cable["label_visible"] is True
+        assert [p["key"] for p in cable["properties"]] == ["Length", "VLAN"]
+        assert cable["properties"][1]["visible"] is False
+
+    async def test_defaults_cable_annotations_when_absent(
+        self, client: AsyncClient, headers
+    ):
+        # A client that predates the feature sends neither key; the response must
+        # still carry usable values rather than nulls.
+        design_id = await _design(client, headers)
+        assert (
+            await client.post("/api/v1/racks/save", json=_state(design_id), headers=headers)
+        ).status_code == 200
+
+        cable = (
+            await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)
+        ).json()["cables"][0]
+        assert cable["label_visible"] is False
+        assert cable["properties"] == []
+
+    async def test_drops_cable_properties_with_no_key(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        payload = _state(design_id)
+        payload["cables"][0]["properties"] = [
+            {"key": "  ", "value": "orphan", "icon": None, "visible": True},
+            {"key": "Length", "value": "2 m", "icon": None, "visible": True},
+        ]
+        assert (
+            await client.post("/api/v1/racks/save", json=payload, headers=headers)
+        ).status_code == 200
+
+        cable = (
+            await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)
+        ).json()["cables"][0]
+        assert [p["key"] for p in cable["properties"]] == ["Length"]
+
+    async def test_updates_cable_annotations_on_a_second_save(
+        self, client: AsyncClient, headers
+    ):
+        design_id = await _design(client, headers)
+        payload = _state(design_id)
+        payload["cables"][0]["properties"] = [
+            {"key": "Length", "value": "2 m", "icon": None, "visible": True}
+        ]
+        await client.post("/api/v1/racks/save", json=payload, headers=headers)
+
+        payload["cables"][0]["properties"] = []
+        payload["cables"][0]["label_visible"] = True
+        await client.post("/api/v1/racks/save", json=payload, headers=headers)
+
+        cable = (
+            await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)
+        ).json()["cables"][0]
+        assert cable["properties"] == []
+        assert cable["label_visible"] is True
+
+    async def test_requires_auth(self, client: AsyncClient):
+        assert (await client.get("/api/v1/racks?design_id=any")).status_code == 401
+
+
+class TestInventory:
+    async def test_lists_rackable_devices_only(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        await client.post(
+            "/api/v1/scan/pending",
+            json={"hostname": "pve-01", "suggested_type": "proxmox"},
+            headers=headers,
+        )
+        await client.post(
+            "/api/v1/scan/pending",
+            json={"hostname": "phone", "suggested_type": "mobile"},
+            headers=headers,
+        )
+
+        res = await client.get(f"/api/v1/racks/inventory?design_id={design_id}", headers=headers)
+        labels = [i["label"] for i in res.json()["items"]]
+        assert "pve-01" in labels
+        assert "phone" not in labels
+
+    async def test_names_a_device_the_way_the_inventory_does(
+        self, client: AsyncClient, headers, db_session
+    ):
+        """A scan find with no hostname is named after the app it runs, not its IP.
+
+        The rack picker used to show "192.168.1.63 · 192.168.1.63" where the
+        Device Inventory showed "jellyfin".
+        """
+        design_id = await _design(client, headers)
+        db_session.add(
+            InventoryDevice(
+                id="pd-services",
+                ip="192.168.1.63",
+                services=[
+                    {"port": 443, "category": "web", "service_name": "https"},
+                    {"port": 8096, "category": "media", "service_name": "jellyfin"},
+                ],
+                suggested_type="server",
+            )
+        )
+        db_session.add(InventoryDevice(id="pd-bare", ip="192.168.1.64", suggested_type="server"))
+        # A portless service is no fingerprint: the inventory skips it, so must
+        # this — `None not in _COMMON_PORTS` is True and used to let it through.
+        db_session.add(
+            InventoryDevice(
+                id="pd-portless",
+                ip="192.168.1.65",
+                services=[{"port": None, "category": "media", "service_name": "jellyfin"}],
+                suggested_type="server",
+            )
+        )
+        await db_session.commit()
+
+        items = (
+            await client.get(f"/api/v1/racks/inventory?design_id={design_id}", headers=headers)
+        ).json()["items"]
+        assert next(i for i in items if i["id"] == "pd-services")["label"] == "jellyfin"
+        # Nothing better to say: the IP stays the label, and the UI stops doubling it.
+        assert next(i for i in items if i["id"] == "pd-bare")["label"] == "192.168.1.64"
+        assert next(i for i in items if i["id"] == "pd-portless")["label"] == "192.168.1.65"
+
+    async def test_flags_devices_already_mounted(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        created = (
+            await client.post(
+                "/api/v1/scan/pending",
+                json={"hostname": "sw-24", "suggested_type": "switch"},
+                headers=headers,
+            )
+        ).json()
+
+        payload = _state(design_id)
+        payload["devices"][0]["device_id"] = created["id"]
+        await client.post("/api/v1/racks/save", json=payload, headers=headers)
+
+        items = (
+            await client.get(f"/api/v1/racks/inventory?design_id={design_id}", headers=headers)
+        ).json()["items"]
+        assert next(i for i in items if i["id"] == created["id"])["racked"] is True
+
+    async def test_resolves_the_canvas_node_for_live_status(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        node = (
+            await client.post(
+                "/api/v1/nodes",
+                json={"type": "server", "label": "nas", "ip": "192.168.1.9", "status": "online"},
+                headers=headers,
+            )
+        ).json()
+        await client.post(
+            "/api/v1/scan/pending",
+            json={"hostname": "nas", "ip": "192.168.1.9", "suggested_type": "nas"},
+            headers=headers,
+        )
+
+        items = (
+            await client.get(f"/api/v1/racks/inventory?design_id={design_id}", headers=headers)
+        ).json()["items"]
+        entry = next(i for i in items if i["label"] == "nas")
+        assert entry["node_id"] == node["id"]
+        assert entry["node_status"] == "online"
+
+    async def test_reports_what_the_canvas_node_knows(
+        self, client: AsyncClient, headers, db_session
+    ):
+        """The rack prints the logical view's facts, so the endpoint must ship them."""
+        rack_design = await _design(client, headers)
+        network = await _design(client, headers, name="Network", design_type="network")
+        await client.post(
+            "/api/v1/nodes",
+            json={
+                "type": "nas",
+                "label": "nas-truenas",
+                "design_id": network,
+                "ip": "192.168.1.9",
+                "mac": "aa:bb:cc:dd:ee:ff",
+                "hostname": "nas.lan",
+                "os": "TrueNAS SCALE",
+                "status": "online",
+                "check_method": "http",
+            },
+            headers=headers,
+        )
+        # Straight to the table: the manual-create schema carries no os/services,
+        # and a scan find does.
+        db_session.add(
+            InventoryDevice(
+                id="pd-nas",
+                hostname="nas",
+                ip="192.168.1.9",
+                mac="aa:bb:cc:dd:ee:ff",
+                os="TrueNAS",
+                suggested_type="nas",
+                services=[{"port": 445, "service_name": "smb", "category": "storage"}],
+            )
+        )
+        await db_session.commit()
+
+        items = (
+            await client.get(f"/api/v1/racks/inventory?design_id={rack_design}", headers=headers)
+        ).json()["items"]
+        entry = next(i for i in items if i["ip"] == "192.168.1.9")
+        assert entry["mac"] == "aa:bb:cc:dd:ee:ff"
+        assert entry["os"] == "TrueNAS"
+        assert entry["services"] == [{"port": 445, "name": "smb"}]
+        assert entry["node_label"] == "nas-truenas"
+        assert entry["node_type"] == "nas"
+        assert entry["node_hostname"] == "nas.lan"
+        assert entry["node_os"] == "TrueNAS SCALE"
+        assert entry["node_check_method"] == "http"
+        assert entry["node_design_id"] == network
+        assert entry["node_design_name"] == "Network"
+
+    async def test_stamps_last_seen_with_an_offset(self, client: AsyncClient, headers, db_session):
+        """SQLite reads `last_seen` back naive, and a naive ISO string is *local*
+        time to `new Date()` — the panel printed it shifted by the viewer's offset.
+        """
+        design_id = await _design(client, headers)
+        node = (
+            await client.post(
+                "/api/v1/nodes",
+                json={"type": "server", "label": "seen", "ip": "192.168.1.77"},
+                headers=headers,
+            )
+        ).json()
+        db_session.add(InventoryDevice(id="pd-seen", ip="192.168.1.77", suggested_type="server"))
+        await db_session.execute(
+            text("UPDATE nodes SET last_seen = :ts WHERE id = :id"),
+            {"ts": "2026-08-08 10:00:00.000000", "id": node["id"]},
+        )
+        await db_session.commit()
+
+        items = (
+            await client.get(f"/api/v1/racks/inventory?design_id={design_id}", headers=headers)
+        ).json()["items"]
+        entry = next(i for i in items if i["id"] == "pd-seen")
+        assert entry["node_last_seen"].endswith(("Z", "+00:00"))
+
+    async def test_prefers_the_node_the_mount_names(self, client: AsyncClient, headers):
+        """A link the user picked in the rack beats the IEEE/IP guess.
+
+        The guess is what failed on gear with no MAC and no address, and it is
+        wrong — not merely absent — when two hosts have swapped IPs.
+        """
+        design_id = await _design(client, headers)
+        picked = (
+            await client.post(
+                "/api/v1/nodes",
+                json={"type": "pdu", "label": "pdu-main", "status": "online"},
+                headers=headers,
+            )
+        ).json()
+        guessed = (
+            await client.post(
+                "/api/v1/nodes",
+                json={"type": "server", "label": "someone-else", "ip": "192.168.1.90"},
+                headers=headers,
+            )
+        ).json()
+        device = (
+            await client.post(
+                "/api/v1/scan/pending",
+                json={"hostname": "pdu", "ip": "192.168.1.90", "suggested_type": "generic"},
+                headers=headers,
+            )
+        ).json()
+
+        payload = _state(design_id)
+        payload["devices"][0]["device_id"] = device["id"]
+        payload["devices"][0]["node_id"] = picked["id"]
+        await client.post("/api/v1/racks/save", json=payload, headers=headers)
+
+        items = (
+            await client.get(f"/api/v1/racks/inventory?design_id={design_id}", headers=headers)
+        ).json()["items"]
+        entry = next(i for i in items if i["id"] == device["id"])
+        assert entry["node_id"] == picked["id"] != guessed["id"]
+        assert entry["node_label"] == "pdu-main"
+        assert entry["node_status"] == "online"
+
+    async def test_falls_back_when_the_named_node_is_gone(self, client: AsyncClient, headers):
+        """A mount keeps its `node_id` in the payload the client last sent, so a
+        node deleted meanwhile must not report a node that no longer exists.
+        """
+        design_id = await _design(client, headers)
+        guessed = (
+            await client.post(
+                "/api/v1/nodes",
+                json={"type": "server", "label": "nas", "ip": "192.168.1.91"},
+                headers=headers,
+            )
+        ).json()
+        device = (
+            await client.post(
+                "/api/v1/scan/pending",
+                json={"hostname": "nas", "ip": "192.168.1.91", "suggested_type": "nas"},
+                headers=headers,
+            )
+        ).json()
+
+        payload = _state(design_id)
+        payload["devices"][0]["device_id"] = device["id"]
+        payload["devices"][0]["node_id"] = "node-that-was-deleted"
+        await client.post("/api/v1/racks/save", json=payload, headers=headers)
+
+        items = (
+            await client.get(f"/api/v1/racks/inventory?design_id={design_id}", headers=headers)
+        ).json()["items"]
+        entry = next(i for i in items if i["id"] == device["id"])
+        assert entry["node_id"] == guessed["id"]
+
+    async def test_leaves_the_node_fields_empty_without_a_match(
+        self, client: AsyncClient, headers
+    ):
+        design_id = await _design(client, headers)
+        await client.post(
+            "/api/v1/scan/pending",
+            json={"hostname": "pdu-main", "suggested_type": "generic"},
+            headers=headers,
+        )
+
+        items = (
+            await client.get(f"/api/v1/racks/inventory?design_id={design_id}", headers=headers)
+        ).json()["items"]
+        entry = next(i for i in items if i["label"] == "pdu-main")
+        assert entry["node_id"] is None
+        assert entry["node_label"] is None
+        assert entry["node_design_name"] is None
+        assert entry["services"] == []
+
+    async def test_falls_back_to_the_node_services(self, client: AsyncClient, headers, db_session):
+        """An approved device keeps its fingerprint on the node, not the inventory row."""
+        design_id = await _design(client, headers)
+        await client.post(
+            "/api/v1/nodes",
+            json={
+                "type": "server",
+                "label": "media",
+                "ip": "192.168.1.63",
+                "services": [{"port": 8096, "service_name": "jellyfin", "category": "media"}],
+            },
+            headers=headers,
+        )
+        db_session.add(
+            InventoryDevice(id="pd-noservices", ip="192.168.1.63", suggested_type="server")
+        )
+        await db_session.commit()
+
+        items = (
+            await client.get(f"/api/v1/racks/inventory?design_id={design_id}", headers=headers)
+        ).json()["items"]
+        entry = next(i for i in items if i["id"] == "pd-noservices")
+        assert entry["services"] == [{"port": 8096, "name": "jellyfin"}]
+
+    async def test_manual_entry_is_tagged_as_such(self, client: AsyncClient, headers):
+        created = (
+            await client.post(
+                "/api/v1/scan/pending",
+                json={"hostname": "patch-panel", "suggested_type": "generic"},
+                headers=headers,
+            )
+        ).json()
+        assert created["discovery_source"] == "manual"
+        assert created["status"] == "pending"
+
+        listed = (await client.get("/api/v1/scan/pending", headers=headers)).json()
+        assert any(d["id"] == created["id"] for d in listed)
+
+
+class TestRackSourcedInventory:
+    """Gear created from a rack canvas shares the Device Inventory, but never a
+    logical canvas: it documents a mount, not a host."""
+
+    async def _rack_device(self, client: AsyncClient, headers, hostname: str = "patch-house"):
+        return (
+            await client.post(
+                "/api/v1/scan/pending",
+                json={"hostname": hostname, "discovery_source": "rack"},
+                headers=headers,
+            )
+        ).json()
+
+    async def test_records_the_rack_source(self, client: AsyncClient, headers):
+        created = await self._rack_device(client, headers)
+        assert created["discovery_source"] == "rack"
+        assert created["discovery_sources"] == ["rack"]
+
+    async def test_rejects_an_unknown_source(self, client: AsyncClient, headers):
+        res = await client.post(
+            "/api/v1/scan/pending",
+            json={"hostname": "spoof", "discovery_source": "zigbee"},
+            headers=headers,
+        )
+        assert res.status_code == 422
+
+    async def test_approve_refuses_rack_gear(self, client: AsyncClient, headers):
+        created = await self._rack_device(client, headers)
+        res = await client.post(
+            f"/api/v1/scan/pending/{created['id']}/approve",
+            json={"type": "generic", "label": "patch-house"},
+            headers=headers,
+        )
+        assert res.status_code == 409
+        assert "rack" in res.json()["detail"].lower()
+
+    async def test_bulk_approve_skips_rack_gear(self, client: AsyncClient, headers):
+        rack_device = await self._rack_device(client, headers)
+        scanned = (
+            await client.post(
+                "/api/v1/scan/pending",
+                json={"hostname": "nuc", "ip": "192.168.1.77", "suggested_type": "server"},
+                headers=headers,
+            )
+        ).json()
+
+        res = await client.post(
+            "/api/v1/scan/pending/bulk-approve",
+            json={"device_ids": [rack_device["id"], scanned["id"]]},
+            headers=headers,
+        )
+        body = res.json()
+        assert body["approved"] == 1
+        assert body["device_ids"] == [scanned["id"]]
+        skipped = next(s for s in body["skipped_devices"] if s["device_id"] == rack_device["id"])
+        assert skipped["match"] == "rack"
+
+    async def test_rack_gear_is_offered_to_the_rack_inventory(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        created = await self._rack_device(client, headers, hostname="blank-panel")
+        items = (
+            await client.get(f"/api/v1/racks/inventory?design_id={design_id}", headers=headers)
+        ).json()["items"]
+        assert any(i["id"] == created["id"] for i in items)
+
+
+class TestDesignLifecycle:
+    async def test_deleting_a_design_removes_its_rack_rows(self, client: AsyncClient, headers):
+        keeper = await _design(client, headers, name="Keeper", design_type="network")
+        design_id = await _design(client, headers)
+        await client.post("/api/v1/racks/save", json=_state(design_id), headers=headers)
+
+        assert (await client.delete(f"/api/v1/designs/{design_id}", headers=headers)).status_code == 204
+        assert (await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)).status_code == 404
+        # The other design is untouched.
+        assert (await client.get(f"/api/v1/racks?design_id={keeper}", headers=headers)).status_code == 200
+
+    async def test_unmounting_keeps_the_inventory_entry(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        created = (
+            await client.post(
+                "/api/v1/scan/pending",
+                json={"hostname": "sw-24", "suggested_type": "switch"},
+                headers=headers,
+            )
+        ).json()
+
+        payload = _state(design_id)
+        payload["devices"][0]["device_id"] = created["id"]
+        await client.post("/api/v1/racks/save", json=payload, headers=headers)
+
+        # Unmount: the device disappears from the rack payload entirely.
+        unmounted = _state(design_id)
+        unmounted["devices"] = [d for d in unmounted["devices"] if d["id"] != "dev-sw"]
+        unmounted["cables"] = []
+        await client.post("/api/v1/racks/save", json=unmounted, headers=headers)
+
+        items = (
+            await client.get(f"/api/v1/racks/inventory?design_id={design_id}", headers=headers)
+        ).json()["items"]
+        entry = next(i for i in items if i["id"] == created["id"])
+        assert entry["racked"] is False
+
+    async def test_copying_a_rack_design_duplicates_its_racks(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        await client.post("/api/v1/racks/save", json=_state(design_id), headers=headers)
+
+        copy = (
+            await client.post(
+                f"/api/v1/designs/{design_id}/copy",
+                json={"name": "Rack Room (copy)", "icon": "server"},
+                headers=headers,
+            )
+        ).json()
+        assert copy["design_type"] == "rack"
+
+        loaded = (await client.get(f"/api/v1/racks?design_id={copy['id']}", headers=headers)).json()
+        assert [r["name"] for r in loaded["racks"]] == ["Main"]
+        assert len(loaded["devices"]) == 2
+        assert len(loaded["cables"]) == 1
+        # Fresh ids, so editing the copy cannot touch the original.
+        assert loaded["racks"][0]["id"] != "rack-1"
+        assert {d["id"] for d in loaded["devices"]}.isdisjoint({"dev-sw", "dev-nas"})
+        # Cables still join the copied devices, not the originals.
+        copied_ids = {d["id"] for d in loaded["devices"]}
+        assert loaded["cables"][0]["from_device_id"] in copied_ids
+        assert loaded["cables"][0]["to_device_id"] in copied_ids

backend/tests/test_scanner.py

@@ -8,7 +8,7 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_asyn
 from sqlalchemy.pool import StaticPool
 
 from app.db.database import Base
-from app.db.models import Node, PendingDevice, ScanRun
+from app.db.models import InventoryDevice, Node, ScanRun
 
 # ---------------------------------------------------------------------------
 # Helpers
@@ -253,6 +253,128 @@ def test_nmap_scan_single_returns_host_unchanged_when_no_results():
     assert result["mac"] == "34:94:54:aa:bb:cc"  # preserved from Phase 1
 
 
+# ---------------------------------------------------------------------------
+# _nmap_scan_single — two-pass discovery/version split (issue #277)
+# ---------------------------------------------------------------------------
+
+def _fake_scanner(ip, port_info, mac=None):
+    """Mock nmap.PortScanner whose results contain `ip` with tcp `port_info`."""
+    host = MagicMock()
+    host.all_protocols.return_value = ["tcp"]
+    host.__getitem__ = MagicMock(return_value=port_info)
+    host.get.return_value = {"mac": mac} if mac else {}
+    nm = MagicMock()
+    nm.all_hosts.return_value = [ip]
+    nm.__getitem__ = MagicMock(return_value=host)
+    return nm
+
+
+def _empty_scanner():
+    nm = MagicMock()
+    nm.all_hosts.return_value = []
+    return nm
+
+
+def _failing_scanner(exc=Exception("host timeout")):
+    nm = MagicMock()
+    nm.scan.side_effect = exc
+    return nm
+
+
+def test_nmap_scan_single_two_pass_merges_banners():
+    """Pass A discovers ports; Pass B enriches them with -sV banners."""
+    from app.services.scanner import _nmap_scan_single
+
+    host = {"ip": "192.168.1.10", "hostname": None, "mac": None, "os": None, "open_ports": []}
+    disc = _fake_scanner("192.168.1.10", {22: {"state": "open"}, 8006: {"state": "open"}})
+    ver = _fake_scanner("192.168.1.10", {
+        22: {"state": "open", "product": "OpenSSH", "version": "9.0"},
+        8006: {"state": "open", "product": "", "version": ""},
+    })
+
+    with patch("app.services.scanner.nmap.PortScanner", side_effect=[disc, ver]), \
+         patch("app.services.scanner.os.geteuid", return_value=0), \
+         patch("app.services.scanner._extract_os", return_value=None):
+        result = _nmap_scan_single(host)
+
+    banners = {p["port"]: p["banner"] for p in result["open_ports"]}
+    assert banners == {22: "OpenSSH 9.0", 8006: ""}
+
+    # Pass A: discovery only, no -sV / host-timeout. Pass B: -sV, bounded.
+    disc_args = disc.scan.call_args.kwargs["arguments"]
+    ver_args = ver.scan.call_args.kwargs["arguments"]
+    assert "-sV" not in disc_args and "--host-timeout" not in disc_args
+    assert "-sV" in ver_args and "--host-timeout 60s" in ver_args
+    assert ver_args.endswith("-p 22,8006")  # version pass scoped to found ports
+
+
+def test_nmap_scan_single_keeps_ports_when_version_pass_fails():
+    """Regression #277: a stalling version pass must not drop discovered ports."""
+    from app.services.scanner import _nmap_scan_single
+
+    host = {"ip": "192.168.100.3", "hostname": None, "mac": None, "os": None, "open_ports": []}
+    disc = _fake_scanner("192.168.100.3", {22: {"state": "open"}, 8006: {"state": "open"}})
+    ver = _failing_scanner()  # -sV blows past --host-timeout on the TLS port
+
+    with patch("app.services.scanner.nmap.PortScanner", side_effect=[disc, ver]), \
+         patch("app.services.scanner.os.geteuid", return_value=0):
+        result = _nmap_scan_single(host)
+
+    ports = {p["port"] for p in result["open_ports"]}
+    assert ports == {22, 8006}  # both survive despite the version failure
+    assert all(p["banner"] == "" for p in result["open_ports"])
+
+
+def test_nmap_scan_single_keeps_ports_when_version_pass_empty():
+    """Version pass returns no results for the host — keep the discovered ports."""
+    from app.services.scanner import _nmap_scan_single
+
+    host = {"ip": "192.168.1.11", "hostname": None, "mac": None, "os": None, "open_ports": []}
+    disc = _fake_scanner("192.168.1.11", {443: {"state": "open"}})
+    ver = _empty_scanner()
+
+    with patch("app.services.scanner.nmap.PortScanner", side_effect=[disc, ver]), \
+         patch("app.services.scanner.os.geteuid", return_value=0):
+        result = _nmap_scan_single(host)
+
+    assert [p["port"] for p in result["open_ports"]] == [443]
+    assert result["open_ports"][0]["banner"] == ""
+
+
+def test_nmap_scan_single_no_open_ports_skips_version_pass():
+    """Host reachable but nothing open — no version pass, empty ports."""
+    from app.services.scanner import _nmap_scan_single
+
+    host = {"ip": "192.168.1.12", "hostname": None, "mac": None, "os": None, "open_ports": []}
+    disc = _fake_scanner("192.168.1.12", {80: {"state": "filtered"}})
+
+    # Only one PortScanner instance may be created (Pass B must be skipped);
+    # a second would raise StopIteration from side_effect.
+    with patch("app.services.scanner.nmap.PortScanner", side_effect=[disc]), \
+         patch("app.services.scanner.os.geteuid", return_value=0):
+        result = _nmap_scan_single(host)
+
+    assert result["open_ports"] == []
+
+
+def test_nmap_scan_single_non_root_uses_connect_scan():
+    """Without root, both passes use -sT (connect) instead of -sS (SYN)."""
+    from app.services.scanner import _nmap_scan_single
+
+    host = {"ip": "192.168.1.13", "hostname": None, "mac": None, "os": None, "open_ports": []}
+    disc = _fake_scanner("192.168.1.13", {80: {"state": "open"}})
+    ver = _fake_scanner("192.168.1.13", {80: {"state": "open", "product": "nginx", "version": "1.24"}})
+
+    with patch("app.services.scanner.nmap.PortScanner", side_effect=[disc, ver]), \
+         patch("app.services.scanner.os.geteuid", return_value=1000), \
+         patch("app.services.scanner._extract_os", return_value=None):
+        result = _nmap_scan_single(host)
+
+    assert disc.scan.call_args.kwargs["arguments"].startswith("-sT")
+    assert ver.scan.call_args.kwargs["arguments"].startswith("-sT")
+    assert result["open_ports"][0]["banner"] == "nginx 1.24"
+
+
 # ---------------------------------------------------------------------------
 # _nmap_scan
 # ---------------------------------------------------------------------------
@@ -466,7 +588,7 @@ async def test_run_scan_adds_nmap_devices_as_pending(mem_db):
             await run_scan(["192.168.1.0/24"], session, run_id)
 
     async with mem_db() as session:
-        result = await session.execute(sa_select(PendingDevice))
+        result = await session.execute(sa_select(InventoryDevice))
         devices = result.scalars().all()
 
     assert any(d.ip == "192.168.1.5" for d in devices)
@@ -552,7 +674,7 @@ async def test_run_scan_leaves_last_scan_untouched_on_unmatched_node(mem_db):
 
 @pytest.mark.asyncio
 async def test_run_scan_mdns_only_device_added(mem_db):
-    """Devices found only by mDNS (not nmap) should appear in pending_devices."""
+    """Devices found only by mDNS (not nmap) should appear in device_inventory."""
     from app.services.scanner import run_scan
 
     run_id = _make_run_id()
@@ -569,7 +691,7 @@ async def test_run_scan_mdns_only_device_added(mem_db):
             await run_scan(["192.168.1.0/24"], session, run_id)
 
     async with mem_db() as session:
-        result = await session.execute(sa_select(PendingDevice).where(PendingDevice.ip == "192.168.1.80"))
+        result = await session.execute(sa_select(InventoryDevice).where(InventoryDevice.ip == "192.168.1.80"))
         device = result.scalar_one_or_none()
 
     assert device is not None
@@ -577,6 +699,44 @@ async def test_run_scan_mdns_only_device_added(mem_db):
     assert device.discovery_source == "mdns"
 
 
+@pytest.mark.asyncio
+async def test_run_scan_merges_proxmox_row_by_mac(mem_db):
+    """A scan reconciles a prior Proxmox-imported row by MAC: fills the IP,
+    unions the source, keeps the vm type, and does not duplicate."""
+    from app.services.scanner import run_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(_make_scan_run(run_id))
+        # Previously imported from Proxmox: no IP, known NIC MAC, vm type.
+        session.add(InventoryDevice(
+            id="pve-row", ieee_address="pve-pve1-101", ip=None,
+            mac="bc:24:11:aa:bb:cc", suggested_type="vm", status="pending",
+            discovery_source="proxmox", discovery_sources=["proxmox"],
+        ))
+        await session.commit()
+
+    # Scan sees the same box (same MAC, different casing) with a live IP.
+    nmap_hosts = [{"ip": "192.168.1.50", "hostname": "web.lan",
+                   "mac": "BC:24:11:AA:BB:CC", "os": None, "open_ports": []}]
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan", return_value=nmap_hosts), \
+             patch("app.services.scanner._mdns_discover", new_callable=AsyncMock, return_value=[]), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_scan(["192.168.1.0/24"], session, run_id)
+
+    async with mem_db() as session:
+        rows = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+    assert len(rows) == 1                                  # merged, not duplicated
+    row = rows[0]
+    assert row.ip == "192.168.1.50"                        # scan filled the IP
+    assert row.mac == "bc:24:11:aa:bb:cc"                  # normalized
+    assert row.suggested_type == "vm"                      # kept proxmox type
+    assert set(row.discovery_sources) == {"proxmox", "arp"}  # both filters
+
+
 @pytest.mark.asyncio
 async def test_run_scan_mdns_skipped_if_already_in_nmap(mem_db):
     """If nmap and mDNS both find the same IP, it should not be double-counted."""
@@ -596,7 +756,7 @@ async def test_run_scan_mdns_skipped_if_already_in_nmap(mem_db):
             await run_scan(["192.168.1.0/24"], session, run_id)
 
     async with mem_db() as session:
-        result = await session.execute(sa_select(PendingDevice).where(PendingDevice.ip == "192.168.1.10"))
+        result = await session.execute(sa_select(InventoryDevice).where(InventoryDevice.ip == "192.168.1.10"))
         devices = result.scalars().all()
 
     assert len(devices) == 1  # not duplicated
@@ -627,7 +787,7 @@ async def test_run_scan_keeps_canvas_nodes(mem_db):
             await run_scan(["192.168.1.0/24"], session, run_id)
 
     async with mem_db() as session:
-        result = await session.execute(sa_select(PendingDevice).where(PendingDevice.ip == "192.168.1.100"))
+        result = await session.execute(sa_select(InventoryDevice).where(InventoryDevice.ip == "192.168.1.100"))
         device = result.scalar_one_or_none()
         assert device is not None
         assert device.status == "pending"
@@ -641,7 +801,7 @@ async def test_run_scan_skips_hidden_devices(mem_db):
     run_id = _make_run_id()
     async with mem_db() as session:
         session.add(_make_scan_run(run_id))
-        hidden = PendingDevice(ip="192.168.1.55", status="hidden")
+        hidden = InventoryDevice(ip="192.168.1.55", status="hidden")
         session.add(hidden)
         await session.commit()
 
@@ -655,7 +815,7 @@ async def test_run_scan_skips_hidden_devices(mem_db):
 
     async with mem_db() as session:
         result = await session.execute(
-            sa_select(PendingDevice).where(PendingDevice.ip == "192.168.1.55", PendingDevice.status == "pending")
+            sa_select(InventoryDevice).where(InventoryDevice.ip == "192.168.1.55", InventoryDevice.status == "pending")
         )
         assert result.scalar_one_or_none() is None
 
@@ -783,7 +943,7 @@ async def test_run_scan_probe_enriches_services(mem_db):
             )
 
     async with mem_db() as session:
-        result = await session.execute(sa_select(PendingDevice).where(PendingDevice.ip == "192.168.1.50"))
+        result = await session.execute(sa_select(InventoryDevice).where(InventoryDevice.ip == "192.168.1.50"))
         device = result.scalar_one_or_none()
 
     assert device is not None

backend/tests/test_scheduler.py

@@ -6,9 +6,20 @@ import pytest
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 
 from app.core.scheduler import (
+    _run_proxmox_sync,
     _run_service_checks,
     _run_status_checks,
+    _run_zigbee_sync,
+    _run_zwave_sync,
+    reschedule_proxmox_sync,
+    reschedule_service_checks,
+    reschedule_status_checks,
+    reschedule_zigbee_sync,
+    reschedule_zwave_sync,
+    set_proxmox_sync_enabled,
     set_service_checks_enabled,
+    set_zigbee_sync_enabled,
+    set_zwave_sync_enabled,
     start_scheduler,
     stop_scheduler,
 )
@@ -148,6 +159,9 @@ def test_scheduler_uses_settings_interval():
          patch("app.core.scheduler.AsyncIOScheduler", return_value=mock_sched):
         mock_settings.status_checker_interval = 45
         mock_settings.service_check_enabled = False
+        mock_settings.proxmox_sync_enabled = False
+        mock_settings.zigbee_sync_enabled = False
+        mock_settings.zwave_sync_enabled = False
         start_scheduler()
         _, kwargs = mock_sched.add_job.call_args
         assert kwargs["seconds"] == 45
@@ -156,7 +170,13 @@ def test_scheduler_uses_settings_interval():
 def test_start_and_stop_scheduler():
     """Scheduler can be started and stopped without errors."""
     mock_sched = MagicMock()
-    with patch("app.core.scheduler.AsyncIOScheduler", return_value=mock_sched):
+    with patch("app.core.scheduler.AsyncIOScheduler", return_value=mock_sched), \
+         patch("app.core.scheduler.settings") as mock_settings:
+        mock_settings.status_checker_interval = 60
+        mock_settings.service_check_enabled = False
+        mock_settings.proxmox_sync_enabled = False
+        mock_settings.zigbee_sync_enabled = False
+        mock_settings.zwave_sync_enabled = False
         start_scheduler()
         stop_scheduler()
         mock_sched.add_job.assert_called_once()
@@ -245,7 +265,286 @@ def test_start_scheduler_adds_service_job_when_enabled():
         mock_settings.status_checker_interval = 60
         mock_settings.service_check_enabled = True
         mock_settings.service_check_interval = 300
+        mock_settings.proxmox_sync_enabled = False
+        mock_settings.zigbee_sync_enabled = False
+        mock_settings.zwave_sync_enabled = False
         start_scheduler()
     job_ids = [kw.get("id") for _, kw in mock_sched.add_job.call_args_list]
     assert "status_checks" in job_ids
     assert "service_checks" in job_ids
+
+
+# ---------------------------------------------------------------------------
+# Proxmox auto-sync job
+# ---------------------------------------------------------------------------
+
+def test_set_proxmox_sync_enabled_adds_and_removes_job():
+    mock_sched = MagicMock()
+    mock_sched.running = True
+    with patch("app.core.scheduler.scheduler", mock_sched), \
+         patch("app.core.scheduler.settings") as mock_settings:
+        mock_settings.proxmox_sync_interval = 3600
+        mock_sched.get_job.return_value = None
+        set_proxmox_sync_enabled(True)
+        mock_sched.add_job.assert_called_once()
+        mock_sched.get_job.return_value = MagicMock()
+        set_proxmox_sync_enabled(False)
+        mock_sched.remove_job.assert_called_once_with("proxmox_sync")
+
+
+def test_reschedule_proxmox_sync_rejects_short_interval():
+    with pytest.raises(ValueError):
+        reschedule_proxmox_sync(60)
+
+
+@pytest.mark.asyncio
+async def test_run_proxmox_sync_skips_when_disabled():
+    with patch("app.core.scheduler.settings") as mock_settings:
+        mock_settings.proxmox_sync_enabled = False
+        # Must return before importing/fetching anything.
+        await _run_proxmox_sync()
+
+
+@pytest.mark.asyncio
+async def test_run_proxmox_sync_skips_when_no_token():
+    with patch("app.core.scheduler.settings") as mock_settings:
+        mock_settings.proxmox_sync_enabled = True
+        mock_settings.proxmox_host = "pve"
+        mock_settings.proxmox_token_id = ""
+        mock_settings.proxmox_token_secret = ""
+        await _run_proxmox_sync()  # no exception, no fetch
+
+
+def _proxmox_settings(mock_settings):
+    mock_settings.proxmox_sync_enabled = True
+    mock_settings.proxmox_host = "pve"
+    mock_settings.proxmox_port = 8006
+    mock_settings.proxmox_token_id = "root@pam!tok"
+    mock_settings.proxmox_token_secret = "secret"
+    mock_settings.proxmox_verify_tls = False
+
+
+@pytest.mark.asyncio
+async def test_run_proxmox_sync_records_scan_run(mem_db):
+    """Auto-sync must create a ScanRun (kind=proxmox) so it shows in Scan
+    history, then delegate to the shared background import with the run id."""
+    from app.db.models import ScanRun
+
+    with (
+        patch("app.core.scheduler.settings") as mock_settings,
+        patch("app.core.scheduler.AsyncSessionLocal", mem_db),
+        patch(
+            "app.api.routes.proxmox._background_proxmox_import",
+            new_callable=AsyncMock,
+        ) as mock_bg,
+    ):
+        _proxmox_settings(mock_settings)
+        await _run_proxmox_sync()
+
+    # A ScanRun row exists — the missing scan-history trace.
+    async with mem_db() as db:
+        from sqlalchemy import select
+        run = (await db.execute(select(ScanRun))).scalars().one()
+    assert run.kind == "proxmox"
+    assert run.ranges == ["pve:8006"]
+
+    # Delegated to the same background flow the manual /sync-now uses, passing
+    # the run id + env connection settings.
+    mock_bg.assert_awaited_once_with(
+        run.id, "pve", 8006, "root@pam!tok", "secret", False,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Zigbee / Z-Wave auto-sync jobs (MQTT mesh imports)
+# ---------------------------------------------------------------------------
+
+def test_set_zigbee_sync_enabled_adds_and_removes_job():
+    mock_sched = MagicMock()
+    mock_sched.running = True
+    with patch("app.core.scheduler.scheduler", mock_sched), \
+         patch("app.core.scheduler.settings") as mock_settings:
+        mock_settings.zigbee_sync_interval = 3600
+        mock_sched.get_job.return_value = None
+        set_zigbee_sync_enabled(True)
+        mock_sched.add_job.assert_called_once()
+        mock_sched.get_job.return_value = MagicMock()
+        set_zigbee_sync_enabled(False)
+        mock_sched.remove_job.assert_called_once_with("zigbee_sync")
+
+
+def test_set_zwave_sync_enabled_adds_and_removes_job():
+    mock_sched = MagicMock()
+    mock_sched.running = True
+    with patch("app.core.scheduler.scheduler", mock_sched), \
+         patch("app.core.scheduler.settings") as mock_settings:
+        mock_settings.zwave_sync_interval = 3600
+        mock_sched.get_job.return_value = None
+        set_zwave_sync_enabled(True)
+        mock_sched.add_job.assert_called_once()
+        mock_sched.get_job.return_value = MagicMock()
+        set_zwave_sync_enabled(False)
+        mock_sched.remove_job.assert_called_once_with("zwave_sync")
+
+
+def test_reschedule_zigbee_sync_rejects_short_interval():
+    with pytest.raises(ValueError):
+        reschedule_zigbee_sync(60)
+
+
+def test_reschedule_zwave_sync_rejects_short_interval():
+    with pytest.raises(ValueError):
+        reschedule_zwave_sync(60)
+
+
+@pytest.mark.asyncio
+async def test_run_zigbee_sync_skips_when_disabled():
+    with patch("app.core.scheduler.settings") as mock_settings:
+        mock_settings.zigbee_sync_enabled = False
+        await _run_zigbee_sync()  # returns before importing/fetching anything
+
+
+@pytest.mark.asyncio
+async def test_run_zigbee_sync_skips_when_no_host():
+    with patch("app.core.scheduler.settings") as mock_settings:
+        mock_settings.zigbee_sync_enabled = True
+        mock_settings.zigbee_mqtt_host = ""
+        await _run_zigbee_sync()  # no exception, no fetch
+
+
+@pytest.mark.asyncio
+async def test_run_zwave_sync_skips_when_no_host():
+    with patch("app.core.scheduler.settings") as mock_settings:
+        mock_settings.zwave_sync_enabled = True
+        mock_settings.zwave_mqtt_host = ""
+        await _run_zwave_sync()
+
+
+@pytest.mark.asyncio
+async def test_run_zigbee_sync_records_scan_run(mem_db):
+    """Auto-sync must create a ScanRun (kind=zigbee) so it shows in Scan history,
+    then delegate to the shared background import with the run id + env payload."""
+    from app.db.models import ScanRun
+    from app.schemas.zigbee import ZigbeeImportRequest
+
+    fake_payload = ZigbeeImportRequest(mqtt_host="broker", mqtt_port=1883)
+
+    with (
+        patch("app.core.scheduler.settings") as mock_settings,
+        patch("app.core.scheduler.AsyncSessionLocal", mem_db),
+        patch("app.api.routes.zigbee._background_zigbee_import", new_callable=AsyncMock) as mock_bg,
+        patch("app.api.routes.zigbee.env_import_request", return_value=fake_payload),
+    ):
+        mock_settings.zigbee_sync_enabled = True
+        mock_settings.zigbee_mqtt_host = "broker"
+        mock_settings.zigbee_mqtt_port = 1883
+        await _run_zigbee_sync()
+
+    async with mem_db() as db:
+        from sqlalchemy import select
+        run = (await db.execute(select(ScanRun))).scalars().one()
+    assert run.kind == "zigbee"
+    assert run.ranges == ["broker:1883"]
+    mock_bg.assert_awaited_once_with(run.id, fake_payload)
+
+
+@pytest.mark.asyncio
+async def test_run_zwave_sync_records_scan_run(mem_db):
+    """Auto-sync must create a ScanRun (kind=zwave) then delegate to the shared
+    background import with the run id + env payload."""
+    from app.db.models import ScanRun
+    from app.schemas.zwave import ZwaveImportRequest
+
+    fake_payload = ZwaveImportRequest(mqtt_host="broker", mqtt_port=1883)
+
+    with (
+        patch("app.core.scheduler.settings") as mock_settings,
+        patch("app.core.scheduler.AsyncSessionLocal", mem_db),
+        patch("app.api.routes.zwave._background_zwave_import", new_callable=AsyncMock) as mock_bg,
+        patch("app.api.routes.zwave.env_import_request", return_value=fake_payload),
+    ):
+        mock_settings.zwave_sync_enabled = True
+        mock_settings.zwave_mqtt_host = "broker"
+        mock_settings.zwave_mqtt_port = 1883
+        await _run_zwave_sync()
+
+    async with mem_db() as db:
+        from sqlalchemy import select
+        run = (await db.execute(select(ScanRun))).scalars().one()
+    assert run.kind == "zwave"
+    assert run.ranges == ["broker:1883"]
+    mock_bg.assert_awaited_once_with(run.id, fake_payload)
+
+
+def test_reschedule_zigbee_sync_noop_when_not_running():
+    mock_sched = MagicMock()
+    mock_sched.running = False
+    with patch("app.core.scheduler.scheduler", mock_sched):
+        reschedule_zigbee_sync(600)
+    mock_sched.reschedule_job.assert_not_called()
+
+
+def test_start_scheduler_adds_mesh_jobs_when_enabled():
+    mock_sched = MagicMock()
+    with patch("app.core.scheduler.settings") as mock_settings, \
+         patch("app.core.scheduler.AsyncIOScheduler", return_value=mock_sched):
+        mock_settings.status_checker_interval = 60
+        mock_settings.service_check_enabled = False
+        mock_settings.proxmox_sync_enabled = False
+        mock_settings.zigbee_sync_enabled = True
+        mock_settings.zigbee_sync_interval = 3600
+        mock_settings.zwave_sync_enabled = True
+        mock_settings.zwave_sync_interval = 3600
+        start_scheduler()
+    job_ids = [kw.get("id") for _, kw in mock_sched.add_job.call_args_list]
+    assert "zigbee_sync" in job_ids
+    assert "zwave_sync" in job_ids
+
+
+# --- reschedule_* validation and not-running guards ---
+
+def test_reschedule_status_checks_rejects_short_interval():
+    with pytest.raises(ValueError):
+        reschedule_status_checks(5)
+
+
+def test_reschedule_status_checks_noop_when_not_running():
+    mock_sched = MagicMock()
+    mock_sched.running = False
+    with patch("app.core.scheduler.scheduler", mock_sched):
+        reschedule_status_checks(60)
+    mock_sched.reschedule_job.assert_not_called()
+
+
+def test_reschedule_status_checks_updates_running_job():
+    mock_sched = MagicMock()
+    mock_sched.running = True
+    with patch("app.core.scheduler.scheduler", mock_sched):
+        reschedule_status_checks(60)
+    mock_sched.reschedule_job.assert_called_once_with(
+        "status_checks", trigger="interval", seconds=60,
+    )
+
+
+def test_reschedule_service_checks_rejects_short_interval():
+    with pytest.raises(ValueError):
+        reschedule_service_checks(10)
+
+
+def test_reschedule_service_checks_updates_when_job_exists():
+    mock_sched = MagicMock()
+    mock_sched.running = True
+    mock_sched.get_job.return_value = MagicMock()
+    with patch("app.core.scheduler.scheduler", mock_sched):
+        reschedule_service_checks(60)
+    mock_sched.reschedule_job.assert_called_once_with(
+        "service_checks", trigger="interval", seconds=60,
+    )
+
+
+def test_reschedule_proxmox_sync_noop_when_not_running():
+    mock_sched = MagicMock()
+    mock_sched.running = False
+    with patch("app.core.scheduler.scheduler", mock_sched):
+        reschedule_proxmox_sync(600)
+    mock_sched.reschedule_job.assert_not_called()

backend/tests/test_settings.py

@@ -1,15 +1,11 @@
 """Tests for GET/POST /api/v1/settings."""
+import json
 from unittest.mock import patch
 
 import pytest
 from httpx import AsyncClient
 
-
-@pytest.fixture
-async def headers(client: AsyncClient):
-    res = await client.post("/api/v1/auth/login", json={"username": "admin", "password": "admin"})
-    token = res.json()["access_token"]
-    return {"Authorization": f"Bearer {token}"}
+from app.core.config import Settings
 
 
 @pytest.mark.asyncio
@@ -84,3 +80,151 @@ async def test_update_settings_rejects_too_short_service_interval(client: AsyncC
         headers=headers,
     )
     assert res.status_code == 422
+
+
+def test_proxmox_connection_config_is_env_only_never_from_overrides(tmp_path):
+    """Connection config (host/port/verify_tls) is env-only: a stale value in
+    scan_config.json must be ignored so it can never clobber the env. Only the
+    auto-sync activation is read back."""
+    s = Settings(secret_key="x", sqlite_path=str(tmp_path / "homelab.db"))
+    s.proxmox_host = "pve.local"  # as if set from env
+    s.proxmox_port = 8006
+    s.proxmox_verify_tls = True
+    (tmp_path / "scan_config.json").write_text(json.dumps({
+        "proxmox_host": "stale-host",
+        "proxmox_port": 9999,
+        "proxmox_verify_tls": False,
+        "proxmox_sync_enabled": True,
+        "proxmox_sync_interval": 600,
+    }))
+    s.load_overrides()
+    # Connection config untouched by the file (env values survive).
+    assert s.proxmox_host == "pve.local"
+    assert s.proxmox_port == 8006
+    assert s.proxmox_verify_tls is True
+    # Auto-sync activation is the only thing loaded.
+    assert s.proxmox_sync_enabled is True
+    assert s.proxmox_sync_interval == 600
+
+
+def test_save_overrides_omits_proxmox_connection_config(tmp_path):
+    """save_overrides must never write host/port/verify_tls (nor the token) —
+    only the sync activation. This is what prevents the dual source of truth."""
+    s = Settings(secret_key="x", sqlite_path=str(tmp_path / "homelab.db"))
+    s.proxmox_host = "pve.local"
+    s.proxmox_sync_enabled = True
+    s.proxmox_sync_interval = 900
+    s.save_overrides()
+    written = json.loads((tmp_path / "scan_config.json").read_text())
+    assert "proxmox_host" not in written
+    assert "proxmox_port" not in written
+    assert "proxmox_verify_tls" not in written
+    assert "proxmox_token_id" not in written
+    assert "proxmox_token_secret" not in written
+    assert written["proxmox_sync_enabled"] is True
+    assert written["proxmox_sync_interval"] == 900
+
+
+def test_mesh_connection_config_is_env_only_never_from_overrides(tmp_path):
+    """Zigbee/Z-Wave MQTT connection config (host/port/credentials/topic/tls) is
+    env-only: stale values in scan_config.json must be ignored. Only the
+    auto-sync activation is read back."""
+    s = Settings(secret_key="x", sqlite_path=str(tmp_path / "homelab.db"))
+    s.zigbee_mqtt_host = "broker.local"
+    s.zwave_mqtt_host = "broker.local"
+    (tmp_path / "scan_config.json").write_text(json.dumps({
+        "zigbee_mqtt_host": "stale", "zigbee_mqtt_password": "stale",
+        "zigbee_sync_enabled": True, "zigbee_sync_interval": 600,
+        "zwave_mqtt_host": "stale", "zwave_mqtt_password": "stale",
+        "zwave_sync_enabled": True, "zwave_sync_interval": 700,
+    }))
+    s.load_overrides()
+    assert s.zigbee_mqtt_host == "broker.local"
+    assert s.zwave_mqtt_host == "broker.local"
+    assert s.zigbee_sync_enabled is True
+    assert s.zigbee_sync_interval == 600
+    assert s.zwave_sync_enabled is True
+    assert s.zwave_sync_interval == 700
+
+
+def test_save_overrides_omits_mesh_credentials(tmp_path):
+    """save_overrides must never write MQTT host/credentials — only the sync
+    activation. Prevents the dual source of truth and leaking secrets to disk."""
+    s = Settings(secret_key="x", sqlite_path=str(tmp_path / "homelab.db"))
+    s.zigbee_mqtt_host = "broker.local"
+    s.zigbee_mqtt_password = "secret"
+    s.zigbee_sync_enabled = True
+    s.zigbee_sync_interval = 900
+    s.zwave_mqtt_password = "secret"
+    s.zwave_sync_interval = 1200
+    s.save_overrides()
+    raw = (tmp_path / "scan_config.json").read_text()
+    assert "secret" not in raw
+    written = json.loads(raw)
+    assert "zigbee_mqtt_host" not in written
+    assert "zigbee_mqtt_password" not in written
+    assert "zwave_mqtt_password" not in written
+    assert written["zigbee_sync_enabled"] is True
+    assert written["zigbee_sync_interval"] == 900
+    assert written["zwave_sync_interval"] == 1200
+
+
+def _valid_oidc_settings(**overrides):
+    values = {
+        "secret_key": "test-secret-key-that-is-at-least-32-bytes",
+        "auth_mode": "oidc",
+        "oidc_discovery_url": "https://idp.example/application/o/homelable/.well-known/openid-configuration",
+        "oidc_client_id": "homelable",
+        "oidc_client_secret": "client-secret",
+        "oidc_redirect_uri": "https://homelable.example/api/v1/auth/oidc/callback",
+        "cors_origins": ["https://homelable.example"],
+    }
+    values.update(overrides)
+    return Settings(_env_file=None, **values)
+
+
+def test_oidc_mode_requires_complete_client_configuration():
+    with pytest.raises(ValueError, match="OIDC_DISCOVERY_URL.*OIDC_CLIENT_ID.*OIDC_CLIENT_SECRET.*OIDC_REDIRECT_URI"):
+        Settings(secret_key="test-secret", auth_mode="oidc", _env_file=None)
+
+
+def test_oidc_mode_requires_openid_scope():
+    with pytest.raises(ValueError, match="OIDC_SCOPES must contain 'openid'"):
+        _valid_oidc_settings(oidc_scopes="profile email")
+
+
+def test_oidc_mode_requires_strong_session_secret():
+    with pytest.raises(ValueError, match="SECRET_KEY must be at least 32 bytes"):
+        _valid_oidc_settings(secret_key="too-short")
+
+
+def test_oidc_secure_cookie_requires_https_callback():
+    with pytest.raises(ValueError, match="must use HTTPS"):
+        _valid_oidc_settings(oidc_redirect_uri="http://localhost/api/v1/auth/oidc/callback")
+
+
+def test_oidc_secure_cookie_requires_https_discovery():
+    with pytest.raises(ValueError, match="OIDC_DISCOVERY_URL must use HTTPS"):
+        _valid_oidc_settings(
+            oidc_discovery_url="http://idp.local/application/o/homelable/.well-known/openid-configuration"
+        )
+
+
+def test_oidc_insecure_dev_mode_allows_http_urls():
+    configured = _valid_oidc_settings(
+        oidc_cookie_secure=False,
+        oidc_discovery_url="http://idp.local/.well-known/openid-configuration",
+        oidc_redirect_uri="http://localhost/api/v1/auth/oidc/callback",
+    )
+    assert configured.oidc_cookie_secure is False
+
+
+def test_oidc_mode_rejects_wildcard_cors():
+    with pytest.raises(ValueError, match="CORS_ORIGINS cannot contain"):
+        _valid_oidc_settings(cors_origins=["*"])
+
+
+def test_valid_oidc_configuration_is_accepted():
+    configured = _valid_oidc_settings()
+    assert configured.auth_mode == "oidc"
+    assert configured.oidc_cookie_secure is True

backend/tests/test_stats.py

@@ -9,7 +9,7 @@ from httpx import AsyncClient
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.config import settings
-from app.db.models import Node, PendingDevice, ScanRun
+from app.db.models import InventoryDevice, Node, ScanRun
 
 
 @pytest.fixture(autouse=True)
@@ -75,9 +75,9 @@ async def test_summary_aggregates_counts(
         Node(type="server", label="D", status="unknown"),
         Node(type="iot",    label="Z1", status="online", ieee_address="0x1"),
         Node(type="iot",    label="Z2", status="online", ieee_address="0x2"),
-        PendingDevice(ip="10.0.0.1", status="pending"),
-        PendingDevice(ip="10.0.0.2", status="pending"),
-        PendingDevice(ip="10.0.0.3", status="hidden"),  # excluded
+        InventoryDevice(ip="10.0.0.1", status="pending"),
+        InventoryDevice(ip="10.0.0.2", status="pending"),
+        InventoryDevice(ip="10.0.0.3", status="hidden"),  # excluded
         ScanRun(status="success", finished_at=finished),
         ScanRun(status="success",
                 finished_at=datetime(2026, 5, 13, 10, 0, tzinfo=timezone.utc)),

backend/tests/test_status_checker.py

@@ -4,6 +4,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 import pytest
 
 from app.services.status_checker import (
+    _http_get,
     _ping,
     _tcp_connect,
     check_node,
@@ -11,6 +12,18 @@ from app.services.status_checker import (
     check_services,
 )
 
+
+def _mock_httpx_client(status_code):
+    """Build a stand-in for httpx.AsyncClient whose GET returns status_code."""
+    resp = MagicMock()
+    resp.status_code = status_code
+    client = MagicMock()
+    client.get = AsyncMock(return_value=resp)
+    ctx = MagicMock()
+    ctx.__aenter__ = AsyncMock(return_value=client)
+    ctx.__aexit__ = AsyncMock(return_value=False)
+    return MagicMock(return_value=ctx)
+
 # --- check_node dispatcher ---
 
 @pytest.mark.asyncio
@@ -462,3 +475,35 @@ async def test_check_services_returns_status_per_service():
 @pytest.mark.asyncio
 async def test_check_services_empty_list():
     assert await check_services("10.0.0.1", []) == []
+
+
+# --- _http_get status-code interpretation (real primitive, mocked transport) ---
+
+@pytest.mark.asyncio
+async def test_http_get_true_on_2xx():
+    with patch("app.services.status_checker.httpx.AsyncClient", _mock_httpx_client(200)):
+        assert await _http_get("http://host") is True
+
+
+@pytest.mark.asyncio
+async def test_http_get_true_on_4xx():
+    # A 4xx means the server is up and answering — still "online".
+    with patch("app.services.status_checker.httpx.AsyncClient", _mock_httpx_client(404)):
+        assert await _http_get("http://host") is True
+
+
+@pytest.mark.asyncio
+async def test_http_get_false_on_5xx():
+    with patch("app.services.status_checker.httpx.AsyncClient", _mock_httpx_client(503)):
+        assert await _http_get("http://host") is False
+
+
+@pytest.mark.asyncio
+async def test_check_service_http_exception_returns_offline():
+    svc = {"port": 80, "protocol": "tcp", "service_name": "http"}
+    with patch(
+        "app.services.status_checker._http_get",
+        new_callable=AsyncMock,
+        side_effect=RuntimeError("connection refused"),
+    ):
+        assert await check_service(svc, "10.0.0.1") == "offline"

backend/tests/test_zigbee_router.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from unittest.mock import patch
+from unittest.mock import AsyncMock, patch
 
 import pytest
 from httpx import AsyncClient
@@ -11,13 +11,6 @@ from httpx import AsyncClient
 # Fixtures
 # ---------------------------------------------------------------------------
 
-@pytest.fixture
-async def headers(client: AsyncClient):
-    res = await client.post("/api/v1/auth/login", json={"username": "admin", "password": "admin"})
-    token = res.json()["access_token"]
-    return {"Authorization": f"Bearer {token}"}
-
-
 # ---------------------------------------------------------------------------
 # /api/v1/zigbee/test-connection
 # ---------------------------------------------------------------------------
@@ -338,20 +331,36 @@ async def test_import_pending_endpoint_creates_zigbee_scan_run(
 
 
 @pytest.mark.asyncio
-async def test_persist_pending_import_creates_coordinator_and_pending(
+async def test_persist_pending_import_coordinator_goes_to_pending(
     db_session,
 ) -> None:
+    """Coordinator is no longer auto-placed — it lands in pending like the rest."""
+    from sqlalchemy import select
+
     from app.api.routes.zigbee import _persist_pending_import
+    from app.db.models import InventoryDevice, Node
 
     result = await _persist_pending_import(db_session, _PENDING_NODES, _PENDING_EDGES)
     assert result.device_count == 3
-    assert result.pending_created == 2
+    assert result.pending_created == 3          # coordinator included now
     assert result.pending_updated == 0
-    assert result.coordinator is not None
-    assert result.coordinator.ieee_address == "0xCOORD"
+    assert result.coordinator is None           # not auto-placed
     assert result.coordinator_already_existed is False
     assert result.links_recorded == 2
 
+    # No canvas Node auto-created for the coordinator.
+    nodes = (await db_session.execute(select(Node))).scalars().all()
+    assert nodes == []
+    # Coordinator sits in the pending inventory.
+    coord = (
+        await db_session.execute(
+            select(InventoryDevice).where(InventoryDevice.ieee_address == "0xCOORD")
+        )
+    ).scalar_one()
+    assert coord.status == "pending"
+    assert coord.suggested_type == "zigbee_coordinator"
+    assert coord.device_subtype == "Coordinator"
+
 
 @pytest.mark.asyncio
 async def test_persist_pending_import_idempotent_updates_existing(
@@ -366,8 +375,8 @@ async def test_persist_pending_import_idempotent_updates_existing(
     result = await _persist_pending_import(db_session, bumped, _PENDING_EDGES)
 
     assert result.pending_created == 0
-    assert result.pending_updated == 2
-    assert result.coordinator_already_existed is True
+    assert result.pending_updated == 3          # coordinator upserts too
+    assert result.coordinator_already_existed is False
     assert result.links_recorded == 2
 
 
@@ -376,25 +385,25 @@ async def test_persist_pending_import_replaces_links(db_session) -> None:
     from sqlalchemy import select
 
     from app.api.routes.zigbee import _persist_pending_import
-    from app.db.models import PendingDeviceLink
+    from app.db.models import InventoryDeviceLink
 
     await _persist_pending_import(db_session, _PENDING_NODES, _PENDING_EDGES)
 
     new_edges = [{"source": "0xCOORD", "target": "0xR1"}]
     await _persist_pending_import(db_session, _PENDING_NODES[:2], new_edges)
 
-    rows = (await db_session.execute(select(PendingDeviceLink))).scalars().all()
+    rows = (await db_session.execute(select(InventoryDeviceLink))).scalars().all()
     assert len(rows) == 1
     assert (rows[0].source_ieee, rows[0].target_ieee) == ("0xCOORD", "0xR1")
 
 
 @pytest.mark.asyncio
-async def test_persist_pending_import_sets_coordinator_properties(db_session) -> None:
-    """Coordinator Node is created with IEEE/Vendor/Model/LQI in properties."""
+async def test_persist_pending_import_sets_coordinator_pending_fields(db_session) -> None:
+    """Coordinator lands in pending carrying its vendor/model metadata."""
     from sqlalchemy import select
 
     from app.api.routes.zigbee import _persist_pending_import
-    from app.db.models import Node
+    from app.db.models import InventoryDevice
 
     nodes_with_meta = [dict(n) for n in _PENDING_NODES]
     nodes_with_meta[0]["vendor"] = "TI"
@@ -403,28 +412,30 @@ async def test_persist_pending_import_sets_coordinator_properties(db_session) ->
     await _persist_pending_import(db_session, nodes_with_meta, _PENDING_EDGES)
 
     coord = (
-        await db_session.execute(select(Node).where(Node.ieee_address == "0xCOORD"))
+        await db_session.execute(
+            select(InventoryDevice).where(InventoryDevice.ieee_address == "0xCOORD")
+        )
     ).scalar_one()
-    keys = {p["key"]: p["value"] for p in coord.properties}
-    assert keys == {"IEEE": "0xCOORD", "Vendor": "TI", "Model": "CC2652"}
-    # New zigbee props default to hidden — user opts in from the right panel.
-    assert all(p["visible"] is False for p in coord.properties)
+    assert coord.vendor == "TI"
+    assert coord.model == "CC2652"
+    assert coord.suggested_type == "zigbee_coordinator"
 
 
 @pytest.mark.asyncio
-async def test_persist_pending_import_skips_pending_for_approved_node(
+async def test_persist_pending_import_backfills_inventory_for_approved_node(
     db_session,
 ) -> None:
-    """A device already approved as a canvas Node must not reappear in pending.
-
-    Its properties must still be refreshed with the latest Vendor/Model/LQI.
+    """A device on canvas but missing its inventory row gets one backfilled
+    (status="approved"), so it shows in the inventory list. Node props still
+    refresh with the latest Vendor/Model/LQI.
     """
     from sqlalchemy import select
 
     from app.api.routes.zigbee import _persist_pending_import
-    from app.db.models import Node, PendingDevice
+    from app.db.models import InventoryDevice, Node
 
-    # Simulate: router was approved earlier → exists as a canvas Node.
+    # Simulate: router was approved earlier → exists as a canvas Node, but with
+    # no matching device_inventory row (e.g. a legacy auto-placed device).
     approved = Node(
         label="router_1",
         type="zigbee_router",
@@ -441,13 +452,15 @@ async def test_persist_pending_import_skips_pending_for_approved_node(
     bumped[1]["lqi"] = 250  # new LQI from re-import
     await _persist_pending_import(db_session, bumped, _PENDING_EDGES)
 
-    # No PendingDevice row was created for the approved router.
-    pendings = (
+    # An inventory row is backfilled as "approved" (it is on a canvas).
+    inv = (
         await db_session.execute(
-            select(PendingDevice).where(PendingDevice.ieee_address == "0xR1")
+            select(InventoryDevice).where(InventoryDevice.ieee_address == "0xR1")
         )
-    ).scalars().all()
-    assert pendings == []
+    ).scalar_one()
+    assert inv.status == "approved"
+    assert inv.suggested_type == "zigbee_router"
+    assert inv.device_subtype == "Router"
 
     # Node properties got refreshed.
     refreshed = (
@@ -459,13 +472,44 @@ async def test_persist_pending_import_skips_pending_for_approved_node(
     assert all(p["visible"] is False for p in refreshed.properties)
 
 
+@pytest.mark.asyncio
+async def test_persist_pending_import_preserves_hidden_inventory_for_approved_node(
+    db_session,
+) -> None:
+    """If the on-canvas device already has a hidden inventory row, re-import
+    refreshes its metadata but must NOT flip it back to approved/visible."""
+    from sqlalchemy import select
+
+    from app.api.routes.zigbee import _persist_pending_import
+    from app.db.models import InventoryDevice, Node
+
+    db_session.add(Node(
+        label="router_1", type="zigbee_router", status="online",
+        check_method="none", ieee_address="0xR1", services=[], properties=[],
+    ))
+    db_session.add(InventoryDevice(
+        ieee_address="0xR1", friendly_name="router_1", suggested_type="zigbee_router",
+        device_subtype="Router", status="hidden", discovery_source="zigbee",
+    ))
+    await db_session.commit()
+
+    await _persist_pending_import(db_session, _PENDING_NODES, _PENDING_EDGES)
+
+    inv = (
+        await db_session.execute(
+            select(InventoryDevice).where(InventoryDevice.ieee_address == "0xR1")
+        )
+    ).scalar_one()
+    assert inv.status == "hidden"  # stays hidden
+
+
 @pytest.mark.asyncio
 async def test_persist_pending_import_revives_orphaned_approved_device(
     db_session,
 ) -> None:
     """Regression for #167: approve → delete node → re-import must re-list device.
 
-    When a device was approved (PendingDevice.status="approved") and its canvas
+    When a device was approved (InventoryDevice.status="approved") and its canvas
     Node was later deleted, the orphaned "approved" row must be reset to
     "pending" on re-import so it shows up in the Pending list again — instead of
     being silently swallowed (re-import reports "found" but Pending stays empty).
@@ -473,11 +517,11 @@ async def test_persist_pending_import_revives_orphaned_approved_device(
     from sqlalchemy import select
 
     from app.api.routes.zigbee import _persist_pending_import
-    from app.db.models import PendingDevice
+    from app.db.models import InventoryDevice
 
-    # Simulate prior approve: a PendingDevice marked approved, but NO matching
+    # Simulate prior approve: a InventoryDevice marked approved, but NO matching
     # Node exists (the user deleted the canvas node afterwards).
-    orphan = PendingDevice(
+    orphan = InventoryDevice(
         ieee_address="0xR1",
         friendly_name="router_1",
         hostname="router_1",
@@ -497,21 +541,21 @@ async def test_persist_pending_import_revives_orphaned_approved_device(
     # No new row created for 0xR1 — the existing one was updated/revived.
     revived = (
         await db_session.execute(
-            select(PendingDevice).where(PendingDevice.ieee_address == "0xR1")
+            select(InventoryDevice).where(InventoryDevice.ieee_address == "0xR1")
         )
     ).scalar_one()
     assert revived.status == "pending"
-    # End device 0xE1 is brand new → created as pending; router was updated.
-    assert result.pending_created == 1
+    # Coordinator + end device 0xE1 are brand new → created; router was revived.
+    assert result.pending_created == 2
     assert result.pending_updated == 1
 
     # It is now visible to the Pending list (status filter == "pending").
     listed = (
         await db_session.execute(
-            select(PendingDevice).where(PendingDevice.status == "pending")
+            select(InventoryDevice).where(InventoryDevice.status == "pending")
         )
     ).scalars().all()
-    assert {p.ieee_address for p in listed} == {"0xR1", "0xE1"}
+    assert {p.ieee_address for p in listed} == {"0xCOORD", "0xR1", "0xE1"}
 
 
 @pytest.mark.asyncio
@@ -522,9 +566,9 @@ async def test_persist_pending_import_keeps_hidden_hidden_on_reimport(
     from sqlalchemy import select
 
     from app.api.routes.zigbee import _persist_pending_import
-    from app.db.models import PendingDevice
+    from app.db.models import InventoryDevice
 
-    hidden = PendingDevice(
+    hidden = InventoryDevice(
         ieee_address="0xR1",
         friendly_name="router_1",
         suggested_type="zigbee_router",
@@ -539,7 +583,7 @@ async def test_persist_pending_import_keeps_hidden_hidden_on_reimport(
 
     still_hidden = (
         await db_session.execute(
-            select(PendingDevice).where(PendingDevice.ieee_address == "0xR1")
+            select(InventoryDevice).where(InventoryDevice.ieee_address == "0xR1")
         )
     ).scalar_one()
     assert still_hidden.status == "hidden"
@@ -591,15 +635,23 @@ async def test_persist_pending_import_preserves_user_visibility(db_session) -> N
 
 
 @pytest.mark.asyncio
-async def test_persist_pending_import_refreshes_existing_coordinator_properties(
+async def test_persist_pending_import_refreshes_approved_coordinator_node(
     db_session,
 ) -> None:
+    """An already-approved coordinator Node gets its props refreshed on
+    re-import, and a backfilled inventory row (approved) so it shows in the
+    inventory list — this is the legacy auto-placed coordinator scenario."""
     from sqlalchemy import select
 
     from app.api.routes.zigbee import _persist_pending_import
-    from app.db.models import Node
+    from app.db.models import InventoryDevice, Node
 
-    await _persist_pending_import(db_session, _PENDING_NODES, _PENDING_EDGES)
+    # Legacy: coordinator auto-placed as a canvas Node, no device_inventory row.
+    db_session.add(Node(
+        label="Coordinator", type="zigbee_coordinator", status="online",
+        check_method="none", ieee_address="0xCOORD", services=[], properties=[],
+    ))
+    await db_session.commit()
 
     bumped = [dict(n) for n in _PENDING_NODES]
     bumped[0]["vendor"] = "TI"
@@ -612,10 +664,53 @@ async def test_persist_pending_import_refreshes_existing_coordinator_properties(
     keys = {p["key"]: p["value"] for p in coord.properties}
     assert keys["Vendor"] == "TI"
     assert keys["Model"] == "CC2652"
-    # Newly added keys on re-import default to hidden.
     by_key = {p["key"]: p for p in coord.properties}
     assert by_key["Vendor"]["visible"] is False
-    assert by_key["Model"]["visible"] is False
+    # Inventory row backfilled as approved → now visible in the inventory list.
+    inv = (
+        await db_session.execute(
+            select(InventoryDevice).where(InventoryDevice.ieee_address == "0xCOORD")
+        )
+    ).scalar_one()
+    assert inv.status == "approved"
+    assert inv.suggested_type == "zigbee_coordinator"
+
+
+@pytest.mark.asyncio
+async def test_persist_pending_import_device_on_multiple_canvases(
+    db_session,
+) -> None:
+    """Regression: a device approved onto TWO designs (one Node each) must not
+    crash re-import with MultipleResultsFound — props refresh on both nodes."""
+    from sqlalchemy import select
+
+    from app.api.routes.zigbee import _persist_pending_import
+    from app.db.models import Design, Node
+
+    d1 = Design(name="d1")
+    d2 = Design(name="d2")
+    db_session.add_all([d1, d2])
+    await db_session.flush()
+    for d in (d1, d2):
+        db_session.add(Node(
+            label="router_1", type="zigbee_router", status="online",
+            check_method="none", ieee_address="0xR1", services=[],
+            properties=[], design_id=d.id,
+        ))
+    await db_session.commit()
+
+    bumped = [dict(n) for n in _PENDING_NODES]
+    bumped[1]["lqi"] = 240
+    # Must not raise.
+    await _persist_pending_import(db_session, bumped, _PENDING_EDGES)
+
+    nodes = (
+        await db_session.execute(select(Node).where(Node.ieee_address == "0xR1"))
+    ).scalars().all()
+    assert len(nodes) == 2  # both canvas placements preserved
+    for n in nodes:
+        lqi = {p["key"]: p["value"] for p in n.properties}.get("LQI")
+        assert lqi == "240"  # refreshed on every canvas
 
 
 @pytest.mark.asyncio
@@ -645,3 +740,106 @@ async def test_test_connection_with_tls(client: AsyncClient, headers: dict) -> N
     kwargs = mock_conn.call_args.kwargs
     assert kwargs["tls"] is True
     assert kwargs["tls_insecure"] is True
+
+
+# ---------------------------------------------------------------------------
+# /api/v1/zigbee/config + /sync-now (auto-sync)
+# ---------------------------------------------------------------------------
+
+from app.core.config import settings  # noqa: E402
+
+
+@pytest.fixture
+def _restore_zigbee_env():
+    """Snapshot + restore the env-only Zigbee connection/activation settings."""
+    keys = (
+        "zigbee_mqtt_host", "zigbee_mqtt_port", "zigbee_mqtt_username",
+        "zigbee_mqtt_password", "zigbee_base_topic", "zigbee_sync_enabled",
+        "zigbee_sync_interval",
+    )
+    saved = {k: getattr(settings, k) for k in keys}
+    yield
+    for k, v in saved.items():
+        setattr(settings, k, v)
+
+
+@pytest.mark.asyncio
+async def test_config_omits_credentials(
+    client: AsyncClient, headers: dict, _restore_zigbee_env
+) -> None:
+    settings.zigbee_mqtt_host = "broker"
+    settings.zigbee_mqtt_username = "user"
+    settings.zigbee_mqtt_password = "supersecret"
+    res = await client.get("/api/v1/zigbee/config", headers=headers)
+    assert res.status_code == 200
+    assert "supersecret" not in res.text
+    assert "user" not in res.text
+    assert res.json()["host_configured"] is True
+
+
+@pytest.mark.asyncio
+async def test_config_requires_auth(client: AsyncClient) -> None:
+    res = await client.get("/api/v1/zigbee/config")
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_enable_sync_without_host_rejected(
+    client: AsyncClient, headers: dict, _restore_zigbee_env
+) -> None:
+    settings.zigbee_mqtt_host = ""
+    res = await client.post(
+        "/api/v1/zigbee/config",
+        json={"sync_enabled": True, "sync_interval": 600},
+        headers=headers,
+    )
+    assert res.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_save_config_persists_only_sync_fields(
+    client: AsyncClient, headers: dict, _restore_zigbee_env
+) -> None:
+    settings.zigbee_mqtt_host = "broker"
+    saved: dict = {}
+    with patch.object(type(settings), "save_overrides", lambda self: saved.update(
+        host=self.zigbee_mqtt_host, enabled=self.zigbee_sync_enabled,
+        interval=self.zigbee_sync_interval,
+    )), patch("app.api.routes.zigbee.set_zigbee_sync_enabled"), \
+            patch("app.api.routes.zigbee.reschedule_zigbee_sync"):
+        res = await client.post(
+            "/api/v1/zigbee/config",
+            json={"mqtt_host": "attacker", "sync_enabled": True, "sync_interval": 900},
+            headers=headers,
+        )
+    assert res.status_code == 200
+    assert settings.zigbee_mqtt_host == "broker"  # body host ignored
+    assert saved == {"host": "broker", "enabled": True, "interval": 900}
+
+
+@pytest.mark.asyncio
+async def test_sync_now_creates_scan_run(
+    client: AsyncClient, headers: dict, _restore_zigbee_env
+) -> None:
+    settings.zigbee_mqtt_host = "broker"
+    with patch("app.api.routes.zigbee._background_zigbee_import", new_callable=AsyncMock):
+        res = await client.post("/api/v1/zigbee/sync-now", headers=headers)
+    assert res.status_code == 200
+    data = res.json()
+    assert data["kind"] == "zigbee"
+    assert data["status"] == "running"
+
+
+@pytest.mark.asyncio
+async def test_sync_now_rejected_without_host(
+    client: AsyncClient, headers: dict, _restore_zigbee_env
+) -> None:
+    settings.zigbee_mqtt_host = ""
+    res = await client.post("/api/v1/zigbee/sync-now", headers=headers)
+    assert res.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_sync_now_requires_auth(client: AsyncClient) -> None:
+    res = await client.post("/api/v1/zigbee/sync-now")
+    assert res.status_code == 401

backend/tests/test_zwave_router.py

@@ -7,14 +7,6 @@ from unittest.mock import patch
 import pytest
 from httpx import AsyncClient
 
-
-@pytest.fixture
-async def headers(client: AsyncClient):
-    res = await client.post("/api/v1/auth/login", json={"username": "admin", "password": "admin"})
-    token = res.json()["access_token"]
-    return {"Authorization": f"Bearer {token}"}
-
-
 # ---------------------------------------------------------------------------
 # /api/v1/zwave/test-connection
 # ---------------------------------------------------------------------------
@@ -297,18 +289,31 @@ async def test_import_pending_requires_auth(client: AsyncClient) -> None:
 
 
 @pytest.mark.asyncio
-async def test_persist_creates_coordinator_and_pending(db_session) -> None:
+async def test_persist_coordinator_goes_to_pending(db_session) -> None:
+    """Coordinator is no longer auto-placed — it lands in pending like the rest."""
+    from sqlalchemy import select
+
     from app.api.routes.zwave import _persist_pending_import
+    from app.db.models import InventoryDevice, Node
 
     result = await _persist_pending_import(db_session, _PENDING_NODES, _PENDING_EDGES)
     assert result.device_count == 3
-    assert result.pending_created == 2
+    assert result.pending_created == 3          # coordinator included now
     assert result.pending_updated == 0
-    assert result.coordinator is not None
-    assert result.coordinator.ieee_address == "zwave-0xh-1"
+    assert result.coordinator is None           # not auto-placed
     assert result.coordinator_already_existed is False
     assert result.links_recorded == 2
 
+    nodes = (await db_session.execute(select(Node))).scalars().all()
+    assert nodes == []
+    coord = (
+        await db_session.execute(
+            select(InventoryDevice).where(InventoryDevice.ieee_address == "zwave-0xh-1")
+        )
+    ).scalar_one()
+    assert coord.status == "pending"
+    assert coord.suggested_type == "zwave_coordinator"
+
 
 @pytest.mark.asyncio
 async def test_persist_idempotent_updates_existing(db_session) -> None:
@@ -319,8 +324,8 @@ async def test_persist_idempotent_updates_existing(db_session) -> None:
     bumped[1]["model"] = "ZW111"
     result = await _persist_pending_import(db_session, bumped, _PENDING_EDGES)
     assert result.pending_created == 0
-    assert result.pending_updated == 2
-    assert result.coordinator_already_existed is True
+    assert result.pending_updated == 3          # coordinator upserts too
+    assert result.coordinator_already_existed is False
 
 
 @pytest.mark.asyncio
@@ -328,41 +333,46 @@ async def test_persist_replaces_links(db_session) -> None:
     from sqlalchemy import select
 
     from app.api.routes.zwave import _persist_pending_import
-    from app.db.models import PendingDeviceLink
+    from app.db.models import InventoryDeviceLink
 
     await _persist_pending_import(db_session, _PENDING_NODES, _PENDING_EDGES)
     new_edges = [{"source": "zwave-0xh-1", "target": "zwave-0xh-2"}]
     await _persist_pending_import(db_session, _PENDING_NODES[:2], new_edges)
-    rows = (await db_session.execute(select(PendingDeviceLink))).scalars().all()
+    rows = (await db_session.execute(select(InventoryDeviceLink))).scalars().all()
     assert len(rows) == 1
     assert (rows[0].source_ieee, rows[0].target_ieee) == ("zwave-0xh-1", "zwave-0xh-2")
 
 
 @pytest.mark.asyncio
-async def test_persist_sets_coordinator_properties(db_session) -> None:
+async def test_persist_sets_coordinator_pending_fields(db_session) -> None:
+    """Coordinator lands in pending carrying its vendor/model metadata."""
     from sqlalchemy import select
 
     from app.api.routes.zwave import _persist_pending_import
-    from app.db.models import Node
+    from app.db.models import InventoryDevice
 
     nodes = [dict(n) for n in _PENDING_NODES]
     nodes[0]["vendor"] = "Aeotec"
     nodes[0]["model"] = "ZW090"
     await _persist_pending_import(db_session, nodes, _PENDING_EDGES)
     coord = (
-        await db_session.execute(select(Node).where(Node.ieee_address == "zwave-0xh-1"))
+        await db_session.execute(
+            select(InventoryDevice).where(InventoryDevice.ieee_address == "zwave-0xh-1")
+        )
     ).scalar_one()
-    keys = {p["key"]: p["value"] for p in coord.properties}
-    assert keys == {"Z-Wave ID": "zwave-0xh-1", "Vendor": "Aeotec", "Model": "ZW090"}
-    assert all(p["visible"] is False for p in coord.properties)
+    assert coord.vendor == "Aeotec"
+    assert coord.model == "ZW090"
+    assert coord.suggested_type == "zwave_coordinator"
 
 
 @pytest.mark.asyncio
-async def test_persist_skips_pending_for_approved_node(db_session) -> None:
+async def test_persist_backfills_inventory_for_approved_node(db_session) -> None:
+    """On-canvas device missing its inventory row gets one backfilled
+    (status="approved"); Node props still refresh."""
     from sqlalchemy import select
 
     from app.api.routes.zwave import _persist_pending_import
-    from app.db.models import Node, PendingDevice
+    from app.db.models import InventoryDevice, Node
 
     approved = Node(
         label="Wall Plug",
@@ -378,12 +388,13 @@ async def test_persist_skips_pending_for_approved_node(db_session) -> None:
 
     await _persist_pending_import(db_session, _PENDING_NODES, _PENDING_EDGES)
 
-    pendings = (
+    inv = (
         await db_session.execute(
-            select(PendingDevice).where(PendingDevice.ieee_address == "zwave-0xh-2")
+            select(InventoryDevice).where(InventoryDevice.ieee_address == "zwave-0xh-2")
         )
-    ).scalars().all()
-    assert pendings == []
+    ).scalar_one()
+    assert inv.status == "approved"
+    assert inv.suggested_type == "zwave_router"
     refreshed = (
         await db_session.execute(select(Node).where(Node.ieee_address == "zwave-0xh-2"))
     ).scalar_one()
@@ -396,9 +407,9 @@ async def test_persist_revives_orphaned_approved_device(db_session) -> None:
     from sqlalchemy import select
 
     from app.api.routes.zwave import _persist_pending_import
-    from app.db.models import PendingDevice
+    from app.db.models import InventoryDevice
 
-    orphan = PendingDevice(
+    orphan = InventoryDevice(
         ieee_address="zwave-0xh-2",
         friendly_name="Wall Plug",
         suggested_type="zwave_router",
@@ -412,11 +423,12 @@ async def test_persist_revives_orphaned_approved_device(db_session) -> None:
     result = await _persist_pending_import(db_session, _PENDING_NODES, _PENDING_EDGES)
     revived = (
         await db_session.execute(
-            select(PendingDevice).where(PendingDevice.ieee_address == "zwave-0xh-2")
+            select(InventoryDevice).where(InventoryDevice.ieee_address == "zwave-0xh-2")
         )
     ).scalar_one()
     assert revived.status == "pending"
-    assert result.pending_created == 1
+    # Coordinator + end device are brand new → created; router was revived.
+    assert result.pending_created == 2
     assert result.pending_updated == 1
 
 
@@ -425,9 +437,9 @@ async def test_persist_keeps_hidden_hidden(db_session) -> None:
     from sqlalchemy import select
 
     from app.api.routes.zwave import _persist_pending_import
-    from app.db.models import PendingDevice
+    from app.db.models import InventoryDevice
 
-    hidden = PendingDevice(
+    hidden = InventoryDevice(
         ieee_address="zwave-0xh-2",
         friendly_name="Wall Plug",
         suggested_type="zwave_router",
@@ -441,7 +453,147 @@ async def test_persist_keeps_hidden_hidden(db_session) -> None:
     await _persist_pending_import(db_session, _PENDING_NODES, _PENDING_EDGES)
     still_hidden = (
         await db_session.execute(
-            select(PendingDevice).where(PendingDevice.ieee_address == "zwave-0xh-2")
+            select(InventoryDevice).where(InventoryDevice.ieee_address == "zwave-0xh-2")
         )
     ).scalar_one()
     assert still_hidden.status == "hidden"
+
+
+@pytest.mark.asyncio
+async def test_persist_device_on_multiple_canvases(db_session) -> None:
+    """Regression: a device on TWO designs (one Node each) must not crash
+    re-import with MultipleResultsFound — props refresh on both nodes."""
+    from sqlalchemy import select
+
+    from app.api.routes.zwave import _persist_pending_import
+    from app.db.models import Design, Node
+
+    d1 = Design(name="d1")
+    d2 = Design(name="d2")
+    db_session.add_all([d1, d2])
+    await db_session.flush()
+    for d in (d1, d2):
+        db_session.add(Node(
+            label="Wall Plug", type="zwave_router", status="online",
+            check_method="none", ieee_address="zwave-0xh-2", services=[],
+            properties=[], design_id=d.id,
+        ))
+    await db_session.commit()
+
+    bumped = [dict(n) for n in _PENDING_NODES]
+    bumped[1]["model"] = "ZW200"
+    # Must not raise.
+    await _persist_pending_import(db_session, bumped, _PENDING_EDGES)
+
+    nodes = (
+        await db_session.execute(select(Node).where(Node.ieee_address == "zwave-0xh-2"))
+    ).scalars().all()
+    assert len(nodes) == 2  # both canvas placements preserved
+    for n in nodes:
+        model = {p["key"]: p["value"] for p in n.properties}.get("Model")
+        assert model == "ZW200"  # refreshed on every canvas
+
+
+# ---------------------------------------------------------------------------
+# /api/v1/zwave/config + /sync-now (auto-sync)
+# ---------------------------------------------------------------------------
+
+from unittest.mock import AsyncMock  # noqa: E402
+
+from app.core.config import settings  # noqa: E402
+
+
+@pytest.fixture
+def _restore_zwave_env():
+    """Snapshot + restore the env-only Z-Wave connection/activation settings."""
+    keys = (
+        "zwave_mqtt_host", "zwave_mqtt_port", "zwave_mqtt_username",
+        "zwave_mqtt_password", "zwave_prefix", "zwave_gateway_name",
+        "zwave_sync_enabled", "zwave_sync_interval",
+    )
+    saved = {k: getattr(settings, k) for k in keys}
+    yield
+    for k, v in saved.items():
+        setattr(settings, k, v)
+
+
+@pytest.mark.asyncio
+async def test_config_omits_credentials(
+    client: AsyncClient, headers: dict, _restore_zwave_env
+) -> None:
+    settings.zwave_mqtt_host = "broker"
+    settings.zwave_mqtt_username = "user"
+    settings.zwave_mqtt_password = "supersecret"
+    res = await client.get("/api/v1/zwave/config", headers=headers)
+    assert res.status_code == 200
+    assert "supersecret" not in res.text
+    assert "user" not in res.text
+    assert res.json()["host_configured"] is True
+
+
+@pytest.mark.asyncio
+async def test_config_requires_auth(client: AsyncClient) -> None:
+    res = await client.get("/api/v1/zwave/config")
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_enable_sync_without_host_rejected(
+    client: AsyncClient, headers: dict, _restore_zwave_env
+) -> None:
+    settings.zwave_mqtt_host = ""
+    res = await client.post(
+        "/api/v1/zwave/config",
+        json={"sync_enabled": True, "sync_interval": 600},
+        headers=headers,
+    )
+    assert res.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_save_config_persists_only_sync_fields(
+    client: AsyncClient, headers: dict, _restore_zwave_env
+) -> None:
+    settings.zwave_mqtt_host = "broker"
+    saved: dict = {}
+    with patch.object(type(settings), "save_overrides", lambda self: saved.update(
+        host=self.zwave_mqtt_host, enabled=self.zwave_sync_enabled,
+        interval=self.zwave_sync_interval,
+    )), patch("app.api.routes.zwave.set_zwave_sync_enabled"), \
+            patch("app.api.routes.zwave.reschedule_zwave_sync"):
+        res = await client.post(
+            "/api/v1/zwave/config",
+            json={"mqtt_host": "attacker", "sync_enabled": True, "sync_interval": 900},
+            headers=headers,
+        )
+    assert res.status_code == 200
+    assert settings.zwave_mqtt_host == "broker"  # body host ignored
+    assert saved == {"host": "broker", "enabled": True, "interval": 900}
+
+
+@pytest.mark.asyncio
+async def test_sync_now_creates_scan_run(
+    client: AsyncClient, headers: dict, _restore_zwave_env
+) -> None:
+    settings.zwave_mqtt_host = "broker"
+    with patch("app.api.routes.zwave._background_zwave_import", new_callable=AsyncMock):
+        res = await client.post("/api/v1/zwave/sync-now", headers=headers)
+    assert res.status_code == 200
+    data = res.json()
+    assert data["kind"] == "zwave"
+    assert data["status"] == "running"
+
+
+@pytest.mark.asyncio
+async def test_sync_now_rejected_without_host(
+    client: AsyncClient, headers: dict, _restore_zwave_env
+) -> None:
+    settings.zwave_mqtt_host = ""
+    res = await client.post("/api/v1/zwave/sync-now", headers=headers)
+    assert res.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_sync_now_requires_auth(client: AsyncClient) -> None:
+    res = await client.post("/api/v1/zwave/sync-now")
+    assert res.status_code == 401

docs/logo/icon-inline.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 82" width="64" height="82" fill="none">
+  <defs>
+    <radialGradient id="bg-glow" cx="50%" cy="35%" r="55%">
+      <stop offset="0%" stop-color="#00d4ff" stop-opacity="0.08"/>
+      <stop offset="100%" stop-color="#0d1117" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="node-glow">
+      <feGaussianBlur stdDeviation="1.5" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+  <circle cx="32" cy="32" r="32" fill="#0d1117"/>
+  <circle cx="32" cy="32" r="32" fill="url(#bg-glow)"/>
+  <path d="M32 11 L53 30 L48 30 L48 53 L16 53 L16 30 L11 30 Z"
+        fill="#161b22" stroke="#00d4ff" stroke-width="1.5" stroke-linejoin="round"/>
+  <line x1="16" y1="30" x2="48" y2="30" stroke="#00d4ff" stroke-width="0.5" opacity="0.25"/>
+  <rect x="27" y="40" width="10" height="13" rx="1.5"
+        fill="#0d1117" stroke="#00d4ff" stroke-width="1" opacity="0.9"/>
+  <line x1="32" y1="23" x2="32" y2="30" stroke="#a855f7" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="21" y1="38" x2="29" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="43" y1="38" x2="35" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <circle cx="32" cy="33" r="5" fill="#00d4ff" opacity="0.12"/>
+  <circle cx="32" cy="33" r="3" fill="#00d4ff" filter="url(#node-glow)"/>
+  <circle cx="21" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+  <circle cx="43" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+  <circle cx="32" cy="23" r="2" fill="#a855f7" filter="url(#node-glow)"/>
+</svg>

docs/oidc-auth.md

@@ -0,0 +1,192 @@
+# OpenID Connect (OIDC) Authentication
+
+Homelable can delegate login to your own identity provider (IdP) instead of the
+built-in username/password. Sign-in uses the standard **Authorization Code flow
+with PKCE**: the browser is redirected to your IdP, and on return Homelable
+issues its own short-lived session cookie. Provider access/ID tokens are
+exchanged server-side and **never** reach the browser.
+
+Use it when you want single sign-on, per-user accounts managed at the IdP, MFA,
+or central account revocation — Authentik, Keycloak, Authelia, Zitadel, Google,
+Microsoft Entra ID, Okta, or any spec-compliant OpenID Connect provider.
+
+> 🔒 **Server-dependent feature** — requires the Homelable backend. It is hidden
+> in the no-backend standalone/demo build, which has no login at all.
+
+---
+
+## How it works
+
+1. Homelable exposes its mode at `GET /api/v1/auth/config`. In OIDC mode the
+   login screen shows **Sign in with OpenID Connect**.
+2. `GET /api/v1/auth/oidc/login` redirects to your IdP with `state`, `nonce`,
+   and a PKCE `code_challenge` (S256).
+3. The IdP authenticates the user and redirects back to
+   `GET /api/v1/auth/oidc/callback`.
+4. Homelable validates the response (signature via the IdP's JWKS, issuer,
+   audience, expiry, `nonce`, `state`, PKCE) and mints its **own** session token.
+5. That token is stored in a `__Host-`, `HttpOnly`, `Secure`, `SameSite=Lax`
+   cookie. The browser never sees the provider tokens.
+
+The display name shown in the app is the first present of
+`preferred_username` → `name` → `email` → `sub`.
+
+Local Bearer authentication and the MCP service key keep working unchanged, so
+the API and the MCP server are unaffected.
+
+---
+
+## Prerequisites
+
+1. A reachable **OpenID Connect** provider with a discovery document
+   (`.well-known/openid-configuration`).
+2. Homelable served over **HTTPS** in production (required for the secure
+   session cookie).
+3. A **confidential** OIDC client (client id **and** secret) registered at the
+   IdP, with Homelable's callback URL allow-listed as a redirect URI.
+
+---
+
+## Configuration
+
+All settings live in `.env` (see `.env.example`). Switching to OIDC is
+exclusive — it replaces local login. Existing installs stay on
+`AUTH_MODE=local` until you change this.
+
+```env
+AUTH_MODE=oidc
+
+# Pin CORS to the exact browser origin(s). Wildcard is rejected in OIDC mode.
+CORS_ORIGINS=["https://homelable.example"]
+
+# From your IdP:
+OIDC_DISCOVERY_URL=https://idp.example/application/o/homelable/.well-known/openid-configuration
+OIDC_CLIENT_ID=homelable
+OIDC_CLIENT_SECRET=replace-with-a-secret
+
+# Must EXACTLY match a redirect URI registered at the IdP.
+OIDC_REDIRECT_URI=https://homelable.example/api/v1/auth/oidc/callback
+
+OIDC_SCOPES="openid profile email"
+OIDC_COOKIE_SECURE=true
+OIDC_SESSION_EXPIRE_MINUTES=480
+OIDC_TRANSACTION_EXPIRE_SECONDS=600
+```
+
+Then restart the backend (`docker compose restart backend`).
+
+### Reference
+
+| Variable | Required | Default | Notes |
+|---|---|---|---|
+| `AUTH_MODE` | yes | `local` | Set to `oidc` to enable. |
+| `OIDC_DISCOVERY_URL` | yes | — | The IdP's `.well-known/openid-configuration` URL. |
+| `OIDC_CLIENT_ID` | yes | — | Confidential client id. |
+| `OIDC_CLIENT_SECRET` | yes | — | Client secret. Keep it out of Git and Compose YAML. |
+| `OIDC_REDIRECT_URI` | yes | — | Must equal the registered redirect **exactly**, path included. |
+| `OIDC_SCOPES` | no | `openid profile email` | Must contain `openid`. |
+| `OIDC_COOKIE_SECURE` | no | `true` | `true` requires an HTTPS redirect URI and enables the `__Host-` cookie prefix. Set `false` only for local HTTP testing. |
+| `OIDC_SESSION_EXPIRE_MINUTES` | no | `480` | App session lifetime (5–1440). |
+| `OIDC_TRANSACTION_EXPIRE_SECONDS` | no | `600` | Lifetime of the short login-flow cookie holding `state`/`nonce`/PKCE (60–3600). |
+| `SECRET_KEY` | yes | — | Must be **≥ 32 bytes** in OIDC mode. Generate: `python3 -c "import secrets; print(secrets.token_hex(32))"`. |
+| `CORS_ORIGINS` | yes | — | Exact browser origin(s). `*` is rejected in OIDC mode. |
+
+### Fail-closed validation
+
+The backend refuses to start in OIDC mode unless the configuration is complete
+and safe. It errors if any of the following is true:
+
+- any of `OIDC_DISCOVERY_URL`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`,
+  `OIDC_REDIRECT_URI` is missing;
+- `SECRET_KEY` is shorter than 32 bytes;
+- `OIDC_SCOPES` does not contain `openid`;
+- `OIDC_DISCOVERY_URL` or `OIDC_REDIRECT_URI` is not an HTTP(S) URL;
+- `OIDC_COOKIE_SECURE=true` but `OIDC_REDIRECT_URI` is not HTTPS;
+- `CORS_ORIGINS` contains `*`.
+
+---
+
+## Provider setup
+
+The callback URL to register everywhere is:
+
+```
+https://<your-host>/api/v1/auth/oidc/callback
+```
+
+### Authentik
+
+1. **Applications → Providers → Create → OAuth2/OpenID Provider.**
+2. Client type **Confidential**; add the redirect URI above.
+3. Note the client id/secret and the discovery URL:
+   `https://authentik.example/application/o/<app-slug>/.well-known/openid-configuration`.
+4. Create an **Application** bound to that provider.
+
+### Keycloak
+
+1. In your realm: **Clients → Create client** (OpenID Connect), **Client
+   authentication ON** (confidential).
+2. Set **Valid redirect URIs** to the callback URL.
+3. Discovery URL:
+   `https://kc.example/realms/<realm>/.well-known/openid-configuration`.
+4. Copy the secret from the **Credentials** tab.
+
+### Authelia
+
+1. Add Homelable to the `identity_providers.oidc.clients` list with a
+   `client_secret`, the redirect URI, and scopes `openid profile email`.
+2. Discovery URL: `https://auth.example/.well-known/openid-configuration`.
+
+### Google
+
+1. **Google Cloud Console → APIs & Services → Credentials → OAuth client ID**
+   (type *Web application*).
+2. Add the callback URL under **Authorized redirect URIs** (Google requires
+   HTTPS).
+3. Discovery URL: `https://accounts.google.com/.well-known/openid-configuration`.
+
+Any other spec-compliant provider works the same way — point
+`OIDC_DISCOVERY_URL` at its discovery document.
+
+---
+
+## Behind a reverse proxy
+
+Homelable derives the redirect target from `OIDC_REDIRECT_URI`, so set it to the
+**public** HTTPS URL your users reach — not the internal container address. Make
+sure the proxy:
+
+- terminates TLS and forwards `/api/v1/auth/oidc/*` to the backend;
+- passes the original `Host` and `X-Forwarded-Proto` headers;
+- does not strip the `Cookie` / `Set-Cookie` headers on those routes.
+
+---
+
+## Logout & sessions
+
+- **Logout** clears the Homelable session cookie (`POST /api/v1/auth/logout`).
+- Sessions are stateless JWTs signed with `SECRET_KEY`; there is no server-side
+  revocation, so a session stays valid until `OIDC_SESSION_EXPIRE_MINUTES`
+  elapses. Keep the lifetime modest for sensitive deployments.
+- Logout is local to Homelable; it does not sign the user out at the IdP.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause / fix |
+|---|---|
+| IdP shows `redirect_uri_mismatch` | `OIDC_REDIRECT_URI` must equal the registered URI **exactly**, including scheme, host, port and the `/api/v1/auth/oidc/callback` path. |
+| `OIDC authentication failed` (401) after IdP login | Wrong client secret, `openid` missing from scopes, or clock skew breaking `nonce`/`exp` — sync server time (NTP). |
+| Logged out immediately / cookie not set | `OIDC_COOKIE_SECURE=true` while serving over HTTP. Serve HTTPS, or set `OIDC_COOKIE_SECURE=false` for local testing only. |
+| `403 CSRF validation failed` on save/actions | The request `Origin` is not in `CORS_ORIGINS`, or a stale tab is missing the CSRF token — reload the page. |
+| Backend won't start in OIDC mode | Re-read the error: a required `OIDC_*` value is missing, `SECRET_KEY` < 32 bytes, `CORS_ORIGINS` has `*`, or the redirect isn't HTTPS while the cookie is secure. |
+| Login button doesn't appear | `AUTH_MODE` is still `local`, or the frontend can't reach `/api/v1/auth/config` — check the proxy and `CORS_ORIGINS`. |
+
+---
+
+## Reverting to local auth
+
+Set `AUTH_MODE=local` (or remove it) and restart the backend. The
+`AUTH_USERNAME` / `AUTH_PASSWORD_HASH` login is restored; the `OIDC_*` values are
+ignored while in local mode.

docs/proxmox-import.md

@@ -0,0 +1,176 @@
+# Proxmox VE Import
+
+This feature connects Homelable to your Proxmox VE host, reads the inventory over
+the Proxmox REST API, and drops your hosts, VMs and LXC containers onto the canvas
+as typed nodes — with names, run state and hardware specs. It can also **sync**
+on a schedule so the canvas keeps up with your cluster, and it **merges** with
+devices already discovered by a network scan (a VM whose guest IP was already
+scanned is updated in place, not duplicated).
+
+> 🔒 **Server-dependent feature** — requires the Homelable backend. It is hidden
+> in the no-backend standalone/demo build.
+
+---
+
+## Feature Overview
+
+- **API-based discovery** — Reads `/api2/json` from Proxmox VE using a read-only API token.
+- **Typed nodes** — Devices map to existing Homelable node types:
+  - `proxmox` — a Proxmox host / cluster member (becomes a parent)
+  - `vm` — a QEMU/KVM virtual machine
+  - `lxc` — an LXC container
+- **Hierarchy** — Each host is linked to its VMs/LXC with a `virtual` edge.
+- **Hardware specs** — vCPU count, RAM and disk size are imported as node properties (CPU Cores, RAM, Disk), hidden by default — toggle them on from the right panel.
+- **Guest IPs** — QEMU IPs come from the guest agent (when installed); LXC IPs are parsed from the container's static `net0` config.
+- **Merge / sync** — Re-importing updates existing devices in place and never deletes anything. A guest IP matching a previously scanned node merges onto it.
+- **Auto-sync** — Optional scheduled re-import into the pending inventory.
+
+---
+
+## Prerequisites
+
+1. A reachable **Proxmox VE** host (default API port `8006`).
+2. A **Proxmox API token** with a read-only role (see below).
+3. (Optional, for QEMU guest IPs) the **QEMU guest agent** installed in your VMs.
+
+### Create an API token
+
+In the Proxmox web UI:
+
+1. **Datacenter → Permissions → API Tokens → Add**.
+2. Pick a **User** (e.g. `root@pam`, or better a dedicated `homelable@pve` user).
+3. Give the token an **ID** (e.g. `homelable`). The full token id is then
+   `user@realm!tokenid` — for example `root@pam!homelable`.
+4. Leave **Privilege Separation** checked (recommended) and click **Add**.
+5. **Copy the secret now** — Proxmox shows it only once.
+
+Grant the token (or its user) a **read-only** role:
+
+1. **Datacenter → Permissions → Add → API Token Permission**.
+2. Path `/`, select your token, Role **`PVEAuditor`**, enable **Propagate**.
+
+`PVEAuditor` is read-only — Homelable never needs write access.
+
+### Where the token is stored
+
+The token is a real credential and is treated as one:
+
+- For a **one-off import**, type the token into the import dialog. It is sent with
+  that request only and is **never stored**.
+- For **auto-sync** (which runs with no user present), configure the token on the
+  **server** via environment variables (below). It is read from `.env`, kept in
+  memory.
+
+```env
+# backend/.env
+PROXMOX_TOKEN_ID=root@pam!homelable
+PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+PROXMOX_HOST=192.168.1.10          # optional default for auto-sync
+PROXMOX_PORT=8006
+PROXMOX_VERIFY_TLS=true            # set false only for self-signed certs
+```
+
+---
+
+## Step-by-step Usage
+
+### 1. Open the Proxmox Import dialog
+
+Click **Proxmox Import** in the left sidebar (below "Z-Wave Import").
+
+### 2. Configure the connection
+
+| Field | Default | Description |
+|---|---|---|
+| Proxmox Host | — | IP or hostname of the Proxmox host |
+| Port | 8006 | Proxmox API port |
+| Token ID | _(optional)_ | `user@realm!tokenid`; leave blank to use the server token |
+| Token Secret | _(optional)_ | The token secret; leave blank to use the server token |
+| Verify TLS | on | Uncheck for self-signed certificates |
+
+### 3. Test the connection (optional)
+
+Click **Test Connection**. A green indicator confirms reachability + a valid token;
+red shows a sanitized error.
+
+### 4. Choose an import target
+
+- **Pending section** — Devices are queued in the Device Inventory for review
+  (and tracked as a scan run in Scan History). Approve, hide, or delete each.
+- **Canvas directly** — Devices are fetched and shown grouped in the dialog so you
+  can pick which ones to add immediately.
+
+### 5. Fetch inventory
+
+Click **Import to Pending** (or **Fetch Inventory** in canvas mode). Homelable will:
+1. Query `/nodes` for hosts
+2. Query `/qemu` and `/lxc` per host
+3. Resolve guest IPs (agent for QEMU, `net0` for LXC) best-effort
+4. Return hosts + guests grouped by type
+
+### 6. Select and add to canvas
+
+(Canvas mode) Devices are grouped by type (Hosts / Virtual Machines / LXC
+Containers). Use the checkboxes to pick which to add, then **Add N to Canvas**.
+
+### 7. Arrange on the canvas
+
+Nodes are placed in a grid; host→guest `virtual` edges connect them. Use
+**Auto Layout** or drag nodes manually.
+
+---
+
+## Node Type Mapping
+
+| Proxmox (`/api2/json`) | Homelable type | Notes |
+|---|---|---|
+| `/nodes` (host) | `proxmox` | Becomes the parent, linked to its guests |
+| `/nodes/{node}/qemu/{vmid}` | `vm` | Guest-agent IP when available |
+| `/nodes/{node}/lxc/{vmid}` | `lxc` | Static `net0` IP when set |
+| `status` running/stopped | node status online/offline | |
+| `maxcpu` | CPU Cores property | hidden by default |
+| `maxmem` | RAM property (GB) | hidden by default |
+| `maxdisk` | Disk property (GB) | hidden by default |
+| VMID + host | synthetic identity (`pve-{host}-{vmid}`) | stable across re-imports |
+
+Guest hierarchy is rendered as `virtual` edges (host ↔ VM/LXC).
+
+---
+
+## Auto-sync configuration
+
+1. Configure `PROXMOX_TOKEN_ID` / `PROXMOX_TOKEN_SECRET` (and optionally
+   `PROXMOX_HOST`) in `backend/.env` and restart the backend.
+2. Open **Settings** — a **Proxmox auto-sync** section appears once a server token
+   is configured.
+3. Toggle **Auto-sync Proxmox inventory** and set the interval (min 300 s).
+
+On each run, Homelable re-imports the inventory into the pending section:
+- New VMs/LXC appear as **pending** for review.
+- Existing devices are **updated in place** (status, specs, IP).
+- Nothing is ever deleted — a VM removed from Proxmox is left on your canvas.
+
+
+---
+
+## Supported Versions
+
+Works with the Proxmox VE 7.x / 8.x REST API (`/api2/json`). No extra Proxmox
+plugins are required.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| "Authentication failed" | Bad token id/secret or missing role | Re-check the token; grant `PVEAuditor` at `/` |
+| "TLS verification failed" | Self-signed certificate | Uncheck **Verify TLS** (labs only) |
+| "Proxmox host could not be resolved" | DNS/hostname wrong | Use the IP or a resolvable name |
+| "No API token provided and none configured" | No token in the form and none in `.env` | Enter a token or set the server env vars |
+| VMs have no IP | No guest agent (QEMU) / DHCP-only LXC | Install the QEMU guest agent; static IPs are read from `net0` |
+| Duplicate-looking node | Same guest under a different identity | Re-import merges by IP/VMID; report if it persists |
+
+---
+
+

docs/rack-canvas.md

@@ -0,0 +1,247 @@
+# Rack Canvas
+
+A rack canvas is the **physical** counterpart to the network diagram: real racks,
+the gear mounted in them, and the patch cables between their ports. It is a
+canvas kind of its own — you create it like any other canvas, and Homelable swaps
+the renderer when you switch to it.
+
+Where the diagram answers *what talks to what*, the rack answers *what is where*:
+which U a machine sits in, what plate it wears, which switch port its uplink
+lands on.
+
+> Works with **and** without the backend. In the no-backend standalone/demo build
+> a rack canvas persists to your browser's local storage; the Device Inventory
+> picker and the live status check are backend-only (marked 🔒 below).
+
+---
+
+## Feature Overview
+
+- **Racks** — any U height, 19" or 10" wide, bottom-up or top-down numbering, per-rack frame / rail / interior colours, open or enclosed.
+- **Mounted gear** — a device occupies a U range and part of a 12-column width grid, so half- and third-width machines share a U.
+- **Faceplates** — a visual catalog of plates (servers, switches, routers, patch panels, UPS, PDUs, desktop NAS towers, shelves, blanks, cable managers) drawn as vector artwork that scales with the rack.
+- **Ports & patching** — RJ45 and SFP ports per device, cabled port-to-port by dragging from one to the other, across racks if needed.
+- **Device Inventory** 🔒 — a mount points at a real inventory entry, so a rack shows the same devices your scans found, and gear you rack by hand joins that inventory.
+- **Live status** 🔒 — a mount can follow the status check already configured on the matching diagram node, and light its plate LED accordingly.
+- **Import links** 🔒 — derive patches from the physical links already drawn on your diagrams, as often as you like.
+
+---
+
+## Create a rack canvas
+
+1. Open the **canvas switcher** at the top of the left sidebar.
+2. Click **New Canvas**.
+3. Under **Kind**, pick **Rack** (the other kind, *Diagram*, is the usual node/link canvas).
+4. Name it, pick an icon, and create.
+
+A canvas cannot change kind afterwards — a diagram and a rack store different
+things. Deleting a rack canvas deletes its racks, mounts and cables with it;
+duplicating a canvas duplicates them too.
+
+---
+
+## Add a rack
+
+**Add Rack** in the header drops a new rack on the canvas. Drag it anywhere; a
+canvas can hold as many as you like, and cables can run between them.
+
+**Double-click the rack chrome** (the frame, not a device) to open its settings:
+
+| Setting | What it does |
+|---|---|
+| Name / Location | Free text — "Baie salon", "Garage", … |
+| U height | How many mountable U the rack has (42 by default). |
+| Width | 19" or 10" — drives the drawn inner width. |
+| Numbering | `bottom-up` or `top-down`. **Labels only** — gear never moves. |
+| Show U numbers | Print the U scale on the rails. |
+| Enclosed | Draw side panels / a closed chassis. |
+| Colours | Frame, rails and interior. Defaults come from your app theme. |
+| Delete | Removes the rack and everything mounted in it. |
+
+---
+
+## Mount a device
+
+Click **+ Device** in the left sidebar, or drag an accessory from the sidebar
+tray straight onto a rack. The device modal offers three sources:
+
+- **Device Inventory entry** 🔒 — pick something already discovered. The field
+  opens the real Device Inventory, with its search, source and type filters, and
+  it opens pre-filtered to **rackable** hardware (no light bulbs, no sockets).
+  A device already mounted on this canvas is refused.
+- **New device** — for hardware no scan can find (a patch panel, a PDU, an
+  unmanaged switch). It is created as a normal Device Inventory entry tagged
+  **Rack devices**, so you can search, filter, hide and delete it like any other.
+- **Accessory** — rack-only furniture: blanking plate, shelf, cable manager.
+  These are not devices and never appear in the inventory.
+
+Then set:
+
+| Field | Notes |
+|---|---|
+| Label | Shown on the plate. |
+| Faceplate | Opens the visual catalog — see below. |
+| U position / height | `U` is counted **from the bottom rail**, whatever the numbering setting prints. |
+| Column / width | Full, half, third, sixth or quarter of the rack width. |
+| Status | A fixed colour, or **Check device** 🔒 — see below. |
+| Colour | Overrides the plate's default tint. |
+| Ports | The list of RJ45 / SFP ports, seeded by the faceplate and editable afterwards. |
+
+**Double-click a plate** to reopen this modal on an existing mount; a single
+click only selects it. **Unmount** takes the device out of the rack — it stays in
+the Device Inventory.
+
+### Linked device 🔒
+
+Under the port list, a mount that stands for a real device prints what is known
+about that box: name, type, hostname, IP, MAC, OS, the status check it runs, the
+canvas it is drawn on, when it was last seen, and the services discovery
+fingerprinted on it.
+
+It is read-only — edit those facts in the Device Inventory or on the logical
+canvas, not in the rack — and an accessory shows nothing at all. A device that is
+on no diagram still prints everything discovery found about it; only the
+canvas-side lines go missing, and the panel says *Not on a logical canvas.*
+
+**Link to another device…** points the plate at a different Device Inventory
+entry — the whole inventory, not just the devices you approved onto a diagram.
+Use it when you created the gear from the rack (the entry starts empty, with just
+a name) or when the plate ended up on the wrong twin of two look-alike hosts. The
+plate takes the entry's IP, MAC, services, status and — unless you renamed it —
+its name, **Check device** becomes available if that device is on a diagram, and
+the link is saved with the rest of the canvas. A device already mounted elsewhere
+in the design is not offered: one entry, one plate. The empty placeholder the
+rack created for the plate is removed from the inventory once nothing uses it.
+
+### Placement rules
+
+- A drop **snaps to the nearest free slot**; a placement that cannot work
+  previews in red.
+- Drag a mounted device inside its rack to move it — same snapping.
+- **Growing** a device, by hand or by picking a taller plate, relocates it to the
+  nearest slot that takes the new size. Only a rack with no such slot refuses the
+  edit, and it tells you so.
+
+---
+
+## Faceplates
+
+The **Faceplate** field opens a catalog, not a dropdown of names: every plate is
+drawn with the real renderer, at its real relative width and U height, grouped by
+family and searchable.
+
+| Family | Examples |
+|---|---|
+| Servers | 1U, 1U with drive bays, 2U with bays, 4U storage, half-width SFF, third-width mini PC |
+| Network | 8 / 24 / 48-port switches, 1U router |
+| Patch | 24-port copper panel, 12-port fibre panel |
+| Storage | 2U NAS, desktop NAS towers in 2, 4 and 5 bays |
+| Power | 2U UPS, 1U PDU |
+| Accessories | Blanking plate, shelf, cable manager |
+
+Picking a plate **reseeds the ports** it comes with; your own port edits are kept
+until you change plate again. Plates are drawn as vector artwork in relative
+coordinates, so they stay correct at any rack width and U height, and their
+colours follow the active app theme.
+
+---
+
+## Ports and patching
+
+Ports are **RJ45** or **SFP/SFP+**, drawn as real jack artwork at a fixed size so
+plates of different heights line up. Power outlets are artwork only — they are
+never a cable endpoint.
+
+Patch-facing gear (switches, patch panels) shows its ports permanently;
+everything else reveals them on hover, on selection, or when cables are shown.
+
+To cable:
+
+1. Click **Patch** in the header.
+2. **Drag from one port to another** — a dashed rubber band follows the pointer.
+   Clicking the two ports in turn works just as well. **Escape** drops a
+   half-drawn patch.
+3. Repeat. One cable per port; copper or fibre follows the port you start from.
+4. Click **Exit patching** when done — the canvas returns to the cable visibility
+   it had before.
+
+To unplug: **click the cable** (it gets an accent halo), then press
+**Delete/Backspace** or click **Unplug** in the header. A stray click never
+destroys a patch.
+
+A header select controls what you see: cables **on hover**, **always**, or
+**hidden**. Cables
+pan and zoom with the canvas and may run from one rack to another. A cable you
+have selected stays drawn whatever that select says.
+
+### Documenting a cable
+
+**Click a cable** — patching or not — and a panel opens on the right:
+
+| Field | What it does |
+|---|---|
+| Endpoints | The two devices and ports the run connects. Read-only: move a patch by unplugging it and drawing it again. |
+| Type | Ethernet or fibre. A cable still wearing its type's default colour is recoloured to match; a colour you picked yourself is kept. |
+| Colour | The sheath colours you actually have on the shelf, plus a free hex field for anything else. |
+| Label | A name for the run — "Uplink to core", a patch-panel reference. **Show on canvas** prints it next to the cable. |
+| Properties | Anything else worth recording: length, VLAN, speed, category, patch reference. Same editor as a node's properties on a diagram — a label, a value, an optional icon, and an eye that decides whether it shows on the canvas. |
+| Unplug cable | Removes the patch. The devices and their ports stay. |
+
+What you tick as visible is drawn on a small plate at the middle of the run, so a
+rack photo exports with its cable lengths and VLANs on it. Everything else stays
+in the panel, one click away.
+
+### Import links 🔒
+
+**Import links** derives patches from the physical links (ethernet, fibre, vlan,
+cluster) already drawn on your diagrams, matching both ends to mounts that point
+at those nodes. Run it as often as you like: a pair of devices already cabled
+is left alone, so a second run after racking more gear only adds what is
+missing.
+
+---
+
+## Status 🔒
+
+A mount's **Status** is either pinned by hand (online / offline / unknown) or set
+to **Check device**: the plate then follows the status check already configured
+on the matching diagram node (ping, HTTP, SSH, …) and its LED lights accordingly.
+
+The rack runs no checker of its own — it reads the result of the one your diagram
+already performs. So:
+
+- **Check device** is only offered when the mount resolves to a diagram node.
+- Losing that link drops the mount back to `unknown`, rather than leaving it on a
+  status nothing answers for.
+- The refresh polls every 60 s, and only while at least one mount is on
+  **Check device**.
+
+---
+
+## Saving
+
+Like the diagram canvas, a rack canvas is **saved explicitly** — **Save Rack** in
+the left sidebar, or the header's save button. Nothing is written behind your
+back unless you turn on **Autosave** in Settings.
+
+The sidebar footer counts racks, mounts, cables and free U instead of the
+diagram's online/offline tally. **PNG export** works here too.
+
+---
+
+## Known limits
+
+- **Front view only** — no rear view, no half-depth pairing.
+- No 0U side-mounted PDU.
+- No power draw or outlet budgeting.
+- No undo/redo on a rack canvas (the diagram canvas keeps its own).
+- Rack canvases are not shown by the read-only [Live View](../README.md#live-view-read-only-public-canvas).
+- The MCP server exposes diagram nodes and links only, not racks.
+
+---
+
+## See also
+
+- [FEATURES.md](../FEATURES.md) — every feature, one page.
+- [Device Inventory](../FEATURES.md#12-device-inventory-) — where racked devices live.
+- `frontend/src/rack/README.md` — the developer reference for this canvas.

docs/zwave-import.md

@@ -0,0 +1,161 @@
+# Z-Wave (Z-Wave JS UI) Network Map Importer
+
+This feature lets you connect Homelable to your MQTT broker, fetch the Z-Wave node list from **Z-Wave JS UI** (formerly `zwavejs2mqtt`), and drop all Z-Wave devices onto the canvas as typed nodes with proper hierarchy.
+
+It mirrors the [Zigbee2MQTT importer](./zigbee-import.md): same MQTT request/response pattern, same node-type model, same canvas behaviour.
+
+---
+
+## Feature Overview
+
+- **Automatic device discovery** — Requests the node list from the Z-Wave JS UI MQTT gateway API and parses the full device list
+- **Typed nodes** — Devices are mapped to three homelable node types:
+  - `zwave_coordinator` — The Z-Wave controller (hub)
+  - `zwave_router` — Mains-powered / routing nodes
+  - `zwave_enddevice` — Battery-powered end devices (sensors, locks, etc.)
+- **Hierarchy** — `parent_id` is set automatically: controller → routers → end devices, derived from each node's neighbor list
+- **IoT edges** — Links between devices are added as `IoT / Zigbee` edge type
+- **Import targets** — Send discovered devices to the **Pending** section (review before adding) or drop them on the **Canvas** directly
+
+> **Note:** Z-Wave does not expose an LQI value the way Zigbee does, so the LQI property is omitted. (RSSI may be surfaced in a future release.)
+
+---
+
+## Prerequisites
+
+1. A running **MQTT broker** (e.g. Mosquitto) accessible from your Homelable host
+2. **Z-Wave JS UI** connected to the broker with the **MQTT gateway** enabled
+3. The gateway must respond to `getNodes` requests on:
+   - **Request topic:** `<prefix>/_CLIENTS/ZWAVE_GATEWAY-<gateway>/api/getNodes/set`
+   - **Response topic:** `<prefix>/_CLIENTS/ZWAVE_GATEWAY-<gateway>/api/getNodes`
+   - The default prefix is `zwave` and the default gateway name is `zwavejs2mqtt`
+
+---
+
+## Step-by-step Usage
+
+### 1. Open the Z-Wave Import dialog
+
+Click **Z-Wave Import** in the left sidebar (below "Zigbee Import").
+
+### 2. Configure the MQTT connection
+
+| Field | Default | Description |
+|---|---|---|
+| Broker Host | — | IP or hostname of your MQTT broker |
+| Port | 1883 | MQTT broker port (auto-switches to 8883 when TLS is enabled) |
+| MQTT Prefix | `zwave` | Z-Wave JS UI MQTT prefix (Settings → MQTT → "Prefix") |
+| Gateway Name | `zwavejs2mqtt` | Z-Wave JS UI gateway name (Settings → MQTT → "Name") |
+| Username | _(optional)_ | MQTT username if authentication is enabled |
+| Password | _(optional)_ | MQTT password |
+| Use TLS | off | Connect over TLS (typically port 8883) |
+| Skip cert verify | off | Accept self-signed certificates (TLS only) |
+
+> The **Prefix** and **Gateway Name** together form the MQTT topic the importer talks to. They must match your Z-Wave JS UI **Settings → MQTT** configuration exactly, or the request will time out.
+
+### 3. Test the connection (optional)
+
+Click **Test Connection** to verify broker reachability before fetching devices.
+A green indicator confirms success; red shows the error message from the broker.
+
+### 4. Choose an import target
+
+Pick where discovered devices should go:
+
+- **Pending section** — Devices are queued for review in the Pending list (and tracked as a scan run in Scan History). The controller is auto-approved as a canvas node; the rest wait for you to approve, hide, or delete them.
+- **Canvas directly** — Devices are fetched and shown grouped in the dialog so you can pick which ones to add immediately.
+
+### 5. Fetch devices
+
+Click **Import to Pending** (or **Fetch Devices** in canvas mode). Homelable will:
+1. Connect to the broker
+2. Subscribe to the response topic
+3. Publish a `getNodes` request to the gateway request topic
+4. Wait for the node-list response
+5. Parse and group devices by type
+
+### 6. Select and add to canvas
+
+(Canvas mode) Devices are grouped by type (Controller / Router / End Device).
+Use the checkboxes to select which devices to add, then click **Add N to Canvas**.
+
+> **Tip:** All devices are selected by default. Uncheck any you don't want.
+
+### 7. Arrange on the canvas
+
+Devices are placed in a grid at the top-right of the canvas.
+Use **Auto Layout** (toolbar) to re-arrange the full canvas, or drag nodes manually.
+
+---
+
+## Node Type Mapping
+
+The importer reads each Z-Wave node's role flags from the gateway and maps them as follows:
+
+| Z-Wave JS UI flag | homelable type | Role label |
+|---|---|---|
+| `isControllerNode` | `zwave_coordinator` | Controller |
+| `isRouting` | `zwave_router` | Router |
+| _(everything else)_ | `zwave_enddevice` | EndDevice |
+
+Each node keeps its name (`name` → `loc` → `Node <id>` fallback), vendor (`manufacturer`), and model (`productLabel` / `productDescription`) where available.
+
+---
+
+## MQTT Configuration Tips
+
+### Mosquitto without authentication
+
+```
+listener 1883
+allow_anonymous true
+```
+
+### Mosquitto with password file
+
+```
+listener 1883
+password_file /etc/mosquitto/passwd
+```
+
+Create a user:
+```bash
+mosquitto_passwd -c /etc/mosquitto/passwd <username>
+```
+
+### Z-Wave JS UI MQTT settings
+
+In **Settings → MQTT**, make sure the gateway is enabled and note these two values — they must match the importer fields:
+
+| Z-Wave JS UI setting | Importer field | Default |
+|---|---|---|
+| Name | Gateway Name | `zwavejs2mqtt` |
+| Prefix | MQTT Prefix | `zwave` |
+| Host / Port | Broker Host / Port | `localhost` / `1883` |
+
+The gateway must be in **"Named topics"** mode (the default) so the `getNodes` API topic is exposed.
+
+---
+
+## Supported Versions
+
+The `getNodes` MQTT gateway API is provided by **Z-Wave JS UI** (and its predecessor `zwavejs2mqtt`). Any recent release with the MQTT gateway enabled is supported.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| "Connection refused" | Broker unreachable | Check host/port, firewall rules |
+| "Timed out waiting for response" | Gateway not running, or wrong prefix/gateway name | Verify Z-Wave JS UI is connected to MQTT; match **Prefix** and **Gateway Name** to Settings → MQTT |
+| 0 devices returned | No nodes included in the Z-Wave network | Include at least one device first |
+| "Z-Wave gateway reported failure" | Gateway returned `success: false` | Check the Z-Wave JS UI logs |
+| "Malformed getNodes response" | Gateway returned an unexpected format | Check the Z-Wave JS UI version; open an issue |
+| TLS errors with a self-signed cert | Certificate not trusted | Enable **Use TLS** + **Skip cert verify** |
+
+---
+
+## Screenshots
+
+_(Screenshots will be added in a future release)_

frontend/package.json

@@ -1,13 +1,13 @@
 {
   "name": "frontend",
   "private": true,
-  "version": "2.6.0",
+  "version": "3.2.0",
   "type": "module",
   "scripts": {
     "dev": "vite",
     "build": "tsc -b && vite build",
     "lint": "eslint .",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc -b",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -27,11 +27,10 @@
     "clsx": "^2.1.1",
     "dagre": "^0.8.5",
     "html-to-image": "^1.11.13",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.3.1",
     "next-themes": "^0.4.6",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
-    "shadcn": "^4.0.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
     "tw-animate-css": "^1.4.0",
@@ -60,6 +59,7 @@
     "globals": "^16.5.0",
     "jsdom": "^28.1.0",
     "lucide-react": "^1.7.0",
+    "shadcn": "^4.0.0",
     "tailwindcss": "^4.2.1",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.48.0",

frontend/src/App.tsx

@@ -1,13 +1,14 @@
-import { useEffect, useCallback, useRef, useState } from 'react'
+import { useEffect, useCallback, useMemo, useRef, useState } from 'react'
 import { ReactFlowProvider, type Connection, type Edge } from '@xyflow/react'
 import { type Node } from '@xyflow/react'
 import { applyDagreLayout } from '@/utils/layout'
-import { serializeNode, serializeEdge, deserializeApiNode, deserializeApiEdge, type ApiNode, type ApiEdge } from '@/utils/canvasSerializer'
+import { serializeNode, serializeEdge, deserializeApiNode, deserializeApiEdge, migrateClusterHandles, type ApiNode, type ApiEdge } from '@/utils/canvasSerializer'
 import { generateUUID } from '@/utils/uuid'
 import { getCenteredPosition } from '@/utils/viewportCenter'
 import { resolveVirtualEdgeParent } from '@/utils/virtualEdgeParent'
 import { generateMarkdownTable } from '@/utils/exportMarkdown'
 import { copyToClipboard } from '@/utils/clipboard'
+import { getDesignIdFromUrl, setDesignIdInUrl } from '@/utils/designUrl'
 import { ExportModal } from '@/components/modals/ExportModal'
 import { exportCanvasToYaml, downloadYaml } from '@/utils/exportYaml'
 import { parseYamlToCanvas } from '@/utils/importYaml'
@@ -25,48 +26,104 @@ import { ScanConfigModal } from '@/components/modals/ScanConfigModal'
 import { SettingsModal } from '@/components/modals/SettingsModal'
 import { ZigbeeImportModal } from '@/components/zigbee/ZigbeeImportModal'
 import { ZwaveImportModal } from '@/components/zwave/ZwaveImportModal'
+import { ProxmoxImportModal } from '@/components/proxmox/ProxmoxImportModal'
 import { GroupRectModal, type GroupRectFormData } from '@/components/modals/GroupRectModal'
 import { TextModal, type TextFormData } from '@/components/modals/TextModal'
 import { ThemeModal } from '@/components/modals/ThemeModal'
+import { CustomStyleModal } from '@/components/modals/CustomStyleModal'
 import { SearchModal } from '@/components/modals/SearchModal'
-import { PendingDevicesModal } from '@/components/modals/PendingDevicesModal'
+import { DeviceInventoryModal } from '@/components/modals/DeviceInventoryModal'
 import { ScanHistoryModal } from '@/components/modals/ScanHistoryModal'
 import { ShortcutsModal } from '@/components/modals/ShortcutsModal'
 import { ConfirmAddToGroupModal } from '@/components/modals/ConfirmAddToGroupModal'
 import { useCanvasStore } from '@/stores/canvasStore'
+import { readAutosaveSettings, subscribeAutosaveSettings, type AutosaveSettings } from '@/utils/autosaveSettings'
+import { useAutosave } from '@/hooks/useAutosave'
 import { useDesignStore } from '@/stores/designStore'
 import { useAuthStore } from '@/stores/authStore'
 import { useThemeStore } from '@/stores/themeStore'
 import { canvasApi, designsApi, liveviewApi } from '@/api/client'
+import * as standaloneStorage from '@/utils/standaloneStorage'
 import { demoNodes, demoEdges } from '@/utils/demoData'
+import { decideCanvasLoad, isNewUserCanvas } from '@/utils/canvasLoadDecision'
+import { WalkthroughActionsProvider, type WalkthroughActionApi } from '@/walkthrough/actions'
+import { WalkthroughInvite } from '@/walkthrough/WalkthroughInvite'
+import { WalkthroughOverlay } from '@/walkthrough/WalkthroughOverlay'
+import { DEMO_SCAN_RUNS, DEMO_INVENTORY_DEVICES } from '@/walkthrough/demoTourData'
 import { useStatusPolling } from '@/hooks/useStatusPolling'
-import type { NodeData, EdgeData, CustomStyleDef } from '@/types'
+import { bootstrapAuth } from '@/auth/bootstrap'
+import { RackCanvas } from '@/rack/components/RackCanvas'
+import { RackCablePanel } from '@/rack/components/RackCablePanel'
+import { useRackStore } from '@/rack/store'
+import type { NodeData, EdgeData, CustomStyleDef, DesignType, FloorMapConfig, NodeType } from '@/types'
 import type { ZigbeeNode, ZigbeeEdge } from '@/components/zigbee/types'
 import type { ZwaveNode, ZwaveEdge } from '@/components/zwave/types'
+import type { ProxmoxNode, ProxmoxEdge } from '@/components/proxmox/types'
+import { buildProxmoxClusterEdges } from '@/components/proxmox/clusterEdges'
 
 const STANDALONE = import.meta.env.VITE_STANDALONE === 'true'
-const STANDALONE_STORAGE_KEY = 'homelable_canvas'
 
 export default function App() {
-  const { loadCanvas, markSaved, markUnsaved, selectedNodeId, selectedNodeIds, addNode, updateNode, deleteNode, onConnect, updateEdge, deleteEdge, setProxmoxContainerMode, setNodeZIndex, editingGroupRectId, setEditingGroupRectId, editingTextId, setEditingTextId, nodes, edges, snapshotHistory, undo, redo, addToGroup, addToContainer } = useCanvasStore()
+  const { loadCanvas, applyLayout, markSaved, markUnsaved, hasUnsavedChanges, editSeq, selectedNodeId, selectedNodeIds, addNode, updateNode, deleteNode, onConnect, updateEdge, deleteEdge, setProxmoxContainerMode, setNodeZIndex, editingGroupRectId, setEditingGroupRectId, editingTextId, setEditingTextId, nodes, edges, snapshotHistory, undo, redo, addToGroup, addToContainer, floorMap, setFloorMap } = useCanvasStore()
   const canvasRef = useRef<HTMLDivElement>(null)
-  const { isAuthenticated } = useAuthStore()
+  const { isAuthenticated, isInitialized } = useAuthStore()
+  const authBootstrapStarted = useRef(false)
   const { activeTheme, setTheme, customStyle, setCustomStyle } = useThemeStore()
-  const { activeDesignId, setDesigns, setActiveDesign } = useDesignStore()
+  const { activeDesignId, activeDesignType, setDesigns, setActiveDesign } = useDesignStore()
+  const isRackDesign = activeDesignType === 'rack'
+  const rackDirty = useRackStore((s) => s.hasUnsavedChanges)
+  const rackEditSeq = useRackStore((s) => s.editSeq)
+
+  /** Kind of a design by id, read straight from the store (no stale closure). */
+  const designTypeOf = useCallback(
+    (id: string | null | undefined): DesignType =>
+      useDesignStore.getState().designs.find((d) => d.id === id)?.design_type ?? 'network',
+    [],
+  )
 
   useStatusPolling()
 
+  useEffect(() => {
+    if (STANDALONE || authBootstrapStarted.current) return
+    authBootstrapStarted.current = true
+    void bootstrapAuth()
+  }, [])
+
+  const [autosave, setAutosave] = useState<AutosaveSettings>(readAutosaveSettings)
+  useEffect(() => subscribeAutosaveSettings(setAutosave), [])
+
+  // Provenance: which design the in-memory canvas was loaded as. Differs from
+  // activeDesignId (the selection) during a switch, so autosave gates on this to
+  // avoid writing one design's canvas under another's id. Ref mirror for the
+  // fire-time guard, which must read the live value without re-arming the timer.
+  const [loadedDesignId, setLoadedDesignId] = useState<string | null>(null)
+  const loadedDesignIdRef = useRef<string | null>(loadedDesignId)
+  useEffect(() => { loadedDesignIdRef.current = loadedDesignId }, [loadedDesignId])
+
+  // True while the last canvas load failed (backend down/error). Drives the error
+  // banner and keeps us from masking a real failure with the demo canvas.
+  const [loadError, setLoadError] = useState(false)
+  // True when the loaded canvas is the demo (a brand-new user). Reserved as the
+  // entry signal for the upcoming Getting Started walkthrough.
+  const [isNewUser, setIsNewUser] = useState(false)
+
+  // Getting Started tour: when true, the corresponding modal renders injected demo
+  // data instead of hitting the backend.
+  const [tourScanHistoryDemo, setTourScanHistoryDemo] = useState(false)
+  const [tourInventoryDemo, setTourInventoryDemo] = useState(false)
+
   const [themeModalOpen, setThemeModalOpen] = useState(false)
+  const [styleEditorType, setStyleEditorType] = useState<NodeType | null>(null)
   const [searchOpen, setSearchOpen] = useState(false)
   const [scanHistoryOpen, setScanHistoryOpen] = useState(false)
-  const [pendingModalOpen, setPendingModalOpen] = useState(false)
-  const [pendingModalStatus, setPendingModalStatus] = useState<'pending' | 'hidden'>('pending')
-  const [pendingHighlightId, setPendingHighlightId] = useState<string | undefined>(undefined)
-  const openPendingModal = useCallback((deviceId?: string, status: 'pending' | 'hidden' = 'pending') => {
-    setPendingHighlightId(undefined)
-    setPendingModalStatus(status)
-    setPendingModalOpen(true)
-    if (deviceId) setTimeout(() => setPendingHighlightId(deviceId), 0)
+  const [inventoryModalOpen, setInventoryModalOpen] = useState(false)
+  const [inventoryModalStatus, setInventoryModalStatus] = useState<'pending' | 'hidden'>('pending')
+  const [inventoryHighlightId, setInventoryHighlightId] = useState<string | undefined>(undefined)
+  const openInventoryModal = useCallback((deviceId?: string, status: 'pending' | 'hidden' = 'pending') => {
+    setInventoryHighlightId(undefined)
+    setInventoryModalStatus(status)
+    setInventoryModalOpen(true)
+    if (deviceId) setTimeout(() => setInventoryHighlightId(deviceId), 0)
   }, [])
   const [shortcutsOpen, setShortcutsOpen] = useState(false)
   const [addNodeOpen, setAddNodeOpen] = useState(false)
@@ -82,97 +139,271 @@ export default function App() {
   const [exportModalOpen, setExportModalOpen] = useState(false)
   const [zigbeeImportOpen, setZigbeeImportOpen] = useState(false)
   const [zwaveImportOpen, setZwaveImportOpen] = useState(false)
+  const [proxmoxImportOpen, setProxmoxImportOpen] = useState(false)
 
   // Declare handleSave before the Ctrl+S effect so it is in scope.
   // Returns true on success, false on failure — the design-switch effect relies
   // on this to avoid loading (and clobbering) the canvas when a save fails.
-  const handleSave = useCallback(async (designIdOverride?: string): Promise<boolean> => {
+  const handleSave = useCallback(async (designIdOverride?: string, options?: { silent?: boolean }): Promise<boolean> => {
     try {
       const saveDesignId = designIdOverride ?? activeDesignId
+      // Rack canvases own their own state and persistence path.
+      if (designTypeOf(saveDesignId) === 'rack') {
+        // Named explicitly: the design-switch flow saves the *old* design, and
+        // the store refuses rather than writing under whichever one it holds.
+        const ok = await useRackStore.getState().save(saveDesignId)
+        if (ok) {
+          if (!options?.silent) toast.success('Rack canvas saved')
+        } else {
+          toast.error('Save failed')
+        }
+        return ok
+      }
       if (STANDALONE) {
-        localStorage.setItem(STANDALONE_STORAGE_KEY, JSON.stringify({ nodes, edges, theme_id: activeTheme, custom_style: customStyle }))
+        if (!saveDesignId) return false
+        // Floor plans are backend-only (upload/serve), so standalone never persists one.
+        standaloneStorage.saveCanvas(saveDesignId, { nodes, edges, theme_id: activeTheme, custom_style: customStyle })
         markSaved()
-        toast.success('Canvas saved')
+        if (!options?.silent) toast.success('Canvas saved')
         return true
       }
       const nodesToSave = nodes.map(serializeNode)
       const edgesToSave = edges.map(serializeEdge)
-      await canvasApi.save({ nodes: nodesToSave, edges: edgesToSave, viewport: { theme_id: activeTheme }, custom_style: customStyle, design_id: saveDesignId })
+      const viewport: Record<string, unknown> = { theme_id: activeTheme }
+      if (floorMap) viewport.floor_map = floorMap
+      await canvasApi.save({ nodes: nodesToSave, edges: edgesToSave, viewport, custom_style: customStyle, design_id: saveDesignId })
       markSaved()
-      toast.success('Canvas saved')
+      if (!options?.silent) toast.success('Canvas saved')
       return true
     } catch {
       toast.error('Save failed')
       return false
     }
-  }, [nodes, edges, markSaved, activeTheme, customStyle, activeDesignId])
+  }, [nodes, edges, markSaved, activeTheme, customStyle, activeDesignId, floorMap, designTypeOf])
 
   // Keep a ref so the keydown handler always calls the latest version
   const handleSaveRef = useRef(handleSave)
   useEffect(() => { handleSaveRef.current = handleSave }, [handleSave])
 
+  // Debounced, opt-in autosave. Pins the active design when armed and re-checks
+  // it at fire time so a mid-switch save can't clobber the wrong design.
+  useAutosave({
+    enabled: autosave.enabled,
+    delaySeconds: autosave.delay,
+    hasUnsavedChanges: isRackDesign ? rackDirty : hasUnsavedChanges,
+    designId: loadedDesignId,
+    // Debounce resets on each real user edit (editSeq), not on raw nodes/edges
+    // identity — live status polling churns those arrays without a user edit and
+    // would otherwise keep re-arming (and starving) the timer during monitoring.
+    changeSignals: [isRackDesign ? rackEditSeq : editSeq],
+    getLiveDesignId: () => loadedDesignIdRef.current,
+    onSave: (designId) => { void handleSaveRef.current(designId, { silent: true }) },
+  })
+
   const loadCanvasFromApi = useCallback(async (designId?: string) => {
+    let res
     try {
-      const res = await canvasApi.load(designId)
-      const { nodes: apiNodes, edges: apiEdges } = res.data
-      if (apiNodes.length > 0) {
-        const proxmoxContainerMap = new Map<string, boolean>(
-          (apiNodes as ApiNode[])
-            .filter((n) => n.type === 'group' || n.container_mode === true)
-            .map((n) => [n.id, true])
-        )
-        const rfNodes = (apiNodes as ApiNode[]).map((n) => deserializeApiNode(n, proxmoxContainerMap))
-        const rfEdges = (apiEdges as ApiEdge[]).map(deserializeApiEdge)
-        const savedTheme = res.data.viewport?.theme_id
-        if (savedTheme) setTheme(savedTheme)
-        if (res.data.custom_style) setCustomStyle(res.data.custom_style as CustomStyleDef)
-        loadCanvas(rfNodes, rfEdges)
-      } else {
-        loadCanvas(demoNodes, demoEdges)
-      }
+      res = await canvasApi.load(designId)
     } catch {
+      // Backend down / errored. Surface it and STOP — never fall back to the demo
+      // canvas, which would hide the real error and look like a fresh account.
+      // Leave the on-screen canvas and provenance untouched so an autosave can't
+      // clobber real data with an empty canvas.
+      setLoadError(true)
+      toast.error('Could not load canvas — backend not responding')
+      return
+    }
+    const { nodes: apiNodes, edges: apiEdges } = res.data
+    const mode = decideCanvasLoad(apiNodes.length > 0, res.data.initialized === true)
+    if (mode === 'real') {
+      const proxmoxContainerMap = new Map<string, boolean>(
+        (apiNodes as ApiNode[])
+          .filter((n) => n.type === 'group' || n.container_mode === true)
+          .map((n) => [n.id, true])
+      )
+      const { nodes: rfNodes, edges: rfEdges } = migrateClusterHandles(
+        (apiNodes as ApiNode[]).map((n) => deserializeApiNode(n, proxmoxContainerMap)),
+        (apiEdges as ApiEdge[]).map(deserializeApiEdge),
+      )
+      const savedTheme = res.data.viewport?.theme_id
+      if (savedTheme) setTheme(savedTheme)
+      if (res.data.custom_style) setCustomStyle(res.data.custom_style as CustomStyleDef)
+      const savedFloorMap = res.data.viewport?.floor_map as FloorMapConfig | undefined
+      // Clear when the target design has no floor plan, so it doesn't bleed
+      // across canvases when switching designs.
+      setFloorMap(savedFloorMap ?? null)
+      loadCanvas(rfNodes, rfEdges)
+    } else if (mode === 'empty') {
+      // Initialized but no nodes: the user cleared this canvas on purpose — respect
+      // it and keep it empty instead of re-seeding the demo.
+      const savedTheme = res.data.viewport?.theme_id
+      if (savedTheme) setTheme(savedTheme)
+      if (res.data.custom_style) setCustomStyle(res.data.custom_style as CustomStyleDef)
+      setFloorMap(null)
+      loadCanvas([], [])
+    } else {
+      // Brand-new, never-saved canvas: seed the demo.
+      setFloorMap(null)
       loadCanvas(demoNodes, demoEdges)
     }
-  }, [loadCanvas, setTheme, setCustomStyle])
+    setLoadError(false)
+    setIsNewUser(isNewUserCanvas(mode))
+    // Record provenance so autosave writes back under the design just loaded.
+    setLoadedDesignId(designId ?? null)
+  }, [loadCanvas, setTheme, setCustomStyle, setFloorMap])
+
+  // Standalone counterpart of loadCanvasFromApi — reads a design's canvas from
+  // localStorage, falling back to the demo canvas when it has never been saved.
+  const loadStandaloneCanvas = useCallback((designId: string) => {
+    const saved = standaloneStorage.loadCanvas(designId)
+    // A stored entry (even with zero nodes) means the user has saved this canvas,
+    // so treat it as initialized and don't re-seed the demo on top of a canvas
+    // they deliberately cleared.
+    const mode = decideCanvasLoad((saved?.nodes.length ?? 0) > 0, saved !== null)
+    if (mode === 'real' && saved) {
+      if (saved.theme_id) setTheme(saved.theme_id)
+      if (saved.custom_style) setCustomStyle(saved.custom_style)
+      // Floor plans are backend-only; keep the store clear in standalone mode.
+      setFloorMap(null)
+      const migrated = migrateClusterHandles(saved.nodes, saved.edges)
+      loadCanvas(migrated.nodes, migrated.edges)
+    } else if (mode === 'empty' && saved) {
+      if (saved.theme_id) setTheme(saved.theme_id)
+      if (saved.custom_style) setCustomStyle(saved.custom_style)
+      setFloorMap(null)
+      loadCanvas([], [])
+    } else {
+      setFloorMap(null)
+      loadCanvas(demoNodes, demoEdges)
+    }
+    setLoadError(false)
+    setIsNewUser(isNewUserCanvas(mode))
+    // Record provenance so autosave writes back under the design just loaded.
+    setLoadedDesignId(designId)
+  }, [loadCanvas, setTheme, setCustomStyle, setFloorMap])
+
+  /**
+   * Load whichever canvas the design holds. Rack designs bypass the node/edge
+   * canvas entirely — different store, different endpoints.
+   */
+  const loadAnyDesign = useCallback(async (designId: string) => {
+    if (designTypeOf(designId) !== 'rack') {
+      if (STANDALONE) loadStandaloneCanvas(designId)
+      else await loadCanvasFromApi(designId)
+      return
+    }
+    // The rack store owns the fetch; App only records provenance afterwards, so
+    // none of these run synchronously inside the calling effect.
+    await useRackStore.getState().loadDesign(designId)
+    setIsNewUser(false)
+    setLoadError(false)
+    setLoadedDesignId(designId)
+  }, [designTypeOf, loadStandaloneCanvas, loadCanvasFromApi])
 
   const loadDesignsAndCanvas = useCallback(async () => {
-    if (STANDALONE) return
+    // Prefer a design id explicitly requested via the URL (?design=<id>), so a
+    // refresh or shared link opens that design. Ignore it when it doesn't match
+    // a known design and fall back to the current/default one.
+    const urlDesignId = getDesignIdFromUrl()
+    if (STANDALONE) {
+      const designs = standaloneStorage.ensureSeed()
+      setDesigns(designs)
+      const fromUrl = urlDesignId && designs.some((d) => d.id === urlDesignId) ? urlDesignId : null
+      const targetId = fromUrl ?? activeDesignId ?? designs[0]?.id
+      if (targetId) {
+        setActiveDesign(targetId)
+        void loadAnyDesign(targetId)
+      }
+      return
+    }
     try {
       const res = await designsApi.list()
       const loadedDesigns = res.data
       setDesigns(loadedDesigns)
-      const targetId = activeDesignId ?? loadedDesigns[0]?.id
+      const fromUrl = urlDesignId && loadedDesigns.some((d) => d.id === urlDesignId) ? urlDesignId : null
+      const targetId = fromUrl ?? activeDesignId ?? loadedDesigns[0]?.id
       if (targetId) {
         setActiveDesign(targetId)
-        await loadCanvasFromApi(targetId)
+        await loadAnyDesign(targetId)
       }
     } catch {
-      // If API fails (e.g. fresh DB with no designs), fall back to demo data
-      loadCanvas(demoNodes, demoEdges)
+      // Backend unreachable/errored — surface it. Do NOT seed the demo: that would
+      // hide a real outage behind a fake "new account" canvas.
+      setLoadError(true)
+      toast.error('Could not reach backend — check the server and retry')
     }
-  }, [setDesigns, setActiveDesign, loadCanvasFromApi, activeDesignId, loadCanvas])
+  }, [setDesigns, setActiveDesign, loadAnyDesign, activeDesignId])
 
-  // Load canvas on auth (or immediately in standalone mode)
+  // Keep a ref so the auth effect can call the latest loader without listing it
+  // as a dependency (which would re-fire on every design switch).
+  const loadDesignsAndCanvasRef = useRef(loadDesignsAndCanvas)
+  useEffect(() => { loadDesignsAndCanvasRef.current = loadDesignsAndCanvas }, [loadDesignsAndCanvas])
+
+  // Retry a failed load from the error banner.
+  const handleRetryLoad = useCallback(() => {
+    setLoadError(false)
+    void loadDesignsAndCanvasRef.current()
+  }, [])
+
+  // Bridge the Getting Started tour steps to the App's modal controls. The overlay
+  // calls closeAll() before each step, then the step's action to open the target.
+  const walkthroughActions = useMemo<WalkthroughActionApi>(() => ({
+    closeAll: () => {
+      setScanConfigOpen(false)
+      setScanHistoryOpen(false)
+      setTourScanHistoryDemo(false)
+      setInventoryModalOpen(false)
+      setTourInventoryDemo(false)
+      setEditNodeId(null)
+      setThemeModalOpen(false)
+      setZigbeeImportOpen(false)
+      // Clear any tour-driven multi-selection so the DetailPanel closes.
+      useCanvasStore.setState((s) => ({
+        nodes: s.nodes.map((n) => (n.selected ? { ...n, selected: false } : n)),
+        selectedNodeIds: [],
+        selectedNodeId: null,
+      }))
+    },
+    openScanConfig: () => setScanConfigOpen(true),
+    openScanHistoryDemo: () => {
+      setTourScanHistoryDemo(true)
+      setScanHistoryOpen(true)
+    },
+    openInventoryDemo: () => {
+      setTourInventoryDemo(true)
+      openInventoryModal(undefined, 'pending')
+    },
+    editFirstNode: () => {
+      const first = useCanvasStore.getState().nodes.find((n) => n.data.type !== 'groupRect' && n.data.type !== 'text')
+      if (first) setEditNodeId(first.id)
+    },
+    selectTwoNodes: () => {
+      const ids = useCanvasStore.getState().nodes
+        .filter((n) => n.data.type !== 'groupRect' && n.data.type !== 'text')
+        .slice(0, 2)
+        .map((n) => n.id)
+      if (ids.length < 2) return
+      const set = new Set(ids)
+      useCanvasStore.setState((s) => ({
+        nodes: s.nodes.map((n) => ({ ...n, selected: set.has(n.id) })),
+        selectedNodeIds: ids,
+        selectedNodeId: null,
+      }))
+    },
+    openStyle: () => setThemeModalOpen(true),
+    openZigbeeImport: () => setZigbeeImportOpen(true),
+  }), [openInventoryModal])
+
+  // Load designs + canvas on auth (or immediately in standalone mode, which has
+  // no auth gate).
   useEffect(() => {
     if (STANDALONE) {
-      try {
-        const saved = localStorage.getItem(STANDALONE_STORAGE_KEY)
-        if (saved) {
-          const { nodes: savedNodes, edges: savedEdges, theme_id, custom_style } = JSON.parse(saved)
-          if (theme_id) setTheme(theme_id)
-          if (custom_style) setCustomStyle(custom_style)
-          loadCanvas(savedNodes, savedEdges)
-        } else {
-          loadCanvas(demoNodes, demoEdges)
-        }
-      } catch {
-        loadCanvas(demoNodes, demoEdges)
-      }
+      loadDesignsAndCanvasRef.current()
       return
     }
     if (!isAuthenticated) return
-    loadDesignsAndCanvas()
-  }, [isAuthenticated, loadCanvas, setTheme, setCustomStyle]) // only on auth change, not design change
+    loadDesignsAndCanvasRef.current()
+  }, [isAuthenticated]) // only on auth change, not design change
 
   // Reload canvas when active design changes (after initial load)
   const initialLoadDone = useRef(false)
@@ -186,7 +417,10 @@ export default function App() {
       prevDesignRef.current = activeDesignId
       return
     }
-    if (!STANDALONE && isAuthenticated && activeDesignId && initialLoadDone.current) {
+    // Standalone has no auth gate; backed mode requires authentication.
+    const ready = STANDALONE || isAuthenticated
+    const loadForDesign = loadAnyDesign
+    if (ready && activeDesignId && initialLoadDone.current) {
       const oldId = prevDesignRef.current
       // If the previous design was deleted (no longer in the list), don't try to
       // save into it — just load the newly-selected design.
@@ -199,7 +433,7 @@ export default function App() {
         const targetId = activeDesignId
         handleSave(oldId).then((ok) => {
           if (ok) {
-            loadCanvasFromApi(targetId)
+            void loadForDesign(targetId)
           } else {
             // Save failed: don't load the new design — that would overwrite the
             // unsaved in-memory canvas. Revert the selection back to the old
@@ -210,7 +444,12 @@ export default function App() {
           }
         })
       } else {
-        loadCanvasFromApi(activeDesignId)
+        // Loading a design is exactly the "synchronize with an external system"
+        // case: it fetches and then publishes the result into React state. The
+        // rule can't see through the loader, so silence it here rather than
+        // deferring the fetch by a tick.
+        // eslint-disable-next-line react-hooks/set-state-in-effect
+        void loadForDesign(activeDesignId)
       }
     }
     if (activeDesignId) {
@@ -219,6 +458,11 @@ export default function App() {
     }
   }, [activeDesignId])
 
+  // Reflect the active design into the URL so refresh/share reopens it.
+  useEffect(() => {
+    if (activeDesignId) setDesignIdInUrl(activeDesignId)
+  }, [activeDesignId])
+
   // Keep refs for store actions so keydown handler is always up-to-date without re-registering
   const undoRef = useRef(undo)
   const redoRef = useRef(redo)
@@ -406,8 +650,13 @@ export default function App() {
     snapshotHistory()
     const existingNode = nodes.find((n) => n.id === editNodeId)
     updateNode(editNodeId, data)
-    // If container_mode changed, apply structural changes (children parentId, node dimensions)
-    if (typeof data.container_mode === 'boolean') {
+    // Only run the structural container transition when container_mode ACTUALLY
+    // changed. The modal always includes container_mode in its payload, so firing
+    // on presence alone re-ran the absolute<->relative child-position conversion on
+    // every edit (e.g. an icon change), corrupting nested child positions (they pile
+    // up in a corner). Gate on a real toggle instead.
+    const prevContainerMode = !!existingNode?.data.container_mode
+    if (typeof data.container_mode === 'boolean' && data.container_mode !== prevContainerMode) {
       setProxmoxContainerMode(editNodeId, data.container_mode)
     }
     // Sync virtual edge when parent_id changes on an LXC/VM node
@@ -440,9 +689,11 @@ export default function App() {
 
   const handleAutoLayout = useCallback(() => {
     const laid = applyDagreLayout(nodes, edges)
-    loadCanvas(laid, edges)
+    // applyLayout keeps undo history so the user can revert an accidental
+    // Auto Layout (#280); loadCanvas would wipe it.
+    applyLayout(laid, edges)
     toast.success('Canvas auto-arranged')
-  }, [nodes, edges, loadCanvas])
+  }, [nodes, edges, applyLayout])
 
   const handleExportMd = useCallback(async () => {
     const md = generateMarkdownTable(nodes)
@@ -464,21 +715,24 @@ export default function App() {
   const handleImportYaml = useCallback((content: string) => {
     try {
       const { nodes: merged, edges: mergedEdges, imported } = parseYamlToCanvas(content, nodes, edges)
-      snapshotHistory()
-      loadCanvas(merged, mergedEdges)
-      markUnsaved()
+      // applyLayout keeps undo history so an import can be reverted; loadCanvas
+      // would wipe it (#280).
+      applyLayout(merged, mergedEdges)
       toast.success(`Imported ${imported} node${imported !== 1 ? 's' : ''}`)
     } catch (err) {
       toast.error(`Import failed: ${err instanceof Error ? err.message : String(err)}`)
     }
-  }, [nodes, edges, snapshotHistory, loadCanvas, markUnsaved])
+  }, [nodes, edges, applyLayout])
 
   // Open the read-only live view of the currently active design in a new tab.
   // Standalone has no backend/key — it reads localStorage, so just open /view.
   // Otherwise fetch the configured live view key and build /view?key=...&design=<id>.
   const handleViewOnly = useCallback(async () => {
     if (STANDALONE) {
-      window.open('/view', '_blank', 'noopener,noreferrer')
+      // Standalone reads canvas from localStorage; pass the active design id so
+      // the read-only tab renders the same canvas the user is viewing.
+      const url = activeDesignId ? `/view?design=${encodeURIComponent(activeDesignId)}` : '/view'
+      window.open(url, '_blank', 'noopener,noreferrer')
       return
     }
     try {
@@ -599,6 +853,69 @@ export default function App() {
     markUnsaved()
   }, [addNode, onConnect, snapshotHistory, markUnsaved])
 
+  const handleProxmoxAddToCanvas = useCallback((pmNodes: ProxmoxNode[], pmEdges: ProxmoxEdge[]) => {
+    snapshotHistory()
+    const COLS = 4
+    const SPACING_X = 190
+    const SPACING_Y = 110
+    const cols = Math.min(COLS, pmNodes.length)
+    const rows = Math.ceil(pmNodes.length / COLS)
+    const origin = getCenteredPosition(cols * SPACING_X, rows * SPACING_Y)
+    // Multiple hosts from one import = a cluster → chain them via left/right
+    // 'cluster' edges. Those endpoints need one left + one right handle each
+    // (both default to 0), so grant them to the host nodes up front.
+    const clusterEdges = buildProxmoxClusterEdges(pmNodes)
+    const cluster = clusterEdges.length > 0
+    pmNodes.forEach((pn, i) => {
+      const col = i % COLS
+      const row = Math.floor(i / COLS)
+      const position = { x: origin.x + col * SPACING_X, y: origin.y + row * SPACING_Y }
+      const isClusterHost = cluster && pn.type === 'proxmox'
+      const newNode: import('@xyflow/react').Node<NodeData> = {
+        id: pn.id,
+        type: pn.type,
+        position,
+        data: {
+          label: pn.label,
+          type: pn.type as NodeData['type'],
+          status: (pn.status === 'online' ? 'online' : 'unknown') as NodeData['status'],
+          services: [],
+          ...(pn.ip ? { ip: pn.ip } : {}),
+          ...(pn.hostname ? { hostname: pn.hostname } : {}),
+          ...(isClusterHost ? { left_handles: 1, right_handles: 1 } : {}),
+        },
+      }
+      addNode(newNode)
+    })
+    // Host → guest links render as 'virtual' edges (VM/LXC ↔ host).
+    pmEdges.forEach((pe) => {
+      onConnect({
+        source: pe.source,
+        sourceHandle: 'bottom',
+        target: pe.target,
+        targetHandle: 'top-t',
+        type: 'virtual',
+      } as unknown as import('@xyflow/react').Connection)
+    })
+    // Host ↔ host links render as 'cluster' edges (left → right chain).
+    clusterEdges.forEach((ce) => {
+      onConnect({
+        source: ce.source,
+        sourceHandle: ce.sourceHandle,
+        target: ce.target,
+        targetHandle: ce.targetHandle,
+        type: 'cluster',
+      } as unknown as import('@xyflow/react').Connection)
+    })
+    const importedIds = new Set(pmNodes.map((pn) => pn.id))
+    useCanvasStore.setState((state) => ({
+      nodes: state.nodes.map((n) => ({ ...n, selected: importedIds.has(n.id) })),
+      selectedNodeIds: Array.from(importedIds),
+      selectedNodeId: importedIds.size === 1 ? Array.from(importedIds)[0] : null,
+    }))
+    markUnsaved()
+  }, [addNode, onConnect, snapshotHistory, markUnsaved])
+
   const handleEdgeConnect = useCallback((connection: Connection) => {
     setPendingConnection(connection)
   }, [])
@@ -661,12 +978,22 @@ export default function App() {
   const editNode = editNodeId ? nodes.find((n) => n.id === editNodeId) : null
   const editEdge = editEdgeId ? edges.find((e) => e.id === editEdgeId) : null
 
+  if (!STANDALONE && !isInitialized) {
+    return (
+      <div className="flex h-screen w-screen items-center justify-center bg-[#0d1117] text-sm text-muted-foreground">
+        Loading authentication…
+      </div>
+    )
+  }
   if (!STANDALONE && !isAuthenticated) return <LoginPage />
 
   return (
+    <WalkthroughActionsProvider value={walkthroughActions}>
     <TooltipProvider>
       <ReactFlowProvider>
-        <div className="flex h-screen w-screen overflow-hidden bg-[#0d1117]">
+        {/* data-new-user marks a first-time (demo) canvas — the hook the upcoming
+            Getting Started walkthrough keys off. */}
+        <div className="flex h-screen w-screen overflow-hidden bg-[#0d1117]" data-new-user={isNewUser}>
           <Sidebar
             onAddNode={() => setAddNodeOpen(true)}
             onAddGroupRect={() => setAddGroupRectOpen(true)}
@@ -674,12 +1001,28 @@ export default function App() {
             onScan={() => setScanConfigOpen(true)}
             onZigbeeImport={() => setZigbeeImportOpen(true)}
             onZwaveImport={() => setZwaveImportOpen(true)}
+            onProxmoxImport={() => setProxmoxImportOpen(true)}
             onSave={handleSave}
             onOpenSettings={() => setSettingsOpen(true)}
             onOpenHistory={() => setScanHistoryOpen(true)}
-            onOpenPending={openPendingModal}
+            onOpenInventory={openInventoryModal}
           />
           <div className="flex flex-col flex-1 min-w-0">
+            {loadError && (
+              <div
+                role="alert"
+                className="flex items-center justify-between gap-3 bg-[#3d1418] border-b border-[#f85149] px-4 py-2 text-sm text-[#ffa198]"
+              >
+                <span>Backend not responding — the canvas could not be loaded.</span>
+                <button
+                  type="button"
+                  onClick={handleRetryLoad}
+                  className="rounded border border-[#f85149] px-2 py-0.5 text-[#ffa198] hover:bg-[#f85149]/20"
+                >
+                  Retry
+                </button>
+              </div>
+            )}
             <Toolbar
               onSave={handleSave}
               onAutoLayout={handleAutoLayout}
@@ -695,17 +1038,28 @@ export default function App() {
             />
             <div className="flex flex-1 min-h-0">
               <div ref={canvasRef} className="flex-1 min-w-0 h-full">
-                <CanvasContainer
-                  onConnect={handleEdgeConnect}
-                  onEdgeDoubleClick={handleEdgeDoubleClick}
-                  onNodeDoubleClick={handleNodeDoubleClick}
-                  onNodeDragStart={snapshotHistory}
-                  onRequestAddToGroup={setPendingGroupAdd}
-                  onRequestAddToContainer={setPendingContainerAdd}
-                  onOpenPending={(deviceId) => openPendingModal(deviceId)}
-                />
+                {isRackDesign ? (
+                  <RackCanvas />
+                ) : (
+                  <CanvasContainer
+                    onConnect={handleEdgeConnect}
+                    onEdgeDoubleClick={handleEdgeDoubleClick}
+                    onNodeDoubleClick={handleNodeDoubleClick}
+                    onNodeDragStart={snapshotHistory}
+                    onRequestAddToGroup={setPendingGroupAdd}
+                    onRequestAddToContainer={setPendingContainerAdd}
+                    onOpenInventory={(deviceId) => openInventoryModal(deviceId)}
+                  />
+                )}
               </div>
-              {(selectedNodeId || selectedNodeIds.length > 1) && <DetailPanel onEdit={handleEditNode} />}
+              {/* Rack designs keep the full width for mounted gear — a mount is
+                  edited in its own modal — but a selected cable has no plate to
+                  double-click, so it gets the rail. */}
+              {isRackDesign
+                ? <RackCablePanel />
+                : (selectedNodeId || selectedNodeIds.length > 1) && (
+                    <DetailPanel onEdit={handleEditNode} />
+                  )}
             </div>
           </div>
         </div>
@@ -717,6 +1071,7 @@ export default function App() {
           onSubmit={handleAddNode}
           title="Add Node"
           parentCandidates={nodes.map((n) => ({ id: n.id, label: n.data.label ?? n.id, type: n.data.type, container_mode: n.data.container_mode }))}
+          onEditTypeStyle={setStyleEditorType}
         />
 
         {/* key forces re-mount when editing a different node, resetting form state */}
@@ -746,6 +1101,7 @@ export default function App() {
               .map((n) => ({ id: n.id, label: n.data.label ?? n.id, type: n.data.type, container_mode: n.data.container_mode }))
           })()}
           currentNodeId={editNodeId ?? undefined}
+          onEditTypeStyle={setStyleEditorType}
         />
 
         <EdgeModal
@@ -753,11 +1109,6 @@ export default function App() {
           open={!!pendingConnection}
           onClose={() => setPendingConnection(null)}
           onSubmit={handleEdgeConfirm}
-          initial={
-            pendingConnection?.sourceHandle?.includes('cluster') || pendingConnection?.targetHandle?.includes('cluster')
-              ? { type: 'cluster' }
-              : undefined
-          }
         />
 
         <EdgeModal
@@ -786,7 +1137,7 @@ export default function App() {
             open={zigbeeImportOpen}
             onClose={() => setZigbeeImportOpen(false)}
             onAddToCanvas={handleZigbeeAddToCanvas}
-            onPendingImported={() => {
+            onInventoryImported={() => {
               toast.success('Zigbee import started — check Scan History for results')
             }}
           />
@@ -797,16 +1148,28 @@ export default function App() {
             open={zwaveImportOpen}
             onClose={() => setZwaveImportOpen(false)}
             onAddToCanvas={handleZwaveAddToCanvas}
-            onPendingImported={() => {
+            onInventoryImported={() => {
               toast.success('Z-Wave import started — check Scan History for results')
             }}
           />
         )}
 
+        {!STANDALONE && (
+          <ProxmoxImportModal
+            open={proxmoxImportOpen}
+            onClose={() => setProxmoxImportOpen(false)}
+            onAddToCanvas={handleProxmoxAddToCanvas}
+            onInventoryImported={() => {
+              toast.success('Proxmox import started — check Scan History for results')
+            }}
+          />
+        )}
+
         {!STANDALONE && (
           <ScanHistoryModal
             open={scanHistoryOpen}
             onClose={() => setScanHistoryOpen(false)}
+            demoRuns={tourScanHistoryDemo ? DEMO_SCAN_RUNS : undefined}
           />
         )}
 
@@ -883,10 +1246,19 @@ export default function App() {
           onClose={() => setThemeModalOpen(false)}
         />
 
+        {/* Standalone Custom Style editor, opened from a node's Appearance
+            shortcut with that node's type preselected. */}
+        <CustomStyleModal
+          key={styleEditorType ? `style-${styleEditorType}` : 'style-closed'}
+          open={styleEditorType !== null}
+          initialNodeType={styleEditorType ?? undefined}
+          onClose={() => setStyleEditorType(null)}
+        />
+
         <SearchModal
           open={searchOpen}
           onClose={() => setSearchOpen(false)}
-          onOpenPending={(deviceId) => openPendingModal(deviceId)}
+          onOpenInventory={(deviceId) => openInventoryModal(deviceId)}
         />
         <ShortcutsModal open={shortcutsOpen} onClose={() => setShortcutsOpen(false)} />
 
@@ -913,15 +1285,16 @@ export default function App() {
           onCancel={() => setPendingContainerAdd(null)}
         />
 
-        {!STANDALONE && (
-          <SettingsModal open={settingsOpen} onClose={() => setSettingsOpen(false)} />
-        )}
+        {/* Mounted in standalone too: status-check settings are hidden inside,
+            but canvas prefs (snap, hide-IP) still apply. */}
+        <SettingsModal open={settingsOpen} onClose={() => setSettingsOpen(false)} />
 
-        <PendingDevicesModal
-          open={pendingModalOpen}
-          onClose={() => setPendingModalOpen(false)}
-          highlightId={pendingHighlightId}
-          initialStatus={pendingModalStatus}
+        <DeviceInventoryModal
+          open={inventoryModalOpen}
+          onClose={() => setInventoryModalOpen(false)}
+          highlightId={inventoryHighlightId}
+          initialStatus={inventoryModalStatus}
+          demoDevices={tourInventoryDemo ? DEMO_INVENTORY_DEVICES : undefined}
         />
 
         <ExportModal
@@ -931,7 +1304,10 @@ export default function App() {
         />
 
         <Toaster theme="dark" position="bottom-right" />
+        <WalkthroughInvite />
+        <WalkthroughOverlay />
       </ReactFlowProvider>
     </TooltipProvider>
+    </WalkthroughActionsProvider>
   )
 }

frontend/src/api/__tests__/client.test.ts

@@ -6,7 +6,7 @@ type Interceptor<T> = {
 }
 
 interface MockInstance {
-  defaults: { baseURL?: string }
+  defaults: { baseURL?: string; withCredentials?: boolean }
   interceptors: {
     request: { use: (f: Interceptor<unknown>['fulfilled'], r?: Interceptor<unknown>['rejected']) => void }
     response: { use: (f: Interceptor<unknown>['fulfilled'], r?: Interceptor<unknown>['rejected']) => void }
@@ -25,9 +25,9 @@ const instances = hoisted.instances as MockInstance[]
 vi.mock('axios', () => {
   return {
     default: {
-      create: (cfg: { baseURL?: string }) => {
+      create: (cfg: { baseURL?: string; withCredentials?: boolean }) => {
         const inst: MockInstance = {
-          defaults: { baseURL: cfg?.baseURL },
+          defaults: { baseURL: cfg?.baseURL, withCredentials: cfg?.withCredentials },
           interceptors: {
             request: { use: (f: unknown, r?: unknown) => { inst.__req = { fulfilled: f as never, rejected: r as never } } },
             response: { use: (f: unknown, r?: unknown) => { inst.__res = { fulfilled: f as never, rejected: r as never } } },
@@ -54,7 +54,7 @@ describe('api/client', () => {
   const [api, publicApi] = instances
 
   beforeEach(() => {
-    useAuthStore.setState({ token: null, isAuthenticated: false })
+    useAuthStore.setState({ token: null, csrfToken: null, isAuthenticated: false })
     api.get.mockClear()
     api.post.mockClear()
     api.patch.mockClear()
@@ -66,6 +66,7 @@ describe('api/client', () => {
   it('creates two axios instances with /api/v1 baseURL', () => {
     expect(instances).toHaveLength(2)
     expect(api.defaults.baseURL).toBe('/api/v1')
+    expect(api.defaults.withCredentials).toBe(true)
     expect(publicApi.defaults.baseURL).toBe('/api/v1')
   })
 
@@ -86,6 +87,18 @@ describe('api/client', () => {
     expect((out as typeof cfg).headers.Authorization).toBeUndefined()
   })
 
+  it('adds the in-memory OIDC CSRF token only to unsafe requests', () => {
+    useAuthStore.setState({ csrfToken: 'csrf-123' })
+    const post = { method: 'post', headers: {} as Record<string, string> }
+    const get = { method: 'get', headers: {} as Record<string, string> }
+
+    api.__req.fulfilled!(post)
+    api.__req.fulfilled!(get)
+
+    expect(post.headers['X-Homelable-CSRF']).toBe('csrf-123')
+    expect(get.headers['X-Homelable-CSRF']).toBeUndefined()
+  })
+
   it('response interceptor passes through 2xx responses', () => {
     const r = { status: 200, data: { ok: true } }
     expect(api.__res.fulfilled!(r)).toBe(r)
@@ -125,6 +138,15 @@ describe('api/client', () => {
     expect(api.post).toHaveBeenCalledWith('/auth/login', { username: 'u', password: 'p' })
   })
 
+  it('authApi discovers auth publicly and manages the current session', () => {
+    mod.authApi.config()
+    expect(publicApi.get).toHaveBeenCalledWith('/auth/config')
+    mod.authApi.me()
+    expect(api.get).toHaveBeenCalledWith('/auth/me')
+    mod.authApi.logout()
+    expect(api.post).toHaveBeenCalledWith('/auth/logout')
+  })
+
   it('canvasApi.load GETs /canvas', () => {
     mod.canvasApi.load()
     expect(api.get).toHaveBeenCalledWith('/canvas', expect.objectContaining({}))
@@ -229,4 +251,22 @@ describe('api/client', () => {
     mod.zwaveApi.importToPending(cfg)
     expect(api.post).toHaveBeenCalledWith('/zwave/import-pending', cfg)
   })
+
+  it('proxmoxApi.testConnection/importNetwork/importToPending', () => {
+    const cfg = { host: 'pve', port: 8006, token_id: 'u@pam!t', token_secret: 's', verify_tls: true }
+    mod.proxmoxApi.testConnection(cfg)
+    expect(api.post).toHaveBeenCalledWith('/proxmox/test-connection', cfg)
+    mod.proxmoxApi.importNetwork(cfg)
+    expect(api.post).toHaveBeenCalledWith('/proxmox/import', cfg)
+    mod.proxmoxApi.importToPending(cfg)
+    expect(api.post).toHaveBeenCalledWith('/proxmox/import-pending', cfg)
+  })
+
+  it('proxmoxApi.getConfig/saveConfig hit /proxmox/config', () => {
+    mod.proxmoxApi.getConfig()
+    expect(api.get).toHaveBeenCalledWith('/proxmox/config')
+    const conf = { sync_enabled: false, sync_interval: 3600 }
+    mod.proxmoxApi.saveConfig(conf)
+    expect(api.post).toHaveBeenCalledWith('/proxmox/config', conf)
+  })
 })

frontend/src/api/client.ts

@@ -1,16 +1,22 @@
 import axios from 'axios'
 import { useAuthStore } from '@/stores/authStore'
+import type { AuthMode, AuthUser } from '@/stores/authStore'
 
 export const api = axios.create({
   baseURL: '/api/v1',
+  withCredentials: true,
 })
 
 // Unauthenticated axios instance — no JWT, no 401 redirect (used for public endpoints)
 const publicApi = axios.create({ baseURL: '/api/v1' })
 
 api.interceptors.request.use((config) => {
-  const token = useAuthStore.getState().token
+  const { token, csrfToken } = useAuthStore.getState()
   if (token) config.headers.Authorization = `Bearer ${token}`
+  const method = config.method?.toUpperCase() ?? 'GET'
+  if (csrfToken && !['GET', 'HEAD', 'OPTIONS'].includes(method)) {
+    config.headers['X-Homelable-CSRF'] = csrfToken
+  }
   return config
 })
 
@@ -23,8 +29,11 @@ api.interceptors.response.use(
 )
 
 export const authApi = {
+  config: () => publicApi.get<{ mode: AuthMode; oidc_login_url: string | null }>('/auth/config'),
   login: (username: string, password: string) =>
     api.post<{ access_token: string }>('/auth/login', { username, password }),
+  me: () => api.get<AuthUser>('/auth/me'),
+  logout: () => api.post('/auth/logout'),
 }
 
 export const canvasApi = {
@@ -41,7 +50,40 @@ export const canvasApi = {
   }) => api.post('/canvas/save', payload),
 }
 
+export const mediaApi = {
+  /** Upload an image, returns its server URL (e.g. /api/v1/media/<uuid>.png). */
+  upload: async (file: File): Promise<{ url: string; filename: string }> => {
+    const form = new FormData()
+    form.append('file', file)
+    const res = await api.post<{ url: string; filename: string }>('/media/upload', form)
+    return res.data
+  },
+  delete: (filename: string) => api.delete(`/media/${filename}`),
+}
+
+/**
+ * A canvas node as `GET /nodes` reports it — the fields a reader needs to tell
+ * two hosts apart. The canvas itself keeps its own richer React Flow shape; this
+ * is only for pickers and lookups.
+ */
+export interface ApiCanvasNode {
+  id: string
+  design_id: string | null
+  label: string
+  type: string
+  ip: string | null
+  mac: string | null
+  hostname: string | null
+  os: string | null
+  status: string
+  check_method: string | null
+  last_seen: string | null
+}
+
 export const nodesApi = {
+  /** Every node, across every design. `label` filters case-insensitively. */
+  list: (label?: string) =>
+    api.get<ApiCanvasNode[]>('/nodes', { params: label ? { label } : {} }),
   create: (data: object) => api.post('/nodes', data),
   update: (id: string, data: object) => api.patch(`/nodes/${id}`, data),
   delete: (id: string) => api.delete(`/nodes/${id}`),
@@ -66,18 +108,59 @@ export interface DeepScanConfig {
 
 export type ScanConfigData = { ranges: string[] } & DeepScanConfig
 
+// A device the backend refused to place because an equivalent node already
+// exists on the target design (same ip/mac/ieee). `existing_node_id` points at
+// the node already there so the UI can link to it.
+export interface SkippedDevice {
+  device_id: string
+  label: string
+  match: 'ip' | 'mac' | 'ieee'
+  value: string
+  existing_node_id: string | null
+}
+
+// 409 body from single approve / create when a same-design duplicate is found.
+export interface DuplicateNodeConflict {
+  duplicate: true
+  existing_node_id: string
+  existing_label: string
+  match: 'ip' | 'mac' | 'ieee'
+  value: string
+}
+
+/**
+ * The Device Inventory rides the scan routes.
+ *
+ * `/scan/pending/*` is what the table was called when it was a queue of finds
+ * awaiting approval; the rows are the Device Inventory now, but the paths are a
+ * published contract the MCP server also calls, so they stay. The method names
+ * follow the paths rather than the concept, so a route is easy to find.
+ */
 export const scanApi = {
   trigger: (deepScan?: Partial<DeepScanConfig>) => api.post('/scan/trigger', deepScan ?? {}),
   pending: () => api.get('/scan/pending'),
+  /** Add an inventory entry by hand, for hardware no scan can discover. */
+  createPending: (data: {
+    hostname: string
+    ip?: string | null
+    mac?: string | null
+    suggested_type?: string | null
+    model?: string | null
+    vendor?: string | null
+    /** "manual" (default) or "rack" for gear created from a rack canvas. */
+    discovery_source?: 'manual' | 'rack'
+  }) => api.post<{ id: string; hostname: string | null }>('/scan/pending', data),
   hidden: () => api.get('/scan/hidden'),
   runs: () => api.get('/scan/runs'),
   clearPending: () => api.delete('/scan/pending'),
+  /** Remove one inventory entry. 409 when a rack still mounts it. */
+  deletePending: (id: string) => api.delete<{ deleted: boolean }>(`/scan/pending/${id}`),
   approve: (id: string, nodeData: object) =>
     api.post<{
       approved: boolean
       node_id: string
       edges_created: number
-      edges: { id: string; source: string; target: string }[]
+      edges: { id: string; source: string; target: string; type?: string; source_handle?: string | null; target_handle?: string | null }[]
     }>(`/scan/pending/${id}/approve`, nodeData),
   hide: (id: string) => api.post(`/scan/pending/${id}/hide`),
   ignore: (id: string) => api.post(`/scan/pending/${id}/ignore`),
@@ -87,8 +170,9 @@ export const scanApi = {
       node_ids: string[]
       device_ids: string[]
       edges_created: number
-      edges: { id: string; source: string; target: string }[]
+      edges: { id: string; source: string; target: string; type?: string; source_handle?: string | null; target_handle?: string | null }[]
       skipped: number
+      skipped_devices: SkippedDevice[]
     }>('/scan/pending/bulk-approve', { device_ids: ids, design_id: designId ?? undefined }),
   bulkHide: (ids: string[]) => api.post<{ hidden: number; skipped: number }>('/scan/pending/bulk-hide', { device_ids: ids }),
   restore: (id: string) => api.post<{ restored: boolean; device_id: string }>(`/scan/pending/${id}/restore`),
@@ -109,15 +193,120 @@ export const settingsApi = {
   save: (data: AppSettings) => api.post<AppSettings>('/settings', data),
 }
 
+export interface ProxmoxConnection {
+  host: string
+  port: number
+  token_id?: string
+  token_secret?: string
+  verify_tls?: boolean
+}
+
+export interface ProxmoxConfigData {
+  host: string
+  port: number
+  verify_tls: boolean
+  sync_enabled: boolean
+  sync_interval: number
+  token_configured: boolean
+}
+
+export const proxmoxApi = {
+  testConnection: (data: ProxmoxConnection) =>
+    api.post<{ connected: boolean; message: string }>('/proxmox/test-connection', data),
+
+  importNetwork: (data: ProxmoxConnection) =>
+    api.post<{
+      nodes: import('@/components/proxmox/types').ProxmoxNode[]
+      edges: import('@/components/proxmox/types').ProxmoxEdge[]
+      device_count: number
+    }>('/proxmox/import', data),
+
+  importToPending: (data: ProxmoxConnection) =>
+    api.post<{
+      id: string
+      status: string
+      kind: string
+      ranges: string[]
+      devices_found: number
+      started_at: string
+      finished_at: string | null
+      error: string | null
+    }>('/proxmox/import-pending', data),
+
+  getConfig: () => api.get<ProxmoxConfigData>('/proxmox/config'),
+  // Only the auto-sync activation is persisted. Connection config
+  // (host/port/token/verify_tls) is env-only and never sent.
+  saveConfig: (data: { sync_enabled: boolean; sync_interval: number }) =>
+    api.post<ProxmoxConfigData>('/proxmox/config', data),
+
+  syncNow: () =>
+    api.post<{
+      id: string
+      status: string
+      kind: string
+      ranges: string[]
+      devices_found: number
+      started_at: string
+      finished_at: string | null
+      error: string | null
+    }>('/proxmox/sync-now'),
+}
+
 export const designsApi = {
   list: () => api.get<import('@/types').Design[]>('/designs'),
   create: (data: { name: string; icon?: string; design_type?: string }) =>
     api.post<import('@/types').Design>('/designs', data),
+  copy: (sourceId: string, data: { name: string; icon?: string }) =>
+    api.post<import('@/types').Design>(`/designs/${sourceId}/copy`, data),
   update: (id: string, data: { name?: string; icon?: string }) =>
     api.put<import('@/types').Design>(`/designs/${id}`, data),
   delete: (id: string) => api.delete(`/designs/${id}`),
 }
 
+export const racksApi = {
+  load: (designId: string) =>
+    api.get<import('@/utils/rackSerializer').ApiRackState>('/racks', { params: { design_id: designId } }),
+  save: (payload: import('@/utils/rackSerializer').RackSavePayload) =>
+    api.post<{ saved: boolean }>('/racks/save', payload),
+  inventory: (designId: string) =>
+    api.get<{ items: import('@/utils/rackSerializer').ApiInventoryItem[] }>('/racks/inventory', {
+      params: { design_id: designId },
+    }),
+}
+
+export interface ZigbeeConfigData {
+  mqtt_host: string
+  mqtt_port: number
+  base_topic: string
+  mqtt_tls: boolean
+  sync_enabled: boolean
+  sync_interval: number
+  host_configured: boolean
+}
+
+export interface ZwaveConfigData {
+  mqtt_host: string
+  mqtt_port: number
+  prefix: string
+  gateway_name: string
+  mqtt_tls: boolean
+  sync_enabled: boolean
+  sync_interval: number
+  host_configured: boolean
+}
+
+// Shape returned by every background-scan trigger (import-pending / sync-now).
+interface ScanRunResult {
+  id: string
+  status: string
+  kind: string
+  ranges: string[]
+  devices_found: number
+  started_at: string
+  finished_at: string | null
+  error: string | null
+}
+
 export const zigbeeApi = {
   testConnection: (data: {
     mqtt_host: string
@@ -163,6 +352,13 @@ export const zigbeeApi = {
       finished_at: string | null
       error: string | null
     }>('/zigbee/import-pending', data),
+
+  getConfig: () => api.get<ZigbeeConfigData>('/zigbee/config'),
+  // Only the auto-sync activation is persisted. MQTT connection config
+  // (host/port/credentials/topic/tls) is env-only and never sent.
+  saveConfig: (data: { sync_enabled: boolean; sync_interval: number }) =>
+    api.post<ZigbeeConfigData>('/zigbee/config', data),
+  syncNow: () => api.post<ScanRunResult>('/zigbee/sync-now'),
 }
 
 export const zwaveApi = {
@@ -212,4 +408,11 @@ export const zwaveApi = {
       finished_at: string | null
       error: string | null
     }>('/zwave/import-pending', data),
+
+  getConfig: () => api.get<ZwaveConfigData>('/zwave/config'),
+  // Only the auto-sync activation is persisted. MQTT connection config
+  // (host/port/credentials/prefix/gateway/tls) is env-only and never sent.
+  saveConfig: (data: { sync_enabled: boolean; sync_interval: number }) =>
+    api.post<ZwaveConfigData>('/zwave/config', data),
+  syncNow: () => api.post<ScanRunResult>('/zwave/sync-now'),
 }

frontend/src/auth/__tests__/bootstrap.test.ts

@@ -0,0 +1,121 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAuthStore } from '@/stores/authStore'
+
+vi.mock('@/api/client', () => ({
+  authApi: {
+    config: vi.fn(),
+    me: vi.fn(),
+  },
+}))
+
+import { authApi } from '@/api/client'
+import { bootstrapAuth } from '../bootstrap'
+
+describe('bootstrapAuth', () => {
+  beforeEach(() => {
+    sessionStorage.clear()
+    useAuthStore.setState({
+      token: null,
+      isAuthenticated: false,
+      isInitialized: false,
+      authMode: null,
+      authMethod: null,
+      oidcLoginUrl: null,
+      displayName: null,
+      csrfToken: null,
+    })
+    vi.mocked(authApi.config).mockReset()
+    vi.mocked(authApi.me).mockReset()
+  })
+
+  it('restores an OIDC cookie session without storing an IdP token', async () => {
+    vi.mocked(authApi.config).mockResolvedValue({
+      data: { mode: 'oidc', oidc_login_url: '/api/v1/auth/oidc/login' },
+    } as never)
+    vi.mocked(authApi.me).mockResolvedValue({
+      data: {
+        subject: 'user-1',
+        display_name: 'Alice',
+        auth_method: 'oidc',
+        issuer: 'https://id.example/application/o/homelable/',
+        csrf_token: 'csrf-123',
+      },
+    } as never)
+
+    await bootstrapAuth()
+
+    const state = useAuthStore.getState()
+    expect(authApi.me).toHaveBeenCalledOnce()
+    expect(state.isAuthenticated).toBe(true)
+    expect(state.authMethod).toBe('oidc')
+    expect(state.token).toBeNull()
+    expect(state.csrfToken).toBe('csrf-123')
+  })
+
+  it('does not probe /auth/me for local mode without a persisted token', async () => {
+    vi.mocked(authApi.config).mockResolvedValue({
+      data: { mode: 'local', oidc_login_url: null },
+    } as never)
+
+    await bootstrapAuth()
+
+    expect(authApi.me).not.toHaveBeenCalled()
+    expect(useAuthStore.getState()).toMatchObject({
+      authMode: 'local',
+      isAuthenticated: false,
+      isInitialized: true,
+    })
+  })
+
+  it('validates and retains a persisted local bearer token', async () => {
+    useAuthStore.setState({ token: 'local-token' })
+    vi.mocked(authApi.config).mockResolvedValue({
+      data: { mode: 'local', oidc_login_url: null },
+    } as never)
+    vi.mocked(authApi.me).mockResolvedValue({
+      data: {
+        subject: 'admin',
+        display_name: 'admin',
+        auth_method: 'local',
+        issuer: null,
+        csrf_token: null,
+      },
+    } as never)
+
+    await bootstrapAuth()
+
+    expect(useAuthStore.getState()).toMatchObject({
+      token: 'local-token',
+      isAuthenticated: true,
+      authMethod: 'local',
+    })
+  })
+
+  it('fails closed when the backend rejects the session', async () => {
+    useAuthStore.setState({ token: 'expired-token', isAuthenticated: true })
+    vi.mocked(authApi.config).mockResolvedValue({
+      data: { mode: 'local', oidc_login_url: null },
+    } as never)
+    vi.mocked(authApi.me).mockRejectedValue({ response: { status: 401 } })
+
+    await bootstrapAuth()
+
+    expect(useAuthStore.getState()).toMatchObject({
+      token: null,
+      isAuthenticated: false,
+      isInitialized: true,
+    })
+  })
+
+  it('leaves the auth mode unknown when discovery is unavailable', async () => {
+    vi.mocked(authApi.config).mockRejectedValue(new Error('network down'))
+
+    await bootstrapAuth()
+
+    expect(useAuthStore.getState()).toMatchObject({
+      authMode: null,
+      isAuthenticated: false,
+      isInitialized: true,
+    })
+  })
+})

frontend/src/auth/bootstrap.ts

@@ -0,0 +1,33 @@
+import { authApi } from '@/api/client'
+import { useAuthStore } from '@/stores/authStore'
+
+/**
+ * Discover the configured authentication mode and restore a valid session.
+ * OIDC sessions are represented only by the backend's HttpOnly cookie; local
+ * sessions retain their existing bearer token until /auth/me validates it.
+ */
+export async function bootstrapAuth(): Promise<void> {
+  const store = useAuthStore.getState()
+
+  try {
+    const { data: config } = await authApi.config()
+    store.setAuthConfig(config.mode, config.oidc_login_url)
+
+    const token = useAuthStore.getState().token
+    if (config.mode === 'oidc' || token) {
+      try {
+        const { data: user } = await authApi.me()
+        useAuthStore.getState().authenticate(user)
+      } catch {
+        // The response interceptor clears invalid credentials on 401. Also
+        // clear them for malformed/unreachable session checks, failing closed.
+        useAuthStore.getState().logout()
+      }
+    }
+  } catch {
+    // Keep authMode unknown when discovery is unreachable. The login screen
+    // reports that state without guessing which authentication mode is active.
+  } finally {
+    useAuthStore.getState().finishInitialization()
+  }
+}

frontend/src/components/LiveView.tsx

@@ -27,13 +27,13 @@ import { useThemeStore } from '@/stores/themeStore'
 import { THEMES } from '@/utils/themes'
 import { nodeTypes } from '@/components/canvas/nodes/nodeTypes'
 import { edgeTypes } from '@/components/canvas/edges/edgeTypes'
-import { deserializeApiNode, deserializeApiEdge, type ApiNode, type ApiEdge } from '@/utils/canvasSerializer'
+import { deserializeApiNode, deserializeApiEdge, migrateClusterHandles, type ApiNode, type ApiEdge } from '@/utils/canvasSerializer'
 import { computeCollapseInfo, rewireEdgesForCollapse } from '@/utils/collapseFilter'
 import { liveviewApi } from '@/api/client'
+import * as standaloneStorage from '@/utils/standaloneStorage'
 import type { NodeData, CustomStyleDef } from '@/types'
 
 const STANDALONE = import.meta.env.VITE_STANDALONE === 'true'
-const STORAGE_KEY = 'homelable_canvas'
 
 type ViewState = 'loading' | 'disabled' | 'invalid-key' | 'no-key' | 'network-error' | 'ready'
 
@@ -55,14 +55,16 @@ function LiveViewCanvas() {
 
   useEffect(() => {
     if (STANDALONE) {
-      try {
-        const saved = localStorage.getItem(STORAGE_KEY)
-        if (saved) {
-          const { nodes: savedNodes, edges: savedEdges } = JSON.parse(saved)
-          loadCanvas(savedNodes, savedEdges)
-        }
-      } catch {
-        // empty canvas on parse error — show empty canvas
+      // ?design=<id> selects which canvas to render; fall back to the first
+      // design when omitted. Standalone stores full React Flow nodes/edges, so
+      // no API deserialization is needed.
+      const designId = new URLSearchParams(window.location.search).get('design')
+        ?? standaloneStorage.listDesigns()[0]?.id
+      const saved = designId ? standaloneStorage.loadCanvas(designId) : null
+      if (saved) {
+        if (saved.theme_id) setTheme(saved.theme_id)
+        if (saved.custom_style) setCustomStyle(saved.custom_style)
+        loadCanvas(saved.nodes, saved.edges)
       }
       return
     }
@@ -86,10 +88,11 @@ function LiveViewCanvas() {
         const savedTheme = res.data.viewport?.theme_id
         if (savedTheme) setTheme(savedTheme)
         if (res.data.custom_style) setCustomStyle(res.data.custom_style as CustomStyleDef)
-        loadCanvas(
+        const migrated = migrateClusterHandles(
           (apiNodes as ApiNode[]).map((n) => deserializeApiNode(n, proxmoxMap)),
           (apiEdges as ApiEdge[]).map(deserializeApiEdge),
         )
+        loadCanvas(migrated.nodes, migrated.edges)
         setViewState('ready')
       })
       .catch((err) => {

frontend/src/components/LoginPage.tsx

@@ -1,17 +1,19 @@
 import { useState } from 'react'
-import { Network, Loader2 } from 'lucide-react'
-import { Button } from '@/components/ui/button'
+import { Loader2 } from 'lucide-react'
+import { Button, buttonVariants } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
+import { Logo } from '@/components/ui/Logo'
 import { authApi } from '@/api/client'
 import { useAuthStore } from '@/stores/authStore'
+import { cn } from '@/lib/utils'
 
 export function LoginPage() {
   const [username, setUsername] = useState('')
   const [password, setPassword] = useState('')
   const [error, setError] = useState('')
   const [loading, setLoading] = useState(false)
-  const login = useAuthStore((s) => s.login)
+  const { authMode, oidcLoginUrl, login } = useAuthStore()
 
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault()
@@ -42,62 +44,92 @@ export function LoginPage() {
       <div className="relative w-full max-w-sm px-4">
         {/* Logo */}
         <div className="flex flex-col items-center gap-3 mb-8">
-          <div className="flex items-center justify-center w-14 h-14 rounded-xl bg-[#00d4ff]/10 border border-[#00d4ff]/20">
-            <Network size={28} className="text-[#00d4ff]" />
-          </div>
+          <Logo size={64} showText={false} />
           <div className="text-center">
-            <h1 className="text-xl font-semibold text-foreground tracking-wide">Homelable</h1>
+            <h1 className="text-xl font-semibold tracking-tight">
+              <span className="text-[#e6edf3]">Home</span>
+              <span className="text-[#00d4ff]">lable</span>
+            </h1>
             <p className="text-xs text-muted-foreground mt-0.5">HomeLab Visualizer</p>
           </div>
         </div>
 
-        {/* Form */}
-        <form
-          onSubmit={handleSubmit}
-          className="flex flex-col gap-4 bg-[#161b22] border border-[#30363d] rounded-xl p-6"
-        >
-          <div className="flex flex-col gap-1.5">
-            <Label htmlFor="username" className="text-xs text-muted-foreground">Username</Label>
-            <Input
-              id="username"
-              autoComplete="username"
-              value={username}
-              onChange={(e) => setUsername(e.target.value)}
-              className="bg-[#21262d] border-[#30363d] focus-visible:ring-[#00d4ff]/50 text-sm"
-              placeholder="admin"
-              required
-            />
+        {authMode === 'local' && (
+          <>
+            <form
+              onSubmit={handleSubmit}
+              className="flex flex-col gap-4 bg-[#161b22] border border-[#30363d] rounded-xl p-6"
+            >
+              <div className="flex flex-col gap-1.5">
+                <Label htmlFor="username" className="text-xs text-muted-foreground">Username</Label>
+                <Input
+                  id="username"
+                  autoComplete="username"
+                  value={username}
+                  onChange={(e) => setUsername(e.target.value)}
+                  className="bg-[#21262d] border-[#30363d] focus-visible:ring-[#00d4ff]/50 text-sm"
+                  placeholder="admin"
+                  required
+                />
+              </div>
+
+              <div className="flex flex-col gap-1.5">
+                <Label htmlFor="password" className="text-xs text-muted-foreground">Password</Label>
+                <Input
+                  id="password"
+                  type="password"
+                  autoComplete="current-password"
+                  value={password}
+                  onChange={(e) => setPassword(e.target.value)}
+                  className="bg-[#21262d] border-[#30363d] focus-visible:ring-[#00d4ff]/50 text-sm"
+                  required
+                />
+              </div>
+
+              {error && (
+                <p className="text-xs text-[#f85149] text-center">{error}</p>
+              )}
+
+              <Button
+                type="submit"
+                disabled={loading}
+                className="mt-1 bg-[#00d4ff] text-[#0d1117] hover:bg-[#00d4ff]/90 font-medium"
+              >
+                {loading ? <Loader2 size={15} className="animate-spin" /> : 'Sign in'}
+              </Button>
+            </form>
+
+            <p className="text-center text-[10px] text-muted-foreground/40 mt-4">
+              Credentials configured in <span className="font-mono">.env</span>
+            </p>
+          </>
+        )}
+
+        {authMode === 'oidc' && (
+          <div className="flex flex-col gap-4 bg-[#161b22] border border-[#30363d] rounded-xl p-6 text-center">
+            <p className="text-sm text-muted-foreground">
+              Continue through the configured OpenID Connect provider.
+            </p>
+            <a
+              href={oidcLoginUrl ?? '/api/v1/auth/oidc/login'}
+              className={cn(
+                buttonVariants(),
+                'bg-[#00d4ff] text-[#0d1117] hover:bg-[#00d4ff]/90 font-medium',
+              )}
+            >
+              Sign in with OpenID Connect
+            </a>
           </div>
+        )}
 
-          <div className="flex flex-col gap-1.5">
-            <Label htmlFor="password" className="text-xs text-muted-foreground">Password</Label>
-            <Input
-              id="password"
-              type="password"
-              autoComplete="current-password"
-              value={password}
-              onChange={(e) => setPassword(e.target.value)}
-              className="bg-[#21262d] border-[#30363d] focus-visible:ring-[#00d4ff]/50 text-sm"
-              required
-            />
+        {authMode === null && (
+          <div className="flex flex-col gap-4 bg-[#161b22] border border-[#30363d] rounded-xl p-6 text-center">
+            <p className="text-sm text-[#f85149]">Could not load authentication configuration.</p>
+            <Button type="button" variant="outline" onClick={() => window.location.reload()}>
+              Retry
+            </Button>
           </div>
-
-          {error && (
-            <p className="text-xs text-[#f85149] text-center">{error}</p>
-          )}
-
-          <Button
-            type="submit"
-            disabled={loading}
-            className="mt-1 bg-[#00d4ff] text-[#0d1117] hover:bg-[#00d4ff]/90 font-medium"
-          >
-            {loading ? <Loader2 size={15} className="animate-spin" /> : 'Sign in'}
-          </Button>
-        </form>
-
-        <p className="text-center text-[10px] text-muted-foreground/40 mt-4">
-          Credentials configured in <span className="font-mono">.env</span>
-        </p>
+        )}
       </div>
     </div>
   )

frontend/src/components/__tests__/LiveView.test.tsx

@@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest'
 import { render, screen, waitFor } from '@testing-library/react'
 import { useCanvasStore } from '@/stores/canvasStore'
 import { useThemeStore } from '@/stores/themeStore'
+import * as standaloneStorage from '@/utils/standaloneStorage'
 
 // ── Mock heavy dependencies ────────────────────────────────────────────────
 
@@ -213,9 +214,13 @@ describe('LiveView (non-standalone)', () => {
 
 // ── Standalone mode ────────────────────────────────────────────────────────
 
+// Captures props from the re-imported (resetModules) ReactFlow so standalone
+// tests can assert which nodes were rendered without reaching into the fresh
+// canvas-store module instance.
+let standaloneRfProps: Record<string, unknown> = {}
 const XYFLOW_MOCK = {
   ReactFlowProvider: ({ children }: { children: React.ReactNode }) => <>{children}</>,
-  ReactFlow: () => <div data-testid="react-flow" />,
+  ReactFlow: (props: Record<string, unknown>) => { standaloneRfProps = props; return <div data-testid="react-flow" /> },
   Background: () => null,
   Controls: () => null,
   BackgroundVariant: { Dots: 'dots' },
@@ -235,16 +240,45 @@ describe('LiveView (standalone — localStorage)', () => {
     vi.unstubAllEnvs()
   })
 
-  it('loads canvas from localStorage without calling the API', async () => {
-    const stored = {
+  it('loads the active design canvas from localStorage without calling the API', async () => {
+    const design = standaloneStorage.createDesign('Main')
+    standaloneStorage.saveCanvas(design.id, {
       nodes: [{
         id: 'ls-node', type: 'router',
         position: { x: 10, y: 20 },
         data: { label: 'Router', type: 'router', status: 'unknown', services: [] },
       }],
       edges: [],
-    }
-    localStorage.setItem('homelable_canvas', JSON.stringify(stored))
+    })
+
+    vi.stubEnv('VITE_STANDALONE', 'true')
+    vi.resetModules()
+    const mockLoad = vi.fn()
+    vi.doMock('@xyflow/react', () => XYFLOW_MOCK)
+    vi.doMock('@xyflow/react/dist/style.css', () => ({}))
+    vi.doMock('@/api/client', () => ({ liveviewApi: { load: mockLoad } }))
+    const { default: LiveViewStandalone } = await import('../LiveView')
+
+    setSearch(`?design=${design.id}`)
+    render(<LiveViewStandalone />)
+
+    await waitFor(() => {
+      expect(screen.getByTestId('react-flow')).toBeDefined()
+    })
+    expect((standaloneRfProps.nodes as { id: string }[]).map((n) => n.id)).toContain('ls-node')
+    expect(mockLoad).not.toHaveBeenCalled()
+  })
+
+  it('falls back to the first design when no ?design= param is given', async () => {
+    const design = standaloneStorage.createDesign('Only')
+    standaloneStorage.saveCanvas(design.id, {
+      nodes: [{
+        id: 'fb-node', type: 'server',
+        position: { x: 0, y: 0 },
+        data: { label: 'Srv', type: 'server', status: 'unknown', services: [] },
+      }],
+      edges: [],
+    })
 
     vi.stubEnv('VITE_STANDALONE', 'true')
     vi.resetModules()
@@ -260,6 +294,7 @@ describe('LiveView (standalone — localStorage)', () => {
     await waitFor(() => {
       expect(screen.getByTestId('react-flow')).toBeDefined()
     })
+    expect((standaloneRfProps.nodes as { id: string }[]).map((n) => n.id)).toContain('fb-node')
     expect(mockLoad).not.toHaveBeenCalled()
   })
 

frontend/src/components/__tests__/LoginPage.test.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest'
-import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { act, render, screen, fireEvent, waitFor } from '@testing-library/react'
 import { LoginPage } from '../LoginPage'
 import { useAuthStore } from '@/stores/authStore'
 
@@ -13,7 +13,12 @@ import { authApi } from '@/api/client'
 
 describe('LoginPage', () => {
   beforeEach(() => {
-    useAuthStore.setState({ token: null, isAuthenticated: false })
+    useAuthStore.setState({
+      token: null,
+      isAuthenticated: false,
+      authMode: 'local',
+      oidcLoginUrl: null,
+    })
     vi.mocked(authApi.login).mockReset()
   })
 
@@ -30,6 +35,41 @@ describe('LoginPage', () => {
     expect(screen.getByRole('button', { name: /sign in/i })).toBeDefined()
   })
 
+  it('renders the official Homelable logo mark — not a generic lucide icon', () => {
+    render(<LoginPage />)
+    const svg = screen.getByTestId('logo-mark')
+    // The official mark from docs/logo/icon.svg, not lucide's Network glyph
+    expect(svg.querySelector('path')?.getAttribute('d'))
+      .toBe('M32 11 L53 30 L48 30 L48 53 L16 53 L16 30 L11 30 Z')
+    expect(svg.classList.contains('lucide')).toBe(false)
+    expect(screen.getByRole('heading', { level: 1 })).toHaveTextContent('Homelable')
+    expect(screen.getByText('HomeLab Visualizer')).toBeDefined()
+  })
+
+  it('renders only the provider redirect in OIDC mode', () => {
+    useAuthStore.setState({
+      authMode: 'oidc',
+      oidcLoginUrl: '/api/v1/auth/oidc/login',
+    })
+
+    render(<LoginPage />)
+
+    expect(screen.queryByLabelText('Username')).toBeNull()
+    expect(screen.queryByLabelText('Password')).toBeNull()
+    expect(screen.getByRole('link', { name: 'Sign in with OpenID Connect' }))
+      .toHaveAttribute('href', '/api/v1/auth/oidc/login')
+  })
+
+  it('does not guess an auth mode when discovery failed', () => {
+    useAuthStore.setState({ authMode: null })
+
+    render(<LoginPage />)
+
+    expect(screen.getByText('Could not load authentication configuration.')).toBeDefined()
+    expect(screen.queryByLabelText('Username')).toBeNull()
+    expect(screen.getByRole('button', { name: 'Retry' })).toBeDefined()
+  })
+
   // ── Security checks ──────────────────────────────────────────────────────
 
   it('password field type is "password" — not rendered as plain text', () => {
@@ -102,7 +142,9 @@ describe('LoginPage', () => {
     await waitFor(() => {
       expect((screen.getByRole('button', { name: '' }) as HTMLButtonElement).disabled).toBe(true)
     })
-    resolve({ data: { access_token: 'tok' } })
+    await act(async () => {
+      resolve({ data: { access_token: 'tok' } })
+    })
   })
 
   it('calls authApi.login with credentials via POST body (not URL params)', async () => {

frontend/src/components/canvas/CanvasContainer.tsx

@@ -22,6 +22,7 @@ import { nodeTypes } from './nodes/nodeTypes'
 import { edgeTypes } from './edges/edgeTypes'
 import { SearchBar } from './SearchBar'
 import { AlignmentGuides } from './AlignmentGuides'
+import { FloorMapLayer } from './FloorMapLayer'
 import { useAlignmentGuides } from '@/hooks/useAlignmentGuides'
 import { setViewportCenterProjector } from '@/utils/viewportCenter'
 import type { NodeData, EdgeData } from '@/types'
@@ -33,10 +34,10 @@ interface CanvasContainerProps {
   onNodeDragStart?: () => void
   onRequestAddToGroup?: (payload: { nodeId: string; groupId: string }) => void
   onRequestAddToContainer?: (payload: { nodeId: string; containerId: string }) => void
-  onOpenPending?: (deviceId: string) => void
+  onOpenInventory?: (deviceId: string) => void
 }
 
-export function CanvasContainer({ onConnect: onConnectProp, onEdgeDoubleClick, onNodeDoubleClick, onNodeDragStart, onRequestAddToGroup, onRequestAddToContainer, onOpenPending }: CanvasContainerProps) {
+export function CanvasContainer({ onConnect: onConnectProp, onEdgeDoubleClick, onNodeDoubleClick, onNodeDragStart, onRequestAddToGroup, onRequestAddToContainer, onOpenInventory }: CanvasContainerProps) {
   const [lassoMode, setLassoMode] = useState(true)
   const {
     nodes, edges,
@@ -191,6 +192,7 @@ export function CanvasContainer({ onConnect: onConnectProp, onEdgeDoubleClick, o
         colorMode={theme.colors.reactFlowColorMode}
         elevateNodesOnSelect={false}
         connectionMode={ConnectionMode.Loose}
+        connectionRadius={30}
         isValidConnection={isValidConnection}
       >
         <Background
@@ -199,7 +201,8 @@ export function CanvasContainer({ onConnect: onConnectProp, onEdgeDoubleClick, o
           size={1}
           color={theme.colors.canvasDotColor}
         />
-        <SearchBar onOpenPending={onOpenPending} />
+        <FloorMapLayer />
+        <SearchBar onOpenInventory={onOpenInventory} />
         <AlignmentGuides guides={guides} />
         <Controls>
           <ControlButton

frontend/src/components/canvas/FloorMapLayer.tsx

@@ -0,0 +1,181 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { ViewportPortal, useReactFlow, useStore } from '@xyflow/react'
+import { useCanvasStore } from '@/stores/canvasStore'
+
+interface ResizeState {
+  startMouseX: number
+  startMouseY: number
+  startX: number
+  startY: number
+  startW: number
+  startH: number
+  edges: Set<'n' | 's' | 'e' | 'w'>
+}
+
+/**
+ * Floor plan background rendered INSIDE the React Flow viewport (via
+ * ViewportPortal) so it pans and zooms together with the nodes. Position and
+ * size are stored in flow coordinates.
+ *
+ * It always sits at the bottom of the canvas (behind nodes and edges). When
+ * unlocked it can still be grabbed/resized in areas not covered by a node;
+ * resize handles appear only while it is selected. Double-clicking an unlocked
+ * plan opens its edit modal.
+ */
+export function FloorMapLayer() {
+  const floorMap = useCanvasStore((s) => s.floorMap)
+  const updateFloorMap = useCanvasStore((s) => s.updateFloorMap)
+  const requestFloorMapEdit = useCanvasStore((s) => s.requestFloorMapEdit)
+  const { screenToFlowPosition } = useReactFlow()
+  const zoom = useStore((s) => s.transform[2])
+
+  const resizeRef = useRef<ResizeState | null>(null)
+  const wrapperRef = useRef<HTMLDivElement>(null)
+  const [selected, setSelected] = useState(false)
+
+  const locked = floorMap?.locked ?? false
+
+  // While selected (and unlocked), deselect on any click outside the plan.
+  // A locked plan can't be selected, and handles/edit are gated on !locked, so
+  // a residual selection is harmless.
+  useEffect(() => {
+    if (locked || !selected) return
+    const onDocDown = (ev: MouseEvent) => {
+      if (!wrapperRef.current?.contains(ev.target as Node)) setSelected(false)
+    }
+    document.addEventListener('mousedown', onDocDown)
+    return () => document.removeEventListener('mousedown', onDocDown)
+  }, [selected, locked])
+
+  const onDragStart = useCallback((e: React.MouseEvent) => {
+    if (!floorMap) return
+    e.stopPropagation()
+    setSelected(true)
+    const startX = e.clientX
+    const startY = e.clientY
+    const origPosX = floorMap.posX
+    const origPosY = floorMap.posY
+
+    const onMove = (ev: MouseEvent) => {
+      const start = screenToFlowPosition({ x: startX, y: startY })
+      const cur = screenToFlowPosition({ x: ev.clientX, y: ev.clientY })
+      updateFloorMap({ posX: origPosX + (cur.x - start.x), posY: origPosY + (cur.y - start.y) })
+    }
+    const onUp = () => {
+      window.removeEventListener('mousemove', onMove)
+      window.removeEventListener('mouseup', onUp)
+    }
+    window.addEventListener('mousemove', onMove)
+    window.addEventListener('mouseup', onUp)
+  }, [floorMap, updateFloorMap, screenToFlowPosition])
+
+  const onResizeStart = useCallback((e: React.MouseEvent, edges: Set<'n' | 's' | 'e' | 'w'>) => {
+    if (!floorMap) return
+    e.stopPropagation()
+    resizeRef.current = {
+      startMouseX: e.clientX,
+      startMouseY: e.clientY,
+      startX: floorMap.posX,
+      startY: floorMap.posY,
+      startW: floorMap.width,
+      startH: floorMap.height,
+      edges,
+    }
+
+    const onMove = (ev: MouseEvent) => {
+      const rs = resizeRef.current
+      if (!rs) return
+      const start = screenToFlowPosition({ x: rs.startMouseX, y: rs.startMouseY })
+      const cur = screenToFlowPosition({ x: ev.clientX, y: ev.clientY })
+      const dx = cur.x - start.x
+      const dy = cur.y - start.y
+      let x = rs.startX, y = rs.startY, w = rs.startW, h = rs.startH
+      if (rs.edges.has('w')) { x += dx; w -= dx }
+      if (rs.edges.has('e')) w += dx
+      if (rs.edges.has('n')) { y += dy; h -= dy }
+      if (rs.edges.has('s')) h += dy
+      const MIN = 80
+      if (w < MIN) {
+        if (rs.edges.has('w')) x = rs.startX + rs.startW - MIN
+        w = MIN
+      }
+      if (h < MIN) {
+        if (rs.edges.has('n')) y = rs.startY + rs.startH - MIN
+        h = MIN
+      }
+      updateFloorMap({ posX: x, posY: y, width: w, height: h })
+    }
+    const onUp = () => {
+      resizeRef.current = null
+      window.removeEventListener('mousemove', onMove)
+      window.removeEventListener('mouseup', onUp)
+    }
+    window.addEventListener('mousemove', onMove)
+    window.addEventListener('mouseup', onUp)
+  }, [floorMap, updateFloorMap, screenToFlowPosition])
+
+  if (!floorMap || !floorMap.enabled) return null
+
+  const { imageData, posX, posY, width, height, opacity } = floorMap
+
+  // Handles live in flow space, so counter-scale by zoom to keep a ~constant
+  // on-screen size regardless of the current zoom level.
+  const hsz = 10 / zoom
+  const half = hsz / 2
+  const hs: React.CSSProperties = {
+    position: 'absolute',
+    width: hsz,
+    height: hsz,
+    background: '#00d4ff',
+    border: `${2 / zoom}px solid #0d1117`,
+    borderRadius: 2 / zoom,
+    zIndex: 10,
+  }
+
+  return (
+    <ViewportPortal>
+      <div
+        ref={wrapperRef}
+        style={{
+          position: 'absolute',
+          left: posX,
+          top: posY,
+          width,
+          height,
+          opacity,
+          // Always at the bottom of the canvas, behind nodes and edges.
+          zIndex: -1,
+          pointerEvents: locked ? 'none' : 'auto',
+          cursor: locked ? 'default' : 'move',
+        }}
+        onMouseDown={locked ? undefined : onDragStart}
+        onDoubleClick={locked ? undefined : (e) => { e.stopPropagation(); requestFloorMapEdit() }}
+      >
+        <img
+          src={imageData}
+          alt="Floor plan"
+          draggable={false}
+          style={{
+            width: '100%',
+            height: '100%',
+            objectFit: 'fill',
+            pointerEvents: 'none',
+            userSelect: 'none',
+          }}
+        />
+        {!locked && selected && (
+          <>
+            <div style={{ ...hs, cursor: 'nw-resize', top: -half, left: -half }} onMouseDown={(e) => onResizeStart(e, new Set(['n','w']))} />
+            <div style={{ ...hs, cursor: 'n-resize', top: -half, left: '50%', marginLeft: -half }} onMouseDown={(e) => onResizeStart(e, new Set(['n']))} />
+            <div style={{ ...hs, cursor: 'ne-resize', top: -half, right: -half }} onMouseDown={(e) => onResizeStart(e, new Set(['n','e']))} />
+            <div style={{ ...hs, cursor: 'e-resize', top: '50%', marginTop: -half, right: -half }} onMouseDown={(e) => onResizeStart(e, new Set(['e']))} />
+            <div style={{ ...hs, cursor: 'se-resize', bottom: -half, right: -half }} onMouseDown={(e) => onResizeStart(e, new Set(['s','e']))} />
+            <div style={{ ...hs, cursor: 's-resize', bottom: -half, left: '50%', marginLeft: -half }} onMouseDown={(e) => onResizeStart(e, new Set(['s']))} />
+            <div style={{ ...hs, cursor: 'sw-resize', bottom: -half, left: -half }} onMouseDown={(e) => onResizeStart(e, new Set(['s','w']))} />
+            <div style={{ ...hs, cursor: 'w-resize', top: '50%', marginTop: -half, left: -half }} onMouseDown={(e) => onResizeStart(e, new Set(['w']))} />
+          </>
+        )}
+      </div>
+    </ViewportPortal>
+  )
+}

frontend/src/components/canvas/SearchBar.tsx

@@ -4,23 +4,23 @@ import { Search, X } from 'lucide-react'
 import { useCanvasStore } from '@/stores/canvasStore'
 import { scanApi } from '@/api/client'
 import { NODE_TYPE_LABELS } from '@/types'
-import type { PendingDevice } from '@/components/modals/PendingDeviceModal'
+import type { InventoryEntry } from '@/components/modals/InventoryDeviceModal'
 
 interface SearchBarProps {
-  onOpenPending?: (deviceId: string) => void
+  onOpenInventory?: (deviceId: string) => void
 }
 
-export function SearchBar({ onOpenPending }: SearchBarProps) {
+export function SearchBar({ onOpenInventory }: SearchBarProps) {
   const [open, setOpen] = useState(false)
   const [query, setQuery] = useState('')
-  const [pendingDevices, setPendingDevices] = useState<PendingDevice[]>([])
+  const [inventoryDevices, setInventoryEntrys] = useState<InventoryEntry[]>([])
   const inputRef = useRef<HTMLInputElement>(null)
   const { nodes, setSelectedNode } = useCanvasStore()
   const { setCenter } = useReactFlow()
 
   useEffect(() => {
     if (!open) return
-    scanApi.pending().then((res) => setPendingDevices(res.data)).catch(() => {})
+    scanApi.pending().then((res) => setInventoryEntrys(res.data)).catch(() => {})
   }, [open])
 
   useEffect(() => {
@@ -43,20 +43,50 @@ export function SearchBar({ onOpenPending }: SearchBarProps) {
   }, [open])
 
   const q = query.toLowerCase().trim()
+
   const nodeResults = q
-    ? nodes.filter((n) => {
-        if (n.data.type === 'groupRect') return false
-        return (
-          n.data.label?.toLowerCase().includes(q) ||
-          n.data.ip?.toLowerCase().includes(q) ||
-          n.data.hostname?.toLowerCase().includes(q) ||
-          (n.data.services ?? []).some((s) => s.service_name?.toLowerCase().includes(q))
-        )
+    ? nodes.flatMap((n) => {
+        if (n.data.type === 'groupRect') return []
+
+        const contains = (v?: string | null) => v?.toLowerCase().includes(q)
+
+        const matches: Array<{ key: string; display_value: string }> = []
+
+        // Label matches make the node a result, but it is already shown in the
+        // header — don't repeat it in the matched-values column.
+        const labelMatch = contains(n.data.label)
+
+        for (const [key, value] of [
+          ['notes', n.data.notes],
+          ['ip', n.data.ip],
+          ['hostname', n.data.hostname],
+        ] as const) {
+          if (contains(value)) {
+            matches.push({ key, display_value: value ?? '' })
+          }
+        }
+
+        for (const s of n.data.services ?? []) {
+          if (contains(s.service_name)) {
+            matches.push({ key: 'services', display_value: s.service_name ?? '' })
+          }
+        }
+
+        for (const p of (n.data.properties ?? []).filter((p) => p.visible)) {
+          if (contains(p.key) || contains(p.value)) {
+            matches.push({
+              key: 'properties',
+              display_value: `${p.key ?? ''} = ${p.value ?? ''}`,
+            })
+          }
+        }
+
+        return labelMatch || matches.length > 0 ? [{ node: n, matches }] : []
       })
     : []
 
   const pendingResults = q
-    ? pendingDevices.filter((d) =>
+    ? inventoryDevices.filter((d) =>
         d.ip?.toLowerCase().includes(q) ||
         d.hostname?.toLowerCase().includes(q) ||
         d.friendly_name?.toLowerCase().includes(q) ||
@@ -142,10 +172,10 @@ export function SearchBar({ onOpenPending }: SearchBarProps) {
 
         {totalResults > 0 && (
           <div style={{ borderTop: '1px solid #30363d', maxHeight: 260, overflowY: 'auto' }}>
-            {nodeResults.map((n) => (
+            {nodeResults.map((n, idx) => (
               <button
-                key={n.id}
-                onClick={() => goToNode(n.id)}
+                key={`${n.node.id}-${idx}`}
+                onClick={() => goToNode(n.node.id)}
                 style={{
                   width: '100%',
                   display: 'flex',
@@ -161,15 +191,19 @@ export function SearchBar({ onOpenPending }: SearchBarProps) {
                 onMouseLeave={(e) => (e.currentTarget.style.background = 'none')}
               >
                 <span style={{ fontSize: 12, fontWeight: 600, color: '#e6edf3', flex: 1, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
-                  {n.data.label}
+                  {n.node.data.label}
                 </span>
-                {n.data.ip && (
-                  <span style={{ fontSize: 11, color: '#8b949e', fontFamily: 'JetBrains Mono, monospace', flexShrink: 0 }}>
-                    {n.data.ip}
+                {n.matches.length > 0 && (
+                  <span style={{ maxWidth: "50%", display: 'flex', flexDirection: 'column', gap: 2, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                    {n.matches.map((m, mIdx) => (
+                      <span key={`${m.key}-${mIdx}`} style={{ fontSize: 11, color: '#8b949e', fontFamily: 'JetBrains Mono, monospace', flexShrink: 0, display: 'inline-block' }}>
+                        {m.display_value}
+                      </span>
+                    ))}
                   </span>
                 )}
                 <span style={{ fontSize: 10, color: '#6e7681', flexShrink: 0 }}>
-                  {NODE_TYPE_LABELS[n.data.type] ?? n.data.type}
+                  {NODE_TYPE_LABELS[n.node.data.type] ?? n.node.data.type}
                 </span>
               </button>
             ))}
@@ -181,7 +215,7 @@ export function SearchBar({ onOpenPending }: SearchBarProps) {
               return (
                 <button
                   key={d.id}
-                  onClick={() => { onOpenPending?.(d.id); setOpen(false); setQuery('') }}
+                  onClick={() => { onOpenInventory?.(d.id); setOpen(false); setQuery('') }}
                   style={{
                     width: '100%',
                     display: 'flex',

frontend/src/components/canvas/__tests__/BaseNode.test.tsx

@@ -9,7 +9,7 @@ let mockZoom = 1
 
 vi.mock('@xyflow/react', () => ({
   Handle: () => null,
-  Position: { Top: 'top', Bottom: 'bottom' },
+  Position: { Top: 'top', Bottom: 'bottom', Left: 'left', Right: 'right' },
   NodeResizer: () => null,
   useUpdateNodeInternals: () => vi.fn(),
   useViewport: () => ({ zoom: mockZoom }),
@@ -44,9 +44,11 @@ vi.mock('@/utils/nodeColors', () => ({
   resolveNodeColors: () => ({ background: '#161b22', border: '#30363d', icon: '#00d4ff' }),
 }))
 
-vi.mock('@/utils/nodeIcons', () => ({
+// Partial mock: node-type icon resolution is stubbed, but the brand/lucide
+// resolver stays real so service icons render as they do in the app.
+vi.mock('@/utils/nodeIcons', async (importActual) => ({
+  ...(await importActual<typeof import('@/utils/nodeIcons')>()),
   resolveNodeIcon: (_typeIcon: unknown) => _typeIcon,
-  isBrandIconKey: (k: string | undefined) => !!k && k.startsWith('brand:'),
 }))
 
 vi.mock('@/utils/maskIp', () => ({
@@ -59,14 +61,9 @@ vi.mock('@/utils/propertyIcons', () => ({
   resolvePropertyIcon: (icon: string | null) => icon ? Server : null,
 }))
 
-vi.mock('@/utils/handleUtils', () => ({
-  bottomHandleId: (idx: number) => idx === 0 ? 'bottom' : `bottom-${idx + 1}`,
-  bottomHandlePositions: (count: number) => {
-    const c = typeof count === 'number' && count > 0 ? Math.floor(count) : 1
-    return Array.from({ length: c }, (_, i) => ((i + 1) * 100) / (c + 1))
-  },
-  clampBottomHandles: (n: unknown) => typeof n === 'number' ? n : 1,
-}))
+// handleUtils is pure — use the real implementation so the side-generic API
+// (SIDES, handleId, handlePositions, sideHandleCount, …) stays in sync.
+vi.mock('@/utils/handleUtils', async (importOriginal) => await importOriginal())
 
 beforeEach(() => { mockZoom = 1 })
 
@@ -124,6 +121,14 @@ describe('BaseNode — borderWidth zoom scaling', () => {
     expect((container.firstChild as HTMLElement).style.borderWidth).toBe('1px')
   })
 
+  // Regression: the node root must NOT clip its own bounds, otherwise the outer
+  // half of each connection handle (which sits centred on the edge) becomes
+  // non-interactive and the "magnet" snap area is halved.
+  it('root does not clip overflow (keeps handles grabbable)', () => {
+    const { container } = renderBaseNode({})
+    expect((container.firstChild as HTMLElement).className).not.toContain('overflow-hidden')
+  })
+
   it('boxShadow glow ring uses borderWidth when selected + online at zoom=0.5', () => {
     mockZoom = 0.5
     const node = makeNode({ status: 'online' })
@@ -176,15 +181,23 @@ describe('BaseNode — properties rendering', () => {
   })
 })
 
-describe('BaseNode — port numbers (issue #20)', () => {
-  it('renders a number above each bottom handle when show_port_numbers is on', () => {
+describe('BaseNode — port numbers (issue #20 / #243)', () => {
+  it('renders a number on each connection point when show_port_numbers is on', () => {
+    // bottom=4 → labels 1..4; top defaults to 1 → an extra "1" on top.
     renderBaseNode({ bottom_handles: 4, show_port_numbers: true })
-    expect(screen.getByText('1')).toBeDefined()
+    expect(screen.getAllByText('1')).toHaveLength(2) // top slot 0 + bottom slot 0
     expect(screen.getByText('2')).toBeDefined()
     expect(screen.getByText('3')).toBeDefined()
     expect(screen.getByText('4')).toBeDefined()
   })
 
+  it('labels left/right connection points too when enabled', () => {
+    // top=1, bottom=1, left=2, right=0 → labels: two "1" (top+bottom) + "2" (left).
+    renderBaseNode({ bottom_handles: 1, left_handles: 2, show_port_numbers: true })
+    expect(screen.getByText('2')).toBeDefined()
+    expect(screen.getAllByText('1')).toHaveLength(3) // top + bottom + left slot 0
+  })
+
   it('does not render port numbers when show_port_numbers is off', () => {
     renderBaseNode({ bottom_handles: 4 })
     expect(screen.queryByText('1')).toBeNull()
@@ -192,8 +205,9 @@ describe('BaseNode — port numbers (issue #20)', () => {
   })
 
   it('numbers match the handle count', () => {
+    // bottom=2 → 1,2; top default 1 adds one more "1"; no "3".
     renderBaseNode({ bottom_handles: 2, show_port_numbers: true })
-    expect(screen.getByText('1')).toBeDefined()
+    expect(screen.getAllByText('1')).toHaveLength(2)
     expect(screen.getByText('2')).toBeDefined()
     expect(screen.queryByText('3')).toBeNull()
   })
@@ -240,6 +254,27 @@ describe('BaseNode — services visibility toggle', () => {
 
     expect(screen.queryByRole('link', { name: /ssh/i })).toBeNull()
   })
+
+  it('renders the brand icon of a service that has one', () => {
+    renderBaseNode({
+      ip: '192.168.1.10',
+      custom_colors: { show_services: true },
+      services: [{ service_name: 'plex', port: 32400, protocol: 'tcp', icon: 'brand:plex' }],
+    })
+
+    const img = screen.getByAltText('plex') as HTMLImageElement
+    expect(img.src).toContain('dashboard-icons/svg/plex.svg')
+  })
+
+  it('renders no service icon when the service has none', () => {
+    renderBaseNode({
+      ip: '192.168.1.10',
+      custom_colors: { show_services: true },
+      services: [{ service_name: 'ssh', port: 22, protocol: 'tcp' }],
+    })
+
+    expect(screen.queryByRole('img')).toBeNull()
+  })
 })
 
 describe('BaseNode — legacy hardware fallback', () => {