chore: bump version to 3.4.0

Version bump to 3.4.0 plus the CHANGELOG entry for the release:
the Documentation space, the rack faceplate owned by the Device
Inventory, Proxmox guest nesting, subpath serving, the MCP rack and
inventory tools, and the fixes since 3.3.5.

ha-relevant: no

.env.example

@@ -1,19 +1,56 @@
 # 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
+# Serve the UI under a subpath instead of the root of the origin, e.g. /homelab/.
+# Read by docker-compose at *build* time (docker compose build frontend), since the
+# prefix is baked into the frontend bundle. See INSTALLATION.md.
+# VITE_BASE_PATH=/homelab/
+
+# 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.
+#     podman-compose does not strip those quotes the way Docker Compose does, so the
+#     backend unwraps one matched pair itself — quoted or not, both work everywhere.
 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"]
 
+# Deep scan (optional) — extra nmap port ranges + HTTP probe for service ID on
+# custom ports. Defaults below are overridable per-scan from the scan dialog.
+# SCANNER_HTTP_RANGES: JSON array of port specs, each a single port "N" or an
+# inclusive range "N-M" (1–65535, N <= M). Not CIDRs, not bare ints.
+# Example: SCANNER_HTTP_RANGES=["8080","9000-9100"]
+SCANNER_HTTP_RANGES=[]
+SCANNER_HTTP_PROBE_ENABLED=false
+SCANNER_HTTP_VERIFY_TLS=false
+
 # Status checker interval in seconds
 STATUS_CHECKER_INTERVAL=60
 
@@ -34,3 +71,45 @@ 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)
+# Seconds to wait for the Z2M bridge to answer a networkmap request. Applies to
+# manual imports too. Raise it on a large mesh (200+ devices can take minutes)
+# if an import fails with "Timed out waiting for networkmap response".
+# ZIGBEE_NETWORKMAP_TIMEOUT=300
+
+# 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)
+# Seconds to wait for the gateway to answer an MQTT request. Same rationale as
+# ZIGBEE_NETWORKMAP_TIMEOUT above.
+# MQTT_RESPONSE_TIMEOUT=300

.github/scripts/audit-with-retry.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+#
+# Run a dependency audit, retrying only when the registry could not be reached.
+#
+# Both `npm audit` and `pip-audit` exit non-zero for two very different reasons:
+# a real advisory, and a registry that would not answer. Only the second is
+# worth a retry — the audit endpoints 503 often enough to redden PRs that
+# changed no dependency at all. An advisory fails on the first attempt, so a
+# vulnerability can never be retried into a pass.
+#
+# Usage: audit-with-retry.sh <command> [args...]
+
+set -uo pipefail
+
+ATTEMPTS=${AUDIT_ATTEMPTS:-3}
+DELAY=${AUDIT_RETRY_DELAY:-30}
+
+# Transport and availability failures, from both npm and pip-audit/urllib3.
+NETWORK_FAILURE='audit endpoint returned an error|service unavailable|max retries exceeded|connectionerror|readtimeout|read timed out|temporary failure in name resolution|50[234] server error|etimedout|econnreset|enotfound|socket hang up|connection reset|remotedisconnected|urlopen error|timeouterror'
+
+for attempt in $(seq 1 "$ATTEMPTS"); do
+  if out=$("$@" 2>&1); then
+    echo "$out"
+    exit 0
+  fi
+  echo "$out"
+
+  if ! grep -qiE "$NETWORK_FAILURE" <<<"$out"; then
+    echo "::error::$1 reported findings — see the output above"
+    exit 1
+  fi
+
+  echo "::warning::$1 could not reach its registry (attempt $attempt/$ATTEMPTS)"
+  if [ "$attempt" -lt "$ATTEMPTS" ]; then sleep "$DELAY"; fi
+done
+
+echo "::error::$1 could not reach its registry after $ATTEMPTS attempts"
+exit 1

.github/workflows/docker-ci.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   smoke-and-integration:
     runs-on: ubuntu-latest

.github/workflows/docker-publish.yml

@@ -16,14 +16,21 @@ jobs:
       matrix:
         include:
           - image: ghcr.io/pouzor/homelable-backend
+            context: .
             dockerfile: Dockerfile.backend
             build_args: ""
           - image: ghcr.io/pouzor/homelable-frontend
+            context: .
             dockerfile: Dockerfile.frontend
             build_args: ""
           - image: ghcr.io/pouzor/homelable-frontend-standalone
+            context: .
             dockerfile: Dockerfile.frontend
             build_args: "VITE_STANDALONE=true"
+          - image: ghcr.io/pouzor/homelable-mcp
+            context: ./mcp
+            dockerfile: Dockerfile.mcp
+            build_args: ""
 
     steps:
       - uses: actions/checkout@v4
@@ -55,8 +62,8 @@ jobs:
       - name: Build and push
         uses: docker/build-push-action@v6
         with:
-          context: .
-          file: ${{ matrix.dockerfile }}
+          context: ${{ matrix.context }}
+          file: ${{ matrix.context }}/${{ matrix.dockerfile }}
           platforms: linux/amd64,linux/arm64
           push: true
           tags: ${{ steps.meta.outputs.tags }}

.github/workflows/install-smoke.yml

@@ -0,0 +1,131 @@
+name: Install smoke test
+
+# Runs scripts/install-baremetal.sh for real, in a clean debian:12 container.
+# ShellCheck reads the script but never executes it, so it cannot catch an
+# unintended `set -euo pipefail` abort — the failure class this job exists for.
+# debian:12 reproduces the two conditions that broke the installer once already:
+# the image carries no Node at all (so the version probe and the nodesource
+# install both run) and the job has no TTY (so the prompt fallbacks run).
+#
+# What it does not cover: systemd. A container has no PID 1 systemd, so
+# `systemctl` is stubbed out and the unit is written but never started. The
+# backend is booted by hand afterwards to prove the generated .env parses.
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'scripts/install-baremetal.sh'
+      - 'backend/requirements.txt'
+      - 'frontend/package.json'
+      - 'frontend/package-lock.json'
+      - '.github/workflows/install-smoke.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'scripts/install-baremetal.sh'
+      - 'backend/requirements.txt'
+      - 'frontend/package.json'
+      - 'frontend/package-lock.json'
+      - '.github/workflows/install-smoke.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  baremetal:
+    runs-on: ubuntu-latest
+    container: debian:12
+    timeout-minutes: 25
+    # Without this the runner hands container steps `sh -e {0}` — dash, where
+    # `set -o pipefail` and `[[ … ]]` are syntax errors.
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Install checkout prerequisites
+        run: |
+          apt-get update -qq
+          DEBIAN_FRONTEND=noninteractive apt-get install -y -qq git ca-certificates >/dev/null
+
+      - uses: actions/checkout@v4
+
+      - name: Confirm the container reproduces a fresh host
+        run: |
+          set -euo pipefail
+          node --version || echo "no node — the nodesource path will run"
+          [ -t 0 ] && echo "TTY present (unexpected)" || echo "no TTY — prompt fallbacks will run"
+
+      - name: Stub systemctl
+        # No PID 1 systemd in a container. The stub logs the calls so the run
+        # shows which unit actions the script attempted.
+        run: |
+          printf '#!/bin/sh\necho "[systemctl stub] $*"\n' > /usr/local/bin/systemctl
+          chmod +x /usr/local/bin/systemctl
+
+      - name: Run the installer
+        # INSTALL_DIR is the checkout, so the clone is skipped and the script
+        # installs the tree under test rather than main. SKIP_NGINX because the
+        # front end is not what this job is asserting.
+        run: |
+          INSTALL_DIR="$GITHUB_WORKSPACE" \
+          SKIP_NGINX=1 \
+          ADMIN_PASSWORD=ci-smoke-password \
+          SCANNER_RANGES='["10.0.0.0/24"]' \
+          bash scripts/install-baremetal.sh
+
+      - name: The generated .env is well formed
+        run: |
+          set -euo pipefail
+          test -f backend/.env
+          grep -qE '^SECRET_KEY=[0-9a-f]{64}$' backend/.env
+          grep -qE '^AUTH_PASSWORD_HASH=.\$2b\$' backend/.env
+          # JSON values must stay single-quoted: systemd's EnvironmentFile
+          # parser strips bare double quotes, which would break the JSON.
+          grep -qE "^CORS_ORIGINS='\\[" backend/.env
+          grep -qE "^SCANNER_RANGES='\\[" backend/.env
+          grep -q "^SQLITE_PATH=$GITHUB_WORKSPACE/data/homelab.db$" backend/.env
+          test "$(stat -c '%a' backend/.env)" = "600"
+
+      - name: The build artefacts and service user exist
+        run: |
+          set -euo pipefail
+          test -x backend/.venv/bin/uvicorn
+          test -f frontend/dist/index.html
+          id homelable
+
+      - name: The systemd unit was written
+        run: |
+          set -euo pipefail
+          test -f /etc/systemd/system/homelable.service
+          grep -q 'ExecStart=.*/uvicorn app.main:app --host 127.0.0.1 --port 8000' \
+            /etc/systemd/system/homelable.service
+          grep -q "EnvironmentFile=$GITHUB_WORKSPACE/backend/.env" \
+            /etc/systemd/system/homelable.service
+
+      - name: The backend boots on the generated config
+        # The unit's own ExecStart, run by hand. Proves the .env pydantic reads
+        # is valid — the assertion that catches config drift.
+        run: |
+          set -euo pipefail
+          cd backend
+          .venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000 &
+          for _ in $(seq 1 30); do
+            if curl -fsS http://127.0.0.1:8000/api/v1/health >/dev/null 2>&1; then
+              echo "backend healthy"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "backend did not answer /api/v1/health within 30s" >&2
+          exit 1
+
+      - name: Re-running is idempotent and keeps .env
+        run: |
+          set -euo pipefail
+          before="$(sha256sum backend/.env)"
+          INSTALL_DIR="$GITHUB_WORKSPACE" SKIP_NGINX=1 \
+            bash scripts/install-baremetal.sh | tee /tmp/run2.log
+          after="$(sha256sum backend/.env)"
+          test "$before" = "$after" || { echo "second run rewrote backend/.env" >&2; exit 1; }
+          grep -q 'keeping existing values' /tmp/run2.log

.github/workflows/quality.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   lint-scripts:
     runs-on: ubuntu-latest
@@ -57,3 +60,23 @@ jobs:
       - run: ruff check .
       - run: mypy app/
       - run: pytest
+
+  # Also guards the copies the MCP server keeps of frontend data against drift:
+  # NODE_TYPES / EDGE_TYPES in mcp/app/tools.py against frontend/src/types/index.ts,
+  # and the faceplate catalog in mcp/app/faceplates.py against
+  # frontend/src/rack/faceplates.ts (test_node_types_sync.py,
+  # test_edge_types_sync.py, test_faceplates_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

@@ -8,6 +8,9 @@ on:
   schedule:
     - cron: '0 9 * * 1'  # Weekly on Monday
 
+permissions:
+  contents: read
+
 jobs:
   secrets-scan:
     runs-on: ubuntu-latest
@@ -19,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
@@ -28,11 +37,20 @@ 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.
+        #
+        # Wrapped so a registry outage retries instead of failing the PR; an
+        # advisory still fails on the first attempt. See the script's header.
+        working-directory: frontend
+        run: "$GITHUB_WORKSPACE/.github/scripts/audit-with-retry.sh 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
+        # pip-audit queries PyPI's advisory API and fails the same way npm does
+        # when it cannot reach it, so it gets the same wrapper.
+        run: |
+          pip install pip-audit
+          "$GITHUB_WORKSPACE/.github/scripts/audit-with-retry.sh" pip-audit -r backend/requirements.txt

.gitignore

@@ -1,6 +1,5 @@
 # Claude / project meta — never commit
 CLAUDE.md
-FEATURES.md
 .claude/
 _project_specs/
 
@@ -46,7 +45,14 @@ htmlcov/
 *.db-shm
 *.db-wal
 *.db.back
+*.db.back-*
 
 # 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,797 @@
+# 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.4.0] - 2026-09-07
+
+### Features
+
+- **Documentation** — a real document space for the homelab, beside the canvases. Markdown documents attached to a device, a node, a canvas, or standing on their own; a Library of folders, a Devices tree pivoted by zone, group, type, subnet, rack, vendor or tag, wiki-links between documents, full-text search (FTS5, with a `LIKE` fallback where SQLite ships without it), up to 50 revisions per document with a line diff and restore, backlinks under every body, tags, and a "needs attention" bucket driven by a per-document review interval. A device document is scaffolded once from the scan facts and then belongs to you — nothing rewrites it — with an explicit "device data changed" banner and a per-block regenerate when you want the new facts. The old `device_inventory.notes` are migrated in verbatim and left in place. (#418, #421)
+- Documents are reachable from where you already are: a node's detail panel, a device's inventory modal, and the canvas search modal, which now finds documents too. Wiki-links are written from a picker instead of from memory. (#418, #421)
+- The rack faceplate is a real, editable object, and the **Device Inventory owns it**: plate, U height, column span, colour and the port list — with each port placed by hand — are carried by the device, so it wears the same panel in every rack it is mounted in. Only placement, pinned status and label stay per canvas. A device's front panel can also be drawn and edited straight from its inventory row. (#405)
+- A rack mount chooses when it shows its ports — `auto`, `always` or `hover` — and a cable can no longer end on a plate drawing no socket. (#407)
+- Proxmox guests can be nested inside their host on the canvas instead of sitting beside it on virtual edges. Both entry points ask: the import modal and adding a Proxmox host from the Device Inventory. (#399)
+- Homelable can be served under a subpath. One build-time knob, `VITE_BASE_PATH`, becomes Vite's `base` and is threaded through every hand-built URL, the status WebSocket, the OIDC login and callback, and both shipped nginx configs. Defaults to `/`, where nothing changes. (#412)
+- The MCP server covers the rack canvas and the Device Inventory writes — 24 tools to 47. Racks, mounts, accessories, moves, faceplates and cables, plus create/edit/delete on inventory entries. (#414)
+- The Homelable logo is in the brand icon picker, first in the catalog, for both node and service icons. (#411)
+
+### Fixes
+
+- The scanner and the status checker no longer send an HTTP `GET` to TCP/9100. A printer speaking JetDirect printed that request as a page of plaintext — once a minute, forever, for an approved node. LPD (515) and JetDirect (9100-9107) are now on the non-HTTP denylist. Trade-off: Prometheus Node Exporter on 9100 loses its status check and shows grey. (#406)
+- A device declaring several IPs is matched on every one of them instead of coming back as a new pending row on each scan. Hiding it hides it at all of its addresses, and the deduplication collapses the duplicates an extra address had already spawned — never deleting a second approved row. (#416)
+- A Proxmox import no longer overwrites one guest's inventory row with another's facts. Identity is now the synthetic per-guest ieee first, then NIC MAC, then IP — and the IP fallback skips rows already claimed by a guest, since a shared VIP, a re-used lease or a CNI bridge address describes several machines. A migrated or renamed guest keeps its row. (#420)
+- Coming back to the canvas from Documentation keeps the pan and zoom you left it at, instead of remounting zoomed in at the origin. (#422)
+- Switching back to a rack canvas restores its saved pan and zoom instead of shrinking the racks into a corner until a hard reload. (#409)
+- The basic edge animation runs the same way whichever direction the nodes were dragged in; the dash direction was derived from the source and target's on-screen geometry. (#402)
+- Login works under `podman-compose`. Quoted `AUTH_PASSWORD_HASH`, `SECRET_KEY` and `OIDC_CLIENT_SECRET` values arrive with their quotes attached, which Docker Compose strips and podman-compose does not; a matched pair of surrounding quotes is now unwrapped in the backend, so one `.env` works under either runtime. (#413)
+- A zone or group description is kept on save. (#418)
+- MCP node properties are keyed on `key`, not `name`, so they no longer collapse silently. (#414)
+- Eight Dependabot advisories cleared in the frontend lockfile (`fast-uri`, `@humanfs/node`, `qs`, `nanoid`); all dev-only, `npm audit` reports zero. (#417)
+- The npm and pip audit CI jobs retry a registry outage instead of failing the run. (#409)
+
+### Docs
+
+- README and FEATURES.md cover the Documentation section, and `docs/documentation.md` documents the tree, wiki-links, search, history, backlinks and the API. (#421)
+- `.env.example` notes that quoting a secret is optional and works either way. (#413)
+
+## [3.3.5] - 2026-08-21
+
+### Features
+
+- Deep-scan a single device from its inventory detail: the Services section gets a **Deep scan** button that sweeps the device over a port range you pick, prefilled with the full 1-65535 range and narrowable when you know where the service lives. The run is a normal Scan Run, so stop, progress and Scan History work as usual, and the fresh services are merged in — never replacing what you added by hand. (#363)
+
+### Fixes
+
+- A deep rescan of a slow host no longer comes back empty. The run hit its timeout and nmap discarded every port it had already found; the full range is now scanned in slices, a partial sweep is reported as partial instead of passed off as complete, and the timeout is a total budget between slices rather than an nmap flag. (#363)
+- A scan no longer repaints the service icons you picked by hand: the fingerprint's guess overwrote your choice, and cleared it outright on a port no signature covers. Since 3.3.0 the inventory row is the only copy, so one scan changed the service on every canvas at once. (#363)
+- A rescan finishing while you edit a device no longer throws the edit away, and it no longer tags every device it touches as network-discovered — a Proxmox guest, a rack mount or a hand-added host keeps its own source. A failed run is also recorded as `error`, the status Scan History filters and colours. (#363)
+- A property with no value gets the full node width for its label instead of being truncated against empty space. (#362)
+- A same-origin OIDC deployment behind a reverse proxy no longer answers 403 to every write. The CSRF check validated the browser's `Origin` against `CORS_ORIGINS` alone; the app's own origin, taken from `OIDC_REDIRECT_URI`, is accepted too, and startup warns when `CORS_ORIGINS` omits it. (#360)
+
+## [3.3.4] - 2026-08-17
+
+### Fixes
+
+- A network scan no longer deletes the services you added by hand. The scanner replaced a device's whole service list with what it fingerprinted, so one scan wiped manual entries on every canvas at once and brought back the ones you had deleted. It merges now. (#347)
+- A node whose services were all replaced under it no longer renders empty: when nothing a node's view names is left on the device, the device's own list is drawn instead of hiding everything. (#347)
+- Properties added while running 3.3.0–3.3.2 survive the 3.3.3 upgrade. The view recovered from the pre-3.3.0 backup could not know about them, so they were hidden on every canvas; they are kept visible, and the per-canvas arrangement the backup does know is still restored. (#347)
+
+## [3.3.3] - 2026-08-17
+
+### Features
+
+- Each node now keeps its own view of a device's services and properties: order and visibility are per node, so a service the scanner fingerprinted no longer appears on every canvas drawing that device, and a property added on one schematic stays there. The facts still live on the inventory row — hiding is per node, deleting is device-wide. Upgrades keep what each canvas showed today. (#357)
+
+### Fixes
+
+- The one-off view seed no longer re-opens the pre-upgrade backup on every boot: a node pointing at a deleted device kept matching the seed query and logged a recovery that recovered nothing. (#357)
+
+## [3.3.2] - 2026-08-17
+
+### Fixes
+
+- Devices upgraded from 3.2.0 keep their ip, services, hostname, notes and hardware. The 3.3.0 migration aborted on timestamps SQLite returns as text, so nothing was carried across to the Device Inventory and every device read back blank. (#347, #348)
+- A canvas saved while an earlier migration was stuck no longer loses its device facts: the migration now fills the blank inventory row that save created, instead of skipping the node and dropping the columns holding its only copy. (#347)
+
+## [3.3.1] - 2026-08-17
+
+### Fixes
+
+- Approving a device no longer fails after an upgrade from 3.2.0: a node the 3.3.0 inventory backfill could not link kept the old device columns on `nodes`, and their NOT NULL constraint rejected every new node. (#352)
+
+## [3.3.0] - 2026-08-15
+
+### Features
+
+- The Device Inventory is now the source of truth for device data: a node reads and edits its facts from its inventory row, and the device sheet is grouped by what a reader is after. (#339)
+- Per-service host override, so a service can point at a host other than the node's own. (#338)
+- A zone now parents the nodes dropped inside it. (#343)
+- Node properties accept an empty value. (#345)
+- Nodes can be given 0 connection points on top and bottom. (#336)
+- KVM switch added as a device type. (#335)
+- The sidebar version row links to the public changelog.
+
+### Fixes
+
+- Alignment guides show for nodes inside groups and containers. (#337)
+- The status check interval is applied to the running scheduler. Thanks @JaG-v2. (#319)
+- Bumped undici and ip-address to patch high severity advisories. (#342)
+
+### Docs
+
+- The pre-built GHCR images are documented in the install guide.
+
+## [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

Dockerfile.frontend

@@ -7,6 +7,12 @@ FROM --platform=$BUILDPLATFORM node:20-slim AS builder
 ARG VITE_STANDALONE=false
 ENV VITE_STANDALONE=$VITE_STANDALONE
 
+# Subpath support: build with VITE_BASE_PATH=/homelab/ to serve Homelable under a
+# prefix instead of the root of an origin. The default '/' produces the same build
+# as before the option existed.
+ARG VITE_BASE_PATH=/
+ENV VITE_BASE_PATH=$VITE_BASE_PATH
+
 WORKDIR /app
 COPY frontend/package*.json ./
 RUN npm ci
@@ -18,15 +24,31 @@ RUN npm run build
 # Stage 2: serve
 FROM nginx:alpine
 
-COPY --from=builder /app/dist /usr/share/nginx/html
+COPY --from=builder /app/dist /tmp/dist
 
-# Nginx config: use standalone config (no backend proxy) or full config
+# Nginx config: standalone (no backend proxy) or full, served at the root or under the
+# VITE_BASE_PATH prefix. At the root the build lands in /usr/share/nginx/html and the
+# shipped .conf is copied verbatim, so an existing deployment gets exactly what it had
+# before this option existed. Under a prefix the build lands in the matching
+# subdirectory, which keeps the generated config on plain `root` semantics.
 ARG VITE_STANDALONE=false
-COPY docker/nginx.conf /etc/nginx/conf.d/default.conf
-COPY docker/nginx.standalone.conf /etc/nginx/conf.d/nginx.standalone.conf
-RUN if [ "$VITE_STANDALONE" = "true" ]; then \
-      cp /etc/nginx/conf.d/nginx.standalone.conf /etc/nginx/conf.d/default.conf; \
-    fi && \
-    rm /etc/nginx/conf.d/nginx.standalone.conf
+ARG VITE_BASE_PATH=/
+COPY docker/nginx.conf docker/nginx.standalone.conf /tmp/nginx-conf/
+COPY docker/nginx.subpath.conf.template docker/nginx.standalone.subpath.conf.template /tmp/nginx-conf/
+# ash with pipefail: the base-path normalization below pipes printf into sed.
+SHELL ["/bin/ash", "-eo", "pipefail", "-c"]
+RUN set -eu; \
+    if [ "$VITE_STANDALONE" = "true" ]; then variant=nginx.standalone; else variant=nginx; fi; \
+    base=$(printf '%s' "${VITE_BASE_PATH:-/}" | sed -e 's#^/*#/#' -e 's#/*$#/#' -e 's#//*#/#g'); \
+    [ -n "$base" ] || base=/; \
+    mkdir -p "/usr/share/nginx/html${base}"; \
+    cp -a /tmp/dist/. "/usr/share/nginx/html${base}"; \
+    if [ "$base" = "/" ]; then \
+      cp "/tmp/nginx-conf/${variant}.conf" /etc/nginx/conf.d/default.conf; \
+    else \
+      sed -e "s#__BASE_NO_SLASH__#${base%/}#g" -e "s#__BASE__#${base}#g" \
+        "/tmp/nginx-conf/${variant}.subpath.conf.template" > /etc/nginx/conf.d/default.conf; \
+    fi; \
+    rm -rf /tmp/dist /tmp/nginx-conf
 
 EXPOSE 80

FEATURES.md

@@ -0,0 +1,312 @@
+# 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. [Documentation](#13-documentation-)
+14. [Live Status Monitoring](#14-live-status-monitoring-)
+15. [Export (PNG / SVG / YAML / Markdown)](#15-export)
+16. [Live View (read-only public canvas)](#16-live-view-)
+17. [Gethomepage Widget](#17-gethomepage-widget-)
+18. [MCP Server (AI integration)](#18-mcp-server-)
+19. [Settings & Shortcuts](#19-settings--shortcuts)
+20. [Authentication (Local / OpenID Connect)](#20-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. Documentation 🔒
+
+**What:** A markdown documentation space for the whole lab. Every device gets a document written once from what the scan actually found — identity, hardware, services, network, operations, troubleshooting — and it is yours from there; nothing rewrites it behind you. Next to it, a Library of pages you write yourself: runbooks, incidents, decisions, a network overview.
+
+**Use:**
+- Sidebar → **Documentation**. The **Devices** root re-pivots instantly by zone, group, type, physical/virtual, subnet, rack, vendor, discovery source, status, tag or A–Z; picking a device with no document writes one from its facts.
+- The **Library** is folders you make. **New page** / **New folder** in the header, drag an item to file it. Templates: blank, runbook, service, network overview, incident, procedure, decision (ADR), zone.
+- Editing is plain markdown and **saving is explicit**, like the canvas. An unsaved body is kept in your browser and offered back if you close the tab. `/` in the editor inserts a freshly generated block — services, hardware, network, rack — from the device's current data.
+- **Link documents** with `[[VLAN plan]]`, `[[device:nas-01]]` or `[[doc:slug|label]]`. Typing `[[` opens a picker that writes the link for you. A link to a document that does not exist yet renders red and offers to create it, and every document lists **Linked from** at the bottom — who points here.
+- **History**: the clock-arrow button in the header lists earlier versions, up to 50 per document. Read one, hit **Changes** for a line-by-line diff against the current body, **Restore** to bring it back — the body it replaces is saved to the history first.
+- **Keeping it honest**: `review_every: 6m` in a document's frontmatter badges it "due for review" when it lapses; a **device data changed** banner appears when the device has moved on since the document was written; **Regenerate** rebuilds a device document from scratch (old body kept in the history). Tags are chips under the title.
+- **Search** the whole space from the box above the tree — title, tags and body. The canvas' own search (Ctrl/Cmd+K) finds documents too, and picking one jumps here.
+- Coming from the old per-device **Notes** field? A banner offers to migrate every device that has one into a document. It copies, it does not move: the `notes` field is left exactly as it was.
+
+> **Full documentation:** [docs/documentation.md](./docs/documentation.md)
+
+---
+
+## 14. 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.
+
+---
+
+## 15. 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.
+
+---
+
+## 16. 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.
+
+---
+
+## 17. 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).
+
+---
+
+## 18. 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/zones/designs/inventory/scans, add/update/delete nodes, edges and zones, kick off scans, triage and edit inventory entries, and work a rack canvas — create racks, mount and move gear, patch cables. Keep port 8001 firewalled to your LAN. Full setup in the [README](./README.md#mcp-server-ai-integration-optional).
+
+---
+
+## 19. 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).
+
+---
+
+## 20. 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
@@ -40,8 +40,75 @@ curl -fsSL https://raw.githubusercontent.com/Pouzor/homelable/main/install.sh |
 cd homelable && docker compose pull && docker compose up -d
 ```
 
+## Pre-built Docker images
+
+The quick starts above never build anything — `install.sh` writes `docker-compose.prebuilt.yml` (or `docker-compose.standalone.yml` with `--standalone`) as your `docker-compose.yml`, and both pull ready-made images. They are published to the GitHub Container Registry on every push to `main` and every `v*` tag, for `linux/amd64` and `linux/arm64`:
+
+| Image | Contents |
+|---|---|
+| [`ghcr.io/pouzor/homelable-backend`](https://github.com/Pouzor/homelable/pkgs/container/homelable-backend) | FastAPI API, scanner, status checker |
+| [`ghcr.io/pouzor/homelable-frontend`](https://github.com/Pouzor/homelable/pkgs/container/homelable-frontend) | React SPA behind nginx, proxying `/api` to the backend |
+| [`ghcr.io/pouzor/homelable-frontend-standalone`](https://github.com/Pouzor/homelable/pkgs/container/homelable-frontend-standalone) | Same SPA built with `VITE_STANDALONE=true` — no backend, canvases in `localStorage` |
+| [`ghcr.io/pouzor/homelable-mcp`](https://github.com/Pouzor/homelable/pkgs/container/homelable-mcp) | MCP server exposing the canvas to AI clients |
+
+Tags: `latest` (tip of `main`), plus `X.Y.Z` and `X.Y` for releases.
+
+To wire it up by hand instead of using `install.sh`:
+
+```bash
+curl -fsSLO https://raw.githubusercontent.com/Pouzor/homelable/main/docker-compose.prebuilt.yml
+curl -fsSL https://raw.githubusercontent.com/Pouzor/homelable/main/.env.example -o .env
+docker compose -f docker-compose.prebuilt.yml up -d
+```
+
+Update the same way: `docker compose -f docker-compose.prebuilt.yml pull && … up -d`.
+
+## Scanning from Docker — MAC addresses
+
+Out of the box the backend runs on a Docker bridge network, and **the scan will
+never report a MAC address** from it. MACs come from ARP, which is layer 2: the
+container's ARP cache holds only the Docker gateway, and nmap can read a target's
+hardware address only when that target sits in the same broadcast domain. From a
+bridge every LAN host is one hop away behind the gateway, so the field stays
+empty. `cap_add: NET_RAW` does not change this — the capability grants raw
+sockets, not a place on the LAN.
+
+This also affects device identity. When a device is rescanned it is matched on
+MAC first and IP second, so without MACs a DHCP lease change makes the device
+come back as a new entry in the inventory instead of updating the old one.
+
+To collect MACs, put the backend on the LAN itself. In `docker-compose.yml` (or
+`docker-compose.prebuilt.yml`), comment out the backend's `networks:` key and
+uncomment:
+
+```yaml
+    network_mode: host
+```
+
+then `docker compose up -d`. Caveats:
+
+- **Linux only.** On Docker Desktop for macOS and Windows the containers run
+  inside a VM, so host networking still does not reach your physical LAN. There
+  is no MAC-capable Docker setup on those platforms — run the
+  [bare-metal install](#bare-metal--no-docker) instead.
+- The backend binds `8000` directly on the host, with no port mapping and no
+  network isolation from other host services.
+- `frontend` and `mcp` reach the backend at `http://backend:8000` over the
+  `homelable` bridge; once the backend leaves that network they need
+  `http://127.0.0.1:8000` instead. Set `BACKEND_URL` on `mcp`, and for the front
+  end either give it `network_mode: host` too or point its nginx proxy at the
+  host address.
+
+The alternative, if you would rather keep the backend isolated, is a **macvlan**
+network, which gives the container its own MAC and IP on your physical LAN.
+It needs a parent interface and a spare address range from your subnet, and on
+most setups the Docker host itself cannot talk to a macvlan container without an
+extra shim interface.
+
 ## Build from source
 
+`docker-compose.yml` at the repo root builds the images locally instead of pulling them — use it for development, or to run a patched tree.
+
 ```bash
 git clone https://github.com/Pouzor/homelable.git
 cd homelable
@@ -64,11 +131,242 @@ bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/Proxmo
 
 ---
 
+## Bare metal — no Docker
+
+`scripts/install-baremetal.sh` installs Homelable natively on a Debian 12+ /
+Ubuntu 22.04+ host (physical, VM or LXC): a Python venv and a `homelable`
+systemd unit for the backend on `127.0.0.1:8000`, the built frontend served by
+nginx on port 3000.
+
+```bash
+git clone https://github.com/Pouzor/homelable.git /opt/homelable
+sudo bash /opt/homelable/scripts/install-baremetal.sh
+```
+
+It prompts for the admin password and the CIDR range to scan, then writes
+`backend/.env` with a generated `SECRET_KEY` and bcrypt hash. Open
+**http://\<host-ip\>:3000**.
+
+The script can also clone for you — run it from anywhere and it fetches the repo
+into `INSTALL_DIR` when that directory is empty. Piped into `bash` there is no
+terminal to prompt on, so pass the two answers as environment variables:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Pouzor/homelable/main/scripts/install-baremetal.sh \
+  | sudo ADMIN_PASSWORD=hunter2 SCANNER_RANGES='["192.168.1.0/24"]' bash
+```
+
+Without them the prompts are skipped and their defaults apply — the password
+becomes `admin` and the range is guessed from the primary interface. The script
+warns when that happens; change the password before exposing the host.
+
+Re-running is safe and is how you upgrade — an existing `backend/.env` is kept
+untouched, everything else is rebuilt:
+
+```bash
+cd /opt/homelable && git pull
+sudo bash scripts/install-baremetal.sh
+```
+
+### Options
+
+Every setting is an environment variable. Setting them all skips every prompt,
+which is what makes an unattended install possible:
+
+```bash
+sudo HTTP_PORT=8080 ADMIN_PASSWORD=hunter2 SCANNER_RANGES='["10.0.0.0/24"]' \
+  bash scripts/install-baremetal.sh
+```
+
+| Variable | Default | What |
+|---|---|---|
+| `INSTALL_DIR` | `/opt/homelable` | Repo root |
+| `REPO_URL` / `REPO_REF` | upstream / `main` | Used only when `INSTALL_DIR` is empty |
+| `SERVICE_USER` | `homelable` | systemd `User=` |
+| `BACKEND_PORT` | `8000` | uvicorn port, bound to loopback |
+| `HTTP_PORT` | `3000` | nginx port |
+| `SERVER_NAME` | `_` | nginx `server_name` |
+| `ADMIN_PASSWORD` | prompt, else `admin` | Initial password for user `admin` |
+| `SCANNER_RANGES` | prompt, else guessed | JSON array of CIDRs |
+| `SKIP_NGINX=1` | off | Do not install or touch nginx |
+| `BASE_PATH` | `/` | Serve under a subpath — see [Serving under a subpath](#serving-under-a-subpath) |
+
+### Afterwards
+
+```bash
+systemctl status homelable
+journalctl -u homelable -f
+```
+
+- Config: `/opt/homelable/backend/.env` — every other option (OIDC, MCP,
+  Proxmox, Zigbee, Z-Wave, live view) is documented in `.env.example`.
+  `systemctl restart homelable` after an edit.
+- Data: `/opt/homelable/data` — SQLite DB and uploads. Back up this folder.
+- nginx site: `/etc/nginx/sites-available/homelable`.
+
+Change the password later:
+
+```bash
+/opt/homelable/backend/.venv/bin/python -c \
+  'import bcrypt; print(bcrypt.hashpw(b"newpassword", bcrypt.gensalt()).decode())'
+# put it in backend/.env as AUTH_PASSWORD_HASH='$2b$12$...' (keep the single quotes)
+systemctl restart homelable
+```
+
+⚠️ Keep JSON values in `backend/.env` single-quoted — `CORS_ORIGINS='["http://…"]'`.
+systemd's `EnvironmentFile` parser strips bare double quotes, which breaks the
+JSON before the backend parses it. This does not apply to the Docker install.
+
+### Scanning as a non-root service
+
+The unit runs as `homelable`, not root, so nmap has no raw sockets and silently
+falls back to a TCP connect scan: hosts and open ports are still found, OS
+detection (`-O`) and SYN scan (`-sS`) are not. To grant them, uncomment in
+`/etc/systemd/system/homelable.service`:
+
+```ini
+AmbientCapabilities=CAP_NET_RAW CAP_NET_ADMIN
+CapabilityBoundingSet=CAP_NET_RAW CAP_NET_ADMIN
+```
+
+then `systemctl daemon-reload && systemctl restart homelable`.
+
+### Your own reverse proxy
+
+With `SKIP_NGINX=1` the script leaves the front end to you: serve
+`/opt/homelable/frontend/dist` as a static SPA and proxy the API to the backend.
+The nginx translation of `docker/nginx.conf` — what the script writes, with
+`backend:8000` replaced by `127.0.0.1:8000`:
+
+```nginx
+server {
+    listen 3000;
+    server_name _;
+    root /opt/homelable/frontend/dist;
+    index index.html;
+
+    client_max_body_size 20M;
+
+    # WebSocket — must come before /api/ to take priority
+    location /api/v1/status/ws/ {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    location /api/ {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    # Legacy /ws/ path
+    location /ws/ {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+    }
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}
+```
+
+Terminating TLS in front of it means adding your own hostname to
+`CORS_ORIGINS` in `backend/.env` (`https://homelable.example`) and restarting
+the service.
+
+---
+
+## Serving under a subpath
+
+By default Homelable owns the root of its origin (`https://homelable.example/`).
+To put it behind an existing reverse proxy on a shared hostname — one cert, one
+dynamic-DNS name, one open port, every service on its own prefix — build it with
+a base path.
+
+The base path is **baked into the build**: the browser has no way to guess it, so
+it cannot be a runtime setting. Changing it means rebuilding the frontend.
+
+### Docker
+
+```bash
+# in .env, next to the backend settings
+VITE_BASE_PATH=/homelab/
+
+docker compose build frontend && docker compose up -d
+```
+
+Homelable then answers on `http://<host>:3000/homelab/`. The generated nginx
+config accepts both reverse-proxy styles, so either of these works in front of
+it:
+
+```nginx
+# prefix forwarded intact — no trailing slash on proxy_pass
+location /homelab/ {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $host;
+}
+
+# or: prefix stripped — trailing slash on proxy_pass
+location /homelab/ {
+    proxy_pass http://127.0.0.1:3000/;
+    ...
+}
+```
+
+The pre-built images (`docker-compose.prebuilt.yml`) are built for the root, so a
+subpath needs a local build.
+
+### Bare metal / LXC
+
+```bash
+sudo BASE_PATH=/homelab/ bash scripts/install-baremetal.sh
+```
+
+The script bakes the prefix into the build and writes the matching nginx site.
+The build stays in `/opt/homelable/frontend/dist`; the site serves it through
+`/var/www/homelable/homelab`, a symlink refreshed on every run. Re-running the
+script with a different `BASE_PATH` (or none) rewrites both.
+
+### Development
+
+```bash
+cd frontend && VITE_BASE_PATH=/homelab/ npm run dev   # http://localhost:5173/homelab/
+```
+
+The Vite dev proxy follows the same prefix and strips it before forwarding to
+uvicorn on `:8000`.
+
+### What to expect
+
+- WebSocket status updates, uploaded floor plans and the read-only live view
+  (`/homelab/view`) all follow the prefix.
+- TLS in front still means adding your hostname to `CORS_ORIGINS` in
+  `backend/.env`, exactly as at the root.
+- OIDC: `OIDC_REDIRECT_URI` must carry the prefix
+  (`https://home.example/homelab/api/v1/auth/oidc/callback`), and so must the
+  redirect URI registered with your provider.
+- Floor plans uploaded before the move keep working — stored URLs are resolved
+  against the base path at render time.
+
+---
+
 ## Configuration
 
 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 +380,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,15 +1,47 @@
-# 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.
 
 Homelable also offers a healthcheck system through multiple methods (ping/TCP, /health API, etc.) to get a global overview of online/offline services.
 
+Every device also gets a **document** — written for you from what the scan found, and yours to maintain from there — next to a Library of pages you write yourself: runbooks, incidents, a network overview. Your homelab stops being documented in a wiki somewhere else.
+
 You can also select some pre-built design styles, or personalize each device in your diagram.
 
 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,17 +49,65 @@ 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 alt="Rack display" src="https://github.com/user-attachments/assets/43273605-4f46-4163-8aea-8bf8a76a3f76" />
 
 </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, a **markdown documentation space** for the whole lab, multi-canvas layouts and an **MCP server** for AI assistants — Homelable maps, documents 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)**.
+Docker (from the **[pre-built GHCR images](./INSTALLATION.md#pre-built-docker-images)**), Proxmox LXC, **[bare metal without Docker](./INSTALLATION.md#bare-metal--no-docker)** (`sudo bash scripts/install-baremetal.sh` — systemd unit plus nginx on a Debian/Ubuntu host), 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)
+
+---
+
+## Documentation
+
+Homelable keeps its own markdown documentation space, so the lab is described where it is drawn. Sidebar → **Documentation**.
+
+Every device has a document, generated once from what the scan actually found — identity, hardware, one section per service, network, operations, troubleshooting — and never rewritten behind you. Beside it, a **Library** of pages you write: runbooks, incidents, decisions, a network overview, from a template or blank.
+
+### Usage
+
+1. **Pick a device** in the tree — one with no document yet gets one written from its facts. Re-pivot the tree by zone, subnet, type, rack, vendor, tag… at no cost; it is grouped from data the app already holds
+2. **Write markdown**, save explicitly — nothing is ever saved behind your back. `/` inserts a freshly generated block (services, hardware, network, rack) from the device's current data
+3. **Link things**: `[[VLAN plan]]`, `[[device:nas-01]]`. Each document lists **Linked from** at the bottom, so you can see what points at it
+4. **History**: up to 50 versions per document. Read one, diff it against the current body, restore it — what it replaces is kept too
+5. **Search** the whole space, tag documents, and set `review_every: 6m` on the ones that rot; a document past its interval is badged as due
+
+A device that changes after its document was written raises a **device data changed** banner, and **Regenerate** rebuilds the document from scratch when you want that. Old per-device **Notes** migrate into documents from a banner, non-destructively.
+
+Full mode only — documents need the backend to store, index and search them.
+
+> **Full documentation:** [docs/documentation.md](./docs/documentation.md)
 
 ---
 
@@ -40,6 +120,28 @@ The scanner runs `nmap -sV --open` on your configured CIDR ranges and populates
 To save you time when mapping your infrastructure, Homlable can scan your network and report all the services it detects. It can also identify them, saving you even more time.
 Click **Scan Network** in the sidebar. The Scan History tab opens automatically and refreshes every 3 seconds until the scan completes.
 
+### Deep scan (custom ports)
+
+By default the scanner only probes nmap's standard port set. To fingerprint services on non-standard ports, enable the deep scan via `.env` (all options are overridable per-scan from the scan dialog):
+
+```env
+# JSON array of port specs — each entry is a single port "N" or an inclusive
+# range "N-M" (1–65535, N <= M). These are ports, not CIDRs or bare integers.
+SCANNER_HTTP_RANGES=["8080","9000-9100"]
+SCANNER_HTTP_PROBE_ENABLED=true   # send an HTTP probe to those ports for service ID
+SCANNER_HTTP_VERIFY_TLS=false     # verify TLS certs on the HTTP probe
+```
+
+The listed ports are appended to nmap's `-p` spec. Invalid entries (out-of-range, malformed, or reversed ranges) are silently skipped.
+
+### MAC addresses (Docker)
+
+The scan reports no MAC address when the backend runs on a Docker bridge
+network — ARP is layer 2, and from a bridge every LAN host sits behind the
+Docker gateway. It also means a DHCP device that changes IP comes back as a new
+inventory entry, since matching prefers the MAC. Fix and caveats:
+[INSTALLATION.md](./INSTALLATION.md#scanning-from-docker--mac-addresses).
+
 ### macOS / root privileges
 
 Some nmap scan types (SYN scan, OS detection) require root. If the scan fails with a permissions error, run it manually with sudo using the included script:
@@ -109,6 +211,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.
@@ -196,8 +360,8 @@ Homelable can exposes a [Model Context Protocol](https://modelcontextprotocol.io
 
 | | Action |
 |---|---|
-| **Read** | List all nodes, edges, full canvas, pending devices, scan history |
-| **Write** | Add / update / delete nodes and edges, trigger a network scan, approve or hide discovered devices |
+| **Read** | List all nodes, edges, full canvas, zones, designs, the device inventory and scan history — and the rack canvases: racks, mounted gear, patched cables |
+| **Write** | Add / update / delete nodes, edges and zones, trigger a network scan, approve / hide / restore discovered devices, create and edit inventory entries, build racks and mount, move and patch the gear in them |
 
 ### Setup
 
@@ -223,11 +387,17 @@ docker compose up -d mcp
 # MCP server is now listening on http://<your-homelab-ip>:8001
 ```
 
+> **Proxmox LXC / bare-metal (no Docker):** create the LXC via
+> [community-scripts/ProxmoxVE](https://github.com/community-scripts/ProxmoxVE) (or any
+> Debian/Ubuntu LXC), then inside it run `sudo bash scripts/lxc-mcp-install.sh`.
+> Installs a `homelable-mcp` systemd service, prompts for `MCP_API_KEY` / `MCP_SERVICE_KEY`
+> (auto-generated if you press Enter), and skips prompts if `mcp/.env` already exists.
+
 **3. Configure your AI client:**
 
 **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"
 ```
 
@@ -236,8 +406,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"
       }
@@ -251,8 +421,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"
       }
@@ -267,6 +437,8 @@ Or add it manually to `~/.claude.json`:
 - *"Add a new LXC container named `pihole` at 192.168.1.5, connected to my switch."*
 - *"Trigger a network scan on 192.168.1.0/24 and show me the pending devices."*
 - *"Show me the full canvas topology."*
+- *"How much free U is left in the garage rack?"*
+- *"Mount the NAS in rack 1 and patch its first port to port 12 of the patch panel."*
 
 ### Security
 

VERSION

@@ -1 +1 @@
-2.0.3
+3.4.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.core.config import settings
-from app.core.security import create_access_token, verify_password
+from app.api.deps import AuthContext, get_auth_context
+from app.core.config import app_base_path_of, settings
+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,58 @@ 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()
+    # Back to the SPA — which is not necessarily at the root of the origin.
+    response = RedirectResponse(
+        url=app_base_path_of(settings.oidc_redirect_uri), 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

@@ -1,81 +1,144 @@
+import uuid
 from datetime import datetime, timezone
 from typing import Any
 
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, 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, Edge, Node
+from app.db.models import CanvasState, Design, Edge, Node
 from app.schemas.canvas import CanvasSaveRequest, CanvasStateResponse
 from app.schemas.edges import EdgeResponse
 from app.schemas.nodes import NodeResponse
+from app.services.inventory_sync import (
+    facts_from_payload,
+    hydrated_node,
+    link_facts,
+    load_devices_for,
+    node_columns,
+)
 
 router = APIRouter()
 
 
 @router.get("", response_model=CanvasStateResponse)
-async def load_canvas(db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> CanvasStateResponse:
-    nodes = (await db.execute(select(Node))).scalars().all()
-    edges = (await db.execute(select(Edge))).scalars().all()
-    state = await db.get(CanvasState, 1)
+async def load_canvas(
+    design_id: str | None = Query(None, description="Design ID to load; uses first design if omitted"),
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> CanvasStateResponse:
+    if design_id is None:
+        first = (await db.execute(select(Design).order_by(Design.created_at).limit(1))).scalar()
+        design_id = first.id if first else None
+    if design_id is None:
+        return CanvasStateResponse(nodes=[], edges=[], viewport={"x": 0, "y": 0, "zoom": 1}, custom_style=None)
+
+    nodes = list((await db.execute(select(Node).where(Node.design_id == design_id))).scalars().all())
+    edges = (await db.execute(select(Edge).where(Edge.design_id == design_id))).scalars().all()
+    state = await db.get(CanvasState, design_id)
     viewport: dict[str, Any] = state.viewport if state else {"x": 0, "y": 0, "zoom": 1}
+    # The device facts live on the inventory row now; hydrate them back into the
+    # node so the wire shape the canvas consumes is unchanged.
+    devices = await load_devices_for(db, nodes)
     return CanvasStateResponse(
-        nodes=[NodeResponse.model_validate(n) for n in nodes],
+        nodes=[NodeResponse.model_validate(hydrated_node(n, devices.get(n.device_id or ""))) for n in nodes],
         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,
     )
 
 
 @router.post("/save")
 async def save_canvas(
     body: CanvasSaveRequest, db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)
-) -> dict[str, bool]:
+) -> dict[str, bool | str]:
+    design_id = body.design_id
+    if design_id is None:
+        first = (await db.execute(select(Design).order_by(Design.created_at).limit(1))).scalar()
+        design_id = first.id if first else None
+    if design_id is None:
+        new_design = Design(id=str(uuid.uuid4()), name="Network Topology", design_type="network")
+        db.add(new_design)
+        await db.flush()
+        design_id = new_design.id
+
     incoming_node_ids = {n.id for n in body.nodes}
     incoming_edge_ids = {e.id for e in body.edges}
 
-    # Delete nodes removed from canvas
-    existing_nodes = (await db.execute(select(Node))).scalars().all()
+    # Delete nodes removed from canvas (only within this design)
+    existing_nodes = (await db.execute(select(Node).where(Node.design_id == design_id))).scalars().all()
     for node in existing_nodes:
         if node.id not in incoming_node_ids:
             await db.delete(node)
 
-    # Delete edges removed from canvas
-    existing_edges = (await db.execute(select(Edge))).scalars().all()
+    # Delete edges removed from canvas (only within this design)
+    existing_edges = (await db.execute(select(Edge).where(Edge.design_id == design_id))).scalars().all()
     for edge in existing_edges:
         if edge.id not in incoming_edge_ids:
             await db.delete(edge)
 
     await db.flush()
 
-    # Upsert nodes
+    # Upsert nodes, then route their device facts to the inventory row that owns
+    # them — an edit made on this canvas is an edit to the device itself, and
+    # every other canvas showing it follows.
+    saved: list[tuple[Node, dict[str, Any], list[str] | None]] = []
     for node_data in body.nodes:
         db_node = await db.get(Node, node_data.id)
+        payload = node_data.model_dump()
+        payload["design_id"] = design_id
+        facts = facts_from_payload(payload, label=node_data.label, node_type=node_data.type)
+        columns = node_columns(payload)
         if db_node:
-            for field, value in node_data.model_dump().items():
+            for field, value in columns.items():
                 setattr(db_node, field, value)
         else:
-            db.add(Node(**node_data.model_dump()))
+            db_node = Node(**columns)
+            db.add(db_node)
+        saved.append((db_node, facts, node_data.changed_facts))
+
+    await db.flush()
+    for node, facts, changed in saved:
+        # The payload carries a full copy of each device, hydrated when this
+        # canvas loaded. Routing all of it back would rewrite the row from a
+        # stale snapshot — a save made for nothing but a moved node could revert
+        # an edit meanwhile in the inventory modal. `changed_facts` (when the
+        # client tracked it) plus the row diff narrow the write to this canvas'
+        # actual edit.
+        await link_facts(
+            db,
+            node,
+            facts,
+            overwrite_scalars=True,
+            replace_lists=True,
+            only_changed=True,
+            changed_fields=changed,
+        )
 
     # Upsert edges
     for edge_data in body.edges:
         db_edge = await db.get(Edge, edge_data.id)
+        payload = edge_data.model_dump()
+        payload["design_id"] = design_id
         if db_edge:
-            for field, value in edge_data.model_dump().items():
+            for field, value in payload.items():
                 setattr(db_edge, field, value)
         else:
-            db.add(Edge(**edge_data.model_dump()))
+            db.add(Edge(**payload))
 
     # Upsert viewport + custom style
-    state = await db.get(CanvasState, 1)
+    state = await db.get(CanvasState, design_id)
     if state:
         state.viewport = body.viewport
         state.custom_style = body.custom_style
         state.saved_at = datetime.now(timezone.utc)
     else:
-        db.add(CanvasState(id=1, viewport=body.viewport, custom_style=body.custom_style))
+        db.add(CanvasState(design_id=design_id, viewport=body.viewport, custom_style=body.custom_style))
 
     await db.commit()
     return {"saved": True}

backend/app/api/routes/designs.py

@@ -0,0 +1,242 @@
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException
+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, Rack, RackCable, RackDevice
+from app.schemas.designs import DesignCopy, DesignCreate, DesignResponse, DesignUpdate
+from app.services.doc_links import unlink_documents
+
+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(
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> list[DesignResponse]:
+    designs = (await db.execute(select(Design).order_by(Design.created_at))).scalars().all()
+    # 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)
+async def create_design(
+    body: DesignCreate,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> DesignResponse:
+    design = Design(name=body.name, design_type=body.design_type, icon=body.icon)
+    db.add(design)
+    await db.flush()
+    # Create empty canvas state for the new design
+    db.add(CanvasState(design_id=design.id))
+    await db.commit()
+    await db.refresh(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,
+    body: DesignUpdate,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> DesignResponse:
+    design = await db.get(Design, design_id)
+    if not design:
+        raise HTTPException(404, "Design not found")
+    if body.name is not None:
+        design.name = body.name
+    if body.icon is not None:
+        design.icon = body.icon
+    await db.commit()
+    await db.refresh(design)
+    return DesignResponse.model_validate(design)
+
+
+@router.delete("/{design_id}", status_code=204)
+async def delete_design(
+    design_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> None:
+    design = await db.get(Design, design_id)
+    if not design:
+        raise HTTPException(404, "Design not found")
+    # Count remaining designs — prevent deleting the last one
+    count = (await db.execute(select(Design))).scalars().all()
+    if len(count) <= 1:
+        raise HTTPException(400, "Cannot delete the only design")
+    # 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)
+    nodes = (await db.execute(select(Node).where(Node.design_id == design_id))).scalars().all()
+    # Foreign keys are off, so orphan the documents by hand before the rows go.
+    await unlink_documents(db, node_ids=[n.id for n in nodes], design_ids=[design_id])
+    for n in nodes:
+        await db.delete(n)
+    await db.delete(design)
+    await db.commit()

backend/app/api/routes/documents.py

@@ -0,0 +1,719 @@
+"""Documents — the markdown documentation space.
+
+A document is either a page or a folder in the Library tree, or it describes one
+thing elsewhere in the app: a Device Inventory row, a piece of canvas furniture
+(a zone, a group), or a whole canvas. The tree the user navigates is *not* stored
+here: device documents are pivoted client-side by zone, subnet, type and so on,
+because every one of those groupings is derivable from data the frontend already
+holds and re-pivoting must be instant.
+
+The generated header is written once, at creation. Nothing in this module ever
+rewrites a body the user owns; `GET /blocks` hands the editor a freshly generated
+section on request, and `facts_snapshot` is what lets the UI say the device has
+moved on since the document was written.
+"""
+
+import re
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+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 Document, DocumentRevision, Edge, InventoryDevice, Node, Rack, RackDevice
+from app.schemas.documents import (
+    BacklinkHit,
+    CoverageResponse,
+    DocumentCreate,
+    DocumentResponse,
+    DocumentSummary,
+    DocumentUpdate,
+    RevisionResponse,
+    RevisionSummary,
+    ScaffoldRequest,
+    ScaffoldResponse,
+    SearchHit,
+    SearchResponse,
+)
+from app.services import doc_backlinks, doc_search
+from app.services.doc_template import (
+    BLOCKS,
+    TEMPLATE_DEVICE,
+    facts_snapshot,
+    render_block,
+    render_device_document,
+    render_library_document,
+)
+from app.services.doc_tree import (
+    REVISION_LIMIT,
+    TREE_KINDS,
+    is_ancestor,
+    parse_frontmatter,
+    subtree_ids,
+    tags_from,
+    unique_slug,
+)
+
+router = APIRouter()
+
+# Node.type values that are canvas furniture. A zone or a group is documented
+# through its node; everything else is documented through its device.
+_FURNITURE_TYPES = {"group", "groupRect", "text"}
+
+_INTERVAL = re.compile(r"^\s*(\d+)\s*([dwmy])\s*$", re.IGNORECASE)
+_INTERVAL_DAYS = {"d": 1, "w": 7, "m": 30, "y": 365}
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _aware(value: datetime | None) -> datetime | None:
+    """SQLite hands back naive datetimes; compare them as UTC."""
+    if value is None:
+        return None
+    return value if value.tzinfo else value.replace(tzinfo=timezone.utc)
+
+
+def _parse_interval(raw: Any) -> timedelta | None:
+    """`review_every: 6m` → 180 days. Anything unparseable means "never due"."""
+    match = _INTERVAL.match(str(raw or ""))
+    if not match:
+        return None
+    return timedelta(days=int(match.group(1)) * _INTERVAL_DAYS[match.group(2).lower()])
+
+
+def _apply_body(doc: Document, body: str) -> None:
+    """Store a body and refresh the frontmatter/tags cache from it.
+
+    The body is the source of truth — it is what exports to disk — so the two
+    JSON columns are only ever derived from it, never edited on their own.
+    """
+    doc.body = body
+    frontmatter = parse_frontmatter(body)
+    doc.frontmatter = frontmatter
+    doc.tags = tags_from(frontmatter)
+
+
+async def _adopt_frontmatter_title(db: AsyncSession, doc: Document) -> None:
+    """Follow the name the body gives, since the body is what the user edits.
+
+    `title:` in the frontmatter is the only place a document is named — there is
+    no rename field anywhere in the UI — so a row that kept the title it was
+    created with went stale the moment someone edited that line, and the tree
+    went on showing the old name.
+    """
+    front = doc.frontmatter if isinstance(doc.frontmatter, dict) else {}
+    title = front.get("title")
+    if not isinstance(title, str) or not title.strip() or title.strip() == doc.title:
+        return
+    doc.title = title.strip()
+    doc.slug = await unique_slug(db, doc.title, parent_id=doc.parent_id, exclude_id=doc.id)
+
+
+async def _record_revision(db: AsyncSession, doc: Document, reason: str) -> None:
+    """Snapshot the current body, then prune the document's oldest history."""
+    db.add(DocumentRevision(document_id=doc.id, title=doc.title, body=doc.body or "", reason=reason))
+    await db.flush()
+    stale = (
+        await db.execute(
+            select(DocumentRevision)
+            .where(DocumentRevision.document_id == doc.id)
+            .order_by(DocumentRevision.saved_at.desc(), DocumentRevision.id.desc())
+            .offset(REVISION_LIMIT)
+        )
+    ).scalars().all()
+    for revision in stale:
+        await db.delete(revision)
+
+
+async def _device_context(db: AsyncSession, device_id: str) -> dict[str, Any]:
+    """Zone, rack placement and canvas neighbours for a device.
+
+    All three are optional: a device may be on no canvas, in no rack and in no
+    zone, and the template drops those sections rather than printing them empty.
+    """
+    context: dict[str, Any] = {"zone_label": None, "rack": None, "connections": []}
+
+    node = (
+        await db.execute(select(Node).where(Node.device_id == device_id).order_by(Node.created_at))
+    ).scalars().first()
+    if node is not None:
+        parent_id = node.parent_id
+        seen: set[str] = set()
+        while parent_id and parent_id not in seen:
+            seen.add(parent_id)
+            parent = await db.get(Node, parent_id)
+            if parent is None:
+                break
+            if parent.type in _FURNITURE_TYPES:
+                context["zone_label"] = parent.label
+                break
+            parent_id = parent.parent_id
+
+        edges = (
+            await db.execute(select(Edge).where((Edge.source == node.id) | (Edge.target == node.id)))
+        ).scalars().all()
+        peer_ids = [e.target if e.source == node.id else e.source for e in edges]
+        if peer_ids:
+            peers = (await db.execute(select(Node.label).where(Node.id.in_(peer_ids)))).scalars().all()
+            context["connections"] = sorted({label for label in peers if label})
+
+    mount = (
+        await db.execute(select(RackDevice).where(RackDevice.device_id == device_id))
+    ).scalars().first()
+    if mount is not None:
+        rack = await db.get(Rack, mount.rack_id)
+        context["rack"] = {
+            "name": rack.name if rack else None,
+            "u_start": mount.u_start,
+            "u_height": mount.u_height,
+            "col_span": mount.col_span,
+        }
+    return context
+
+
+async def _scaffold_body(db: AsyncSession, doc: Document, template_id: str | None) -> None:
+    """Generate this document's initial body. Called once, at creation."""
+    if doc.device_id:
+        device = await db.get(InventoryDevice, doc.device_id)
+        if device is not None:
+            context = await _device_context(db, doc.device_id)
+            _apply_body(doc, render_device_document(device, **context))
+            doc.facts_snapshot = facts_snapshot(device)
+            doc.facts_synced_at = _now()
+            doc.template_id = TEMPLATE_DEVICE
+            return
+    _apply_body(doc, render_library_document(template_id or "blank", doc.title))
+    doc.template_id = template_id or "blank"
+
+
+def _has_drifted(doc: Document, device: InventoryDevice | None) -> bool:
+    """Whether the device has moved on since this document was snapshotted.
+
+    The comparison lives on the server rather than in the UI because
+    `facts_snapshot` is the server's own shape — `label` and `type` are stored
+    through their fallbacks and `properties` as a flat map — so nothing else
+    can compare it to a device row correctly. Same rule as the coverage count.
+    """
+    if not doc.device_id or not doc.facts_snapshot or device is None:
+        return False
+    return doc.facts_snapshot != facts_snapshot(device)
+
+
+async def _devices_for(db: AsyncSession, docs: list[Document]) -> dict[str, InventoryDevice]:
+    """The devices a batch of documents describes, in one query."""
+    wanted = {d.device_id for d in docs if d.device_id and d.facts_snapshot}
+    if not wanted:
+        return {}
+    rows = (
+        await db.execute(select(InventoryDevice).where(InventoryDevice.id.in_(wanted)))
+    ).scalars().all()
+    return {device.id: device for device in rows}
+
+
+def _summary(doc: Document, device: InventoryDevice | None) -> DocumentSummary:
+    payload = DocumentSummary.model_validate(doc)
+    payload.drifted = _has_drifted(doc, device)
+    return payload
+
+
+async def _response(db: AsyncSession, doc: Document) -> DocumentResponse:
+    """One document, with the drift flag resolved against the live device."""
+    payload = DocumentResponse.model_validate(doc)
+    payload.drifted = _has_drifted(doc, await db.get(InventoryDevice, doc.device_id) if doc.device_id else None)
+    return payload
+
+
+# ── list / read ─────────────────────────────────────────────────────────────
+
+
+@router.get("", response_model=list[DocumentSummary])
+async def list_documents(
+    kind: str | None = Query(None, description="Filter to one document kind"),
+    parent_id: str | None = Query(None, description="Library children of this folder"),
+    device_id: str | None = Query(None, description="The document describing this device"),
+    tag: str | None = Query(None, description="Documents carrying this frontmatter tag"),
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> list[DocumentSummary]:
+    query = select(Document)
+    if kind:
+        query = query.where(Document.kind == kind)
+    if parent_id:
+        query = query.where(Document.parent_id == parent_id)
+    if device_id:
+        query = query.where(Document.device_id == device_id)
+    docs = (await db.execute(query.order_by(Document.sort_order, Document.title))).scalars().all()
+    if tag:
+        wanted = tag.lower()
+        docs = [d for d in docs if any(str(t).lower() == wanted for t in (d.tags or []))]
+    devices = await _devices_for(db, list(docs))
+    return [_summary(d, devices.get(d.device_id or "")) for d in docs]
+
+
+@router.get("/coverage", response_model=CoverageResponse)
+async def coverage(
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> CoverageResponse:
+    """How much of the homelab is actually written down."""
+    devices = (
+        await db.execute(select(InventoryDevice).where(InventoryDevice.status != "hidden"))
+    ).scalars().all()
+    docs = (await db.execute(select(Document))).scalars().all()
+    by_device = {d.device_id: d for d in docs if d.device_id}
+
+    header_only = drifted = overdue = 0
+    now = _now()
+    for device in devices:
+        doc = by_device.get(device.id)
+        if doc is None:
+            continue
+        # Never edited since it was generated: the template is all there is.
+        if doc.edited_at is None and doc.reviewed_at is None:
+            header_only += 1
+        if doc.facts_snapshot and doc.facts_snapshot != facts_snapshot(device):
+            drifted += 1
+        interval = _parse_interval((doc.frontmatter or {}).get("review_every"))
+        since = _aware(doc.reviewed_at) or _aware(doc.created_at)
+        if interval and since and now - since > interval:
+            overdue += 1
+
+    documented = sum(1 for device in devices if device.id in by_device)
+    return CoverageResponse(
+        devices=len(devices),
+        documented=documented,
+        header_only=header_only,
+        missing=len(devices) - documented,
+        drifted=drifted,
+        overdue=overdue,
+        notes_unmigrated=sum(
+            1 for device in devices if (device.notes or "").strip() and device.id not in by_device
+        ),
+        library_pages=sum(1 for d in docs if d.kind in TREE_KINDS),
+    )
+
+
+@router.get("/search", response_model=SearchResponse)
+async def search_documents(
+    q: str = Query(..., description="Full-text query"),
+    limit: int = Query(25, ge=1, le=100),
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> SearchResponse:
+    engine, rows = await doc_search.search(db, q, limit)
+    if not rows:
+        return SearchResponse(engine=engine, hits=[])
+    docs = {
+        d.id: d
+        for d in (
+            await db.execute(select(Document).where(Document.id.in_([r["doc_id"] for r in rows])))
+        ).scalars().all()
+    }
+    hits = [
+        SearchHit(
+            doc_id=row["doc_id"],
+            title=docs[row["doc_id"]].title,
+            kind=docs[row["doc_id"]].kind,
+            snippet=row["snippet"] or "",
+            device_id=docs[row["doc_id"]].device_id,
+        )
+        for row in rows
+        if row["doc_id"] in docs
+    ]
+    return SearchResponse(engine=engine, hits=hits)
+
+
+@router.get("/blocks", response_model=dict)
+async def generated_block(
+    block: str = Query(..., description=f"One of {sorted(BLOCKS)}"),
+    device_id: str = Query(..., description="Device to read the facts from"),
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> dict[str, str]:
+    """Render one generated section, for the editor's `/` insert menu.
+
+    This is the counterpart to generating the header only once: the user can
+    always pull a fresh block in, but nothing pushes one at them.
+    """
+    if block not in BLOCKS:
+        raise HTTPException(400, f"block must be one of {sorted(BLOCKS)}")
+    device = await db.get(InventoryDevice, device_id)
+    if not device:
+        raise HTTPException(404, "Device not found")
+    context = await _device_context(db, device_id) if block in {"rack", "network"} else {}
+    return {"block": block, "markdown": render_block(block, device, **context)}
+
+
+@router.get("/{document_id}", response_model=DocumentResponse)
+async def get_document(
+    document_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> DocumentResponse:
+    doc = await db.get(Document, document_id)
+    if not doc:
+        raise HTTPException(404, "Document not found")
+    return await _response(db, doc)
+
+
+@router.get("/{document_id}/revisions", response_model=list[RevisionSummary])
+async def list_revisions(
+    document_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> list[RevisionSummary]:
+    doc = await db.get(Document, document_id)
+    if not doc:
+        raise HTTPException(404, "Document not found")
+    revisions = (
+        await db.execute(
+            select(DocumentRevision)
+            .where(DocumentRevision.document_id == document_id)
+            .order_by(DocumentRevision.saved_at.desc(), DocumentRevision.id.desc())
+        )
+    ).scalars().all()
+    return [
+        RevisionSummary(
+            id=r.id,
+            document_id=r.document_id,
+            title=r.title,
+            reason=r.reason,
+            saved_at=r.saved_at,
+            size=len(r.body or ""),
+        )
+        for r in revisions
+    ]
+
+
+@router.get("/{document_id}/backlinks", response_model=list[BacklinkHit])
+async def list_backlinks(
+    document_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> list[BacklinkHit]:
+    """The documents whose body links here.
+
+    Answered on the server because the browser only holds document *metadata* —
+    the list endpoint carries no bodies, and loading every body to invert the
+    links client-side would trade a small query for a large download on every
+    open.
+    """
+    doc = await db.get(Document, document_id)
+    if not doc:
+        raise HTTPException(404, "Document not found")
+
+    # Every document is loaded because every one is a possible *target* of a
+    # link — a bare `[[VLAN plan]]` resolves by title. Only the bodies carrying
+    # `[[` are walked as sources, and the inventory is fetched only when a
+    # `[[device:…]]` is actually in play.
+    docs = list(
+        (
+            await db.execute(select(Document).order_by(Document.sort_order, Document.title))
+        ).scalars().all()
+    )
+    devices = (
+        list((await db.execute(select(InventoryDevice))).scalars().all())
+        if doc_backlinks.has_device_link(docs)
+        else []
+    )
+
+    titles = {d.id: d for d in docs}
+    return [
+        BacklinkHit(
+            doc_id=hit.doc_id,
+            title=titles[hit.doc_id].title,
+            kind=titles[hit.doc_id].kind,
+            device_id=titles[hit.doc_id].device_id,
+            label=hit.label,
+            context=hit.context,
+            count=hit.count,
+        )
+        for hit in doc_backlinks.backlinks_for(document_id, docs, devices)
+        if hit.doc_id in titles
+    ]
+
+
+@router.get("/revisions/{revision_id}", response_model=RevisionResponse)
+async def get_revision(
+    revision_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> RevisionResponse:
+    revision = await db.get(DocumentRevision, revision_id)
+    if not revision:
+        raise HTTPException(404, "Revision not found")
+    return RevisionResponse(
+        id=revision.id,
+        document_id=revision.document_id,
+        title=revision.title,
+        reason=revision.reason,
+        saved_at=revision.saved_at,
+        size=len(revision.body or ""),
+        body=revision.body or "",
+    )
+
+
+# ── write ───────────────────────────────────────────────────────────────────
+
+
+@router.post("", response_model=DocumentResponse, status_code=201)
+async def create_document(
+    body: DocumentCreate,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> DocumentResponse:
+    links = [body.device_id, body.node_id, body.design_id]
+    if sum(1 for link in links if link) > 1:
+        raise HTTPException(400, "A document describes at most one device, node or design")
+    if body.kind in TREE_KINDS and any(links):
+        raise HTTPException(400, "A page or folder cannot also describe a device, node or design")
+    if body.kind not in TREE_KINDS and not any(links):
+        raise HTTPException(400, f"A '{body.kind}' document must name what it describes")
+    if body.parent_id and body.kind not in TREE_KINDS:
+        raise HTTPException(400, "Only pages and folders live in the Library tree")
+
+    for link, model, what in (
+        (body.device_id, InventoryDevice, "Device"),
+        (body.node_id, Node, "Node"),
+    ):
+        if link and not await db.get(model, link):
+            raise HTTPException(404, f"{what} not found")
+    if body.parent_id and not await db.get(Document, body.parent_id):
+        raise HTTPException(404, "Parent folder not found")
+
+    for column, value in (
+        (Document.device_id, body.device_id),
+        (Document.node_id, body.node_id),
+        (Document.design_id, body.design_id),
+    ):
+        if value and (await db.execute(select(Document).where(column == value))).scalars().first():
+            raise HTTPException(409, "That already has a document")
+
+    doc = Document(
+        kind=body.kind,
+        title=body.title,
+        slug=await unique_slug(db, body.title, parent_id=body.parent_id),
+        icon=body.icon,
+        parent_id=body.parent_id,
+        device_id=body.device_id,
+        node_id=body.node_id,
+        design_id=body.design_id,
+    )
+    if body.body is not None:
+        _apply_body(doc, body.body)
+        doc.template_id = body.template_id
+    else:
+        await _scaffold_body(db, doc, body.template_id)
+
+    db.add(doc)
+    await db.flush()
+    await doc_search.index_document(db, doc)
+    await db.commit()
+    await db.refresh(doc)
+    return await _response(db, doc)
+
+
+@router.patch("/{document_id}", response_model=DocumentResponse)
+async def update_document(
+    document_id: str,
+    body: DocumentUpdate,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> DocumentResponse:
+    doc = await db.get(Document, document_id)
+    if not doc:
+        raise HTTPException(404, "Document not found")
+    sent = body.model_dump(exclude_unset=True)
+
+    if "parent_id" in sent:
+        parent_id = sent["parent_id"]
+        if doc.kind not in TREE_KINDS:
+            raise HTTPException(400, "Only pages and folders live in the Library tree")
+        if parent_id:
+            parent = await db.get(Document, parent_id)
+            if not parent:
+                raise HTTPException(404, "Parent folder not found")
+            if parent.kind != "folder":
+                raise HTTPException(400, "A document can only be filed under a folder")
+            if await is_ancestor(db, document_id, parent_id):
+                raise HTTPException(400, "A folder cannot be moved inside itself")
+        doc.parent_id = parent_id
+        doc.slug = await unique_slug(db, doc.title, parent_id=parent_id, exclude_id=doc.id)
+
+    if "body" in sent and sent["body"] is not None and sent["body"] != doc.body:
+        await _record_revision(db, doc, "edit")
+        _apply_body(doc, sent["body"])
+        doc.edited_at = _now()
+        # An explicit title in the same request still wins: it is applied below.
+        await _adopt_frontmatter_title(db, doc)
+
+    if "title" in sent and sent["title"]:
+        doc.title = sent["title"]
+        doc.slug = await unique_slug(db, doc.title, parent_id=doc.parent_id, exclude_id=doc.id)
+    if "icon" in sent:
+        doc.icon = sent["icon"]
+    if "sort_order" in sent and sent["sort_order"] is not None:
+        doc.sort_order = sent["sort_order"]
+    if "starred" in sent and sent["starred"] is not None:
+        doc.starred = sent["starred"]
+    if sent.get("reviewed"):
+        doc.reviewed_at = _now()
+    if sent.get("resync_facts") and doc.device_id:
+        device = await db.get(InventoryDevice, doc.device_id)
+        if device is not None:
+            doc.facts_snapshot = facts_snapshot(device)
+            doc.facts_synced_at = _now()
+
+    await db.flush()
+    await doc_search.index_document(db, doc)
+    await db.commit()
+    await db.refresh(doc)
+    return await _response(db, doc)
+
+
+@router.post("/{document_id}/revisions/{revision_id}/restore", response_model=DocumentResponse)
+async def restore_revision(
+    document_id: str,
+    revision_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> DocumentResponse:
+    doc = await db.get(Document, document_id)
+    if not doc:
+        raise HTTPException(404, "Document not found")
+    revision = await db.get(DocumentRevision, revision_id)
+    if not revision or revision.document_id != document_id:
+        raise HTTPException(404, "Revision not found")
+    # The body being replaced becomes history too, so a restore is undoable.
+    await _record_revision(db, doc, "restore")
+    _apply_body(doc, revision.body or "")
+    # A restored body brings its own title back with it.
+    await _adopt_frontmatter_title(db, doc)
+    await db.flush()
+    await doc_search.index_document(db, doc)
+    await db.commit()
+    await db.refresh(doc)
+    return await _response(db, doc)
+
+
+@router.post("/{document_id}/regenerate", response_model=DocumentResponse)
+async def regenerate_document(
+    document_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> DocumentResponse:
+    """Throw the body away and scaffold it again from what the database holds.
+
+    The one place that overwrites a body the user owns, so it is only ever
+    reached from an explicit confirmation. The replaced body is snapshotted
+    first, which makes the whole thing undoable from the history list.
+    """
+    doc = await db.get(Document, document_id)
+    if not doc:
+        raise HTTPException(404, "Document not found")
+    if doc.kind == "folder":
+        raise HTTPException(400, "A folder has no body to regenerate")
+    if doc.device_id and not await db.get(InventoryDevice, doc.device_id):
+        raise HTTPException(404, "Device not found")
+
+    await _record_revision(db, doc, "regenerate")
+    await _scaffold_body(db, doc, doc.template_id)
+    # Back to a freshly generated document: nothing of the user's is left in it.
+    doc.edited_at = None
+    await db.flush()
+    await doc_search.index_document(db, doc)
+    await db.commit()
+    await db.refresh(doc)
+    return await _response(db, doc)
+
+
+@router.post("/scaffold", response_model=ScaffoldResponse)
+async def scaffold_documents(
+    body: ScaffoldRequest,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> ScaffoldResponse:
+    """Create the device documents that do not exist yet.
+
+    This is the migration off `device_inventory.notes`: the old text is appended
+    verbatim under `## Notes` and the column is left untouched, so nothing is
+    lost and the move is repeatable.
+    """
+    query = select(InventoryDevice).where(InventoryDevice.status != "hidden")
+    if body.device_ids:
+        query = query.where(InventoryDevice.id.in_(body.device_ids))
+    devices = (await db.execute(query.order_by(InventoryDevice.discovered_at))).scalars().all()
+    existing = {
+        doc_id
+        for doc_id in (
+            await db.execute(select(Document.device_id).where(Document.device_id.is_not(None)))
+        ).scalars().all()
+    }
+
+    created: list[Document] = []
+    skipped = 0
+    for device in devices:
+        if device.id in existing:
+            skipped += 1
+            continue
+        if body.only_with_notes and not (device.notes or "").strip():
+            skipped += 1
+            continue
+        context = await _device_context(db, device.id)
+        doc = Document(
+            kind="device",
+            title=device.label or device.friendly_name or device.hostname or device.ip or "device",
+            slug="",
+            device_id=device.id,
+            template_id=TEMPLATE_DEVICE,
+            facts_snapshot=facts_snapshot(device),
+            facts_synced_at=_now(),
+        )
+        doc.slug = await unique_slug(db, doc.title, parent_id=None)
+        _apply_body(doc, render_device_document(device, **context))
+        db.add(doc)
+        await db.flush()
+        db.add(
+            DocumentRevision(
+                document_id=doc.id,
+                title=doc.title,
+                body=doc.body,
+                reason="migrate" if (device.notes or "").strip() else "scaffold",
+            )
+        )
+        await doc_search.index_document(db, doc)
+        created.append(doc)
+
+    await db.commit()
+    for doc in created:
+        await db.refresh(doc)
+    return ScaffoldResponse(created=[DocumentSummary.model_validate(d) for d in created], skipped=skipped)
+
+
+@router.delete("/{document_id}", status_code=204)
+async def delete_document(
+    document_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> None:
+    doc = await db.get(Document, document_id)
+    if not doc:
+        raise HTTPException(404, "Document not found")
+    # SQLite does not always enforce the ON DELETE CASCADE, so walk the subtree
+    # by hand — a folder takes its children with it.
+    for doc_id in reversed(await subtree_ids(db, document_id)):
+        target = await db.get(Document, doc_id)
+        if target is None:
+            continue
+        for revision in (
+            await db.execute(select(DocumentRevision).where(DocumentRevision.document_id == doc_id))
+        ).scalars().all():
+            await db.delete(revision)
+        await doc_search.unindex_document(db, doc_id)
+        await db.delete(target)
+    await db.commit()

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 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]:
@@ -18,7 +63,26 @@ async def list_edges(db: AsyncSession = Depends(get_db), _: str = Depends(get_cu
 
 @router.post("", response_model=EdgeResponse, status_code=status.HTTP_201_CREATED)
 async def create_edge(body: EdgeCreate, db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> Edge:
-    edge = Edge(**body.model_dump())
+    data = body.model_dump()
+    # Same reconciliation as nodes: clients omitting design_id (MCP write tools)
+    # would create design_id=null edges that never render until a restart.
+    # Fall back to the first design so the edge attaches to a canvas.
+    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()
     await db.refresh(edge)

backend/app/api/routes/liveview.py

@@ -2,22 +2,46 @@ import hmac
 from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel
 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.db.database import get_db
-from app.db.models import CanvasState, Edge, Node
+from app.db.models import CanvasState, Design, Edge, Node
 from app.schemas.canvas import CanvasStateResponse
 from app.schemas.edges import EdgeResponse
 from app.schemas.nodes import NodeResponse
+from app.services.inventory_sync import hydrated_node, load_devices_for
 
 router = APIRouter()
 
 
+class LiveViewConfigResponse(BaseModel):
+    """Whether live view is enabled, plus the key (admin-only) to build share links."""
+
+    enabled: bool
+    key: str | None = None
+
+
+@router.get("/config", response_model=LiveViewConfigResponse)
+async def liveview_config(
+    _: str = Depends(get_current_user),
+) -> LiveViewConfigResponse:
+    """Authenticated: expose the configured live view key so the UI can build a
+    ready-to-use share link (e.g. /view?key=...&design=<id>).
+
+    Only reachable by a logged-in user — the key is never exposed publicly.
+    """
+    key = settings.liveview_key or None
+    return LiveViewConfigResponse(enabled=bool(key), key=key)
+
+
 @router.get("", response_model=CanvasStateResponse)
 async def liveview_canvas(
     key: str | None = Query(default=None),
+    design_id: str | None = Query(default=None, description="Design to show; uses first if omitted"),
     db: AsyncSession = Depends(get_db),
 ) -> CanvasStateResponse:
     """Read-only public canvas endpoint.
@@ -30,12 +54,22 @@ async def liveview_canvas(
     if not key or not hmac.compare_digest(key, settings.liveview_key):
         raise HTTPException(status_code=403, detail="Invalid live view key")
 
-    nodes = (await db.execute(select(Node))).scalars().all()
-    edges = (await db.execute(select(Edge))).scalars().all()
-    state = await db.get(CanvasState, 1)
+    if design_id is None:
+        first = (await db.execute(select(Design).order_by(Design.created_at).limit(1))).scalar()
+        design_id = first.id if first else None
+    if design_id is None:
+        return CanvasStateResponse(nodes=[], edges=[], viewport={"x": 0, "y": 0, "zoom": 1}, custom_style=None)
+
+    nodes = list((await db.execute(select(Node).where(Node.design_id == design_id))).scalars().all())
+    edges = (await db.execute(select(Edge).where(Edge.design_id == design_id))).scalars().all()
+    state = await db.get(CanvasState, design_id)
     viewport: dict[str, Any] = state.viewport if state else {"x": 0, "y": 0, "zoom": 1}
+    custom_style: dict[str, Any] | None = state.custom_style if state else None
+    # Device facts come off the inventory row, same as the editable canvas.
+    devices = await load_devices_for(db, nodes)
     return CanvasStateResponse(
-        nodes=[NodeResponse.model_validate(n) for n in nodes],
+        nodes=[NodeResponse.model_validate(hydrated_node(n, devices.get(n.device_id or ""))) for n in nodes],
         edges=[EdgeResponse.model_validate(e) for e in edges],
         viewport=viewport,
+        custom_style=custom_style,
     )

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,50 +1,177 @@
-from fastapi import APIRouter, Depends, HTTPException, status
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
 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 Node
+from app.db.models import Design, InventoryDevice, Node
 from app.schemas.nodes import NodeCreate, NodeResponse, NodeUpdate
+from app.services.doc_links import unlink_documents
+from app.services.inventory_sync import (
+    facts_from_payload,
+    facts_from_update,
+    hydrated_node,
+    link_facts,
+    load_devices_for,
+    node_columns,
+)
+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[Any]:
+    query = select(Node)
+    if label:
+        query = query.where(Node.label.ilike(f"%{label}%"))
+    nodes = list((await db.execute(query)).scalars().all())
+    devices = await load_devices_for(db, nodes)
+    return [hydrated_node(n, devices.get(n.device_id or "")) for n in nodes]
 
 
 @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:
-    node = Node(**body.model_dump())
+async def create_node(body: NodeCreate, db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> Any:
+    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
+    # restart reconciles them. Fall back to the first design, matching bulk-approve.
+    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(**node_columns(data))
     db.add(node)
+    await db.flush()
+    # A new device node gets (or joins) its Device Inventory row — the canvas is
+    # one more way to document hardware, not a parallel store.
+    await link_facts(
+        db, node, facts_from_payload(data, label=data["label"], node_type=data["type"])
+    )
     await db.commit()
     await db.refresh(node)
-    return node
+    return await _hydrate(db, node)
+
+
+async def _hydrate(db: AsyncSession, node: Node) -> dict[str, Any]:
+    """Node as the API reports it, with the device facts read off its row."""
+    device = await db.get(InventoryDevice, node.device_id) if node.device_id else None
+    return hydrated_node(node, device)
 
 
 @router.get("/{node_id}", response_model=NodeResponse)
-async def get_node(node_id: str, db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> Node:
+async def get_node(node_id: str, db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> Any:
     node = await db.get(Node, node_id)
     if not node:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Node not found")
-    return node
+    return await _hydrate(db, node)
 
 
 @router.patch("/{node_id}", response_model=NodeResponse)
 async def update_node(
     node_id: str, body: NodeUpdate, db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)
-) -> Node:
+) -> Any:
     node = await db.get(Node, node_id)
     if not node:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Node not found")
-    for field, value in body.model_dump(exclude_unset=True).items():
+    sent = body.model_dump(exclude_unset=True)
+    # A node can never be its own parent: the canvas' parent walks assume an
+    # acyclic tree and a self-parent row freezes the node on screen (#370).
+    # Dropped rather than rejected so the rest of the edit still lands.
+    if sent.get("parent_id") == node_id:
+        sent.pop("parent_id")
+    for field, value in node_columns(sent).items():
         setattr(node, field, value)
+    # The user edited the device, not just its drawing: push the facts down.
+    # Only what was sent counts — an omitted field must not clear the row, and
+    # lists are replaced only when the client actually sent them.
+    facts = facts_from_update(sent)
+    await link_facts(
+        db,
+        node,
+        facts,
+        overwrite_scalars=True,
+        replace_lists="properties" in sent or "services" in sent,
+    )
     await db.commit()
     await db.refresh(node)
-    return node
+    return await _hydrate(db, node)
 
 
 @router.delete("/{node_id}", status_code=status.HTTP_204_NO_CONTENT)
@@ -52,5 +179,7 @@ async def delete_node(node_id: str, db: AsyncSession = Depends(get_db), _: str =
     node = await db.get(Node, node_id)
     if not node:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Node not found")
+    # Foreign keys are off, so the schema's ON DELETE SET NULL does not fire.
+    await unlink_documents(db, node_ids=[node_id])
     await db.delete(node)
     await db.commit()

backend/app/api/routes/proxmox.py

@@ -0,0 +1,579 @@
+"""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.inventory_sync import attach_device_ids
+from app.services.mac_utils import normalize_mac
+from app.services.node_dedupe import dedupe_nodes_by_device
+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"
+# Every imported guest/host carries a synthetic ieee under this prefix
+# (``pve-node-{host}`` / ``pve-{host}-{vmid}``), built in proxmox_service.
+_PVE_IEEE_PREFIX = "pve-"
+
+
+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,
+    db: AsyncSession = Depends(get_db),
+    _: 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
+
+    # A canvas import is an import: the guests land in the Device Inventory too,
+    # and each node carries the id of the row it draws so the canvas save links
+    # to it instead of minting a second row for the same guest.
+    await _persist_pending_import(db, nodes_raw, edges_raw)
+    nodes_raw = await attach_device_ids(db, nodes_raw)
+
+    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) — see ``_find_pending``:
+      1. Match by the synthetic ``ieee_address`` (``pve-{host}-{vmid}``), the
+         only key that identifies a guest.
+      2. Else match an existing pending row by MAC, then IP, to merge into a
+         device a scan found first — never duplicate. Rows already claimed by
+         another Proxmox guest are excluded.
+
+    Update-in-place only. Nothing is ever deleted; hidden rows stay hidden.
+    """
+    await dedupe_nodes_by_device(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)
+
+        # 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
+        # device). The inventory row owns the facts, so the import merges into
+        # it whether or not the device is drawn anywhere; a node only needs its
+        # cluster handles adjusted. Do NOT stomp user-set type/status.
+        pending = await _find_pending(db, ieee, ip, mac)
+        drawn = bool(
+            pending
+            and (
+                await db.execute(select(Node.id).where(Node.device_id == pending.id).limit(1))
+            ).scalar_one_or_none()
+        )
+
+        if pending is None:
+            db.add(_new_pending(ieee, ip, mac, n, props, status="pending"))
+            pending_created += 1
+        else:
+            if drawn:
+                # Already on a canvas: refresh the facts but leave the lifecycle
+                # alone (_refresh_pending would revive it as pending).
+                await _ensure_inventory_row(db, ieee, ip, mac, n, props, approved=True)
+            else:
+                _refresh_pending(pending, ieee, ip, mac, n, props)
+            pending.cpu_count = pending.cpu_count or n.get("cpu_count")
+            pending.ram_gb = pending.ram_gb or n.get("ram_gb")
+            pending.disk_gb = pending.disk_gb or n.get("disk_gb")
+            pending_updated += 1
+
+            # A cluster host needs one left + one right handle for the cluster
+            # edge endpoints (both default to 0) — the one piece of this that is
+            # genuinely about how the node is drawn.
+            if ieee in cluster_members:
+                for en in (
+                    await db.execute(select(Node).where(Node.device_id == pending.id))
+                ).scalars().all():
+                    en.left_handles = max(en.left_handles or 0, 1)
+                    en.right_handles = max(en.right_handles or 0, 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:
+    """The inventory row this guest *is*, in strict precedence order.
+
+    1. The synthetic ``ieee_address`` (``pve-{host}-{vmid}``). Unique per guest
+       and the only key that identifies one.
+    2. Else the NIC MAC, else the IP — merging into a row an IP/ARP scan found
+       first, or into this same guest under its previous host name.
+
+    An IP is not an identity: a duplicated static lease, a re-used DHCP address,
+    two guests behind one NAT, or a container-bridge address several guests
+    report to the agent all make one address describe several machines. So the
+    IP fallback skips any row already claimed by a Proxmox guest — matching one
+    used to overwrite that guest's hostname, VMID and specs, and
+    non-deterministically, since one flat OR with no ordering returned whichever
+    row the database yielded first. Oldest row wins, so a re-import is stable.
+
+    A MAC *is* an identity, so its fallback matches a claimed row too. It has to:
+    the synthetic ieee embeds the host name, and a live migration or a node
+    rename changes it for what is the same guest (``pve-pve1-802`` →
+    ``pve-pve2-802``). Excluding claimed rows there would file the migrated
+    guest as a new device and orphan its old row. See ``_adopted_ieee``.
+    """
+    exact = (
+        await db.execute(
+            select(InventoryDevice).where(InventoryDevice.ieee_address == ieee)
+        )
+    ).scalars().first()
+    if exact is not None:
+        return exact
+
+    unclaimed = or_(
+        InventoryDevice.ieee_address.is_(None),
+        ~InventoryDevice.ieee_address.startswith(_PVE_IEEE_PREFIX),
+    )
+    for column, value, claimed_ok in (
+        (InventoryDevice.mac, mac, True),
+        (InventoryDevice.ip, ip, False),
+    ):
+        if not value:
+            continue
+        where = [column == value] if claimed_ok else [column == value, unclaimed]
+        row = (
+            await db.execute(
+                select(InventoryDevice)
+                .where(*where)
+                .order_by(InventoryDevice.discovered_at, InventoryDevice.id)
+            )
+        ).scalars().first()
+        if row is not None:
+            return row
+    return None
+
+
+def _adopted_ieee(current: str | None, ieee: str) -> str:
+    """The ``ieee_address`` a row should carry once this guest merges into it.
+
+    Re-point a row that already belongs to a Proxmox guest: matched by NIC MAC,
+    it is this same guest under a stale host name (migrated, or the node was
+    renamed). Links are rebuilt keyed on the ieee, so a row left on the old one
+    stops resolving as a host→guest endpoint. A mesh ieee is a real hardware
+    address and is never overwritten.
+    """
+    if not current or current.startswith(_PVE_IEEE_PREFIX):
+        return ieee
+    return current
+
+
+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,
+        # Specs the guest reports. They used to land only on the canvas node;
+        # the inventory row owns them now.
+        cpu_count=n.get("cpu_count"),
+        ram_gb=n.get("ram_gb"),
+        disk_gb=n.get("disk_gb"),
+        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_IEEE_PREFIX)
+    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 = _adopted_ieee(pending.ieee_address, 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 = _adopted_ieee(inv.ieee_address, 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,502 @@
+from collections.abc import Sequence
+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 (
+    RACK_COLUMNS,
+    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 []
+
+
+def _rack_model(device: InventoryDevice) -> dict[str, Any] | None:
+    """The rack modelisation the inventory row owns, or None when never modelled.
+
+    `rack_faceplate_id` is the flag: a device that has never been mounted (or was
+    mounted before this became inventory-owned) carries NULL, and the mount's own
+    denormalized copy then stands unchanged.
+    """
+    if not device.rack_faceplate_id:
+        return None
+    return {
+        "faceplate_id": device.rack_faceplate_id,
+        "u_height": device.rack_u_height,
+        "col_span": device.rack_col_span,
+        "color": device.rack_color,
+        "ports": [p for p in (device.rack_ports or []) if isinstance(p, dict) and p.get("id")],
+    }
+
+
+# A mount's footprint in the rack grid: (u_start, u_height, col_start, col_span).
+_Box = tuple[int, int, int, int]
+
+
+def _height_fits(u_start: int, u_height: int | None, rack_u_height: int | None) -> bool:
+    """Whether a mount of that height, starting there, stays under the top rail."""
+    if not u_height:
+        return False
+    return rack_u_height is None or u_start + u_height - 1 <= rack_u_height
+
+
+def _span_fits(col_start: int, col_span: int | None) -> bool:
+    """Whether a mount of that width, starting there, stays inside the grid."""
+    if not col_span:
+        return False
+    return col_start + col_span <= RACK_COLUMNS
+
+
+def _overlaps(box: _Box, others: Sequence[_Box]) -> bool:
+    """Whether a footprint (u_start, u_height, col_start, col_span) hits any other."""
+    u_start, u_height, col_start, col_span = box
+    return any(
+        u_start < o_u + o_uh
+        and o_u < u_start + u_height
+        and col_start < o_c + o_cs
+        and o_c < col_start + col_span
+        for o_u, o_uh, o_c, o_cs in others
+    )
+
+
+def _with_model(
+    device: RackDevice,
+    model: dict[str, Any] | None,
+    rack_u_height: int | None,
+    neighbours: Sequence[_Box] = (),
+) -> RackDeviceResponse:
+    """Overlay the inventory's rack modelisation onto a mount for the response.
+
+    Geometry is global, but a rack is not: a device grown to 4U in one rack may no
+    longer fit where it sits in another. Height and width are therefore applied
+    only when they still fit at the mount's own `u_start` / `col_start` *and* the
+    bigger footprint lands on no neighbour — the placement rule the canvas itself
+    enforces, and one a plain rail check misses: a 4U model overlaid on a mount
+    with a device one U above it would draw two plates on the same U, and save
+    back in that state. The plate, its colour and its ports always are, since
+    none of them can overflow anything.
+    """
+    row = RackDeviceResponse.model_validate(device)
+    if model is None:
+        return row
+    patch: dict[str, Any] = {
+        "faceplate_id": model["faceplate_id"],
+        "ports": model["ports"],
+        "color": model["color"],
+    }
+    u_height = row.u_height
+    if _height_fits(row.u_start, model["u_height"], rack_u_height) and not _overlaps(
+        (row.u_start, model["u_height"], row.col_start, row.col_span), neighbours
+    ):
+        u_height = model["u_height"]
+        patch["u_height"] = u_height
+    if _span_fits(row.col_start, model["col_span"]) and not _overlaps(
+        (row.u_start, u_height, row.col_start, model["col_span"]), neighbours
+    ):
+        patch["col_span"] = model["col_span"]
+    return row.model_copy(update=patch)
+
+
+_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)
+
+    # The inventory row owns the front panel, so it wins over the mount's copy.
+    inventory_ids = {d.device_id for d in devices if d.device_id}
+    models: dict[str, dict[str, Any]] = {}
+    if inventory_ids:
+        rows = (
+            await db.execute(
+                select(InventoryDevice).where(InventoryDevice.id.in_(inventory_ids))
+            )
+        ).scalars().all()
+        for row in rows:
+            model = _rack_model(row)
+            if model is not None:
+                models[row.id] = model
+    heights = {r.id: r.u_height for r in racks}
+
+    # An overlaid size must not land on the mount above. Footprints start as
+    # persisted and are replaced by what the overlay actually applied, so a rack
+    # of devices that all grew elsewhere resolves in one deterministic pass
+    # instead of each one being measured against stale neighbours.
+    boxes: dict[str, _Box] = {
+        d.id: (d.u_start, d.u_height, d.col_start, d.col_span) for d in devices
+    }
+    mounted: list[RackDeviceResponse] = []
+    for d in devices:
+        placed = _with_model(
+            d,
+            models.get(d.device_id or ""),
+            heights.get(d.rack_id),
+            [boxes[o.id] for o in devices if o.id != d.id and o.rack_id == d.rack_id],
+        )
+        boxes[d.id] = (placed.u_start, placed.u_height, placed.col_start, placed.col_span)
+        mounted.append(placed)
+
+    return RackStateResponse(
+        racks=[RackResponse.model_validate(r) for r in racks],
+        devices=mounted,
+        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)
+        # The size this mount held before the save, to tell a real resize from an
+        # echo of what the load handed out. See the write-through below.
+        was = (db_device.u_height, db_device.col_span) if db_device else None
+        if db_device:
+            for field, value in payload.items():
+                setattr(db_device, field, value)
+        else:
+            db.add(RackDevice(**payload))
+
+        # Write-through: the device's front panel belongs to the inventory row,
+        # not to this mount, so every rack showing the same device picks the
+        # change up on its next load. Accessories have no row and keep theirs.
+        if device_data.device_id:
+            entry = await db.get(InventoryDevice, device_data.device_id)
+            if entry is not None:
+                entry.rack_faceplate_id = device_data.faceplate_id
+                entry.rack_color = device_data.color
+                entry.rack_ports = [p for p in device_data.ports if isinstance(p, dict)]
+                # Size, unlike the plate, is not written back blind. The load
+                # overlays it only where it still fits this rack, so a mount can
+                # legitimately hold less than the row does — and saving that back
+                # would shrink the device in every other rack. Only a size this
+                # save actually changes travels; an unchanged one is an echo.
+                if was is None or device_data.u_height != was[0]:
+                    entry.rack_u_height = device_data.u_height
+                if was is None or device_data.col_span != was[1]:
+                    entry.rack_col_span = device_data.col_span
+    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: a node names the inventory row it draws,
+    # so the IEEE/IP guessing this used to do is gone — the link is explicit.
+    nodes = (await db.execute(select(Node))).scalars().all()
+    by_id = {n.id: n for n in nodes}
+    by_device: dict[str, Node] = {}
+    for node in nodes:
+        if node.device_id:
+            by_device.setdefault(node.device_id, 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()
+    }
+
+    # A pinned node may draw a *different* device than the mount names, so its
+    # view is read off its own row.
+    devices_by_id = {d.id: d for d in devices}
+
+    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
+        # node that draws this device, if any.
+        linked: Node | None = by_id.get(pinned.get(device.id) or "") or by_device.get(device.id)
+        # The logical view is whatever the linked node actually draws. Usually
+        # that is this same row — the node_* fields then simply mirror it.
+        node_device = None
+        if linked is not None:
+            node_device = devices_by_id.get(linked.device_id or "")
+            if node_device is None and linked.device_id:
+                node_device = await db.get(InventoryDevice, linked.device_id)
+        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(device.services),
+                node_id=linked.id if linked else None,
+                node_status=node_device.status_live if node_device else None,
+                node_label=(
+                    (node_device.label if node_device else None) or linked.label
+                ) if linked else None,
+                node_type=(
+                    (node_device.type if node_device else None) or linked.type
+                ) if linked else None,
+                node_ip=node_device.ip if node_device else None,
+                node_mac=(node_device.mac or node_device.ieee_address) if node_device else None,
+                node_hostname=node_device.hostname if node_device else None,
+                node_os=node_device.os if node_device else None,
+                node_check_method=node_device.check_method if node_device 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=node_device.last_seen if node_device else None,
+                racked=device.id in mounted,
+                rack_faceplate_id=device.rack_faceplate_id,
+                rack_u_height=device.rack_u_height,
+                rack_col_span=device.rack_col_span,
+                rack_color=device.rack_color,
+                rack_ports=device.rack_ports or [],
+            )
+        )
+    return RackInventoryResponse(items=items)

backend/app/api/routes/settings.py

@@ -1,20 +1,33 @@
 """App-level settings (status checker interval, etc.)."""
 from fastapi import APIRouter, Depends, HTTPException
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from app.api.deps import get_current_user
 from app.core.config import settings
+from app.core.scheduler import (
+    reschedule_service_checks,
+    reschedule_status_checks,
+    set_service_checks_enabled,
+)
 
 router = APIRouter()
 
 
 class AppSettings(BaseModel):
-    interval_seconds: int
+    # Mirrors the floor enforced by reschedule_status_checks(): rejecting here
+    # returns 422 instead of persisting the value and then failing with a 500.
+    interval_seconds: int = Field(ge=10)
+    service_check_enabled: bool = False
+    service_check_interval: int = Field(default=300, ge=30)
 
 
 @router.get("", response_model=AppSettings)
 async def get_settings(_: str = Depends(get_current_user)) -> AppSettings:
-    return AppSettings(interval_seconds=settings.status_checker_interval)
+    return AppSettings(
+        interval_seconds=settings.status_checker_interval,
+        service_check_enabled=settings.service_check_enabled,
+        service_check_interval=settings.service_check_interval,
+    )
 
 
 @router.post("", response_model=AppSettings)
@@ -23,7 +36,17 @@ async def update_settings(
 ) -> AppSettings:
     try:
         settings.status_checker_interval = payload.interval_seconds
+        settings.service_check_enabled = payload.service_check_enabled
+        settings.service_check_interval = payload.service_check_interval
         settings.save_overrides()
+        # Apply the status-check schedule live. Without this the new interval is
+        # persisted and shown in the UI, but the running job keeps the old one
+        # until the backend restarts.
+        reschedule_status_checks(payload.interval_seconds)
+        # Apply the service-check schedule live.
+        set_service_checks_enabled(payload.service_check_enabled)
+        if payload.service_check_enabled:
+            reschedule_service_checks(payload.service_check_interval)
         return payload
     except Exception as exc:
         raise HTTPException(status_code=500, detail=str(exc)) from exc

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()
 
@@ -30,22 +30,38 @@ async def summary(
     """
     _check_key(x_api_key)
 
+    # A node's reachability lives on the Device Inventory row it draws, so the
+    # per-canvas counts come from the join. A node with no row (canvas
+    # furniture) counts as unknown.
     status_rows = (
-        await db.execute(select(Node.status, func.count()).group_by(Node.status))
+        await db.execute(
+            select(InventoryDevice.status_live, func.count())
+            .select_from(Node)
+            .join(InventoryDevice, Node.device_id == InventoryDevice.id)
+            .group_by(InventoryDevice.status_live)
+        )
     ).all()
-    counts = {row[0]: row[1] for row in status_rows}
+    counts = {(row[0] or "unknown"): row[1] for row in status_rows}
+    unlinked = (
+        await db.execute(select(func.count()).select_from(Node).where(Node.device_id.is_(None)))
+    ).scalar_one()
+    if unlinked:
+        counts["unknown"] = counts.get("unknown", 0) + unlinked
 
     pending = (
         await db.execute(
             select(func.count())
-            .select_from(PendingDevice)
-            .where(PendingDevice.status == "pending")
+            .select_from(InventoryDevice)
+            .where(InventoryDevice.status == "pending")
         )
     ).scalar_one()
 
     zigbee = (
         await db.execute(
-            select(func.count()).select_from(Node).where(Node.ieee_address.isnot(None))
+            select(func.count())
+            .select_from(Node)
+            .join(InventoryDevice, Node.device_id == InventoryDevice.id)
+            .where(InventoryDevice.ieee_address.isnot(None))
         )
     ).scalar_one()
 
@@ -58,6 +74,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

@@ -1,8 +1,15 @@
+import contextlib
 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()
 
@@ -10,30 +17,50 @@ router = APIRouter()
 _connections: list[WebSocket] = []
 
 
+def _drop(websocket: WebSocket) -> None:
+    """Remove a connection if still present — idempotent, never raises."""
+    with contextlib.suppress(ValueError):
+        _connections.remove(websocket)
+
+
 @router.websocket("/ws/status")
 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:
         while True:
             await websocket.receive_text()
     except WebSocketDisconnect:
-        _connections.remove(websocket)
+        pass
+    finally:
+        # Any error (disconnect or otherwise) must release the slot, else the
+        # dead socket lingers in the broadcast pool.
+        _drop(websocket)
 
 
 async def _broadcast(payload: str) -> None:
@@ -41,19 +68,44 @@ async def _broadcast(payload: str) -> None:
         try:
             await conn.send_text(payload)
         except Exception:
-            _connections.remove(conn)
+            _drop(conn)
 
 
-async def broadcast_status(node_id: str, status: str, checked_at: str, response_time_ms: int | None = None) -> None:
+async def broadcast_status(
+    device_id: str,
+    node_ids: list[str],
+    status: str,
+    checked_at: str,
+    response_time_ms: int | None = None,
+) -> None:
+    """Report one device's reachability to every canvas drawing it.
+
+    A device is checked once, not once per canvas, so the result is addressed by
+    device and carries the nodes it lights up. ``node_ids`` is empty for a
+    device that is in the inventory but on no canvas.
+    """
     await _broadcast(json.dumps({
         "type": "status",
-        "node_id": node_id,
+        "device_id": device_id,
+        "node_ids": node_ids,
         "status": status,
         "checked_at": checked_at,
         "response_time_ms": response_time_ms,
     }))
 
 
+async def broadcast_service_status(
+    device_id: str, node_ids: list[str], services: list[dict[str, object]], checked_at: str
+) -> None:
+    await _broadcast(json.dumps({
+        "type": "service_status",
+        "device_id": device_id,
+        "node_ids": node_ids,
+        "services": services,
+        "checked_at": checked_at,
+    }))
+
+
 async def broadcast_scan_update(run_id: str, devices_found: int) -> None:
     await _broadcast(json.dumps({
         "type": "scan_device_found",

backend/app/api/routes/zigbee.py

@@ -10,19 +10,28 @@ 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 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,
+    ZigbeeImportJob,
+    ZigbeeImportJobResult,
     ZigbeeImportPendingResponse,
     ZigbeeImportRequest,
     ZigbeeImportResponse,
     ZigbeeNodeOut,
+    ZigbeeSyncConfig,
     ZigbeeTestConnectionRequest,
     ZigbeeTestConnectionResponse,
 )
+from app.services.import_jobs import create_job, fail_job, finish_job, get_job
+from app.services.inventory_sync import attach_device_ids
+from app.services.node_dedupe import dedupe_nodes_by_device
 from app.services.zigbee_service import (
     build_zigbee_properties,
     fetch_networkmap,
@@ -31,21 +40,82 @@ from app.services.zigbee_service import (
 )
 
 logger = logging.getLogger(__name__)
+
+
+async def _is_drawn(db: AsyncSession, device_id: str) -> bool:
+    """True while at least one canvas node still draws this device."""
+    return (
+        await db.execute(select(Node.id).where(Node.device_id == device_id).limit(1))
+    ).scalar_one_or_none() is not None
+
+
 router = APIRouter()
 
 
-@router.post("/import", response_model=ZigbeeImportResponse)
+def _import_error(exc: BaseException) -> tuple[int, str]:
+    """Map a fetch_networkmap failure to the (status, detail) the API reports."""
+    if isinstance(exc, ImportError):
+        return 500, str(exc)
+    if isinstance(exc, ConnectionError):
+        return 502, str(exc)
+    if isinstance(exc, TimeoutError):
+        return 504, str(exc)
+    if isinstance(exc, ValueError):
+        return 422, str(exc)
+    logger.exception("Unexpected error during Zigbee import", exc_info=exc)
+    return 500, "Unexpected error during Zigbee import"
+
+
+@router.post("/import", response_model=ZigbeeImportJob, status_code=202)
 async def import_zigbee_network(
     payload: ZigbeeImportRequest,
+    background_tasks: BackgroundTasks,
     _: str = Depends(get_current_user),
-) -> ZigbeeImportResponse:
-    """Fetch the Zigbee2MQTT network map and return nodes + edges ready for canvas drop.
+) -> ZigbeeImportJob:
+    """Start a canvas import and return a job id to poll.
 
     Connects to the specified MQTT broker, publishes a networkmap request to
-    ``<base_topic>/bridge/request/networkmap``, and waits up to 60 s for the
-    response (large meshes can take 30 s+).  The devices are returned as typed homelable nodes with a
-    coordinator → router → end-device hierarchy.
+    ``<base_topic>/bridge/request/networkmap`` and waits up to
+    ``ZIGBEE_NETWORKMAP_TIMEOUT`` seconds (default 300) for the response.
+
+    The fetch runs in the background and the result is collected from
+    ``GET /zigbee/import/{job_id}``: a 200+ device mesh takes minutes to answer,
+    which outlives the read timeout of any reverse proxy sitting in front of the
+    API. Polling keeps each request short.
     """
+    job = create_job()
+    background_tasks.add_task(_background_canvas_import, job.id, payload)
+    return ZigbeeImportJob(job_id=job.id, status=job.status)
+
+
+@router.get("/import/{job_id}", response_model=ZigbeeImportJobResult)
+async def get_zigbee_import_job(
+    job_id: str,
+    _: str = Depends(get_current_user),
+) -> ZigbeeImportJobResult:
+    """Poll a canvas import started by ``POST /zigbee/import``.
+
+    While running, returns ``status="running"`` with no payload. On success the
+    nodes and edges are carried in ``result``. A failed fetch is reported as the
+    status code the synchronous route used to raise, so the client keeps
+    distinguishing a bad broker (502) from a slow mesh (504).
+    """
+    job = get_job(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="Import job not found or expired")
+    if job.status == "error":
+        raise HTTPException(
+            status_code=job.error_status or 500,
+            detail=job.error or "Zigbee import failed",
+        )
+    result = None
+    if job.status == "done" and job.result is not None:
+        result = ZigbeeImportResponse(**job.result)
+    return ZigbeeImportJobResult(job_id=job.id, status=job.status, result=result)
+
+
+async def _background_canvas_import(job_id: str, payload: ZigbeeImportRequest) -> None:
+    """Fetch the network map and park the canvas-ready payload on the job."""
     try:
         nodes_raw, edges_raw = await fetch_networkmap(
             mqtt_host=payload.mqtt_host,
@@ -56,21 +126,31 @@ async def import_zigbee_network(
             tls=payload.mqtt_tls,
             tls_insecure=payload.mqtt_tls_insecure,
         )
-    except ImportError as exc:
-        raise HTTPException(status_code=500, detail=str(exc)) from exc
-    except ConnectionError as exc:
-        raise HTTPException(status_code=502, detail=str(exc)) from exc
-    except TimeoutError as exc:
-        raise HTTPException(status_code=504, 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 Zigbee import")
-        raise HTTPException(status_code=500, detail="Unexpected error during Zigbee import") from exc
+        status, detail = _import_error(exc)
+        fail_job(job_id, detail, status)
+        return
+
+    # A canvas import is an import: the devices land in the Device Inventory
+    # too, and each node carries the id of the row it draws so the canvas save
+    # links to it instead of minting a second, IEEE-less row.
+    try:
+        async with AsyncSessionLocal() as db:
+            await _persist_pending_import(db, nodes_raw, edges_raw)
+            nodes_raw = await attach_device_ids(db, nodes_raw)
+    except Exception as exc:
+        status, detail = _import_error(exc)
+        fail_job(job_id, detail, status)
+        return
 
     nodes = [ZigbeeNodeOut(**n) for n in nodes_raw]
     edges = [ZigbeeEdgeOut(**e) for e in edges_raw]
-    return ZigbeeImportResponse(nodes=nodes, edges=edges, device_count=len(nodes))
+    finish_job(
+        job_id,
+        ZigbeeImportResponse(
+            nodes=nodes, edges=edges, device_count=len(nodes)
+        ).model_dump(),
+    )
 
 
 @router.post("/import-pending", response_model=ScanRunResponse)
@@ -98,6 +178,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,11 +260,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.
     """
+    # 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_device(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
@@ -151,57 +284,21 @@ 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:
-                existing_node.properties = merge_zigbee_properties(
-                    existing_node.properties, props
-                )
-                coordinator_out = ZigbeeCoordinatorOut(
-                    id=existing_node.id,
-                    label=existing_node.label,
-                    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,
-            )
-            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
-            )
-            continue
+        # 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.
 
+        # Properties belong to the inventory row now, so one upsert serves
+        # every canvas drawing this device — there is no per-node refresh left
+        # to do. The row's status is never touched here: an approved device
+        # stays approved, a hidden one stays hidden.
         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"),
@@ -210,6 +307,7 @@ async def _persist_pending_import(
                     model=n.get("model"),
                     vendor=n.get("vendor"),
                     lqi=n.get("lqi"),
+                    properties=props,
                     status="pending",
                     discovery_source="zigbee",
                 )
@@ -223,14 +321,20 @@ async def _persist_pending_import(
             pending.vendor = n.get("vendor") or pending.vendor
             if n.get("lqi") is not None:
                 pending.lqi = n.get("lqi")
-            if pending.status == "hidden":
+            pending.properties = merge_zigbee_properties(list(pending.properties or []), props)
+            if pending.status == "approved" and not await _is_drawn(db, pending.id):
+                # Approved earlier but no canvas draws it any more — the node was
+                # deleted. Revive the row to "pending" so it reappears in the list
+                # on re-import instead of being silently swallowed. (Issue #167)
+                pending.status = "pending"
+            elif pending.status == "hidden":
                 # Re-imported a hidden device → leave it hidden, just refresh fields.
                 pass
             pending_updated += 1
 
     # 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
@@ -242,7 +346,7 @@ async def _persist_pending_import(
             continue
         seen.add((src, tgt))
         db.add(
-            PendingDeviceLink(
+            InventoryDeviceLink(
                 source_ieee=src,
                 target_ieee=tgt,
                 discovery_source="zigbee",
@@ -285,3 +389,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

@@ -0,0 +1,372 @@
+"""FastAPI router for Z-Wave JS UI (zwavejs2mqtt) import."""
+
+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 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 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.inventory_sync import attach_device_ids
+from app.services.node_dedupe import dedupe_nodes_by_device
+from app.services.zwave_service import (
+    build_zwave_properties,
+    fetch_zwave_network,
+    merge_zwave_properties,
+    test_zwave_connection,
+)
+
+logger = logging.getLogger(__name__)
+
+
+async def _is_drawn(db: AsyncSession, device_id: str) -> bool:
+    """True while at least one canvas node still draws this device."""
+    return (
+        await db.execute(select(Node.id).where(Node.device_id == device_id).limit(1))
+    ).scalar_one_or_none() is not None
+
+
+router = APIRouter()
+
+
+@router.post("/import", response_model=ZwaveImportResponse)
+async def import_zwave_network(
+    payload: ZwaveImportRequest,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> ZwaveImportResponse:
+    """Fetch the Z-Wave node list and return nodes + edges ready for canvas drop.
+
+    Connects to the broker, publishes a ``getNodes`` request to the Z-Wave JS UI
+    gateway, and waits for the response. Devices are returned as typed homelable
+    nodes with a coordinator → router → end-device hierarchy.
+    """
+    try:
+        nodes_raw, edges_raw = await fetch_zwave_network(
+            mqtt_host=payload.mqtt_host,
+            mqtt_port=payload.mqtt_port,
+            prefix=payload.prefix,
+            gateway_name=payload.gateway_name,
+            username=payload.mqtt_username,
+            password=payload.mqtt_password,
+            tls=payload.mqtt_tls,
+            tls_insecure=payload.mqtt_tls_insecure,
+        )
+    except ImportError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+    except ConnectionError as exc:
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+    except TimeoutError as exc:
+        raise HTTPException(status_code=504, 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 Z-Wave import")
+        raise HTTPException(status_code=500, detail="Unexpected error during Z-Wave import") from exc
+
+    # A canvas import is an import: the devices land in the Device Inventory too,
+    # and each node carries the id of the row it draws so the canvas save links
+    # to it instead of minting a second, IEEE-less row.
+    await _persist_pending_import(db, nodes_raw, edges_raw)
+    nodes_raw = await attach_device_ids(db, nodes_raw)
+
+    nodes = [ZwaveNodeOut(**n) for n in nodes_raw]
+    edges = [ZwaveEdgeOut(**e) for e in edges_raw]
+    return ZwaveImportResponse(nodes=nodes, edges=edges, device_count=len(nodes))
+
+
+@router.post("/import-pending", response_model=ScanRunResponse)
+async def import_zwave_to_pending(
+    payload: ZwaveImportRequest,
+    background_tasks: BackgroundTasks,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> ScanRun:
+    """Queue a Z-Wave pending import as a background scan run (kind=zwave)."""
+    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
+
+
+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:
+            nodes_raw, edges_raw = await fetch_zwave_network(
+                mqtt_host=payload.mqtt_host,
+                mqtt_port=payload.mqtt_port,
+                prefix=payload.prefix,
+                gateway_name=payload.gateway_name,
+                username=payload.mqtt_username,
+                password=payload.mqtt_password,
+                tls=payload.mqtt_tls,
+                tls_insecure=payload.mqtt_tls_insecure,
+            )
+            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)
+                await db.commit()
+        except Exception as exc:
+            logger.exception("Z-Wave 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()
+
+
+async def _persist_pending_import(
+    db: AsyncSession,
+    nodes_raw: list[dict[str, Any]],
+    edges_raw: list[dict[str, Any]],
+) -> ZwaveImportPendingResponse:
+    """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.
+    """
+    # Repair any pre-existing same-canvas duplicate nodes before upserting, so
+    # the by-IEEE lookups below resolve cleanly.
+    await dedupe_nodes_by_device(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
+    pending_updated = 0
+
+    for n in nodes_raw:
+        ieee = n.get("ieee_address")
+        if not ieee:
+            continue
+        props = build_zwave_properties(ieee, n.get("vendor"), n.get("model"))
+
+        # 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.
+
+        # Properties belong to the inventory row now, so one upsert serves
+        # every canvas drawing this device — there is no per-node refresh left
+        # to do. The row's status is never touched here: an approved device
+        # stays approved, a hidden one stays hidden.
+        result = await db.execute(
+            select(InventoryDevice).where(InventoryDevice.ieee_address == ieee)
+        )
+        pending = result.scalar_one_or_none()
+        if pending 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"),
+                    properties=props,
+                    status="pending",
+                    discovery_source="zwave",
+                )
+            )
+            pending_created += 1
+        else:
+            pending.friendly_name = n.get("friendly_name") or pending.friendly_name
+            pending.suggested_type = n.get("type") or pending.suggested_type
+            pending.device_subtype = n.get("device_type") or pending.device_subtype
+            pending.model = n.get("model") or pending.model
+            pending.vendor = n.get("vendor") or pending.vendor
+            pending.properties = merge_zwave_properties(list(pending.properties or []), props)
+            if pending.status == "approved" and not await _is_drawn(db, pending.id):
+                # Approved earlier but no canvas draws it any more (the node was
+                # deleted) — revive to "pending" so it reappears in the list.
+                pending.status = "pending"
+            elif pending.status == "hidden":
+                pass
+            pending_updated += 1
+
+    # Replace all zwave-source links with the freshly discovered set.
+    await db.execute(
+        sa_delete(InventoryDeviceLink).where(InventoryDeviceLink.discovery_source == "zwave")
+    )
+
+    links_recorded = 0
+    seen: set[tuple[str, str]] = set()
+    for e in edges_raw:
+        src = e.get("source")
+        tgt = e.get("target")
+        if not src or not tgt or (src, tgt) in seen:
+            continue
+        seen.add((src, tgt))
+        db.add(
+            InventoryDeviceLink(
+                source_ieee=src,
+                target_ieee=tgt,
+                discovery_source="zwave",
+            )
+        )
+        links_recorded += 1
+
+    await db.commit()
+
+    return ZwaveImportPendingResponse(
+        pending_created=pending_created,
+        pending_updated=pending_updated,
+        coordinator=coordinator_out,
+        coordinator_already_existed=coordinator_existed,
+        links_recorded=links_recorded,
+        device_count=len(nodes_raw),
+    )
+
+
+@router.post("/test-connection", response_model=ZwaveTestConnectionResponse)
+async def test_connection_endpoint(
+    payload: ZwaveTestConnectionRequest,
+    _: str = Depends(get_current_user),
+) -> ZwaveTestConnectionResponse:
+    """Quick MQTT ping to validate broker connection before importing."""
+    try:
+        await test_zwave_connection(
+            mqtt_host=payload.mqtt_host,
+            mqtt_port=payload.mqtt_port,
+            username=payload.mqtt_username,
+            password=payload.mqtt_password,
+            tls=payload.mqtt_tls,
+            tls_insecure=payload.mqtt_tls_insecure,
+        )
+        return ZwaveTestConnectionResponse(connected=True, message="Connection successful")
+    except ImportError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+    except (ConnectionError, TimeoutError) as exc:
+        return ZwaveTestConnectionResponse(connected=False, message=str(exc))
+    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,12 +1,62 @@
 import json
 import logging
 from pathlib import Path
+from typing import Literal
+from urllib.parse import urlsplit
 
-from pydantic import model_validator
+from pydantic import Field, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 logger = logging.getLogger(__name__)
 
+
+def origin_of(url: str) -> str:
+    """`scheme://host[:port]` of an absolute URL, or "" when it has none."""
+    parts = urlsplit(url)
+    if not parts.scheme or not parts.netloc:
+        return ""
+    return f"{parts.scheme}://{parts.netloc}"
+
+
+OIDC_CALLBACK_PATH = "/api/v1/auth/oidc/callback"
+
+
+def app_base_path_of(redirect_uri: str) -> str:
+    """
+    Path the SPA is served under, read back from OIDC_REDIRECT_URI.
+
+    The frontend can be mounted under a prefix (`VITE_BASE_PATH=/homelab/`), and the
+    backend only ever learns about it through the callback URL the operator
+    configured — `https://home.example/homelab/api/v1/auth/oidc/callback` means the
+    app lives at `/homelab/`. Always returns a path with a trailing slash; `/` when
+    the URI is unset, relative, or not a callback URL.
+    """
+    path = urlsplit(redirect_uri).path
+    if not path.endswith(OIDC_CALLBACK_PATH):
+        return "/"
+    base = path[: -len(OIDC_CALLBACK_PATH)]
+    return f"{base}/" if base else "/"
+
+def unquote_env(value: str) -> str:
+    """
+    Drop one matched pair of surrounding quotes from an env value.
+
+    Secrets that contain `$` (bcrypt hashes, most OIDC client secrets) have to be
+    single-quoted in `.env`, or Docker Compose eats the `$`. Compose then strips
+    those quotes itself when it reads `env_file`, and so does python-dotenv on the
+    `env_file=` path — but `podman-compose` (1.0.6) passes them through verbatim,
+    so the container receives `'$2b$12$…'`, quotes included, and every bcrypt
+    verify fails. Unwrap here rather than asking operators to quote differently
+    per container runtime.
+
+    Only a *matched* pair is removed, so a genuinely malformed value still reaches
+    the validation below instead of being silently patched up.
+    """
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+        return value[1:-1]
+    return value
+
+
 def _read_version() -> str:
     for candidate in [
         Path(__file__).parent.parent.parent.parent / "VERSION",  # repo root (dev)
@@ -24,6 +74,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 +85,28 @@ 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":
+        # Runtime-dependent quoting: see unquote_env. Applied to the three values
+        # that routinely contain a `$` and so get quoted in .env.
+        self.secret_key = unquote_env(self.secret_key)
+        self.auth_password_hash = unquote_env(self.auth_password_hash)
+        self.oidc_client_secret = unquote_env(self.oidc_client_secret)
+
         h = self.auth_password_hash
         if h and not h.startswith("$2"):
             logger.error(
@@ -43,14 +114,76 @@ 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")
+            app_origin = origin_of(self.oidc_redirect_uri)
+            allowed = {value.rstrip("/") for value in self.cors_origins}
+            if app_origin and app_origin not in allowed:
+                logger.warning(
+                    "CORS_ORIGINS does not list %s (the origin of OIDC_REDIRECT_URI). "
+                    "The CSRF check accepts that origin anyway, but add it to CORS_ORIGINS "
+                    "so browser requests are not rejected: CORS_ORIGINS=[\"%s\"]",
+                    app_origin,
+                    app_origin,
+                )
         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
+
+    # Per-device deep rescan: total time budget in seconds, checked between port
+    # slices. Unprivileged nmap falls back to a connect scan (-sT), and a host
+    # that drops packets makes every filtered port wait out its RTT — the whole
+    # range against such a host runs ~20-45 min. When the budget is spent the
+    # run keeps what it found and says how much it did not reach. This is NOT an
+    # nmap --host-timeout: that one discards a host's results wholesale.
+    scanner_deep_host_timeout: int = 2700
+
+    # 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] = []
+    scanner_http_probe_enabled: bool = False
+    scanner_http_verify_tls: bool = False
+
     # Status checker
     status_checker_interval: int = 60
 
+    # Per-service status checker (independent of node checks). Off by default.
+    service_check_enabled: bool = False
+    service_check_interval: int = 300
+
     # MCP service key — set MCP_SERVICE_KEY in .env
     # Used by the MCP server to authenticate against the backend without a user password.
     # Leave empty to disable MCP service key auth.
@@ -66,9 +199,63 @@ 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)
+    # Seconds to wait for the Z2M bridge to answer a networkmap request. A mesh
+    # of 200+ devices can take several minutes to build the map, so raise this
+    # if imports fail with "Timed out waiting for networkmap response".
+    zigbee_networkmap_timeout: int = 300
+
+    # 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)
+
+    # Seconds to wait for any MQTT gateway request/response round-trip
+    # (the Z-Wave node dump today). Same rationale as the Zigbee twin above.
+    mqtt_response_timeout: int = 300
+
     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:
@@ -77,6 +264,35 @@ class Settings(BaseSettings):
                 self.scanner_ranges = data["scanner_ranges"]
             if "status_checker_interval" in data:
                 self.status_checker_interval = int(data["status_checker_interval"])
+            if "service_check_enabled" in data:
+                self.service_check_enabled = bool(data["service_check_enabled"])
+            if "service_check_interval" in data:
+                self.service_check_interval = int(data["service_check_interval"])
+            if "scanner_http_ranges" in data:
+                self.scanner_http_ranges = list(data["scanner_http_ranges"])
+            if "scanner_http_probe_enabled" in data:
+                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
 
@@ -86,6 +302,22 @@ class Settings(BaseSettings):
         self._override_path().write_text(json.dumps({
             "scanner_ranges": self.scanner_ranges,
             "status_checker_interval": self.status_checker_interval,
+            "service_check_enabled": self.service_check_enabled,
+            "service_check_interval": self.service_check_interval,
+            "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,28 +1,45 @@
 """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
+from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.config import settings
 from app.db.database import AsyncSessionLocal
-from app.db.models import Node
-from app.services.status_checker import check_node
+from app.db.models import InventoryDevice, 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()
 
 
-async def _check_single_node(
-    node_id: str,
+async def _nodes_by_device(db: AsyncSession) -> dict[str, list[str]]:
+    """Map each device id to the nodes drawing it, across every canvas."""
+    rows = (await db.execute(select(Node.id, Node.device_id).where(Node.device_id.is_not(None)))).all()
+    out: dict[str, list[str]] = {}
+    for node_id, device_id in rows:
+        out.setdefault(device_id, []).append(node_id)
+    return out
+
+
+async def _check_single_device(
+    device_id: str,
+    node_ids: list[str],
     check_method: str,
     check_target: str | None,
     ip: str | None,
 ) -> tuple[str, dict[str, object] | None]:
-    """Run a single node check; returns (node_id, result_or_None).
+    """Run a single device check; returns (device_id, result_or_None).
 
     Accepts plain scalars — not an ORM object — so there is no risk of
     DetachedInstanceError when the originating session has already closed.
@@ -31,48 +48,246 @@ async def _check_single_node(
 
     try:
         check_result = await check_node(check_method, check_target, ip)
+        raw_ms = check_result["response_time_ms"]
+        response_ms = raw_ms if isinstance(raw_ms, int) else None
         now = datetime.now(timezone.utc)
         async with AsyncSessionLocal() as db:
-            n = await db.get(Node, node_id)
-            if n:
-                n.status = check_result["status"]
-                n.response_time_ms = check_result["response_time_ms"]
+            device = await db.get(InventoryDevice, device_id)
+            if device:
+                device.status_live = str(check_result["status"])
+                device.response_time_ms = response_ms
                 if check_result["status"] == "online":
-                    n.last_seen = now
+                    device.last_seen = now
                 await db.commit()
         await broadcast_status(
-            node_id=node_id,
-            status=check_result["status"],
+            device_id=device_id,
+            node_ids=node_ids,
+            status=str(check_result["status"]),
             checked_at=now.isoformat(),
-            response_time_ms=check_result["response_time_ms"],
+            response_time_ms=response_ms,
         )
-        return node_id, check_result
+        return device_id, check_result
     except Exception as exc:
-        logger.error("Status check failed for node %s: %s", node_id, exc)
-        return node_id, None
+        logger.error("Status check failed for device %s: %s", device_id, exc)
+        return device_id, None
 
 
 async def _run_status_checks() -> None:
-    """Check all nodes concurrently and broadcast results via WebSocket."""
+    """Check every device once and broadcast the result to every canvas.
+
+    Device-scoped, not node-scoped: a host drawn on three canvases used to be
+    pinged three times and could report three different states. Hidden devices
+    are skipped — hiding one is how a user says "stop showing me this".
+
+    A device with no node at all is still checked, deliberately. The inventory
+    row owns the device and shows its live status in the list and the detail
+    modal, so a rack mount or an inventory-only entry reports state without
+    being drawn anywhere — and deleting a node no longer silently stops
+    monitoring the host. `hide` (or clearing the check method) is what ends the
+    checks; the broadcast simply carries an empty `node_ids`.
+    """
     async with AsyncSessionLocal() as db:
-        result = await db.execute(select(Node))
-        nodes = result.scalars().all()
+        devices = (
+            await db.execute(
+                select(InventoryDevice).where(
+                    InventoryDevice.check_method.is_not(None),
+                    InventoryDevice.check_method != "",
+                    InventoryDevice.status != "hidden",
+                )
+            )
+        ).scalars().all()
+        node_map = await _nodes_by_device(db)
         # Extract scalars while the session is open to avoid DetachedInstanceError
         checkable = [
-            (n.id, n.check_method, n.check_target, n.ip)
-            for n in nodes
-            if n.check_method
+            (d.id, node_map.get(d.id, []), d.check_method or "ping", d.check_target, d.ip)
+            for d in devices
         ]
 
     if not checkable:
         return
 
     await asyncio.gather(*[
-        _check_single_node(node_id, method, target, ip)
-        for node_id, method, target, ip in checkable
+        _check_single_device(device_id, node_ids, method, target, ip)
+        for device_id, node_ids, method, target, ip in checkable
     ])
 
 
+def _node_host(ip: str | None, hostname: str | None) -> str | None:
+    """Pick the address to probe services on: first IP, else hostname."""
+    if ip:
+        first = ip.split(",")[0].strip()
+        if first:
+            return first
+    return hostname or None
+
+
+async def _run_service_checks() -> None:
+    """Check every service of every device and broadcast per-service results.
+
+    Device-scoped for the same reason as the status check: the services belong
+    to the device, so one pass serves every canvas showing it.
+    """
+    if not settings.service_check_enabled:
+        return
+    from app.api.routes.status import broadcast_service_status  # avoid circular import
+
+    async with AsyncSessionLocal() as db:
+        devices = (
+            await db.execute(select(InventoryDevice).where(InventoryDevice.status != "hidden"))
+        ).scalars().all()
+        node_map = await _nodes_by_device(db)
+        checkable = [
+            (d.id, node_map.get(d.id, []), _node_host(d.ip, d.hostname), list(d.services or []))
+            for d in devices
+            if d.services
+        ]
+
+    now = datetime.now(timezone.utc).isoformat()
+    for device_id, node_ids, host, services in checkable:
+        try:
+            statuses = await check_services(host, services)
+            await broadcast_service_status(
+                device_id=device_id, node_ids=node_ids, services=statuses, checked_at=now
+            )
+        except Exception as exc:
+            logger.error("Service checks failed for device %s: %s", device_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,
+        "interval",
+        seconds=settings.service_check_interval,
+        id="service_checks",
+        max_instances=1,
+        coalesce=True,
+    )
+
+
+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:
@@ -89,6 +304,14 @@ def start_scheduler() -> None:
         max_instances=1,
         coalesce=True,
     )
+    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)
 
@@ -104,6 +327,106 @@ def reschedule_status_checks(interval_seconds: int) -> None:
     logger.info("Status checks rescheduled to every %ds", interval_seconds)
 
 
+def reschedule_service_checks(interval_seconds: int) -> None:
+    """Update the service-check interval on the running scheduler (if enabled)."""
+    if interval_seconds < 30:
+        raise ValueError(f"interval_seconds must be >= 30, got {interval_seconds}")
+    if not scheduler.running:
+        logger.warning("Scheduler not running, skipping reschedule")
+        return
+    if scheduler.get_job("service_checks"):
+        scheduler.reschedule_job("service_checks", trigger="interval", seconds=interval_seconds)
+        logger.info("Service checks rescheduled to every %ds", interval_seconds)
+
+
+def set_service_checks_enabled(enabled: bool) -> None:
+    """Add or remove the service-check job on the running scheduler."""
+    if not scheduler.running:
+        return
+    job = scheduler.get_job("service_checks")
+    if enabled and not job:
+        _add_service_check_job()
+        logger.info("Service checks enabled — every %ds", settings.service_check_interval)
+    elif not enabled and job:
+        scheduler.remove_job("service_checks")
+        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,9 +1,32 @@
+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
+from app.core.config import origin_of, 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:
@@ -21,14 +44,176 @@ 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}
+    # A same-origin deployment behind a reverse proxy needs no CORS, so
+    # CORS_ORIGINS is often left at its localhost default — yet browsers still
+    # send Origin on unsafe methods. The OIDC callback URL is served by this app,
+    # so its origin is the app's own and is always a legitimate CSRF origin.
+    app_origin = origin_of(settings.oidc_redirect_uri)
+    if app_origin:
+        allowed_origins.add(app_origin)
+    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/data/oui_database.json

@@ -0,0 +1,221 @@
+[
+  {
+    "vendor": "Proxmox / QEMU / KVM",
+    "type": "vm",
+    "prefixes": ["52:54:00", "bc:24:11"]
+  },
+  {
+    "vendor": "VMware",
+    "type": "vm",
+    "prefixes": ["00:50:56", "00:0c:29", "00:05:69", "00:1c:14"]
+  },
+  {
+    "vendor": "VirtualBox",
+    "type": "vm",
+    "prefixes": ["08:00:27"]
+  },
+  {
+    "vendor": "Microsoft Hyper-V",
+    "type": "vm",
+    "prefixes": ["00:15:5d"]
+  },
+  {
+    "vendor": "Xen",
+    "type": "vm",
+    "prefixes": ["00:16:3e"]
+  },
+
+  {
+    "vendor": "MikroTik",
+    "type": "router",
+    "prefixes": [
+      "00:0c:42",
+      "08:55:31",
+      "18:fd:74",
+      "2c:c8:1b",
+      "48:8f:5a",
+      "4c:5e:0c",
+      "64:d1:54",
+      "6c:3b:6b",
+      "74:4d:28",
+      "b8:69:f4",
+      "c4:ad:34",
+      "cc:2d:e0",
+      "d4:ca:6d",
+      "dc:2c:6e",
+      "e4:8d:8c"
+    ]
+  },
+  {
+    "vendor": "Ubiquiti",
+    "type": "ap",
+    "prefixes": [
+      "00:15:6d",
+      "00:27:22",
+      "04:18:d6",
+      "24:5a:4c",
+      "24:a4:3c",
+      "44:d9:e7",
+      "68:72:51",
+      "68:d7:9a",
+      "74:83:c2",
+      "78:8a:20",
+      "78:45:58",
+      "80:2a:a8",
+      "94:2a:6f",
+      "9c:05:d6",
+      "b4:fb:e4",
+      "dc:9f:db",
+      "e0:63:da",
+      "f0:9f:c2",
+      "fc:ec:da"
+    ]
+  },
+  {
+    "vendor": "Ruckus Wireless",
+    "type": "ap",
+    "prefixes": ["00:13:92", "4c:b1:cd", "8c:7a:15", "f0:b0:52", "c0:8a:de"]
+  },
+  {
+    "vendor": "Aruba Networks (HPE)",
+    "type": "ap",
+    "prefixes": ["00:0b:86", "6c:f3:7f", "94:b4:0f", "9c:1c:12", "ac:a3:1e"]
+  },
+
+  {
+    "vendor": "Cisco Systems",
+    "type": "switch",
+    "prefixes": [
+      "00:00:0c",
+      "00:1b:0d",
+      "00:1c:f6",
+      "00:1e:13",
+      "00:23:04",
+      "00:24:13",
+      "00:25:45",
+      "00:50:0b",
+      "b0:00:b4",
+      "b8:38:61",
+      "f8:c0:01"
+    ]
+  },
+  {
+    "vendor": "Juniper Networks",
+    "type": "switch",
+    "prefixes": ["00:14:f6", "2c:6b:f5", "b0:c6:9a", "f0:1c:2d"]
+  },
+  {
+    "vendor": "Zyxel",
+    "type": "switch",
+    "prefixes": ["00:13:49", "60:31:97", "ec:43:f6"]
+  },
+
+  {
+    "vendor": "Netgear",
+    "type": "router",
+    "prefixes": ["00:09:5b", "28:c6:8e", "c0:ff:d4", "2c:30:33", "a0:40:a0"]
+  },
+  {
+    "vendor": "TP-Link",
+    "type": "router",
+    "prefixes": ["14:eb:b6", "60:e3:27", "b0:4e:26", "c4:e9:0a", "ec:08:6b"]
+  },
+
+  {
+    "vendor": "Synology",
+    "type": "nas",
+    "prefixes": ["00:11:32", "00:f4:6f", "90:09:d0"]
+  },
+  {
+    "vendor": "QNAP Systems",
+    "type": "nas",
+    "prefixes": ["00:08:9b", "00:0e:23", "00:13:42", "04:f0:21", "24:5e:be"]
+  },
+  {
+    "vendor": "Asustor",
+    "type": "nas",
+    "prefixes": ["e8:9c:25"]
+  },
+
+  {
+    "vendor": "Hikvision",
+    "type": "camera",
+    "prefixes": ["28:57:be", "44:19:b6", "b4:a3:82", "bc:ad:28", "c0:51:7e", "c0:56:e3", "c4:2f:90"]
+  },
+  {
+    "vendor": "Dahua / Amcrest",
+    "type": "camera",
+    "prefixes": ["3c:ef:8c", "4c:11:bf", "90:02:a9", "bc:32:5f", "e0:50:8b"]
+  },
+  {
+    "vendor": "Reolink",
+    "type": "camera",
+    "prefixes": ["ec:71:db"]
+  },
+  {
+    "vendor": "Axis Communications",
+    "type": "camera",
+    "prefixes": ["00:40:8c", "ac:cc:8e"]
+  },
+
+  {
+    "vendor": "Raspberry Pi Foundation",
+    "type": "server",
+    "prefixes": ["28:cd:c1", "2c:cf:67", "b8:27:eb", "d8:3a:dd", "dc:a6:32", "e4:5f:01"]
+  },
+  {
+    "vendor": "Dell",
+    "type": "server",
+    "prefixes": ["00:14:22", "90:b1:1c", "b0:83:fe", "b8:ca:3a", "f8:b1:56"]
+  },
+  {
+    "vendor": "Supermicro",
+    "type": "server",
+    "prefixes": ["00:25:90", "0c:c4:7a", "ac:1f:6b"]
+  },
+
+  {
+    "vendor": "Shelly",
+    "type": "iot",
+    "prefixes": ["30:c6:f7", "34:94:54", "84:f3:eb", "ec:fa:bc"]
+  },
+  {
+    "vendor": "Espressif (ESP8266 / ESP32)",
+    "type": "iot",
+    "prefixes": [
+      "24:62:ab",
+      "30:ae:a4",
+      "3c:71:bf",
+      "8c:aa:b5",
+      "a0:20:a6",
+      "ac:67:b2",
+      "b4:e6:2d",
+      "cc:50:e3"
+    ]
+  },
+  {
+    "vendor": "Sonoff / ITEAD",
+    "type": "iot",
+    "prefixes": ["dc:4f:22", "e8:db:84"]
+  },
+  {
+    "vendor": "TP-Link Tapo / Kasa",
+    "type": "iot",
+    "prefixes": ["10:27:f5", "1c:3b:f3", "50:c7:bf", "b0:a7:b9"]
+  },
+  {
+    "vendor": "Philips Hue",
+    "type": "iot",
+    "prefixes": ["00:17:88", "ec:b5:fa"]
+  },
+  {
+    "vendor": "IKEA Tradfri",
+    "type": "iot",
+    "prefixes": ["00:21:2e", "34:13:e8"]
+  },
+  {
+    "vendor": "Tuya / Smart Life",
+    "type": "iot",
+    "prefixes": ["68:57:2d", "d8:f1:5b"]
+  }
+]

backend/app/data/service_signatures.json

@@ -142,5 +142,74 @@
   {"port": 1194,  "protocol": "udp", "banner_regex": null,                              "service_name": "OpenVPN",                 "icon": "shield",      "category": "vpn",           "suggested_node_type": "router"},
   {"port": 500,   "protocol": "udp", "banner_regex": null,                              "service_name": "IPsec IKE",               "icon": "shield",      "category": "vpn",           "suggested_node_type": "router"},
   {"port": 53,    "protocol": "udp", "banner_regex": null,                              "service_name": "DNS",                     "icon": "search",      "category": "network",       "suggested_node_type": "router"},
-  {"port": 67,    "protocol": "udp", "banner_regex": null,                              "service_name": "DHCP",                    "icon": "wifi",        "category": "network",       "suggested_node_type": "router"}
+  {"port": 67,    "protocol": "udp", "banner_regex": null,                              "service_name": "DHCP",                    "icon": "wifi",        "category": "network",       "suggested_node_type": "router"},
+
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Jellyfin",                 "service_name": "Jellyfin",            "icon": "film",        "category": "media",      "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Plex",                     "service_name": "Plex",                "icon": "play-circle", "category": "media",      "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Emby",                     "service_name": "Emby",                "icon": "film",        "category": "media",      "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Overseerr",                "service_name": "Overseerr",           "icon": "tv",          "category": "media",      "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Jellyseerr",               "service_name": "Jellyseerr",          "icon": "tv",          "category": "media",      "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Tautulli",                 "service_name": "Tautulli",            "icon": "bar-chart",   "category": "media",      "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Navidrome",                "service_name": "Navidrome",           "icon": "music",       "category": "media",      "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "[Aa]udiobookshelf",        "service_name": "Audiobookshelf",      "icon": "book-open",   "category": "media",      "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Immich",                   "service_name": "Immich",              "icon": "camera",      "category": "media",      "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "PhotoPrism",               "service_name": "PhotoPrism",          "icon": "camera",      "category": "media",      "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Calibre[- ]Web",           "service_name": "Calibre-Web",         "icon": "book",        "category": "media",      "suggested_node_type": "server"},
+
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Sonarr",                   "service_name": "Sonarr",              "icon": "tv",          "category": "download",   "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Radarr",                   "service_name": "Radarr",              "icon": "film",        "category": "download",   "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Lidarr",                   "service_name": "Lidarr",              "icon": "music",       "category": "download",   "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Readarr",                  "service_name": "Readarr",             "icon": "book",        "category": "download",   "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Prowlarr",                 "service_name": "Prowlarr",            "icon": "search",      "category": "download",   "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Bazarr",                   "service_name": "Bazarr",              "icon": "subtitles",   "category": "download",   "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "qBittorrent",              "service_name": "qBittorrent",         "icon": "download",    "category": "download",   "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "SABnzbd",                  "service_name": "SABnzbd",             "icon": "download",    "category": "download",   "suggested_node_type": "server"},
+
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Homarr",                   "service_name": "Homarr",              "icon": "home",        "category": "web",        "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Heimdall",                 "service_name": "Heimdall",            "icon": "home",        "category": "web",        "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Dashy",                    "service_name": "Dashy",               "icon": "home",        "category": "web",        "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Organizr",                 "service_name": "Organizr",            "icon": "home",        "category": "web",        "suggested_node_type": "server"},
+
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Portainer",                "service_name": "Portainer",           "icon": "box",         "category": "containers", "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Dockge",                   "service_name": "Dockge",              "icon": "box",         "category": "containers", "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Yacht",                    "service_name": "Yacht",               "icon": "box",         "category": "containers", "suggested_node_type": "server"},
+
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Home Assistant",           "service_name": "Home Assistant",      "icon": "home",        "category": "automation", "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Node-RED",                 "service_name": "Node-RED",            "icon": "share-2",     "category": "automation", "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Zigbee2MQTT",              "service_name": "Zigbee2MQTT",         "icon": "radio",       "category": "automation", "suggested_node_type": "iot"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "ESPHome",                  "service_name": "ESPHome",             "icon": "cpu",         "category": "automation", "suggested_node_type": "iot"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "openHAB",                  "service_name": "openHAB",             "icon": "home",        "category": "automation", "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Domoticz",                 "service_name": "Domoticz",            "icon": "home",        "category": "automation", "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Homebridge",               "service_name": "Homebridge",          "icon": "home",        "category": "automation", "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Jeedom",                   "service_name": "Jeedom",              "icon": "home",        "category": "automation", "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Scrypted",                 "service_name": "Scrypted",            "icon": "video",       "category": "automation", "suggested_node_type": "server"},
+
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Grafana",                  "service_name": "Grafana",             "icon": "bar-chart-2", "category": "monitoring", "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Uptime Kuma",              "service_name": "Uptime Kuma",         "icon": "activity",    "category": "monitoring", "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Netdata",                  "service_name": "Netdata",             "icon": "activity",    "category": "monitoring", "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Glances",                  "service_name": "Glances",             "icon": "activity",    "category": "monitoring", "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Dozzle",                   "service_name": "Dozzle",              "icon": "terminal",    "category": "monitoring", "suggested_node_type": "server"},
+
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "AdGuard Home",             "service_name": "AdGuard Home",        "icon": "shield",      "category": "network",    "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Pi-hole",                  "service_name": "Pi-hole",             "icon": "shield",      "category": "network",    "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Nginx Proxy Manager",      "service_name": "Nginx Proxy Manager", "icon": "share-2",     "category": "network",    "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Traefik",                  "service_name": "Traefik",             "icon": "share-2",     "category": "network",    "suggested_node_type": "server"},
+
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Vaultwarden|Bitwarden",    "service_name": "Vaultwarden",         "icon": "lock",        "category": "auth",       "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Authelia",                 "service_name": "Authelia",            "icon": "lock",        "category": "auth",       "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "[Aa]uthentik",             "service_name": "Authentik",           "icon": "lock",        "category": "auth",       "suggested_node_type": "server"},
+
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Nextcloud",                "service_name": "Nextcloud",           "icon": "hard-drive",  "category": "storage",    "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Paperless",                "service_name": "Paperless-ngx",       "icon": "book",        "category": "storage",    "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Syncthing",                "service_name": "Syncthing",           "icon": "refresh-cw",  "category": "storage",    "suggested_node_type": "server"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Gitea",                    "service_name": "Gitea",               "icon": "git-branch",  "category": "dev",        "suggested_node_type": "server"},
+
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "[Pp]i[Kk]VM",              "service_name": "PiKVM",               "icon": "monitorcog",  "category": "kvm",        "suggested_node_type": "kvm"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "TinyPilot",                "service_name": "TinyPilot",           "icon": "monitorcog",  "category": "kvm",        "suggested_node_type": "kvm"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "JetKVM",                   "service_name": "JetKVM",              "icon": "monitorcog",  "category": "kvm",        "suggested_node_type": "kvm"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "NanoKVM",                  "service_name": "NanoKVM",             "icon": "monitorcog",  "category": "kvm",        "suggested_node_type": "kvm"},
+
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "openmediavault",           "service_name": "OpenMediaVault",      "icon": "hard-drive",  "category": "nas",        "suggested_node_type": "nas"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Unraid",                   "service_name": "Unraid",              "icon": "hard-drive",  "category": "nas",        "suggested_node_type": "nas"},
+  {"port": null, "protocol": "tcp", "banner_regex": null, "http_regex": "Cockpit",                  "service_name": "Cockpit",             "icon": "monitor",     "category": "nas",        "suggested_node_type": "server"}
 ]

backend/app/db/database.py

@@ -1,10 +1,14 @@
+import json as _json
 import logging
 import shutil
+import sqlite3
+import uuid as _uuid_mod
 from collections.abc import AsyncGenerator
-from contextlib import suppress
+from contextlib import closing, suppress
 from pathlib import Path
+from typing import Any
 
-from sqlalchemy.exc import OperationalError
+from sqlalchemy.exc import IntegrityError, OperationalError
 from sqlalchemy.ext.asyncio import AsyncConnection, AsyncSession, async_sessionmaker, create_async_engine
 from sqlalchemy.orm import DeclarativeBase
 
@@ -13,6 +17,59 @@ from app.core.config import APP_VERSION, settings
 logger = logging.getLogger(__name__)
 
 
+# DDL for the documents feature that `Base.metadata.create_all` does not apply:
+# the column additions it never makes to an existing table, plus a virtual table
+# and partial indexes it cannot express at all. Shared with the test fixtures so
+# the suite runs against the same schema production boots with.
+DOCUMENT_DDL: tuple[tuple[str, str], ...] = (
+    # `create_all` creates a missing table; it never adds a column to one that
+    # already exists. A database that met an earlier shape of `documents` — an
+    # intermediate build, a branch checked out and run before a column landed —
+    # keeps that shape forever, and every query naming the new column fails with
+    # `no such column`. So every nullable / defaulted column is (re)stated here
+    # as an idempotent ALTER, the way the `device_inventory` migrations are.
+    ("documents.icon", "ALTER TABLE documents ADD COLUMN icon TEXT"),
+    ("documents.parent_id", "ALTER TABLE documents ADD COLUMN parent_id TEXT"),
+    ("documents.sort_order", "ALTER TABLE documents ADD COLUMN sort_order INTEGER DEFAULT 0"),
+    ("documents.device_id", "ALTER TABLE documents ADD COLUMN device_id TEXT"),
+    ("documents.node_id", "ALTER TABLE documents ADD COLUMN node_id TEXT"),
+    ("documents.design_id", "ALTER TABLE documents ADD COLUMN design_id TEXT"),
+    ("documents.frontmatter", "ALTER TABLE documents ADD COLUMN frontmatter JSON"),
+    ("documents.tags", "ALTER TABLE documents ADD COLUMN tags JSON"),
+    ("documents.starred", "ALTER TABLE documents ADD COLUMN starred BOOLEAN DEFAULT 0"),
+    ("documents.template_id", "ALTER TABLE documents ADD COLUMN template_id TEXT"),
+    ("documents.facts_snapshot", "ALTER TABLE documents ADD COLUMN facts_snapshot JSON"),
+    ("documents.facts_synced_at", "ALTER TABLE documents ADD COLUMN facts_synced_at DATETIME"),
+    ("documents.reviewed_at", "ALTER TABLE documents ADD COLUMN reviewed_at DATETIME"),
+    # Set only when a body is edited, so "never touched since it was generated"
+    # is distinguishable from "edited" — `created_at` and `updated_at` are two
+    # separate clock reads on insert and are never equal.
+    ("documents.edited_at", "ALTER TABLE documents ADD COLUMN edited_at DATETIME"),
+    ("document_revisions.reason", "ALTER TABLE document_revisions ADD COLUMN reason TEXT"),
+    (
+        "documents_fts.table",
+        "CREATE VIRTUAL TABLE IF NOT EXISTS documents_fts USING fts5("
+        "doc_id UNINDEXED, title, tags, body, "
+        "tokenize = 'unicode61 remove_diacritics 2')",
+    ),
+    (
+        "documents.device_id.unique",
+        "CREATE UNIQUE INDEX IF NOT EXISTS ux_documents_device "
+        "ON documents(device_id) WHERE device_id IS NOT NULL",
+    ),
+    (
+        "documents.node_id.unique",
+        "CREATE UNIQUE INDEX IF NOT EXISTS ux_documents_node "
+        "ON documents(node_id) WHERE node_id IS NOT NULL",
+    ),
+    (
+        "documents.design_id.unique",
+        "CREATE UNIQUE INDEX IF NOT EXISTS ux_documents_design "
+        "ON documents(design_id) WHERE design_id IS NOT NULL",
+    ),
+)
+
+
 async def _try_migrate(conn: AsyncConnection, sql: str, *, label: str) -> None:
     """Run an idempotent migration statement, logging any error.
 
@@ -58,9 +115,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):
@@ -79,6 +194,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):
@@ -89,6 +212,8 @@ async def init_db() -> None:
             await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN disk_gb REAL")
         with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN show_hardware BOOLEAN NOT NULL DEFAULT 0")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN show_port_numbers BOOLEAN NOT NULL DEFAULT 0")
         with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN width REAL")
         with suppress(OperationalError):
@@ -96,7 +221,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) ---
@@ -106,32 +241,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,"
@@ -144,44 +279,166 @@ 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)
+        await _try_migrate(
+            conn,
+            "CREATE TABLE IF NOT EXISTS designs ("
+            "id VARCHAR PRIMARY KEY,"
+            "name VARCHAR NOT NULL,"
+            "design_type VARCHAR NOT NULL DEFAULT 'network',"
+            "created_at DATETIME,"
+            "updated_at DATETIME"
+            ")",
+            label="designs.table",
+        )
+        # Add user-chosen icon to designs (idempotent), then backfill existing rows
+        # so legacy designs keep a sensible icon based on their original type.
+        await _try_migrate(
+            conn, "ALTER TABLE designs ADD COLUMN icon VARCHAR", label="designs.icon",
+        )
+        with suppress(OperationalError):
+            await conn.exec_driver_sql(
+                "UPDATE designs SET icon = 'zap' WHERE icon IS NULL AND design_type = 'electrical'"
+            )
+        with suppress(OperationalError):
+            await conn.exec_driver_sql(
+                "UPDATE designs SET icon = 'dashboard' WHERE icon IS NULL"
+            )
+        # Seed default Network Topology design if designs table is empty
+        _default_design_id = str(_uuid_mod.uuid4())
+        row = await conn.exec_driver_sql("SELECT COUNT(*) FROM designs")
+        count_row = row.fetchone()
+        count = count_row[0] if count_row else 0
+        if count == 0:
+            await conn.exec_driver_sql(
+                "INSERT INTO designs (id, name, design_type, icon, created_at, updated_at) "
+                "VALUES (?, 'Network Topology', 'network', 'dashboard', datetime('now'), datetime('now'))",
+                (_default_design_id,),
+            )
+        else:
+            row2 = await conn.exec_driver_sql("SELECT id FROM designs WHERE design_type = 'network' LIMIT 1")
+            default = row2.fetchone()
+            _default_design_id = default[0] if default else _default_design_id
+
+        # Add design_id to nodes
+        await _try_migrate(
+            conn, "ALTER TABLE nodes ADD COLUMN design_id VARCHAR REFERENCES designs(id)",
+            label="nodes.design_id",
+        )
+        # Assign existing nodes to default design
+        await conn.exec_driver_sql(
+            "UPDATE nodes SET design_id = ? WHERE design_id IS NULL", (_default_design_id,),
+        )
+
+        # Add design_id to edges
+        await _try_migrate(
+            conn, "ALTER TABLE edges ADD COLUMN design_id VARCHAR REFERENCES designs(id)",
+            label="edges.design_id",
+        )
+        # Assign existing edges to default design
+        await conn.exec_driver_sql(
+            "UPDATE edges SET design_id = ? WHERE design_id IS NULL", (_default_design_id,),
+        )
+
+        # Migrate canvas_state from id=1 to design_id PK (SQLite rebuild)
+        try:
+            info = await conn.exec_driver_sql("PRAGMA table_info(canvas_state)")
+            cols = info.fetchall()
+            has_design_id = any(c[1] == "design_id" for c in cols)
+            if not has_design_id:
+                logger.info("Migrating canvas_state: switching to design_id primary key")
+                await conn.exec_driver_sql("PRAGMA foreign_keys = OFF")
+                await conn.exec_driver_sql(
+                    "CREATE TABLE canvas_state_new ("
+                    "design_id VARCHAR PRIMARY KEY REFERENCES designs(id) ON DELETE CASCADE,"
+                    "viewport JSON,"
+                    "custom_style JSON,"
+                    "saved_at DATETIME"
+                    ")"
+                )
+                # Copy existing row(s), mapping id=1 to default design_id
+                old_rows = await conn.exec_driver_sql("SELECT id, viewport, custom_style, saved_at FROM canvas_state")
+                for old in old_rows.fetchall():
+                    cs_id, viewport, custom_style, saved_at = old
+                    target_design = _default_design_id
+                    await conn.exec_driver_sql(
+                        "INSERT INTO canvas_state_new (design_id, viewport, custom_style, saved_at) "
+                        "VALUES (?, ?, ?, ?)",
+                        (target_design, viewport, custom_style, saved_at),
+                    )
+                await conn.exec_driver_sql("DROP TABLE canvas_state")
+                await conn.exec_driver_sql("ALTER TABLE canvas_state_new RENAME TO canvas_state")
+                await conn.exec_driver_sql("PRAGMA foreign_keys = ON")
+        except OperationalError as exc:
+            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"
+            )
+
+        # A mount can override when its plate draws its sockets. Existing rows
+        # keep the old behaviour, which is exactly what "auto" means.
+        await _try_migrate(
+            conn,
+            "ALTER TABLE rack_devices ADD COLUMN port_visibility TEXT NOT NULL DEFAULT 'auto'",
+            label="rack_devices.port_visibility",
+        )
+        with suppress(OperationalError):
+            await conn.exec_driver_sql(
+                "UPDATE rack_devices SET port_visibility = 'auto' WHERE port_visibility IS NULL"
+            )
+
         with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE edges ADD COLUMN waypoints JSON")
         with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN properties JSON")
-        with suppress(OperationalError):
-            await conn.exec_driver_sql("ALTER TABLE canvas_state ADD COLUMN custom_style JSON")
         # Migrate hardware columns → properties JSON (idempotent: only runs on nodes where properties IS NULL)
         with suppress(OperationalError):
             rows = await conn.exec_driver_sql(
                 "SELECT id, cpu_model, cpu_count, ram_gb, disk_gb, show_hardware "
                 "FROM nodes WHERE properties IS NULL"
             )
-            for row in rows.fetchall():
-                node_id, cpu_model, cpu_count, ram_gb, disk_gb, show_hardware = row
+            for r in rows.fetchall():
+                node_id, cpu_model, cpu_count, ram_gb, disk_gb, show_hardware = r
                 props = []
                 visible = bool(show_hardware)
                 if cpu_model:
@@ -192,17 +449,549 @@ async def init_db() -> None:
                     props.append({"key": "RAM", "value": f"{ram_gb} GB", "icon": "MemoryStick", "visible": visible})
                 if disk_gb is not None:
                     props.append({"key": "Disk", "value": f"{disk_gb} GB", "icon": "HardDrive", "visible": visible})
-                import json as _json
                 await conn.exec_driver_sql(
                     "UPDATE nodes SET properties = ? WHERE id = ?",
                     (_json.dumps(props), node_id),
                 )
+        # Inventory timestamp: last time a scan observed this node (idempotent)
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN last_scan DATETIME")
         # Migrate animated column from boolean (0/1) to string ('none'/'snake')
         with suppress(OperationalError):
             await conn.exec_driver_sql("UPDATE edges SET animated = 'snake' WHERE animated = '1' OR animated = 1")
         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"
+            )
+        # 3.3.0 — the inventory row owns the device facts, the canvas node only
+        # owns how it is drawn. These columns receive what used to live solely on
+        # `nodes`. Additive here; `nodes` keeps its copies until the backfill has
+        # run and been verified.
+        inventory_device_migrations: list[tuple[str, str]] = [
+            ("device_inventory.label", "ALTER TABLE device_inventory ADD COLUMN label TEXT"),
+            ("device_inventory.type", "ALTER TABLE device_inventory ADD COLUMN type TEXT"),
+            ("device_inventory.notes", "ALTER TABLE device_inventory ADD COLUMN notes TEXT"),
+            ("device_inventory.cpu_count", "ALTER TABLE device_inventory ADD COLUMN cpu_count INTEGER"),
+            ("device_inventory.cpu_model", "ALTER TABLE device_inventory ADD COLUMN cpu_model TEXT"),
+            ("device_inventory.ram_gb", "ALTER TABLE device_inventory ADD COLUMN ram_gb FLOAT"),
+            ("device_inventory.disk_gb", "ALTER TABLE device_inventory ADD COLUMN disk_gb FLOAT"),
+            (
+                "device_inventory.show_hardware",
+                "ALTER TABLE device_inventory ADD COLUMN show_hardware BOOLEAN DEFAULT 0",
+            ),
+            ("device_inventory.check_method", "ALTER TABLE device_inventory ADD COLUMN check_method TEXT"),
+            ("device_inventory.check_target", "ALTER TABLE device_inventory ADD COLUMN check_target TEXT"),
+            (
+                "device_inventory.status_live",
+                "ALTER TABLE device_inventory ADD COLUMN status_live TEXT DEFAULT 'unknown'",
+            ),
+            ("device_inventory.last_seen", "ALTER TABLE device_inventory ADD COLUMN last_seen DATETIME"),
+            ("device_inventory.last_scan", "ALTER TABLE device_inventory ADD COLUMN last_scan DATETIME"),
+            (
+                "device_inventory.response_time_ms",
+                "ALTER TABLE device_inventory ADD COLUMN response_time_ms INTEGER",
+            ),
+            ("device_inventory.updated_at", "ALTER TABLE device_inventory ADD COLUMN updated_at DATETIME"),
+        ]
+        for label, sql in inventory_device_migrations:
+            await _try_migrate(conn, sql, label=label)
+        # Backfill the columns that carry a non-NULL default in the model, so a
+        # legacy row round-trips through Pydantic without tripping the validators.
+        # The link itself: a node points at the inventory row it draws.
+        for label, sql in (
+            ("nodes.device_id", "ALTER TABLE nodes ADD COLUMN device_id TEXT"),
+            (
+                "nodes.device_id.index",
+                "CREATE INDEX IF NOT EXISTS ix_nodes_device_id ON nodes(device_id)",
+            ),
+            # Which of the row's services and properties this canvas shows, and
+            # in what order. Seeded from the row further down, once the backfill
+            # has had its say — see `_seed_node_views`.
+            ("nodes.display_view", "ALTER TABLE nodes ADD COLUMN display_view JSON"),
+            # A zone or a group describes no device, so it has no inventory row to
+            # keep its text on. Furniture keeps it here instead — see `Node.description`.
+            ("nodes.description", "ALTER TABLE nodes ADD COLUMN description TEXT"),
+        ):
+            await _try_migrate(conn, sql, label=label)
+        # 3.3.x — the inventory row owns the device's rack modelisation: the
+        # faceplate it wears, its size and its ports (labels, types, positions).
+        # A mount reads them at load and writes them back on save, so a device
+        # keeps the same front panel in every rack it is mounted in.
+        for label, sql in (
+            (
+                "device_inventory.rack_faceplate_id",
+                "ALTER TABLE device_inventory ADD COLUMN rack_faceplate_id TEXT",
+            ),
+            (
+                "device_inventory.rack_u_height",
+                "ALTER TABLE device_inventory ADD COLUMN rack_u_height INTEGER",
+            ),
+            (
+                "device_inventory.rack_col_span",
+                "ALTER TABLE device_inventory ADD COLUMN rack_col_span INTEGER",
+            ),
+            ("device_inventory.rack_color", "ALTER TABLE device_inventory ADD COLUMN rack_color TEXT"),
+            ("device_inventory.rack_ports", "ALTER TABLE device_inventory ADD COLUMN rack_ports JSON"),
+        ):
+            await _try_migrate(conn, sql, label=label)
+        for label, sql in (
+            (
+                "device_inventory.status_live.backfill",
+                "UPDATE device_inventory SET status_live = 'unknown' WHERE status_live IS NULL",
+            ),
+            (
+                "device_inventory.show_hardware.backfill",
+                "UPDATE device_inventory SET show_hardware = 0 WHERE show_hardware IS NULL",
+            ),
+            (
+                "device_inventory.updated_at.backfill",
+                "UPDATE device_inventory SET updated_at = discovered_at WHERE updated_at IS NULL",
+            ),
+        ):
+            await _try_migrate(conn, sql, label=label)
+
+        # Documents. create_all makes the two tables on a fresh database; this
+        # brings an existing one up to the current shape — the columns create_all
+        # would never add, the FTS5 index and the partial uniques that keep one
+        # document per device / node / design.
+        for label, sql in DOCUMENT_DDL:
+            await _try_migrate(conn, sql, label=label)
+
+    await _backfill_node_devices()
+    await _drop_legacy_node_columns()
+    await _seed_node_views()
+    await _backfill_zone_size()
+    await _repair_self_parent_nodes()
+    await _reindex_documents_fts()
+
+
+
+# Columns `nodes` carried before 3.3.0, when a node owned the device facts. They
+# belong to `device_inventory` now; the backfill above copies them across, and
+# this rebuild removes them.
+_LEGACY_NODE_COLUMNS = (
+    "hostname", "ip", "mac", "os", "status", "check_method", "check_target",
+    "services", "notes", "cpu_count", "cpu_model", "ram_gb", "disk_gb",
+    "show_hardware", "properties", "ieee_address", "last_seen", "last_scan",
+    "response_time_ms",
+)
+
+# What a node keeps: how the device is drawn on one canvas.
+_NODE_COLUMNS_SQL = (
+    "id VARCHAR PRIMARY KEY,"
+    "type VARCHAR NOT NULL,"
+    "label VARCHAR NOT NULL,"
+    "design_id VARCHAR REFERENCES designs(id) ON DELETE SET NULL,"
+    "device_id VARCHAR REFERENCES device_inventory(id) ON DELETE SET NULL,"
+    "display_view JSON,"
+    "pos_x FLOAT,"
+    "pos_y FLOAT,"
+    "parent_id VARCHAR REFERENCES nodes(id) ON DELETE CASCADE,"
+    "container_mode BOOLEAN,"
+    "custom_colors JSON,"
+    "custom_icon VARCHAR,"
+    "description TEXT,"
+    "show_port_numbers BOOLEAN,"
+    "width FLOAT,"
+    "height FLOAT,"
+    "bottom_handles INTEGER,"
+    "top_handles INTEGER,"
+    "left_handles INTEGER,"
+    "right_handles INTEGER,"
+    "created_at DATETIME,"
+    "updated_at DATETIME"
+)
+
+_NODE_KEPT = (
+    "id, type, label, design_id, device_id, display_view, pos_x, pos_y, parent_id, container_mode, "
+    "custom_colors, custom_icon, description, show_port_numbers, width, height, bottom_handles, "
+    "top_handles, left_handles, right_handles, created_at, updated_at"
+)
+
+
+async def _relax_legacy_node_columns(conn: AsyncConnection, info: list[Any]) -> None:
+    """Make the retained legacy `nodes` columns nullable — SQLite table rebuild.
+
+    The 3.2.0 schema declares `status`, `services`, `properties` and
+    `show_hardware` NOT NULL with no server-side default. The 3.3.0 model no
+    longer maps them, so every INSERT omits them and SQLite rejects the row —
+    approving a device, creating a node, importing a canvas all fail with
+    ``NOT NULL constraint failed: nodes.status``. Dropping the columns is the
+    real fix, but it waits on a complete backfill; until then they have to stop
+    blocking writes. Values are preserved: only the constraint goes.
+    """
+    kept = [row for row in info if row[1] in _LEGACY_NODE_COLUMNS]
+    if not any(row[3] for row in kept):  # PRAGMA `notnull`
+        return  # Already relaxed, or never constrained.
+
+    logger.info("Relaxing NOT NULL on the retained legacy node columns")
+    legacy_defs = ",".join(f"{row[1]} {row[2] or 'VARCHAR'}" for row in kept)
+    legacy_names = ", ".join(row[1] for row in kept)
+    await _rebuild_nodes(
+        conn,
+        columns_sql=f"{_NODE_COLUMNS_SQL},{legacy_defs}",
+        copied=f"{_NODE_KEPT}, {legacy_names}",
+        what="nodes legacy-column relax",
+    )
+
+
+async def _rebuild_nodes(conn: AsyncConnection, *, columns_sql: str, copied: str, what: str) -> None:
+    """Recreate `nodes` with a new column list — SQLite cannot alter constraints.
+
+    Never fatal: a rebuild that fails leaves the table it could not replace, and
+    the boot carries on. Foreign keys go off for the swap, because `edges` and
+    `rack_devices` point at `nodes`, and back on in every case — the pragma is
+    per connection and this one returns to the pool.
+    """
+    try:
+        await conn.exec_driver_sql("PRAGMA foreign_keys = OFF")
+        # A previous attempt that failed after the create would block this one.
+        await conn.exec_driver_sql("DROP TABLE IF EXISTS nodes_new")
+        await conn.exec_driver_sql(f"CREATE TABLE nodes_new ({columns_sql})")
+        await conn.exec_driver_sql(f"INSERT INTO nodes_new ({copied}) SELECT {copied} FROM nodes")
+        await conn.exec_driver_sql("DROP TABLE nodes")
+        await conn.exec_driver_sql("ALTER TABLE nodes_new RENAME TO nodes")
+        await conn.exec_driver_sql("CREATE INDEX IF NOT EXISTS ix_nodes_device_id ON nodes(device_id)")
+    except (OperationalError, IntegrityError) as exc:
+        logger.warning("%s failed: %s", what, exc)
+    finally:
+        await conn.exec_driver_sql("PRAGMA foreign_keys = ON")
+
+
+async def _drop_legacy_node_columns() -> None:
+    """Remove the device columns from `nodes` (3.3.0) — SQLite table rebuild.
+
+    Runs only after the backfill has linked every device node to its inventory
+    row. If any non-furniture node is still unlinked the drop is skipped and
+    logged: the columns are the only remaining copy of that node's facts, and
+    losing them is not recoverable. The skip then relaxes their NOT NULL instead,
+    because the 3.3.0 model no longer writes them and the database must stay
+    insertable while the backfill is retried on later boots.
+    """
+    async with engine.begin() as conn:
+        info = (await conn.exec_driver_sql("PRAGMA table_info(nodes)")).fetchall()
+        present = {row[1] for row in info}
+        if not (present & set(_LEGACY_NODE_COLUMNS)):
+            return  # Already migrated.
+
+        unlinked = (
+            await conn.exec_driver_sql(
+                "SELECT COUNT(*) FROM nodes WHERE device_id IS NULL "
+                "AND type NOT IN ('group', 'groupRect', 'text')"
+            )
+        ).scalar()
+        if unlinked:
+            logger.warning(
+                "Keeping the legacy node columns: %d node(s) have no inventory row. "
+                "The backfill must link every device node before they can be dropped.",
+                unlinked,
+            )
+            await _relax_legacy_node_columns(conn, list(info))
+            return
+
+        logger.info("Migrating nodes: the device columns move to device_inventory")
+        await _rebuild_nodes(
+            conn,
+            columns_sql=_NODE_COLUMNS_SQL,
+            copied=_NODE_KEPT,
+            what="nodes device-column drop",
+        )
+
+
+async def _backfill_node_devices() -> None:
+    """Link existing canvas nodes to their Device Inventory rows (3.3.0).
+
+    Runs outside the DDL connection because the merge is Python-side, not SQL.
+    Self-limiting: it only looks at nodes with no ``device_id``, so a second boot
+    finds nothing to do. Never fatal — a failure here leaves the canvas working
+    off its own columns, which still carry the data at this point.
+    """
+    # Imported here: app.services imports app.db.models, which imports this module.
+    from app.services.inventory_sync import backfill_node_devices
+
+    try:
+        async with AsyncSessionLocal() as session:
+            stats = await backfill_node_devices(session)
+            if stats["linked"]:
+                await session.commit()
+                logger.info(
+                    "Inventory backfill: linked %d node(s) — %d device(s) created, %d merged",
+                    stats["linked"], stats["created"], stats["merged"],
+                )
+            if stats.get("skipped"):
+                logger.warning(
+                    "Inventory backfill: %d node(s) could not be linked; they keep their "
+                    "legacy columns and are retried on the next start.",
+                    stats["skipped"],
+                )
+    except Exception as exc:  # pragma: no cover - defensive, boot must not die
+        logger.warning("Inventory backfill failed: %s", exc)
+
+
+def _pre_split_backup() -> Path | None:
+    """The newest backup still holding the per-node device columns, if any.
+
+    `_backup_db` copies the database *before* the migrations of each new
+    version, so a user who upgraded to 3.3.0 has a `homelab.db.back-3.3.0`
+    carrying the last state in which `nodes` still owned its own services and
+    properties. That copy is the only record of which canvas showed what, since
+    3.3.0's backfill unioned them all onto one inventory row. Newest first: it is
+    the state closest to the upgrade, so it is what the user last saw.
+    """
+    db_path = Path(settings.sqlite_path)
+    candidates = sorted(
+        db_path.parent.glob(f"{db_path.name}.back-*"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    for path in candidates:
+        try:
+            with closing(sqlite3.connect(f"file:{path}?mode=ro", uri=True)) as conn:
+                cols = {row[1] for row in conn.execute("PRAGMA table_info(nodes)")}
+        except sqlite3.Error:
+            continue
+        if {"services", "properties"} <= cols:
+            return path
+    return None
+
+
+def _views_from_backup() -> dict[str, dict[str, Any]]:
+    """What each node drew, read out of the pre-3.3.0 backup. Empty when there is none.
+
+    Keyed by node id, which is a uuid and stable across every version. A backup
+    that cannot be opened, or holds nodes this database no longer has, simply
+    contributes nothing — the caller falls back to the inventory row.
+    """
+    path = _pre_split_backup()
+    if path is None:
+        return {}
+    try:
+        with closing(sqlite3.connect(f"file:{path}?mode=ro", uri=True)) as conn:
+            rows = conn.execute("SELECT id, services, properties FROM nodes").fetchall()
+    except sqlite3.Error as exc:
+        logger.warning("Could not read the pre-3.3.0 node lists from %s: %s", path.name, exc)
+        return {}
+
+    out: dict[str, dict[str, Any]] = {}
+    for node_id, services, properties in rows:
+        drawn: dict[str, Any] = {}
+        for kind, raw in (("services", services), ("properties", properties)):
+            if isinstance(raw, str | bytes):
+                with suppress(ValueError):
+                    decoded = _json.loads(raw)
+                    if isinstance(decoded, list):
+                        drawn[kind] = decoded
+        if drawn:
+            out[node_id] = drawn
+    if out:
+        logger.info("Recovering the per-canvas service/property layout from %s", path.name)
+    return out
+
+
+async def _seed_node_views() -> None:
+    """Give pre-existing nodes an explicit view of their inventory row (3.3.3).
+
+    Order and visibility for services and properties moved to the node, so one
+    device drawn on two canvases can be rendered two ways. A node from before
+    that has no view, and where it comes from decides whether the user gets
+    their arrangement back:
+
+    * upgrading from 3.2.0, the backfill has already seeded it from the node's
+      own columns — nothing here to do;
+    * upgrading from 3.3.0-3.3.2, those columns are gone and the row holds the
+      union of every canvas, so the view is recovered from the backup taken
+      before the 3.3.0 migration. That is the difference between a canvas coming
+      back as the user left it and coming back showing every other canvas'
+      properties;
+    * with no usable backup, the row itself is the seed: what shows today keeps
+      showing, and only what the row gains *later* is held back.
+
+    Never fatal: without a view the node simply shows the whole row, which is
+    the behaviour it has now.
+    """
+    # Imported here: app.services imports app.db.models, which imports this module.
+    from app.services.inventory_sync import seed_node_views
+
+    try:
+        async with AsyncSessionLocal() as session:
+            seeded = await seed_node_views(session, drawn=_views_from_backup)
+            if seeded:
+                await session.commit()
+                logger.info("Seeded the service/property view of %d node(s)", seeded)
+    except Exception as exc:  # pragma: no cover - defensive, boot must not die
+        logger.warning("Seeding the node service/property views failed: %s", exc)
+
+
+async def _backfill_zone_size() -> None:
+    """Move a zone's size out of the custom_colors blob into the real columns.
+
+    Every node type stored its size in `nodes.width` / `nodes.height` except
+    `groupRect`, which stashed it inside the `custom_colors` JSON alongside its
+    colours. The serializer writes the columns for zones too now, so a canvas
+    saved before this upgrade would come back at the default 360x240 without
+    this backfill.
+
+    Only fills a column that is still NULL, so it cannot overwrite a size the
+    user has set since, and re-running it is a no-op. Parsed in Python rather
+    than with `json_extract`, so it does not depend on the SQLite build being
+    compiled with JSON1.
+
+    Never fatal: the reader falls back to the blob, so the worst case of a
+    failure here is that the geometry keeps coming from where it always did.
+    """
+    try:
+        async with engine.begin() as conn:
+            rows = (
+                await conn.exec_driver_sql(
+                    "SELECT id, custom_colors FROM nodes "
+                    "WHERE type = 'groupRect' AND custom_colors IS NOT NULL "
+                    "AND (width IS NULL OR height IS NULL)"
+                )
+            ).fetchall()
+
+            moved = 0
+            for node_id, blob in rows:
+                if isinstance(blob, str):
+                    try:
+                        blob = _json.loads(blob)
+                    except ValueError:
+                        continue
+                if not isinstance(blob, dict):
+                    continue
+
+                width, height = blob.get("width"), blob.get("height")
+                # A bool is an int in Python; a size that is not a real number
+                # is left alone rather than written as garbage.
+                if not isinstance(width, int | float) or isinstance(width, bool):
+                    width = None
+                if not isinstance(height, int | float) or isinstance(height, bool):
+                    height = None
+                if width is None and height is None:
+                    continue
+
+                await conn.exec_driver_sql(
+                    "UPDATE nodes SET width = COALESCE(width, ?), height = COALESCE(height, ?) "
+                    "WHERE id = ?",
+                    (width, height, node_id),
+                )
+                moved += 1
+
+            if moved:
+                logger.info("Moved the size of %d zone(s) to the width/height columns", moved)
+    except Exception as exc:  # pragma: no cover - defensive, boot must not die
+        logger.warning("Backfilling zone width/height failed: %s", exc)
+
+
+async def _repair_self_parent_nodes() -> None:
+    """Detach any node that is recorded as its own parent.
+
+    Several write paths could persist ``parent_id = id`` before the guards
+    added alongside this repair: a YAML import resolving a parent by a label
+    that mapped back to the node, the node dedupe re-pointing a canonical node
+    that had been nested under one of its own duplicates, and any client PATCH
+    or canvas save, neither of which validated it (#370).
+
+    The row is fatal on the canvas: the parent walks assume an acyclic tree, so
+    dragging the node overflowed the stack inside the change reducer and the
+    move was silently dropped — the node selected but would not move. It also
+    renders unparented, so it sits wherever its stored coordinates put it
+    rather than inside the container it appears to belong to.
+
+    Clearing the column is the only safe repair: the real parent is not
+    recoverable from the row, and NULL simply returns the node to the top level
+    where the user can re-nest it. Idempotent — a second run matches nothing.
+
+    Never fatal: a failure here leaves the row as it was, and the runtime cycle
+    guards keep the canvas usable either way.
+    """
+    try:
+        async with engine.begin() as conn:
+            rows = (
+                await conn.exec_driver_sql(
+                    "SELECT id, label FROM nodes WHERE parent_id IS NOT NULL AND parent_id = id"
+                )
+            ).fetchall()
+            if not rows:
+                return
+            await conn.exec_driver_sql(
+                "UPDATE nodes SET parent_id = NULL WHERE parent_id IS NOT NULL AND parent_id = id"
+            )
+            for node_id, label in rows:
+                logger.info("Detached self-parented node %s (%s)", node_id, label)
+            logger.info("Repaired %d node(s) recorded as their own parent", len(rows))
+    except Exception as exc:  # pragma: no cover - defensive, boot must not die
+        logger.warning("Repairing self-parented nodes failed: %s", exc)
+
+
+async def _reindex_documents_fts() -> None:
+    """Rebuild the document search index from the documents table.
+
+    The index is maintained on every write, so this only has to catch up the
+    rows a write path could not have seen: the first boot after the feature
+    lands, a restored backup, or a hand-edited database. Cheap enough to run on
+    every boot — it does nothing once the counts already match.
+
+    Never fatal: SQLite may be built without FTS5, in which case the search
+    endpoint falls back to LIKE and this is a no-op.
+    """
+    try:
+        async with engine.begin() as conn:
+            indexed = (await conn.exec_driver_sql("SELECT COUNT(*) FROM documents_fts")).scalar_one()
+            total = (await conn.exec_driver_sql("SELECT COUNT(*) FROM documents")).scalar_one()
+            if indexed == total:
+                return
+            await conn.exec_driver_sql("DELETE FROM documents_fts")
+            rows = (
+                await conn.exec_driver_sql("SELECT id, title, tags, body FROM documents")
+            ).fetchall()
+            for doc_id, title, tags, body in rows:
+                await conn.exec_driver_sql(
+                    "INSERT INTO documents_fts (doc_id, title, tags, body) VALUES (?, ?, ?, ?)",
+                    (doc_id, title or "", _tags_text(tags), body or ""),
+                )
+            logger.info("Reindexed %d document(s) for search", len(rows))
+    except Exception as exc:  # pragma: no cover - defensive, boot must not die
+        logger.debug("Document search index not rebuilt: %s", exc)
+
+
+def _tags_text(raw: Any) -> str:
+    """Flatten a document's JSON tag list into a single indexable string."""
+    if isinstance(raw, str):
+        with suppress(ValueError):
+            raw = _json.loads(raw)
+    if isinstance(raw, list):
+        return " ".join(str(tag) for tag in raw)
+    return ""
 
 
 async def get_db() -> AsyncGenerator[AsyncSession, None]:

backend/app/db/models.py

@@ -16,39 +16,66 @@ def _uuid() -> str:
     return str(uuid.uuid4())
 
 
+class Design(Base):
+    __tablename__ = "designs"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
+    name: Mapped[str] = mapped_column(String, nullable=False)
+    design_type: Mapped[str] = mapped_column(String, nullable=False, default="network")
+    icon: Mapped[str | None] = mapped_column(String, nullable=True, default="dashboard")
+    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 Node(Base):
+    """How a device is drawn on one canvas.
+
+    A node owns presentation only — position, size, colours, icon, handles,
+    nesting. What the device *is* (addresses, services, properties, notes,
+    hardware, check method, live status) belongs to the `device_inventory` row
+    named by `device_id`, so one device reads the same on every canvas. The API
+    still reports both together: see `services/inventory_sync.hydrated_node`.
+    """
+
     __tablename__ = "nodes"
 
     id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
     type: Mapped[str] = mapped_column(String, nullable=False)
     label: Mapped[str] = mapped_column(String, nullable=False)
-    hostname: Mapped[str | None] = mapped_column(String)
-    ip: Mapped[str | None] = mapped_column(String)
-    mac: Mapped[str | None] = mapped_column(String)
-    os: Mapped[str | None] = mapped_column(String)
-    status: Mapped[str] = mapped_column(String, default="unknown")
-    check_method: Mapped[str | None] = mapped_column(String)
-    check_target: Mapped[str | None] = mapped_column(String)
-    services: Mapped[list[Any]] = mapped_column(JSON, default=list)
-    notes: Mapped[str | None] = mapped_column(Text)
+    design_id: Mapped[str | None] = mapped_column(String, ForeignKey("designs.id", ondelete="SET NULL"), nullable=True)
+    # The Device Inventory row this node draws. NULL for canvas furniture
+    # (group / groupRect / text), which represents nothing physical. Deleting a
+    # node never deletes the device — the inventory outlives every canvas.
+    device_id: Mapped[str | None] = mapped_column(
+        String, ForeignKey("device_inventory.id", ondelete="SET NULL"), index=True, nullable=True
+    )
+    # How this canvas renders the device's list facts: which services and which
+    # properties it shows, and in what order. The facts themselves stay on the
+    # inventory row, so the same device drawn on two canvases can show two
+    # different subsets — a scanner-guessed service on one, none on the other.
+    #   {"services": [{"key": "443|tcp|https", "visible": true}, …],
+    #    "properties": [{"key": "rack", "visible": false}, …]}
+    # NULL only for canvas furniture and for a node with no inventory row yet;
+    # `inventory_sync.link_facts` fills both lists as soon as there is one.
+    display_view: Mapped[dict[str, Any] | None] = mapped_column(JSON, nullable=True)
     pos_x: Mapped[float] = mapped_column(Float, default=0)
     pos_y: Mapped[float] = mapped_column(Float, default=0)
     parent_id: Mapped[str | None] = mapped_column(String, ForeignKey("nodes.id", ondelete="CASCADE"))
     container_mode: Mapped[bool] = mapped_column(Boolean, default=False)
     custom_colors: Mapped[dict[str, Any] | None] = mapped_column(JSON, nullable=True)
     custom_icon: Mapped[str | None] = mapped_column(String, nullable=True)
-    cpu_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
-    cpu_model: Mapped[str | None] = mapped_column(String, nullable=True)
-    ram_gb: Mapped[float | None] = mapped_column(Float, nullable=True)
-    disk_gb: Mapped[float | None] = mapped_column(Float, nullable=True)
-    show_hardware: Mapped[bool] = mapped_column(Boolean, default=False)
-    properties: Mapped[list[Any]] = mapped_column(JSON, default=list)
+    # What this piece of canvas furniture is for, in the user's words. Furniture
+    # (group / groupRect / text) draws no device, so it has no inventory row to
+    # carry a `notes` field — this column is that text's only home. NULL on every
+    # node that does draw a device: its notes belong to the inventory row.
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    show_port_numbers: Mapped[bool] = mapped_column(Boolean, default=False)
     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)
-    ieee_address: Mapped[str | None] = mapped_column(String, index=True, nullable=True)
-    last_seen: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
-    response_time_ms: Mapped[int | None] = mapped_column(Integer)
+    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)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
     updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now, onupdate=_now)
     children: Mapped[list["Node"]] = relationship("Node", back_populates="parent")
@@ -61,13 +88,18 @@ class Edge(Base):
     id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
     source: Mapped[str] = mapped_column(String, ForeignKey("nodes.id", ondelete="CASCADE"))
     target: Mapped[str] = mapped_column(String, ForeignKey("nodes.id", ondelete="CASCADE"))
+    design_id: Mapped[str | None] = mapped_column(String, ForeignKey("designs.id", ondelete="SET NULL"), nullable=True)
     type: Mapped[str] = mapped_column(String, default="ethernet")
     label: Mapped[str | None] = mapped_column(String)
     vlan_id: Mapped[int | None] = mapped_column(Integer)
     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)
@@ -77,14 +109,118 @@ class Edge(Base):
 class CanvasState(Base):
     __tablename__ = "canvas_state"
 
-    id: Mapped[int] = mapped_column(Integer, primary_key=True, default=1)
+    design_id: Mapped[str] = mapped_column(String, ForeignKey("designs.id", ondelete="CASCADE"), primary_key=True)
     viewport: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict)
     custom_style: Mapped[dict[str, Any] | None] = mapped_column(JSON, nullable=True)
     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")
+    # When the plate draws its sockets: "auto" (the faceplate decides), "always"
+    # or "hover". A canvas display choice about the mount, not about the device.
+    port_visibility: Mapped[str] = mapped_column(String, default="auto")
+    # [{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
 
     id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
     ip: Mapped[str | None] = mapped_column(String, nullable=True)
@@ -94,26 +230,85 @@ 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)
 
+    # --- Curated device facts (3.3.0) -------------------------------------
+    # The inventory row, not the canvas node, owns what the device *is*. A node
+    # only says how it is drawn. `label`/`type` supersede friendly_name/
+    # suggested_type for a device that reached a canvas; the older pair is kept
+    # so discovery imports and the source filters keep working unchanged.
+    label: Mapped[str | None] = mapped_column(String, nullable=True)
+    type: Mapped[str | None] = mapped_column(String, nullable=True)
+    notes: Mapped[str | None] = mapped_column(Text, nullable=True)
+    cpu_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    cpu_model: Mapped[str | None] = mapped_column(String, nullable=True)
+    ram_gb: Mapped[float | None] = mapped_column(Float, nullable=True)
+    disk_gb: Mapped[float | None] = mapped_column(Float, nullable=True)
+    show_hardware: Mapped[bool] = mapped_column(Boolean, default=False)
+    check_method: Mapped[str | None] = mapped_column(String, nullable=True)
+    check_target: Mapped[str | None] = mapped_column(String, nullable=True)
+    # Live reachability from the status checker. NOT `status` — that column holds
+    # the inventory lifecycle (pending/approved/hidden) and the two must not be
+    # conflated.
+    status_live: Mapped[str] = mapped_column(String, default="unknown")
+    last_seen: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    last_scan: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    response_time_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=_now, onupdate=_now
+    )
 
-class PendingDeviceLink(Base):
+    # --- Rack modelisation (owned here, not by the mount) ------------------
+    # A device wears the same front panel in every rack it is mounted in, so the
+    # inventory row — not `rack_devices` — owns the faceplate, its size and its
+    # ports. The mount keeps a denormalized copy so a rack still renders after an
+    # inventory purge; `/api/v1/racks` overlays these on load and `save` writes
+    # them back. NULL means "never modelled" — the mount's own copy then stands.
+    rack_faceplate_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    rack_u_height: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    rack_col_span: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    rack_color: Mapped[str | None] = mapped_column(String, nullable=True)
+    # [{id, label, type, x, y}] — x/y are unit coordinates on the plate.
+    rack_ports: Mapped[list[Any] | None] = mapped_column(JSON, nullable=True)
+
+    # Transient (not persisted): populated per-request by the scan routes to report
+    # how many canvases this device already appears on. Not a mapped column.
+    canvas_count: int = 0
+    # Transient (not persisted): timestamps from the linked canvas node(s),
+    # correlated by ip / ieee_address. None when the device is not on any canvas.
+    node_created_at: datetime | None = None
+    node_last_scan: datetime | None = None
+    node_last_modified: datetime | None = None
+    node_last_seen: datetime | None = None
+
+
+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)
@@ -134,3 +329,88 @@ class ScanRun(Base):
     started_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
     finished_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
     error: Mapped[str | None] = mapped_column(Text)
+
+
+class Document(Base):
+    """One markdown document.
+
+    A document either stands alone in the Library tree (`kind` page/folder,
+    placed by `parent_id`) or describes exactly one thing on the other side of
+    an optional link: a Device Inventory row (`device_id`), a piece of canvas
+    furniture such as a zone or a group (`node_id`), or a whole canvas
+    (`design_id`). Only one of the three is ever set, and each is enforced
+    unique by a partial index created in `database.init_db`.
+
+    Every link is `SET NULL` and `title` is denormalized, so deleting a device
+    or a canvas never destroys what the user wrote — the document survives as
+    an orphan and can be re-linked or filed away.
+
+    `body` is the whole markdown file, YAML frontmatter included, so a document
+    exports to disk as-is. `frontmatter` and `tags` are a parsed cache of that
+    block, kept only so listings can filter without reading every body.
+    """
+
+    __tablename__ = "documents"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
+    kind: Mapped[str] = mapped_column(String, nullable=False, default="page")
+    title: Mapped[str] = mapped_column(String, nullable=False)
+    slug: Mapped[str] = mapped_column(String, nullable=False, index=True)
+    icon: Mapped[str | None] = mapped_column(String, nullable=True)
+
+    # Library tree. Folders are documents too, so an empty folder is possible
+    # and a folder can carry an index body. Only page/folder set this.
+    parent_id: Mapped[str | None] = mapped_column(
+        String, ForeignKey("documents.id", ondelete="CASCADE"), nullable=True, index=True
+    )
+    sort_order: Mapped[int] = mapped_column(Integer, default=0)
+
+    device_id: Mapped[str | None] = mapped_column(
+        String, ForeignKey("device_inventory.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    node_id: Mapped[str | None] = mapped_column(
+        String, ForeignKey("nodes.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    design_id: Mapped[str | None] = mapped_column(
+        String, ForeignKey("designs.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+
+    body: Mapped[str] = mapped_column(Text, nullable=False, default="")
+    frontmatter: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict)
+    tags: Mapped[list[str]] = mapped_column(JSON, default=list)
+    starred: Mapped[bool] = mapped_column(Boolean, default=False)
+    template_id: Mapped[str | None] = mapped_column(String, nullable=True)
+
+    # The device facts as they read when this document was scaffolded or last
+    # reconciled. The header is generated once and then owned by the user, so
+    # this is what tells the UI the document has drifted from the device.
+    facts_snapshot: Mapped[dict[str, Any] | None] = mapped_column(JSON, nullable=True)
+    facts_synced_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    reviewed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    # Set the first time the body is edited by hand. NULL means the document is
+    # still only what the template generated — which is what the coverage view
+    # counts as "not really documented yet". A timestamp comparison cannot say
+    # this: created_at and updated_at are two separate clock reads on insert.
+    edited_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    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 DocumentRevision(Base):
+    """A prior version of a document's body.
+
+    Written on every explicit save that actually changed the body, and pruned
+    to the most recent `REVISION_LIMIT` per document in the same transaction.
+    """
+
+    __tablename__ = "document_revisions"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
+    document_id: Mapped[str] = mapped_column(
+        String, ForeignKey("documents.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    title: Mapped[str] = mapped_column(String, nullable=False)
+    body: Mapped[str] = mapped_column(Text, nullable=False, default="")
+    reason: Mapped[str] = mapped_column(String, nullable=False, default="edit")
+    saved_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)

backend/app/main.py

@@ -6,12 +6,31 @@ 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, edges, liveview, nodes, scan, stats, status, zigbee
+from app.api.routes import (
+    auth,
+    canvas,
+    designs,
+    documents,
+    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.db.database import init_db
+from app.core.security import OIDCCSRFMiddleware
+from app.db.database import AsyncSessionLocal, init_db
+from app.services.scanner import reconcile_orphan_runs
 
 
 @asynccontextmanager
@@ -28,6 +47,10 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
     logging.getLogger("app.services.scanner").setLevel(logging.INFO)
     await init_db()
     settings.load_overrides()
+    # A scan runs on a background thread in this process, so anything still
+    # flagged "running" now was orphaned by a previous one that died mid-scan.
+    async with AsyncSessionLocal() as db:
+        await reconcile_orphan_runs(db)
     start_scheduler()
     yield
     stop_scheduler()
@@ -39,24 +62,39 @@ 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"])
 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.include_router(documents.router, prefix="/api/v1/documents", tags=["documents"])
 
 
 @app.get("/api/v1/health")

backend/app/schemas/canvas.py

@@ -1,16 +1,27 @@
 from typing import Any
 
-from pydantic import BaseModel, field_validator
+from pydantic import BaseModel, field_validator, model_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):
     id: str
     type: str
     label: str
+    # Round-tripped so a save keeps the node pointed at its inventory row. The
+    # device fields below are still accepted at their canvas values and routed
+    # to that row server-side.
+    device_id: str | None = None
+    # Which device facts this canvas edited since it loaded them, if the client
+    # tracked that. The payload always carries a *full* copy of the device — it
+    # was hydrated from the inventory row on load — so without this a save made
+    # for nothing but a moved node would rewrite the row from a snapshot that may
+    # be hours old. `None` (an older client, an import, the MCP server) keeps the
+    # previous behaviour: every fact is a candidate write.
+    changed_facts: list[str] | None = None
     hostname: str | None = None
     ip: str | None = None
     mac: str | None = None
@@ -20,6 +31,9 @@ class NodeSave(BaseModel):
     check_target: str | None = None
     services: list[Any] = []
     notes: str | None = None
+    # Canvas furniture only: the zone or group's own description. Furniture has no
+    # inventory row, so this is the one place the text can live.
+    description: str | None = None
     parent_id: str | None = None
     container_mode: bool = False
     custom_colors: dict[str, Any] | None = None
@@ -29,13 +43,33 @@ class NodeSave(BaseModel):
     ram_gb: float | None = None
     disk_gb: float | None = None
     show_hardware: bool = False
+    show_port_numbers: bool = False
     properties: list[Any] = []
     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
 
+    @model_validator(mode="after")
+    def drop_self_parent(self) -> "NodeSave":
+        """A node can never be its own parent.
+
+        Every parent walk on the canvas — waypoint propagation, ordering
+        parents before children, collapse — assumes an acyclic tree, and a
+        self-parent row makes the node undraggable once it is reloaded (#370).
+
+        Dropped rather than rejected: a canvas that already carries the bad row
+        must still be able to save, and a 422 here would cost the user the whole
+        save. The startup repair clears what is already persisted.
+        """
+        if self.parent_id is not None and self.parent_id == self.id:
+            self.parent_id = None
+        return self
+
 
 class EdgeSave(BaseModel):
     id: str
@@ -47,7 +81,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
@@ -57,12 +95,18 @@ 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] = []
     edges: list[EdgeSave] = []
     viewport: dict[str, Any] = {}
     custom_style: dict[str, Any] | None = None
+    design_id: str | None = None
 
 
 class CanvasStateResponse(BaseModel):
@@ -70,3 +114,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

@@ -0,0 +1,51 @@
+from datetime import datetime
+
+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"
+    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
+    design_type: str
+    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/documents.py

@@ -0,0 +1,177 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, field_validator
+
+from app.services.doc_template import TEMPLATE_IDS
+from app.services.doc_tree import DOCUMENT_KINDS
+
+# Kept in sync with DocKind in frontend/src/documentation/types.ts.
+# "page" and "folder" live in the Library tree and carry a parent; "device",
+# "node" and "design" each point at exactly one thing elsewhere in the app and
+# are placed by that link instead, so the frontend can pivot them however the
+# user asks (by zone, subnet, type…) without the server storing a tree.
+DOC_KINDS = set(DOCUMENT_KINDS)
+
+
+class DocumentCreate(BaseModel):
+    kind: str = "page"
+    title: str
+    icon: str | None = None
+    parent_id: str | None = None
+    device_id: str | None = None
+    node_id: str | None = None
+    design_id: str | None = None
+    # Scaffolds the body when no body is supplied. "device" is implied for a
+    # device document and is the only template that reads the live facts.
+    template_id: str | None = None
+    body: str | None = None
+
+    @field_validator("kind")
+    @classmethod
+    def _known_kind(cls, v: str) -> str:
+        if v not in DOC_KINDS:
+            raise ValueError(f"kind must be one of {sorted(DOC_KINDS)}")
+        return v
+
+    @field_validator("template_id")
+    @classmethod
+    def _known_template(cls, v: str | None) -> str | None:
+        if v is not None and v not in TEMPLATE_IDS:
+            raise ValueError(f"template_id must be one of {sorted(TEMPLATE_IDS)}")
+        return v
+
+
+class DocumentUpdate(BaseModel):
+    title: str | None = None
+    icon: str | None = None
+    body: str | None = None
+    parent_id: str | None = None
+    sort_order: int | None = None
+    starred: bool | None = None
+    # Explicit: "I have re-read this and it is still true." Sent as a bare true
+    # rather than a timestamp so the server owns the clock.
+    reviewed: bool | None = None
+    # Accept the device's current facts as documented, clearing the drift
+    # banner without touching the body.
+    resync_facts: bool | None = None
+
+
+class DocumentSummary(BaseModel):
+    """Everything the tree needs. Never carries a body — listings stay small."""
+
+    id: str
+    kind: str
+    title: str
+    slug: str
+    icon: str | None = None
+    parent_id: str | None = None
+    sort_order: int = 0
+    device_id: str | None = None
+    node_id: str | None = None
+    design_id: str | None = None
+    tags: list[str] = []
+    # The parsed frontmatter travels with the summary so the tree can badge a
+    # document as due for review without fetching every body.
+    frontmatter: dict[str, Any] = {}
+    starred: bool = False
+    template_id: str | None = None
+    # Whether the device has moved on since the snapshot was taken. Computed by
+    # the server because only the server knows the snapshot's shape: it holds
+    # `label` and `type` through their fallbacks and `properties` as a flat
+    # map, none of which the inventory wire shape can be compared against
+    # field by field.
+    drifted: bool = False
+    reviewed_at: datetime | None = None
+    edited_at: datetime | None = None
+    facts_synced_at: datetime | None = None
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class DocumentResponse(DocumentSummary):
+    body: str = ""
+    facts_snapshot: dict[str, Any] | None = None
+
+
+class RevisionSummary(BaseModel):
+    id: str
+    document_id: str
+    title: str
+    reason: str
+    saved_at: datetime
+    # Character count, so the history list can show how much changed without
+    # shipping every body.
+    size: int = 0
+
+    model_config = {"from_attributes": True}
+
+
+class RevisionResponse(RevisionSummary):
+    body: str = ""
+
+
+class SearchHit(BaseModel):
+    doc_id: str
+    title: str
+    kind: str
+    snippet: str
+    device_id: str | None = None
+
+
+class SearchResponse(BaseModel):
+    # "fts5" or "like" — the UI drops snippet highlighting on the fallback.
+    engine: str
+    hits: list[SearchHit]
+
+
+class BacklinkHit(BaseModel):
+    """A document that links here, and the line it does it on."""
+
+    doc_id: str
+    title: str
+    kind: str
+    device_id: str | None = None
+    # What the link was written as, so a `[[…|label]]` reads back as the author
+    # meant it rather than as the target's own title.
+    label: str
+    context: str
+    count: int = 1
+
+
+class ScaffoldRequest(BaseModel):
+    """Create the missing device documents.
+
+    Omitting `device_ids` means every approved device that has none, which is
+    the one-click migration off the old notes field.
+    """
+
+    device_ids: list[str] | None = None
+    template_id: str = "device"
+    # Only devices whose notes are not empty. What the migration banner sends.
+    only_with_notes: bool = False
+
+
+class ScaffoldResponse(BaseModel):
+    created: list[DocumentSummary]
+    skipped: int
+
+
+class DriftField(BaseModel):
+    field: str
+    documented: Any = None
+    current: Any = None
+
+
+class CoverageResponse(BaseModel):
+    devices: int
+    documented: int
+    # A document whose body is still only what the template generated.
+    header_only: int
+    missing: int
+    drifted: int
+    overdue: int
+    notes_unmigrated: int
+    library_pages: int

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,9 +28,14 @@ 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):
-    pass
+    design_id: str | None = None
 
 
 class EdgeUpdate(BaseModel):
@@ -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,9 +61,17 @@ 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
+    design_id: str | None = None
     created_at: datetime
 
     model_config = {"from_attributes": True}

backend/app/schemas/nodes.py

@@ -16,6 +16,9 @@ class NodeBase(BaseModel):
     check_target: str | None = None
     services: list[Any] = []
     notes: str | None = None
+    # Canvas furniture only (group / groupRect / text): what the zone or group is
+    # for. A node that draws a device keeps its text on the inventory row instead.
+    description: str | None = None
     pos_x: float = 0
     pos_y: float = 0
     parent_id: str | None = None
@@ -27,14 +30,26 @@ class NodeBase(BaseModel):
     ram_gb: float | None = None
     disk_gb: float | None = None
     show_hardware: bool = False
+    show_port_numbers: bool = False
     properties: list[dict[str, Any]] = []
     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):
-    pass
+    # 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):
@@ -49,6 +64,7 @@ class NodeUpdate(BaseModel):
     check_target: str | None = None
     services: list[Any] | None = None
     notes: str | None = None
+    description: str | None = None
     pos_x: float | None = None
     pos_y: float | None = None
     parent_id: str | None = None
@@ -60,15 +76,26 @@ class NodeUpdate(BaseModel):
     ram_gb: float | None = None
     disk_gb: float | None = None
     show_hardware: bool | None = None
+    show_port_numbers: bool | None = None
     properties: list[dict[str, Any]] | None = None
     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):
     id: str
+    design_id: str | None = None
+    # The Device Inventory row this node draws; None for canvas furniture. The
+    # device fields above are hydrated from that row on read, so the wire shape
+    # is unchanged even though the row, not the node, owns them.
+    device_id: str | None = None
+    ieee_address: str | None = None
     last_seen: datetime | None = None
+    last_scan: datetime | None = None
     response_time_ms: int | None = None
     created_at: datetime
     updated_at: datetime

backend/app/schemas/proxmox.py

@@ -0,0 +1,91 @@
+"""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
+    # The Device Inventory row this node draws, stamped by the import. The
+    # canvas carries it back on save so the node links to that row rather
+    # than minting a second one for the same device.
+    device_id: 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,361 @@
+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"}
+# When a mount draws its ports; "auto" leaves the faceplate in charge.
+PORT_VISIBILITIES = {"auto", "always", "hover"}
+# 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"
+    port_visibility: str = "auto"
+    ports: list[Any] = []
+
+    @field_validator("port_visibility", mode="before")
+    @classmethod
+    def _known_port_visibility(cls, v: Any) -> str:
+        """Anything unknown — including the NULL of a pre-column row — is `auto`."""
+        return str(v) if v in PORT_VISIBILITIES else "auto"
+
+    @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
+
+    @model_validator(mode="after")
+    def _devices_do_not_overlap(self) -> "RackSaveRequest":
+        """Two mounts may not claim the same square of a rack.
+
+        The canvas already refuses such a drop (`canPlace`), so this is the same
+        rule stated where the state is persisted rather than where it is dragged
+        — a stale tab, a hand-built payload or a bug upstream would otherwise
+        store two plates drawn on top of each other, with no way to grab the one
+        underneath.
+        """
+        by_rack: dict[str, list[RackDeviceSave]] = {}
+        for device in self.devices:
+            by_rack.setdefault(device.rack_id, []).append(device)
+        for mounts in by_rack.values():
+            for i, a in enumerate(mounts):
+                for b in mounts[i + 1 :]:
+                    if (
+                        a.u_start < b.u_start + b.u_height
+                        and b.u_start < a.u_start + a.u_height
+                        and a.col_start < b.col_start + b.col_span
+                        and b.col_start < a.col_start + a.col_span
+                    ):
+                        raise ValueError(
+                            f"Devices {a.id} and {b.id} overlap in rack {a.rack_id}"
+                        )
+        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
+    port_visibility: str = "auto"
+    ports: list[Any] = []
+
+    @field_validator("port_visibility", mode="before")
+    @classmethod
+    def _port_visibility_or_auto(cls, v: Any) -> str:
+        """Rows written before the column existed read back as NULL."""
+        return str(v) if v in PORT_VISIBILITIES else "auto"
+
+    @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
+    # Rack modelisation the inventory row owns — the same front panel wherever
+    # the device is mounted. All None/empty for a device never modelled; the
+    # tray then falls back to the type-suggested faceplate.
+    rack_faceplate_id: str | None = None
+    rack_u_height: int | None = None
+    rack_col_span: int | None = None
+    rack_color: str | None = None
+    rack_ports: list[dict[str, Any]] = []
+
+    @field_validator("rack_ports", mode="before")
+    @classmethod
+    def _clean_ports(cls, v: Any) -> list[dict[str, Any]]:
+        """NULL for a row written before the column existed; junk stays out."""
+        if not isinstance(v, list):
+            return []
+        return [p for p in v if isinstance(p, dict) and p.get("id")]
+
+    @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,15 @@
 from datetime import datetime
 from typing import Any
 
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
+
+from app.schemas.racks import RACK_COLUMNS
+
+# Tallest plate the rack canvas offers; `MAX_RACK_U` on the frontend.
+MAX_PLATE_U = 48
 
 
-class PendingDeviceResponse(BaseModel):
+class InventoryDeviceResponse(BaseModel):
     id: str
     ip: str | None
     mac: str | None
@@ -14,17 +19,197 @@ 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
+    # Curated device facts (3.3.0). `label`/`type` supersede friendly_name/
+    # suggested_type once the user has named the device; the older pair stays for
+    # discovery imports and the source filters.
+    label: str | None = None
+    type: str | None = None
+    notes: str | None = None
+    cpu_count: int | None = None
+    cpu_model: str | None = None
+    ram_gb: float | None = None
+    disk_gb: float | None = None
+    show_hardware: bool = False
+    check_method: str | None = None
+    check_target: str | None = None
+    # Live reachability, distinct from `status` (the pending/approved/hidden
+    # lifecycle).
+    status_live: str = "unknown"
+    last_seen: datetime | None = None
+    last_scan: datetime | None = None
+    response_time_ms: int | None = None
+    updated_at: datetime | None = None
+    # Number of distinct canvases (designs) this device already appears on,
+    # correlated by ip / ieee_address against existing nodes. Computed per-request.
+    canvas_count: int = 0
+    # Timestamps from the linked canvas node(s), correlated by ip / ieee_address.
+    # Null when the device is not on any canvas yet. Aggregated across matches:
+    # created_at = oldest; last_scan / last_modified / last_seen = newest.
+    node_created_at: datetime | None = None
+    node_last_scan: datetime | None = None
+    node_last_modified: datetime | None = None
+    node_last_seen: datetime | None = None
+    # Rack modelisation: the front panel this device wears in every rack it is
+    # mounted in. The row owns it — see `RackDevice` and `/api/v1/racks`. All
+    # None/empty for a device that has never been racked or modelled.
+    rack_faceplate_id: str | None = None
+    rack_u_height: int | None = None
+    rack_col_span: int | None = None
+    rack_color: str | None = None
+    rack_ports: list[Any] = []
+
+    @field_validator("rack_ports", mode="before")
+    @classmethod
+    def _coerce_rack_ports(cls, v: Any) -> list[Any]:
+        """NULL on every row written before the column existed."""
+        return v if isinstance(v, list) else []
+
+    @field_validator("properties", "discovery_sources", "services", 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 []
+
+    @field_validator("status_live", mode="before")
+    @classmethod
+    def _coerce_status_live(cls, v: Any) -> str:
+        return v if isinstance(v, str) and v else "unknown"
+
+    @field_validator("show_hardware", mode="before")
+    @classmethod
+    def _coerce_show_hardware(cls, v: Any) -> bool:
+        return bool(v)
 
     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"
+    # Curated fields, so a hand-made entry can carry everything the edit modal
+    # shows rather than needing a create-then-PATCH round trip.
+    os: str | None = None
+    services: list[Any] = []
+    friendly_name: str | None = None
+    device_subtype: str | None = None
+    label: str | None = None
+    type: str | None = None
+    notes: str | None = None
+    cpu_count: int | None = None
+    cpu_model: str | None = None
+    ram_gb: float | None = None
+    disk_gb: float | None = None
+    show_hardware: bool = False
+    check_method: str | None = None
+    check_target: str | None = None
+
+    @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 InventoryDeviceUpdate(BaseModel):
+    """Partial edit of an inventory row — the write half of the detail modal.
+
+    Every field is optional and only what the client sends is applied
+    (`exclude_unset`), so a caller editing one field never clears the rest.
+    Lifecycle (`status`) and discovery bookkeeping (`discovery_source(s)`,
+    `discovered_at`, `ieee_address`) are deliberately not editable here: those
+    are owned by the approve/hide routes and the importers.
+    """
+
+    ip: str | None = None
+    mac: str | None = None
+    hostname: str | None = None
+    os: str | None = None
+    label: str | None = None
+    type: str | None = None
+    suggested_type: str | None = None
+    friendly_name: str | None = None
+    device_subtype: str | None = None
+    model: str | None = None
+    vendor: str | None = None
+    services: list[Any] | None = None
+    properties: list[Any] | None = None
+    notes: str | None = None
+    cpu_count: int | None = None
+    cpu_model: str | None = None
+    ram_gb: float | None = None
+    disk_gb: float | None = None
+    show_hardware: bool | None = None
+    check_method: str | None = None
+    check_target: str | None = None
+    # Rack modelisation, edited from the Device Inventory as well as from a rack
+    # canvas. Sending `rack_faceplate_id` is what models a device; the rest
+    # describes the plate it wears.
+    rack_faceplate_id: str | None = None
+    rack_u_height: int | None = None
+    rack_col_span: int | None = None
+    rack_color: str | None = None
+    rack_ports: list[Any] | None = None
+
+    @field_validator("rack_u_height")
+    @classmethod
+    def _plate_height(cls, v: int | None) -> int | None:
+        if v is not None and not 1 <= v <= MAX_PLATE_U:
+            raise ValueError(f"rack_u_height must be between 1 and {MAX_PLATE_U}")
+        return v
+
+    @field_validator("rack_col_span")
+    @classmethod
+    def _plate_span(cls, v: int | None) -> int | None:
+        if v is not None and not 1 <= v <= RACK_COLUMNS:
+            raise ValueError(f"rack_col_span must be between 1 and {RACK_COLUMNS}")
+        return v
+
+    @field_validator("rack_ports")
+    @classmethod
+    def _plate_ports(cls, v: list[Any] | None) -> list[Any] | None:
+        """A port with no id is not a port: no cable could ever name it."""
+        if v is None:
+            return None
+        return [p for p in v if isinstance(p, dict) and p.get("id")]
+
+
 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

@@ -60,6 +60,10 @@ class ZigbeeNodeOut(BaseModel):
     vendor: str | None = None
     lqi: int | None = None
     parent_id: str | None = None
+    # The Device Inventory row this node draws, stamped by the import. The
+    # canvas carries it back on save so the node links to that row rather
+    # than minting a second one for the same device.
+    device_id: str | None = None
 
 
 class ZigbeeEdgeOut(BaseModel):
@@ -73,6 +77,21 @@ class ZigbeeImportResponse(BaseModel):
     device_count: int
 
 
+class ZigbeeImportJob(BaseModel):
+    """Handle returned when a canvas import is queued."""
+
+    job_id: str
+    status: str  # running | done | error
+
+
+class ZigbeeImportJobResult(BaseModel):
+    """Poll response for a canvas import. ``result`` is set once done."""
+
+    job_id: str
+    status: str  # running | done
+    result: ZigbeeImportResponse | None = None
+
+
 class ZigbeeTestConnectionResponse(BaseModel):
     connected: bool
     message: str
@@ -93,3 +112,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

@@ -0,0 +1,116 @@
+"""Pydantic v2 schemas for Z-Wave JS UI (zwavejs2mqtt) import."""
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class ZwaveImportRequest(BaseModel):
+    mqtt_host: str = Field(..., description="MQTT broker hostname or IP address")
+    mqtt_port: int = Field(1883, ge=1, le=65535, description="MQTT broker port")
+    mqtt_username: str | None = Field(None, description="MQTT username (optional)")
+    mqtt_password: str | None = Field(None, description="MQTT password (optional)")
+    prefix: str = Field("zwave", description="Z-Wave JS UI MQTT prefix")
+    gateway_name: str = Field("zwavejs2mqtt", description="Z-Wave JS UI gateway name")
+    mqtt_tls: bool = Field(False, description="Enable TLS (typically port 8883)")
+    mqtt_tls_insecure: bool = Field(
+        False, description="Skip TLS certificate verification (self-signed only)"
+    )
+
+    @model_validator(mode="after")
+    def _insecure_requires_tls(self) -> "ZwaveImportRequest":
+        if self.mqtt_tls_insecure and not self.mqtt_tls:
+            raise ValueError("mqtt_tls_insecure requires mqtt_tls=true")
+        return self
+
+
+class ZwaveTestConnectionRequest(BaseModel):
+    mqtt_host: str
+    mqtt_port: int = Field(1883, ge=1, le=65535)
+    mqtt_username: str | None = None
+    mqtt_password: str | None = None
+    mqtt_tls: bool = False
+    mqtt_tls_insecure: bool = False
+
+    @model_validator(mode="after")
+    def _insecure_requires_tls(self) -> "ZwaveTestConnectionRequest":
+        if self.mqtt_tls_insecure and not self.mqtt_tls:
+            raise ValueError("mqtt_tls_insecure requires mqtt_tls=true")
+        return self
+
+
+class ZwaveNodeOut(BaseModel):
+    """A homelable-ready node representation of a Z-Wave device."""
+
+    id: str
+    label: str
+    type: str  # zwave_coordinator | zwave_router | zwave_enddevice
+    ieee_address: str
+    friendly_name: str
+    device_type: str
+    model: str | None = None
+    vendor: str | None = None
+    lqi: int | None = None
+    parent_id: str | None = None
+    # The Device Inventory row this node draws, stamped by the import. The
+    # canvas carries it back on save so the node links to that row rather
+    # than minting a second one for the same device.
+    device_id: str | None = None
+
+
+class ZwaveEdgeOut(BaseModel):
+    source: str
+    target: str
+
+
+class ZwaveImportResponse(BaseModel):
+    nodes: list[ZwaveNodeOut]
+    edges: list[ZwaveEdgeOut]
+    device_count: int
+
+
+class ZwaveTestConnectionResponse(BaseModel):
+    connected: bool
+    message: str
+
+
+class ZwaveCoordinatorOut(BaseModel):
+    id: str
+    label: str
+    ieee_address: str
+
+
+class ZwaveImportPendingResponse(BaseModel):
+    """Result of importing a Z-Wave network into the pending section."""
+
+    pending_created: int
+    pending_updated: int
+    coordinator: ZwaveCoordinatorOut | None = None
+    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/doc_backlinks.py

@@ -0,0 +1,158 @@
+"""Backlinks — the documents pointing at a given document.
+
+A wiki-link is one-way in the body: `[[device:nas-01]]` says where to go, not
+where it came from. This walks every body once and inverts that.
+
+The parsing and resolution rules **mirror `frontend/src/documentation/
+wikilinks.ts` exactly** — same prefixes, same fallback order, same
+case-insensitivity — the way `doc_template.service_url` mirrors
+`utils/serviceUrl.ts`. They are duplicated rather than shared because the
+forward direction has to resolve while the user types, with only what the
+browser already holds, and the reverse direction needs every body, which the
+browser does not hold: the list endpoint is metadata-only on purpose.
+
+Change one side and change the other; `test_doc_backlinks.py` pins the rules.
+"""
+
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import Any
+
+_LINK = re.compile(r"\[\[([^\]]+)\]\]")
+_TARGETS = {"device", "doc", "node"}
+
+# How much of the line the link sits on is worth showing next to it.
+_CONTEXT_CHARS = 160
+
+
+@dataclass(frozen=True)
+class WikiLink:
+    """`[[device:nas-01|the NAS]]` → target=device, key=nas-01, label=the NAS."""
+
+    target: str
+    key: str
+    label: str
+
+
+@dataclass(frozen=True)
+class Backlink:
+    """One document pointing at another, and the line it does it on."""
+
+    doc_id: str
+    label: str
+    context: str
+    count: int
+
+
+def parse_link(inner: str) -> WikiLink | None:
+    """Parse the inside of a `[[…]]`. An unknown prefix is part of the key."""
+    address, _, label_part = inner.partition("|")
+    address = address.strip()
+    label = label_part.strip()
+    if not address:
+        return None
+    target = "doc"
+    key = address
+    prefix, sep, rest = address.partition(":")
+    if sep and prefix.lower() in _TARGETS:
+        target = prefix.lower()
+        key = rest.strip()
+    if not key:
+        return None
+    return WikiLink(target=target, key=key, label=label or key)
+
+
+def iter_links(body: str) -> Iterator[tuple[str, WikiLink]]:
+    """Every link in a body, with the line it was written on."""
+    for line in (body or "").splitlines():
+        for match in _LINK.finditer(line):
+            link = parse_link(match.group(1))
+            if link:
+                yield line, link
+
+
+def device_label(device: Any) -> str:
+    """Mirrors `deviceLabel` in `documentation/tree.ts`."""
+    return (
+        device.label
+        or device.friendly_name
+        or device.hostname
+        or device.ip
+        or "Unnamed device"
+    )
+
+
+def resolve(link: WikiLink, docs: list[Any], devices: list[Any]) -> str | None:
+    """The document a link points at, or None when nothing matches yet."""
+    key = link.key.lower()
+    if link.target == "device":
+        device = next(
+            (d for d in devices if d.id == link.key or device_label(d).lower() == key),
+            None,
+        )
+        if device is None:
+            return None
+        return next((doc.id for doc in docs if doc.device_id == device.id), None)
+    if link.target == "node":
+        return next((doc.id for doc in docs if doc.node_id == link.key), None)
+    # A bare or `doc:` link: id, then slug, then title.
+    return (
+        next((doc.id for doc in docs if doc.id == link.key), None)
+        or next((doc.id for doc in docs if (doc.slug or "").lower() == key), None)
+        or next((doc.id for doc in docs if (doc.title or "").lower() == key), None)
+    )
+
+
+def _context(line: str, label: str) -> str:
+    """The line the link is on, trimmed to a readable window around it."""
+    text = " ".join(line.split())
+    if len(text) <= _CONTEXT_CHARS:
+        return text
+    at = text.find(label)
+    if at < 0:
+        return text[:_CONTEXT_CHARS].rstrip() + "…"
+    start = max(0, at - _CONTEXT_CHARS // 2)
+    end = min(len(text), start + _CONTEXT_CHARS)
+    return ("…" if start else "") + text[start:end].strip() + ("…" if end < len(text) else "")
+
+
+def backlinks_for(target_id: str, docs: list[Any], devices: list[Any]) -> list[Backlink]:
+    """Which of `docs` link to `target_id`, in the order the tree lists them.
+
+    One entry per source document however many times it links, because the
+    reader wants the documents, not the occurrences; `count` keeps the rest.
+    A document linking to itself is not a backlink.
+    """
+    found: dict[str, Backlink] = {}
+    for doc in docs:
+        # Every document is a resolution target, but only one carrying `[[`
+        # can be a source — skipping the rest early keeps this one cheap pass.
+        if doc.id == target_id or "[[" not in (doc.body or ""):
+            continue
+        for line, link in iter_links(doc.body or ""):
+            if resolve(link, docs, devices) != target_id:
+                continue
+            existing = found.get(doc.id)
+            if existing is None:
+                found[doc.id] = Backlink(
+                    doc_id=doc.id,
+                    label=link.label,
+                    context=_context(line, link.label),
+                    count=1,
+                )
+            else:
+                found[doc.id] = Backlink(
+                    doc_id=existing.doc_id,
+                    label=existing.label,
+                    context=existing.context,
+                    count=existing.count + 1,
+                )
+    return list(found.values())
+
+
+def has_device_link(docs: list[Any]) -> bool:
+    """Whether any body carries a `[[device:…]]`, so the devices load is skippable."""
+    return any(
+        link.target == "device" for doc in docs for _, link in iter_links(doc.body or "")
+    )

backend/app/services/doc_links.py

@@ -0,0 +1,40 @@
+"""Clear document links when the thing a document describes is deleted.
+
+The schema declares `ON DELETE SET NULL` on `documents.device_id`, `node_id` and
+`design_id`, but SQLite runs here with foreign keys off (see
+`api/routes/scan.py::delete_pending`), so nothing enforces it. Without this the
+column would keep naming a row that no longer exists and the document would look
+linked while resolving to nothing.
+
+Clearing rather than deleting is deliberate: the inventory outlives the canvas,
+and what the user wrote outlives both. The document survives as an orphan,
+keeping its denormalized `title`, and can be re-linked or filed into the Library.
+"""
+
+from collections.abc import Sequence
+
+from sqlalchemy import update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import Document
+
+
+async def unlink_documents(
+    db: AsyncSession,
+    *,
+    device_ids: Sequence[str] | None = None,
+    node_ids: Sequence[str] | None = None,
+    design_ids: Sequence[str] | None = None,
+) -> None:
+    """Orphan every document pointing at any of the given rows.
+
+    Caller commits — this is meant to run inside the same transaction as the
+    delete it accompanies.
+    """
+    for column, ids in (
+        (Document.device_id, device_ids),
+        (Document.node_id, node_ids),
+        (Document.design_id, design_ids),
+    ):
+        if ids:
+            await db.execute(update(Document).where(column.in_(list(ids))).values({column: None}))

backend/app/services/doc_search.py

@@ -0,0 +1,132 @@
+"""Full-text search over documents.
+
+SQLite's FTS5 module is not guaranteed: the LXC and Docker images ship whatever
+SQLite the base distribution built, and `database.py` already avoids depending
+on JSON1 for the same reason. So the index is best-effort — every write keeps it
+up to date when it exists, and `search` falls back to LIKE when it does not. The
+endpoint reports which engine answered so the UI can drop snippet highlighting.
+
+The index is maintained from Python rather than by triggers: the write paths are
+few, they are already inside a transaction, and a trigger would have to be kept
+in sync through `_try_migrate` forever.
+"""
+
+import logging
+from typing import Any
+
+from sqlalchemy import text
+from sqlalchemy.exc import OperationalError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+logger = logging.getLogger(__name__)
+
+# Column positions inside documents_fts, for snippet().
+_BODY_COLUMN = 3
+
+_available: bool | None = None
+
+
+def reset_availability_cache() -> None:
+    """Forget the probed FTS5 state. Tests swap databases between cases."""
+    global _available
+    _available = None
+
+
+async def fts_available(db: AsyncSession) -> bool:
+    """Whether this SQLite build has FTS5 and the index table exists."""
+    global _available
+    if _available is None:
+        try:
+            await db.execute(text("SELECT doc_id FROM documents_fts LIMIT 1"))
+            _available = True
+        except OperationalError:
+            _available = False
+            logger.info("FTS5 unavailable — document search falls back to LIKE")
+    return _available
+
+
+def tags_text(tags: Any) -> str:
+    """Flatten a tag list into one indexable string."""
+    if isinstance(tags, list):
+        return " ".join(str(tag) for tag in tags)
+    return ""
+
+
+async def index_document(db: AsyncSession, doc: Any) -> None:
+    """Re-index one document. Safe to call when FTS5 is missing."""
+    if not await fts_available(db):
+        return
+    await unindex_document(db, doc.id)
+    await db.execute(
+        text("INSERT INTO documents_fts (doc_id, title, tags, body) VALUES (:i, :t, :g, :b)"),
+        {"i": doc.id, "t": doc.title or "", "g": tags_text(doc.tags), "b": doc.body or ""},
+    )
+
+
+async def unindex_document(db: AsyncSession, doc_id: str) -> None:
+    if not await fts_available(db):
+        return
+    await db.execute(text("DELETE FROM documents_fts WHERE doc_id = :i"), {"i": doc_id})
+
+
+def build_match_query(raw: str) -> str:
+    """Turn user input into an FTS5 MATCH expression.
+
+    Every term is quoted, so punctuation a user types (`192.168.1.1`, `nas-01`,
+    an unbalanced quote) is data rather than FTS5 syntax, and gets a prefix `*`
+    so typing half a word still matches.
+    """
+    terms = [term.replace('"', '""') for term in raw.split() if term.strip()]
+    return " AND ".join(f'"{term}"*' for term in terms)
+
+
+async def search(db: AsyncSession, query: str, limit: int = 25) -> tuple[str, list[dict[str, Any]]]:
+    """Return `(engine, hits)`; engine is "fts5" or "like"."""
+    query = query.strip()
+    if not query:
+        return ("fts5" if await fts_available(db) else "like", [])
+
+    if await fts_available(db):
+        match = build_match_query(query)
+        if not match:
+            return ("fts5", [])
+        try:
+            rows = (
+                await db.execute(
+                    text(
+                        "SELECT doc_id, "
+                        f"snippet(documents_fts, {_BODY_COLUMN}, '<<', '>>', '…', 14) AS snip, "
+                        "rank AS score "
+                        "FROM documents_fts WHERE documents_fts MATCH :q "
+                        "ORDER BY rank LIMIT :n"
+                    ),
+                    {"q": match, "n": limit},
+                )
+            ).fetchall()
+            return ("fts5", [{"doc_id": r[0], "snippet": r[1], "score": r[2]} for r in rows])
+        except OperationalError as exc:
+            # A malformed MATCH must degrade, never 500.
+            logger.debug("FTS query failed, falling back to LIKE: %s", exc)
+
+    like = f"%{query.lower()}%"
+    rows = (
+        await db.execute(
+            text(
+                "SELECT id, body FROM documents "
+                "WHERE lower(title) LIKE :q OR lower(body) LIKE :q "
+                "ORDER BY updated_at DESC LIMIT :n"
+            ),
+            {"q": like, "n": limit},
+        )
+    ).fetchall()
+    return ("like", [{"doc_id": r[0], "snippet": _excerpt(r[1] or "", query), "score": None} for r in rows])
+
+
+def _excerpt(body: str, query: str, width: int = 120) -> str:
+    """A LIKE-mode stand-in for snippet(): the text around the first match."""
+    at = body.lower().find(query.lower())
+    if at < 0:
+        return body[:width].strip()
+    start = max(0, at - width // 2)
+    end = min(len(body), at + len(query) + width // 2)
+    return ("…" if start else "") + body[start:end].strip() + ("…" if end < len(body) else "")

backend/app/services/doc_template.py

@@ -0,0 +1,559 @@
+"""Markdown scaffolding for documents.
+
+The header of a device document is generated **once**, when the document is
+created or migrated from the old `notes` field, and from then on it belongs to
+the user — nothing here ever rewrites a body that already exists. What keeps the
+document honest instead is `facts_snapshot`, which records the facts as they read
+at generation time so the UI can tell the user the device has moved on, and
+`render_block`, which lets them drop a freshly generated section back in from the
+editor's `/` menu whenever they want it.
+
+Every section is emitted even when its data is empty, with an italic prompt in
+place of the value. A blank section is the document telling the user what has not
+been written yet; omitting it would hide the gap.
+"""
+
+from collections.abc import Callable
+from datetime import date, datetime
+from typing import Any
+
+# Sections whose data is structural rather than descriptive: they are dropped
+# entirely rather than printed empty, because an unracked device has no rack
+# position to leave blank.
+_EMPTY = "—"
+_PROMPT = "_…_"
+
+TEMPLATE_DEVICE = "device"
+TEMPLATE_BLANK = "blank"
+TEMPLATE_RUNBOOK = "runbook"
+TEMPLATE_SERVICE = "service"
+TEMPLATE_NETWORK = "network"
+TEMPLATE_INCIDENT = "incident"
+TEMPLATE_PROCEDURE = "procedure"
+TEMPLATE_DECISION = "decision"
+TEMPLATE_ZONE = "zone"
+
+# Frontmatter carries a version from the first release: documents round-trip to
+# disk through export/import, so the on-disk shape is a compatibility surface.
+FRONTMATTER_VERSION = 1
+
+
+def cell(value: Any) -> str:
+    """Escape a value for a markdown table cell.
+
+    Mirrors `frontend/src/utils/exportMarkdown.ts`: backslash first, then pipe,
+    then collapse newlines so one field cannot break the row.
+    """
+    if value is None or value == "":
+        return _EMPTY
+    text = str(value).replace("\\", "\\\\").replace("|", "\\|")
+    return " ".join(text.split())
+
+
+def device_name(device: Any) -> str:
+    for attr in ("label", "friendly_name", "hostname", "ip"):
+        value = getattr(device, attr, None)
+        if value:
+            return str(value)
+    return "device"
+
+
+def device_type(device: Any) -> str | None:
+    return getattr(device, "type", None) or getattr(device, "suggested_type", None)
+
+
+def _fmt_date(value: Any) -> str:
+    if isinstance(value, datetime):
+        return value.date().isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    return _EMPTY
+
+
+def _sources(device: Any) -> str:
+    sources = getattr(device, "discovery_sources", None) or []
+    if not sources:
+        single = getattr(device, "discovery_source", None)
+        sources = [single] if single else []
+    return ", ".join(str(s) for s in sources) if sources else _EMPTY
+
+
+def service_key(service: dict[str, Any]) -> str:
+    """The identity used everywhere else for a service: port|protocol|name."""
+    port = service.get("port")
+    protocol = service.get("protocol") or "tcp"
+    name = (service.get("service_name") or "").lower()
+    return f"{port if port is not None else ''}|{protocol}|{name}"
+
+
+# Ports that are definitely not HTTP. Mirrors NON_HTTP_PORTS in
+# `frontend/src/utils/serviceUrl.ts` — a service link printed in a document has
+# to be the same link the canvas offers, or the document is quietly wrong.
+_NON_HTTP_PORTS = frozenset(
+    {
+        21, 23, 25, 53, 110, 143, 389, 445, 465, 514, 587, 636, 993, 995,
+        1433, 3306, 5432, 5672, 6379, 9092, 11211, 27017, 27018,
+    }
+)
+
+
+def service_url(service: dict[str, Any], host: str | None) -> str | None:
+    """The browsable URL for a service, or None when there is not one.
+
+    Follows `getServiceUrl`: everything is HTTP unless the port says otherwise,
+    a host override wins over the device's address and hides the scanned port
+    (it usually names a reverse proxy), and UDP and SSH have no browser URL.
+    """
+    override = (service.get("host") or "").strip()
+    effective_host = override or host
+    if not effective_host or service.get("protocol") == "udp":
+        return None
+
+    scheme: str | None = None
+    hostname = effective_host.split(",")[0].strip()
+    for prefix in ("https://", "http://"):
+        if hostname.startswith(prefix):
+            scheme = prefix[:-3]
+            hostname = hostname[len(prefix):].rstrip("/")
+            break
+    if not hostname:
+        return None
+
+    port = service.get("port")
+    if port == 22 or (port is not None and port in _NON_HTTP_PORTS):
+        return None
+
+    name = (service.get("service_name") or "").lower()
+    if scheme is None:
+        secure = any(token in name for token in ("https", "ssl", "tls")) or port in (443, 8443)
+        scheme = "https" if secure else "http"
+
+    # A host override points at the public name; the scanned port is internal.
+    printed_port = "" if override else (f":{port}" if port is not None else "")
+    path = (service.get("path") or "").strip()
+    if path and not path.startswith("/"):
+        path = f"/{path}"
+    return f"{scheme}://{hostname}{printed_port}{path}"
+
+
+# ── generated blocks ────────────────────────────────────────────────────────
+
+
+def block_device_info(device: Any, **_: Any) -> str:
+    check = getattr(device, "check_method", None)
+    target = getattr(device, "check_target", None)
+    check_cell = f"`{check}` → `{target}`" if check and target else (f"`{check}`" if check else _EMPTY)
+    vendor = getattr(device, "vendor", None)
+    model = getattr(device, "model", None)
+    vendor_model = " / ".join(part for part in (vendor, model) if part) or _EMPTY
+    rows = [
+        ("Type", device_type(device)),
+        ("Vendor / Model", vendor_model),
+        ("Hostname", getattr(device, "hostname", None)),
+        ("IP", getattr(device, "ip", None)),
+        ("MAC", getattr(device, "mac", None)),
+        ("IEEE", getattr(device, "ieee_address", None)),
+        ("OS", getattr(device, "os", None)),
+        ("First discovered", f"{_fmt_date(getattr(device, 'discovered_at', None))} ({_sources(device)})"),
+        ("Status check", check_cell),
+    ]
+    lines = ["| | |", "|---|---|"]
+    lines += [f"| {label} | {cell(value)} |" for label, value in rows]
+    return "\n".join(lines)
+
+
+# What the hardware table looks for in `properties`, in order of preference.
+# The scanner and the Proxmox import write these keys ("CPU Cores", "RAM",
+# "Disk"); a user typing their own is likely to reach for one of the synonyms.
+# Matched case-insensitively, so "ram" and "RAM" are the same key.
+_HARDWARE_KEYS: dict[str, tuple[str, ...]] = {
+    "cpu_model": ("cpu model", "cpu", "processor"),
+    "cpu_count": ("cpu cores", "cores", "vcpu", "vcpus", "cpu count"),
+    "ram": ("ram", "memory", "mem"),
+    "disk": ("disk", "storage", "disk size", "capacity"),
+}
+
+
+def property_map(device: Any) -> dict[str, str]:
+    """A device's properties as a lowercased key -> value lookup.
+
+    The first occurrence of a key wins, matching how the tables read: a device
+    carrying two "RAM" rows is showing the first one.
+    """
+    found: dict[str, str] = {}
+    for entry in getattr(device, "properties", None) or []:
+        if not isinstance(entry, dict):
+            continue
+        key = entry.get("key")
+        value = entry.get("value")
+        if not key or value in (None, ""):
+            continue
+        found.setdefault(str(key).strip().lower(), str(value).strip())
+    return found
+
+
+def _hardware_property(properties: dict[str, str], field: str) -> str | None:
+    for candidate in _HARDWARE_KEYS[field]:
+        if candidate in properties:
+            return properties[candidate]
+    return None
+
+
+def block_hardware(device: Any, **_: Any) -> str:
+    """CPU / RAM / Disk, read from `properties` first.
+
+    The `cpu_count` / `cpu_model` / `ram_gb` / `disk_gb` columns are barely
+    written any more — the scanner, the Proxmox import and the inventory modal
+    all put hardware in `properties` instead — so a document generated from the
+    columns alone printed an empty table beside a properties table listing the
+    very same facts. Properties win; the columns are the fallback for a row that
+    still carries them.
+
+    A property value is taken verbatim: it is already formatted the way the user
+    or the importer wrote it ("15.5 GB"), and guessing a unit onto a bare number
+    would be inventing a fact.
+    """
+    properties = property_map(device)
+
+    cpu_model = _hardware_property(properties, "cpu_model") or getattr(device, "cpu_model", None)
+    cpu_count = _hardware_property(properties, "cpu_count") or getattr(device, "cpu_count", None)
+    if cpu_model and cpu_count:
+        cpu: Any = f"{cpu_model} ×{cpu_count}"
+    else:
+        cpu = cpu_model or (f"{cpu_count} cores" if cpu_count else None)
+
+    ram_gb = getattr(device, "ram_gb", None)
+    ram = _hardware_property(properties, "ram") or (f"{ram_gb:g} GB" if ram_gb else None)
+    disk_gb = getattr(device, "disk_gb", None)
+    disk = _hardware_property(properties, "disk") or (f"{disk_gb:g} GB" if disk_gb else None)
+
+    return "\n".join(
+        [
+            "| CPU | RAM | Disk |",
+            "|---|---|---|",
+            f"| {cell(cpu)} | {cell(ram)} | {cell(disk)} |",
+        ]
+    )
+
+
+def block_services(device: Any, **_: Any) -> str:
+    services = getattr(device, "services", None) or []
+    if not services:
+        return "_No service has been fingerprinted on this device yet._"
+    host = getattr(device, "ip", None) or getattr(device, "hostname", None)
+    sections: list[str] = []
+    for service in services:
+        if not isinstance(service, dict):
+            continue
+        name = service.get("service_name") or "Service"
+        port = service.get("port")
+        protocol = service.get("protocol") or "tcp"
+        heading = f"### {name}" + (f" — `{port}/{protocol}`" if port else "")
+        lines = [heading, ""]
+        url = service_url(service, host)
+        if url:
+            lines.append(f"- **URL** — <{url}>")
+        if service.get("category"):
+            lines.append(f"- **Category** — {service['category']}")
+        lines += [
+            f"- **Purpose** — {_PROMPT}",
+            f"- **Credentials** — {_PROMPT} _(where they are kept — never the secret itself)_",
+            f"- **Depends on** — {_PROMPT}",
+        ]
+        sections.append("\n".join(lines))
+    return "\n\n".join(sections)
+
+
+def block_properties(device: Any, **_: Any) -> str:
+    properties = getattr(device, "properties", None) or []
+    rows = [p for p in properties if isinstance(p, dict) and p.get("key")]
+    if not rows:
+        return ""
+    lines = ["| Key | Value |", "|---|---|"]
+    lines += [f"| {cell(p.get('key'))} | {cell(p.get('value'))} |" for p in rows]
+    return "\n".join(lines)
+
+
+def block_rack(device: Any, *, rack: dict[str, Any] | None = None, zone_label: str | None = None, **_: Any) -> str:
+    parts: list[str] = []
+    if rack and rack.get("name"):
+        u_start = rack.get("u_start")
+        u_height = rack.get("u_height") or 1
+        span = rack.get("col_span")
+        where = f"Rack **{rack['name']}**"
+        if u_start:
+            top = u_start + u_height - 1
+            where += f", U{u_start}" + (f"–U{top}" if top != u_start else "")
+        if span:
+            where += ", full width" if span >= 12 else f", {span}/12 wide"
+        parts.append(where + ".")
+    if zone_label:
+        parts.append(f"Zone **{zone_label}**.")
+    return " ".join(parts)
+
+
+def block_network(device: Any, *, connections: list[str] | None = None, **_: Any) -> str:
+    ip = getattr(device, "ip", None)
+    subnet = _guess_subnet(ip)
+    peers = ", ".join(f"`{peer}`" for peer in connections) if connections else _PROMPT
+    return "\n".join(
+        [
+            f"- **Subnet / VLAN** — {subnet or _PROMPT}",
+            f"- **Connected to** — {peers}",
+            f"- **DNS names** — {_PROMPT}",
+            f"- **Firewall / exposure** — {_PROMPT}",
+            f"- **Reverse proxy** — {_PROMPT}",
+        ]
+    )
+
+
+def _guess_subnet(ip: str | None) -> str | None:
+    """The /24 an IPv4 address sits in. Multi-IP fields keep the first token."""
+    if not ip:
+        return None
+    first = ip.split(",")[0].strip()
+    octets = first.split(".")
+    if len(octets) != 4 or not all(o.isdigit() for o in octets):
+        return None
+    return f"{octets[0]}.{octets[1]}.{octets[2]}.0/24"
+
+
+BLOCKS: dict[str, Callable[..., str]] = {
+    "device-info": block_device_info,
+    "hardware": block_hardware,
+    "services": block_services,
+    "properties": block_properties,
+    "rack": block_rack,
+    "network": block_network,
+}
+
+
+def render_block(name: str, device: Any, **context: Any) -> str:
+    render = BLOCKS.get(name)
+    if render is None:
+        raise ValueError(f"Unknown block: {name}")
+    return render(device, **context)
+
+
+# ── the device document ─────────────────────────────────────────────────────
+
+
+def facts_snapshot(device: Any) -> dict[str, Any]:
+    """The device facts a generated document depends on.
+
+    Compared against the live row to tell the user their document has drifted,
+    so it holds the fields the template actually prints and nothing else.
+    """
+    services = getattr(device, "services", None) or []
+    return {
+        "label": device_name(device),
+        "type": device_type(device),
+        "hostname": getattr(device, "hostname", None),
+        "ip": getattr(device, "ip", None),
+        "mac": getattr(device, "mac", None),
+        "ieee_address": getattr(device, "ieee_address", None),
+        "os": getattr(device, "os", None),
+        "vendor": getattr(device, "vendor", None),
+        "model": getattr(device, "model", None),
+        "cpu_count": getattr(device, "cpu_count", None),
+        "cpu_model": getattr(device, "cpu_model", None),
+        "ram_gb": getattr(device, "ram_gb", None),
+        "disk_gb": getattr(device, "disk_gb", None),
+        # The properties table prints these, and the hardware table now reads
+        # CPU / RAM / Disk out of them — so an edit to one is a real change to
+        # what the document says. A plain dict, because the snapshot is compared
+        # against its own JSON round-trip and a tuple would come back a list.
+        "properties": {
+            str(entry["key"]): str(entry.get("value") or "")
+            for entry in reversed(getattr(device, "properties", None) or [])
+            if isinstance(entry, dict) and entry.get("key")
+        },
+        "check_method": getattr(device, "check_method", None),
+        "check_target": getattr(device, "check_target", None),
+        "services": sorted(service_key(s) for s in services if isinstance(s, dict)),
+    }
+
+
+def render_frontmatter(values: dict[str, Any]) -> str:
+    """A minimal YAML block.
+
+    Hand-rolled rather than `yaml.safe_dump` so key order is the order written
+    here — the frontmatter is read by humans at the top of every document.
+
+    An empty list still prints. `tags: []` is the only advertisement tags have:
+    dropped, the key never appears in any document and nobody learns it exists.
+    An empty string is still dropped — `owner:` teaches nothing a reader of the
+    template does not already see.
+    """
+    lines = ["---"]
+    for key, value in values.items():
+        if value is None or value == "":
+            continue
+        if isinstance(value, list):
+            lines.append(f"{key}: [{', '.join(str(v) for v in value)}]")
+        else:
+            lines.append(f"{key}: {value}")
+    lines.append("---")
+    return "\n".join(lines)
+
+
+def render_device_document(
+    device: Any,
+    *,
+    zone_label: str | None = None,
+    rack: dict[str, Any] | None = None,
+    connections: list[str] | None = None,
+    today: date | None = None,
+) -> str:
+    """The full skeleton for a device, old notes appended verbatim."""
+    today = today or date.today()
+    name = device_name(device)
+    notes = (getattr(device, "notes", None) or "").strip()
+
+    front = render_frontmatter(
+        {
+            "homelable": FRONTMATTER_VERSION,
+            "title": name,
+            "device": getattr(device, "id", None),
+            "type": device_type(device),
+            "tags": [],
+            "criticality": "medium",
+            "owner": "",
+            "review_every": "6m",
+            "created": today.isoformat(),
+        }
+    )
+
+    parts = [
+        front,
+        "",
+        f"# {name}",
+        "",
+        "> _One line: what this device is for. Replace this quote._",
+        "",
+        "## Device Information",
+        "",
+        block_device_info(device),
+        "",
+        "### Hardware",
+        "",
+        block_hardware(device),
+        "",
+    ]
+
+    location = block_rack(device, rack=rack, zone_label=zone_label)
+    if location:
+        parts += ["### Physical location", "", location, ""]
+
+    properties = block_properties(device)
+    if properties:
+        parts += ["### Properties", "", properties, ""]
+
+    parts += [
+        "## Services",
+        "",
+        block_services(device),
+        "",
+        "## Network",
+        "",
+        block_network(device, connections=connections),
+        "",
+        "## Configuration",
+        "",
+        "_How it is set up, where the config lives, what is not default, and what",
+        "would be needed to rebuild it from scratch._",
+        "",
+        "## Operations",
+        "",
+        "### Start / stop",
+        "",
+        _PROMPT,
+        "",
+        "### Backup",
+        "",
+        _PROMPT,
+        "",
+        "### Update procedure",
+        "",
+        _PROMPT,
+        "",
+        "### Monitoring and alerts",
+        "",
+        _PROMPT,
+        "",
+        "## Troubleshooting",
+        "",
+        "| Symptom | Likely cause | Fix |",
+        "|---|---|---|",
+        f"| {_PROMPT} | {_PROMPT} | {_PROMPT} |",
+        "",
+        "## Dependencies",
+        "",
+        f"- **Depends on** — {_PROMPT}",
+        f"- **Used by** — {_PROMPT}",
+        "",
+        "## Changelog",
+        "",
+        "| Date | Change |",
+        "|---|---|",
+        f"| {today.isoformat()} | Document created |",
+        "",
+        "## Notes",
+        "",
+    ]
+
+    if notes:
+        parts += [
+            f"<!-- Migrated verbatim from this device's Notes field on {today.isoformat()}. -->",
+            "",
+            notes,
+            "",
+        ]
+    else:
+        parts += ["_Anything worth remembering about this device._", ""]
+
+    return "\n".join(parts)
+
+
+# ── library templates ───────────────────────────────────────────────────────
+
+_LIBRARY_TEMPLATES: dict[str, tuple[str, list[str]]] = {
+    TEMPLATE_BLANK: ("", []),
+    TEMPLATE_RUNBOOK: (
+        "runbook",
+        ["Trigger", "Preconditions", "Steps", "Verification", "Rollback", "Escalation"],
+    ),
+    TEMPLATE_SERVICE: (
+        "service",
+        ["What it does", "Endpoints", "Components", "Configuration", "Backup", "Failure modes"],
+    ),
+    TEMPLATE_NETWORK: (
+        "network",
+        ["Topology", "Subnets and VLANs", "DHCP and DNS", "Routing", "Firewall zones", "Remote access"],
+    ),
+    TEMPLATE_INCIDENT: ("incident", ["Timeline", "Impact", "Root cause", "Fix", "What to change"]),
+    TEMPLATE_PROCEDURE: ("procedure", ["Goal", "Prerequisites", "Steps", "Verification"]),
+    TEMPLATE_DECISION: ("decision", ["Status", "Context", "Decision", "Consequences"]),
+    TEMPLATE_ZONE: ("zone", ["Purpose", "Members", "Addressing", "Access", "Notes"]),
+}
+
+TEMPLATE_IDS = frozenset({TEMPLATE_DEVICE, *_LIBRARY_TEMPLATES})
+
+
+def render_library_document(template_id: str, title: str, *, today: date | None = None) -> str:
+    """The skeleton for a page that is not about one device."""
+    today = today or date.today()
+    kind, headings = _LIBRARY_TEMPLATES.get(template_id, _LIBRARY_TEMPLATES[TEMPLATE_BLANK])
+    front = render_frontmatter(
+        {
+            "homelable": FRONTMATTER_VERSION,
+            "title": title,
+            "template": kind or None,
+            "tags": [],
+            "created": today.isoformat(),
+        }
+    )
+    parts = [front, "", f"# {title}", ""]
+    for heading in headings:
+        parts += [f"## {heading}", "", _PROMPT, ""]
+    return "\n".join(parts)

backend/app/services/doc_tree.py

@@ -0,0 +1,137 @@
+"""Placement and parsing helpers for documents.
+
+The Library is a real tree — a folder is a document with `kind='folder'`, so an
+empty folder exists and a folder can carry an index body. That makes three
+things this module owns: slugs that stay unique among siblings, a re-parent
+guard so the tree cannot be knotted into a cycle, and the subtree walk that
+`DELETE` needs because SQLite does not always enforce `ON DELETE CASCADE`
+(`api/routes/designs.py` unwinds its own deletes for the same reason).
+
+It also parses the YAML frontmatter out of a body. The body is the source of
+truth — it is what exports to disk — and `documents.frontmatter` / `documents.tags`
+are only a cache so a listing can filter without reading every body.
+"""
+
+import re
+from typing import Any
+
+import yaml
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import Document
+
+# A document is addressed by id; the slug is for readable URLs and export
+# filenames, so it only has to be filesystem- and URL-safe.
+_SLUG_STRIP = re.compile(r"[^a-z0-9]+")
+# `[ \t]*`, not `\s*`: `\s` matches the newline the fence line ends with, and an
+# alternative that can be reached two ways makes the match quadratic on a body
+# that opens with `---` and never closes it — the shape a half-typed document
+# has for as long as the user is typing it.
+_FRONTMATTER = re.compile(r"\A---[ \t]*\n(.*?)\n---[ \t]*(?:\n|\Z)", re.DOTALL)
+
+DOCUMENT_KINDS = frozenset({"device", "node", "design", "page", "folder"})
+
+# Kinds that live in the Library tree and may therefore carry a parent.
+TREE_KINDS = frozenset({"page", "folder"})
+
+REVISION_LIMIT = 50
+
+
+def slugify(title: str) -> str:
+    slug = _SLUG_STRIP.sub("-", (title or "").strip().lower()).strip("-")
+    return slug[:80] or "untitled"
+
+
+async def unique_slug(db: AsyncSession, title: str, *, parent_id: str | None, exclude_id: str | None = None) -> str:
+    """A slug no sibling is already using."""
+    base = slugify(title)
+    sibling = Document.parent_id.is_(None) if parent_id is None else Document.parent_id == parent_id
+    query = select(Document.slug).where(sibling)
+    if exclude_id is not None:
+        query = query.where(Document.id != exclude_id)
+    taken = {row for row in (await db.execute(query)).scalars().all()}
+    if base not in taken:
+        return base
+    suffix = 2
+    while f"{base}-{suffix}" in taken:
+        suffix += 1
+    return f"{base}-{suffix}"
+
+
+def parse_frontmatter(body: str) -> dict[str, Any]:
+    """The YAML block at the top of a body, or `{}`.
+
+    Malformed YAML is not an error the user should be blocked by — they are
+    mid-edit. The cache simply stays empty until the block parses again.
+    """
+    match = _FRONTMATTER.match(body or "")
+    if not match:
+        return {}
+    try:
+        parsed = yaml.safe_load(match.group(1))
+    except yaml.YAMLError:
+        return {}
+    if not isinstance(parsed, dict):
+        return {}
+    return {str(key): _jsonable(value) for key, value in parsed.items()}
+
+
+def _jsonable(value: Any) -> Any:
+    """Coerce a parsed YAML value into something the JSON column can hold.
+
+    YAML resolves `created: 2026-09-05` to a `date` and `at: 10:30` to an int,
+    neither of which survives `json.dumps`. The cache is only ever read back for
+    filtering and display, so a string is the right shape — the body keeps the
+    literal the user typed either way.
+    """
+    if isinstance(value, str | int | float | bool) or value is None:
+        return value
+    if isinstance(value, list):
+        return [_jsonable(item) for item in value]
+    if isinstance(value, dict):
+        return {str(key): _jsonable(item) for key, item in value.items()}
+    return str(value)
+
+
+def tags_from(frontmatter: dict[str, Any]) -> list[str]:
+    raw = frontmatter.get("tags")
+    if isinstance(raw, str):
+        raw = [part.strip() for part in raw.split(",")]
+    if not isinstance(raw, list):
+        return []
+    return [str(tag).strip() for tag in raw if str(tag).strip()]
+
+
+async def is_ancestor(db: AsyncSession, candidate_id: str, of_id: str) -> bool:
+    """Whether `candidate_id` is `of_id` or sits above it.
+
+    Guards re-parenting: moving a folder inside its own subtree would orphan
+    everything under it. Mirrors the `_is_ancestor` guard the MCP zone tools use.
+    """
+    if candidate_id == of_id:
+        return True
+    seen: set[str] = set()
+    current: str | None = of_id
+    while current and current not in seen:
+        seen.add(current)
+        current = (await db.execute(select(Document.parent_id).where(Document.id == current))).scalar_one_or_none()
+        if current == candidate_id:
+            return True
+    return False
+
+
+async def subtree_ids(db: AsyncSession, root_id: str) -> list[str]:
+    """`root_id` plus every document beneath it, deepest last."""
+    collected = [root_id]
+    frontier = [root_id]
+    while frontier:
+        children = (
+            await db.execute(select(Document.id).where(Document.parent_id.in_(frontier)))
+        ).scalars().all()
+        children = [child for child in children if child not in collected]
+        if not children:
+            break
+        collected.extend(children)
+        frontier = children
+    return collected

backend/app/services/fingerprint.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from typing import Any
 
 _SIGNATURES: list[dict[str, Any]] | None = None
+_OUI_MAP: dict[str, str] | None = None
 _LOCK = threading.Lock()
 
 
@@ -26,25 +27,124 @@ def _load() -> list[dict[str, Any]]:
     return _SIGNATURES
 
 
-def match_port(port: int, protocol: str, banner: str | None = None) -> dict[str, Any] | None:
-    """Return the first signature matching port+protocol, optionally banner."""
-    for sig in _load():
-        if sig["port"] != port or sig["protocol"] != protocol:
-            continue
-        if sig.get("banner_regex") and (not banner or not re.search(sig["banner_regex"], banner, re.IGNORECASE)):
-            continue
-        return sig
-    return None
+def _load_oui() -> dict[str, str]:
+    """Load OUI database and flatten to {prefix: node_type}."""
+    global _OUI_MAP
+    if _OUI_MAP is None:
+        with _LOCK:
+            if _OUI_MAP is None:
+                path = Path(__file__).parent.parent / "data" / "oui_database.json"
+                try:
+                    with open(path) as f:
+                        entries = json.load(f)
+                except FileNotFoundError as err:
+                    raise FileNotFoundError(
+                        f"oui_database.json not found at {path}. "
+                        "This file should be bundled with the application."
+                    ) from err
+                _OUI_MAP = {
+                    prefix.lower(): entry["type"]
+                    for entry in entries
+                    for prefix in entry["prefixes"]
+                }
+    return _OUI_MAP
 
 
-def fingerprint_ports(open_ports: list[dict[str, Any]]) -> list[dict[str, Any]]:
+def _http_regex_hit(sig: dict[str, Any], http_signals: dict[str, Any] | None) -> bool:
+    """True when the signature's http_regex matches the probe's title/headers."""
+    rx = sig.get("http_regex")
+    if not rx or not http_signals:
+        return False
+    headers = http_signals.get("headers") or {}
+    haystack = " ".join(
+        s for s in (
+            http_signals.get("title"),
+            headers.get("Server"),
+            headers.get("X-Powered-By"),
+        ) if s
+    )
+    return bool(haystack and re.search(rx, haystack, re.IGNORECASE))
+
+
+def _service_tier(
+    sig: dict[str, Any],
+    port: int,
+    protocol: str,
+    banner: str | None,
+    http_signals: dict[str, Any] | None,
+) -> int | None:
     """
-    Given a list of {port, protocol, banner?} dicts, return matched services.
-    Unknown ports are included as unknown_service.
+    Rank how well a signature matches (lower = stronger). None = not a match.
+
+    Tier 1: port match + http_regex confirmed
+    Tier 2: port match + banner_regex confirmed
+    Tier 3: port-agnostic (port: null) + http_regex confirmed
+    Tier 4: port match only (no regex, or http_regex with probe disabled)
+
+    When http_signals is None (probe not run) an http_regex entry degrades to
+    a port-only match — identical to pre-probe behaviour, no regression.
+    When http_signals is provided, http_regex is strict: a miss disqualifies.
+    """
+    probe_ran = http_signals is not None
+    has_http = bool(sig.get("http_regex"))
+
+    # Port-agnostic entries (port: null) match purely on HTTP signals.
+    if sig.get("port") is None:
+        if has_http and _http_regex_hit(sig, http_signals):
+            return 3
+        return None
+
+    if sig["port"] != port or sig["protocol"] != protocol:
+        return None
+
+    # http_regex is authoritative once a probe has run.
+    if has_http and probe_ran:
+        return 1 if _http_regex_hit(sig, http_signals) else None
+
+    if sig.get("banner_regex"):
+        if banner and re.search(sig["banner_regex"], banner, re.IGNORECASE):
+            return 2
+        return None
+
+    # No regex constraint (or http_regex but probe disabled) → port-only guess.
+    return 4
+
+
+def match_service(
+    port: int,
+    protocol: str,
+    banner: str | None = None,
+    http_signals: dict[str, Any] | None = None,
+) -> dict[str, Any] | None:
+    """Return the best signature for a port, walking tiers most-specific first."""
+    best: dict[str, Any] | None = None
+    best_tier = 99
+    for sig in _load():
+        tier = _service_tier(sig, port, protocol, banner, http_signals)
+        if tier is not None and tier < best_tier:
+            best, best_tier = sig, tier
+            if best_tier == 1:
+                break  # strongest possible — stop early
+    return best
+
+
+def match_port(port: int, protocol: str, banner: str | None = None) -> dict[str, Any] | None:
+    """Back-compat alias: match without HTTP-probe signals."""
+    return match_service(port, protocol, banner)
+
+
+def fingerprint_ports(
+    open_ports: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """
+    Given a list of {port, protocol, banner?, http_signals?} dicts, return
+    matched services. Unknown ports are included as unknown_service.
     """
     results = []
     for p in open_ports:
-        sig = match_port(p["port"], p.get("protocol", "tcp"), p.get("banner"))
+        sig = match_service(
+            p["port"], p.get("protocol", "tcp"), p.get("banner"), p.get("http_signals")
+        )
         if sig:
             results.append({
                 "port": p["port"],
@@ -65,55 +165,12 @@ def fingerprint_ports(open_ports: list[dict[str, Any]]) -> list[dict[str, Any]]:
     return results
 
 
-# Known OUI prefixes — lowercase, colon-separated, first 3 octets
-_MAC_OUI_TYPES: dict[str, str] = {
-    # Hypervisors / VMs
-    "52:54:00": "vm",    # QEMU/KVM (Proxmox VMs)
-    "bc:24:11": "vm",    # Proxmox official OUI (VMs and LXC, 7.3+)
-    "00:50:56": "vm",    # VMware
-    "00:0c:29": "vm",    # VMware Workstation / Fusion
-    "08:00:27": "vm",    # VirtualBox
-    "00:15:5d": "vm",    # Hyper-V
-    # Shelly
-    "34:94:54": "iot",
-    "84:f3:eb": "iot",
-    "ec:fa:bc": "iot",
-    "30:c6:f7": "iot",
-    # Espressif (ESP8266 / ESP32 — used by Sonoff, many DIY IoT)
-    "a0:20:a6": "iot",
-    "24:62:ab": "iot",
-    "30:ae:a4": "iot",
-    "cc:50:e3": "iot",
-    "ac:67:b2": "iot",
-    "b4:e6:2d": "iot",
-    "3c:71:bf": "iot",
-    "8c:aa:b5": "iot",
-    # Sonoff / ITEAD
-    "dc:4f:22": "iot",
-    "e8:db:84": "iot",
-    # Tapo / TP-Link smart home
-    "b0:a7:b9": "iot",
-    "50:c7:bf": "iot",
-    "1c:3b:f3": "iot",
-    "10:27:f5": "iot",
-    # Philips Hue
-    "00:17:88": "iot",
-    "ec:b5:fa": "iot",
-    # IKEA Tradfri
-    "34:13:e8": "iot",
-    "00:21:2e": "iot",
-    # Tuya / Smart Life (widely used chip in many brands)
-    "d8:f1:5b": "iot",
-    "68:57:2d": "iot",
-}
-
-
 def suggest_type_from_mac(mac: str | None) -> str | None:
     """Return a suggested node type from MAC OUI, or None if unknown."""
     if not mac:
         return None
     prefix = mac.lower()[:8]
-    return _MAC_OUI_TYPES.get(prefix)
+    return _load_oui().get(prefix)
 
 
 _PORT_TYPE_HINTS: dict[int, str] = {
@@ -156,12 +213,16 @@ def suggest_node_type(open_ports: list[dict[str, Any]], mac: str | None = None)
     if mac_type == "iot":
         return "iot"
 
-    priority = ["proxmox", "nas", "router", "lxc", "vm", "ap", "camera", "iot", "server", "switch"]
+    priority = [
+        "proxmox", "nas", "kvm", "router", "lxc", "vm", "ap", "camera", "iot", "server", "switch",
+    ]
     found: set[str] = set()
     for p in open_ports:
         port = p["port"]
         proto = p.get("protocol", "tcp")
-        sig = match_port(port, proto)
+        # Pass the HTTP-probe signals through: port-agnostic signatures (port: null,
+        # e.g. PiKVM, Unraid) match on title/headers alone and are invisible otherwise.
+        sig = match_service(port, proto, p.get("banner"), p.get("http_signals"))
         if sig and sig.get("suggested_node_type"):
             found.add(sig["suggested_node_type"])
         if port in _PORT_TYPE_HINTS:

backend/app/services/http_probe.py

@@ -0,0 +1,115 @@
+"""HTTP probe: GET a discovered port and extract identifying signals.
+
+Used by the optional deep-scan mode to confirm what service sits behind an
+open port, regardless of port number. Returns the page <title> plus a small
+set of identifying response headers, which fingerprint.match_service() then
+matches against signature http_regex fields.
+"""
+import asyncio
+import logging
+import re
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Headers that commonly carry the application name.
+_SIGNAL_HEADERS = ("Server", "X-Powered-By")
+# Cap how much body we read when hunting for <title>. This is a cap on the
+# download itself, not just on what we scan: the body is streamed and the
+# connection dropped once we hold this much. Some endpoints stream without end
+# and send no Content-Length (bandwidth-test endpoints, MJPEG cameras), so
+# buffering a full response would OOM the backend.
+_MAX_BODY_BYTES = 64 * 1024
+_TITLE_RE = re.compile(r"<title[^>]*>(.*?)</title>", re.IGNORECASE | re.DOTALL)
+_PROBE_TIMEOUT = 3.0
+# Ports we never bother probing over HTTP (not web services).
+#
+# 515 and 9100-9107 are raw printing (LPD / JetDirect). Those are not merely
+# uninteresting: a printer takes whatever bytes land on 9100 as a print job, so
+# a GET line makes it spit out a page of plaintext. Never send them anything.
+# nmap already ships `Exclude T:9100-9107` for the same reason, which is why
+# the -sV pass never triggered this — only our own probe did.
+_PRINTER_PORTS = frozenset({515, *range(9100, 9108)})
+_NON_HTTP_PORTS = frozenset({
+    22, 21, 23, 25, 53, 110, 143, 161, 162, 179, 445, 3306, 5432, 6379,
+}) | _PRINTER_PORTS
+
+
+async def _read_capped(resp: httpx.Response) -> str:
+    """Read at most _MAX_BODY_BYTES of a streaming response, then stop."""
+    chunks: list[bytes] = []
+    size = 0
+    async for chunk in resp.aiter_bytes():
+        chunks.append(chunk)
+        size += len(chunk)
+        if size >= _MAX_BODY_BYTES:
+            break
+    raw = b"".join(chunks)[:_MAX_BODY_BYTES]
+    encoding = resp.charset_encoding or "utf-8"
+    try:
+        return raw.decode(encoding, errors="replace")
+    except LookupError:
+        return raw.decode("utf-8", errors="replace")
+
+
+def _extract_title(body: str) -> str | None:
+    m = _TITLE_RE.search(body)
+    if not m:
+        return None
+    title = re.sub(r"\s+", " ", m.group(1)).strip()
+    return title or None
+
+
+async def _probe_scheme(client: httpx.AsyncClient, url: str) -> dict[str, Any] | None:
+    try:
+        async with client.stream("GET", url, follow_redirects=True) as resp:
+            headers = {h: resp.headers[h] for h in _SIGNAL_HEADERS if h in resp.headers}
+            body = await _read_capped(resp)
+    except (httpx.HTTPError, OSError):
+        return None
+    title = _extract_title(body)
+    if not title and not headers:
+        return None
+    return {"title": title, "headers": headers}
+
+
+async def probe_port(
+    ip: str, port: int, verify_tls: bool = False
+) -> dict[str, Any] | None:
+    """
+    GET https:// then http:// for a port and return {title, headers} or None.
+
+    None means the port did not answer HTTP or yielded no usable signal.
+    """
+    if port in _NON_HTTP_PORTS:
+        return None
+    async with httpx.AsyncClient(verify=verify_tls, timeout=_PROBE_TIMEOUT) as client:
+        for scheme in ("https", "http"):
+            result = await _probe_scheme(client, f"{scheme}://{ip}:{port}/")
+            if result is not None:
+                return result
+    return None
+
+
+async def probe_open_ports(
+    ip: str,
+    open_ports: list[dict[str, Any]],
+    verify_tls: bool = False,
+    concurrency: int = 50,
+) -> list[dict[str, Any]]:
+    """
+    Probe every open port for HTTP signals (option 2: probe all, match after).
+
+    Returns the same port dicts, each enriched with an http_signals key
+    (None when the port gave no HTTP signal).
+    """
+    sem = asyncio.Semaphore(concurrency)
+
+    async def _one(p: dict[str, Any]) -> dict[str, Any]:
+        async with sem:
+            signals = await probe_port(ip, p["port"], verify_tls)
+        return {**p, "http_signals": signals}
+
+    return await asyncio.gather(*(_one(p) for p in open_ports))

backend/app/services/import_jobs.py

@@ -0,0 +1,92 @@
+"""In-process registry for long-running import jobs that return a payload.
+
+Pending imports already run in the background and report through ``scan_runs``.
+Canvas imports are different: the caller wants the fetched map *back* so it can
+drop it on the canvas, which kept the request open for the whole MQTT
+round-trip. On a large mesh that outlives any reverse proxy's read timeout
+(Cloudflare cuts at 100 s and returns a 524), so the browser never sees the
+result even though the fetch succeeded server-side.
+
+The fix is to hand the client a job id immediately and let it poll. Results are
+transient — a canvas import is meaningless once the user has closed the modal —
+so they live in memory rather than the DB, and expire on a TTL. The backend runs
+a single uvicorn worker, the same assumption the scheduler and ``BackgroundTasks``
+already make.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+JobStatus = Literal["running", "done", "error"]
+
+# How long a finished job stays readable. Long enough for a client that polls
+# slowly or reloads mid-import, short enough that a forgotten map is not held
+# for the life of the process.
+JOB_TTL_SECONDS = 900.0
+
+
+@dataclass
+class ImportJob:
+    id: str
+    status: JobStatus = "running"
+    result: dict[str, Any] | None = None
+    error: str | None = None
+    # HTTP status the synchronous route would have raised, so the client can
+    # keep reacting to failures the way it always has.
+    error_status: int | None = None
+    created_at: float = field(default_factory=time.monotonic)
+    finished_at: float | None = None
+
+
+_jobs: dict[str, ImportJob] = {}
+
+
+def _purge_expired(now: float) -> None:
+    for job_id, job in list(_jobs.items()):
+        if job.finished_at is not None and now - job.finished_at > JOB_TTL_SECONDS:
+            del _jobs[job_id]
+
+
+def create_job() -> ImportJob:
+    """Register a new running job and return it."""
+    now = time.monotonic()
+    _purge_expired(now)
+    job = ImportJob(id=str(uuid.uuid4()))
+    _jobs[job.id] = job
+    return job
+
+
+def get_job(job_id: str) -> ImportJob | None:
+    """Return a job, or None if it never existed or has expired."""
+    _purge_expired(time.monotonic())
+    return _jobs.get(job_id)
+
+
+def finish_job(job_id: str, result: dict[str, Any]) -> None:
+    """Mark a job done and attach its payload. No-op if it expired."""
+    job = _jobs.get(job_id)
+    if job is None:
+        return
+    job.status = "done"
+    job.result = result
+    job.finished_at = time.monotonic()
+
+
+def fail_job(job_id: str, error: str, status: int) -> None:
+    """Mark a job failed with a client-safe message. No-op if it expired."""
+    job = _jobs.get(job_id)
+    if job is None:
+        return
+    job.status = "error"
+    job.error = error
+    job.error_status = status
+    job.finished_at = time.monotonic()
+
+
+def reset_jobs() -> None:
+    """Drop every job. For tests."""
+    _jobs.clear()

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/mqtt_common.py

@@ -0,0 +1,187 @@
+"""Shared MQTT helpers for the Zigbee and Z-Wave import services.
+
+Holds the credential-safe error sanitizer, the TLS context builder, and a
+generic request/response round-trip over MQTT used by gateway-style APIs
+(publish a request topic, wait for a single response topic message).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import ssl
+from typing import Any
+
+from app.core.config import settings
+
+logger = logging.getLogger(__name__)
+
+try:
+    import aiomqtt
+except ImportError:  # pragma: no cover
+    aiomqtt = None  # type: ignore[assignment]
+
+_CONNECTION_TIMEOUT = 5.0   # seconds to verify broker reachability
+# Fallback wait for a gateway response. The effective value comes from
+# ``settings.mqtt_response_timeout`` (env MQTT_RESPONSE_TIMEOUT), read at call
+# time so an operator with a large mesh can raise it without a code change.
+_RESPONSE_TIMEOUT = 300.0
+
+
+def _sanitize_mqtt_error(exc: BaseException) -> str:
+    """Return a generic, credential-free message for an MQTT error.
+
+    The raw aiomqtt/paho error string can include the broker URI with
+    embedded credentials (e.g. ``mqtt://user:pass@host``) or auth-related
+    detail that should not leak to API clients. Map known patterns to
+    coarse categories; default to a generic failure message. The original
+    exception is logged at WARNING level for operator debugging.
+    """
+    logger.warning("MQTT error (sanitized for client): %r", exc)
+    raw = str(exc).lower()
+    if "not authoriz" in raw or "bad user" in raw or "bad username" in raw:
+        return "Authentication failed"
+    if "refused" in raw:
+        return "Connection refused by broker"
+    if "name or service not known" in raw or "getaddrinfo" in raw or "nodename nor servname" in raw:
+        return "Broker hostname could not be resolved"
+    if "ssl" in raw or "tls" in raw or "certificate" in raw:
+        return "TLS handshake failed"
+    if "timed out" in raw or "timeout" in raw:
+        return "Connection to broker timed out"
+    return "MQTT connection failed"
+
+
+def _build_tls_context(insecure: bool) -> ssl.SSLContext:
+    """Build an SSL context for MQTT TLS. If insecure, skip verification."""
+    ctx = ssl.create_default_context()
+    if insecure:
+        logger.warning(
+            "MQTT TLS certificate verification is DISABLED — "
+            "use only with self-signed brokers on trusted networks."
+        )
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+    return ctx
+
+
+async def request_response(
+    mqtt_host: str,
+    mqtt_port: int,
+    request_topic: str,
+    response_topic: str,
+    request_payload: dict[str, Any],
+    username: str | None = None,
+    password: str | None = None,
+    tls: bool = False,
+    tls_insecure: bool = False,
+    response_timeout: float | None = None,
+) -> dict[str, Any]:
+    """Publish ``request_payload`` to ``request_topic`` and return the first
+    JSON message received on ``response_topic`` as a dict.
+
+    ``response_timeout`` defaults to ``settings.mqtt_response_timeout``
+    (env ``MQTT_RESPONSE_TIMEOUT``, 300 s) — a large mesh can take minutes.
+
+    Raises:
+        ImportError: if aiomqtt is not installed.
+        TimeoutError: if no response arrives in time.
+        ConnectionError: if the broker cannot be reached.
+        ValueError: if the response payload is not valid JSON / is empty.
+    """
+    if aiomqtt is None:  # pragma: no cover
+        raise ImportError(
+            "aiomqtt is required for MQTT import. "
+            "Install it with: pip install aiomqtt"
+        )
+
+    timeout = (
+        float(settings.mqtt_response_timeout)
+        if response_timeout is None
+        else response_timeout
+    )
+    if timeout <= 0:
+        timeout = _RESPONSE_TIMEOUT
+
+    response_payload: dict[str, Any] = {}
+    tls_context = _build_tls_context(tls_insecure) if tls else None
+
+    try:
+        async with aiomqtt.Client(
+            hostname=mqtt_host,
+            port=mqtt_port,
+            username=username,
+            password=password,
+            timeout=_CONNECTION_TIMEOUT,
+            tls_context=tls_context,
+        ) as client:
+            await client.subscribe(response_topic)
+            # Give the broker a brief window to register the subscription
+            # before we publish the request. Without this, brokers that
+            # race SUBACK with our PUBLISH may deliver the response before
+            # the subscription is active and we'd hang until timeout.
+            await asyncio.sleep(0.1)
+            await client.publish(request_topic, json.dumps(request_payload))
+
+            async def _wait_for_response() -> None:
+                async for message in client.messages:
+                    if str(message.topic) != response_topic:
+                        continue
+                    raw = message.payload
+                    try:
+                        payload_str = (
+                            raw.decode() if isinstance(raw, bytes | bytearray) else str(raw)
+                        )
+                        response_payload.update(json.loads(payload_str))
+                    except (json.JSONDecodeError, TypeError) as exc:
+                        raise ValueError(f"Malformed MQTT response: {exc}") from exc
+                    return
+
+            await asyncio.wait_for(_wait_for_response(), timeout=timeout)
+
+    except aiomqtt.MqttError as exc:
+        raise ConnectionError(_sanitize_mqtt_error(exc)) from exc
+    except asyncio.TimeoutError as exc:
+        raise TimeoutError(
+            f"Timed out waiting for MQTT response after {timeout:g}s — "
+            "raise MQTT_RESPONSE_TIMEOUT if your mesh is large"
+        ) from exc
+
+    if not response_payload:
+        raise ValueError("Empty MQTT response received")
+
+    return response_payload
+
+
+async def test_connection(
+    mqtt_host: str,
+    mqtt_port: int,
+    username: str | None = None,
+    password: str | None = None,
+    tls: bool = False,
+    tls_insecure: bool = False,
+) -> bool:
+    """Attempt a quick MQTT connection to verify broker reachability.
+
+    Returns True on success, raises ConnectionError/TimeoutError on failure.
+    """
+    if aiomqtt is None:  # pragma: no cover
+        raise ImportError("aiomqtt is required")
+
+    tls_context = _build_tls_context(tls_insecure) if tls else None
+
+    try:
+        async with aiomqtt.Client(
+            hostname=mqtt_host,
+            port=mqtt_port,
+            username=username,
+            password=password,
+            timeout=_CONNECTION_TIMEOUT,
+            tls_context=tls_context,
+        ):
+            return True
+    except aiomqtt.MqttError as exc:
+        raise ConnectionError(_sanitize_mqtt_error(exc)) from exc
+    except asyncio.TimeoutError as exc:
+        raise TimeoutError("Connection to broker timed out") from exc

backend/app/services/node_dedupe.py

@@ -0,0 +1,158 @@
+"""Duplicate canvas nodes: the same device drawn twice on the *same* canvas.
+
+A device legitimately appears on several canvases — one :class:`Node` per
+design, all pointing at one ``device_inventory`` row. Two nodes drawing that row
+on the *same* design are the corrupt case, and the only one collapsed here.
+
+Identity is the device link, not the addresses: a node names the row it draws,
+so "same device" is an id comparison rather than a guess across ieee/ip/mac.
+The repair is idempotent — the oldest node stays, edges and ``parent_id``
+references are re-pointed onto it, then the extras go. No device data is lost in
+the process because none of it lives on the node any more.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import Edge, Node
+from app.services.inventory_sync import find_device_for
+
+logger = logging.getLogger(__name__)
+
+
+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 this device is already drawn on ``design_id``.
+
+    Identity is resolved once, by the inventory row the addresses point at
+    (``find_device_for``: ieee > ip > mac), and a duplicate is simply a second
+    node on the same design drawing that row. Scoped to one design on purpose:
+    the same device may legitimately appear on several canvases.
+
+    The create/approve endpoints turn this into a 409 so the UI can offer "go to
+    existing" vs "add duplicate anyway".
+    """
+    device = await find_device_for(db, ip=ip, mac=mac, ieee=ieee)
+    if device is None:
+        return None
+    existing = (
+        await db.execute(
+            select(Node)
+            .where(Node.design_id == design_id, Node.device_id == device.id)
+            .order_by(Node.created_at, Node.id)
+        )
+    ).scalars().first()
+    if existing is None:
+        return None
+
+    # Report which address identified the device, as the UI prints it, in the
+    # same precedence find_device_for used: ieee > ip > mac.
+    match: str
+    value: str | None
+    device_ips = {t.strip() for t in (device.ip or "").split(",") if t.strip()}
+    shared_ip = next((t.strip() for t in (ip or "").split(",") if t.strip() in device_ips), None)
+    if ieee and device.ieee_address == ieee:
+        match, value = "ieee", ieee
+    elif shared_ip:
+        match, value = "ip", shared_ip
+    elif mac and device.mac == mac:
+        match, value = "mac", mac
+    else:
+        match, value = "ip", ip
+    return {
+        "duplicate": True,
+        "existing_node_id": existing.id,
+        "existing_label": device.label or existing.label,
+        "match": match,
+        "value": value,
+    }
+
+
+async def dedupe_nodes_by_device(db: AsyncSession) -> int:
+    """Merge duplicate nodes drawing the same device on the same canvas.
+
+    Returns the number of nodes removed. Idempotent. Nodes drawing one device on
+    *different* designs are left alone — that is valid cross-canvas placement.
+    The device facts live on the inventory row, so nothing has to be merged out
+    of the extras: only edges and parent links are re-pointed before they go.
+    Does not commit — the caller owns the transaction.
+    """
+    rows = (
+        await db.execute(
+            select(Node)
+            .where(Node.device_id.is_not(None))
+            .order_by(Node.device_id, Node.created_at, Node.id)
+        )
+    ).scalars().all()
+
+    groups: dict[tuple[str, str | None], list[Node]] = {}
+    for node in rows:
+        groups.setdefault((node.device_id, node.design_id), []).append(node)  # type: ignore[arg-type]
+
+    removed = 0
+    for (device_id, _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}
+
+        # 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
+
+        children = (
+            await db.execute(select(Node).where(Node.parent_id.in_(dup_ids)))
+        ).scalars().all()
+        for child in children:
+            # The canonical node may itself have been nested under one of its
+            # own duplicates. Re-pointing it here would make it its own parent,
+            # which freezes it on the canvas (#370) — detach it instead. Mirrors
+            # the self-loop edge deletion below.
+            child.parent_id = None if child.id == canonical.id else canonical.id
+
+        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 device %s: merged %d duplicate node(s) into %s",
+            device_id, len(dups), canonical.id,
+        )
+
+    if removed:
+        await db.flush()
+    return removed

backend/app/services/proxmox_service.py

@@ -0,0 +1,452 @@
+"""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 _iface_ipv4(iface: Any) -> str | None:
+    """First non-loopback IPv4 of one guest-agent interface entry."""
+    if not isinstance(iface, dict):
+        return None
+    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_qemu_ip(
+    agent_payload: dict[str, Any] | None, mac: str | None = None
+) -> str | None:
+    """The guest's LAN IPv4 from a qemu guest-agent interfaces reply.
+
+    Prefer the interface whose ``hardware-address`` is the NIC MAC from the
+    guest ``/config`` — the agent lists every interface, and on a guest running
+    Docker/k8s the bridge (``cni0``, ``flannel``, ``docker0``) can come first.
+    Those addresses repeat across guests, and a shared address is what let one
+    guest's import land on another's inventory row. Fall back to the first
+    non-loopback IPv4 when no MAC is known or none matches.
+    """
+    if not agent_payload:
+        return None
+    result = agent_payload.get("result")
+    if not isinstance(result, list):
+        return None
+    wanted = normalize_mac(mac)
+    if wanted:
+        for iface in result:
+            if not isinstance(iface, dict):
+                continue
+            if normalize_mac(iface.get("hardware-address")) != wanted:
+                continue
+            ip = _iface_ipv4(iface)
+            if ip:
+                return ip
+    for iface in result:
+        ip = _iface_ipv4(iface)
+        if ip:
+            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, mac)
+        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

@@ -7,14 +7,21 @@ import re
 import socket
 import subprocess
 import threading
+import time
+from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Any
 
-from sqlalchemy import select
+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, 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.inventory_sync import ip_tokens, merge_services
+from app.services.mac_utils import normalize_mac
 
 logger = logging.getLogger(__name__)
 
@@ -34,6 +41,118 @@ _EXTRA_PORTS = (
     "16686,34567,37777,51413,64738"
 )
 
+# nmap -p accepts "N" or "N-M"; user ranges are validated against this.
+_PORT_RANGE_RE = re.compile(r"^\d{1,5}(-\d{1,5})?$")
+
+
+@dataclass
+class DeepScanOptions:
+    """Per-scan deep-scan settings (None/empty → standard scan, today's behaviour)."""
+
+    http_ranges: list[str] = field(default_factory=list)
+    http_probe_enabled: bool = False
+    verify_tls: bool = False
+
+
+def _valid_port_range(spec: str) -> bool:
+    if not _PORT_RANGE_RE.match(spec):
+        return False
+    parts = [int(p) for p in spec.split("-")]
+    if any(p < 1 or p > 65535 for p in parts):
+        return False
+    return len(parts) == 1 or parts[0] <= parts[1]
+
+
+# Every TCP port. Used by the per-device deep rescan, which trades minutes of
+# nmap time for a service list that no curated port list can promise.
+_FULL_PORTS = "1-65535"
+
+# The deep rescan runs the full range in slices, one nmap call each, unioning
+# what they find. A slice that runs long costs only its own ports — where a
+# single 65535-port call that overruns costs everything (see _nmap_scan_single).
+# It also gives the run somewhere to notice a stop request, and somewhere to
+# give up when the budget is spent, without abandoning the ports already found.
+_DEEP_CHUNK_SIZE = 8192
+
+
+def _parse_port_spec(spec: str) -> list[tuple[int, int]]:
+    """Parse an nmap ``-p`` spec into sorted, merged ``(start, end)`` ranges.
+
+    Accepts what the user can type in the deep-scan dialog: ``80``,
+    ``8000-9000``, or a comma list of both. Returns ``[]`` for anything invalid
+    — the caller turns that into a 422 rather than handing nmap a bad ``-p``.
+    """
+    ranges: list[tuple[int, int]] = []
+    for token in (t.strip() for t in spec.split(",")):
+        if not token or not _valid_port_range(token):
+            return []
+        parts = [int(p) for p in token.split("-")]
+        ranges.append((parts[0], parts[-1]))
+    if not ranges:
+        return []
+    ranges.sort()
+    merged = [ranges[0]]
+    for start, end in ranges[1:]:
+        last_start, last_end = merged[-1]
+        if start <= last_end + 1:
+            merged[-1] = (last_start, max(last_end, end))
+        else:
+            merged.append((start, end))
+    return merged
+
+
+def _valid_port_spec(spec: str) -> bool:
+    """True when ``spec`` is a usable comma list of ports/ranges."""
+    return bool(_parse_port_spec(spec))
+
+
+def _port_chunks(spec: str, size: int = _DEEP_CHUNK_SIZE) -> list[str]:
+    """Slice a port spec into nmap ``-p`` specs of at most ``size`` ports each.
+
+    Ranges are packed, not scanned one call per range: ``80,443`` is one chunk,
+    not two, while ``1-65535`` becomes eight. Each chunk is a scan boundary —
+    where a stop request lands and where the time budget is checked.
+    """
+    chunks: list[str] = []
+    current: list[str] = []
+    budget = size
+    for start, end in _parse_port_spec(spec):
+        cursor = start
+        while cursor <= end:
+            take = min(budget, end - cursor + 1)
+            stop = cursor + take - 1
+            current.append(f"{cursor}-{stop}" if stop > cursor else str(cursor))
+            budget -= take
+            cursor = stop + 1
+            if budget == 0:
+                chunks.append(",".join(current))
+                current = []
+                budget = size
+    if current:
+        chunks.append(",".join(current))
+    return chunks
+
+
+def _deep_port_chunks(size: int = _DEEP_CHUNK_SIZE) -> list[str]:
+    """Slice the whole TCP range into nmap ``-p`` specs of ``size`` ports."""
+    return _port_chunks(_FULL_PORTS, size)
+
+
+def _build_port_spec(http_ranges: list[str] | None, full: bool = False) -> str:
+    """Combine the default port list with validated user ranges for nmap -p.
+
+    ``full`` overrides everything with the whole TCP range — the deep rescan of
+    a single device, where completeness beats speed.
+    """
+    if full:
+        return _FULL_PORTS
+    if not http_ranges:
+        return _EXTRA_PORTS
+    extra = [r.strip() for r in http_ranges if _valid_port_range(r.strip())]
+    if not extra:
+        return _EXTRA_PORTS
+    return _EXTRA_PORTS + "," + ",".join(extra)
+
 _MDNS_SERVICE_TYPES = [
     "_http._tcp.local.",
     "_shelly._tcp.local.",
@@ -142,7 +261,7 @@ def _arp_table_hosts(network: str) -> dict[str, dict[str, Any]]:
         return {}
 
 
-async def _ping_sweep(target: str) -> dict[str, dict[str, Any]]:
+async def _ping_sweep(target: str, run_id: str | None = None) -> dict[str, dict[str, Any]]:
     """
     Phase 1: Concurrent ICMP ping sweep + ARP cache.
     Pings all IPs in the CIDR in parallel (up to 50 at once, 1s timeout each).
@@ -172,6 +291,12 @@ async def _ping_sweep(target: str) -> dict[str, dict[str, Any]]:
     alive_ips: set[str] = {ip for ip in ping_results if ip is not None}
     logger.info("[Phase 1] %d/%d hosts responded to ping", len(alive_ips), len(all_ips))
 
+    # Cancelled during the sweep — bail before the (potentially long) Phase 2
+    # port scan. Returning empty makes _nmap_scan skip nmap entirely.
+    if run_id is not None and _is_cancelled(run_id):
+        logger.info("[Phase 1] %s — scan cancelled, skipping hostname/ARP enrichment", target)
+        return {}
+
     # ARP cache: catch devices that block ICMP but were recently active,
     # and enrich ping-alive hosts with their MAC addresses.
     arp_cache = await asyncio.to_thread(_arp_table_hosts, target)
@@ -195,10 +320,20 @@ async def _ping_sweep(target: str) -> dict[str, dict[str, Any]]:
     return alive
 
 
-def _nmap_scan_single(host_dict: dict[str, Any]) -> dict[str, Any]:
+def _nmap_scan_single(
+    host_dict: dict[str, Any], port_spec: str = _EXTRA_PORTS, bounded: bool = False
+) -> dict[str, Any]:
     """
     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)
@@ -207,52 +342,101 @@ def _nmap_scan_single(host_dict: dict[str, Any]) -> dict[str, Any]:
         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 {_EXTRA_PORTS}"
-    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 {_EXTRA_PORTS}"
+    # -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) ---
+    # Default timing for the range scan: its ports are authoritative and a
+    # curated port list is fast either way.
+    #
+    # ``bounded`` is the deep rescan's timing, and carries NO --host-timeout on
+    # purpose: nmap answers a host timeout with "Skipping host <ip> due to host
+    # timeout" and discards *every* port it had already found, so a ceiling here
+    # turns a slow scan into one that reports nothing. The caller bounds total
+    # runtime by slicing the range instead.
+    #
+    # What costs the time is a host that drops packets: 8188 of 8192 ports
+    # filtered, each waiting out its probe. Measured against such a host, the
+    # retry pass is the whole cost — 8192 ports took 329s at --max-retries 1
+    # and 164s at 0, finding the same ports. Capping the RTT changed nothing
+    # (329s), so it is not set. Dropping retries risks missing a port that
+    # loses its one probe; that trade belongs to the deep scan alone, and the
+    # curated-port range scan keeps nmap's default retries.
+    discovery_args = f"{scan_type} --open -T4 -Pn -p {port_spec}"
+    if bounded:
+        discovery_args += " --max-retries 0 --min-rate 2000"
+    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
 
 
-async def _nmap_port_scan(alive: dict[str, dict[str, Any]]) -> list[dict[str, Any]]:
+async def _nmap_port_scan(
+    alive: dict[str, dict[str, Any]], port_spec: str = _EXTRA_PORTS,
+    run_id: str | None = None,
+) -> list[dict[str, Any]]:
     """
     Phase 2: Per-IP service detection with bounded concurrency.
     Each host is scanned independently in a thread — no inter-host timeout interference.
@@ -266,7 +450,12 @@ async def _nmap_port_scan(alive: dict[str, dict[str, Any]]) -> list[dict[str, An
 
     async def _scan_with_sem(host_dict: dict[str, Any]) -> dict[str, Any]:
         async with semaphore:
-            return await asyncio.to_thread(_nmap_scan_single, host_dict)
+            # Once cancelled, skip the expensive nmap call for every host still
+            # queued behind the semaphore — return it unscanned so the gather
+            # unwinds fast instead of blocking the stop for minutes.
+            if run_id is not None and _is_cancelled(run_id):
+                return host_dict
+            return await asyncio.to_thread(_nmap_scan_single, host_dict, port_spec)
 
     raw = await asyncio.gather(*[_scan_with_sem(h) for h in alive.values()], return_exceptions=True)
     results = []
@@ -279,24 +468,32 @@ async def _nmap_port_scan(alive: dict[str, dict[str, Any]]) -> list[dict[str, An
     return results
 
 
-async def _nmap_scan(target: str) -> list[dict[str, Any]]:
+async def _nmap_scan(
+    target: str, port_spec: str = _EXTRA_PORTS, run_id: str | None = None
+) -> list[dict[str, Any]]:
     """
     Two-phase scan for a CIDR range.
     Phase 1: Concurrent ping sweep to find alive hosts (fast, no false positives).
     Phase 2: Per-IP nmap port scan with service detection (bounded concurrency, 10 at a time).
+
+    ``run_id`` lets each phase poll for cancellation so a stop request takes
+    effect mid-range instead of only at CIDR/host boundaries in run_scan.
     """
     logger.info("[Scan] Starting scan for %s — nmap available: %s", target, _NMAP_AVAILABLE)
+    if run_id is not None and _is_cancelled(run_id):
+        logger.info("[Scan] %s — cancelled before start, skipping", target)
+        return []
     if not _NMAP_AVAILABLE:
         logger.warning("[Scan] nmap not available — returning mock data")
         return _mock_scan(target)
     try:
-        alive = await _ping_sweep(target)
+        alive = await _ping_sweep(target, run_id=run_id)
         logger.info("[Phase 1] Found %d alive host(s) in %s: %s",
                     len(alive), target, ", ".join(sorted(alive.keys())))
     except Exception as exc:
         logger.error("Phase 1 ping sweep failed: %s", exc)
         raise RuntimeError(str(exc)) from exc
-    return await _nmap_port_scan(alive)
+    return await _nmap_port_scan(alive, port_spec, run_id=run_id)
 
 
 async def _mdns_discover(timeout: float = 4.0) -> list[dict[str, Any]]:
@@ -375,10 +572,213 @@ def _mock_scan(target: str) -> list[dict[str, Any]]:
     ]
 
 
-async def run_scan(ranges: list[str], db: AsyncSession, run_id: str) -> None:
-    """Execute scan for given CIDR ranges and populate pending_devices."""
+def _group_by_shared_ip(rows: list[InventoryDevice]) -> list[list[InventoryDevice]]:
+    """Group rows that share at least one address, transitively.
+
+    A row may hold several comma-separated addresses, so grouping is per token:
+    ``10.0.0.1`` and ``10.0.0.1, 10.0.1.1`` are the same device, and a row
+    bridging two others (``A,B`` next to ``A`` and ``B``) puts all three in one
+    group. Input order is preserved inside each group, so a caller ordering by
+    ``discovered_at`` still gets the oldest row first.
+    """
+    # Union-find over row indices, keyed by the addresses they carry.
+    parent = list(range(len(rows)))
+
+    def find(i: int) -> int:
+        while parent[i] != i:
+            parent[i] = parent[parent[i]]
+            i = parent[i]
+        return i
+
+    owner: dict[str, int] = {}
+    for i, row in enumerate(rows):
+        for tok in ip_tokens(row.ip):
+            first = owner.setdefault(tok, i)
+            root_a, root_b = find(first), find(i)
+            if root_a != root_b:
+                parent[max(root_a, root_b)] = min(root_a, root_b)
+
+    groups: dict[int, list[InventoryDevice]] = {}
+    for i, row in enumerate(rows):
+        groups.setdefault(find(i), []).append(row)
+    return list(groups.values())
+
+
+def _collapse_targets(
+    group: list[InventoryDevice],
+) -> tuple[InventoryDevice, list[InventoryDevice]]:
+    """The row a duplicate group folds into, and the rows safe to delete for it.
+
+    An ``approved`` row owns the canvas-link semantics — nodes and rack mounts
+    point at it under ``ON DELETE SET NULL`` — so deleting one silently unlinks
+    whatever drew it. With one approved row that row is the merge target and the
+    rest collapse into it. With *two*, the group is two canvas-linked devices
+    laying claim to one address, and a background scan is not the place to
+    decide which of them loses its links: every approved row stands, and only
+    the pending ones are collapsed. The pair then stays visible in the inventory
+    for the user to sort out.
+    """
+    approved = [row for row in group if row.status == "approved"]
+    keep = approved[0] if approved else group[0]
+    if len(approved) > 1:
+        return keep, [row for row in group if row.status != "approved"]
+    return keep, [row for row in group if row is not keep]
+
+
+async def _dedupe_pending_by_ip(db: AsyncSession) -> int:
+    """Collapse duplicate non-hidden inventory rows that share an IP into one.
+
+    Keeps an ``approved`` row when present (it carries canvas-link semantics),
+    otherwise the oldest row, and deletes the rest. Returns the number deleted.
+    Rows carrying several addresses count as duplicates of any row holding one
+    of them — that is what declaring the extra address is for.
+    """
+    rows = (await db.execute(
+        select(InventoryDevice)
+        .where(InventoryDevice.status != "hidden", InventoryDevice.ip.isnot(None))
+        .order_by(InventoryDevice.discovered_at)
+    )).scalars().all()
+
+    deleted = 0
+    for group in _group_by_shared_ip(list(rows)):
+        if len(group) < 2:
+            continue
+        _, dups = _collapse_targets(group)
+        for dup in dups:
+            await db.delete(dup)
+            deleted += 1
+    if deleted:
+        await db.commit()
+    return deleted
+
+
+async def process_host(
+    db: AsyncSession,
+    host: dict[str, Any],
+    *,
+    hidden_ips: set[str],
+    deep_scan: DeepScanOptions,
+    discovery_source: str = "arp",
+) -> str:
+    """Fold one scanned host into ``device_inventory`` and commit.
+
+    Shared by the range scan and the single-device deep rescan, so both apply
+    the same matching, merge and de-duplication rules.
+
+    Returns ``"skipped"`` (hidden by the user), ``"created"`` (a new inventory
+    row) or ``"updated"`` (an existing row refreshed).
+    """
+    ip = host["ip"]
+
+    # Skip only user-hidden devices. On-canvas devices are kept so they
+    # surface in the inventory with a canvas-presence badge.
+    if ip in hidden_ips:
+        logger.debug("Skipping %s — hidden by user", ip)
+        return "skipped"
+
+    open_ports = host["open_ports"]
+    # Deep-scan HTTP probe: enrich open ports with title/header signals so
+    # fingerprint can confirm services on custom ports. No-op when disabled
+    # or when the host has no open ports (e.g. mDNS-only discovery).
+    if deep_scan.http_probe_enabled and open_ports:
+        open_ports = await probe_open_ports(
+            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, norm_mac)
+
+    # 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.
+    #
+    # The IP side matches per token: a row may hold several comma-separated
+    # addresses (a router's LAN and VLAN legs, a host and its VIP), declared by
+    # the user precisely so this scan folds into it rather than minting a second
+    # row every run. `contains` only narrows the query — the tokens are confirmed
+    # below, because "10.0.0.4" is a substring of "10.0.0.40" and these rows are
+    # deleted, not merely skipped.
+    match_cond = [InventoryDevice.ip.contains(ip)]
+    if norm_mac:
+        match_cond.append(InventoryDevice.mac == norm_mac)
+    candidates = (await db.execute(
+        select(InventoryDevice)
+        .where(or_(*match_cond), InventoryDevice.status != "hidden")
+        .order_by(InventoryDevice.discovered_at)
+    )).scalars().all()
+    existing_rows = [
+        row for row in candidates
+        if ip in ip_tokens(row.ip) or (norm_mac is not None and row.mac == norm_mac)
+    ]
+
+    if existing_rows:
+        # Prefer an approved row (it owns the canvas link semantics),
+        # otherwise the oldest. Collapse any leftover duplicates created
+        # by earlier scans — except a second approved row, which keeps its
+        # own canvas links (see `_collapse_targets`).
+        keep, dups = _collapse_targets(existing_rows)
+        for dup in dups:
+            await db.delete(dup)
+        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
+        # Union, never replace. Since 3.3.0 the row is the only copy of
+        # a device's services — every canvas drawing it reads this list
+        # — so overwriting it with the fingerprint would delete services
+        # the user added by hand, on every canvas at once. What a scan
+        # finds is added; what it no longer sees stays. A service the
+        # user does not want on a canvas is hidden by that node's view,
+        # which is where "I deleted this" belongs.
+        # discovered=: the fingerprint may add services and refresh what it
+        # knows, but never repaints an icon or category the user chose.
+        keep.services = merge_services(keep.services, services, discovered=True)
+        # 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.
+        # Stamp last_scan on the row so every canvas drawing the device
+        # shows when the scanner last observed it. The row is the one
+        # place that fact belongs; a node only draws it.
+        keep.last_scan = datetime.now(timezone.utc)
+        outcome = "updated"
+    else:
+        db.add(InventoryDevice(
+            ip=ip,
+            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],
+            last_scan=datetime.now(timezone.utc),
+        ))
+        outcome = "created"
+
+    await db.commit()
+    return outcome
+
+
+async def run_scan(
+    ranges: list[str],
+    db: AsyncSession,
+    run_id: str,
+    deep_scan: DeepScanOptions | None = None,
+) -> None:
+    """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()
+    port_spec = _build_port_spec(deep_scan.http_ranges)
+
     devices_found = 0
     mdns_task: asyncio.Task[list[dict[str, Any]]] | None = None
     try:
@@ -389,25 +789,22 @@ async def run_scan(ranges: list[str], db: AsyncSession, run_id: str) -> None:
             except ValueError:
                 raise ValueError(f"Invalid CIDR range: {r!r}") from None
 
-        # Pre-fetch canvas IPs and hidden IPs once — avoids N+1 queries per host
-        canvas_ips_result = await db.execute(select(Node.ip).where(Node.ip.isnot(None)))
-        canvas_ips: set[str] = {row[0] for row in canvas_ips_result.fetchall()}
-
+        # Pre-fetch hidden IPs once — avoids N+1 queries per host.
+        # 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()}
+        # Per address, not per row: a hidden device holding several addresses is
+        # hidden at every one of them.
+        hidden_ips: set[str] = {
+            tok for row in hidden_ips_result.fetchall() for tok in ip_tokens(row[0])
+        }
 
-        # Clean up stale pending devices whose IPs are already in the canvas
-        if canvas_ips:
-            from sqlalchemy import delete as sa_delete
-            await db.execute(
-                sa_delete(PendingDevice).where(
-                    PendingDevice.status == "pending",
-                    PendingDevice.ip.in_(canvas_ips),
-                )
-            )
-            await db.commit()
+        # Collapse any pre-existing duplicate inventory rows (same IP, non-hidden)
+        # left over from older scans, so the device shows up exactly once even if
+        # it isn't re-discovered this run (e.g. now offline).
+        await _dedupe_pending_by_ip(db)
 
         # Start mDNS discovery in the background while nmap scans run
         mdns_task = asyncio.create_task(_mdns_discover())
@@ -417,53 +814,24 @@ async def run_scan(ranges: list[str], db: AsyncSession, run_id: str) -> None:
 
         async def _process_host(host: dict[str, Any], discovery_source: str = "arp") -> None:
             nonlocal devices_found
-            ip = host["ip"]
-
-            # Skip canvas nodes and user-hidden devices (sets pre-fetched before loop)
-            if ip in canvas_ips:
-                logger.debug("Skipping %s — already in canvas", ip)
-                return
-            if ip in hidden_ips:
-                logger.debug("Skipping %s — hidden by user", ip)
-                return
-
-            services = fingerprint_ports(host["open_ports"])
-            suggested_type = suggest_node_type(host["open_ports"], host.get("mac"))
-
-            existing_result = await db.execute(
-                select(PendingDevice).where(
-                    PendingDevice.ip == ip,
-                    PendingDevice.status == "pending",
-                )
+            outcome = await process_host(
+                db,
+                host,
+                hidden_ips=hidden_ips,
+                deep_scan=deep_scan,
+                discovery_source=discovery_source,
             )
-            existing = existing_result.scalar_one_or_none()
-            if existing:
-                existing.mac = host.get("mac") or existing.mac
-                existing.hostname = host.get("hostname") or existing.hostname
-                existing.os = host.get("os") or existing.os
-                existing.services = services
-                existing.suggested_type = suggested_type
-            else:
-                db.add(PendingDevice(
-                    ip=ip,
-                    mac=host.get("mac"),
-                    hostname=host.get("hostname"),
-                    os=host.get("os"),
-                    services=services,
-                    suggested_type=suggested_type,
-                    status="pending",
-                    discovery_source=discovery_source,
-                ))
+            if outcome == "skipped":
+                return
+            if outcome == "created":
                 devices_found += 1
-
-            await db.commit()
             await broadcast_scan_update(run_id=run_id, devices_found=devices_found)
 
         # nmap scan per CIDR — results stream in progressively
         for cidr in ranges:
             if _is_cancelled(run_id):
                 break
-            hosts = await _nmap_scan(cidr)
+            hosts = await _nmap_scan(cidr, port_spec, run_id=run_id)
             for host in hosts:
                 if _is_cancelled(run_id):
                     break
@@ -510,3 +878,165 @@ async def run_scan(ranges: list[str], db: AsyncSession, run_id: str) -> None:
     finally:
         with _cancelled_lock:
             _cancelled_runs.discard(run_id)
+
+
+async def run_device_scan(
+    device_id: str,
+    db: AsyncSession,
+    run_id: str,
+    deep_scan: DeepScanOptions | None = None,
+    full_ports: bool = True,
+    ports: str | None = None,
+) -> None:
+    """Deep-rescan one known device and refresh its inventory row.
+
+    No ping sweep and no mDNS: the device is already known, so the IP goes
+    straight to the phase-2 port scan (``-Pn``). ``full_ports`` scans all 65535
+    TCP ports, which is the point of the feature — a device added before the
+    scanner knew a service, or listening on a port no curated list covers.
+    Minutes, not seconds; the run is cancellable like any other.
+
+    ``ports`` narrows that to a user-chosen spec (``80,443``, ``1-1024``) and
+    wins over ``full_ports`` — the dialog prefills the full range, so a caller
+    that passes something else means it.
+    """
+    from app.api.routes.status import broadcast_scan_update
+
+    deep_scan = deep_scan or DeepScanOptions()
+    port_spec = (
+        ports if ports else _build_port_spec(deep_scan.http_ranges, full=full_ports)
+    )
+
+    try:
+        device = await db.get(InventoryDevice, device_id)
+        if device is None or not device.ip:
+            raise ValueError("Device has no IP to scan")
+
+        host: dict[str, Any] = {
+            "ip": device.ip,
+            "mac": device.mac,
+            "hostname": device.hostname,
+            "os": device.os,
+            "open_ports": [],
+        }
+        # A rescan re-observes a device through the source it already has; it
+        # is not a network discovery. Hardcoding "arp" here would tell a
+        # Proxmox guest, a rack mount or a hand-added host that the network
+        # scanner found it, and it would then answer that source filter.
+        source = device.discovery_source or "arp"
+
+        # The full range goes out in slices so a stop request lands within one
+        # slice instead of at the end, and so a spent budget keeps the ports
+        # found so far. A curated port list is one call, as before.
+        if ports:
+            chunks = _port_chunks(ports)
+        elif full_ports:
+            chunks = _deep_port_chunks()
+        else:
+            chunks = [port_spec]
+        # Retry-free timing pays for itself over thousands of ports on a host
+        # that drops packets; over a handful it only costs accuracy.
+        total_ports = sum(end - start + 1 for start, end in _parse_port_spec(port_spec))
+        bounded = total_ports > _DEEP_CHUNK_SIZE
+        deadline = time.monotonic() + settings.scanner_deep_host_timeout
+        found: list[dict[str, Any]] = []
+        seen: set[tuple[str, int]] = set()
+        skipped = 0
+
+        for i, chunk in enumerate(chunks):
+            if _is_cancelled(run_id):
+                skipped = len(chunks) - i
+                break
+            if i and time.monotonic() > deadline:
+                skipped = len(chunks) - i
+                logger.warning(
+                    "[Deep scan] %s — budget of %ds spent, %d port range(s) not scanned",
+                    host["ip"], settings.scanner_deep_host_timeout, skipped,
+                )
+                break
+            # bounded: retry-free timing, for a host that drops packets.
+            scanned = await asyncio.to_thread(
+                _nmap_scan_single, dict(host), chunk, bounded
+            )
+            for port in scanned.get("open_ports") or []:
+                key = (port["protocol"], port["port"])
+                if key not in seen:
+                    seen.add(key)
+                    found.append(port)
+            host["mac"] = host["mac"] or scanned.get("mac")
+            host["os"] = scanned.get("os") or host["os"]
+
+        host["open_ports"] = found
+        # A partial sweep still says what it saw; the row unions it in.
+        partial = (
+            f"Scanned {len(chunks) - skipped}/{len(chunks)} port ranges "
+            f"({len(found)} open) — the rest was not reached"
+            if skipped
+            else None
+        )
+
+        devices_found = 0
+        if not _is_cancelled(run_id):
+            # The row is being rescanned on the user's request, so it is never
+            # "hidden" from itself — the route rejects hidden devices upfront.
+            outcome = await process_host(
+                db, host, hidden_ips=set(), deep_scan=deep_scan, discovery_source=source
+            )
+            if outcome == "created":
+                devices_found = 1
+            await broadcast_scan_update(run_id=run_id, devices_found=devices_found)
+
+        run = await db.get(ScanRun, run_id)
+        if run:
+            run.status = "cancelled" if _is_cancelled(run_id) else "done"
+            run.devices_found = devices_found
+            # Not a failure: a done run carrying an advisory, the way a Proxmox
+            # import reports what it could not see. Never let a partial sweep
+            # read as a complete one.
+            if partial and run.status == "done":
+                run.error = partial
+            run.finished_at = datetime.now(timezone.utc)
+            await db.commit()
+
+    except Exception as exc:
+        logger.error("Device scan failed: %s", exc)
+        await db.rollback()
+        run = await db.get(ScanRun, run_id)
+        if run:
+            run.status = "error"
+            run.error = str(exc)
+            run.finished_at = datetime.now(timezone.utc)
+            await db.commit()
+    finally:
+        with _cancelled_lock:
+            _cancelled_runs.discard(run_id)
+
+
+async def reconcile_orphan_runs(db: AsyncSession) -> int:
+    """
+    Mark every scan run still flagged `running` at startup as errored.
+
+    Scans live on a background thread inside this process, so nothing can
+    legitimately be `running` the moment we boot: any such row belongs to a
+    previous process that died mid-scan (an OOM kill, `docker stop`, a crash).
+    Left alone the row is immortal, and it also locks the target out — the
+    trigger endpoints reject a new scan while one is `running` for the same
+    range, so a single kill blocks re-scanning for good.
+
+    Returns the number of rows reconciled.
+    """
+    orphans = (
+        await db.execute(select(ScanRun).where(ScanRun.status == "running"))
+    ).scalars().all()
+    if not orphans:
+        return 0
+    now = datetime.now(timezone.utc)
+    for run in orphans:
+        # "error" is the word run_scan and run_device_scan already write when
+        # they fail; Scan History filters and colours that one.
+        run.status = "error"
+        run.error = "Interrupted: the backend restarted while this scan was running"
+        run.finished_at = now
+    await db.commit()
+    logger.warning("Reconciled %d scan run(s) left running by a previous process", len(orphans))
+    return len(orphans)

backend/app/services/status_checker.py

@@ -64,17 +64,35 @@ async def check_node(check_method: str, target: str | None, ip: str | None) -> d
         return {"status": "offline", "response_time_ms": None}
 
 
+def _is_ipv6(host: str) -> bool:
+    """True if host is a literal IPv6 address (bracketed or bare)."""
+    try:
+        socket.inet_pton(socket.AF_INET6, host.strip("[]"))
+        return True
+    except OSError:
+        return False
+
+
 async def _ping(host: str) -> bool:
-    # ping(8) -W flag units differ by OS:
-    #   Linux:   seconds        (-W 1   = 1s)
-    #   macOS:   milliseconds   (-W 1   = 1ms — fails for any RTT >1ms)
-    #   Windows: -w in ms       (-w 1000 = 1s)
+    # Send 2 probes with a ~2s timeout so a single dropped packet or a slow
+    # device (ESPHome, IoT) doesn't flap a node offline. Success = any reply.
+    #
+    # -W flag units differ by OS:
+    #   Linux:   seconds        (-W 2   = 2s)
+    #   macOS:   milliseconds   (-W 2000 = 2s)
+    #   Windows: -w in ms       (-w 2000 = 2s)
+    #
+    # IPv6-only hosts (e.g. Alexa) never answer IPv4 ping, so target the right
+    # stack: macOS ships a separate ping6; Linux/Windows take a -6 flag.
+    ipv6 = _is_ipv6(host)
     if sys.platform == "win32":
-        args = ["ping", "-n", "1", "-w", "1000", host]
+        family = ["-6"] if ipv6 else ["-4"]
+        args = ["ping", *family, "-n", "2", "-w", "2000", host]
     elif sys.platform == "darwin":
-        args = ["ping", "-c", "1", "-W", "1000", host]
+        args = ["ping6", "-c", "2", host] if ipv6 else ["ping", "-c", "2", "-W", "2000", host]
     else:
-        args = ["ping", "-c", "1", "-W", "1", host]
+        family = ["-6"] if ipv6 else []
+        args = ["ping", *family, "-c", "2", "-W", "2", host]
     proc = await asyncio.create_subprocess_exec(
         *args,
         stdout=asyncio.subprocess.DEVNULL,
@@ -85,8 +103,16 @@ async def _ping(host: str) -> bool:
 
 
 async def _http_get(url: str, verify: bool = False) -> bool:
-    async with httpx.AsyncClient(verify=verify, timeout=5) as client:
-        resp = await client.get(url, follow_redirects=True)
+    # Only the status line matters here. A plain .get() buffers the whole body
+    # first, and some endpoints stream without end (bandwidth-test endpoints,
+    # MJPEG cameras, log tails) — enough to OOM the backend. timeout=5 does not
+    # save us: httpx applies it per network operation, not to the total time
+    # spent draining a socket that keeps delivering data. stream() closes the
+    # connection on exit without draining it.
+    async with (
+        httpx.AsyncClient(verify=verify, timeout=5) as client,
+        client.stream("GET", url, follow_redirects=True) as resp,
+    ):
         return resp.status_code < 500
 
 
@@ -100,3 +126,136 @@ async def _tcp_connect(host: str, port: int) -> bool:
         return True
     except (TimeoutError, OSError, socket.gaierror):
         return False
+
+
+# --- Per-service status checks ---
+
+# Ports that are not HTTP/web. These get NO status check — a service here stays
+# grey (unknown) rather than going red. An open TCP socket doesn't prove the
+# service is healthy, and a closed one flaps red misleadingly (e.g. SSH on a
+# box that simply firewalls 22). Only HTTP(S)-reachable services are checked.
+#
+# 515 and 9100-9107 are raw printing (LPD / JetDirect), and they are here for a
+# stronger reason than the rest: a printer treats any bytes on 9100 as a print
+# job, so a GET line makes it print a page — every 60 s, for as long as the node
+# exists. Node Exporter also lives on 9100 and loses its status check because of
+# this; a grey dot is the cheaper mistake.
+_PRINTER_PORTS = frozenset({515, *range(9100, 9108)})
+_NON_HTTP_PORTS = frozenset({
+    22, 21, 23, 25, 465, 587, 53, 110, 143, 993, 995, 389, 636, 445, 514,
+    1433, 3306, 5432, 5672, 6379, 9092, 11211, 27017, 27018,
+}) | _PRINTER_PORTS
+_HTTPS_PORTS = frozenset({443, 8443})
+
+
+def _service_host(svc: dict[str, Any], host: str) -> str:
+    """Bracket bare IPv6 literals for use in a URL."""
+    return f"[{host}]" if _is_ipv6(host) else host
+
+
+def _parse_override(raw: str) -> tuple[str, str | None, int | None]:
+    """Split a service `host` override into (hostname, scheme, port).
+
+    Mirrors the frontend `parseHostParts`: a node can serve several domains, so
+    a service may carry its own host, optionally with a scheme and a port
+    (`blog.example.com`, `blog.example.com:8443`, `https://blog.example.com`).
+    """
+    # Like a node ip, an override may list several hosts — the first one wins,
+    # same as the frontend's `splitFirstHost`.
+    rest = raw.split(",")[0].strip()
+    scheme: str | None = None
+    for prefix in ("https://", "http://"):
+        if rest.lower().startswith(prefix):
+            scheme = prefix[:-3]
+            rest = rest[len(prefix):]
+            break
+    rest = rest.split("/", 1)[0]
+
+    if rest.startswith("["):
+        closing = rest.find("]")
+        if closing == -1:
+            return rest, scheme, None
+        hostname = rest[1:closing]
+        remainder = rest[closing + 1:]
+        port = remainder[1:] if remainder.startswith(":") else ""
+        return hostname, scheme, int(port) if port.isdigit() else None
+
+    if rest.count(":") == 1:
+        hostname, _, port = rest.partition(":")
+        if hostname and port.isdigit():
+            return hostname, scheme, int(port)
+
+    return rest, scheme, None
+
+
+async def check_service(svc: dict[str, Any], host: str | None) -> str:
+    """Check a single service. Returns 'online' | 'offline' | 'unknown'.
+
+    Only HTTP(S)-reachable services get a real check (an HTTP GET). Everything
+    else — SSH, databases, mail, DNS, raw TCP, UDP, port-less — stays 'unknown'
+    so it keeps its category colour instead of flashing red. An open TCP socket
+    doesn't prove a non-web service is healthy, so we don't pretend it does.
+    """
+    override = str(svc.get("host") or "").strip()
+    override_scheme: str | None = None
+    override_port: int | None = None
+    if override:
+        host, override_scheme, override_port = _parse_override(override)
+
+    if not host or host.startswith("-"):
+        return "unknown"
+    if str(svc.get("protocol", "")).lower() == "udp":
+        return "unknown"
+
+    port = svc.get("port")
+    port = int(port) if isinstance(port, int) or (isinstance(port, str) and port.isdigit()) else None
+    if port is None:
+        port = override_port
+
+    # Non-HTTP ports (SSH 22, DB, mail, …) are never checked — keep them grey.
+    if port is not None and port in _NON_HTTP_PORTS:
+        return "unknown"
+
+    name = str(svc.get("service_name", "")).lower()
+    is_web = port is not None or "http" in name or override_scheme is not None
+    if not is_web:
+        return "unknown"
+
+    try:
+        scheme = override_scheme or ("https" if (
+            port in _HTTPS_PORTS or "https" in name or "ssl" in name or "tls" in name
+        ) else "http")
+        url_host = _service_host(svc, host)
+        # A host override usually points at a reverse proxy, where the scanned
+        # port is an internal detail that would break the public URL. Only a
+        # port typed into the override itself is used.
+        url_port = override_port if override else port
+        url = f"{scheme}://{url_host}" + (f":{url_port}" if url_port is not None else "")
+        return "online" if await _http_get(url, verify=False) else "offline"
+    except Exception as exc:
+        logger.debug("Service check failed for %s:%s (%s)", host, port, exc)
+        return "offline"
+
+
+async def check_services(
+    host: str | None, services: list[dict[str, Any]], concurrency: int = 10
+) -> list[dict[str, Any]]:
+    """Check every service against host concurrently (bounded).
+
+    Returns a list of {port, protocol, status} dicts, one per input service.
+    """
+    sem = asyncio.Semaphore(concurrency)
+
+    async def _one(svc: dict[str, Any]) -> dict[str, Any]:
+        async with sem:
+            status = await check_service(svc, host)
+        # `host` rides along: several vhosts can share one port on one node, so
+        # port+protocol alone no longer identifies a service on the client side.
+        return {
+            "port": svc.get("port"),
+            "protocol": svc.get("protocol"),
+            "host": svc.get("host"),
+            "status": status,
+        }
+
+    return await asyncio.gather(*[_one(s) for s in services]) if services else []

backend/app/services/zigbee_service.py

@@ -5,9 +5,11 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
-import ssl
 from typing import Any
 
+from app.core.config import settings
+from app.services.mqtt_common import _build_tls_context, _sanitize_mqtt_error
+
 logger = logging.getLogger(__name__)
 
 try:
@@ -18,44 +20,13 @@ except ImportError:  # pragma: no cover
 _NETWORKMAP_REQUEST_TOPIC = "{base_topic}/bridge/request/networkmap"
 _NETWORKMAP_RESPONSE_TOPIC = "{base_topic}/bridge/response/networkmap"
 _CONNECTION_TIMEOUT = 5.0   # seconds to verify broker reachability
-_NETWORKMAP_TIMEOUT = 300.0  # seconds to wait for the networkmap response (large meshes can be slow)
+# Fallback wait for the networkmap response. The effective value comes from
+# ``settings.zigbee_networkmap_timeout`` (env ZIGBEE_NETWORKMAP_TIMEOUT), read at
+# call time so an operator with a large mesh can raise it without a code change.
+_NETWORKMAP_TIMEOUT = 300.0
 
-
-def _sanitize_mqtt_error(exc: BaseException) -> str:
-    """Return a generic, credential-free message for an MQTT error.
-
-    The raw aiomqtt/paho error string can include the broker URI with
-    embedded credentials (e.g. ``mqtt://user:pass@host``) or auth-related
-    detail that should not leak to API clients. Map known patterns to
-    coarse categories; default to a generic failure message. The original
-    exception is logged at WARNING level for operator debugging.
-    """
-    logger.warning("MQTT error (sanitized for client): %r", exc)
-    raw = str(exc).lower()
-    if "not authoriz" in raw or "bad user" in raw or "bad username" in raw:
-        return "Authentication failed"
-    if "refused" in raw:
-        return "Connection refused by broker"
-    if "name or service not known" in raw or "getaddrinfo" in raw or "nodename nor servname" in raw:
-        return "Broker hostname could not be resolved"
-    if "ssl" in raw or "tls" in raw or "certificate" in raw:
-        return "TLS handshake failed"
-    if "timed out" in raw or "timeout" in raw:
-        return "Connection to broker timed out"
-    return "MQTT connection failed"
-
-
-def _build_tls_context(insecure: bool) -> ssl.SSLContext:
-    """Build an SSL context for MQTT TLS. If insecure, skip verification."""
-    ctx = ssl.create_default_context()
-    if insecure:
-        logger.warning(
-            "MQTT TLS certificate verification is DISABLED — "
-            "use only with self-signed brokers on trusted networks."
-        )
-        ctx.check_hostname = False
-        ctx.verify_mode = ssl.CERT_NONE
-    return ctx
+# Re-exported for backwards compatibility — these now live in mqtt_common.
+__all__ = ["_build_tls_context", "_sanitize_mqtt_error"]
 
 
 def build_zigbee_properties(
@@ -271,9 +242,14 @@ async def fetch_networkmap(
     password: str | None = None,
     tls: bool = False,
     tls_insecure: bool = False,
+    response_timeout: float | None = None,
 ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
     """Connect to the MQTT broker, request the Z2M networkmap, and return (nodes, edges).
 
+    ``response_timeout`` defaults to ``settings.zigbee_networkmap_timeout``
+    (env ``ZIGBEE_NETWORKMAP_TIMEOUT``, 300 s) — a 200+ device mesh can take
+    minutes to answer.
+
     Raises:
         TimeoutError: if the broker does not respond in time.
         ConnectionError: if the broker cannot be reached.
@@ -285,6 +261,14 @@ async def fetch_networkmap(
             "Install it with: pip install aiomqtt"
         )
 
+    timeout = (
+        float(settings.zigbee_networkmap_timeout)
+        if response_timeout is None
+        else response_timeout
+    )
+    if timeout <= 0:
+        timeout = _NETWORKMAP_TIMEOUT
+
     request_topic = _NETWORKMAP_REQUEST_TOPIC.format(base_topic=base_topic)
     response_topic = _NETWORKMAP_RESPONSE_TOPIC.format(base_topic=base_topic)
 
@@ -328,12 +312,15 @@ async def fetch_networkmap(
                         ) from exc
                     return
 
-            await asyncio.wait_for(_wait_for_response(), timeout=_NETWORKMAP_TIMEOUT)
+            await asyncio.wait_for(_wait_for_response(), timeout=timeout)
 
     except aiomqtt.MqttError as exc:
         raise ConnectionError(_sanitize_mqtt_error(exc)) from exc
     except asyncio.TimeoutError as exc:
-        raise TimeoutError("Timed out waiting for networkmap response") from exc
+        raise TimeoutError(
+            f"Timed out waiting for networkmap response after {timeout:g}s — "
+            "raise ZIGBEE_NETWORKMAP_TIMEOUT if your mesh is large"
+        ) from exc
 
     if not response_payload:
         raise ValueError("Empty networkmap response received")

backend/app/services/zwave_service.py

@@ -0,0 +1,235 @@
+"""Z-Wave JS UI (zwavejs2mqtt) service: fetch the node list via the MQTT gateway API.
+
+Mirrors the Zigbee pipeline. Z-Wave JS UI exposes a request/response gateway over
+MQTT: publish to ``<prefix>/_CLIENTS/ZWAVE_GATEWAY-<gateway>/api/getNodes/set`` and
+read the answer from ``<prefix>/_CLIENTS/ZWAVE_GATEWAY-<gateway>/api/getNodes``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.services.mqtt_common import request_response, test_connection
+from app.services.zigbee_service import _find_parent_router, merge_zigbee_properties
+
+logger = logging.getLogger(__name__)
+
+# Reuse the zigbee merge logic verbatim — same NodeProperty shape + visibility rules.
+merge_zwave_properties = merge_zigbee_properties
+
+_REQUEST_TOPIC = "{prefix}/_CLIENTS/ZWAVE_GATEWAY-{gateway}/api/getNodes/set"
+_RESPONSE_TOPIC = "{prefix}/_CLIENTS/ZWAVE_GATEWAY-{gateway}/api/getNodes"
+
+
+def _zwave_type_to_homelable(raw: dict[str, Any]) -> str:
+    """Map a Z-Wave node's role flags to a homelable node type.
+
+    Controller → coordinator. Mains-powered / routing nodes → router.
+    Everything else (battery sensors, etc.) → end device.
+    """
+    if raw.get("isControllerNode"):
+        return "zwave_coordinator"
+    if raw.get("isRouting"):
+        return "zwave_router"
+    return "zwave_enddevice"
+
+
+def _role_label(node_type: str) -> str:
+    """Human role string stored as ``device_subtype`` / ``device_type``."""
+    return {
+        "zwave_coordinator": "Controller",
+        "zwave_router": "Router",
+        "zwave_enddevice": "EndDevice",
+    }.get(node_type, "EndDevice")
+
+
+def _node_from_zwave(raw: dict[str, Any], home_id: str) -> dict[str, Any] | None:
+    """Build a homelable node dict from a Z-Wave JS UI ``getNodes`` entry."""
+    node_id = raw.get("id")
+    if node_id is None:
+        return None
+    ieee = f"zwave-{home_id}-{node_id}"
+    node_type = _zwave_type_to_homelable(raw)
+    name = raw.get("name") or raw.get("loc") or f"Node {node_id}"
+    model = raw.get("productLabel") or raw.get("productDescription") or None
+    vendor = raw.get("manufacturer") or None
+    return {
+        "id": ieee,
+        "label": name,
+        "type": node_type,
+        "ieee_address": ieee,
+        "friendly_name": name,
+        "device_type": _role_label(node_type),
+        "node_id": node_id,
+        "model": model,
+        "vendor": vendor,
+        "lqi": None,  # Z-Wave has no LQI; RSSI may be added later.
+        "parent_id": None,
+        "neighbors": raw.get("neighbors") or [],
+    }
+
+
+def _resolve_home_id(raw_nodes: list[dict[str, Any]]) -> str:
+    """Pick a home id for the network: prefer the controller's, else any node's."""
+    controller_home = None
+    for entry in raw_nodes:
+        if not isinstance(entry, dict):
+            continue
+        home = entry.get("homeId")
+        if home is None:
+            continue
+        if entry.get("isControllerNode"):
+            return str(home)
+        if controller_home is None:
+            controller_home = str(home)
+    return controller_home or "0"
+
+
+def parse_zwave_nodes(
+    payload: dict[str, Any],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Parse a Z-Wave JS UI ``getNodes`` response into (nodes, edges).
+
+    Expected shape::
+
+        {"success": true, "result": [ {<node>}, ... ]}
+
+    Edges are a strict coordinator → router → end-device tree, derived from
+    each node's ``neighbors`` list (same approach as the Zigbee parser).
+    """
+    if payload.get("success") is False:
+        raise ValueError("Z-Wave gateway reported failure")
+
+    result = payload.get("result")
+    if result is None:
+        result = []
+    if not isinstance(result, list):
+        raise ValueError("Malformed getNodes response: 'result' is not a list")
+
+    home_id = _resolve_home_id(result)
+
+    nodes_list: list[dict[str, Any]] = []
+    seen_ids: set[str] = set()
+    coordinator_id: str | None = None
+    # Map nodeId (int) → identity string, to translate neighbors → edges.
+    id_by_node_id: dict[Any, str] = {}
+
+    for entry in result:
+        if not isinstance(entry, dict):
+            continue
+        node = _node_from_zwave(entry, home_id)
+        if node is None or node["id"] in seen_ids:
+            continue
+        seen_ids.add(node["id"])
+        id_by_node_id[node["node_id"]] = node["id"]
+        nodes_list.append(node)
+        if node["type"] == "zwave_coordinator":
+            coordinator_id = node["id"]
+
+    # Translate neighbor lists into candidate edges (only between known nodes).
+    raw_edges: list[dict[str, Any]] = []
+    for node in nodes_list:
+        src = node["id"]
+        for neighbor in node.get("neighbors") or []:
+            tgt = id_by_node_id.get(neighbor)
+            if tgt and tgt != src:
+                raw_edges.append({"source": src, "target": tgt})
+
+    # Build parent_id hierarchy: coordinator → routers → end devices.
+    if coordinator_id:
+        router_ids = {n["id"] for n in nodes_list if n["type"] == "zwave_router"}
+        for node in nodes_list:
+            if node["type"] == "zwave_router":
+                node["parent_id"] = coordinator_id
+            elif node["type"] == "zwave_enddevice":
+                parent = _find_parent_router(node["id"], router_ids, raw_edges)
+                node["parent_id"] = parent or coordinator_id
+
+    # Final edges = strict parent → child tree (one edge per non-coordinator).
+    edges_list: list[dict[str, Any]] = [
+        {"source": node["parent_id"], "target": node["id"]}
+        for node in nodes_list
+        if node.get("parent_id")
+    ]
+
+    # Drop transient helper keys before returning.
+    for node in nodes_list:
+        node.pop("neighbors", None)
+        node.pop("node_id", None)
+
+    return nodes_list, edges_list
+
+
+def build_zwave_properties(
+    ieee: str | None,
+    vendor: str | None,
+    model: str | None,
+) -> list[dict[str, Any]]:
+    """Build a NodeProperty list for a Z-Wave device (Identity, Vendor, Model).
+
+    Z-Wave has no LQI, so that row is omitted. New props default to
+    ``visible=False`` — users opt in from the right panel.
+    """
+    props: list[dict[str, Any]] = []
+    if ieee:
+        props.append({"key": "Z-Wave ID", "value": ieee, "icon": None, "visible": False})
+    if vendor:
+        props.append({"key": "Vendor", "value": vendor, "icon": None, "visible": False})
+    if model:
+        props.append({"key": "Model", "value": model, "icon": None, "visible": False})
+    return props
+
+
+async def fetch_zwave_network(
+    mqtt_host: str,
+    mqtt_port: int,
+    prefix: str = "zwave",
+    gateway_name: str = "zwavejs2mqtt",
+    username: str | None = None,
+    password: str | None = None,
+    tls: bool = False,
+    tls_insecure: bool = False,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Connect to the broker, request the Z-Wave node list, return (nodes, edges).
+
+    Raises:
+        TimeoutError: if the gateway does not respond in time.
+        ConnectionError: if the broker cannot be reached.
+        ValueError: if the response payload is malformed.
+    """
+    request_topic = _REQUEST_TOPIC.format(prefix=prefix, gateway=gateway_name)
+    response_topic = _RESPONSE_TOPIC.format(prefix=prefix, gateway=gateway_name)
+
+    payload = await request_response(
+        mqtt_host=mqtt_host,
+        mqtt_port=mqtt_port,
+        request_topic=request_topic,
+        response_topic=response_topic,
+        request_payload={"args": []},
+        username=username,
+        password=password,
+        tls=tls,
+        tls_insecure=tls_insecure,
+    )
+
+    return parse_zwave_nodes(payload)
+
+
+async def test_zwave_connection(
+    mqtt_host: str,
+    mqtt_port: int,
+    username: str | None = None,
+    password: str | None = None,
+    tls: bool = False,
+    tls_insecure: bool = False,
+) -> bool:
+    """Quick MQTT reachability check for the Z-Wave broker."""
+    return await test_connection(
+        mqtt_host=mqtt_host,
+        mqtt_port=mqtt_port,
+        username=username,
+        password=password,
+        tls=tls,
+        tls_insecure=tls_insecure,
+    )

backend/requirements.txt

@@ -6,16 +6,18 @@ 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
-python-multipart==0.0.27
+authlib==1.7.2
+itsdangerous==2.2.0
+python-multipart==0.0.31
 apscheduler==3.10.4
 python-nmap==0.7.1
 pyyaml==6.0.2
 types-PyYAML==6.0.12.20240917
 websockets==13.1
 httpx==0.27.2
-zeroconf==0.131.0
+zeroconf==0.149.16
 aiomqtt==2.3.0
 
 # Dev

backend/tests/conftest.py

@@ -1,3 +1,4 @@
+import importlib
 import os
 
 # Must be set before any app import so pydantic-settings can resolve the required field.
@@ -8,7 +9,7 @@ from httpx import ASGITransport, AsyncClient
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 
 from app.core.security import hash_password
-from app.db.database import Base, get_db
+from app.db.database import DOCUMENT_DDL, Base, _try_migrate, get_db
 from app.main import app
 
 TEST_DB_URL = "sqlite+aiosqlite:///:memory:"
@@ -27,9 +28,38 @@ async def db_session():
     engine = create_async_engine(TEST_DB_URL)
     async with engine.begin() as conn:
         await conn.run_sync(Base.metadata.create_all)
+        # Apply the same documents DDL init_db does, through the same helper, so
+        # the suite matches boot. `_try_migrate` matters here: on a database
+        # create_all has just built, every ALTER in that list is a no-op that
+        # raises "duplicate column" — swallowing it is the point, not a leniency.
+        for label, sql in DOCUMENT_DDL:
+            await _try_migrate(conn, sql, label=label)
     session_factory = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+    # Background tasks open their own session through `AsyncSessionLocal` — the
+    # request-scoped `get_db` override does not reach them. Left alone they would
+    # run against the *real* configured database, so point the factory at the
+    # test engine everywhere it was imported by name.
+    patched = [
+        importlib.import_module(name)
+        for name in (
+            "app.db.database",
+            "app.api.routes.zigbee",
+            "app.api.routes.zwave",
+            "app.api.routes.proxmox",
+            "app.api.routes.scan",
+        )
+    ]
+    originals = [
+        (module, getattr(module, "AsyncSessionLocal", None)) for module in patched
+    ]
+    for module, original in originals:
+        if original is not None:
+            module.AsyncSessionLocal = session_factory
     async with session_factory() as session:
         yield session
+    for module, original in originals:
+        if original is not None:
+            module.AsyncSessionLocal = original
     async with engine.begin() as conn:
         await conn.run_sync(Base.metadata.drop_all)
     await engine.dispose()
@@ -44,10 +74,17 @@ 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']}"}
+
+
+@pytest.fixture(autouse=True)
+def _reset_doc_search_probe():
+    """Forget whether FTS5 was available — each test gets a fresh database."""
+    from app.services import doc_search
+
+    doc_search.reset_availability_cache()
+    yield
+    doc_search.reset_availability_cache()

backend/tests/migrations/test_legacy_designs.py

@@ -0,0 +1,156 @@
+"""Backward-compatibility tests for the legacy → multi-design migration.
+
+Simulates a database created by a pre-"designs" version of the app and asserts
+that running init_db() adopts all existing nodes/edges/canvas into a single
+default "Network Topology" design with no data loss. The rest of the test suite
+builds the *current* schema via create_all and never exercises this upgrade
+path, so this file guards real users upgrading in place.
+"""
+import os
+
+os.environ.setdefault("SECRET_KEY", "test-only-secret-key-not-for-production")
+
+import pytest
+from sqlalchemy.ext.asyncio import create_async_engine
+
+import app.db.database as database
+
+
+@pytest.fixture
+def legacy_engine(tmp_path, monkeypatch):
+    """Point the module-global engine + sqlite_path at a throwaway legacy DB."""
+    db_path = tmp_path / "legacy.db"
+    monkeypatch.setattr(database.settings, "sqlite_path", str(db_path))
+    engine = create_async_engine(f"sqlite+aiosqlite:///{db_path}")
+    monkeypatch.setattr(database, "engine", engine)
+    return db_path, engine
+
+
+async def _build_legacy_schema(engine) -> None:
+    """Create the pre-designs schema (no design_id, integer canvas_state PK)."""
+    async with engine.begin() as conn:
+        await conn.exec_driver_sql(
+            "CREATE TABLE nodes (id VARCHAR PRIMARY KEY, type VARCHAR, label VARCHAR, "
+            "status VARCHAR, services JSON, pos_x FLOAT, pos_y FLOAT)"
+        )
+        await conn.exec_driver_sql(
+            "CREATE TABLE edges (id VARCHAR PRIMARY KEY, source VARCHAR, target VARCHAR, type VARCHAR)"
+        )
+        await conn.exec_driver_sql(
+            "CREATE TABLE canvas_state (id INTEGER PRIMARY KEY, viewport JSON, "
+            "custom_style JSON, saved_at DATETIME)"
+        )
+        await conn.exec_driver_sql(
+            "INSERT INTO nodes (id, type, label, status, services, pos_x, pos_y) "
+            "VALUES ('n1','server','Old Server','online','[]',10,20)"
+        )
+        await conn.exec_driver_sql(
+            "INSERT INTO nodes (id, type, label, status, services, pos_x, pos_y) "
+            "VALUES ('n2','router','Old Router','offline','[]',30,40)"
+        )
+        await conn.exec_driver_sql(
+            "INSERT INTO edges (id, source, target, type) VALUES ('e1','n1','n2','ethernet')"
+        )
+        await conn.exec_driver_sql(
+            "INSERT INTO canvas_state (id, viewport, custom_style, saved_at) "
+            "VALUES (1, '{\"x\":5,\"y\":6,\"zoom\":2}', NULL, '2024-01-01 00:00:00')"
+        )
+
+
+async def test_legacy_canvas_migrates_into_default_design(legacy_engine):
+    db_path, engine = legacy_engine
+    await _build_legacy_schema(engine)
+
+    await database.init_db()
+
+    check = create_async_engine(f"sqlite+aiosqlite:///{db_path}")
+    try:
+        async with check.begin() as conn:
+            # Exactly one seeded default design.
+            designs = (await conn.exec_driver_sql(
+                "SELECT id, name, design_type, icon FROM designs"
+            )).fetchall()
+            assert len(designs) == 1
+            did, name, dtype, icon = designs[0]
+            assert name == "Network Topology"
+            assert dtype == "network"
+            assert icon == "dashboard"
+
+            # Every legacy node adopted into the default design, data preserved.
+            nodes = (await conn.exec_driver_sql(
+                "SELECT id, label, status, design_id FROM nodes ORDER BY id"
+            )).fetchall()
+            assert [(n[0], n[1], n[2]) for n in nodes] == [
+                ("n1", "Old Server", "online"),
+                ("n2", "Old Router", "offline"),
+            ]
+            assert all(n[3] == did for n in nodes)
+
+            # Legacy edge adopted too.
+            edge = (await conn.exec_driver_sql(
+                "SELECT design_id FROM edges WHERE id='e1'"
+            )).fetchone()
+            assert edge[0] == did
+
+            # canvas_state rebuilt with design_id PK; the old id=1 row maps to the
+            # default design and the viewport survives.
+            cs = (await conn.exec_driver_sql(
+                "SELECT design_id, viewport FROM canvas_state"
+            )).fetchall()
+            assert len(cs) == 1
+            assert cs[0][0] == did
+            assert "zoom" in (cs[0][1] or "")
+    finally:
+        await check.dispose()
+        await engine.dispose()
+
+
+async def test_legacy_nodes_gain_last_scan_column(legacy_engine):
+    """A legacy nodes table (no last_scan) gains the column after init_db."""
+    db_path, engine = legacy_engine
+    await _build_legacy_schema(engine)
+
+    await database.init_db()
+
+    check = create_async_engine(f"sqlite+aiosqlite:///{db_path}")
+    try:
+        async with check.begin() as conn:
+            cols = (await conn.exec_driver_sql("PRAGMA table_info(nodes)")).fetchall()
+            assert "last_scan" in {c[1] for c in cols}
+            # Existing rows backfill to NULL (never scanned yet).
+            last_scan = (await conn.exec_driver_sql(
+                "SELECT last_scan FROM nodes WHERE id='n1'"
+            )).fetchone()
+            assert last_scan[0] is None
+    finally:
+        await check.dispose()
+        await engine.dispose()
+
+
+async def test_migration_is_idempotent(legacy_engine):
+    """Running init_db twice must not duplicate the design or drop any data."""
+    db_path, engine = legacy_engine
+    await _build_legacy_schema(engine)
+
+    await database.init_db()
+    await database.init_db()  # second boot — should be a no-op
+
+    check = create_async_engine(f"sqlite+aiosqlite:///{db_path}")
+    try:
+        async with check.begin() as conn:
+            designs = (await conn.exec_driver_sql("SELECT id FROM designs")).fetchall()
+            assert len(designs) == 1
+            did = designs[0][0]
+
+            nodes = (await conn.exec_driver_sql(
+                "SELECT design_id FROM nodes"
+            )).fetchall()
+            assert len(nodes) == 2
+            assert all(n[0] == did for n in nodes)
+
+            cs = (await conn.exec_driver_sql("SELECT design_id FROM canvas_state")).fetchall()
+            assert len(cs) == 1
+            assert cs[0][0] == did
+    finally:
+        await check.dispose()
+        await engine.dispose()

backend/tests/migrations/test_legacy_node_columns.py

@@ -0,0 +1,491 @@
+"""The 3.2.0 → 3.3.0 upgrade of the `nodes` table.
+
+3.3.0 moved the device facts off `nodes` onto `device_inventory` and dropped the
+columns. A real 3.2.0 database declares several of them NOT NULL with no
+server-side default (`status`, `services`, `properties`, `show_hardware`) — the
+schema here is `create_all`'s output at tag v3.2.0, not a hand-simplified copy,
+because that constraint is exactly what breaks: the 3.3.0 model no longer writes
+those columns, so if they survive the upgrade every INSERT fails with
+``NOT NULL constraint failed: nodes.status`` and approving a device is dead.
+"""
+import os
+import shutil
+
+os.environ.setdefault("SECRET_KEY", "test-only-secret-key-not-for-production")
+
+import pytest
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import create_async_engine
+
+import app.db.database as database
+import app.services.inventory_sync as inventory_sync
+
+# `create_all` under v3.2.0. NOT NULL is reproduced exactly where it was.
+_NODES_320 = (
+    "CREATE TABLE nodes ("
+    "id VARCHAR NOT NULL PRIMARY KEY, type VARCHAR NOT NULL, label VARCHAR NOT NULL, "
+    "design_id VARCHAR, hostname VARCHAR, ip VARCHAR, mac VARCHAR, os VARCHAR, "
+    "status VARCHAR NOT NULL, check_method VARCHAR, check_target VARCHAR, "
+    "services JSON NOT NULL, notes TEXT, pos_x FLOAT NOT NULL, pos_y FLOAT NOT NULL, "
+    "parent_id VARCHAR, container_mode BOOLEAN NOT NULL, custom_colors JSON, "
+    "custom_icon VARCHAR, cpu_count INTEGER, cpu_model VARCHAR, ram_gb FLOAT, "
+    "disk_gb FLOAT, show_hardware BOOLEAN NOT NULL, show_port_numbers BOOLEAN NOT NULL, "
+    "properties JSON NOT NULL, width FLOAT, height FLOAT, "
+    "bottom_handles INTEGER NOT NULL, top_handles INTEGER NOT NULL, "
+    "left_handles INTEGER NOT NULL, right_handles INTEGER NOT NULL, "
+    "ieee_address VARCHAR, last_seen DATETIME, last_scan DATETIME, "
+    "response_time_ms INTEGER, created_at DATETIME NOT NULL, updated_at DATETIME NOT NULL)"
+)
+
+_DESIGNS_320 = (
+    "CREATE TABLE designs (id VARCHAR NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, "
+    "design_type VARCHAR NOT NULL, icon VARCHAR, created_at DATETIME NOT NULL, "
+    "updated_at DATETIME NOT NULL)"
+)
+
+
+def _node_sql(node_id: str, label: str, node_type: str, ip: str | None) -> str:
+    ip_sql = f"'{ip}'" if ip else "NULL"
+    return (
+        "INSERT INTO nodes (id, type, label, design_id, ip, status, services, pos_x, pos_y, "
+        "container_mode, show_hardware, show_port_numbers, properties, bottom_handles, "
+        "top_handles, left_handles, right_handles, created_at, updated_at) VALUES "
+        f"('{node_id}', '{node_type}', '{label}', 'd1', {ip_sql}, 'online', '[]', 0, 0, "
+        "0, 0, 0, '[]', 1, 1, 0, 0, '2026-01-01 00:00:00', '2026-01-01 00:00:00')"
+    )
+
+
+@pytest.fixture
+def db_320(tmp_path, monkeypatch):
+    """A v3.2.0 database, with the module-global engine pointed at it."""
+    db_path = tmp_path / "v320.db"
+    monkeypatch.setattr(database.settings, "sqlite_path", str(db_path))
+    engine = create_async_engine(f"sqlite+aiosqlite:///{db_path}")
+    monkeypatch.setattr(database, "engine", engine)
+    monkeypatch.setattr(
+        database, "AsyncSessionLocal", database.async_sessionmaker(engine, expire_on_commit=False)
+    )
+    return db_path, engine
+
+
+async def _build_320(engine) -> None:
+    async with engine.begin() as conn:
+        await conn.exec_driver_sql(_DESIGNS_320)
+        await conn.exec_driver_sql(_NODES_320)
+        await conn.exec_driver_sql(
+            "INSERT INTO designs (id, name, design_type, icon, created_at, updated_at) "
+            "VALUES ('d1', 'Network Topology', 'network', 'dashboard', "
+            "'2026-01-01 00:00:00', '2026-01-01 00:00:00')"
+        )
+        await conn.exec_driver_sql(_node_sql("n1", "OpnSense", "firewall", "192.168.1.1"))
+        await conn.exec_driver_sql(_node_sql("n2", "NAS", "nas", "192.168.1.2"))
+        await conn.exec_driver_sql(_node_sql("n3", "a note", "text", None))
+
+
+async def _insert_node(engine) -> None:
+    """What approve does: insert a node the way the 3.3.0 model writes one."""
+    from app.db.models import Node
+
+    session_factory = database.async_sessionmaker(engine, expire_on_commit=False)
+    async with session_factory() as session:
+        session.add(Node(id="new", type="firewall", label="Approved", design_id="d1"))
+        await session.commit()
+
+
+async def test_upgrade_drops_the_device_columns_and_leaves_nodes_insertable(db_320):
+    db_path, engine = db_320
+    await _build_320(engine)
+
+    await database.init_db()
+
+    check = create_async_engine(f"sqlite+aiosqlite:///{db_path}")
+    try:
+        async with check.begin() as conn:
+            cols = {c[1] for c in (await conn.exec_driver_sql("PRAGMA table_info(nodes)")).fetchall()}
+            assert "status" not in cols
+            assert "ip" not in cols
+            assert "device_id" in cols
+            # Every device node linked; the facts moved to the inventory row.
+            linked = (await conn.exec_driver_sql(
+                "SELECT label, device_id FROM nodes ORDER BY id"
+            )).fetchall()
+            assert [row[0] for row in linked] == ["OpnSense", "NAS", "a note"]
+            assert linked[0][1] and linked[1][1]
+            assert linked[2][1] is None  # canvas furniture keeps no row
+            ips = (await conn.exec_driver_sql(
+                "SELECT ip FROM device_inventory ORDER BY ip"
+            )).fetchall()
+            assert [row[0] for row in ips] == ["192.168.1.1", "192.168.1.2"]
+
+        await _insert_node(engine)
+    finally:
+        await check.dispose()
+        await engine.dispose()
+
+
+async def test_a_node_the_backfill_cannot_link_still_leaves_nodes_insertable(db_320, monkeypatch):
+    """The regression: a failed backfill must not brick every later INSERT.
+
+    Before the fix, one unlinkable node kept `nodes.status` NOT NULL while the
+    3.3.0 model stopped writing it, so approving *any* device raised
+    ``NOT NULL constraint failed: nodes.status`` (issue #351).
+    """
+    db_path, engine = db_320
+    await _build_320(engine)
+
+    real_link_facts = inventory_sync.link_facts
+
+    async def link_facts(db, node, facts, **kwargs):
+        if node.id == "n2":
+            raise IntegrityError("boom", None, Exception("UNIQUE constraint failed"))
+        return await real_link_facts(db, node, facts, **kwargs)
+
+    monkeypatch.setattr(inventory_sync, "link_facts", link_facts)
+
+    await database.init_db()
+
+    check = create_async_engine(f"sqlite+aiosqlite:///{db_path}")
+    try:
+        async with check.begin() as conn:
+            info = (await conn.exec_driver_sql("PRAGMA table_info(nodes)")).fetchall()
+            cols = {c[1]: c for c in info}
+            # The columns stay — they are the only remaining copy of n2's facts.
+            assert "status" in cols
+            # But nothing is NOT NULL any more, so the model can insert again.
+            assert not any(c[3] for name, c in cols.items() if name in database._LEGACY_NODE_COLUMNS)
+            # Values preserved by the rebuild.
+            kept = (await conn.exec_driver_sql(
+                "SELECT status, ip FROM nodes WHERE id='n2'"
+            )).fetchone()
+            assert kept == ("online", "192.168.1.2")
+            # The node that did link is linked; the failed one is not.
+            linked = dict((await conn.exec_driver_sql(
+                "SELECT id, device_id FROM nodes"
+            )).fetchall())
+            assert linked["n1"] is not None
+            assert linked["n2"] is None
+
+        await _insert_node(engine)
+
+        # A boot where the failure persists changes nothing further: the relax is
+        # a one-off, not a rebuild on every start.
+        await database.init_db()
+        async with check.begin() as conn:
+            kept = (await conn.exec_driver_sql(
+                "SELECT status, ip FROM nodes WHERE id='n2'"
+            )).fetchone()
+            assert kept == ("online", "192.168.1.2")
+            assert (await conn.exec_driver_sql(
+                "SELECT COUNT(*) FROM nodes"
+            )).scalar() == 4  # the three seeded, plus the one just approved
+
+        # A later boot retries the backfill: with the failure gone, n2 links and
+        # the columns finally drop.
+        monkeypatch.setattr(inventory_sync, "link_facts", real_link_facts)
+        await database.init_db()
+        async with check.begin() as conn:
+            cols = {c[1] for c in (await conn.exec_driver_sql("PRAGMA table_info(nodes)")).fetchall()}
+            assert "status" not in cols
+    finally:
+        await check.dispose()
+        await engine.dispose()
+
+
+async def test_upgrade_keeps_each_canvas_drawing_its_own_services(db_320):
+    """3.3.3: order and visibility become the node's, and the upgrade freezes them.
+
+    Two canvases drew the same host with different service lists, and a scan had
+    already fingerprinted a third the user put on neither. All three converge on
+    one inventory row — so each node must come out of the upgrade still drawing
+    what it drew, with the scanner's guess hidden on both.
+    """
+    db_path, engine = db_320
+    await _build_320(engine)
+    ssh = '[{"port": 22, "protocol": "tcp", "service_name": "ssh"}]'
+    both = '[{"port": 22, "protocol": "tcp", "service_name": "ssh"}, ' \
+           '{"port": 443, "protocol": "tcp", "service_name": "https"}]'
+    async with engine.begin() as conn:
+        await conn.exec_driver_sql(f"UPDATE nodes SET services = '{ssh}' WHERE id = 'n1'")
+        await conn.exec_driver_sql(f"UPDATE nodes SET services = '{both}' WHERE id = 'n2'")
+
+    await database.init_db()
+
+    from app.db.models import InventoryDevice, Node
+
+    session_factory = database.async_sessionmaker(engine, expire_on_commit=False)
+    async with session_factory() as session:
+        drawn = {}
+        for node_id in ("n1", "n2"):
+            node = await session.get(Node, node_id)
+            device = await session.get(InventoryDevice, node.device_id)
+            payload = inventory_sync.hydrated_node(node, device)
+            drawn[node_id] = [s["service_name"] for s in payload["services"] if s.get("visible", True)]
+            # Seeded, not left to "show the whole row".
+            assert node.display_view is not None
+        assert drawn == {"n1": ["ssh"], "n2": ["ssh", "https"]}
+
+        # What a scan finds next lands on the row, and on no canvas.
+        node = await session.get(Node, "n1")
+        device = await session.get(InventoryDevice, node.device_id)
+        device.services = [
+            *device.services,
+            {"port": 3001, "protocol": "tcp", "service_name": "Uptime Kuma"},
+        ]
+        await session.commit()
+        payload = inventory_sync.hydrated_node(node, device)
+        assert [(s["service_name"], s.get("visible", True)) for s in payload["services"]] == [
+            ("ssh", True), ("Uptime Kuma", False),
+        ]
+    await engine.dispose()
+
+
+async def _wind_back_to_3_3_2(engine, extra_service: dict) -> None:
+    """A database that already took the 3.3.0 upgrade, leak included.
+
+    Both nodes point at one row holding the union of what each drew plus what a
+    scan found, and neither has a view — which is every 3.3.0-3.3.2 install.
+    """
+    from app.db.models import InventoryDevice, Node
+
+    async with engine.begin() as conn:
+        await conn.exec_driver_sql("UPDATE nodes SET display_view = NULL")
+    session_factory = database.async_sessionmaker(engine, expire_on_commit=False)
+    async with session_factory() as session:
+        node = await session.get(Node, "n1")
+        one = await session.get(InventoryDevice, node.device_id)
+        other = await session.get(InventoryDevice, (await session.get(Node, "n2")).device_id)
+        for device in (one, other):
+            device.services = [
+                {"port": 22, "protocol": "tcp", "service_name": "ssh"},
+                {"port": 443, "protocol": "tcp", "service_name": "https"},
+                extra_service,
+            ]
+        await session.commit()
+
+
+async def test_a_database_already_on_3_3_recovers_its_layout_from_the_backup(db_320):
+    """The second upgrade path: 3.3.0-3.3.2, where the legacy columns are gone.
+
+    3.3.0 unioned every canvas' services onto one row, so the row can no longer
+    say who drew what — but the backup taken before that migration still can.
+    Recovering from it is the difference between the user getting their canvases
+    back and getting each canvas showing every other canvas' services.
+    """
+    _, engine = db_320
+    await _build_320(engine)
+    ssh = '[{"port": 22, "protocol": "tcp", "service_name": "ssh"}]'
+    both = '[{"port": 22, "protocol": "tcp", "service_name": "ssh"}, ' \
+           '{"port": 443, "protocol": "tcp", "service_name": "https"}]'
+    async with engine.begin() as conn:
+        await conn.exec_driver_sql(f"UPDATE nodes SET services = '{ssh}' WHERE id = 'n1'")
+        await conn.exec_driver_sql(f"UPDATE nodes SET services = '{both}' WHERE id = 'n2'")
+
+    await database.init_db()  # 3.2.0 -> 3.3.x, and the backup that predates it.
+    kuma = {"port": 3001, "protocol": "tcp", "service_name": "Uptime Kuma"}
+    await _wind_back_to_3_3_2(engine, kuma)
+
+    await database.init_db()
+
+    from app.db.models import InventoryDevice, Node
+
+    session_factory = database.async_sessionmaker(engine, expire_on_commit=False)
+    async with session_factory() as session:
+        drawn = {}
+        for node_id in ("n1", "n2"):
+            node = await session.get(Node, node_id)
+            device = await session.get(InventoryDevice, node.device_id)
+            payload = inventory_sync.hydrated_node(node, device)
+            drawn[node_id] = [s["service_name"] for s in payload["services"] if s.get("visible", True)]
+        assert drawn == {"n1": ["ssh"], "n2": ["ssh", "https"]}
+    await engine.dispose()
+
+
+async def test_a_property_added_while_on_3_3_survives_the_recovery(db_320):
+    """The backup is 3.2.0-era and cannot know what the user added afterwards.
+
+    On 3.3.0-3.3.2 the row was the only place to add a property, and every
+    canvas drew it. Recovering the view strictly from the backup would hide it
+    on all of them at once — the "my properties disappeared" half of #347. The
+    scanner's service find is still held back: only properties are appended.
+    """
+    _, engine = db_320
+    await _build_320(engine)
+    rack = '[{"key": "Rack", "value": "A", "icon": null, "visible": true}]'
+    ssh = '[{"port": 22, "protocol": "tcp", "service_name": "ssh"}]'
+    async with engine.begin() as conn:
+        await conn.exec_driver_sql(
+            f"UPDATE nodes SET properties = '{rack}', services = '{ssh}' WHERE id = 'n1'"
+        )
+
+    await database.init_db()  # 3.2.0 -> 3.3.x, and the backup that predates it.
+    kuma = {"port": 3001, "protocol": "tcp", "service_name": "Uptime Kuma"}
+    await _wind_back_to_3_3_2(engine, kuma)
+
+    from app.db.models import InventoryDevice, Node
+
+    session_factory = database.async_sessionmaker(engine, expire_on_commit=False)
+    async with session_factory() as session:
+        node = await session.get(Node, "n1")
+        device = await session.get(InventoryDevice, node.device_id)
+        # What the user re-added by hand while running 3.3.x.
+        device.properties = [
+            *device.properties,
+            {"key": "Ports", "value": "8", "icon": None, "visible": True},
+        ]
+        await session.commit()
+
+    await database.init_db()
+
+    async with session_factory() as session:
+        node = await session.get(Node, "n1")
+        device = await session.get(InventoryDevice, node.device_id)
+        payload = inventory_sync.hydrated_node(node, device)
+        assert [(p["key"], p.get("visible", True)) for p in payload["properties"]] == [
+            ("Rack", True), ("Ports", True),
+        ]
+        # And the scan's find is still off this canvas.
+        assert [s["service_name"] for s in payload["services"] if s.get("visible", True)] == ["ssh"]
+    await engine.dispose()
+
+
+async def test_without_a_usable_backup_the_row_is_the_seed(db_320):
+    """No backup to recover from: keep showing what the canvas shows today.
+
+    Nothing is taken away — the user simply keeps the merged list they have been
+    looking at since 3.3.0, and only what the row gains *after* this boot is
+    held back.
+    """
+    db_path, engine = db_320
+    await _build_320(engine)
+    await database.init_db()
+    kuma = {"port": 3001, "protocol": "tcp", "service_name": "Uptime Kuma"}
+    await _wind_back_to_3_3_2(engine, kuma)
+    for backup in db_path.parent.glob(f"{db_path.name}.back-*"):
+        backup.unlink()
+
+    await database.init_db()
+
+    from app.db.models import InventoryDevice, Node
+
+    session_factory = database.async_sessionmaker(engine, expire_on_commit=False)
+    async with session_factory() as session:
+        node = await session.get(Node, "n1")
+        device = await session.get(InventoryDevice, node.device_id)
+        payload = inventory_sync.hydrated_node(node, device)
+        assert [s["service_name"] for s in payload["services"]] == ["ssh", "https", "Uptime Kuma"]
+        assert all(s.get("visible", True) for s in payload["services"])
+
+        # From here on the node is pinned: the next scan's find is held back.
+        device.services = [*device.services, {"port": 5001, "protocol": "tcp", "service_name": "Synology DSM HTTPS"}]
+        await session.commit()
+        payload = inventory_sync.hydrated_node(node, device)
+        assert [s["service_name"] for s in payload["services"] if not s.get("visible", True)] == [
+            "Synology DSM HTTPS"
+        ]
+    await engine.dispose()
+
+
+async def test_the_newest_backup_that_still_has_the_columns_is_the_one_read(db_320):
+    """A 3.3.2 install has several backups; only some can answer.
+
+    `homelab.db.back-3.3.1` and `-3.3.2` were taken *after* the split and hold
+    nothing per node; `-3.3.0` was taken before it. Reading the wrong one would
+    either say nothing or resurrect a much older canvas.
+    """
+    db_path, engine = db_320
+    await _build_320(engine)
+    async with engine.begin() as conn:
+        await conn.exec_driver_sql(
+            "UPDATE nodes SET services = "
+            "'[{\"port\": 22, \"protocol\": \"tcp\", \"service_name\": \"ssh\"}]' WHERE id = 'n1'"
+        )
+    # Ancient: same shape, but a canvas the user has long since moved on from.
+    old = db_path.parent / f"{db_path.name}.back-3.1.0"
+    shutil.copy2(db_path, old)
+    os.utime(old, (1, 1))
+    async with engine.begin() as conn:
+        await conn.exec_driver_sql(
+            "UPDATE nodes SET services = "
+            "'[{\"port\": 443, \"protocol\": \"tcp\", \"service_name\": \"https\"}]' WHERE id = 'n1'"
+        )
+    pre_split = db_path.parent / f"{db_path.name}.back-3.3.0"
+    shutil.copy2(db_path, pre_split)
+
+    await database.init_db()  # drops the columns, and backs up under this version
+    # Post-split backups: newer, and unable to say who drew what.
+    for name in ("back-3.3.1", "back-3.3.2"):
+        shutil.copy2(db_path, db_path.parent / f"{db_path.name}.{name}")
+
+    assert database._pre_split_backup() == pre_split
+    assert database._views_from_backup()["n1"]["services"] == [
+        {"port": 443, "protocol": "tcp", "service_name": "https"}
+    ]
+    await engine.dispose()
+
+
+async def test_a_furniture_description_survives_the_column_drop(db_320, monkeypatch):
+    """The rebuild copies a fixed column list — `description` has to be on it.
+
+    `_drop_legacy_node_columns` recreates `nodes` from `_NODE_COLUMNS_SQL` /
+    `_NODE_KEPT`. A column missing from those two strings is silently lost on the
+    boot that finally drops the legacy ones, which is exactly the boot a user who
+    wrote a zone description in the meantime would not expect to lose it.
+    """
+    db_path, engine = db_320
+    await _build_320(engine)
+
+    real_link_facts = inventory_sync.link_facts
+
+    async def link_facts(db, node, facts, **kwargs):
+        if node.id == "n2":
+            raise IntegrityError("boom", None, Exception("UNIQUE constraint failed"))
+        return await real_link_facts(db, node, facts, **kwargs)
+
+    monkeypatch.setattr(inventory_sync, "link_facts", link_facts)
+
+    # First boot: the backfill cannot finish, so the legacy columns stay.
+    await database.init_db()
+
+    check = create_async_engine(f"sqlite+aiosqlite:///{db_path}")
+    try:
+        async with check.begin() as conn:
+            cols = {c[1] for c in (await conn.exec_driver_sql("PRAGMA table_info(nodes)")).fetchall()}
+            assert "description" in cols
+            assert "status" in cols  # legacy still there
+            # The user describes a piece of furniture.
+            await conn.exec_driver_sql(
+                "UPDATE nodes SET description = 'Behind the garage door.' WHERE id = 'n3'"
+            )
+
+        # Second boot: the backfill succeeds and the legacy columns finally go.
+        monkeypatch.setattr(inventory_sync, "link_facts", real_link_facts)
+        await database.init_db()
+
+        async with check.begin() as conn:
+            cols = {c[1] for c in (await conn.exec_driver_sql("PRAGMA table_info(nodes)")).fetchall()}
+            assert "status" not in cols
+            assert "description" in cols
+            kept = (await conn.exec_driver_sql(
+                "SELECT description FROM nodes WHERE id = 'n3'"
+            )).scalar()
+            assert kept == "Behind the garage door."
+    finally:
+        await check.dispose()
+        await engine.dispose()
+
+
+async def test_the_description_column_is_added_once_and_is_idempotent(db_320):
+    db_path, engine = db_320
+    await _build_320(engine)
+
+    await database.init_db()
+    await database.init_db()
+
+    check = create_async_engine(f"sqlite+aiosqlite:///{db_path}")
+    try:
+        async with check.begin() as conn:
+            info = (await conn.exec_driver_sql("PRAGMA table_info(nodes)")).fetchall()
+            assert [c[1] for c in info].count("description") == 1
+    finally:
+        await check.dispose()
+        await engine.dispose()

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,83 @@
+"""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, device_id=None) -> Node:
+    """A canvas node. Addresses belong to the inventory row it draws, so pass
+    `device_id`, or let `_node_for` mint the row from the addresses."""
+    return Node(
+        id=str(uuid.uuid4()), label="n", type="server", pos_x=0.0, pos_y=0.0,
+        design_id=design_id, device_id=device_id,
+    )
+
+
+async def _node_for(db_session, design_id: str, *, ip=None, ieee=None, mac=None, **device_kwargs) -> Node:
+    """A node plus the inventory row carrying its addresses, linked.
+
+    Reuses a row that already describes these addresses — one device is one row,
+    so a test placing the same host on a second canvas gets a second node, not a
+    second device.
+    """
+    from app.services.inventory_sync import find_device_for
+
+    device = await find_device_for(db_session, ip=ip, mac=mac, ieee=ieee)
+    if device is None:
+        device = InventoryDevice(
+            id=str(uuid.uuid4()), ip=ip, mac=mac, ieee_address=ieee,
+            status="approved", status_live="online", **device_kwargs,
+        )
+        db_session.add(device)
+        await db_session.flush()
+    node = _node(design_id, device_id=device.id)
+    db_session.add(node)
+    await db_session.commit()
+    return node
+
+
+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_device = InventoryDevice(
+        ieee_address="0xCOORD",
+        friendly_name="Coordinator",
+        suggested_type="zigbee_coordinator",
+        status="approved",
+    )
+    db_session.add(coord_device)
+    await db_session.flush()
+    coord = Node(
+        label="Coordinator",
+        type="zigbee_coordinator",
+        device_id=coord_device.id,
+    )
+    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,738 @@
+"""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_for
+
+
+@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".
+    await _node_for(db_session, 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()
+    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.flush()
+    # The node already on this design draws that very row.
+    existing = Node(
+        label="sensor", type="zigbee_enddevice", device_id=device.id, design_id=design.id,
+    )
+    db_session.add(existing)
+    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).join(InventoryDevice, Node.device_id == InventoryDevice.id).where(InventoryDevice.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()
+    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.flush()
+    db_session.add(Node(
+        label="sensor", type="zigbee_enddevice", device_id=device.id, design_id=design.id,
+    ))
+    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).join(InventoryDevice, Node.device_id == InventoryDevice.id).where(InventoryDevice.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 = await _node_for(db_session, 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},
+        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")
+    # The node already on this design draws a row carrying that MAC.
+    await _node_for(db_session, design, ip="10.0.0.9", mac="aa:bb:cc:dd:ee:ff")
+
+    # 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 = await _node_for(db_session, design, ip="fe80::1, 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},
+        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")
+    await _node_for(db_session, 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")
+    await _node_for(db_session, 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")
+    await _node_for(db_session, 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").
+    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.flush()
+    db_session.add(Node(
+        label="sensor", type="zigbee_enddevice", device_id=device.id, design_id=other,
+    ))
+    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).join(InventoryDevice, Node.device_id == InventoryDevice.id).where(InventoryDevice.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).
+    await _node_for(db_session, 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()
+    devices = [await db_session.get(InventoryDevice, n.device_id) for n in nodes]
+    # The pre-existing node plus the one newly approved — no duplicate for .10.
+    assert len(nodes) == 2
+    assert sorted(d.ip for d in devices) == ["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")
+    await _node_for(db_session, 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 = await _node_for(db_session, 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
+    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.device_id.is_not(None)))
+    ).scalars().first()
+    assert node is not None
+    # The device facts belong to the inventory row the node draws.
+    device = await db_session.get(InventoryDevice, node.device_id)
+    assert device is not None
+    assert device.mac == "aa:bb:cc:dd:ee:ff"
+    mac_props = [p for p in device.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.device_id.is_not(None)))
+    ).scalars().first()
+    assert node is not None
+    # The device facts belong to the inventory row the node draws.
+    device = await db_session.get(InventoryDevice, node.device_id)
+    assert device is not None
+    assert device.mac == "11:22:33:44:55:66"
+    mac_props = [p for p in device.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:
+        device = await db_session.get(InventoryDevice, n.device_id)
+        assert device is not None
+        if device.ip:
+            assert device.check_method == "ping", f"device {device.id} has no 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
+    device = await db_session.get(InventoryDevice, node.device_id)
+    assert device is not None
+    assert device.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).join(InventoryDevice, Node.device_id == InventoryDevice.id).where(InventoryDevice.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. All of that
+    # is the device's, so it is read off the row the node draws.
+    device = await db_session.get(InventoryDevice, node.device_id)
+    assert device is not None
+    assert device.status_live == "online"
+    assert device.check_method == "none"
+    assert {p["key"] for p in device.properties} == {"Z-Wave ID", "Vendor", "Model"}

backend/tests/scan/test_scan_inventory_edit.py

@@ -0,0 +1,240 @@
+"""Editing an inventory row: PATCH /scan/pending/{id} and the widened create.
+
+The inventory row owns the device facts, so it has to be editable on its own —
+not only through a canvas node.
+"""
+import pytest
+from httpx import AsyncClient
+
+from app.db.models import InventoryDevice
+
+
+async def _seed(db_session, **kwargs) -> InventoryDevice:
+    device = InventoryDevice(
+        ip="192.168.1.10",
+        mac="aa:bb:cc:11:22:33",
+        hostname="nas",
+        services=[{"port": 22, "protocol": "tcp", "service_name": "ssh"}],
+        suggested_type="nas",
+        status="pending",
+        discovery_source="arp",
+        discovery_sources=["arp"],
+        properties=[{"key": "Rack", "value": "A1", "icon": None, "visible": True}],
+        **kwargs,
+    )
+    db_session.add(device)
+    await db_session.commit()
+    return device
+
+
+@pytest.mark.asyncio
+async def test_update_pending_requires_auth(client: AsyncClient, db_session):
+    device = await _seed(db_session)
+    res = await client.patch(f"/api/v1/scan/pending/{device.id}", json={"hostname": "x"})
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_update_pending_edits_curated_fields(client: AsyncClient, headers, db_session):
+    device = await _seed(db_session)
+    res = await client.patch(
+        f"/api/v1/scan/pending/{device.id}",
+        headers=headers,
+        json={
+            "label": "Big NAS",
+            "type": "nas",
+            "notes": "in the garage rack",
+            "cpu_count": 4,
+            "cpu_model": "N5105",
+            "ram_gb": 16.0,
+            "disk_gb": 4000.0,
+            "show_hardware": True,
+            "check_method": "http",
+            "check_target": "http://192.168.1.10:5000",
+            "properties": [
+                {"key": "Rack", "value": "B2", "icon": None, "visible": True},
+                {"key": "Owner", "value": "me", "icon": None, "visible": False},
+            ],
+            "services": [
+                {"port": 22, "protocol": "tcp", "service_name": "ssh"},
+                {"port": 5000, "protocol": "tcp", "service_name": "http"},
+            ],
+        },
+    )
+    assert res.status_code == 200
+    data = res.json()
+    assert data["label"] == "Big NAS"
+    assert data["notes"] == "in the garage rack"
+    assert data["cpu_count"] == 4
+    assert data["ram_gb"] == 16.0
+    assert data["show_hardware"] is True
+    assert data["check_method"] == "http"
+    assert len(data["properties"]) == 2
+    assert len(data["services"]) == 2
+
+
+@pytest.mark.asyncio
+async def test_update_pending_is_partial(client: AsyncClient, headers, db_session):
+    """Sending one field must not clear the others."""
+    device = await _seed(db_session)
+    res = await client.patch(
+        f"/api/v1/scan/pending/{device.id}", headers=headers, json={"notes": "only this"}
+    )
+    assert res.status_code == 200
+    data = res.json()
+    assert data["notes"] == "only this"
+    assert data["hostname"] == "nas"
+    assert data["ip"] == "192.168.1.10"
+    assert data["mac"] == "aa:bb:cc:11:22:33"
+    assert data["suggested_type"] == "nas"
+    assert len(data["services"]) == 1
+    assert data["properties"][0]["key"] == "Rack"
+
+
+@pytest.mark.asyncio
+async def test_update_pending_normalizes_mac(client: AsyncClient, headers, db_session):
+    device = await _seed(db_session)
+    res = await client.patch(
+        f"/api/v1/scan/pending/{device.id}", headers=headers, json={"mac": "AA-BB-CC-99-88-77"}
+    )
+    assert res.status_code == 200
+    assert res.json()["mac"] == "aa:bb:cc:99:88:77"
+
+
+@pytest.mark.asyncio
+async def test_update_pending_leaves_lifecycle_alone(client: AsyncClient, headers, db_session):
+    """`status` is owned by approve/hide, not by the edit modal."""
+    device = await _seed(db_session)
+    res = await client.patch(
+        f"/api/v1/scan/pending/{device.id}",
+        headers=headers,
+        json={"label": "x", "status": "approved", "discovery_source": "manual"},
+    )
+    assert res.status_code == 200
+    data = res.json()
+    assert data["label"] == "x"
+    assert data["status"] == "pending"
+    assert data["discovery_source"] == "arp"
+
+
+@pytest.mark.asyncio
+async def test_update_pending_unknown_id(client: AsyncClient, headers):
+    res = await client.patch("/api/v1/scan/pending/nope", headers=headers, json={"notes": "x"})
+    assert res.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_create_pending_accepts_curated_fields(client: AsyncClient, headers):
+    """A hand-made entry carries everything the modal shows, no PATCH round trip."""
+    res = await client.post(
+        "/api/v1/scan/pending",
+        headers=headers,
+        json={
+            "hostname": "patch-panel",
+            "os": "n/a",
+            "label": "Patch panel 24p",
+            "type": "switch",
+            "notes": "passive",
+            "services": [{"port": 80, "protocol": "tcp", "service_name": "http"}],
+            "friendly_name": "PP-1",
+            "device_subtype": "passive",
+            "check_method": "none",
+            "discovery_source": "manual",
+        },
+    )
+    assert res.status_code == 201
+    data = res.json()
+    assert data["label"] == "Patch panel 24p"
+    assert data["type"] == "switch"
+    assert data["os"] == "n/a"
+    assert data["notes"] == "passive"
+    assert data["friendly_name"] == "PP-1"
+    assert data["services"][0]["port"] == 80
+    assert data["status"] == "pending"
+
+
+@pytest.mark.asyncio
+async def test_legacy_row_defaults_are_coerced(client: AsyncClient, headers, db_session):
+    """Rows predating the 3.3.0 columns read back with defaults, not nulls."""
+    device = await _seed(db_session)
+    res = await client.get("/api/v1/scan/pending", headers=headers)
+    assert res.status_code == 200
+    row = next(d for d in res.json() if d["id"] == device.id)
+    assert row["status_live"] == "unknown"
+    assert row["show_hardware"] is False
+    assert row["label"] is None
+
+
+@pytest.mark.asyncio
+async def test_update_pending_edits_the_rack_faceplate(
+    client: AsyncClient, headers, db_session
+):
+    """The front panel is a device fact, so the inventory can edit it too.
+
+    Same row the rack canvas writes on save — a plate edited here is the plate
+    every rack mounting this device draws on its next load.
+    """
+    device = await _seed(db_session, rack_faceplate_id="server-1u", rack_u_height=1)
+    res = await client.patch(
+        f"/api/v1/scan/pending/{device.id}",
+        headers=headers,
+        json={
+            "rack_faceplate_id": "server-2u-bays",
+            "rack_u_height": 2,
+            "rack_col_span": 12,
+            "rack_color": "#ff6e00",
+            "rack_ports": [
+                {"id": "p1", "label": "eth0", "type": "rj45", "x": 0.2, "y": 0.6},
+                # No id: nothing could ever cable it, so it never lands.
+                {"label": "ghost", "type": "rj45", "x": 0.5, "y": 0.5},
+            ],
+        },
+    )
+    assert res.status_code == 200, res.text
+    body = res.json()
+    assert body["rack_faceplate_id"] == "server-2u-bays"
+    assert body["rack_u_height"] == 2
+    assert body["rack_color"] == "#ff6e00"
+    assert [p["id"] for p in body["rack_ports"]] == ["p1"]
+
+
+@pytest.mark.asyncio
+async def test_update_pending_leaves_an_unsent_faceplate_alone(
+    client: AsyncClient, headers, db_session
+):
+    device = await _seed(db_session, rack_faceplate_id="switch-24", rack_u_height=1)
+    res = await client.patch(
+        f"/api/v1/scan/pending/{device.id}", headers=headers, json={"notes": "x"}
+    )
+    assert res.status_code == 200
+    assert res.json()["rack_faceplate_id"] == "switch-24"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "patch",
+    [
+        {"rack_u_height": 0},
+        {"rack_u_height": 49},
+        {"rack_col_span": 0},
+        {"rack_col_span": 13},
+    ],
+)
+async def test_update_pending_rejects_an_impossible_plate(
+    client: AsyncClient, headers, db_session, patch
+):
+    device = await _seed(db_session)
+    res = await client.patch(
+        f"/api/v1/scan/pending/{device.id}", headers=headers, json=patch
+    )
+    assert res.status_code == 422
+
+
+@pytest.mark.asyncio
+async def test_inventory_row_reports_no_plate_before_it_is_modelled(
+    client: AsyncClient, headers, db_session
+):
+    await _seed(db_session)
+    rows = (await client.get("/api/v1/scan/pending", headers=headers)).json()
+    assert rows[0]["rack_faceplate_id"] is None
+    assert rows[0]["rack_ports"] == []

backend/tests/scan/test_scan_properties.py

@@ -0,0 +1,352 @@
+"""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.device_id.is_not(None)))
+    ).scalars().first()
+    assert node is not None
+    # The device facts belong to the inventory row the node draws.
+    device = await db_session.get(InventoryDevice, node.device_id)
+    assert device is not None
+    keys = {p["key"]: p["value"] for p in device.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.device_id.is_not(None)))
+    ).scalars().first()
+    assert node is not None
+    # The device facts belong to the inventory row the node draws.
+    device = await db_session.get(InventoryDevice, node.device_id)
+    assert device is not None
+    keys = {p["key"]: p["value"] for p in device.properties}
+    assert keys["IEEE"] == "0xABCDEF"
+    assert keys["Vendor"] == "IKEA"
+    assert keys["Model"] == "TRADFRI"
+    assert keys["LQI"] == "180"
+    assert device.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.device_id.is_not(None)))
+    ).scalars().first()
+    assert node is not None
+    # The device facts belong to the inventory row the node draws.
+    device = await db_session.get(InventoryDevice, node.device_id)
+    assert device is not None
+    mac_props = [p for p in device.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).join(InventoryDevice, Node.device_id == InventoryDevice.id).where(InventoryDevice.ieee_address == "zwave-H-9"))
+    ).scalar_one()
+    assert node.design_id == active
+    node = (await db_session.execute(select(Node))).scalars().first()
+    assert node is not None
+    device = await db_session.get(InventoryDevice, node.device_id)
+    assert device is not None
+    assert device.status_live == "online"
+    assert device.check_method == "none"
+    assert any(p["key"] == "Z-Wave ID" for p in device.properties)

backend/tests/scan/test_scan_routes.py

@@ -0,0 +1,567 @@
+"""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_for
+
+
+@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")
+    await _node_for(db_session, 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")
+    await _node_for(db_session, 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")
+    await _node_for(db_session, d1, ip="192.168.1.100")
+    await _node_for(db_session, 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")
+    await _node_for(db_session, 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 = await _node_for(db_session, d1, ip="192.168.1.100")
+    # When the scanner last saw the device, and when it last answered, are facts
+    # about the device — they live on its row, not on any one drawing of it.
+    device = await db_session.get(InventoryDevice, node.device_id)
+    assert device is not None
+    device.last_scan = datetime(2026, 6, 1, 8, 30, tzinfo=timezone.utc)
+    device.last_seen = datetime(2026, 6, 25, 9, 15, tzinfo=timezone.utc)
+    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 = await _node_for(db_session, d1, ip="192.168.1.100")
+    older.created_at = datetime(2026, 1, 1, 0, 0, tzinfo=timezone.utc)
+    newer = await _node_for(db_session, d2, ip="192.168.1.100")
+    newer.created_at = datetime(2026, 5, 1, 0, 0, tzinfo=timezone.utc)
+    # Both nodes draw the one row, which carries the scan observation.
+    assert older.device_id == newer.device_id
+    device = await db_session.get(InventoryDevice, older.device_id)
+    assert device is not None
+    device.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 node
+    assert data["node_last_scan"].startswith("2026-06-01")   # off the device row
+
+
+@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_create_pending_unhides_the_row_it_merges_into(client: AsyncClient, headers, db_session):
+    """Adding a device by hand outranks an earlier hide of the same host.
+
+    One device is one row, hidden ones included — but merging into a hidden row
+    and leaving it hidden answers 201 while nothing appears in the inventory, so
+    the add reads as a no-op.
+    """
+    db_session.add(InventoryDevice(id="d-1", ip="192.168.1.50", status="hidden"))
+    await db_session.commit()
+
+    res = await client.post(
+        "/api/v1/scan/pending",
+        json={"ip": "192.168.1.50", "hostname": "printer", "discovery_source": "manual"},
+        headers=headers,
+    )
+    assert res.status_code == 201, res.text
+    assert res.json()["id"] == "d-1"
+    assert res.json()["status"] == "pending"
+
+    listed = (await client.get("/api/v1/scan/pending", headers=headers)).json()
+    assert [d["id"] for d in listed] == ["d-1"]
+
+
+@pytest.mark.asyncio
+async def test_create_pending_leaves_an_approved_row_approved(client: AsyncClient, headers, db_session):
+    """Only `hidden` is lifted — a merge must not walk a device back down the
+    lifecycle and re-queue something already on a canvas."""
+    db_session.add(InventoryDevice(id="d-1", ip="192.168.1.51", status="approved"))
+    await db_session.commit()
+
+    res = await client.post(
+        "/api/v1/scan/pending",
+        json={"ip": "192.168.1.51", "hostname": "nas", "discovery_source": "manual"},
+        headers=headers,
+    )
+    assert res.status_code == 201, res.text
+    assert res.json()["status"] == "approved"
+
+
+@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]
+
+
+# ---------------------------------------------------------------------------
+# Per-device deep rescan (issue #350)
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_rescan_device_requires_auth(client: AsyncClient, pending_device):
+    res = await client.post(f"/api/v1/scan/pending/{pending_device.id}/rescan")
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_rescan_device_creates_run_for_that_ip(client: AsyncClient, headers, pending_device):
+    with patch("app.api.routes.scan._background_device_scan", new_callable=AsyncMock) as bg:
+        res = await client.post(
+            f"/api/v1/scan/pending/{pending_device.id}/rescan", headers=headers
+        )
+    assert res.status_code == 200, res.text
+    data = res.json()
+    assert data["status"] == "running"
+    assert data["kind"] == "device"
+    # One host, not the configured ranges — the scan targets this device only.
+    assert data["ranges"] == ["192.168.1.100/32"]
+    bg.assert_called_once()
+    assert bg.call_args.args[1] == pending_device.id
+    # Full range unless the caller says otherwise.
+    assert bg.call_args.args[3] is True
+
+
+@pytest.mark.asyncio
+async def test_rescan_device_passes_the_requested_port_range(
+    client: AsyncClient, headers, pending_device
+):
+    """The dialog's range reaches the scanner verbatim."""
+    with patch("app.api.routes.scan._background_device_scan", new_callable=AsyncMock) as bg:
+        res = await client.post(
+            f"/api/v1/scan/pending/{pending_device.id}/rescan",
+            headers=headers,
+            json={"ports": " 80,443,8000-9000 "},
+        )
+    assert res.status_code == 200, res.text
+    assert bg.call_args.args[4] == "80,443,8000-9000"
+
+
+@pytest.mark.asyncio
+async def test_rescan_device_rejects_an_unusable_port_range(
+    client: AsyncClient, headers, pending_device
+):
+    """A bad spec is refused here, not handed to nmap."""
+    for bad in ["0", "65536", "100-50", "80,", "http"]:
+        res = await client.post(
+            f"/api/v1/scan/pending/{pending_device.id}/rescan",
+            headers=headers,
+            json={"ports": bad},
+        )
+        assert res.status_code == 422, f"{bad}: {res.text}"
+
+
+@pytest.mark.asyncio
+async def test_rescan_device_treats_a_blank_range_as_the_full_sweep(
+    client: AsyncClient, headers, pending_device
+):
+    with patch("app.api.routes.scan._background_device_scan", new_callable=AsyncMock) as bg:
+        res = await client.post(
+            f"/api/v1/scan/pending/{pending_device.id}/rescan",
+            headers=headers,
+            json={"ports": "   "},
+        )
+    assert res.status_code == 200, res.text
+    assert bg.call_args.args[4] is None
+    assert bg.call_args.args[3] is True
+
+
+@pytest.mark.asyncio
+async def test_rescan_device_unknown_id_404(client: AsyncClient, headers):
+    res = await client.post(f"/api/v1/scan/pending/{uuid.uuid4()}/rescan", headers=headers)
+    assert res.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_rescan_device_without_ip_409(client: AsyncClient, headers, db_session):
+    device = InventoryDevice(id=str(uuid.uuid4()), ip=None, hostname="zigbee-lamp", status="pending")
+    db_session.add(device)
+    await db_session.commit()
+
+    res = await client.post(f"/api/v1/scan/pending/{device.id}/rescan", headers=headers)
+    assert res.status_code == 409
+    assert "IP" in res.json()["detail"]
+
+
+@pytest.mark.asyncio
+async def test_rescan_device_hidden_409(client: AsyncClient, headers, db_session):
+    device = InventoryDevice(id=str(uuid.uuid4()), ip="192.168.1.77", status="hidden")
+    db_session.add(device)
+    await db_session.commit()
+
+    res = await client.post(f"/api/v1/scan/pending/{device.id}/rescan", headers=headers)
+    assert res.status_code == 409
+
+
+@pytest.mark.asyncio
+async def test_rescan_device_serialized_per_device(client: AsyncClient, headers, pending_device):
+    """A second rescan while the first still runs is refused, not duplicated."""
+    with patch("app.api.routes.scan._background_device_scan", new_callable=AsyncMock):
+        first = await client.post(
+            f"/api/v1/scan/pending/{pending_device.id}/rescan", headers=headers
+        )
+        second = await client.post(
+            f"/api/v1/scan/pending/{pending_device.id}/rescan", headers=headers
+        )
+    assert first.status_code == 200
+    assert second.status_code == 409
+    assert "already running" in second.json()["detail"]
+
+
+@pytest.mark.asyncio
+async def test_rescan_device_allows_a_new_run_once_the_first_finished(
+    client: AsyncClient, headers, pending_device
+):
+    with patch("app.api.routes.scan._background_device_scan", new_callable=AsyncMock):
+        first = await client.post(
+            f"/api/v1/scan/pending/{pending_device.id}/rescan", headers=headers
+        )
+        assert first.status_code == 200
+        run_id = first.json()["id"]
+        stopped = await client.post(f"/api/v1/scan/{run_id}/stop", headers=headers)
+        assert stopped.status_code == 200
+        again = await client.post(
+            f"/api/v1/scan/pending/{pending_device.id}/rescan", headers=headers
+        )
+    assert again.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_get_run_returns_status(client: AsyncClient, headers, pending_device):
+    with patch("app.api.routes.scan._background_device_scan", new_callable=AsyncMock):
+        started = await client.post(
+            f"/api/v1/scan/pending/{pending_device.id}/rescan", headers=headers
+        )
+    run_id = started.json()["id"]
+    res = await client.get(f"/api/v1/scan/runs/{run_id}", headers=headers)
+    assert res.status_code == 200
+    assert res.json()["id"] == run_id
+    assert res.json()["status"] == "running"
+
+
+@pytest.mark.asyncio
+async def test_get_run_unknown_id_404(client: AsyncClient, headers):
+    res = await client.get(f"/api/v1/scan/runs/{uuid.uuid4()}", headers=headers)
+    assert res.status_code == 404

backend/tests/scan/test_scan_run.py

@@ -0,0 +1,573 @@
+"""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,
+    reconcile_orphan_runs,
+    request_cancel,
+    run_scan,
+)
+
+
+@pytest.mark.asyncio
+async def test_background_scan_marks_run_errored_on_exception(mem_db):
+    """If run_scan() raises, the ScanRun must transition running → error and the
+    session rollback path must execute without a follow-on exception.
+
+    "error" and not "failed": one condition, one name — it is what run_scan
+    writes when it catches the failure itself, and the only one Scan History
+    filters and colours.
+    """
+    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 == "error"
+
+
+@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 'error'."""
+    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."""
+    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(stale)
+    await db_session.flush()
+    # A canvas already draws that device.
+    db_session.add(Node(
+        id=str(uuid.uuid4()),
+        label="Existing Server",
+        type="server",
+        device_id=stale.id,
+        pos_x=0.0,
+        pos_y=0.0,
+    ))
+    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 already drawn on a canvas refreshes the one inventory row.
+
+    The device is never suppressed, and never duplicated: the node draws that
+    row, so a second row for the same host would split the device in two.
+    """
+    existing = InventoryDevice(id=str(uuid.uuid4()), ip="192.168.1.50", status="approved")
+    db_session.add(existing)
+    await db_session.flush()
+    existing_id = existing.id
+    db_session.add(Node(
+        id=str(uuid.uuid4()),
+        label="Existing Server",
+        type="server",
+        device_id=existing.id,
+        pos_x=0.0,
+        pos_y=0.0,
+    ))
+    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)
+
+    rows = (
+        await db_session.execute(
+            select(InventoryDevice).where(InventoryDevice.ip == "192.168.1.50")
+        )
+    ).scalars().all()
+    assert len(rows) == 1
+    assert rows[0].id == existing_id
+    # The scan refreshed it; it did not reset the lifecycle.
+    assert rows[0].status == "approved"
+    assert rows[0].hostname == MOCK_HOST["hostname"]
+
+
+@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)
+
+
+@pytest.mark.asyncio
+async def test_background_device_scan_marks_run_errored_on_exception(mem_db):
+    """Same word as the network scan — a device run that blows up reads alike."""
+    from app.api.routes.scan import _background_device_scan
+
+    async with mem_db() as session:
+        run = ScanRun(status="running", kind="device", ranges=["10.0.0.5/32"])
+        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_device_scan",
+            new_callable=AsyncMock,
+            side_effect=RuntimeError("boom"),
+        ),
+    ):
+        await _background_device_scan(run_id, "d1")
+
+    async with mem_db() as session:
+        refreshed = await session.get(ScanRun, run_id)
+        assert refreshed is not None
+        assert refreshed.status == "error"
+
+
+# --- reconcile_orphan_runs (issue #374) --------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_reconcile_orphan_runs_marks_running_as_error(mem_db):
+    """A run left "running" by a process that died mid-scan is immortal, and it
+    also locks its range out of future scans. Startup must reconcile it."""
+    async with mem_db() as session:
+        orphan = ScanRun(status="running", ranges=["10.0.0.0/24"])
+        session.add(orphan)
+        await session.commit()
+        orphan_id = orphan.id
+
+        assert await reconcile_orphan_runs(session) == 1
+
+        reconciled = await session.get(ScanRun, orphan_id)
+        # "error", not "failed" — one condition, one name, and the only status
+        # Scan History filters and colours.
+        assert reconciled.status == "error"
+        assert reconciled.finished_at is not None
+        assert "restarted" in reconciled.error
+
+
+@pytest.mark.asyncio
+async def test_reconcile_orphan_runs_leaves_finished_runs_alone(mem_db):
+    """Only "running" is orphaned. Terminal rows must not be rewritten."""
+    async with mem_db() as session:
+        done = ScanRun(status="done", ranges=["10.0.0.0/24"], devices_found=7)
+        cancelled = ScanRun(status="cancelled", ranges=["10.0.1.0/24"])
+        errored = ScanRun(status="error", ranges=["10.0.2.0/24"], error="nmap missing")
+        session.add_all([done, cancelled, errored])
+        await session.commit()
+        ids = (done.id, cancelled.id, errored.id)
+
+        assert await reconcile_orphan_runs(session) == 0
+
+        for run_id, expected in zip(ids, ("done", "cancelled", "error"), strict=True):
+            assert (await session.get(ScanRun, run_id)).status == expected
+        # The pre-existing error message must survive untouched.
+        assert (await session.get(ScanRun, ids[2])).error == "nmap missing"
+
+
+@pytest.mark.asyncio
+async def test_reconcile_orphan_runs_handles_several_and_an_empty_table(mem_db):
+    async with mem_db() as session:
+        # Nothing to do on a fresh database.
+        assert await reconcile_orphan_runs(session) == 0
+
+        session.add_all([
+            ScanRun(status="running", ranges=["10.0.0.0/24"]),
+            ScanRun(status="running", kind="device", ranges=["10.0.0.5"]),
+            ScanRun(status="done", ranges=["10.0.1.0/24"]),
+        ])
+        await session.commit()
+
+        assert await reconcile_orphan_runs(session) == 2
+        remaining = (
+            await session.execute(select(ScanRun).where(ScanRun.status == "running"))
+        ).scalars().all()
+        assert remaining == []
+
+
+@pytest.mark.asyncio
+async def test_reconcile_orphan_runs_unblocks_a_new_scan(mem_db):
+    """The point of the reconcile: the trigger endpoints reject a scan while one
+    is "running" for the same target, so an orphan blocks that range for good."""
+    async with mem_db() as session:
+        session.add(ScanRun(status="running", kind="device", ranges=["10.0.0.5"]))
+        await session.commit()
+
+        await reconcile_orphan_runs(session)
+
+        blocking = (
+            await session.execute(
+                select(ScanRun).where(
+                    ScanRun.status == "running", ScanRun.kind == "device"
+                )
+            )
+        ).scalars().all()
+        assert not any("10.0.0.5" in (r.ranges or []) for r in blocking)
+
+
+@pytest.mark.asyncio
+async def test_lifespan_reconciles_orphan_runs_at_startup():
+    """The reconcile is worthless unless startup actually calls it."""
+    from app.main import app as fastapi_app
+    from app.main import lifespan
+
+    with patch("app.main.init_db", new=AsyncMock()), \
+         patch("app.main.start_scheduler"), \
+         patch("app.main.stop_scheduler"), \
+         patch("app.main.reconcile_orphan_runs", new=AsyncMock()) as reconcile:
+        async with lifespan(fastapi_app):
+            pass
+
+    reconcile.assert_awaited_once()

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,343 @@ 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
+
+
+async def test_oidc_callback_returns_to_the_app_base_path(client: AsyncClient, oidc_settings):
+    """The SPA can be mounted under a prefix — the post-login redirect follows it."""
+    oidc_settings.oidc_redirect_uri = "http://test/homelab/api/v1/auth/oidc/callback"
+    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"] == "/homelab/"
+
+
+@pytest.mark.parametrize(
+    ("redirect_uri", "expected"),
+    [
+        ("", "/"),
+        ("https://home.example/api/v1/auth/oidc/callback", "/"),
+        ("https://home.example/homelab/api/v1/auth/oidc/callback", "/homelab/"),
+        ("https://home.example/apps/lab/api/v1/auth/oidc/callback", "/apps/lab/"),
+        ("/api/v1/auth/oidc/callback", "/"),
+        ("https://home.example/somewhere/else", "/"),
+    ],
+)
+def test_app_base_path_of(redirect_uri: str, expected: str):
+    from app.core.config import app_base_path_of
+
+    assert app_base_path_of(redirect_uri) == expected
+
+
+@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_oidc_mutation_allows_app_origin_missing_from_cors_origins(
+    client: AsyncClient, oidc_settings
+):
+    """Regression for #356: a same-origin reverse-proxy deploy needs no CORS, so
+    CORS_ORIGINS is left at its localhost default while the browser still sends
+    Origin — every POST used to 403."""
+    oidc_settings.cors_origins = ["http://localhost:5173", "http://localhost:3000"]
+    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"]
+
+    created = await client.post(
+        "/api/v1/designs",
+        json={"name": "From OIDC", "design_type": "network"},
+        headers={"Origin": "http://test", "X-Homelable-CSRF": csrf_token},
+    )
+    assert created.status_code == 201
+
+    # The fallback widens the allowlist by exactly one origin, nothing more.
+    evil = await client.post(
+        "/api/v1/designs",
+        json={"name": "Nope", "design_type": "network"},
+        headers={"Origin": "https://evil.example", "X-Homelable-CSRF": csrf_token},
+    )
+    assert evil.status_code == 403
+
+
+def test_origin_is_allowed_falls_back_to_the_oidc_redirect_origin(oidc_settings):
+    from app.core.security import origin_is_allowed
+
+    oidc_settings.cors_origins = ["http://localhost:3000"]
+    oidc_settings.oidc_redirect_uri = "https://homelable.example.com/api/v1/auth/oidc/callback"
+
+    assert origin_is_allowed("https://homelable.example.com") is True
+    assert origin_is_allowed("https://homelable.example.com/") is True
+    assert origin_is_allowed("http://localhost:3000") is True
+    assert origin_is_allowed("https://evil.example") is False
+    assert origin_is_allowed(None) is False
+
+    # A redirect URI that is not an absolute URL contributes no origin.
+    oidc_settings.oidc_redirect_uri = "/api/v1/auth/oidc/callback"
+    assert origin_is_allowed("https://homelable.example.com") is False
+
+
+def test_oidc_settings_warn_when_cors_origins_omits_the_app_origin(caplog):
+    from app.core.config import Settings, origin_of
+
+    base = {
+        "secret_key": "x" * 32,
+        "auth_mode": "oidc",
+        "oidc_discovery_url": "https://idp.example/.well-known/openid-configuration",
+        "oidc_client_id": "homelable",
+        "oidc_client_secret": "secret",
+        "oidc_redirect_uri": "https://homelable.example.com/api/v1/auth/oidc/callback",
+    }
+
+    with caplog.at_level("WARNING"):
+        Settings(**base, cors_origins=["http://localhost:3000"])
+    # Asserted against the origin the settings derive rather than one spelled
+    # out again here: this checks the warning names that exact origin, and a
+    # URL literal on the left of an `in` reads to a scanner as a host check
+    # that a substring match would not make safely.
+    assert origin_of(base["oidc_redirect_uri"]) in caplog.text
+    assert "CORS_ORIGINS" in caplog.text
+
+    caplog.clear()
+    with caplog.at_level("WARNING"):
+        Settings(**base, cors_origins=["https://homelable.example.com/"])
+    assert caplog.text == ""
+
+
+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,88 @@ 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)
+
+    node = (await client.get("/api/v1/canvas", headers=headers)).json()["nodes"][0]
+    # created_at / updated_at always set; last_seen / last_scan null until observed.
+    assert node["created_at"] is not None
+    assert node["updated_at"] is not None
+    assert "last_seen" in node
+    assert node["last_scan"] is None
+
+
 async def test_save_canvas_updates_existing_node(client: AsyncClient, headers: dict):
     n1 = node_payload(label="Old Label")
     await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
@@ -199,6 +291,24 @@ async def test_save_canvas_show_hardware_defaults_false(client: AsyncClient, hea
     assert canvas["nodes"][0]["show_hardware"] is False
 
 
+# Regression (#184): show_port_numbers was dropped by the save schema, so the
+# toggle reset on every reload.
+async def test_save_canvas_persists_show_port_numbers(client: AsyncClient, headers: dict):
+    n1 = node_payload(show_port_numbers=True)
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["nodes"][0]["show_port_numbers"] is True
+
+
+async def test_save_canvas_show_port_numbers_defaults_false(client: AsyncClient, headers: dict):
+    n1 = node_payload()
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["nodes"][0]["show_port_numbers"] is False
+
+
 async def test_save_canvas_hardware_fields_cleared_on_update(client: AsyncClient, headers: dict):
     n1 = node_payload(cpu_count=8, ram_gb=32.0)
     await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
@@ -596,3 +706,90 @@ async def test_save_canvas_custom_style_overwrite(client: AsyncClient, headers:
     canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
     assert "proxmox" in canvas["custom_style"]["nodes"]
     assert "server" not in canvas["custom_style"]["nodes"]
+
+
+# ── self-parent guard (#370) ─────────────────────────────────────────────────
+
+async def test_save_canvas_drops_a_node_parented_to_itself(client: AsyncClient, headers: dict):
+    # A self-parent row freezes the node on the canvas and survives a reload, so
+    # the save normalizes it away. Dropped rather than rejected: a canvas that
+    # already carries the bad row must still be able to save.
+    n = node_payload(type="lxc", label="pihole")
+    n["parent_id"] = n["id"]
+
+    res = await client.post(
+        "/api/v1/canvas/save", json={"nodes": [n], "edges": [], "viewport": {}}, headers=headers
+    )
+    assert res.status_code == 200
+
+    saved = (await client.get("/api/v1/canvas", headers=headers)).json()["nodes"]
+    assert len(saved) == 1
+    assert saved[0]["parent_id"] is None
+
+
+async def test_save_canvas_keeps_a_real_parent(client: AsyncClient, headers: dict):
+    host = node_payload(type="proxmox", label="pve", container_mode=True)
+    child = node_payload(type="lxc", label="pihole", parent_id=host["id"])
+
+    res = await client.post(
+        "/api/v1/canvas/save",
+        json={"nodes": [host, child], "edges": [], "viewport": {}},
+        headers=headers,
+    )
+    assert res.status_code == 200
+
+    saved = {n["label"]: n for n in (await client.get("/api/v1/canvas", headers=headers)).json()["nodes"]}
+    assert saved["pihole"]["parent_id"] == host["id"]
+
+
+# ── furniture descriptions ───────────────────────────────────────────────────
+
+async def test_save_canvas_keeps_zone_and_group_descriptions(client: AsyncClient, headers: dict):
+    # Regression: a zone's and a group's description used to ride on `notes`,
+    # which the save routes to the inventory row. Furniture has no such row, so
+    # the text was dropped without an error. It lives on `nodes.description` now.
+    zone = node_payload(type="groupRect", label="Garage", description="Everything behind the garage door.")
+    group = node_payload(type="group", label="Cluster", description="The three Proxmox boxes.")
+
+    res = await client.post(
+        "/api/v1/canvas/save", json={"nodes": [zone, group], "edges": [], "viewport": {}}, headers=headers
+    )
+    assert res.status_code == 200
+
+    saved = {n["label"]: n for n in (await client.get("/api/v1/canvas", headers=headers)).json()["nodes"]}
+    assert saved["Garage"]["description"] == "Everything behind the garage door."
+    assert saved["Cluster"]["description"] == "The three Proxmox boxes."
+
+
+async def test_save_canvas_edits_a_furniture_description(client: AsyncClient, headers: dict):
+    zone = node_payload(type="groupRect", label="Garage", description="First take.")
+    await client.post("/api/v1/canvas/save", json={"nodes": [zone], "edges": [], "viewport": {}}, headers=headers)
+
+    zone["description"] = "Second take."
+    await client.post("/api/v1/canvas/save", json={"nodes": [zone], "edges": [], "viewport": {}}, headers=headers)
+
+    saved = (await client.get("/api/v1/canvas", headers=headers)).json()["nodes"]
+    assert saved[0]["description"] == "Second take."
+
+
+async def test_save_canvas_clears_a_furniture_description(client: AsyncClient, headers: dict):
+    zone = node_payload(type="groupRect", label="Garage", description="Written once.")
+    await client.post("/api/v1/canvas/save", json={"nodes": [zone], "edges": [], "viewport": {}}, headers=headers)
+
+    zone["description"] = ""
+    await client.post("/api/v1/canvas/save", json={"nodes": [zone], "edges": [], "viewport": {}}, headers=headers)
+
+    saved = (await client.get("/api/v1/canvas", headers=headers)).json()["nodes"]
+    assert saved[0]["description"] == ""
+
+
+async def test_save_canvas_drops_a_description_on_a_device_node(client: AsyncClient, headers: dict):
+    # A node that draws a device keeps its text on the inventory row, as `notes`.
+    # `description` is furniture-only, so it is cleared rather than shadowing it.
+    n = node_payload(type="nas", label="nas-01", ip="192.168.1.20", notes="Backs up nightly.", description="Not here.")
+
+    await client.post("/api/v1/canvas/save", json={"nodes": [n], "edges": [], "viewport": {}}, headers=headers)
+
+    saved = (await client.get("/api/v1/canvas", headers=headers)).json()["nodes"][0]
+    assert saved["description"] is None
+    assert saved["notes"] == "Backs up nightly."

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

@@ -0,0 +1,270 @@
+import uuid
+
+from httpx import AsyncClient
+
+
+def node_payload(**kwargs):
+    return {"id": str(uuid.uuid4()), "type": "server", "label": "N", "status": "unknown", "pos_x": 0, "pos_y": 0, **kwargs}
+
+
+def edge_payload(src, tgt, **kwargs):
+    return {"id": str(uuid.uuid4()), "source": src, "target": tgt, "type": "ethernet", **kwargs}
+
+
+async def _create(client: AsyncClient, headers: dict, **body) -> dict:
+    res = await client.post("/api/v1/designs", json={"name": "D", **body}, headers=headers)
+    assert res.status_code == 201, res.text
+    return res.json()
+
+
+# ── auth ──────────────────────────────────────────────────────────────────────
+
+async def test_list_designs_requires_auth(client: AsyncClient):
+    res = await client.get("/api/v1/designs")
+    assert res.status_code == 401
+
+
+async def test_create_design_requires_auth(client: AsyncClient):
+    res = await client.post("/api/v1/designs", json={"name": "X"})
+    assert res.status_code == 401
+
+
+# ── list / create ─────────────────────────────────────────────────────────────
+
+async def test_list_designs_empty(client: AsyncClient, headers: dict):
+    res = await client.get("/api/v1/designs", headers=headers)
+    assert res.status_code == 200
+    assert res.json() == []
+
+
+async def test_create_design_defaults(client: AsyncClient, headers: dict):
+    design = await _create(client, headers, name="Workshop")
+    assert design["name"] == "Workshop"
+    assert design["design_type"] == "network"
+    assert design["icon"] == "dashboard"
+    assert "id" in design and design["id"]
+
+
+async def test_create_design_explicit_type(client: AsyncClient, headers: dict):
+    design = await _create(client, headers, name="Net", design_type="network")
+    assert design["design_type"] == "network"
+
+
+async def test_create_design_with_custom_icon(client: AsyncClient, headers: dict):
+    design = await _create(client, headers, name="Power", icon="zap")
+    assert design["icon"] == "zap"
+
+
+async def test_update_design_changes_icon(client: AsyncClient, headers: dict):
+    design = await _create(client, headers, name="D", icon="dashboard")
+    res = await client.put(f"/api/v1/designs/{design['id']}", json={"icon": "server"}, headers=headers)
+    assert res.status_code == 200
+    assert res.json()["icon"] == "server"
+    # Name left untouched when only icon is sent.
+    assert res.json()["name"] == "D"
+
+
+async def test_update_design_name_and_icon_together(client: AsyncClient, headers: dict):
+    design = await _create(client, headers, name="Old", icon="dashboard")
+    res = await client.put(
+        f"/api/v1/designs/{design['id']}", json={"name": "New", "icon": "network"}, headers=headers,
+    )
+    assert res.status_code == 200
+    body = res.json()
+    assert body["name"] == "New"
+    assert body["icon"] == "network"
+
+
+async def test_create_design_creates_empty_canvas_state(client: AsyncClient, headers: dict):
+    design = await _create(client, headers, name="Has Canvas")
+    # Loading the new design returns an (empty) canvas without falling back to another design.
+    res = await client.get("/api/v1/canvas", params={"design_id": design["id"]}, headers=headers)
+    assert res.status_code == 200
+    body = res.json()
+    assert body["nodes"] == []
+    assert body["edges"] == []
+
+
+async def test_list_returns_created_designs_ordered(client: AsyncClient, headers: dict):
+    a = await _create(client, headers, name="First")
+    b = await _create(client, headers, name="Second")
+    listed = (await client.get("/api/v1/designs", headers=headers)).json()
+    ids = [d["id"] for d in listed]
+    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):
+    design = await _create(client, headers, name="Old Name")
+    res = await client.put(f"/api/v1/designs/{design['id']}", json={"name": "New Name"}, headers=headers)
+    assert res.status_code == 200
+    assert res.json()["name"] == "New Name"
+
+
+async def test_update_design_missing_returns_404(client: AsyncClient, headers: dict):
+    res = await client.put(f"/api/v1/designs/{uuid.uuid4()}", json={"name": "X"}, headers=headers)
+    assert res.status_code == 404
+
+
+# ── delete ────────────────────────────────────────────────────────────────────
+
+async def test_delete_last_design_blocked(client: AsyncClient, headers: dict):
+    design = await _create(client, headers, name="Only One")
+    res = await client.delete(f"/api/v1/designs/{design['id']}", headers=headers)
+    assert res.status_code == 400
+
+
+async def test_delete_design_missing_returns_404(client: AsyncClient, headers: dict):
+    # Need >1 design so we get past nothing; 404 path is checked before the count guard.
+    await _create(client, headers, name="Keep")
+    res = await client.delete(f"/api/v1/designs/{uuid.uuid4()}", headers=headers)
+    assert res.status_code == 404
+
+
+async def test_delete_design_removes_its_nodes_edges_and_canvas(client: AsyncClient, headers: dict):
+    keep = await _create(client, headers, name="Keep")
+    victim = await _create(client, headers, name="Victim")
+
+    # Populate the victim design with nodes + an edge via canvas save.
+    n1 = node_payload(label="A")
+    n2 = node_payload(label="B")
+    e1 = edge_payload(n1["id"], n2["id"])
+    save = await client.post(
+        "/api/v1/canvas/save",
+        json={"nodes": [n1, n2], "edges": [e1], "viewport": {}, "design_id": victim["id"]},
+        headers=headers,
+    )
+    assert save.status_code == 200
+
+    # Populate the kept design too, to prove scoping.
+    k1 = node_payload(label="K")
+    await client.post(
+        "/api/v1/canvas/save",
+        json={"nodes": [k1], "edges": [], "viewport": {}, "design_id": keep["id"]},
+        headers=headers,
+    )
+
+    res = await client.delete(f"/api/v1/designs/{victim['id']}", headers=headers)
+    assert res.status_code == 204
+
+    # Victim gone from list.
+    listed = (await client.get("/api/v1/designs", headers=headers)).json()
+    assert [d["id"] for d in listed] == [keep["id"]]
+
+    # Kept design's node survives untouched.
+    kept_canvas = (await client.get("/api/v1/canvas", params={"design_id": keep["id"]}, headers=headers)).json()
+    assert len(kept_canvas["nodes"]) == 1
+    assert kept_canvas["nodes"][0]["label"] == "K"

backend/tests/test_doc_backlinks.py

@@ -0,0 +1,254 @@
+"""Backlinks — the inverse of a wiki-link.
+
+Two halves. The pure resolution rules, which must stay identical to
+`frontend/src/documentation/wikilinks.ts`, and the route, which has to find a
+target document that carries no links of its own and must not pay for the
+inventory when nothing links to a device.
+"""
+
+from dataclasses import dataclass
+
+from httpx import AsyncClient
+
+from app.services import doc_backlinks
+
+
+@dataclass
+class FakeDoc:
+    id: str
+    slug: str = ""
+    title: str = ""
+    body: str = ""
+    device_id: str | None = None
+    node_id: str | None = None
+
+
+@dataclass
+class FakeDevice:
+    id: str
+    label: str | None = None
+    friendly_name: str | None = None
+    hostname: str | None = None
+    ip: str | None = None
+
+
+# ── parsing ─────────────────────────────────────────────────────────────────
+
+
+def test_a_bare_link_is_a_document_link():
+    link = doc_backlinks.parse_link("VLAN plan")
+    assert link is not None
+    assert (link.target, link.key, link.label) == ("doc", "VLAN plan", "VLAN plan")
+
+
+def test_a_prefix_picks_the_target():
+    assert doc_backlinks.parse_link("device:nas-01").target == "device"
+    assert doc_backlinks.parse_link("NODE:abc").target == "node"
+    assert doc_backlinks.parse_link("doc:vlan-plan").target == "doc"
+
+
+def test_an_unknown_prefix_stays_part_of_the_key():
+    link = doc_backlinks.parse_link("http://nas.lan")
+    assert link is not None
+    assert (link.target, link.key) == ("doc", "http://nas.lan")
+
+
+def test_a_pipe_sets_the_label():
+    link = doc_backlinks.parse_link("device:nas-01|the big NAS")
+    assert link is not None
+    assert (link.key, link.label) == ("nas-01", "the big NAS")
+
+
+def test_an_empty_link_is_not_a_link():
+    assert doc_backlinks.parse_link("") is None
+    assert doc_backlinks.parse_link("device:") is None
+
+
+def test_links_are_collected_with_their_line():
+    body = "intro\nsee [[a]] and [[b]]\n"
+    found = list(doc_backlinks.iter_links(body))
+    assert [link.key for _, link in found] == ["a", "b"]
+    assert {line for line, _ in found} == {"see [[a]] and [[b]]"}
+
+
+# ── resolution ──────────────────────────────────────────────────────────────
+
+
+def _resolve(inner: str, docs: list[FakeDoc], devices: list[FakeDevice] | None = None):
+    link = doc_backlinks.parse_link(inner)
+    assert link is not None
+    return doc_backlinks.resolve(link, docs, devices or [])
+
+
+def test_a_document_resolves_by_id_then_slug_then_title():
+    docs = [
+        FakeDoc(id="d1", slug="vlan-plan", title="VLAN plan"),
+        FakeDoc(id="d2", slug="other", title="Other"),
+    ]
+    assert _resolve("d1", docs) == "d1"
+    assert _resolve("vlan-plan", docs) == "d1"
+    assert _resolve("VLAN PLAN", docs) == "d1"
+
+
+def test_an_unmatched_document_link_resolves_to_nothing():
+    assert _resolve("nowhere", [FakeDoc(id="d1", slug="s", title="t")]) is None
+
+
+def test_a_device_link_resolves_by_id_or_label():
+    docs = [FakeDoc(id="d1", device_id="dev1")]
+    devices = [FakeDevice(id="dev1", label="nas-01")]
+    assert _resolve("device:dev1", docs, devices) == "d1"
+    assert _resolve("device:NAS-01", docs, devices) == "d1"
+
+
+def test_a_device_label_falls_back_the_way_the_tree_does():
+    assert doc_backlinks.device_label(FakeDevice(id="x", hostname="h")) == "h"
+    assert doc_backlinks.device_label(FakeDevice(id="x", ip="10.0.0.1")) == "10.0.0.1"
+    assert doc_backlinks.device_label(FakeDevice(id="x")) == "Unnamed device"
+
+
+def test_a_device_with_no_document_resolves_to_nothing():
+    assert _resolve("device:dev1", [], [FakeDevice(id="dev1", label="nas")]) is None
+
+
+def test_a_node_link_resolves_through_node_id():
+    docs = [FakeDoc(id="d1", node_id="n1")]
+    assert _resolve("node:n1", docs) == "d1"
+    assert _resolve("node:n2", docs) is None
+
+
+# ── inversion ───────────────────────────────────────────────────────────────
+
+
+def test_a_document_that_links_here_is_a_backlink():
+    docs = [
+        FakeDoc(id="d1", slug="a", title="A", body="see [[B]]"),
+        FakeDoc(id="d2", slug="b", title="B", body="no links"),
+    ]
+    hits = doc_backlinks.backlinks_for("d2", docs, [])
+    assert [h.doc_id for h in hits] == ["d1"]
+    assert hits[0].context == "see [[B]]"
+
+
+def test_a_document_does_not_link_to_itself():
+    docs = [FakeDoc(id="d1", slug="a", title="A", body="[[A]] again")]
+    assert doc_backlinks.backlinks_for("d1", docs, []) == []
+
+
+def test_two_links_from_one_document_are_one_backlink_with_a_count():
+    docs = [
+        FakeDoc(id="d1", slug="a", title="A", body="[[B]] and later [[b]]"),
+        FakeDoc(id="d2", slug="b", title="B"),
+    ]
+    hits = doc_backlinks.backlinks_for("d2", docs, [])
+    assert len(hits) == 1
+    assert hits[0].count == 2
+
+
+def test_the_written_label_is_kept():
+    docs = [
+        FakeDoc(id="d1", slug="a", title="A", body="[[B|the other one]]"),
+        FakeDoc(id="d2", slug="b", title="B"),
+    ]
+    assert doc_backlinks.backlinks_for("d2", docs, [])[0].label == "the other one"
+
+
+def test_a_long_line_is_windowed_around_the_link():
+    filler = "word " * 60
+    docs = [
+        FakeDoc(id="d1", slug="a", title="A", body=f"{filler}[[B]]{filler}"),
+        FakeDoc(id="d2", slug="b", title="B"),
+    ]
+    context = doc_backlinks.backlinks_for("d2", docs, [])[0].context
+    assert "[[B]]" in context
+    assert len(context) < 200
+
+
+def test_has_device_link_only_fires_on_a_device_link():
+    assert doc_backlinks.has_device_link([FakeDoc(id="d", body="[[device:x]]")])
+    assert not doc_backlinks.has_device_link([FakeDoc(id="d", body="[[plain]]")])
+
+
+# ── route ───────────────────────────────────────────────────────────────────
+
+
+async def test_backlinks_requires_auth(client: AsyncClient):
+    assert (await client.get("/api/v1/documents/x/backlinks")).status_code == 401
+
+
+async def test_backlinks_404_on_an_unknown_document(client: AsyncClient, headers: dict):
+    res = await client.get("/api/v1/documents/nope/backlinks", headers=headers)
+    assert res.status_code == 404
+
+
+async def test_the_route_finds_a_target_that_carries_no_links(client: AsyncClient, headers: dict):
+    """The target's own body has no `[[`, so it is only ever a resolution target."""
+    target = (
+        await client.post("/api/v1/documents", json={"title": "VLAN plan"}, headers=headers)
+    ).json()
+    source = (
+        await client.post("/api/v1/documents", json={"title": "Runbook"}, headers=headers)
+    ).json()
+    await client.patch(
+        f"/api/v1/documents/{source['id']}",
+        json={"body": "Read the [[VLAN plan]] first."},
+        headers=headers,
+    )
+
+    res = await client.get(f"/api/v1/documents/{target['id']}/backlinks", headers=headers)
+    assert res.status_code == 200
+    hits = res.json()
+    assert [h["doc_id"] for h in hits] == [source["id"]]
+    assert hits[0]["title"] == "Runbook"
+    assert hits[0]["label"] == "VLAN plan"
+    assert hits[0]["context"] == "Read the [[VLAN plan]] first."
+
+
+async def test_a_device_document_is_reachable_by_its_device_link(client: AsyncClient, headers: dict):
+    res = await client.post(
+        "/api/v1/scan/pending",
+        json={
+            "label": "nas-01",
+            "hostname": "nas-01.lan",
+            "ip": "192.168.1.20",
+            "discovery_source": "manual",
+        },
+        headers=headers,
+    )
+    assert res.status_code in (200, 201), res.text
+    device = res.json()
+    doc = (
+        await client.post(
+            "/api/v1/documents",
+            json={"title": "nas-01", "kind": "device", "device_id": device["id"]},
+            headers=headers,
+        )
+    ).json()
+    source = (
+        await client.post("/api/v1/documents", json={"title": "Backups"}, headers=headers)
+    ).json()
+    await client.patch(
+        f"/api/v1/documents/{source['id']}",
+        json={"body": "Runs on [[device:nas-01]]."},
+        headers=headers,
+    )
+
+    hits = (await client.get(f"/api/v1/documents/{doc['id']}/backlinks", headers=headers)).json()
+    assert [h["doc_id"] for h in hits] == [source["id"]]
+    assert hits[0]["device_id"] is None  # the *source* is a page, not a device
+
+
+async def test_an_unresolved_link_is_not_a_backlink(client: AsyncClient, headers: dict):
+    target = (
+        await client.post("/api/v1/documents", json={"title": "Target"}, headers=headers)
+    ).json()
+    source = (
+        await client.post("/api/v1/documents", json={"title": "Source"}, headers=headers)
+    ).json()
+    await client.patch(
+        f"/api/v1/documents/{source['id']}",
+        json={"body": "Points at [[Something else]]."},
+        headers=headers,
+    )
+    hits = (await client.get(f"/api/v1/documents/{target['id']}/backlinks", headers=headers)).json()
+    assert hits == []

backend/tests/test_doc_search.py

@@ -0,0 +1,172 @@
+"""Search over documents, on both engines.
+
+FTS5 is not guaranteed by the SQLite build the LXC and Docker images ship, so
+the LIKE fallback is a supported path, not a safety net — it gets the same
+coverage as the index.
+"""
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import Document
+from app.services import doc_search
+
+
+def _doc(**kwargs) -> Document:
+    base = dict(kind="page", title="T", slug="t", body="", tags=[])
+    base.update(kwargs)
+    return Document(**base)
+
+
+async def _seed(db: AsyncSession) -> list[Document]:
+    docs = [
+        _doc(title="NAS", slug="nas", body="The Synology holds every backup.", tags=["storage"]),
+        _doc(title="Router", slug="router", body="Runs OPNsense on 192.168.1.1.", tags=["network"]),
+        _doc(title="VLAN plan", slug="vlan-plan", body="Guest traffic is isolated.", tags=["network"]),
+    ]
+    for doc in docs:
+        db.add(doc)
+        await db.flush()
+        await doc_search.index_document(db, doc)
+    await db.flush()
+    return docs
+
+
+# ── the MATCH expression ────────────────────────────────────────────────────
+
+
+def test_match_query_quotes_every_term_and_prefixes_it():
+    assert doc_search.build_match_query("nas backup") == '"nas"* AND "backup"*'
+
+
+def test_match_query_neutralises_punctuation_a_user_types():
+    # An IP and a lone quote are data, not FTS5 syntax.
+    assert doc_search.build_match_query("192.168.1.1") == '"192.168.1.1"*'
+    assert doc_search.build_match_query('a"b') == '"a""b"*'
+
+
+def test_match_query_of_whitespace_is_empty():
+    assert doc_search.build_match_query("   ") == ""
+
+
+def test_tags_text_flattens_a_list():
+    assert doc_search.tags_text(["a", "b"]) == "a b"
+    assert doc_search.tags_text(None) == ""
+
+
+# ── FTS5 ────────────────────────────────────────────────────────────────────
+
+
+async def test_fts_is_available_when_the_index_table_exists(db_session: AsyncSession):
+    assert await doc_search.fts_available(db_session) is True
+
+
+async def test_search_finds_a_word_that_is_only_in_a_body(db_session: AsyncSession):
+    await _seed(db_session)
+    engine, hits = await doc_search.search(db_session, "Synology")
+    assert engine == "fts5"
+    assert len(hits) == 1
+    assert "Synology" in hits[0]["snippet"]
+
+
+async def test_search_matches_a_prefix(db_session: AsyncSession):
+    await _seed(db_session)
+    _, hits = await doc_search.search(db_session, "OPNsen")
+    assert len(hits) == 1
+
+
+async def test_search_matches_a_title(db_session: AsyncSession):
+    await _seed(db_session)
+    _, hits = await doc_search.search(db_session, "VLAN")
+    assert len(hits) == 1
+
+
+async def test_search_matches_a_tag(db_session: AsyncSession):
+    await _seed(db_session)
+    _, hits = await doc_search.search(db_session, "network")
+    assert len(hits) == 2
+
+
+async def test_search_ands_its_terms(db_session: AsyncSession):
+    await _seed(db_session)
+    _, hits = await doc_search.search(db_session, "guest traffic")
+    assert len(hits) == 1
+    _, none = await doc_search.search(db_session, "guest Synology")
+    assert none == []
+
+
+async def test_search_of_an_empty_query_returns_nothing(db_session: AsyncSession):
+    await _seed(db_session)
+    _, hits = await doc_search.search(db_session, "   ")
+    assert hits == []
+
+
+async def test_reindexing_replaces_the_previous_body(db_session: AsyncSession):
+    docs = await _seed(db_session)
+    docs[0].body = "Replaced entirely."
+    await doc_search.index_document(db_session, docs[0])
+    _, gone = await doc_search.search(db_session, "Synology")
+    assert gone == []
+    _, found = await doc_search.search(db_session, "Replaced")
+    assert len(found) == 1
+
+
+async def test_unindexing_removes_the_document(db_session: AsyncSession):
+    docs = await _seed(db_session)
+    await doc_search.unindex_document(db_session, docs[0].id)
+    _, hits = await doc_search.search(db_session, "Synology")
+    assert hits == []
+
+
+async def test_the_limit_is_honoured(db_session: AsyncSession):
+    for i in range(8):
+        doc = _doc(title=f"D{i}", slug=f"d{i}", body="shared word here")
+        db_session.add(doc)
+        await db_session.flush()
+        await doc_search.index_document(db_session, doc)
+    _, hits = await doc_search.search(db_session, "shared", limit=3)
+    assert len(hits) == 3
+
+
+# ── the LIKE fallback ───────────────────────────────────────────────────────
+
+
+async def test_search_falls_back_to_like_without_fts5(db_session: AsyncSession):
+    await _seed(db_session)
+    await db_session.execute(text("DROP TABLE documents_fts"))
+    doc_search.reset_availability_cache()
+
+    engine, hits = await doc_search.search(db_session, "Synology")
+    assert engine == "like"
+    assert len(hits) == 1
+    assert "Synology" in hits[0]["snippet"]
+
+
+async def test_indexing_is_a_no_op_without_fts5(db_session: AsyncSession):
+    await db_session.execute(text("DROP TABLE documents_fts"))
+    doc_search.reset_availability_cache()
+    doc = _doc(title="NAS", slug="nas", body="body")
+    db_session.add(doc)
+    await db_session.flush()
+    # Must not raise — writes carry on, only search degrades.
+    await doc_search.index_document(db_session, doc)
+    await doc_search.unindex_document(db_session, doc.id)
+
+
+async def test_like_fallback_is_case_insensitive(db_session: AsyncSession):
+    await _seed(db_session)
+    await db_session.execute(text("DROP TABLE documents_fts"))
+    doc_search.reset_availability_cache()
+    _, hits = await doc_search.search(db_session, "synology")
+    assert len(hits) == 1
+
+
+def test_excerpt_centres_on_the_match():
+    body = "x" * 200 + "needle" + "y" * 200
+    excerpt = doc_search._excerpt(body, "needle")
+    assert "needle" in excerpt
+    assert excerpt.startswith("…") and excerpt.endswith("…")
+
+
+def test_excerpt_falls_back_to_the_head_when_there_is_no_match():
+    assert doc_search._excerpt("short body", "absent") == "short body"

backend/tests/test_doc_template.py

@@ -0,0 +1,392 @@
+"""The generated skeleton. Written once, then owned by the user — so what it
+emits on day one is the whole contract."""
+
+from datetime import date, datetime, timezone
+from types import SimpleNamespace
+
+from app.services import doc_template as t
+
+
+def _device(**overrides):
+    base = dict(
+        id="dev-1",
+        label="nas-01",
+        friendly_name=None,
+        hostname="nas-01.lan",
+        ip="192.168.1.20",
+        mac="00:11:32:aa:bb:cc",
+        ieee_address=None,
+        os="DSM 7.2",
+        vendor="Synology",
+        model="DS920+",
+        type="nas",
+        suggested_type=None,
+        services=[
+            {"port": 5000, "protocol": "tcp", "service_name": "Synology DSM", "category": "management"},
+            {"port": 445, "protocol": "tcp", "service_name": "SMB"},
+        ],
+        properties=[{"key": "serial", "value": "20C0PDN", "icon": None, "visible": True}],
+        cpu_count=4,
+        cpu_model="Intel Celeron J4125",
+        ram_gb=20.0,
+        disk_gb=32000.0,
+        check_method="http",
+        check_target="http://192.168.1.20:5000",
+        discovery_source="arp",
+        discovery_sources=["arp", "mdns"],
+        discovered_at=datetime(2026, 3, 4, tzinfo=timezone.utc),
+        notes="",
+    )
+    base.update(overrides)
+    return SimpleNamespace(**base)
+
+
+# ── cells and names ─────────────────────────────────────────────────────────
+
+
+def test_cell_escapes_pipes_and_collapses_newlines():
+    assert t.cell("a|b") == r"a\|b"
+    assert t.cell("one\ntwo") == "one two"
+    assert t.cell(None) == "—"
+    assert t.cell("") == "—"
+
+
+def test_cell_escapes_backslash_before_pipe():
+    # Backslash first, or the escape of the pipe would itself be escaped.
+    assert t.cell(r"a\|b") == r"a\\\|b"
+
+
+def test_device_name_falls_back_through_label_hostname_ip():
+    assert t.device_name(_device()) == "nas-01"
+    assert t.device_name(_device(label=None)) == "nas-01.lan"
+    assert t.device_name(_device(label=None, hostname=None)) == "192.168.1.20"
+    assert t.device_name(_device(label=None, hostname=None, ip=None)) == "device"
+
+
+def test_device_type_prefers_curated_over_guessed():
+    assert t.device_type(_device(type="nas", suggested_type="server")) == "nas"
+    assert t.device_type(_device(type=None, suggested_type="server")) == "server"
+
+
+# ── blocks ──────────────────────────────────────────────────────────────────
+
+
+def test_device_info_block_reads_every_address():
+    md = t.block_device_info(_device())
+    assert "| Hostname | nas-01.lan |" in md
+    assert "| IP | 192.168.1.20 |" in md
+    assert "| Vendor / Model | Synology / DS920+ |" in md
+    assert "`http` → `http://192.168.1.20:5000`" in md
+    assert "(arp, mdns)" in md
+
+
+def test_device_info_block_prints_dashes_for_missing_facts():
+    md = t.block_device_info(_device(hostname=None, mac=None, os=None, vendor=None, model=None))
+    assert "| Hostname | — |" in md
+    assert "| Vendor / Model | — |" in md
+
+
+def test_hardware_block_joins_cpu_model_and_count():
+    assert "Intel Celeron J4125 ×4" in t.block_hardware(_device())
+    assert "20 GB" in t.block_hardware(_device())
+
+
+def test_hardware_block_handles_a_count_without_a_model():
+    assert "4 cores" in t.block_hardware(_device(cpu_model=None))
+
+
+# ── hardware comes out of `properties` first ────────────────────────────────
+
+# What the Proxmox import and the scanner actually write.
+_PROXMOX_PROPERTIES = [
+    {"key": "VMID", "value": "108"},
+    {"key": "Kind", "value": "LXC"},
+    {"key": "CPU Cores", "value": "4"},
+    {"key": "RAM", "value": "6.1 GB"},
+    {"key": "Disk", "value": "50.0 GB"},
+]
+
+
+def _from_properties(**overrides):
+    """A row as the importers leave it: hardware in properties, columns empty."""
+    return _device(
+        **{
+            "properties": _PROXMOX_PROPERTIES,
+            "cpu_count": None,
+            "cpu_model": None,
+            "ram_gb": None,
+            "disk_gb": None,
+            **overrides,
+        }
+    )
+
+
+def test_hardware_block_reads_the_properties_when_the_columns_are_empty():
+    """The regression: an empty hardware table beside a full properties one.
+
+    `cpu_count` / `ram_gb` / `disk_gb` are barely written any more — the same
+    facts arrive as properties — so the table printed three em dashes next to a
+    properties table listing all three.
+    """
+    md = t.block_hardware(_from_properties())
+    assert "| 4 cores | 6.1 GB | 50.0 GB |" in md
+    assert "—" not in md
+
+
+def test_hardware_block_takes_a_property_value_verbatim():
+    # "6.1 GB" is already formatted; appending a unit would say "6.1 GB GB", and
+    # guessing one onto a bare number would be inventing a fact.
+    md = t.block_hardware(_from_properties(properties=[{"key": "RAM", "value": "12288 MB"}]))
+    assert "| 12288 MB |" in md
+
+
+def test_hardware_block_matches_property_keys_whatever_their_case():
+    md = t.block_hardware(_from_properties(properties=[{"key": "ram", "value": "8 GB"}]))
+    assert "8 GB" in md
+
+
+def test_hardware_block_accepts_the_common_synonyms():
+    md = t.block_hardware(
+        _from_properties(
+            properties=[
+                {"key": "Processor", "value": "Xeon E3-1220"},
+                {"key": "vCPU", "value": "8"},
+                {"key": "Memory", "value": "64 GB"},
+                {"key": "Storage", "value": "4 TB"},
+            ]
+        )
+    )
+    assert "| Xeon E3-1220 ×8 | 64 GB | 4 TB |" in md
+
+
+def test_hardware_block_prefers_a_property_over_the_legacy_column():
+    md = t.block_hardware(_device(properties=[{"key": "RAM", "value": "64 GB"}]))
+    assert "64 GB" in md
+    assert "20 GB" not in md
+
+
+def test_hardware_block_still_falls_back_to_the_columns():
+    # A row that predates the move, or one typed into the inventory modal.
+    md = t.block_hardware(_device(properties=[]))
+    assert "Intel Celeron J4125 ×4" in md
+    assert "20 GB" in md
+
+
+def test_hardware_block_is_empty_when_neither_source_has_anything():
+    md = t.block_hardware(
+        _device(properties=[], cpu_count=None, cpu_model=None, ram_gb=None, disk_gb=None)
+    )
+    assert "| — | — | — |" in md
+
+
+def test_hardware_block_ignores_a_property_with_no_value():
+    md = t.block_hardware(_from_properties(properties=[{"key": "RAM", "value": ""}]))
+    assert "| — | — | — |" in md
+
+
+def test_property_map_keeps_the_first_of_a_repeated_key():
+    device = _device(properties=[{"key": "RAM", "value": "first"}, {"key": "RAM", "value": "second"}])
+    assert t.property_map(device)["ram"] == "first"
+
+
+# ── the snapshot follows what the tables print ──────────────────────────────
+
+
+def test_the_snapshot_carries_the_properties():
+    snapshot = t.facts_snapshot(_from_properties())
+    assert snapshot["properties"]["RAM"] == "6.1 GB"
+
+
+def test_editing_a_property_is_drift():
+    before = t.facts_snapshot(_from_properties())
+    after = t.facts_snapshot(
+        _from_properties(properties=[*_PROXMOX_PROPERTIES[:3], {"key": "RAM", "value": "12 GB"}])
+    )
+    assert before != after
+
+
+def test_the_snapshot_survives_its_json_round_trip():
+    """It is stored as JSON and compared against a freshly computed one.
+
+    A tuple or a set would come back a list and every document would read as
+    drifted forever, so the shape has to be JSON-native on both sides.
+    """
+    import json
+
+    snapshot = t.facts_snapshot(_from_properties())
+    assert json.loads(json.dumps(snapshot)) == snapshot
+
+
+def test_services_block_writes_one_section_per_service():
+    md = t.block_services(_device())
+    assert "### Synology DSM — `5000/tcp`" in md
+    assert "### SMB — `445/tcp`" in md
+    assert "**Category** — management" in md
+    # Prompts, not values — the user fills these in.
+    assert md.count("**Purpose**") == 2
+
+
+def test_services_block_says_so_when_nothing_was_fingerprinted():
+    assert "No service" in t.block_services(_device(services=[]))
+
+
+def test_services_block_never_invents_a_url_for_a_non_http_port():
+    md = t.block_services(_device(services=[{"port": 445, "protocol": "tcp", "service_name": "SMB"}]))
+    assert "**URL**" not in md
+
+
+def test_services_block_builds_an_http_url_from_the_device_ip():
+    assert "<http://192.168.1.20:5000>" in t.block_services(_device())
+
+
+def test_properties_block_is_empty_when_the_device_has_none():
+    assert t.block_properties(_device(properties=[])) == ""
+    assert "| serial | 20C0PDN |" in t.block_properties(_device())
+
+
+def test_rack_block_prints_the_span_of_units():
+    md = t.block_rack(_device(), rack={"name": "Rack-A", "u_start": 12, "u_height": 3, "col_span": 12})
+    assert md == "Rack **Rack-A**, U12–U14, full width."
+
+
+def test_rack_block_collapses_a_single_unit():
+    md = t.block_rack(_device(), rack={"name": "Rack-A", "u_start": 7, "u_height": 1, "col_span": 6})
+    assert "U7," in md and "–" not in md
+    assert "6/12 wide" in md
+
+
+def test_rack_block_is_empty_when_the_device_is_neither_racked_nor_zoned():
+    assert t.block_rack(_device()) == ""
+    assert t.block_rack(_device(), zone_label="Garage") == "Zone **Garage**."
+
+
+def test_network_block_guesses_the_slash_24_and_lists_peers():
+    md = t.block_network(_device(), connections=["switch-core", "router"])
+    assert "192.168.1.0/24" in md
+    assert "`switch-core`, `router`" in md
+
+
+def test_network_block_takes_the_first_ip_of_a_multi_ip_device():
+    assert "10.0.0.0/24" in t.block_network(_device(ip="10.0.0.5, 192.168.1.20"))
+
+
+def test_network_block_survives_a_device_with_no_ip():
+    assert "**Subnet / VLAN** — _…_" in t.block_network(_device(ip=None))
+
+
+def test_render_block_rejects_an_unknown_name():
+    try:
+        t.render_block("nope", _device())
+    except ValueError as exc:
+        assert "Unknown block" in str(exc)
+    else:
+        raise AssertionError("expected ValueError")
+
+
+# ── the whole document ──────────────────────────────────────────────────────
+
+
+def test_device_document_carries_every_section():
+    md = t.render_device_document(_device(), today=date(2026, 9, 5))
+    for heading in (
+        "## Device Information",
+        "### Hardware",
+        "## Services",
+        "## Network",
+        "## Configuration",
+        "## Operations",
+        "## Troubleshooting",
+        "## Dependencies",
+        "## Changelog",
+        "## Notes",
+    ):
+        assert heading in md, heading
+
+
+def test_device_document_opens_with_versioned_frontmatter():
+    md = t.render_device_document(_device(), today=date(2026, 9, 5))
+    assert md.startswith("---\n")
+    assert f"homelable: {t.FRONTMATTER_VERSION}" in md
+    assert "device: dev-1" in md
+    assert "created: 2026-09-05" in md
+    assert "review_every: 6m" in md
+    assert "tags: []" in md
+
+
+def test_library_document_advertises_tags_too():
+    assert "tags: []" in t.render_library_document(t.TEMPLATE_RUNBOOK, "Reboot the NAS")
+
+
+def test_device_document_appends_old_notes_verbatim_with_provenance():
+    notes = "Runs the backups.\n\n  Indented line kept as typed | with a pipe."
+    md = t.render_device_document(_device(notes=notes), today=date(2026, 9, 5))
+    assert "<!-- Migrated verbatim from this device's Notes field on 2026-09-05. -->" in md
+    assert notes.strip() in md
+
+
+def test_device_document_prompts_when_there_were_no_notes():
+    md = t.render_device_document(_device(notes=""))
+    assert "Migrated verbatim" not in md
+    assert "_Anything worth remembering about this device._" in md
+
+
+def test_device_document_drops_the_location_section_when_there_is_no_place():
+    assert "### Physical location" not in t.render_device_document(_device())
+    md = t.render_device_document(_device(), zone_label="Garage")
+    assert "### Physical location" in md
+
+
+def test_device_document_drops_the_properties_section_when_there_are_none():
+    assert "### Properties" not in t.render_device_document(_device(properties=[]))
+
+
+def test_device_document_of_a_bare_device_still_renders():
+    bare = SimpleNamespace(id="d", label=None, notes=None)
+    md = t.render_device_document(bare)
+    assert "# device" in md
+    assert "## Services" in md
+
+
+# ── library templates ───────────────────────────────────────────────────────
+
+
+def test_runbook_template_has_its_headings():
+    md = t.render_library_document(t.TEMPLATE_RUNBOOK, "Reboot the NAS", today=date(2026, 9, 5))
+    assert "# Reboot the NAS" in md
+    assert "## Rollback" in md
+    assert "template: runbook" in md
+
+
+def test_blank_template_is_just_a_title():
+    md = t.render_library_document(t.TEMPLATE_BLANK, "Scratch")
+    assert "# Scratch" in md
+    assert "##" not in md
+
+
+def test_unknown_template_falls_back_to_blank_rather_than_failing():
+    md = t.render_library_document("does-not-exist", "Scratch")
+    assert "# Scratch" in md
+
+
+def test_frontmatter_omits_empty_scalars_but_prints_an_empty_list():
+    # `tags: []` is how a user learns tags exist at all, so an empty list stays.
+    rendered = t.render_frontmatter({"a": 1, "b": None, "c": "", "d": [], "e": ["x", "y"]})
+    assert rendered == "---\na: 1\nd: []\ne: [x, y]\n---"
+
+
+# ── the drift snapshot ──────────────────────────────────────────────────────
+
+
+def test_facts_snapshot_keys_services_by_port_protocol_name():
+    snapshot = t.facts_snapshot(_device())
+    assert snapshot["services"] == ["445|tcp|smb", "5000|tcp|synology dsm"]
+
+
+def test_facts_snapshot_is_stable_when_services_are_reordered():
+    a = t.facts_snapshot(_device())
+    b = t.facts_snapshot(_device(services=list(reversed(_device().services))))
+    assert a == b
+
+
+def test_facts_snapshot_changes_when_the_ip_moves():
+    assert t.facts_snapshot(_device()) != t.facts_snapshot(_device(ip="192.168.1.21"))

backend/tests/test_doc_tree.py

@@ -0,0 +1,153 @@
+"""Slugs, frontmatter parsing, and the two tree guards."""
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import Document
+from app.services import doc_tree
+
+
+def _doc(**kwargs) -> Document:
+    base = dict(kind="folder", title="T", slug="t", body="")
+    base.update(kwargs)
+    return Document(**base)
+
+
+# ── slugs ───────────────────────────────────────────────────────────────────
+
+
+def test_slugify_lowercases_and_collapses_punctuation():
+    assert doc_tree.slugify("NAS-01 / main storage!") == "nas-01-main-storage"
+
+
+def test_slugify_of_nothing_is_untitled():
+    assert doc_tree.slugify("") == "untitled"
+    assert doc_tree.slugify("   ") == "untitled"
+    assert doc_tree.slugify("!!!") == "untitled"
+
+
+def test_slugify_truncates_a_long_title():
+    assert len(doc_tree.slugify("x" * 200)) == 80
+
+
+async def test_unique_slug_suffixes_a_taken_sibling(db_session: AsyncSession):
+    db_session.add(_doc(title="Network", slug="network"))
+    await db_session.flush()
+    assert await doc_tree.unique_slug(db_session, "Network", parent_id=None) == "network-2"
+
+
+async def test_unique_slug_keeps_counting_past_the_second(db_session: AsyncSession):
+    db_session.add(_doc(slug="network"))
+    db_session.add(_doc(slug="network-2"))
+    await db_session.flush()
+    assert await doc_tree.unique_slug(db_session, "Network", parent_id=None) == "network-3"
+
+
+async def test_unique_slug_only_looks_at_siblings(db_session: AsyncSession):
+    parent = _doc(title="Folder", slug="folder")
+    db_session.add(parent)
+    await db_session.flush()
+    db_session.add(_doc(slug="network", parent_id=parent.id))
+    await db_session.flush()
+    # Same slug, different parent — no clash.
+    assert await doc_tree.unique_slug(db_session, "Network", parent_id=None) == "network"
+
+
+async def test_unique_slug_ignores_the_document_being_renamed(db_session: AsyncSession):
+    doc = _doc(title="Network", slug="network")
+    db_session.add(doc)
+    await db_session.flush()
+    assert await doc_tree.unique_slug(db_session, "Network", parent_id=None, exclude_id=doc.id) == "network"
+
+
+# ── frontmatter ─────────────────────────────────────────────────────────────
+
+
+def test_parse_frontmatter_reads_the_leading_block():
+    body = "---\ntitle: NAS\ntags: [a, b]\n---\n\n# NAS\n"
+    assert doc_tree.parse_frontmatter(body) == {"title": "NAS", "tags": ["a", "b"]}
+
+
+def test_parse_frontmatter_ignores_a_block_that_is_not_first():
+    assert doc_tree.parse_frontmatter("# Title\n\n---\ntitle: NAS\n---\n") == {}
+
+
+def test_parse_frontmatter_of_malformed_yaml_is_empty_not_an_error():
+    # The user is mid-edit; the cache goes stale, the save does not fail.
+    assert doc_tree.parse_frontmatter("---\ntitle: [unclosed\n---\nbody") == {}
+
+
+def test_parse_frontmatter_of_a_non_mapping_is_empty():
+    assert doc_tree.parse_frontmatter("---\n- a\n- b\n---\n") == {}
+
+
+def test_parse_frontmatter_of_an_empty_body_is_empty():
+    assert doc_tree.parse_frontmatter("") == {}
+
+
+def test_parse_frontmatter_keeps_a_trailing_space_on_the_fence():
+    assert doc_tree.parse_frontmatter("--- \ntitle: NAS\n--- \n") == {"title": "NAS"}
+
+
+def test_parse_frontmatter_of_an_unclosed_block_does_not_go_quadratic():
+    """A body that opens a block and never closes it must still be linear.
+
+    The shape a document has while the block is being typed, and the input the
+    scanner named: `---\n` then many repetitions of `\n `. With `\s*` around the
+    fences the closing alternative was reachable two ways and each added line
+    multiplied the backtracking.
+    """
+    import time
+
+    body = "---\n" + "\n " * 40_000
+    started = time.perf_counter()
+    assert doc_tree.parse_frontmatter(body) == {}
+    assert time.perf_counter() - started < 1.0
+
+
+def test_tags_accepts_a_list_or_a_comma_string():
+    assert doc_tree.tags_from({"tags": ["a", " b "]}) == ["a", "b"]
+    assert doc_tree.tags_from({"tags": "a, b"}) == ["a", "b"]
+    assert doc_tree.tags_from({"tags": 7}) == []
+    assert doc_tree.tags_from({}) == []
+
+
+# ── tree guards ─────────────────────────────────────────────────────────────
+
+
+async def _chain(db_session: AsyncSession, depth: int) -> list[Document]:
+    docs: list[Document] = []
+    parent_id = None
+    for i in range(depth):
+        doc = _doc(title=f"L{i}", slug=f"l{i}", parent_id=parent_id)
+        db_session.add(doc)
+        await db_session.flush()
+        docs.append(doc)
+        parent_id = doc.id
+    return docs
+
+
+async def test_is_ancestor_walks_the_whole_chain(db_session: AsyncSession):
+    a, b, c = await _chain(db_session, 3)
+    assert await doc_tree.is_ancestor(db_session, a.id, c.id)
+    assert not await doc_tree.is_ancestor(db_session, c.id, a.id)
+
+
+async def test_a_document_is_its_own_ancestor(db_session: AsyncSession):
+    (a,) = await _chain(db_session, 1)
+    assert await doc_tree.is_ancestor(db_session, a.id, a.id)
+
+
+async def test_subtree_ids_collects_every_descendant(db_session: AsyncSession):
+    a, b, c = await _chain(db_session, 3)
+    sibling = _doc(title="S", slug="s", parent_id=a.id)
+    db_session.add(sibling)
+    await db_session.flush()
+    ids = await doc_tree.subtree_ids(db_session, a.id)
+    assert set(ids) == {a.id, b.id, c.id, sibling.id}
+    # Root first, so a caller deleting in reverse removes leaves first.
+    assert ids[0] == a.id
+
+
+async def test_subtree_ids_of_a_leaf_is_just_itself(db_session: AsyncSession):
+    (a,) = await _chain(db_session, 1)
+    assert await doc_tree.subtree_ids(db_session, a.id) == [a.id]

backend/tests/test_documents.py

@@ -0,0 +1,774 @@
+"""The documents API.
+
+Covers what the plan promises the user: a document per device generated once,
+a Library tree that cannot be knotted, history that survives a restore, and a
+document that outlives the device it describes.
+"""
+
+import uuid
+
+from httpx import AsyncClient
+
+
+async def _device(client: AsyncClient, headers: dict, **body) -> dict:
+    payload = {"label": "nas-01", "hostname": "nas-01.lan", "ip": "192.168.1.20", "discovery_source": "manual", **body}
+    res = await client.post("/api/v1/scan/pending", json=payload, headers=headers)
+    assert res.status_code in (200, 201), res.text
+    return res.json()
+
+
+async def _create(client: AsyncClient, headers: dict, **body) -> dict:
+    res = await client.post("/api/v1/documents", json={"title": "Page", **body}, headers=headers)
+    assert res.status_code == 201, res.text
+    return res.json()
+
+
+async def _design(client: AsyncClient, headers: dict) -> str:
+    res = await client.post("/api/v1/designs", json={"name": "D"}, headers=headers)
+    assert res.status_code == 201, res.text
+    return res.json()["id"]
+
+
+# ── auth ────────────────────────────────────────────────────────────────────
+
+
+async def test_list_requires_auth(client: AsyncClient):
+    assert (await client.get("/api/v1/documents")).status_code == 401
+
+
+async def test_create_requires_auth(client: AsyncClient):
+    assert (await client.post("/api/v1/documents", json={"title": "X"})).status_code == 401
+
+
+async def test_search_requires_auth(client: AsyncClient):
+    assert (await client.get("/api/v1/documents/search?q=x")).status_code == 401
+
+
+async def test_coverage_requires_auth(client: AsyncClient):
+    assert (await client.get("/api/v1/documents/coverage")).status_code == 401
+
+
+async def test_delete_requires_auth(client: AsyncClient):
+    assert (await client.delete("/api/v1/documents/x")).status_code == 401
+
+
+# ── create ──────────────────────────────────────────────────────────────────
+
+
+async def test_create_a_blank_page(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="VLAN plan")
+    assert doc["kind"] == "page"
+    assert doc["slug"] == "vlan-plan"
+    assert "# VLAN plan" in doc["body"]
+
+
+async def test_create_a_page_from_a_template(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="Reboot the NAS", template_id="runbook")
+    assert "## Rollback" in doc["body"]
+    assert doc["template_id"] == "runbook"
+
+
+async def test_create_a_page_with_an_explicit_body(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="Raw", body="---\ntags: [a]\n---\n\nhello")
+    assert doc["body"].endswith("hello")
+    # The frontmatter cache is derived from the body, never sent on its own.
+    assert doc["frontmatter"] == {"tags": ["a"]}
+    assert doc["tags"] == ["a"]
+
+
+async def test_create_a_folder(client: AsyncClient, headers: dict):
+    folder = await _create(client, headers, title="Runbooks", kind="folder")
+    child = await _create(client, headers, title="Reboot", parent_id=folder["id"])
+    assert child["parent_id"] == folder["id"]
+
+
+async def test_create_rejects_an_unknown_kind(client: AsyncClient, headers: dict):
+    res = await client.post("/api/v1/documents", json={"title": "X", "kind": "wat"}, headers=headers)
+    assert res.status_code == 422
+
+
+async def test_create_rejects_an_unknown_template(client: AsyncClient, headers: dict):
+    res = await client.post("/api/v1/documents", json={"title": "X", "template_id": "wat"}, headers=headers)
+    assert res.status_code == 422
+
+
+async def test_create_rejects_a_missing_parent(client: AsyncClient, headers: dict):
+    res = await client.post(
+        "/api/v1/documents", json={"title": "X", "parent_id": str(uuid.uuid4())}, headers=headers
+    )
+    assert res.status_code == 404
+
+
+async def test_create_rejects_a_page_that_also_names_a_device(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    res = await client.post(
+        "/api/v1/documents", json={"title": "X", "kind": "page", "device_id": device["id"]}, headers=headers
+    )
+    assert res.status_code == 400
+
+
+async def test_create_rejects_a_device_document_naming_nothing(client: AsyncClient, headers: dict):
+    res = await client.post("/api/v1/documents", json={"title": "X", "kind": "device"}, headers=headers)
+    assert res.status_code == 400
+
+
+async def test_create_rejects_two_links_at_once(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    res = await client.post(
+        "/api/v1/documents",
+        json={"title": "X", "kind": "device", "device_id": device["id"], "design_id": await _design(client, headers)},
+        headers=headers,
+    )
+    assert res.status_code == 400
+
+
+async def test_create_rejects_a_device_that_does_not_exist(client: AsyncClient, headers: dict):
+    res = await client.post(
+        "/api/v1/documents",
+        json={"title": "X", "kind": "device", "device_id": str(uuid.uuid4())},
+        headers=headers,
+    )
+    assert res.status_code == 404
+
+
+async def test_a_device_gets_at_most_one_document(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    body = {"title": "nas", "kind": "device", "device_id": device["id"]}
+    assert (await client.post("/api/v1/documents", json=body, headers=headers)).status_code == 201
+    second = await client.post("/api/v1/documents", json=body, headers=headers)
+    assert second.status_code == 409
+
+
+async def test_a_sibling_title_gets_a_distinct_slug(client: AsyncClient, headers: dict):
+    first = await _create(client, headers, title="Network")
+    second = await _create(client, headers, title="Network")
+    assert first["slug"] == "network"
+    assert second["slug"] == "network-2"
+
+
+# ── the generated device document ───────────────────────────────────────────
+
+
+async def test_a_device_document_is_scaffolded_from_the_live_facts(client: AsyncClient, headers: dict):
+    device = await _device(
+        client, headers, hostname="nas-01.lan", vendor="Synology", notes="Holds the backups."
+    )
+    doc = await _create(client, headers, title="nas-01", kind="device", device_id=device["id"])
+    assert "| Hostname | nas-01.lan |" in doc["body"]
+    assert "| IP | 192.168.1.20 |" in doc["body"]
+    assert "Holds the backups." in doc["body"]
+    assert doc["facts_snapshot"]["ip"] == "192.168.1.20"
+    assert doc["facts_synced_at"] is not None
+
+
+async def test_the_old_notes_column_is_left_untouched_by_scaffolding(client: AsyncClient, headers: dict):
+    device = await _device(client, headers, notes="Holds the backups.")
+    await _create(client, headers, title="nas-01", kind="device", device_id=device["id"])
+    res = await client.get("/api/v1/scan/pending", headers=headers)
+    row = next(d for d in res.json() if d["id"] == device["id"])
+    assert row["notes"] == "Holds the backups."
+
+
+async def test_a_device_document_records_its_zone_and_neighbours(client: AsyncClient, headers: dict):
+    design_id = await _design(client, headers)
+    device = await _device(client, headers)
+    zone = await client.post(
+        "/api/v1/nodes",
+        json={"type": "groupRect", "label": "Garage", "design_id": design_id, "pos_x": 0, "pos_y": 0},
+        headers=headers,
+    )
+    zone_id = zone.json()["id"]
+    # A node binds to its inventory row by its addresses, not by an id on the
+    # payload — the canvas is one more way to document hardware, not a store.
+    node = await client.post(
+        "/api/v1/nodes",
+        json={
+            "type": "nas",
+            "label": "nas-01",
+            "design_id": design_id,
+            "ip": "192.168.1.20",
+            "hostname": "nas-01.lan",
+            "parent_id": zone_id,
+            "pos_x": 0,
+            "pos_y": 0,
+        },
+        headers=headers,
+    )
+    assert node.json()["device_id"] == device["id"], node.text
+    peer = await client.post(
+        "/api/v1/nodes",
+        json={"type": "switch", "label": "switch-core", "design_id": design_id, "pos_x": 0, "pos_y": 0},
+        headers=headers,
+    )
+    await client.post(
+        "/api/v1/edges",
+        json={"source": node.json()["id"], "target": peer.json()["id"], "type": "ethernet"},
+        headers=headers,
+    )
+
+    doc = await _create(client, headers, title="nas-01", kind="device", device_id=device["id"])
+    assert "Zone **Garage**." in doc["body"]
+    assert "`switch-core`" in doc["body"]
+
+
+# ── blocks ──────────────────────────────────────────────────────────────────
+
+
+async def test_a_block_can_be_regenerated_on_demand(client: AsyncClient, headers: dict):
+    device = await _device(client, headers, hostname="nas-01.lan")
+    res = await client.get(
+        f"/api/v1/documents/blocks?block=device-info&device_id={device['id']}", headers=headers
+    )
+    assert res.status_code == 200, res.text
+    assert "| Hostname | nas-01.lan |" in res.json()["markdown"]
+
+
+async def test_an_unknown_block_is_rejected(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    res = await client.get(f"/api/v1/documents/blocks?block=nope&device_id={device['id']}", headers=headers)
+    assert res.status_code == 400
+
+
+async def test_a_block_for_a_missing_device_is_404(client: AsyncClient, headers: dict):
+    res = await client.get(
+        f"/api/v1/documents/blocks?block=device-info&device_id={uuid.uuid4()}", headers=headers
+    )
+    assert res.status_code == 404
+
+
+# ── read / list ─────────────────────────────────────────────────────────────
+
+
+async def test_get_a_missing_document_is_404(client: AsyncClient, headers: dict):
+    assert (await client.get(f"/api/v1/documents/{uuid.uuid4()}", headers=headers)).status_code == 404
+
+
+async def test_listing_carries_no_body(client: AsyncClient, headers: dict):
+    await _create(client, headers, title="VLAN plan")
+    row = (await client.get("/api/v1/documents", headers=headers)).json()[0]
+    assert "body" not in row
+
+
+async def test_listing_filters_by_kind_and_parent(client: AsyncClient, headers: dict):
+    folder = await _create(client, headers, title="Runbooks", kind="folder")
+    await _create(client, headers, title="Reboot", parent_id=folder["id"])
+    await _create(client, headers, title="Loose")
+
+    folders = (await client.get("/api/v1/documents?kind=folder", headers=headers)).json()
+    assert [d["title"] for d in folders] == ["Runbooks"]
+
+    children = (await client.get(f"/api/v1/documents?parent_id={folder['id']}", headers=headers)).json()
+    assert [d["title"] for d in children] == ["Reboot"]
+
+
+async def test_listing_filters_by_tag(client: AsyncClient, headers: dict):
+    await _create(client, headers, title="A", body="---\ntags: [Network]\n---\n")
+    await _create(client, headers, title="B", body="---\ntags: [storage]\n---\n")
+    hits = (await client.get("/api/v1/documents?tag=network", headers=headers)).json()
+    assert [d["title"] for d in hits] == ["A"]
+
+
+# ── update ──────────────────────────────────────────────────────────────────
+
+
+async def test_editing_the_body_refreshes_the_frontmatter_cache(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="Page")
+    res = await client.patch(
+        f"/api/v1/documents/{doc['id']}", json={"body": "---\ntags: [x]\n---\n\nnew"}, headers=headers
+    )
+    assert res.status_code == 200, res.text
+    assert res.json()["tags"] == ["x"]
+
+
+async def test_the_body_renames_the_document(client: AsyncClient, headers: dict):
+    """`title:` in the frontmatter is the only place a document is named."""
+    doc = await _create(client, headers, title="Page")
+    res = await client.patch(
+        f"/api/v1/documents/{doc['id']}",
+        json={"body": "---\ntitle: SMB / CIFS\n---\n\n# SMB / CIFS\n"},
+        headers=headers,
+    )
+    assert res.status_code == 200, res.text
+    assert res.json()["title"] == "SMB / CIFS"
+    assert res.json()["slug"] == "smb-cifs"
+
+
+async def test_a_body_without_a_title_keeps_the_one_it_has(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="Page")
+    res = await client.patch(
+        f"/api/v1/documents/{doc['id']}", json={"body": "---\ntags: [x]\n---\n\nnew"}, headers=headers
+    )
+    assert res.json()["title"] == "Page"
+
+
+async def test_a_blank_title_in_the_body_is_ignored(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="Page")
+    res = await client.patch(
+        f"/api/v1/documents/{doc['id']}", json={"body": "---\ntitle: '   '\n---\n\nnew"}, headers=headers
+    )
+    assert res.json()["title"] == "Page"
+
+
+async def test_an_explicit_title_wins_over_the_body_in_the_same_request(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="Page")
+    res = await client.patch(
+        f"/api/v1/documents/{doc['id']}",
+        json={"title": "Chosen", "body": "---\ntitle: From the body\n---\n\nnew"},
+        headers=headers,
+    )
+    assert res.json()["title"] == "Chosen"
+
+
+async def test_a_device_document_renamed_in_its_body_keeps_its_device(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    doc = await _create(client, headers, title="nas-01", kind="device", device_id=device["id"])
+    res = await client.patch(
+        f"/api/v1/documents/{doc['id']}",
+        json={"body": "---\ntitle: The big NAS\n---\n\n# The big NAS\n"},
+        headers=headers,
+    )
+    assert res.json()["title"] == "The big NAS"
+    assert res.json()["device_id"] == device["id"]
+
+
+async def test_renaming_reslugs(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="Page")
+    res = await client.patch(f"/api/v1/documents/{doc['id']}", json={"title": "New name"}, headers=headers)
+    assert res.json()["slug"] == "new-name"
+
+
+async def test_starring_and_reviewing(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="Page")
+    res = await client.patch(
+        f"/api/v1/documents/{doc['id']}", json={"starred": True, "reviewed": True}, headers=headers
+    )
+    assert res.json()["starred"] is True
+    assert res.json()["reviewed_at"] is not None
+
+
+async def test_patching_a_missing_document_is_404(client: AsyncClient, headers: dict):
+    res = await client.patch(f"/api/v1/documents/{uuid.uuid4()}", json={"title": "X"}, headers=headers)
+    assert res.status_code == 404
+
+
+async def test_a_folder_cannot_be_moved_inside_itself(client: AsyncClient, headers: dict):
+    outer = await _create(client, headers, title="Outer", kind="folder")
+    inner = await _create(client, headers, title="Inner", kind="folder", parent_id=outer["id"])
+    res = await client.patch(f"/api/v1/documents/{outer['id']}", json={"parent_id": inner["id"]}, headers=headers)
+    assert res.status_code == 400
+
+
+async def test_a_document_can_only_be_filed_under_a_folder(client: AsyncClient, headers: dict):
+    page = await _create(client, headers, title="Page")
+    other = await _create(client, headers, title="Other")
+    res = await client.patch(f"/api/v1/documents/{other['id']}", json={"parent_id": page["id"]}, headers=headers)
+    assert res.status_code == 400
+
+
+async def test_a_device_document_does_not_live_in_the_library_tree(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    doc = await _create(client, headers, title="nas", kind="device", device_id=device["id"])
+    folder = await _create(client, headers, title="F", kind="folder")
+    res = await client.patch(f"/api/v1/documents/{doc['id']}", json={"parent_id": folder["id"]}, headers=headers)
+    assert res.status_code == 400
+
+
+async def test_resyncing_facts_clears_the_drift_without_touching_the_body(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    doc = await _create(client, headers, title="nas", kind="device", device_id=device["id"])
+    await client.patch(f"/api/v1/scan/pending/{device['id']}", json={"ip": "192.168.1.99"}, headers=headers)
+
+    res = await client.patch(f"/api/v1/documents/{doc['id']}", json={"resync_facts": True}, headers=headers)
+    assert res.json()["facts_snapshot"]["ip"] == "192.168.1.99"
+    # The header the user owns still says what it always said.
+    assert "192.168.1.20" in res.json()["body"]
+
+
+# ── drift ───────────────────────────────────────────────────────────────────
+
+
+async def test_a_fresh_device_document_has_not_drifted(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    doc = await _create(client, headers, title="nas-01", kind="device", device_id=device["id"])
+    assert doc["drifted"] is False
+    read = (await client.get(f"/api/v1/documents/{doc['id']}", headers=headers)).json()
+    assert read["drifted"] is False
+
+
+async def test_changing_the_device_marks_the_document_drifted(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    doc = await _create(client, headers, title="nas-01", kind="device", device_id=device["id"])
+    await client.patch(
+        f"/api/v1/scan/pending/{device['id']}", json={"ip": "192.168.1.99"}, headers=headers
+    )
+    read = (await client.get(f"/api/v1/documents/{doc['id']}", headers=headers)).json()
+    assert read["drifted"] is True
+
+
+async def test_a_property_edit_alone_marks_the_document_drifted(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    doc = await _create(client, headers, title="nas-01", kind="device", device_id=device["id"])
+    await client.patch(
+        f"/api/v1/scan/pending/{device['id']}",
+        json={"properties": [{"key": "Rack", "value": "A1"}]},
+        headers=headers,
+    )
+    read = (await client.get(f"/api/v1/documents/{doc['id']}", headers=headers)).json()
+    assert read["drifted"] is True
+
+
+async def test_editing_the_body_does_not_make_a_document_drift(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    doc = await _create(client, headers, title="nas-01", kind="device", device_id=device["id"])
+    res = await client.patch(f"/api/v1/documents/{doc['id']}", json={"body": "my words"}, headers=headers)
+    assert res.json()["drifted"] is False
+
+
+async def test_accepting_the_facts_clears_the_drift(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    doc = await _create(client, headers, title="nas-01", kind="device", device_id=device["id"])
+    await client.patch(
+        f"/api/v1/scan/pending/{device['id']}", json={"ip": "192.168.1.99"}, headers=headers
+    )
+    res = await client.patch(
+        f"/api/v1/documents/{doc['id']}", json={"resync_facts": True}, headers=headers
+    )
+    assert res.json()["drifted"] is False
+
+
+async def test_regenerating_clears_the_drift(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    doc = await _create(client, headers, title="nas-01", kind="device", device_id=device["id"])
+    await client.patch(
+        f"/api/v1/scan/pending/{device['id']}", json={"ip": "192.168.1.99"}, headers=headers
+    )
+    res = await client.post(f"/api/v1/documents/{doc['id']}/regenerate", headers=headers)
+    assert res.json()["drifted"] is False
+
+
+async def test_the_listing_carries_the_drift_flag_for_the_tree_badge(
+    client: AsyncClient, headers: dict
+):
+    fresh = await _device(client, headers, label="switch-01", ip="192.168.1.2")
+    stale = await _device(client, headers, label="nas-01", ip="192.168.1.20")
+    in_sync = await _create(client, headers, title="switch-01", kind="device", device_id=fresh["id"])
+    moved = await _create(client, headers, title="nas-01", kind="device", device_id=stale["id"])
+    await client.patch(
+        f"/api/v1/scan/pending/{stale['id']}", json={"ip": "192.168.1.99"}, headers=headers
+    )
+
+    listing = (await client.get("/api/v1/documents", headers=headers)).json()
+    by_id = {d["id"]: d for d in listing}
+    assert by_id[moved["id"]]["drifted"] is True
+    assert by_id[in_sync["id"]]["drifted"] is False
+
+
+async def test_a_library_page_never_drifts(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="VLAN plan")
+    assert doc["drifted"] is False
+
+
+# ── revisions ───────────────────────────────────────────────────────────────
+
+
+async def test_an_edit_records_the_previous_body(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="Page", body="first")
+    await client.patch(f"/api/v1/documents/{doc['id']}", json={"body": "second"}, headers=headers)
+    revisions = (await client.get(f"/api/v1/documents/{doc['id']}/revisions", headers=headers)).json()
+    assert len(revisions) == 1
+    assert revisions[0]["reason"] == "edit"
+    stored = (await client.get(f"/api/v1/documents/revisions/{revisions[0]['id']}", headers=headers)).json()
+    assert stored["body"] == "first"
+
+
+async def test_saving_an_unchanged_body_records_nothing(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="Page", body="same")
+    await client.patch(f"/api/v1/documents/{doc['id']}", json={"body": "same"}, headers=headers)
+    assert (await client.get(f"/api/v1/documents/{doc['id']}/revisions", headers=headers)).json() == []
+
+
+async def test_restoring_brings_back_an_old_body_and_is_itself_undoable(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="Page", body="first")
+    await client.patch(f"/api/v1/documents/{doc['id']}", json={"body": "second"}, headers=headers)
+    revision = (await client.get(f"/api/v1/documents/{doc['id']}/revisions", headers=headers)).json()[0]
+
+    res = await client.post(
+        f"/api/v1/documents/{doc['id']}/revisions/{revision['id']}/restore", headers=headers
+    )
+    assert res.status_code == 200, res.text
+    assert res.json()["body"] == "first"
+
+    history = (await client.get(f"/api/v1/documents/{doc['id']}/revisions", headers=headers)).json()
+    assert [r["reason"] for r in history][0] == "restore"
+
+
+async def test_restoring_brings_back_the_title_that_body_carried(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="Page", body="---\ntitle: First name\n---\n\nfirst")
+    await client.patch(
+        f"/api/v1/documents/{doc['id']}",
+        json={"body": "---\ntitle: Second name\n---\n\nsecond"},
+        headers=headers,
+    )
+    revision = (await client.get(f"/api/v1/documents/{doc['id']}/revisions", headers=headers)).json()[0]
+
+    res = await client.post(
+        f"/api/v1/documents/{doc['id']}/revisions/{revision['id']}/restore", headers=headers
+    )
+    assert res.json()["title"] == "First name"
+
+
+async def test_restoring_a_revision_of_another_document_is_404(client: AsyncClient, headers: dict):
+    a = await _create(client, headers, title="A", body="one")
+    b = await _create(client, headers, title="B", body="one")
+    await client.patch(f"/api/v1/documents/{a['id']}", json={"body": "two"}, headers=headers)
+    revision = (await client.get(f"/api/v1/documents/{a['id']}/revisions", headers=headers)).json()[0]
+    res = await client.post(f"/api/v1/documents/{b['id']}/revisions/{revision['id']}/restore", headers=headers)
+    assert res.status_code == 404
+
+
+async def test_history_is_pruned_to_the_limit(client: AsyncClient, headers: dict):
+    from app.services.doc_tree import REVISION_LIMIT
+
+    doc = await _create(client, headers, title="Page", body="v0")
+    for i in range(1, REVISION_LIMIT + 6):
+        await client.patch(f"/api/v1/documents/{doc['id']}", json={"body": f"v{i}"}, headers=headers)
+    revisions = (await client.get(f"/api/v1/documents/{doc['id']}/revisions", headers=headers)).json()
+    assert len(revisions) == REVISION_LIMIT
+
+
+# ── regenerate ──────────────────────────────────────────────────────────────
+
+
+async def test_regenerate_requires_auth(client: AsyncClient):
+    assert (await client.post("/api/v1/documents/x/regenerate")).status_code == 401
+
+
+async def test_regenerating_a_device_document_rebuilds_it_from_the_facts(
+    client: AsyncClient, headers: dict
+):
+    device = await _device(client, headers)
+    doc = await _create(client, headers, title="nas-01", kind="device", device_id=device["id"])
+    await client.patch(f"/api/v1/documents/{doc['id']}", json={"body": "everything I wrote"}, headers=headers)
+
+    res = await client.post(f"/api/v1/documents/{doc['id']}/regenerate", headers=headers)
+    assert res.status_code == 200, res.text
+    body = res.json()
+    assert "everything I wrote" not in body["body"]
+    assert "192.168.1.20" in body["body"]
+    # A regenerated document is only the template again, as it was on day one.
+    assert body["edited_at"] is None
+    assert body["template_id"] == "device"
+
+
+async def test_regenerating_reads_the_devices_current_facts(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    doc = await _create(client, headers, title="nas-01", kind="device", device_id=device["id"])
+    await client.patch(
+        f"/api/v1/scan/pending/{device['id']}", json={"ip": "192.168.1.99"}, headers=headers
+    )
+
+    res = await client.post(f"/api/v1/documents/{doc['id']}/regenerate", headers=headers)
+    assert "192.168.1.99" in res.json()["body"]
+    # Regenerating documents the device as it is now, so the drift is gone.
+    assert res.json()["facts_snapshot"]["ip"] == "192.168.1.99"
+
+
+async def test_regenerating_keeps_the_replaced_body_in_the_history(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="VLAN plan", body="my own words")
+    await client.post(f"/api/v1/documents/{doc['id']}/regenerate", headers=headers)
+
+    revisions = (await client.get(f"/api/v1/documents/{doc['id']}/revisions", headers=headers)).json()
+    assert revisions[0]["reason"] == "regenerate"
+    stored = (await client.get(f"/api/v1/documents/revisions/{revisions[0]['id']}", headers=headers)).json()
+    assert stored["body"] == "my own words"
+
+
+async def test_regenerating_a_library_page_uses_its_template(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="Restart the NAS", template_id="runbook")
+    await client.patch(f"/api/v1/documents/{doc['id']}", json={"body": "gone"}, headers=headers)
+
+    res = await client.post(f"/api/v1/documents/{doc['id']}/regenerate", headers=headers)
+    assert res.status_code == 200, res.text
+    assert "gone" not in res.json()["body"]
+    assert "# Restart the NAS" in res.json()["body"]
+    assert res.json()["template_id"] == "runbook"
+
+
+async def test_regenerating_a_folder_is_rejected(client: AsyncClient, headers: dict):
+    folder = await _create(client, headers, title="Runbooks", kind="folder")
+    res = await client.post(f"/api/v1/documents/{folder['id']}/regenerate", headers=headers)
+    assert res.status_code == 400
+
+
+async def test_regenerating_an_unknown_document_is_404(client: AsyncClient, headers: dict):
+    res = await client.post(f"/api/v1/documents/{uuid.uuid4()}/regenerate", headers=headers)
+    assert res.status_code == 404
+
+
+# ── delete ──────────────────────────────────────────────────────────────────
+
+
+async def test_deleting_a_folder_takes_its_subtree(client: AsyncClient, headers: dict):
+    outer = await _create(client, headers, title="Outer", kind="folder")
+    inner = await _create(client, headers, title="Inner", kind="folder", parent_id=outer["id"])
+    leaf = await _create(client, headers, title="Leaf", parent_id=inner["id"])
+
+    assert (await client.delete(f"/api/v1/documents/{outer['id']}", headers=headers)).status_code == 204
+    for doc_id in (outer["id"], inner["id"], leaf["id"]):
+        assert (await client.get(f"/api/v1/documents/{doc_id}", headers=headers)).status_code == 404
+
+
+async def test_deleting_a_missing_document_is_404(client: AsyncClient, headers: dict):
+    assert (await client.delete(f"/api/v1/documents/{uuid.uuid4()}", headers=headers)).status_code == 404
+
+
+async def test_a_deleted_document_leaves_the_search_index(client: AsyncClient, headers: dict):
+    doc = await _create(client, headers, title="Page", body="unmistakable")
+    await client.delete(f"/api/v1/documents/{doc['id']}", headers=headers)
+    hits = (await client.get("/api/v1/documents/search?q=unmistakable", headers=headers)).json()["hits"]
+    assert hits == []
+
+
+# ── the document outlives what it describes ─────────────────────────────────
+
+
+async def test_deleting_a_device_orphans_its_document_but_keeps_the_body(client: AsyncClient, headers: dict):
+    device = await _device(client, headers, notes="Holds the backups.")
+    doc = await _create(client, headers, title="nas-01", kind="device", device_id=device["id"])
+
+    assert (await client.delete(f"/api/v1/scan/pending/{device['id']}", headers=headers)).status_code == 200
+
+    after = (await client.get(f"/api/v1/documents/{doc['id']}", headers=headers)).json()
+    assert after["device_id"] is None
+    assert after["title"] == "nas-01"
+    assert "Holds the backups." in after["body"]
+
+
+async def test_deleting_a_node_orphans_the_document_describing_it(client: AsyncClient, headers: dict):
+    design_id = await _design(client, headers)
+    zone = await client.post(
+        "/api/v1/nodes",
+        json={"type": "groupRect", "label": "Garage", "design_id": design_id, "pos_x": 0, "pos_y": 0},
+        headers=headers,
+    )
+    doc = await _create(client, headers, title="Garage", kind="node", node_id=zone.json()["id"])
+
+    await client.delete(f"/api/v1/nodes/{zone.json()['id']}", headers=headers)
+
+    after = (await client.get(f"/api/v1/documents/{doc['id']}", headers=headers)).json()
+    assert after["node_id"] is None
+    assert after["title"] == "Garage"
+
+
+# ── search ──────────────────────────────────────────────────────────────────
+
+
+async def test_search_names_its_engine_and_returns_hits(client: AsyncClient, headers: dict):
+    await _create(client, headers, title="VLAN plan", body="Guest traffic is isolated.")
+    res = await client.get("/api/v1/documents/search?q=isolated", headers=headers)
+    assert res.status_code == 200, res.text
+    payload = res.json()
+    assert payload["engine"] in ("fts5", "like")
+    assert [h["title"] for h in payload["hits"]] == ["VLAN plan"]
+
+
+async def test_search_carries_the_device_link_so_a_hit_can_be_opened(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    await _create(client, headers, title="nas-01", kind="device", device_id=device["id"])
+    hits = (await client.get("/api/v1/documents/search?q=nas", headers=headers)).json()["hits"]
+    assert hits[0]["device_id"] == device["id"]
+
+
+async def test_search_rejects_a_silly_limit(client: AsyncClient, headers: dict):
+    assert (await client.get("/api/v1/documents/search?q=x&limit=0", headers=headers)).status_code == 422
+
+
+# ── scaffold and coverage ───────────────────────────────────────────────────
+
+
+async def test_scaffold_documents_every_device_that_has_none(client: AsyncClient, headers: dict):
+    await _device(client, headers, label="a", ip="10.0.0.1")
+    await _device(client, headers, label="b", ip="10.0.0.2")
+    res = await client.post("/api/v1/documents/scaffold", json={}, headers=headers)
+    assert res.status_code == 200, res.text
+    assert len(res.json()["created"]) == 2
+
+
+async def test_scaffold_is_repeatable_and_skips_what_exists(client: AsyncClient, headers: dict):
+    await _device(client, headers, label="a", ip="10.0.0.1")
+    await client.post("/api/v1/documents/scaffold", json={}, headers=headers)
+    again = (await client.post("/api/v1/documents/scaffold", json={}, headers=headers)).json()
+    assert again["created"] == []
+    assert again["skipped"] == 1
+
+
+async def test_scaffold_can_be_limited_to_devices_that_have_notes(client: AsyncClient, headers: dict):
+    await _device(client, headers, label="a", ip="10.0.0.1", notes="worth keeping")
+    await _device(client, headers, label="b", ip="10.0.0.2")
+    res = (
+        await client.post("/api/v1/documents/scaffold", json={"only_with_notes": True}, headers=headers)
+    ).json()
+    assert [d["title"] for d in res["created"]] == ["a"]
+    assert res["skipped"] == 1
+
+
+async def test_scaffold_can_be_limited_to_named_devices(client: AsyncClient, headers: dict):
+    first = await _device(client, headers, label="a", ip="10.0.0.1")
+    await _device(client, headers, label="b", ip="10.0.0.2")
+    res = (
+        await client.post("/api/v1/documents/scaffold", json={"device_ids": [first["id"]]}, headers=headers)
+    ).json()
+    assert [d["title"] for d in res["created"]] == ["a"]
+
+
+async def test_a_migrated_document_records_why_it_exists(client: AsyncClient, headers: dict):
+    device = await _device(client, headers, notes="worth keeping")
+    created = (
+        await client.post("/api/v1/documents/scaffold", json={}, headers=headers)
+    ).json()["created"][0]
+    revisions = (await client.get(f"/api/v1/documents/{created['id']}/revisions", headers=headers)).json()
+    assert revisions[0]["reason"] == "migrate"
+    assert device["id"]
+
+
+async def test_coverage_counts_what_is_missing_and_unmigrated(client: AsyncClient, headers: dict):
+    await _device(client, headers, label="a", ip="10.0.0.1", notes="notes here")
+    await _device(client, headers, label="b", ip="10.0.0.2")
+
+    before = (await client.get("/api/v1/documents/coverage", headers=headers)).json()
+    assert before["devices"] == 2
+    assert before["documented"] == 0
+    assert before["missing"] == 2
+    assert before["notes_unmigrated"] == 1
+
+    await client.post("/api/v1/documents/scaffold", json={}, headers=headers)
+    after = (await client.get("/api/v1/documents/coverage", headers=headers)).json()
+    assert after["documented"] == 2
+    assert after["missing"] == 0
+    assert after["notes_unmigrated"] == 0
+    # Generated and not yet touched.
+    assert after["header_only"] == 2
+
+
+async def test_coverage_reports_a_document_that_has_drifted(client: AsyncClient, headers: dict):
+    device = await _device(client, headers)
+    await _create(client, headers, title="nas", kind="device", device_id=device["id"])
+    assert (await client.get("/api/v1/documents/coverage", headers=headers)).json()["drifted"] == 0
+
+    await client.patch(f"/api/v1/scan/pending/{device['id']}", json={"ip": "192.168.1.99"}, headers=headers)
+    assert (await client.get("/api/v1/documents/coverage", headers=headers)).json()["drifted"] == 1
+
+
+async def test_coverage_stops_calling_a_document_header_only_once_it_is_edited(
+    client: AsyncClient, headers: dict
+):
+    device = await _device(client, headers)
+    doc = await _create(client, headers, title="nas", kind="device", device_id=device["id"])
+    await client.patch(f"/api/v1/documents/{doc['id']}", json={"body": "written by hand"}, headers=headers)
+    assert (await client.get("/api/v1/documents/coverage", headers=headers)).json()["header_only"] == 0
+
+
+async def test_coverage_counts_library_pages_separately(client: AsyncClient, headers: dict):
+    await _create(client, headers, title="VLAN plan")
+    await _create(client, headers, title="Runbooks", kind="folder")
+    assert (await client.get("/api/v1/documents/coverage", headers=headers)).json()["library_pages"] == 2

backend/tests/test_documents_migration.py

@@ -0,0 +1,158 @@
+"""The documents DDL `create_all` does not apply.
+
+Column additions to an existing table (which `create_all` never makes), plus a
+virtual table and three partial indexes (which it cannot express at all), all
+applied through `_try_migrate` at boot. Every one has to survive a second boot
+untouched, and the partial uniques are what stop two documents claiming the same
+device behind the route's own check.
+"""
+
+import pytest
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from app.db.database import DOCUMENT_DDL, Base, _try_migrate
+
+pytestmark = pytest.mark.asyncio
+
+
+async def _boot(tmp_path, times: int = 1):
+    engine = create_async_engine(f"sqlite+aiosqlite:///{tmp_path / 'test.db'}")
+    for _ in range(times):
+        async with engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+            for label, sql in DOCUMENT_DDL:
+                await _try_migrate(conn, sql, label=label)
+    return engine
+
+
+async def _names(engine, kind: str) -> set[str]:
+    async with engine.begin() as conn:
+        rows = (
+            await conn.exec_driver_sql(f"SELECT name FROM sqlite_master WHERE type = '{kind}'")
+        ).fetchall()
+    return {row[0] for row in rows}
+
+
+async def test_the_tables_and_the_search_index_are_created(tmp_path):
+    engine = await _boot(tmp_path)
+    tables = await _names(engine, "table")
+    assert {"documents", "document_revisions", "documents_fts"} <= tables
+    await engine.dispose()
+
+
+async def test_the_partial_uniques_are_created(tmp_path):
+    engine = await _boot(tmp_path)
+    indexes = await _names(engine, "index")
+    assert {"ux_documents_device", "ux_documents_node", "ux_documents_design"} <= indexes
+    await engine.dispose()
+
+
+async def test_a_second_boot_changes_nothing(tmp_path):
+    engine = await _boot(tmp_path, times=3)
+    tables = await _names(engine, "table")
+    assert {"documents", "documents_fts"} <= tables
+    await engine.dispose()
+
+
+async def test_two_documents_cannot_claim_the_same_device(tmp_path):
+    engine = await _boot(tmp_path)
+    async with engine.begin() as conn:
+        insert = (
+            "INSERT INTO documents (id, kind, title, slug, body, device_id, sort_order, "
+            "frontmatter, tags, starred, created_at, updated_at) "
+            "VALUES (?, 'device', 'nas', ?, '', 'dev-1', 0, '{}', '[]', 0, "
+            "'2026-09-05', '2026-09-05')"
+        )
+        await conn.exec_driver_sql(insert, ("a", "nas"))
+        with pytest.raises(IntegrityError):
+            await conn.exec_driver_sql(insert, ("b", "nas-2"))
+    await engine.dispose()
+
+
+async def test_many_documents_may_have_no_device(tmp_path):
+    engine = await _boot(tmp_path)
+    async with engine.begin() as conn:
+        insert = (
+            "INSERT INTO documents (id, kind, title, slug, body, device_id, sort_order, "
+            "frontmatter, tags, starred, created_at, updated_at) "
+            "VALUES (?, 'page', 'p', ?, '', NULL, 0, '{}', '[]', 0, "
+            "'2026-09-05', '2026-09-05')"
+        )
+        await conn.exec_driver_sql(insert, ("a", "p1"))
+        await conn.exec_driver_sql(insert, ("b", "p2"))
+        count = (await conn.exec_driver_sql("SELECT COUNT(*) FROM documents")).scalar_one()
+    assert count == 2
+    await engine.dispose()
+
+
+# ── columns added to a table that already exists ─────────────────────────────
+
+# `documents` as an earlier build of the feature created it: no `edited_at`.
+_DOCUMENTS_WITHOUT_EDITED_AT = (
+    "CREATE TABLE documents ("
+    "id VARCHAR NOT NULL PRIMARY KEY, kind VARCHAR NOT NULL, title VARCHAR NOT NULL, "
+    "slug VARCHAR NOT NULL, icon VARCHAR, parent_id VARCHAR, sort_order INTEGER, "
+    "device_id VARCHAR, node_id VARCHAR, design_id VARCHAR, body TEXT NOT NULL, "
+    "frontmatter JSON, tags JSON, starred BOOLEAN, template_id VARCHAR, "
+    "facts_snapshot JSON, facts_synced_at DATETIME, reviewed_at DATETIME, "
+    "created_at DATETIME, updated_at DATETIME)"
+)
+
+
+async def _columns(engine, table: str) -> list[str]:
+    async with engine.begin() as conn:
+        rows = (await conn.exec_driver_sql(f"PRAGMA table_info({table})")).fetchall()
+    return [row[1] for row in rows]
+
+
+async def test_an_existing_table_gains_the_columns_create_all_would_not_add(tmp_path):
+    """The regression: `create_all` makes a missing table, never a missing column.
+
+    A database that met an earlier shape of `documents` kept it, and every query
+    naming `edited_at` failed with ``no such column: documents.edited_at`` —
+    including the one behind opening the Documentation section.
+    """
+    engine = create_async_engine(f"sqlite+aiosqlite:///{tmp_path / 'test.db'}")
+    async with engine.begin() as conn:
+        await conn.exec_driver_sql(_DOCUMENTS_WITHOUT_EDITED_AT)
+    assert "edited_at" not in await _columns(engine, "documents")
+
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)  # sees the table, leaves it be
+        for label, sql in DOCUMENT_DDL:
+            await _try_migrate(conn, sql, label=label)
+
+    assert "edited_at" in await _columns(engine, "documents")
+    await engine.dispose()
+
+
+async def test_the_old_rows_survive_the_column_being_added(tmp_path):
+    engine = create_async_engine(f"sqlite+aiosqlite:///{tmp_path / 'test.db'}")
+    async with engine.begin() as conn:
+        await conn.exec_driver_sql(_DOCUMENTS_WITHOUT_EDITED_AT)
+        await conn.exec_driver_sql(
+            "INSERT INTO documents (id, kind, title, slug, body) "
+            "VALUES ('d1', 'page', 'Rebuild plan', 'rebuild-plan', '# Rebuild plan')"
+        )
+
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+        for label, sql in DOCUMENT_DDL:
+            await _try_migrate(conn, sql, label=label)
+
+    async with engine.begin() as conn:
+        row = (
+            await conn.exec_driver_sql("SELECT title, body, edited_at FROM documents WHERE id = 'd1'")
+        ).fetchone()
+    assert row == ("Rebuild plan", "# Rebuild plan", None)
+    await engine.dispose()
+
+
+async def test_a_fresh_database_has_every_column(tmp_path):
+    engine = await _boot(tmp_path, times=2)
+    columns = await _columns(engine, "documents")
+    assert "edited_at" in columns
+    # The re-stated ALTERs are idempotent: no column is added twice.
+    assert len(columns) == len(set(columns))
+    await engine.dispose()

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,12 +84,107 @@ 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"})
     assert res.status_code == 401
 
 
+async def test_create_edge_without_design_id_falls_back_to_first_design(client: AsyncClient, headers: dict, two_nodes):
+    # Regression for #225: MCP create_edge sent no design_id, so edges were
+    # persisted with design_id=null and never rendered until a restart.
+    src, tgt = two_nodes
+    design = await client.post("/api/v1/designs", json={"name": "Primary"}, headers=headers)
+    design_id = design.json()["id"]
+
+    res = await client.post(
+        "/api/v1/edges",
+        json={"source": src, "target": tgt, "type": "ethernet"},
+        headers=headers,
+    )
+    assert res.status_code == 201
+    assert res.json()["design_id"] == design_id
+
+
+async def test_create_edge_respects_explicit_design_id(client: AsyncClient, headers: dict, two_nodes):
+    src, tgt = two_nodes
+    await client.post("/api/v1/designs", json={"name": "First"}, headers=headers)
+    second = await client.post("/api/v1/designs", json={"name": "Second"}, headers=headers)
+    second_id = second.json()["id"]
+
+    res = await client.post(
+        "/api/v1/edges",
+        json={"source": src, "target": tgt, "type": "ethernet", "design_id": second_id},
+        headers=headers,
+    )
+    assert res.status_code == 201
+    assert res.json()["design_id"] == second_id
+
+
 async def test_create_cluster_edge_with_handles(client: AsyncClient, headers: dict, two_nodes):
     src, tgt = two_nodes
     res = await client.post(
@@ -132,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_fingerprint.py

@@ -2,7 +2,13 @@ from unittest.mock import patch
 
 import pytest
 
-from app.services.fingerprint import fingerprint_ports, match_port, suggest_node_type
+from app.services.fingerprint import (
+    fingerprint_ports,
+    match_port,
+    match_service,
+    suggest_node_type,
+    suggest_type_from_mac,
+)
 
 MOCK_SIGNATURES = [
     {"port": 80, "protocol": "tcp", "banner_regex": None, "service_name": "HTTP", "icon": "🌐", "category": "web", "suggested_node_type": "server"},
@@ -118,6 +124,41 @@ def test_suggest_node_type_priority_proxmox_over_server():
     assert result == "proxmox"
 
 
+# A port-agnostic signature: only an HTTP probe can ever match it.
+KVM_SIGNATURE = {
+    "port": None, "protocol": "tcp", "banner_regex": None, "http_regex": "PiKVM",
+    "service_name": "PiKVM", "icon": "monitorcog", "category": "kvm",
+    "suggested_node_type": "kvm",
+}
+
+
+def test_suggest_node_type_kvm_from_http_title():
+    # An IP-KVM answers on 443 like any web app; only the probed title identifies it.
+    with patch("app.services.fingerprint._load", return_value=[*MOCK_SIGNATURES, KVM_SIGNATURE]):
+        result = suggest_node_type([
+            {"port": 443, "protocol": "tcp", "http_signals": {"title": "PiKVM", "headers": {}}},
+        ])
+    assert result == "kvm"
+
+
+def test_suggest_node_type_priority_kvm_over_server():
+    # The same host also answers on 80 (→ server); the KVM signal outranks it.
+    with patch("app.services.fingerprint._load", return_value=[*MOCK_SIGNATURES, KVM_SIGNATURE]):
+        result = suggest_node_type([
+            {"port": 80, "protocol": "tcp"},
+            {"port": 443, "protocol": "tcp", "http_signals": {"title": "PiKVM", "headers": {}}},
+        ])
+    assert result == "kvm"
+
+
+def test_suggest_node_type_ignores_port_agnostic_sig_without_probe():
+    # No http_signals (probe disabled) → port-agnostic entries can't match and the
+    # port-only guess stands, unchanged from pre-probe behaviour.
+    with patch("app.services.fingerprint._load", return_value=[*MOCK_SIGNATURES, KVM_SIGNATURE]):
+        result = suggest_node_type([{"port": 443, "protocol": "tcp"}])
+    assert result == "server"
+
+
 def test_suggest_node_type_camera_from_rtsp_port():
     # RTSP port 554 → camera (via _PORT_TYPE_HINTS)
     result = suggest_node_type([{"port": 554, "protocol": "tcp"}])
@@ -173,3 +214,157 @@ def test_suggest_node_type_iot_wins_over_server_when_mqtt_present():
         {"port": 1883, "protocol": "tcp"},
     ])
     assert result == "iot"
+
+
+# ── OUI vendor detection ──────────────────────────────────────────────────────
+
+def test_suggest_type_from_mac_mikrotik_returns_router():
+    # The motivating case: MikroTik MAC should be recognized as a router
+    assert suggest_type_from_mac("4c:5e:0c:11:22:33") == "router"
+    assert suggest_type_from_mac("b8:69:f4:aa:bb:cc") == "router"
+
+
+def test_suggest_type_from_mac_ubiquiti_returns_ap():
+    # Ubiquiti makes routers, switches, APs, cameras — most homelab gear is UniFi APs,
+    # so OUI defaults to "ap". Port hints can still upgrade to "router" if BGP/VPN open.
+    assert suggest_type_from_mac("24:a4:3c:11:22:33") == "ap"
+    assert suggest_type_from_mac("fc:ec:da:aa:bb:cc") == "ap"
+
+
+def test_suggest_type_from_mac_synology_returns_nas():
+    assert suggest_type_from_mac("00:11:32:11:22:33") == "nas"
+
+
+def test_suggest_type_from_mac_qnap_returns_nas():
+    assert suggest_type_from_mac("24:5e:be:aa:bb:cc") == "nas"
+
+
+def test_suggest_type_from_mac_hikvision_returns_camera():
+    assert suggest_type_from_mac("28:57:be:11:22:33") == "camera"
+
+
+def test_suggest_type_from_mac_dahua_returns_camera():
+    assert suggest_type_from_mac("3c:ef:8c:aa:bb:cc") == "camera"
+
+
+def test_suggest_type_from_mac_cisco_returns_switch():
+    assert suggest_type_from_mac("b8:38:61:11:22:33") == "switch"
+
+
+def test_suggest_type_from_mac_raspberry_pi_returns_server():
+    assert suggest_type_from_mac("b8:27:eb:11:22:33") == "server"
+
+
+def test_suggest_type_from_mac_handles_uppercase():
+    # MACs may arrive in any case; lookup must be case-insensitive
+    assert suggest_type_from_mac("4C:5E:0C:11:22:33") == "router"
+
+
+def test_suggest_type_from_mac_unknown_oui_returns_none():
+    assert suggest_type_from_mac("00:00:01:11:22:33") is None
+
+
+def test_suggest_node_type_mikrotik_mac_returns_router_no_ports():
+    # MikroTik device with no scanned ports should still be classified as router via MAC
+    assert suggest_node_type([], mac="4c:5e:0c:11:22:33") == "router"
+
+
+def test_suggest_node_type_synology_mac_with_http_returns_nas():
+    # NAS priority beats server, so a Synology MAC + open HTTP → nas
+    result = suggest_node_type(
+        [{"port": 80, "protocol": "tcp"}],
+        mac="00:11:32:11:22:33",
+    )
+    assert result == "nas"
+
+
+def test_suggest_node_type_ubiquiti_mac_with_bgp_upgrades_to_router():
+    # Ubiquiti OUI suggests "ap", but BGP port hint upgrades to "router" (higher priority)
+    result = suggest_node_type(
+        [{"port": 179, "protocol": "tcp"}],
+        mac="24:a4:3c:11:22:33",
+    )
+    assert result == "router"
+
+
+# ── match_service: HTTP probe + port-agnostic ──────────────────────────────────
+
+HTTP_SIGNATURES = [
+    # Generic web fallback on 8096 (port-only guess)
+    {"port": 8096, "protocol": "tcp", "banner_regex": None, "http_regex": None,
+     "service_name": "HTTP", "icon": "🌐", "category": "web", "suggested_node_type": "server"},
+    # Same port, but confirmed by HTML title → should win when probe confirms
+    {"port": 8096, "protocol": "tcp", "banner_regex": None, "http_regex": "Jellyfin",
+     "service_name": "Jellyfin", "icon": "🎬", "category": "media", "suggested_node_type": "server"},
+    # Port-agnostic: matches on HTTP content regardless of port
+    {"port": None, "protocol": "tcp", "banner_regex": None, "http_regex": "Portainer",
+     "service_name": "Portainer", "icon": "🐳", "category": "container", "suggested_node_type": "server"},
+    # Banner-based entry, no http
+    {"port": 9090, "protocol": "tcp", "banner_regex": "prometheus", "http_regex": None,
+     "service_name": "Prometheus", "icon": "🔥", "category": "monitoring", "suggested_node_type": "server"},
+]
+
+
+@pytest.fixture
+def http_signatures():
+    with patch("app.services.fingerprint._load", return_value=HTTP_SIGNATURES):
+        yield
+
+
+def test_http_regex_confirmed_beats_port_only(http_signatures):
+    # Probe ran and title matches → Jellyfin (tier 1) beats generic HTTP (tier 4)
+    sig = match_service(8096, "tcp", banner=None,
+                        http_signals={"title": "Jellyfin", "headers": {}})
+    assert sig["service_name"] == "Jellyfin"
+
+
+def test_http_regex_matches_on_header(http_signatures):
+    sig = match_service(8096, "tcp", banner=None,
+                        http_signals={"title": None, "headers": {"Server": "Jellyfin"}})
+    assert sig["service_name"] == "Jellyfin"
+
+
+def test_http_regex_miss_falls_back_to_port_only(http_signatures):
+    # Probe ran but nothing matched the http_regex → generic port-only entry wins
+    sig = match_service(8096, "tcp", banner=None,
+                        http_signals={"title": "Some Other App", "headers": {}})
+    assert sig["service_name"] == "HTTP"
+
+
+def test_probe_disabled_ignores_http_regex(http_signatures):
+    # http_signals=None (deep scan off) → http_regex entry degrades to port-only,
+    # generic entry (listed first) wins — identical to pre-probe behaviour.
+    sig = match_service(8096, "tcp", banner=None, http_signals=None)
+    assert sig["service_name"] == "HTTP"
+
+
+def test_port_agnostic_match_on_custom_port(http_signatures):
+    # Portainer found on a non-standard port, recognised purely by HTTP content
+    sig = match_service(54321, "tcp", banner=None,
+                        http_signals={"title": "Portainer", "headers": {}})
+    assert sig["service_name"] == "Portainer"
+
+
+def test_port_agnostic_requires_probe(http_signatures):
+    # Same custom port, probe off → no signal → no match
+    assert match_service(54321, "tcp", banner=None, http_signals=None) is None
+
+
+def test_banner_match_still_works_with_probe(http_signatures):
+    sig = match_service(9090, "tcp", banner="prometheus 2.x",
+                        http_signals={"title": "x", "headers": {}})
+    assert sig["service_name"] == "Prometheus"
+
+
+def test_match_port_alias_has_no_http(http_signatures):
+    # match_port() is the probe-less alias → http_regex entry degrades to port-only
+    sig = match_port(8096, "tcp")
+    assert sig["service_name"] == "HTTP"
+
+
+def test_fingerprint_ports_uses_http_signals(http_signatures):
+    results = fingerprint_ports([
+        {"port": 8096, "protocol": "tcp", "banner": None,
+         "http_signals": {"title": "Jellyfin", "headers": {}}},
+    ])
+    assert results[0]["service_name"] == "Jellyfin"

backend/tests/test_http_probe.py

@@ -0,0 +1,251 @@
+"""Tests for the HTTP probe used by deep-scan service identification."""
+from unittest.mock import patch
+
+import httpx
+import pytest
+
+from app.services.http_probe import (
+    _MAX_BODY_BYTES,
+    _extract_title,
+    probe_open_ports,
+    probe_port,
+)
+
+
+def _response(text: str = "", headers: dict | None = None, status: int = 200) -> httpx.Response:
+    return httpx.Response(status_code=status, text=text, headers=headers or {})
+
+
+class _TransportClient:
+    """
+    Patch target for httpx.AsyncClient that routes through a MockTransport.
+
+    Real client, fake network: the probe exercises the genuine httpx request
+    path (including .stream() and aiter_bytes()) instead of a mock that would
+    happily accept any call shape. `requests` records what was actually sent.
+    """
+
+    def __init__(self, handler):
+        self._handler = handler
+        # Bound before patching, so building the real client here does not
+        # recurse back into this stand-in.
+        self._real = httpx.AsyncClient
+        self.kwargs: list[dict] = []
+        self.requests: list[httpx.Request] = []
+
+    def _record(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        return self._handler(request)
+
+    def __call__(self, **kwargs):
+        self.kwargs.append(dict(kwargs))
+        kwargs.pop("verify", None)
+        return self._real(transport=httpx.MockTransport(self._record), **kwargs)
+
+
+def _patch_client(handler) -> tuple:
+    """Return (context manager, factory) patching http_probe's AsyncClient."""
+    factory = _TransportClient(handler)
+    return patch("app.services.http_probe.httpx.AsyncClient", factory), factory
+
+
+# ── _extract_title ──────────────────────────────────────────────────────────
+
+def test_extract_title_basic():
+    assert _extract_title("<html><title>Jellyfin</title></html>") == "Jellyfin"
+
+
+def test_extract_title_collapses_whitespace():
+    assert _extract_title("<title>\n  My  App\n</title>") == "My App"
+
+
+def test_extract_title_missing():
+    assert _extract_title("<html><body>no title</body></html>") is None
+
+
+def test_extract_title_case_insensitive():
+    assert _extract_title("<TITLE>Portainer</TITLE>") == "Portainer"
+
+
+# ── probe_port ──────────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_probe_port_reads_title():
+    ctx, _ = _patch_client(lambda req: _response("<title>Jellyfin</title>"))
+    with ctx:
+        result = await probe_port("10.0.0.5", 8096)
+    assert result == {"title": "Jellyfin", "headers": {}}
+
+
+@pytest.mark.asyncio
+async def test_probe_port_reads_headers():
+    ctx, _ = _patch_client(
+        lambda req: _response("", headers={"Server": "nginx", "X-Powered-By": "Express"})
+    )
+    with ctx:
+        result = await probe_port("10.0.0.5", 3000)
+    assert result["headers"] == {"Server": "nginx", "X-Powered-By": "Express"}
+
+
+@pytest.mark.asyncio
+async def test_probe_port_falls_back_to_http():
+    # https raises, http succeeds
+    def handler(request):
+        if str(request.url).startswith("https"):
+            raise httpx.ConnectError("tls fail")
+        return _response("<title>HTTP App</title>")
+
+    ctx, factory = _patch_client(handler)
+    with ctx:
+        result = await probe_port("10.0.0.5", 8080)
+    assert result["title"] == "HTTP App"
+    assert len(factory.requests) == 2  # tried https then http
+
+
+@pytest.mark.asyncio
+async def test_probe_port_no_signal_returns_none():
+    ctx, _ = _patch_client(lambda req: _response(""))
+    with ctx:
+        result = await probe_port("10.0.0.5", 8080)
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_probe_port_timeout_returns_none():
+    def handler(request):
+        raise httpx.TimeoutException("slow")
+
+    ctx, _ = _patch_client(handler)
+    with ctx:
+        result = await probe_port("10.0.0.5", 8080)
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_probe_port_skips_non_http_ports():
+    # SSH should never trigger an HTTP request
+    ctx, factory = _patch_client(lambda req: _response("<title>nope</title>"))
+    with ctx:
+        result = await probe_port("10.0.0.5", 22)
+    assert result is None
+    assert factory.requests == []
+
+
+@pytest.mark.parametrize("port", [515, 9100, 9101, 9107])
+@pytest.mark.asyncio
+async def test_probe_port_never_touches_a_raw_printing_port(port):
+    """Issue #404: a printer prints whatever bytes reach 9100, GET line included."""
+    ctx, factory = _patch_client(lambda req: _response("<title>nope</title>"))
+    with ctx:
+        result = await probe_port("10.0.0.5", port)
+    assert result is None
+    assert factory.requests == []
+
+
+@pytest.mark.asyncio
+async def test_probe_open_ports_leaves_a_printer_port_alone():
+    """The batch path must skip it too, without dropping the port from the result."""
+    ports = [{"port": 8096, "protocol": "tcp"}, {"port": 9100, "protocol": "tcp"}]
+    ctx, factory = _patch_client(lambda req: _response("<title>Jellyfin</title>"))
+    with ctx:
+        result = await probe_open_ports("10.0.0.5", ports)
+
+    by_port = {p["port"]: p for p in result}
+    assert by_port[9100]["http_signals"] is None
+    assert by_port[8096]["http_signals"]["title"] == "Jellyfin"
+    assert all(":9100" not in str(r.url) for r in factory.requests)
+
+
+@pytest.mark.asyncio
+async def test_probe_port_verify_tls_flag_passed():
+    ctx, factory = _patch_client(lambda req: _response("<title>X</title>"))
+    with ctx:
+        await probe_port("10.0.0.5", 8443, verify_tls=True)
+    assert factory.kwargs[0]["verify"] is True
+
+
+# ── endless bodies (issue #375) ─────────────────────────────────────────────
+
+_CHUNK_SIZE = 16 * 1024
+
+
+def _endless_body(counter: dict, head: bytes = b""):
+    """
+    A body that never ends and declares no Content-Length. Bounded at 512
+    chunks so a regression fails the test instead of hanging the suite.
+    """
+
+    async def gen():
+        if head:
+            counter["bytes"] += len(head)
+            yield head
+        for _ in range(512):
+            counter["bytes"] += _CHUNK_SIZE
+            yield b"\0" * _CHUNK_SIZE
+
+    return gen()
+
+
+@pytest.mark.asyncio
+async def test_probe_caps_the_download_of_an_endless_body():
+    # _MAX_BODY_BYTES caps the download, not just the <title> scan: the body is
+    # streamed and the connection dropped once we hold enough. Allow one chunk
+    # of overshoot — the read stops on a chunk boundary.
+    counter = {"bytes": 0}
+
+    def handler(request):
+        # Plain HTTP only, like the reproducer, so the counter covers one probe.
+        if str(request.url).startswith("https"):
+            raise httpx.ConnectError("no tls")
+        return httpx.Response(
+            200,
+            headers={"Content-Type": "application/octet-stream"},
+            content=_endless_body(counter),
+        )
+
+    ctx, _ = _patch_client(handler)
+    with ctx:
+        result = await probe_port("10.0.0.5", 8095)
+    assert result is None  # null bytes carry no title and no signal header
+    assert counter["bytes"] <= _MAX_BODY_BYTES + _CHUNK_SIZE
+
+
+@pytest.mark.asyncio
+async def test_probe_still_reads_a_title_from_an_endless_body():
+    # Stopping early must not cost us the signal: a <title> in the first chunk
+    # is still found even though the rest of the stream is abandoned.
+    counter = {"bytes": 0}
+
+    def handler(request):
+        if str(request.url).startswith("https"):
+            raise httpx.ConnectError("no tls")
+        return httpx.Response(
+            200,
+            headers={"Content-Type": "text/html"},
+            content=_endless_body(counter, head=b"<html><title>Jellyfin</title>"),
+        )
+
+    ctx, _ = _patch_client(handler)
+    with ctx:
+        result = await probe_port("10.0.0.5", 8096)
+    assert result["title"] == "Jellyfin"
+    assert counter["bytes"] <= _MAX_BODY_BYTES + _CHUNK_SIZE
+
+
+# ── probe_open_ports ─────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_probe_open_ports_enriches_each_port():
+    def handler(request):
+        if ":8096" in str(request.url):
+            return _response("<title>Jellyfin</title>")
+        return _response("")
+
+    ports = [{"port": 8096, "protocol": "tcp"}, {"port": 9999, "protocol": "tcp"}]
+    ctx, _ = _patch_client(handler)
+    with ctx:
+        result = await probe_open_ports("10.0.0.5", ports)
+
+    by_port = {p["port"]: p for p in result}
+    assert by_port[8096]["http_signals"]["title"] == "Jellyfin"
+    assert by_port[9999]["http_signals"] is None

backend/tests/test_import_jobs.py

@@ -0,0 +1,90 @@
+"""Unit tests for the in-process canvas-import job registry."""
+
+from __future__ import annotations
+
+import pytest
+
+from app.services import import_jobs
+from app.services.import_jobs import (
+    create_job,
+    fail_job,
+    finish_job,
+    get_job,
+    reset_jobs,
+)
+
+
+@pytest.fixture(autouse=True)
+def _clean() -> None:
+    reset_jobs()
+
+
+def test_create_job_starts_running_with_unique_id() -> None:
+    a = create_job()
+    b = create_job()
+    assert a.id != b.id
+    assert a.status == "running"
+    assert a.result is None
+    assert a.error is None
+
+
+def test_get_job_returns_the_registered_job() -> None:
+    job = create_job()
+    assert get_job(job.id) is job
+
+
+def test_get_unknown_job_returns_none() -> None:
+    assert get_job("nope") is None
+
+
+def test_finish_job_records_the_payload() -> None:
+    job = create_job()
+    finish_job(job.id, {"device_count": 3})
+    stored = get_job(job.id)
+    assert stored is not None
+    assert stored.status == "done"
+    assert stored.result == {"device_count": 3}
+    assert stored.finished_at is not None
+
+
+def test_fail_job_records_message_and_status() -> None:
+    job = create_job()
+    fail_job(job.id, "broker unreachable", 502)
+    stored = get_job(job.id)
+    assert stored is not None
+    assert stored.status == "error"
+    assert stored.error == "broker unreachable"
+    assert stored.error_status == 502
+
+
+def test_finish_and_fail_are_noops_for_unknown_ids() -> None:
+    finish_job("gone", {"device_count": 0})
+    fail_job("gone", "boom", 500)
+    assert get_job("gone") is None
+
+
+def test_finished_jobs_expire_after_the_ttl(monkeypatch) -> None:
+    clock = {"now": 0.0}
+    monkeypatch.setattr(import_jobs.time, "monotonic", lambda: clock["now"])
+
+    job = create_job()
+    finish_job(job.id, {"device_count": 1})
+
+    clock["now"] = import_jobs.JOB_TTL_SECONDS + 1
+    assert get_job(job.id) is None
+
+
+def test_running_jobs_never_expire(monkeypatch) -> None:
+    """A slow mesh must not have its job purged out from under it."""
+    clock = {"now": 0.0}
+    monkeypatch.setattr(import_jobs.time, "monotonic", lambda: clock["now"])
+
+    job = create_job()
+    clock["now"] = import_jobs.JOB_TTL_SECONDS * 10
+    assert get_job(job.id) is not None
+
+
+def test_reset_jobs_clears_everything() -> None:
+    job = create_job()
+    reset_jobs()
+    assert get_job(job.id) is None

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 = {
@@ -112,6 +111,27 @@ async def test_liveview_returns_saved_canvas(client: AsyncClient, auth_headers):
     assert nodes[0]["label"] == "Live Node"
 
 
+# ── custom_style + theme propagation ─────────────────────────────────────────
+
+@pytest.mark.asyncio
+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"
+    payload = {
+        "nodes": [],
+        "edges": [],
+        "viewport": {"x": 0, "y": 0, "zoom": 1, "theme_id": "matrix"},
+        "custom_style": {"fontFamily": "Inter", "nodeRadius": 12},
+    }
+    await client.post("/api/v1/canvas/save", json=payload, headers=headers)
+
+    res = await client.get("/api/v1/liveview?key=test-key")
+    assert res.status_code == 200
+    body = res.json()
+    assert body["viewport"].get("theme_id") == "matrix"
+    assert body["custom_style"] == {"fontFamily": "Inter", "nodeRadius": 12}
+
+
 # ── Re-disable after enabling ─────────────────────────────────────────────────
 
 @pytest.mark.asyncio
@@ -124,3 +144,80 @@ async def test_liveview_disabled_after_key_cleared(client: AsyncClient):
     res = await client.get("/api/v1/liveview?key=was-enabled")
     assert res.status_code == 403
     assert res.json()["detail"] == "Live view is disabled"
+
+
+# ── /config (authenticated) — key used to build share links ──────────────────
+
+@pytest.mark.asyncio
+async def test_liveview_config_requires_auth(client: AsyncClient):
+    """The config endpoint exposes the key, so it must reject unauthenticated calls."""
+    settings.liveview_key = "secret"
+    res = await client.get("/api/v1/liveview/config")
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_liveview_config_returns_key_when_enabled(client: AsyncClient, headers):
+    settings.liveview_key = "share-me"
+    res = await client.get("/api/v1/liveview/config", headers=headers)
+    assert res.status_code == 200
+    body = res.json()
+    assert body == {"enabled": True, "key": "share-me"}
+
+
+@pytest.mark.asyncio
+async def test_liveview_config_disabled_hides_key(client: AsyncClient, headers):
+    settings.liveview_key = None
+    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, headers):
+    settings.liveview_key = ""
+    res = await client.get("/api/v1/liveview/config", headers=headers)
+    assert res.status_code == 200
+    assert res.json() == {"enabled": False, "key": None}
+
+
+# ── design_id selects which canvas is rendered ───────────────────────────────
+
+@pytest.mark.asyncio
+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"
+
+    # Create two designs
+    d1 = (await client.post("/api/v1/designs", json={"name": "Network"}, headers=headers)).json()
+    d2 = (await client.post("/api/v1/designs", json={"name": "Electrical"}, headers=headers)).json()
+
+    # Save a distinct node into each design
+    for design, node_id, label in ((d1, "n-net", "Net Node"), (d2, "n-elec", "Elec Node")):
+        payload = {
+            "nodes": [{
+                "id": node_id,
+                "type": "server",
+                "label": label,
+                "status": "online",
+                "services": [],
+                "pos_x": 0,
+                "pos_y": 0,
+            }],
+            "edges": [],
+            "viewport": {"x": 0, "y": 0, "zoom": 1},
+            "design_id": design["id"],
+        }
+        await client.post("/api/v1/canvas/save", json=payload, headers=headers)
+
+    # Requesting d2 returns only the electrical node
+    res = await client.get(f"/api/v1/liveview?key=test-key&design_id={d2['id']}")
+    assert res.status_code == 200
+    nodes = res.json()["nodes"]
+    assert [n["id"] for n in nodes] == ["n-elec"]
+
+    # Requesting d1 returns only the network node
+    res = await client.get(f"/api/v1/liveview?key=test-key&design_id={d1['id']}")
+    assert res.status_code == 200
+    nodes = res.json()["nodes"]
+    assert [n["id"] for n in nodes] == ["n-net"]