chore: bump version to 3.4.1

ha-relevant: no

.env.example

@@ -8,12 +8,19 @@ SQLITE_PATH=./data/homelab.db
 # Set this to the URL(s) you use to access Homelable in your browser.
 CORS_ORIGINS=["http://localhost:5173","http://localhost:3000"]
 
+# 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 "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'
 
@@ -89,6 +96,10 @@ MCP_SERVICE_KEY=svc_changeme
 # 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
@@ -99,3 +110,6 @@ MCP_SERVICE_KEY=svc_changeme
 # 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/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

@@ -61,10 +61,13 @@ jobs:
       - run: mypy app/
       - run: pytest
 
-  # Also guards the NODE_TYPES / EDGE_TYPES enums in mcp/app/tools.py against
-  # drift from frontend/src/types/index.ts (test_node_types_sync.py,
-  # test_edge_types_sync.py) — those tests need the frontend sources, so this
-  # job runs from a full checkout rather than the mcp Docker context.
+  # 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:

.github/workflows/security.yml

@@ -40,9 +40,17 @@ jobs:
         # --omit=dev: only ship-time deps gate the build. Dev-only tooling
         # (shadcn CLI and its transitive tree: hono, fast-uri, …) is never
         # bundled or served, so its advisories must not fail release CI.
-        run: cd frontend && npm audit --omit=dev --audit-level=high
+        #
+        # 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
-        run: pip install pip-audit && pip-audit -r backend/requirements.txt
+        # 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

CHANGELOG.md

@@ -5,6 +5,95 @@ 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.1] - 2026-09-07
+
+### Features
+
+- Duplicate Device Inventory rows can be merged. A **Merge** action in the inventory's select mode lets you pick the survivor — the only way to collapse rows that share no address at all, since a name is not an identity — and `reconcile_duplicates` now runs at the end of a Proxmox import and of a scan to collapse what a shared MAC proves (never a shared IP alone, never across two distinct IEEEs). Merging keeps everything: the survivor fills its gaps from the others, addresses, services, properties and sources union, and canvas nodes, rack mounts, documents and mesh links are re-pointed before the extra rows go. (#424)
+
+### Fixes
+
+- `dedupe_nodes_by_device` deleted duplicate nodes while `rack_devices.node_id` and `documents.node_id` still named them; SQLite runs with foreign keys off, so the declared `ON DELETE SET NULL` never fired. (#424)
+- The scanner's duplicate collapse merges instead of deleting inventory rows outright, which lost their facts and orphaned whatever drew them. Its guard against removing a second approved row is unchanged. (#424)
+- The merge dialog is wide enough to read an IEEE. The addresses are what the choice is made on, and a long name was clipped at the edge of the dialog; the address line now wraps instead of truncating, and the list grows with the viewport. (#424)
+
+## [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
@@ -20,7 +109,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 ### Fixes
 
 - Alignment guides show for nodes inside groups and containers. (#337)
-- The status check interval is applied to the running scheduler. (#319) — thanks @JaG-v2
+- 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

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

@@ -24,13 +24,14 @@ Here's what Homelable can do. One line on what each feature is, then how to swit
 10. [Z-Wave Import](#10-z-wave-import-)
 11. [Proxmox VE Import](#11-proxmox-ve-import-)
 12. [Device Inventory](#12-device-inventory-)
-13. [Live Status Monitoring](#13-live-status-monitoring-)
-14. [Export (PNG / SVG / YAML / Markdown)](#14-export)
-15. [Live View (read-only public canvas)](#15-live-view-)
-16. [Gethomepage Widget](#16-gethomepage-widget-)
-17. [MCP Server (AI integration)](#17-mcp-server-)
-18. [Settings & Shortcuts](#18-settings--shortcuts)
-19. [Authentication (Local / OpenID Connect)](#19-authentication-local--openid-connect-)
+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-)
 
 ---
 
@@ -187,7 +188,25 @@ Nodes: `proxmox` (host) / `vm` / `lxc`, linked host→guest by a `virtual` edge.
 
 ---
 
-## 13. Live Status Monitoring 🔒
+## 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.
 
@@ -208,7 +227,7 @@ Nodes: `proxmox` (host) / `vm` / `lxc`, linked host→guest by a `virtual` edge.
 
 ---
 
-## 14. Export
+## 15. Export
 
 **What:** Get your canvas out as a picture or as structured data.
 
@@ -220,7 +239,7 @@ Nodes: `proxmox` (host) / `vm` / `lxc`, linked host→guest by a `virtual` edge.
 
 ---
 
-## 15. Live View 🔒
+## 16. Live View 🔒
 
 **What:** A read-only, no-login snapshot of a canvas you can share on your LAN. Off by default.
 
@@ -232,7 +251,7 @@ Pan and zoom only, no editing. Click a node with an IP and it opens in a new tab
 
 ---
 
-## 16. Gethomepage Widget 🔒
+## 17. Gethomepage Widget 🔒
 
 **What:** A tiny JSON stats endpoint for [gethomepage](https://gethomepage.dev)'s `customapi` widget. Off by default.
 
@@ -244,7 +263,7 @@ Widget snippet lives in the [README](./README.md#gethomepage-widget-read-only-st
 
 ---
 
-## 17. MCP Server 🔒
+## 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.
 
@@ -258,11 +277,11 @@ Widget snippet lives in the [README](./README.md#gethomepage-widget-read-only-st
 2. `docker compose up -d mcp` (listens on `:8001`). No Docker? `sudo bash scripts/lxc-mcp-install.sh`.
 3. Point your client at `http://<your-homelab-ip>:8001/mcp` with header `X-API-Key: <your key>`.
 
-The AI can list nodes/edges/canvas/pending/scans, add/update/delete nodes and edges, kick off scans, and approve or hide devices. Keep port 8001 firewalled to your LAN. Full setup in the [README](./README.md#mcp-server-ai-integration-optional).
+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).
 
 ---
 
-## 18. Settings & Shortcuts
+## 19. Settings & Shortcuts
 
 **What:** App config and keyboard shortcuts.
 
@@ -273,7 +292,7 @@ The AI can list nodes/edges/canvas/pending/scans, add/update/delete nodes and ed
 
 ---
 
-## 19. Authentication (Local / OpenID Connect) 🔒
+## 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.

INSTALLATION.md

@@ -63,6 +63,48 @@ 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.
@@ -89,6 +131,236 @@ 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`):

README.md

@@ -35,6 +35,8 @@ Homelable is a self-hosted infrastructure visualization solution. It provides a
 
 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.
@@ -48,8 +50,8 @@ If you are running  <img width="22" height="22" align="top" alt="New_Home_Assist
 <p align="center">
   <img src="docs/homelable1.png" alt="Homelable canvas overview" width="100%" />
   <img  alt="Homelable Device inventory" src="https://github.com/user-attachments/assets/f3903ac8-354d-4873-81ba-1914971890ed" />
-  <img width="49.5%" alt="Homelable Custom node" src="https://github.com/user-attachments/assets/813725b1-376b-4bad-bb1f-0985f3bc7546" />
-  <img width="49.5%"  alt="Homelable Zigbee Network" src="https://github.com/user-attachments/assets/35e18d11-8363-498d-ae3d-642685cac76d" />
+ 
+<img alt="Rack display" src="https://github.com/user-attachments/assets/43273605-4f46-4163-8aea-8bf8a76a3f76" />
 
 </p>
 
@@ -57,7 +59,7 @@ If you are running  <img width="22" height="22" align="top" alt="New_Home_Assist
 
 ## Features
 
-From one-click **network scans** and **Proxmox / Zigbee / Z-Wave** imports to **live status monitoring**, floor plans, **rack canvases** with port-to-port patching, multi-canvas layouts and an **MCP server** for AI assistants — Homelable maps and watches your whole homelab.
+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)**.
 
@@ -65,7 +67,7 @@ Every feature, with how to turn it on and use it, is described in **[FEATURES.md
 
 ## Installation
 
-Docker (from the **[pre-built GHCR images](./INSTALLATION.md#pre-built-docker-images)**), 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)**.
 
 ---
 
@@ -87,6 +89,28 @@ Gear sits in a U range and part of a 12-column width grid, so half- and third-wi
 
 ---
 
+## 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)
+
+---
+
 ## Network Scanner
 
 The scanner runs `nmap -sV --open` on your configured CIDR ranges and populates a **Pending Devices** queue. From the sidebar you can then approve (adds a node to the canvas), hide, or ignore each discovered device.
@@ -110,6 +134,14 @@ 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:
@@ -328,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
 
@@ -405,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 @@
-3.3.0
+3.4.1

backend/app/api/routes/auth.py

@@ -10,7 +10,7 @@ from pydantic import BaseModel
 from starlette.responses import RedirectResponse
 
 from app.api.deps import AuthContext, get_auth_context
-from app.core.config import settings
+from app.core.config import app_base_path_of, settings
 from app.core.security import (
     clear_oidc_session_cookie,
     create_access_token,
@@ -103,7 +103,10 @@ async def oidc_callback(request: Request) -> Response:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="OIDC authentication failed") from None
 
     request.session.clear()
-    response = RedirectResponse(url="/", status_code=status.HTTP_303_SEE_OTHER)
+    # 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
 

backend/app/api/routes/designs.py

@@ -8,6 +8,7 @@ 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()
 
@@ -233,6 +234,8 @@ async def delete_design(
     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)

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

@@ -8,6 +8,7 @@ from app.api.deps import get_current_user
 from app.db.database import get_db
 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,
@@ -150,6 +151,11 @@ async def update_node(
     if not node:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Node not found")
     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.
@@ -173,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

@@ -33,7 +33,9 @@ from app.schemas.proxmox import (
     ProxmoxTestConnectionResponse,
 )
 from app.schemas.scan import ScanRunResponse
+from app.services.device_merge import reconcile_duplicates
 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 (
@@ -51,6 +53,9 @@ router = APIRouter()
 # '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]:
@@ -88,6 +93,7 @@ async def test_connection_endpoint(
 @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."""
@@ -108,6 +114,12 @@ async def import_proxmox(
         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))
@@ -247,10 +259,12 @@ async def _persist_pending_import(
 ) -> ProxmoxImportPendingResponse:
     """Upsert Proxmox nodes/edges into device_inventory + device_inventory_links.
 
-    Two-tier identity (order matters):
-      1. Match an existing canvas Node or pending row by **IP** (merge into a
-         device previously found by a scan) — never duplicate.
-      2. Else match by synthetic ``ieee_address`` (``pve-...``).
+    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.
     """
@@ -308,6 +322,12 @@ async def _persist_pending_import(
                     en.left_handles = max(en.left_handles or 0, 1)
                     en.right_handles = max(en.right_handles or 0, 1)
 
+    # Fold in any row this import just proved to be the same device: a guest
+    # matched here by its synthetic ieee can share a MAC or an IP with a row an
+    # earlier scan (or an older canvas node) minted before either side carried
+    # the address that would have matched them.
+    await reconcile_duplicates(db)
+
     links_recorded = await _replace_links(db, edges_raw, cluster_pairs)
     await db.commit()
 
@@ -322,14 +342,70 @@ async def _persist_pending_import(
 async def _find_pending(
     db: AsyncSession, ieee: str, ip: str | None, mac: str | None
 ) -> InventoryDevice | None:
-    filters = [InventoryDevice.ieee_address == ieee]
-    if ip:
-        filters.append(InventoryDevice.ip == ip)
-    if mac:
-        filters.append(InventoryDevice.mac == mac)
-    return (
-        await db.execute(select(InventoryDevice).where(or_(*filters)))
+    """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(
@@ -372,7 +448,7 @@ def _sources_after_merge(row: InventoryDevice) -> list[str]:
     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-")
+    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)
@@ -388,7 +464,7 @@ def _refresh_pending(
 ) -> None:
     # Compute sources before adopting the pve ieee (needs the pre-merge origin).
     pending.discovery_sources = _sources_after_merge(pending)
-    pending.ieee_address = pending.ieee_address or ieee
+    pending.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
@@ -420,7 +496,7 @@ async def _ensure_inventory_row(
     else:
         # Compute sources before adopting the pve ieee (needs the pre-merge origin).
         inv.discovery_sources = _sources_after_merge(inv)
-        inv.ieee_address = inv.ieee_address or ieee
+        inv.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

backend/app/api/routes/racks.py

@@ -1,3 +1,4 @@
+from collections.abc import Sequence
 from datetime import datetime, timezone
 from typing import Any, TypeVar
 
@@ -9,6 +10,7 @@ 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,
@@ -124,6 +126,92 @@ def _ip_tokens(ip: str | None) -> list[str]:
     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)
 
 
@@ -165,9 +253,42 @@ async def load_racks(
     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=[RackDeviceResponse.model_validate(d) for d in devices],
+        devices=mounted,
         cables=[RackCableResponse.model_validate(c) for c in cables],
         viewport=state.viewport if state else {"x": 0, "y": 0, "zoom": 1},
     )
@@ -228,11 +349,33 @@ async def save_racks(
         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:
@@ -349,6 +492,11 @@ async def rack_inventory(
                 ),
                 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/scan.py

@@ -28,11 +28,20 @@ from app.schemas.scan import (
     InventoryDeviceUpdate,
     ScanRunResponse,
 )
+from app.services.device_merge import merge_devices
 from app.services.discovery_sources import add_source
+from app.services.doc_links import unlink_documents
 from app.services.inventory_sync import find_device_for, merge_properties, merge_services
 from app.services.mac_utils import normalize_mac
 from app.services.node_dedupe import dedupe_nodes_by_device, find_duplicate_node
-from app.services.scanner import DeepScanOptions, _valid_port_range, request_cancel, run_scan
+from app.services.scanner import (
+    DeepScanOptions,
+    _valid_port_range,
+    _valid_port_spec,
+    request_cancel,
+    run_device_scan,
+    run_scan,
+)
 from app.services.zigbee_service import (
     build_zigbee_properties,
     merge_zigbee_properties,
@@ -109,6 +118,13 @@ def merge_mac_property(
     return out
 
 
+class MergeDevicesRequest(BaseModel):
+    """Which inventory rows fold into which. ``winner_id`` is the survivor."""
+
+    winner_id: str
+    loser_ids: list[str]
+
+
 class BulkActionRequest(BaseModel):
     device_ids: list[str]
     # Target design for approved nodes. Falls back to the first design when
@@ -176,7 +192,39 @@ async def _background_scan(
             await db.rollback()
             run = await db.get(ScanRun, run_id)
             if run and run.status == "running":
-                run.status = "failed"
+                # "error", the same word run_scan / run_device_scan write when
+                # they fail themselves — one condition, one name. Scan History
+                # filters and colours that one; "failed" showed up unlabelled.
+                run.status = "error"
+                await db.commit()
+
+
+async def _background_device_scan(
+    run_id: str,
+    device_id: str,
+    deep_scan: DeepScanOptions | None = None,
+    full_ports: bool = True,
+    ports: str | None = None,
+) -> None:
+    async with AsyncSessionLocal() as db:
+        try:
+            await run_device_scan(
+                device_id,
+                db,
+                run_id,
+                deep_scan=deep_scan or DeepScanOptions(),
+                full_ports=full_ports,
+                ports=ports,
+            )
+        except Exception:
+            logger.exception("Device scan run %s failed unexpectedly", run_id)
+            await db.rollback()
+            run = await db.get(ScanRun, run_id)
+            if run and run.status == "running":
+                # "error", the same word run_scan / run_device_scan write when
+                # they fail themselves — one condition, one name. Scan History
+                # filters and colours that one; "failed" showed up unlabelled.
+                run.status = "error"
                 await db.commit()
 
 
@@ -215,6 +263,78 @@ async def trigger_scan(
     return run
 
 
+class RescanDeviceRequest(BaseModel):
+    """Per-device deep rescan. Defaults to every TCP port — that is the point.
+
+    ``ports`` narrows the sweep to what the user typed in the deep-scan dialog
+    (``80,443``, ``1-1024``); it wins over ``full_ports``.
+    """
+
+    full_ports: bool = True
+    ports: str | None = None
+    http_probe_enabled: bool | None = None
+    verify_tls: bool | None = None
+
+    @field_validator("ports")
+    @classmethod
+    def _check_ports(cls, v: str | None) -> str | None:
+        if v is None or not v.strip():
+            return None
+        spec = v.strip()
+        if not _valid_port_spec(spec):
+            raise ValueError("Invalid port range")
+        return spec
+
+
+@router.post("/pending/{device_id}/rescan", response_model=ScanRunResponse)
+async def rescan_device(
+    device_id: str,
+    background_tasks: BackgroundTasks,
+    payload: RescanDeviceRequest | None = None,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> ScanRun:
+    """Deep-rescan one known device to refresh its services (issue #350).
+
+    Recorded as a ScanRun like any other scan, so progress, stop and history
+    work unchanged. One run per device at a time — a second request while the
+    first is still scanning is a 409, not a duplicate nmap over 65535 ports.
+    """
+    device = await db.get(InventoryDevice, device_id)
+    if not device:
+        raise HTTPException(status_code=404, detail="Device not found")
+    if not device.ip:
+        raise HTTPException(
+            status_code=409, detail="Device has no IP address to scan"
+        )
+    if device.status == "hidden":
+        raise HTTPException(status_code=409, detail="Device is hidden")
+
+    target = f"{device.ip}/32"
+    running = (await db.execute(
+        select(ScanRun).where(ScanRun.status == "running", ScanRun.kind == "device")
+    )).scalars().all()
+    if any(target in (r.ranges or []) for r in running):
+        raise HTTPException(
+            status_code=409, detail="A scan is already running for this device"
+        )
+
+    p = payload or RescanDeviceRequest()
+    deep_scan = _resolve_deep_scan(
+        TriggerScanRequest(
+            http_probe_enabled=p.http_probe_enabled, verify_tls=p.verify_tls
+        )
+    )
+    run = ScanRun(status="running", kind="device", ranges=[target])
+    db.add(run)
+    await db.commit()
+    await db.refresh(run)
+    background_tasks.add_task(
+        _background_device_scan, run.id, device_id, deep_scan, p.full_ports, p.ports
+    )
+    return run
+
+
 @router.post("/{run_id}/stop", response_model=dict)
 async def stop_scan(
     run_id: str,
@@ -421,6 +541,10 @@ async def clear_pending(
     _: str = Depends(get_current_user),
 ) -> dict[str, int]:
     from sqlalchemy import delete as sa_delete
+    pending_ids = (
+        await db.execute(select(InventoryDevice.id).where(InventoryDevice.status == "pending"))
+    ).scalars().all()
+    await unlink_documents(db, device_ids=list(pending_ids))
     result = await db.execute(sa_delete(InventoryDevice).where(InventoryDevice.status == "pending"))
     await db.commit()
     return {"deleted": result.rowcount}
@@ -452,6 +576,7 @@ async def delete_pending(
     if mounted:
         raise HTTPException(status_code=409, detail="Device is mounted in a rack")
 
+    await unlink_documents(db, device_ids=[device.id])
     await db.delete(device)
     await db.commit()
     return {"deleted": True}
@@ -463,6 +588,86 @@ async def list_hidden(db: AsyncSession = Depends(get_db), _: str = Depends(get_c
     return await _with_canvas_counts(db, list(result.scalars().all()))
 
 
+@router.get("/pending/{device_id}/proxmox-children", response_model=list[InventoryDeviceResponse])
+async def list_proxmox_children(
+    device_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> list[InventoryDevice]:
+    """Inventory rows for the guests a Proxmox host runs.
+
+    The Proxmox import records host -> guest as a ``device_inventory_links`` row
+    with ``discovery_source == "proxmox"``, keyed by IEEE. This resolves those
+    targets back to inventory rows so the UI can offer "add the children too"
+    when a host is placed on a canvas. Empty for anything that is not a host.
+    """
+    device = await db.get(InventoryDevice, device_id)
+    if device is None:
+        raise HTTPException(status_code=404, detail="Device not found")
+    if not device.ieee_address:
+        return []
+    ieees = list(
+        (
+            await db.execute(
+                select(InventoryDeviceLink.target_ieee).where(
+                    InventoryDeviceLink.source_ieee == device.ieee_address,
+                    InventoryDeviceLink.discovery_source == "proxmox",
+                )
+            )
+        )
+        .scalars()
+        .all()
+    )
+    if not ieees:
+        return []
+    result = await db.execute(
+        select(InventoryDevice).where(
+            InventoryDevice.ieee_address.in_(ieees),
+            InventoryDevice.status != "hidden",
+        )
+    )
+    return await _with_canvas_counts(db, list(result.scalars().all()))
+
+
+@router.post("/pending/merge", response_model=InventoryDeviceResponse)
+async def merge_inventory_devices(
+    payload: MergeDevicesRequest,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> InventoryDevice:
+    """Fold several inventory rows into one, keeping ``winner_id``.
+
+    The manual half of the duplicate repair. Identity matching only runs when a
+    row is created, so two rows describing one host — minted before either
+    carried the address that would have matched them — stay separate forever.
+    Where they share no address at all, no automatic rule can join them safely
+    (a name is not an identity), and this is the only way to say "these are the
+    same machine".
+
+    Non-destructive: facts are unioned onto the survivor and every canvas node,
+    rack mount and document is re-pointed at it before the extras go.
+    """
+    winner = await db.get(InventoryDevice, payload.winner_id)
+    if winner is None:
+        raise HTTPException(status_code=404, detail="Device not found")
+
+    loser_ids = [i for i in dict.fromkeys(payload.loser_ids) if i != winner.id]
+    if not loser_ids:
+        raise HTTPException(status_code=400, detail="Select at least two devices to merge")
+
+    losers = (
+        await db.execute(select(InventoryDevice).where(InventoryDevice.id.in_(loser_ids)))
+    ).scalars().all()
+    missing = set(loser_ids) - {row.id for row in losers}
+    if missing:
+        raise HTTPException(status_code=404, detail="Device not found")
+
+    await merge_devices(db, winner, list(losers))
+    await db.commit()
+    await db.refresh(winner)
+    return (await _with_canvas_counts(db, [winner]))[0]
+
+
 @router.post("/pending/bulk-approve", response_model=dict)
 async def bulk_approve_devices(
     payload: BulkActionRequest,
@@ -922,6 +1127,7 @@ async def ignore_device(
     device = await db.get(InventoryDevice, device_id)
     if not device:
         raise HTTPException(status_code=404, detail="Device not found")
+    await unlink_documents(db, device_ids=[device.id])
     await db.delete(device)
     await db.commit()
     return {"ignored": True}
@@ -933,6 +1139,19 @@ async def list_runs(db: AsyncSession = Depends(get_db), _: str = Depends(get_cur
     return list(result.scalars().all())
 
 
+@router.get("/runs/{run_id}", response_model=ScanRunResponse)
+async def get_run(
+    run_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> ScanRun:
+    """One run, for a caller waiting on a scan it started (the device rescan)."""
+    run = await db.get(ScanRun, run_id)
+    if not run:
+        raise HTTPException(status_code=404, detail="Scan run not found")
+    return run
+
+
 @router.get("/config", response_model=ScanConfig)
 async def get_scan_config(_: str = Depends(get_current_user)) -> ScanConfig:
     return ScanConfig(

backend/app/api/routes/zigbee.py

@@ -19,6 +19,8 @@ from app.schemas.zigbee import (
     ZigbeeConfig,
     ZigbeeCoordinatorOut,
     ZigbeeEdgeOut,
+    ZigbeeImportJob,
+    ZigbeeImportJobResult,
     ZigbeeImportPendingResponse,
     ZigbeeImportRequest,
     ZigbeeImportResponse,
@@ -27,6 +29,8 @@ from app.schemas.zigbee import (
     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,
@@ -48,18 +52,70 @@ async def _is_drawn(db: AsyncSession, device_id: str) -> bool:
 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,
@@ -70,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)

backend/app/api/routes/zwave.py

@@ -27,6 +27,7 @@ from app.schemas.zwave import (
     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,
@@ -51,6 +52,7 @@ 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.
@@ -82,6 +84,12 @@ async def import_zwave_network(
         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))

backend/app/core/config.py

@@ -2,12 +2,61 @@ import json
 import logging
 from pathlib import Path
 from typing import Literal
+from urllib.parse import urlsplit
 
 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)
@@ -52,6 +101,12 @@ class Settings(BaseSettings):
 
     @model_validator(mode="after")
     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(
@@ -88,6 +143,16 @@ class Settings(BaseSettings):
                         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
@@ -98,6 +163,14 @@ class Settings(BaseSettings):
     # 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] = []
@@ -152,6 +225,10 @@ class Settings(BaseSettings):
     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 = ""
@@ -165,6 +242,10 @@ class Settings(BaseSettings):
     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"
 

backend/app/core/security.py

@@ -14,7 +14,7 @@ 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"
@@ -153,6 +153,13 @@ 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
 
 

backend/app/db/database.py

@@ -1,12 +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
 
@@ -15,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.
 
@@ -360,6 +415,18 @@ async def init_db() -> None:
                 "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):
@@ -467,6 +534,34 @@ async def init_db() -> None:
                 "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 (
@@ -485,8 +580,19 @@ async def init_db() -> None:
         ):
             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()
 
 
 
@@ -507,12 +613,14 @@ _NODE_COLUMNS_SQL = (
     "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,"
@@ -525,19 +633,70 @@ _NODE_COLUMNS_SQL = (
 )
 
 _NODE_KEPT = (
-    "id, type, label, design_id, device_id, pos_x, pos_y, parent_id, container_mode, "
-    "custom_colors, custom_icon, show_port_numbers, width, height, bottom_handles, "
+    "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.
+    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()
@@ -557,23 +716,16 @@ async def _drop_legacy_node_columns() -> None:
                 "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")
-        try:
-            await conn.exec_driver_sql("PRAGMA foreign_keys = OFF")
-            await conn.exec_driver_sql(f"CREATE TABLE nodes_new ({_NODE_COLUMNS_SQL})")
-            await conn.exec_driver_sql(
-                f"INSERT INTO nodes_new ({_NODE_KEPT}) SELECT {_NODE_KEPT} 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)"
-            )
-            await conn.exec_driver_sql("PRAGMA foreign_keys = ON")
-        except OperationalError as exc:
-            logger.warning("nodes device-column drop failed: %s", exc)
+        await _rebuild_nodes(
+            conn,
+            columns_sql=_NODE_COLUMNS_SQL,
+            copied=_NODE_KEPT,
+            what="nodes device-column drop",
+        )
 
 
 async def _backfill_node_devices() -> None:
@@ -596,10 +748,252 @@ async def _backfill_node_devices() -> None:
                     "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]:
     async with AsyncSessionLocal() as session:
         yield session

backend/app/db/models.py

@@ -49,12 +49,26 @@ class Node(Base):
     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)
+    # 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)
@@ -163,6 +177,9 @@ class RackDevice(Base):
     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)
@@ -258,6 +275,19 @@ class InventoryDevice(Base):
         DateTime(timezone=True), default=_now, onupdate=_now
     )
 
+    # --- 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
@@ -299,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

@@ -12,6 +12,7 @@ from app.api.routes import (
     auth,
     canvas,
     designs,
+    documents,
     edges,
     liveview,
     media,
@@ -28,7 +29,8 @@ from app.api.routes import settings as settings_routes
 from app.core.config import settings
 from app.core.scheduler import start_scheduler, stop_scheduler
 from app.core.security import OIDCCSRFMiddleware
-from app.db.database import init_db
+from app.db.database import AsyncSessionLocal, init_db
+from app.services.scanner import reconcile_orphan_runs
 
 
 @asynccontextmanager
@@ -45,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()
@@ -88,6 +94,7 @@ 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,6 +1,6 @@
 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
@@ -31,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
@@ -51,6 +54,22 @@ class NodeSave(BaseModel):
     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

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/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
@@ -61,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

backend/app/schemas/proxmox.py

@@ -41,6 +41,10 @@ class ProxmoxNodeOut(BaseModel):
     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):

backend/app/schemas/racks.py

@@ -7,6 +7,8 @@ from pydantic import BaseModel, field_validator, model_validator
 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
 
@@ -57,8 +59,15 @@ class RackDeviceSave(BaseModel):
     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:
@@ -161,6 +170,33 @@ class RackSaveRequest(BaseModel):
                 )
         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
@@ -196,8 +232,15 @@ class RackDeviceResponse(BaseModel):
     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]:
@@ -282,6 +325,22 @@ class RackInventoryItem(BaseModel):
     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

backend/app/schemas/scan.py

@@ -3,6 +3,11 @@ from typing import Any
 
 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 InventoryDeviceResponse(BaseModel):
     id: str
@@ -57,6 +62,20 @@ class InventoryDeviceResponse(BaseModel):
     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
@@ -159,6 +178,36 @@ class InventoryDeviceUpdate(BaseModel):
     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):

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

backend/app/schemas/zwave.py

@@ -50,6 +50,10 @@ class ZwaveNodeOut(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 ZwaveEdgeOut(BaseModel):

backend/app/services/device_merge.py

@@ -0,0 +1,447 @@
+"""Fold several `device_inventory` rows describing one host into a single row.
+
+The inventory matches on identity *when a row is created* (``find_device_for``:
+ieee > ip > mac) and never looks again. A row minted while its facts were still
+incomplete — a canvas node saved before anyone typed its IP, a legacy node the
+3.3.0 backfill could only see by label — therefore stays a second row forever,
+even once the missing address arrives and both rows plainly describe the same
+machine. This module is the repair for that, in two shapes:
+
+* :func:`merge_devices` — the user picks the survivor and what folds into it.
+  The only way to collapse rows that share nothing an automatic rule can trust:
+  a name is not an identity.
+* :func:`reconcile_duplicates` — run after an import, collapses only what a
+  shared MAC proves. Never a shared IP alone: that is not an identity.
+
+Merging is non-destructive by construction: facts are unioned, and every
+reference (`nodes`, `rack_devices`, `documents`, mesh links) is re-pointed onto
+the survivor *before* the extras go. That is what separates it from the
+scanner's older collapse, which deleted duplicate rows outright and left canvas
+nodes naming a row that no longer existed — SQLite runs with foreign keys off
+here, so the declared ``ON DELETE SET NULL`` never fires.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import or_, select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import Document, InventoryDevice, InventoryDeviceLink, Node, RackDevice
+from app.services.discovery_sources import add_source
+from app.services.inventory_sync import (
+    VIEW_LISTS,
+    ip_tokens,
+    merge_properties,
+    merge_services,
+    view_of_device,
+)
+from app.services.node_dedupe import dedupe_nodes_by_device
+
+logger = logging.getLogger(__name__)
+
+# Scalars the survivor fills from a loser when — and only when — it has none of
+# its own. `ip`, `mac`, the lists and the timestamps are merged by rule below.
+_FILL_SCALARS = (
+    "hostname",
+    "os",
+    "suggested_type",
+    "discovery_source",
+    "friendly_name",
+    "device_subtype",
+    "model",
+    "vendor",
+    "lqi",
+    "label",
+    "type",
+    "notes",
+    "cpu_count",
+    "cpu_model",
+    "ram_gb",
+    "disk_gb",
+    "check_method",
+    "check_target",
+    "response_time_ms",
+    "rack_faceplate_id",
+    "rack_u_height",
+    "rack_col_span",
+    "rack_color",
+    "rack_ports",
+)
+
+
+def _blank(value: Any) -> bool:
+    return value is None or value == ""
+
+
+def _newest(left: datetime | None, right: datetime | None) -> datetime | None:
+    if left is None or right is None:
+        return left or right
+    return max(left, right)
+
+
+def _merged_ip(winner: str | None, loser: str | None) -> str | None:
+    """Union of both address lists, the survivor's own addresses first.
+
+    A device legitimately holds several addresses (a management VLAN, a second
+    NIC), and dropping the loser's would undo the very match that identified it
+    — the next import would mint the duplicate again.
+    """
+    tokens = ip_tokens(winner)
+    for token in ip_tokens(loser):
+        if token not in tokens:
+            tokens.append(token)
+    return ", ".join(tokens) or None
+
+
+def _merged_status(winner: str, losers: list[InventoryDevice]) -> str:
+    """The lifecycle state the survivor carries.
+
+    ``approved`` wins over everything: a canvas node or a rack mount is about to
+    point at this row, and a row that is pending or hidden would file a drawn
+    device back in the discovery queue or make it vanish from the inventory.
+    """
+    if winner == "approved" or any(loser.status == "approved" for loser in losers):
+        return "approved"
+    return winner
+
+
+async def _merge_documents(db: AsyncSession, winner: InventoryDevice, loser_ids: list[str]) -> int:
+    """Re-point the losers' documents, or orphan them. Returns how many orphaned.
+
+    ``documents.device_id`` is unique per device (a partial index built in
+    ``init_db``), so only one document can describe the survivor. The oldest of
+    the losers' is adopted when the survivor has none; the rest are unlinked
+    rather than deleted — what the user wrote outlives the row it described, and
+    an orphan keeps its denormalized title and can be re-linked from the Library.
+    """
+    docs = (
+        await db.execute(
+            select(Document)
+            .where(Document.device_id.in_(loser_ids))
+            .order_by(Document.created_at, Document.id)
+        )
+    ).scalars().all()
+    if not docs:
+        return 0
+
+    has_own = (
+        await db.execute(select(Document.id).where(Document.device_id == winner.id).limit(1))
+    ).scalar_one_or_none()
+    orphaned = 0
+    for i, doc in enumerate(docs):
+        if i == 0 and has_own is None:
+            doc.device_id = winner.id
+            continue
+        doc.device_id = None
+        orphaned += 1
+    return orphaned
+
+
+async def _show_merged_facts(db: AsyncSession, winner: InventoryDevice) -> int:
+    """Make the survivor's facts visible on every canvas that draws it.
+
+    A node's ``display_view`` is a whitelist: ``apply_view`` appends anything the
+    view does not list *hidden*, which is what keeps a service a later scan found
+    off canvases nobody has enabled it on. After a merge that rule works against
+    the user — a node that came from the poorer row lists only the poorer row's
+    keys, so every service and property it just gained would arrive invisible,
+    and the canvas would look exactly as bare as before the merge.
+
+    So each node drawing the survivor has the keys missing from its view appended
+    as shown. Only *missing* keys: a fact this canvas listed as hidden was hidden
+    on purpose and stays that way. Returns the number of nodes touched.
+    """
+    nodes = (
+        await db.execute(select(Node).where(Node.device_id == winner.id))
+    ).scalars().all()
+    seeds = view_of_device(winner)
+    touched = 0
+    for node in nodes:
+        view = dict(node.display_view or {})
+        changed = False
+        for kind in VIEW_LISTS:
+            entries = view.get(kind)
+            if not isinstance(entries, list):
+                # No view at all for this list — `apply_view` already shows
+                # everything the row holds, merged facts included.
+                continue
+            listed = {str(e.get("key")) for e in entries if isinstance(e, dict)}
+            missing = [entry for entry in seeds[kind] if entry["key"] not in listed]
+            if missing:
+                view[kind] = [*entries, *missing]
+                changed = True
+        if changed:
+            # Reassign rather than mutate: a JSON column tracks identity, not
+            # in-place edits, so a mutated dict would never be written back.
+            node.display_view = view
+            touched += 1
+    return touched
+
+
+async def _refresh_rack_mounts(db: AsyncSession, winner: InventoryDevice, losers: list[InventoryDevice]) -> None:
+    """Point the losers' rack mounts at the survivor and refresh what they copied.
+
+    A mount denormalizes the device's ``label`` so a rack still renders after an
+    inventory purge. Re-pointing alone would leave it printing the name of a row
+    that no longer exists, so a copy that still matches the loser is refreshed to
+    the survivor's name — a label the user typed on the mount itself does not
+    match and is left alone. The faceplate, its size and its ports are overlaid
+    from the inventory row on load, and the merge already filled any the survivor
+    lacked, so the plate keeps rendering as it did.
+    """
+    loser_ids = [row.id for row in losers]
+    mounts = (
+        await db.execute(select(RackDevice).where(RackDevice.device_id.in_(loser_ids)))
+    ).scalars().all()
+    stale = {
+        name
+        for row in losers
+        for name in (row.label, row.friendly_name, row.hostname)
+        if name
+    }
+    winner_name = winner.label or winner.friendly_name or winner.hostname
+    for mount in mounts:
+        mount.device_id = winner.id
+        if winner_name and mount.label in stale:
+            mount.label = winner_name
+
+
+async def _rewrite_links(db: AsyncSession, winner_ieee: str, loser_ieees: list[str]) -> None:
+    """Move mesh/Proxmox links off the losers' IEEEs onto the survivor's.
+
+    ``device_inventory_links`` addresses endpoints by IEEE, not by row id, so a
+    link left on a merged-away address stops resolving to anything. Rewriting
+    can produce a self-link (both endpoints were the same device) or a duplicate
+    pair; both are dropped.
+    """
+    if not loser_ieees:
+        return
+    links = (
+        await db.execute(
+            select(InventoryDeviceLink).where(
+                or_(
+                    InventoryDeviceLink.source_ieee.in_(loser_ieees),
+                    InventoryDeviceLink.target_ieee.in_(loser_ieees),
+                )
+            )
+        )
+    ).scalars().all()
+    for link in links:
+        if link.source_ieee in loser_ieees:
+            link.source_ieee = winner_ieee
+        if link.target_ieee in loser_ieees:
+            link.target_ieee = winner_ieee
+    await db.flush()
+
+    seen: set[tuple[str, str, str]] = set()
+    all_links = (
+        await db.execute(
+            select(InventoryDeviceLink)
+            .where(
+                or_(
+                    InventoryDeviceLink.source_ieee == winner_ieee,
+                    InventoryDeviceLink.target_ieee == winner_ieee,
+                )
+            )
+            .order_by(InventoryDeviceLink.discovered_at, InventoryDeviceLink.id)
+        )
+    ).scalars().all()
+    for link in all_links:
+        key = (link.source_ieee, link.target_ieee, link.discovery_source)
+        if link.source_ieee == link.target_ieee or key in seen:
+            await db.delete(link)
+            continue
+        seen.add(key)
+
+
+async def merge_devices(
+    db: AsyncSession,
+    winner: InventoryDevice,
+    losers: list[InventoryDevice],
+) -> dict[str, Any]:
+    """Fold ``losers`` into ``winner``. Does not commit — the caller owns that.
+
+    The survivor keeps every fact it already has; a loser only fills a gap. That
+    rule is the whole safety of the operation: whichever row the user (or the
+    reconcile pass) picked, nothing it recorded is overwritten by an older or
+    less-curated copy, and nothing the extras recorded is lost — lists are
+    unioned, addresses are unioned, sources accumulate.
+
+    Returns counts for the caller to report.
+    """
+    losers = [row for row in losers if row.id != winner.id]
+    if not losers:
+        return {
+            "merged": 0,
+            "device_id": winner.id,
+            "nodes_repointed": 0,
+            "documents_orphaned": 0,
+            "views_extended": 0,
+        }
+
+    loser_ids = [row.id for row in losers]
+    # Oldest first: where two losers both fill the same gap, the older sighting
+    # is the one that has survived longest without being contradicted.
+    for loser in sorted(losers, key=lambda d: (d.discovered_at, d.id)):
+        for field in _FILL_SCALARS:
+            if _blank(getattr(winner, field, None)):
+                value = getattr(loser, field, None)
+                if not _blank(value):
+                    setattr(winner, field, value)
+        winner.ip = _merged_ip(winner.ip, loser.ip)
+        winner.mac = winner.mac or loser.mac
+        winner.services = merge_services(winner.services, loser.services)
+        winner.properties = merge_properties(winner.properties, loser.properties)
+        winner.show_hardware = winner.show_hardware or loser.show_hardware
+        for source in add_source(loser.discovery_sources, loser.discovery_source):
+            winner.discovery_sources = add_source(winner.discovery_sources, source)
+        if winner.status_live in (None, "", "unknown"):
+            winner.status_live = loser.status_live
+        winner.last_seen = _newest(winner.last_seen, loser.last_seen)
+        winner.last_scan = _newest(winner.last_scan, loser.last_scan)
+        # The device has been known since the earliest of the rows saw it.
+        if loser.discovered_at and winner.discovered_at:
+            winner.discovered_at = min(winner.discovered_at, loser.discovered_at)
+
+    winner.status = _merged_status(winner.status, losers)
+
+    nodes = await db.execute(
+        update(Node).where(Node.device_id.in_(loser_ids)).values(device_id=winner.id)
+    )
+    await _refresh_rack_mounts(db, winner, losers)
+    orphaned = await _merge_documents(db, winner, loser_ids)
+    await db.flush()
+    shown = await _show_merged_facts(db, winner)
+
+    loser_ieees = [row.ieee_address for row in losers if row.ieee_address]
+    adopted: str | None = None
+    if _blank(winner.ieee_address) and loser_ieees:
+        # `ieee_address` is UNIQUE, so the address can only move once the row
+        # holding it is gone — assigned after the delete below.
+        adopted = loser_ieees[0]
+
+    for loser in losers:
+        await db.delete(loser)
+    await db.flush()
+
+    if adopted is not None:
+        winner.ieee_address = adopted
+        await db.flush()
+    if winner.ieee_address:
+        await _rewrite_links(db, winner.ieee_address, loser_ieees)
+
+    # Two nodes on one canvas may now draw the survivor — that is exactly the
+    # same-design duplicate the node repair collapses.
+    await dedupe_nodes_by_device(db)
+    await db.flush()
+
+    logger.info(
+        "Inventory merge: %d row(s) folded into %s (%s)",
+        len(losers), winner.id, winner.label or winner.friendly_name or winner.ip,
+    )
+    return {
+        "merged": len(losers),
+        "device_id": winner.id,
+        "nodes_repointed": nodes.rowcount or 0,
+        "documents_orphaned": orphaned,
+        "views_extended": shown,
+    }
+
+
+def _conflicting(left: InventoryDevice, right: InventoryDevice) -> bool:
+    """True when two rows carry addresses that say they are different machines.
+
+    A distinct non-blank IEEE on each is decisive: two Proxmox guests (the
+    synthetic ``pve-{host}-{vmid}``) or two radios are never one device. A
+    distinct MAC says the same for hardware. Either one vetoes an automatic
+    merge — the user can still merge them by hand.
+    """
+    if left.ieee_address and right.ieee_address and left.ieee_address.lower() != right.ieee_address.lower():
+        return True
+    return bool(left.mac and right.mac and left.mac != right.mac)
+
+
+def _pick_winner(group: list[InventoryDevice]) -> InventoryDevice:
+    """The row the others fold into.
+
+    An IEEE first: mesh links and the Proxmox host→guest graph are keyed on it,
+    and the import matches on it before anything else, so the row holding one is
+    the row every other writer will come back to. Then an approved row (it is
+    the one already drawn), then the oldest.
+    """
+    return sorted(
+        group,
+        key=lambda d: (
+            0 if d.ieee_address else 1,
+            0 if d.status == "approved" else 1,
+            d.discovered_at,
+            d.id,
+        ),
+    )[0]
+
+
+def _auto_groups(rows: list[InventoryDevice]) -> list[list[InventoryDevice]]:
+    """Group rows a shared MAC proves to be one device.
+
+    The MAC and nothing else. A shared IP is not enough on its own — a re-used
+    DHCP lease, two guests behind one NAT, or a container bridge address several
+    guests report all make one address describe several machines — and the
+    scanner already collapses what an IP does justify, under its own guard for
+    rows that are drawn on a canvas. Labels and hostnames are ignored outright:
+    two boxes are often called the same thing, and an automatic pass is not the
+    place to decide they are one. Whatever is left over is what the manual merge
+    is for.
+
+    A group is dropped whole when any pair inside it contradicts (see
+    :func:`_conflicting`) rather than guessing which member does not belong.
+    """
+    by_mac: dict[str, list[InventoryDevice]] = {}
+    for row in rows:
+        if row.mac:
+            by_mac.setdefault(row.mac.lower(), []).append(row)
+
+    out = []
+    for group in by_mac.values():
+        if len(group) < 2:
+            continue
+        pairs = [(a, b) for i, a in enumerate(group) for b in group[i + 1:]]
+        if any(_conflicting(a, b) for a, b in pairs):
+            logger.info(
+                "Inventory reconcile: leaving %d row(s) sharing a MAC alone — "
+                "their IEEE says they are different devices (%s)",
+                len(group), ", ".join(row.id for row in group),
+            )
+            continue
+        out.append(group)
+    return out
+
+
+async def reconcile_duplicates(db: AsyncSession) -> int:
+    """Merge inventory rows a shared MAC proves to be one device. Does not commit.
+
+    Meant to run at the end of an import, where a row that was created blind may
+    have just gained the address that identifies it. Returns the number of rows
+    merged away.
+
+    Hidden rows are excluded on both sides: the user hid one deliberately, and
+    folding it into a visible row would put it back in front of them, while
+    folding a visible row into it would make a device they are using disappear.
+    """
+    rows = (
+        await db.execute(
+            select(InventoryDevice)
+            .where(InventoryDevice.status != "hidden")
+            .order_by(InventoryDevice.discovered_at, InventoryDevice.id)
+        )
+    ).scalars().all()
+
+    merged = 0
+    for group in _auto_groups(list(rows)):
+        winner = _pick_winner(group)
+        result = await merge_devices(db, winner, [row for row in group if row is not winner])
+        merged += int(result["merged"])
+    return merged

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

@@ -16,12 +16,42 @@ 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> — avoids large downloads.
+# 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).
-_NON_HTTP_PORTS = frozenset({22, 21, 23, 25, 53, 110, 143, 161, 162, 179, 445, 3306, 5432, 6379})
+#
+# 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:
@@ -34,11 +64,11 @@ def _extract_title(body: str) -> str | None:
 
 async def _probe_scheme(client: httpx.AsyncClient, url: str) -> dict[str, Any] | None:
     try:
-        resp = await client.get(url, follow_redirects=True)
+        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
-    headers = {h: resp.headers[h] for h in _SIGNAL_HEADERS if h in resp.headers}
-    body = resp.text[:_MAX_BODY_BYTES] if resp.text else ""
     title = _extract_title(body)
     if not title and not headers:
         return None

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

@@ -15,10 +15,11 @@ from __future__ import annotations
 
 import json
 import logging
-from collections.abc import Mapping
+from collections.abc import Callable, Mapping
+from datetime import datetime
 from typing import Any
 
-from sqlalchemy import or_, select, text
+from sqlalchemy import func, or_, select, text
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.db.models import InventoryDevice, Node
@@ -53,11 +54,13 @@ def is_furniture(node_type: str | None) -> bool:
     return (node_type or "") in FURNITURE_TYPES
 
 
-def _ip_tokens(ip: str | None) -> list[str]:
+def ip_tokens(ip: str | None) -> list[str]:
     """Split an ``ip`` field into individual addresses.
 
-    A node or device may carry several comma-separated addresses, so identity
-    matching compares per token — same rule as ``node_dedupe._ip_tokens``.
+    A node or device may carry several comma-separated addresses — a router with
+    a management VLAN, a host behind a VIP — so identity matching compares per
+    token rather than on the whole string. Every matcher that resolves a device
+    from addresses shares this rule, the scanner included.
     """
     return [t.strip() for t in ip.split(",") if t.strip()] if ip else []
 
@@ -66,6 +69,50 @@ def _blank(value: Any) -> bool:
     return value is None or value == ""
 
 
+def _same_ieee(left: str | None, right: str | None) -> bool:
+    """IEEE addresses compare case-insensitively — the same radio either way."""
+    if _blank(left) or _blank(right):
+        return False
+    return str(left).lower() == str(right).lower()
+
+
+async def _ieee_owner(db: AsyncSession, ieee: str, *, other_than: str | None) -> InventoryDevice | None:
+    """The row already holding ``ieee``, if it is not ``other_than``.
+
+    ``device_inventory.ieee_address`` is UNIQUE, so writing an address a second
+    row owns raises. Callers ask first and leave the address where it is.
+    """
+    stmt = select(InventoryDevice).where(func.lower(InventoryDevice.ieee_address) == ieee.lower())
+    if other_than is not None:
+        # `id != NULL` is NULL in SQL and would match nothing — only narrow when
+        # there is a row to exclude.
+        stmt = stmt.where(InventoryDevice.id != other_than)
+    return (await db.execute(stmt)).scalars().first()
+
+
+async def _drop_taken_ieee(
+    db: AsyncSession, facts: Mapping[str, Any], device: InventoryDevice | None
+) -> Mapping[str, Any]:
+    """``facts`` without an ``ieee_address`` another inventory row already owns.
+
+    Returned unchanged in the common case. The column is UNIQUE, so writing a
+    duplicate raises mid-merge — and during the backfill that would cost the node
+    its link. The address belongs to whichever row holds it; identity for *this*
+    device was established by ip or mac.
+    """
+    ieee = facts.get("ieee_address")
+    if _blank(ieee) or (device is not None and _same_ieee(device.ieee_address, ieee)):
+        return facts
+    owner = await _ieee_owner(db, str(ieee), other_than=device.id if device else None)
+    if owner is None:
+        return facts
+    logger.warning(
+        "IEEE %s is already held by device %s — leaving it off %s",
+        ieee, owner.id, device.id if device else "the new row",
+    )
+    return {k: v for k, v in facts.items() if k != "ieee_address"}
+
+
 async def find_device_for(
     db: AsyncSession,
     *,
@@ -80,10 +127,13 @@ async def find_device_for(
     Hidden rows are eligible: a hidden device is still that device, and silently
     minting a second row for it would resurrect the duplicate the user hid.
     """
-    ip_toks = _ip_tokens(ip)
+    ip_toks = ip_tokens(ip)
     conds = []
     if ieee:
-        conds.append(InventoryDevice.ieee_address == ieee)
+        # Case-insensitive: `0x00124B00…` and `0x00124b00…` are the same radio,
+        # and an exact comparison here would mint a second row for it — one the
+        # UNIQUE index then refuses.
+        conds.append(func.lower(InventoryDevice.ieee_address) == ieee.lower())
     for tok in ip_toks:
         # Narrow with a substring match, then confirm per token below — an exact
         # comparison misses rows holding several addresses.
@@ -98,12 +148,12 @@ async def find_device_for(
     ).scalars().all()
 
     for device in candidates:
-        if ieee and device.ieee_address == ieee:
+        if ieee and _same_ieee(device.ieee_address, ieee):
             return device
     for device in candidates:
         # "1.2.3.4" must not match "1.2.3.40" — confirm the token, don't trust
         # the SQL `contains`.
-        if ip_toks and set(_ip_tokens(device.ip)) & set(ip_toks):
+        if ip_toks and set(ip_tokens(device.ip)) & set(ip_toks):
             return device
     for device in candidates:
         if mac and device.mac == mac:
@@ -155,8 +205,181 @@ def _service_key(svc: Any) -> Any:
     return (svc.get("port"), svc.get("protocol"), (svc.get("service_name") or "").lower())
 
 
-def merge_services(base: list[Any] | None, incoming: list[Any] | None) -> list[Any]:
-    """Union two service lists on (port, protocol, name); incoming wins."""
+# --- Per-node view of the device's list facts -----------------------------
+#
+# The row owns the services and the properties; a node owns which of them it
+# shows and in what order. Both are keyed by a stable string so the view
+# survives an edit to a service's path or a property's value.
+
+VIEW_LISTS = ("services", "properties")
+
+
+def _service_view_key(svc: Any) -> str:
+    port, protocol, name = _service_key(svc) if isinstance(svc, dict) else (None, None, repr(svc))
+    return f"{port}|{protocol}|{name}"
+
+
+def _property_view_key(prop: Any) -> str:
+    if not isinstance(prop, dict):
+        return repr(prop)
+    return str(prop.get("key") or "").lower()
+
+
+_VIEW_KEY = {"services": _service_view_key, "properties": _property_view_key}
+
+
+def view_entries(items: list[Any] | None, kind: str) -> list[dict[str, Any]]:
+    """One list of device facts as a node's view of it: order plus visibility.
+
+    A service carries no ``visible`` of its own — one that reached a canvas was
+    always drawn — so it defaults to shown. A property carries an explicit flag
+    and keeps it. Duplicate keys collapse: the view addresses the row, and the
+    row holds one entry per key.
+    """
+    key_of = _VIEW_KEY[kind]
+    out: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for item in items or []:
+        key = key_of(item)
+        if key in seen:
+            continue
+        seen.add(key)
+        visible = bool(item.get("visible", True)) if isinstance(item, dict) else True
+        out.append({"key": key, "visible": visible})
+    return out
+
+
+def view_from_facts(facts: Mapping[str, Any]) -> dict[str, list[dict[str, Any]]]:
+    """The view a node payload implies — only for the lists it actually sent.
+
+    The wire shape has no separate view: a client sends its services and its
+    properties in display order, each with its ``visible`` flag, exactly as it
+    draws them. That *is* the view, so it is read back out here rather than
+    asking clients for a second field.
+    """
+    return {kind: view_entries(facts[kind], kind) for kind in VIEW_LISTS if kind in facts}
+
+
+def view_of_device(device: InventoryDevice) -> dict[str, list[dict[str, Any]]]:
+    """A view showing everything the row currently holds — the seed for a new node."""
+    return {
+        "services": view_entries(device.services, "services"),
+        "properties": view_entries(device.properties, "properties"),
+    }
+
+
+def next_view(
+    current: Mapping[str, Any] | None,
+    incoming: Mapping[str, Any],
+    device: InventoryDevice | None,
+    *,
+    strict: bool = False,
+) -> dict[str, Any] | None:
+    """This node's view after a write: what it sent, then the row for the rest.
+
+    A list the write did not carry keeps the view it had. A node linked to a row
+    always ends up with both lists, so "not in the view" can mean one thing
+    only: this canvas does not show it. That is what keeps a service a later scan
+    discovers off every canvas until someone turns it on.
+
+    A node getting its *first* view is the exception: an empty list there means
+    the writer had nothing to say about it, not that the user hid everything —
+    creating a node for an already-scanned device sends no services and must
+    still draw the ones the row holds. ``strict`` turns that off for the one
+    caller whose empty list is a real answer: the legacy backfill, where the
+    node's own columns are the whole of what that canvas used to show.
+    """
+    if device is None:
+        return dict(current) if current else None
+    out: dict[str, Any] = dict(current or {})
+    first_view = current is None
+    seed = view_of_device(device)
+    for kind in VIEW_LISTS:
+        entries = incoming.get(kind)
+        if entries or (entries is not None and (strict or not first_view)):
+            out[kind] = entries
+        elif kind not in out:
+            out[kind] = seed[kind]
+    return out
+
+
+def apply_view(items: list[Any] | None, entries: Any, kind: str) -> list[Any]:
+    """The row's facts as one node draws them: its order, its visibility.
+
+    Without a view — furniture, or a node whose row was linked by an older
+    version — everything shows, in the row's own order. With one, an item the
+    view does not list is appended hidden rather than dropped, so a service a
+    scan added is one toggle away instead of invisible.
+
+    A *non-empty* view that matches nothing the row still holds is treated as
+    having no view at all. It means the row was replaced wholesale under the
+    node — every key gone, every key new — and hiding the lot would leave a node
+    drawing nothing while its view claims otherwise. An empty view is different:
+    it is a real answer ("this canvas draws none of them") and keeps hiding
+    everything.
+    """
+    key_of = _VIEW_KEY[kind]
+    facts = list(items or [])
+    if not isinstance(entries, list):
+        return facts
+
+    by_key: dict[str, Any] = {}
+    for item in facts:
+        by_key.setdefault(key_of(item), item)
+
+    out: list[Any] = []
+    taken: set[str] = set()
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        key = str(entry.get("key"))
+        item = by_key.get(key)
+        if item is None or key in taken:
+            continue  # Deleted from the row since — the view catches up on write.
+        taken.add(key)
+        out.append(_stamped(item, bool(entry.get("visible", True))))
+    if entries and not taken:
+        return facts
+    for item in facts:
+        if key_of(item) not in taken:
+            out.append(_stamped(item, False))
+    return out
+
+
+def _stamped(item: Any, visible: bool) -> Any:
+    """``item`` carrying this node's verdict on whether it is drawn.
+
+    A shown item that never had a ``visible`` key does not gain one: services
+    have always travelled without it, and readers treat its absence as shown.
+    Only hiding is news, and properties keep the explicit flag they arrived with.
+    """
+    if not isinstance(item, dict):
+        return item
+    if visible and "visible" not in item:
+        return dict(item)
+    return {**item, "visible": visible}
+
+
+# How a service looks is the user's call. A fingerprint only ever guesses it
+# from a port number and a banner, so a scan that re-finds a known service must
+# not repaint the icon someone picked by hand — that happened on every "Scan
+# network", across every canvas drawing the device, at once.
+_CURATED_SERVICE_FIELDS = ("icon", "category")
+
+
+def merge_services(
+    base: list[Any] | None,
+    incoming: list[Any] | None,
+    *,
+    discovered: bool = False,
+) -> list[Any]:
+    """Union two service lists on (port, protocol, name); incoming wins.
+
+    ``discovered`` marks ``incoming`` as scanner output rather than a user edit:
+    it still adds services and refreshes facts, but leaves an established icon
+    and category alone. Either way a blank incoming value never clears one that
+    is already set — an absent field is silence, not a reset.
+    """
     out: list[Any] = [dict(s) if isinstance(s, dict) else s for s in (base or [])]
     index = {_service_key(s): i for i, s in enumerate(out)}
     for svc in incoming or []:
@@ -166,7 +389,12 @@ def merge_services(base: list[Any] | None, incoming: list[Any] | None) -> list[A
             out.append(dict(svc) if isinstance(svc, dict) else svc)
             index[key] = len(out) - 1
         elif isinstance(svc, dict) and isinstance(out[pos], dict):
-            out[pos] = {**out[pos], **svc}
+            merged = {**out[pos], **svc}
+            for field_name in _CURATED_SERVICE_FIELDS:
+                established = out[pos].get(field_name)
+                if established and (discovered or not svc.get(field_name)):
+                    merged[field_name] = established
+            out[pos] = merged
         else:
             out[pos] = svc
     return out
@@ -330,6 +558,7 @@ async def link_facts(
     replace_lists: bool = False,
     only_changed: bool = False,
     changed_fields: list[str] | None = None,
+    strict_view: bool = False,
 ) -> InventoryDevice | None:
     """Point one node at its inventory row, creating or merging as needed.
 
@@ -352,6 +581,11 @@ async def link_facts(
         node.device_id = None
         return None
 
+    # A node that draws a device has no description of its own — what it is for
+    # is written on the inventory row, as `notes`. Clearing here keeps the two
+    # from becoming rival fields for the same text.
+    node.description = None
+
     device = None
     if node.device_id:
         device = await db.get(InventoryDevice, node.device_id)
@@ -360,6 +594,12 @@ async def link_facts(
             db, ip=facts.get("ip"), mac=facts.get("mac"), ieee=facts.get("ieee_address")
         )
 
+    # The IEEE is UNIQUE across the inventory. Where another row already owns the
+    # one these facts carry, drop it rather than write a duplicate: identity has
+    # been resolved to *this* device by ip or mac, and the address stays with the
+    # row holding it.
+    facts = await _drop_taken_ieee(db, facts, device)
+
     if device is None:
         device = device_from_facts(facts)
         db.add(device)
@@ -379,7 +619,20 @@ async def link_facts(
         )
         device.discovery_sources = add_source(device.discovery_sources, CANVAS_SOURCE)
 
+    # A row a node draws is past the pending queue — the mirror of the
+    # "approved but no longer drawn -> pending" revival the imports do. A hidden
+    # row stays hidden: the user hid it on purpose.
+    if device.status == "pending":
+        device.status = "approved"
+
     node.device_id = device.id
+    # Order and visibility are this node's, not the device's, so they are taken
+    # from the full payload — never from the `changed_fields`/`only_changed`
+    # narrowing above, which exists to protect the *shared* row from a stale
+    # snapshot. A node's own view has no other writer to collide with.
+    node.display_view = next_view(
+        node.display_view, view_from_facts(facts), device, strict=strict_view
+    )
     return device
 
 
@@ -390,10 +643,16 @@ def node_columns(payload: Mapping[str, Any]) -> dict[str, Any]:
     inventory row now, so they are dropped here and applied through
     :func:`link_facts` instead.
     """
-    allowed = {c.name for c in Node.__table__.columns}
+    allowed = {c.name for c in Node.__table__.columns} - _NODE_DERIVED_COLUMNS
     return {k: v for k, v in payload.items() if k in allowed}
 
 
+# Node columns the server derives rather than accepts: `display_view` is read
+# back out of the services and properties a payload carries (see
+# :func:`view_from_facts`), so a client sending one directly is ignored.
+_NODE_DERIVED_COLUMNS = frozenset({"display_view"})
+
+
 # Fields that are both a node column and a device fact: the node keeps a copy so
 # a half-migrated database still renders, but the row is the truth.
 _SHARED_FIELDS = ("label", "type")
@@ -448,6 +707,9 @@ def hydrated_node(node: Node, device: InventoryDevice | None) -> dict[str, Any]:
     payload: dict[str, Any] = {
         c.name: getattr(node, c.name) for c in node.__table__.columns
     }
+    # An implementation detail of the split, not part of the wire shape: the
+    # view is reported *through* the services and properties it orders.
+    view = payload.pop("display_view", None) or {}
     if device is None:
         return payload
 
@@ -455,8 +717,8 @@ def hydrated_node(node: Node, device: InventoryDevice | None) -> dict[str, Any]:
         payload[field] = getattr(device, field, None)
     payload["label"] = device.label or node.label
     payload["type"] = device.type or node.type
-    payload["services"] = device.services or []
-    payload["properties"] = device.properties or []
+    payload["services"] = apply_view(device.services, view.get("services"), "services")
+    payload["properties"] = apply_view(device.properties, view.get("properties"), "properties")
     payload["show_hardware"] = bool(device.show_hardware)
     payload["ieee_address"] = device.ieee_address
     payload["status"] = device.status_live or "unknown"
@@ -494,6 +756,139 @@ def _decode_json(value: Any) -> Any:
     return value
 
 
+# Legacy `nodes` columns SQLite stores as DATETIME. Read through raw SQL they come
+# back as text, and writing text into a DateTime column raises
+# ``TypeError: SQLite DateTime type only accepts Python datetime and date objects``.
+_LEGACY_DATETIME_COLUMNS = ("last_seen", "last_scan")
+
+
+def _decode_dt(value: Any) -> datetime | None:
+    """Raw SQL hands back DATETIME columns as text; the ORM would have parsed them.
+
+    An unparseable stamp becomes ``None`` rather than an error: `last_seen` and
+    `last_scan` are observations the status checker refreshes within a minute,
+    and losing one must not cost a node its inventory row.
+    """
+    if value is None or isinstance(value, datetime):
+        return value
+    if not isinstance(value, str) or not value.strip():
+        return None
+    try:
+        return datetime.fromisoformat(value.strip())
+    except ValueError:
+        logger.debug("Ignoring an unparseable legacy timestamp: %r", value)
+        return None
+
+
+async def _row_is_missing_facts(db: AsyncSession, device_id: str, facts: Mapping[str, Any]) -> bool:
+    """Does the linked row lack a fact the node's legacy columns still hold?
+
+    True only where the node has something to give and the row has nothing in
+    that field, so a node whose facts already made it across is left alone and
+    the backfill stays a no-op on later boots.
+    """
+    device = await db.get(InventoryDevice, device_id)
+    if device is None:
+        return True  # The row is gone; the node needs a new one.
+    for field in (*DEVICE_SCALARS, "label", "type", "ieee_address"):
+        if not _blank(facts.get(field)) and _blank(getattr(device, field, None)):
+            return True
+    return any(
+        facts.get(field) and not getattr(device, field, None)
+        for field in ("services", "properties")
+    )
+
+
+def _with_later_properties(
+    view: dict[str, Any] | None, device: InventoryDevice
+) -> dict[str, Any] | None:
+    """``view``, plus the row's properties the pre-3.3.0 backup never saw.
+
+    They are what the user added while running 3.3.0-3.3.2 — the row was the
+    only place to add them then, and every canvas drew them. Recovering the old
+    view alone would take them off every canvas at once, which reads as data
+    loss. Appended in the row's order, after everything the backup placed.
+    """
+    if view is None:
+        return None
+    entries = view.get("properties")
+    if not isinstance(entries, list):
+        return view
+    listed = {str(e.get("key")) for e in entries if isinstance(e, dict)}
+    later = [e for e in view_entries(device.properties, "properties") if e["key"] not in listed]
+    if not later:
+        return view
+    return {**view, "properties": [*entries, *later]}
+
+
+async def seed_node_views(
+    db: AsyncSession, *, drawn: Callable[[], Mapping[str, Mapping[str, Any]]] | None = None
+) -> int:
+    """Give every linked node with no view one it can be held to.
+
+    Runs once, on the boot that adds `nodes.display_view`. Without it every
+    pre-existing node would fall through to "no view, show everything" and the
+    next scan would push a newly fingerprinted service onto all of them at once —
+    the leak this column exists to stop.
+
+    ``drawn`` returns a map of node id to the services and properties that node
+    itself carried before 3.3.0 unioned them onto the row — the caller reads
+    them out of the pre-upgrade backup, and is only asked to when there is
+    actually a node to seed. Where it has an answer that answer wins, restoring
+    the arrangement the user made; where it does not, the row is the seed and
+    the canvas keeps showing exactly what it shows today. Does not commit.
+
+    The backup is 3.2.0-era, so it can only speak for what existed then. A
+    *property* the row has gained since — one the user added by hand while
+    running 3.3.0-3.3.2, when the row was all a canvas had — appears in no
+    backup entry, and seeding strictly from the backup would hide work the user
+    has been looking at for days. Those are appended visible, keeping the
+    recovered order and hidden flags for everything the backup does know.
+    Services are not treated that way: what a row gained since 3.3.0 is mostly a
+    scan's fingerprint, and holding it back is the whole point of the view.
+    """
+    nodes = list(
+        (
+            await db.execute(
+                select(Node).where(
+                    # A `device_id` naming a row that no longer exists cannot be
+                    # seeded from anything, and leaving it in would match this
+                    # query on every later boot — re-reading the backup file and
+                    # logging a recovery that seeds nothing. Deleting a device
+                    # leaves exactly that: SQLite runs with foreign keys off, so
+                    # the `ON DELETE SET NULL` never fires on an existing table.
+                    Node.device_id.in_(select(InventoryDevice.id)),
+                    Node.display_view.is_(None),
+                )
+            )
+        )
+        .scalars()
+        .all()
+    )
+    if not nodes:
+        return 0
+    devices = await load_devices_for(db, nodes)
+    # Read the backup only now: on every later boot this function returns above
+    # and no file is opened at all.
+    was_drawn = drawn() if drawn is not None else {}
+    seeded = 0
+    for node in nodes:
+        device = devices.get(node.device_id or "")
+        if device is None:  # pragma: no cover - the query already excluded these
+            continue
+        was = was_drawn.get(node.id)
+        # `strict`: an empty list in the backup is this canvas' real answer —
+        # it drew no service — and must not be read as "say nothing, show all".
+        if was:
+            view = next_view(None, view_from_facts(was), device, strict=True)
+            node.display_view = _with_later_properties(view, device)
+        else:
+            node.display_view = view_of_device(device)
+        seeded += 1
+    await db.flush()
+    return seeded
+
+
 async def backfill_node_devices(db: AsyncSession) -> dict[str, int]:
     """Link every pre-3.3.0 canvas node to a Device Inventory row.
 
@@ -507,44 +902,84 @@ async def backfill_node_devices(db: AsyncSession) -> dict[str, int]:
 
     Reads the legacy columns with raw SQL because the model no longer declares
     them — this runs on the boot that drops them, once. Returns counts for the
-    boot log. Does not commit.
+    boot log, ``skipped`` among them: a node whose merge violates a constraint is
+    left unlinked instead of aborting the run. Does not commit.
     """
     legacy = await _legacy_columns_present(db)
     if not legacy:
         # Already migrated: the columns are gone, so nothing can be left to read.
-        return {"linked": 0, "created": 0, "merged": 0}
+        return {"linked": 0, "created": 0, "merged": 0, "skipped": 0}
 
     placeholders = ", ".join(legacy)
     furniture = ", ".join(f"'{t}'" for t in sorted(FURNITURE_TYPES))
+    # Linked nodes are read too, not just unlinked ones. A canvas saved while an
+    # earlier migration was stuck minted a *blank* inventory row from a UI that
+    # had no facts to show, and linked the node to it. Skipping those would count
+    # them as migrated and drop the columns that still hold their only copy of
+    # the ip, services and notes. A linked node is filled, never overwritten.
     rows = (
         await db.execute(
             text(
-                f"SELECT id, label, type, design_id, {placeholders} FROM nodes "
-                f"WHERE device_id IS NULL AND type NOT IN ({furniture}) "
+                f"SELECT id, label, type, design_id, device_id, {placeholders} FROM nodes "
+                f"WHERE type NOT IN ({furniture}) "
                 "ORDER BY updated_at, created_at, id"
             )
         )
     ).mappings().all()
     if not rows:
-        return {"linked": 0, "created": 0, "merged": 0}
+        return {"linked": 0, "created": 0, "merged": 0, "skipped": 0}
 
-    created = merged = 0
+    linked = created = merged = skipped = 0
     for row in rows:
         facts: dict[str, Any] = {c: row[c] for c in legacy}
         facts["services"] = _decode_json(facts.get("services")) or []
         facts["properties"] = _decode_json(facts.get("properties")) or []
+        for field in _LEGACY_DATETIME_COLUMNS:
+            if field in facts:
+                facts[field] = _decode_dt(facts[field])
         facts["label"] = row["label"]
         facts["type"] = row["type"]
 
-        existing = await find_device_for(
-            db, ip=facts.get("ip"), mac=facts.get("mac"), ieee=facts.get("ieee_address")
-        )
-        node = await db.get(Node, row["id"])
-        if node is None:  # pragma: no cover - the row was just read
-            continue
-        device = await link_facts(db, node, facts, overwrite_scalars=True)
-        if device is None:
+        # One savepoint per node: a row the merge cannot write is dropped on its
+        # own rather than taking the whole backfill with it. Every node it does
+        # not link keeps its legacy columns, so nothing is lost and the next boot
+        # retries. The catch is deliberately broad — a node that cannot be read
+        # or written for *any* reason must not cost the others their link.
+        try:
+            async with db.begin_nested():
+                node = await db.get(Node, row["id"])
+                if node is None:  # pragma: no cover - the row was just read
+                    continue
+                if node.device_id and not await _row_is_missing_facts(db, node.device_id, facts):
+                    continue  # Already migrated, and its row holds the facts.
+                existing = await find_device_for(
+                    db, ip=facts.get("ip"), mac=facts.get("mac"), ieee=facts.get("ieee_address")
+                )
+                # A node that is already linked only has its gaps filled: whatever
+                # is on the row was written after the migration and is newer.
+                device = await link_facts(
+                    db,
+                    node,
+                    facts,
+                    overwrite_scalars=node.device_id is None,
+                    # The node's own columns are exactly what this canvas drew
+                    # before the upgrade, empty lists included — so they define
+                    # its view outright. Anything else the row carries (a service
+                    # a scan fingerprinted, a property another canvas added)
+                    # stays hidden here rather than appearing on every canvas.
+                    strict_view=True,
+                )
+                if device is None:
+                    continue
+                await db.flush()
+        except Exception as exc:
+            skipped += 1
+            logger.warning(
+                "Inventory backfill: node %s (%s) skipped — %s", row["id"], row["label"], exc
+            )
             continue
+
+        linked += 1
         if existing is None:
             created += 1
             logger.info(
@@ -558,4 +993,28 @@ async def backfill_node_devices(db: AsyncSession) -> dict[str, int]:
             )
 
     await db.flush()
-    return {"linked": len(rows), "created": created, "merged": merged}
+    return {"linked": linked, "created": created, "merged": merged, "skipped": skipped}
+
+
+async def attach_device_ids(
+    db: AsyncSession, nodes_raw: list[dict[str, Any]]
+) -> list[dict[str, Any]]:
+    """Stamp each imported node with the inventory row that already owns it.
+
+    A canvas-direct import upserts the inventory first, so the node dropped on
+    the canvas can point straight at that row instead of minting a second one
+    on the next save. Matching goes through :func:`find_device_for`, so a
+    Proxmox guest merged into a scanned row by ip/mac resolves too.
+
+    Returns new dicts — the caller's payload is left untouched.
+    """
+    stamped: list[dict[str, Any]] = []
+    for node in nodes_raw:
+        device = await find_device_for(
+            db,
+            ip=node.get("ip"),
+            mac=node.get("mac"),
+            ieee=node.get("ieee_address"),
+        )
+        stamped.append({**node, "device_id": device.id} if device else dict(node))
+    return stamped

backend/app/services/mqtt_common.py

@@ -13,6 +13,8 @@ import logging
 import ssl
 from typing import Any
 
+from app.core.config import settings
+
 logger = logging.getLogger(__name__)
 
 try:
@@ -21,7 +23,10 @@ except ImportError:  # pragma: no cover
     aiomqtt = None  # type: ignore[assignment]
 
 _CONNECTION_TIMEOUT = 5.0   # seconds to verify broker reachability
-_RESPONSE_TIMEOUT = 300.0   # seconds to wait for a gateway response (large meshes are slow)
+# 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:
@@ -71,11 +76,14 @@ async def request_response(
     password: str | None = None,
     tls: bool = False,
     tls_insecure: bool = False,
-    response_timeout: float = _RESPONSE_TIMEOUT,
+    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.
@@ -88,6 +96,14 @@ async def request_response(
             "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
 
@@ -122,12 +138,15 @@ async def request_response(
                         raise ValueError(f"Malformed MQTT response: {exc}") from exc
                     return
 
-            await asyncio.wait_for(_wait_for_response(), timeout=response_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 MQTT response") from 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")

backend/app/services/node_dedupe.py

@@ -15,10 +15,10 @@ from __future__ import annotations
 import logging
 from typing import Any
 
-from sqlalchemy import select
+from sqlalchemy import select, update
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.db.models import Edge, Node
+from app.db.models import Document, Edge, Node, RackDevice
 from app.services.inventory_sync import find_device_for
 
 logger = logging.getLogger(__name__)
@@ -121,7 +121,11 @@ async def dedupe_nodes_by_device(db: AsyncSession) -> int:
             await db.execute(select(Node).where(Node.parent_id.in_(dup_ids)))
         ).scalars().all()
         for child in children:
-            child.parent_id = canonical.id
+            # 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(
@@ -139,6 +143,29 @@ async def dedupe_nodes_by_device(db: AsyncSession) -> int:
                 continue
             seen_pairs.add(key)
 
+        # A rack mount reads live status through `node_id`, and a document may
+        # describe the node itself. Both are `SET NULL` in the schema and SQLite
+        # runs with foreign keys off here, so a duplicate deleted from under them
+        # would leave the column naming a node that no longer exists.
+        await db.execute(
+            update(RackDevice).where(RackDevice.node_id.in_(dup_ids)).values(node_id=canonical.id)
+        )
+        own_doc = (
+            await db.execute(select(Document.id).where(Document.node_id == canonical.id).limit(1))
+        ).scalar_one_or_none()
+        doc_rows = (
+            await db.execute(
+                select(Document)
+                .where(Document.node_id.in_(dup_ids))
+                .order_by(Document.created_at, Document.id)
+            )
+        ).scalars().all()
+        for i, doc in enumerate(doc_rows):
+            # `documents.node_id` is unique (partial index): only one document
+            # can describe the survivor. The rest are orphaned, not deleted —
+            # what the user wrote outlives the node it was attached to.
+            doc.node_id = canonical.id if i == 0 and own_doc is None else None
+
         await db.flush()
         for dup in dups:
             await db.delete(dup)

backend/app/services/proxmox_service.py

@@ -93,24 +93,52 @@ def _guest_type_to_homelable(kind: str) -> str:
     return "vm" if kind == "qemu" else "lxc"
 
 
-def _extract_qemu_ip(agent_payload: dict[str, Any] | None) -> str | None:
-    """Pull the first non-loopback IPv4 from a qemu guest-agent interfaces reply."""
+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
-    for iface in result:
-        if not isinstance(iface, dict):
-            continue
-        for addr in iface.get("ip-addresses") or []:
-            if not isinstance(addr, dict):
+    wanted = normalize_mac(mac)
+    if wanted:
+        for iface in result:
+            if not isinstance(iface, dict):
                 continue
-            if addr.get("ip-address-type") != "ipv4":
+            if normalize_mac(iface.get("hardware-address")) != wanted:
                 continue
-            ip = addr.get("ip-address")
-            if isinstance(ip, str) and ip and not ip.startswith("127."):
+            ip = _iface_ipv4(iface)
+            if ip:
                 return ip
+    for iface in result:
+        ip = _iface_ipv4(iface)
+        if ip:
+            return ip
     return None
 
 
@@ -374,7 +402,7 @@ async def _resolve_guest_net(
                 data = await _get_json(
                     client, f"/nodes/{host_name}/qemu/{vmid}/agent/network-get-interfaces"
                 )
-                ip = _extract_qemu_ip(data)
+                ip = _extract_qemu_ip(data, mac)
         else:
             config = await _get_json(client, f"/nodes/{host_name}/lxc/{vmid}/config")
             ip = _extract_lxc_ip(config)

backend/app/services/scanner.py

@@ -7,6 +7,7 @@ import re
 import socket
 import subprocess
 import threading
+import time
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Any
@@ -16,9 +17,11 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.config import settings
 from app.db.models import InventoryDevice, ScanRun
+from app.services.device_merge import merge_devices, reconcile_duplicates
 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__)
@@ -61,8 +64,89 @@ def _valid_port_range(spec: str) -> bool:
     return len(parts) == 1 or parts[0] <= parts[1]
 
 
-def _build_port_spec(http_ranges: list[str] | None) -> str:
-    """Combine the default port list with validated user ranges for nmap -p."""
+# 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())]
@@ -237,7 +321,9 @@ async def _ping_sweep(target: str, run_id: str | None = None) -> dict[str, dict[
     return alive
 
 
-def _nmap_scan_single(host_dict: dict[str, Any], port_spec: str = _EXTRA_PORTS) -> 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.
@@ -261,8 +347,26 @@ def _nmap_scan_single(host_dict: dict[str, Any], port_spec: str = _EXTRA_PORTS)
     # -sT without root but being explicit avoids edge cases.
     scan_type = "-sS" if os.geteuid() == 0 else "-sT"
 
-    # --- Pass A: port discovery (no -sV, no host-timeout) ---
+    # --- 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:
@@ -469,11 +573,66 @@ def _mock_scan(target: str) -> list[dict[str, Any]]:
     ]
 
 
+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)
@@ -481,26 +640,140 @@ async def _dedupe_pending_by_ip(db: AsyncSession) -> int:
         .order_by(InventoryDevice.discovered_at)
     )).scalars().all()
 
-    by_ip: dict[str, list[InventoryDevice]] = {}
-    for row in rows:
-        if row.ip is None:  # guarded by the query, but keeps the type checker happy
-            continue
-        by_ip.setdefault(row.ip, []).append(row)
-
     deleted = 0
-    for group in by_ip.values():
+    for group in _group_by_shared_ip(list(rows)):
         if len(group) < 2:
             continue
-        keep = next((r for r in group if r.status == "approved"), group[0])
-        for dup in group:
-            if dup is not keep:
-                await db.delete(dup)
-                deleted += 1
+        keep, dups = _collapse_targets(group)
+        if dups:
+            # Non-destructive, for the same reason as `process_host`: whatever
+            # drew the duplicate follows it into `keep`.
+            await merge_devices(db, keep, dups)
+            deleted += len(dups)
     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)
+        # Merge rather than delete: a duplicate row may be the one a canvas node
+        # or a rack mount points at, and SQLite runs with foreign keys off here
+        # so the declared `ON DELETE SET NULL` never fires. `merge_devices`
+        # re-points every reference onto `keep` and unions the facts first.
+        if dups:
+            await merge_devices(db, keep, dups)
+        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,
@@ -529,7 +802,11 @@ async def run_scan(
         hidden_ips_result = await db.execute(
             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])
+        }
 
         # 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
@@ -544,81 +821,17 @@ async def run_scan(
 
         async def _process_host(host: dict[str, Any], discovery_source: str = "arp") -> None:
             nonlocal devices_found
-            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)
+            outcome = await process_host(
+                db,
+                host,
+                hidden_ips=hidden_ips,
+                deep_scan=deep_scan,
+                discovery_source=discovery_source,
+            )
+            if outcome == "skipped":
                 return
-
-            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.
-            match_cond = [InventoryDevice.ip == ip]
-            if norm_mac:
-                match_cond.append(InventoryDevice.mac == norm_mac)
-            existing_rows = (await db.execute(
-                select(InventoryDevice)
-                .where(or_(*match_cond), InventoryDevice.status != "hidden")
-                .order_by(InventoryDevice.discovered_at)
-            )).scalars().all()
-
-            if existing_rows:
-                # Prefer an approved row (it owns the canvas link semantics),
-                # otherwise the oldest. Collapse any leftover duplicates created
-                # by earlier scans.
-                keep = next((r for r in existing_rows if r.status == "approved"), existing_rows[0])
-                for dup in existing_rows:
-                    if dup is not keep:
-                        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
-                keep.services = services
-                # 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)
-            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),
-                ))
+            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
@@ -651,6 +864,14 @@ async def run_scan(
         else:
             mdns_task.cancel()
 
+        # A scan is where a row first learns its MAC, so it is also where two
+        # rows can first be proven to be one device — fold those together before
+        # reporting the run done.
+        merged = await reconcile_duplicates(db)
+        if merged:
+            await db.commit()
+            logger.info("Scan %s: merged %d duplicate inventory row(s)", run_id, merged)
+
         # Mark scan as done or cancelled
         run = await db.get(ScanRun, run_id)
         if run:
@@ -672,3 +893,165 @@ async def run_scan(
     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

@@ -103,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
 
 
@@ -126,10 +134,17 @@ async def _tcp_connect(host: str, port: int) -> bool:
 # 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})
 
 
@@ -211,7 +226,11 @@ async def check_service(svc: dict[str, Any], host: str | None) -> str:
             port in _HTTPS_PORTS or "https" in name or "ssl" in name or "tls" in name
         ) else "http")
         url_host = _service_host(svc, host)
-        url = f"{scheme}://{url_host}" + (f":{port}" if port is not None else "")
+        # 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)

backend/app/services/zigbee_service.py

@@ -7,6 +7,7 @@ import json
 import logging
 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__)
@@ -19,7 +20,10 @@ 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
 
 # Re-exported for backwards compatibility — these now live in mqtt_common.
 __all__ = ["_build_tls_context", "_sanitize_mqtt_error"]
@@ -238,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.
@@ -252,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)
 
@@ -295,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/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()
@@ -48,3 +78,13 @@ 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_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/test_scan_inventory_edit.py

@@ -163,3 +163,78 @@ async def test_legacy_row_defaults_are_coerced(client: AsyncClient, headers, db_
     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_routes.py

@@ -414,3 +414,154 @@ async def test_delete_pending_refuses_a_mounted_device(client: AsyncClient, head
     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

@@ -8,13 +8,23 @@ from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.db.models import InventoryDevice, Node, ScanRun
-from app.services.scanner import _cancelled_runs, request_cancel, run_scan
+from app.services.scanner import (
+    _cancelled_runs,
+    reconcile_orphan_runs,
+    request_cancel,
+    run_scan,
+)
 
 
 @pytest.mark.asyncio
-async def test_background_scan_marks_run_failed_on_exception(mem_db):
-    """If run_scan() raises, the ScanRun must transition running → failed and the
-    session rollback path must execute without a follow-on exception."""
+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:
@@ -36,13 +46,13 @@ async def test_background_scan_marks_run_failed_on_exception(mem_db):
     async with mem_db() as session:
         refreshed = await session.get(ScanRun, run_id)
         assert refreshed is not None
-        assert refreshed.status == "failed"
+        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 'failed'."""
+    must NOT overwrite that terminal status with 'error'."""
     from app.api.routes.scan import _background_scan
 
     async with mem_db() as session:
@@ -436,3 +446,128 @@ async def test_run_scan_updates_existing_pending_device(db_session: AsyncSession
     # 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

@@ -272,6 +272,40 @@ async def test_oidc_callback_creates_session_for_api(client: AsyncClient, oidc_s
     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}
@@ -336,6 +370,84 @@ async def test_oidc_cookie_mutations_require_csrf_and_allowed_origin(client: Asy
     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

backend/tests/test_canvas.py

@@ -706,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_device_merge.py

@@ -0,0 +1,405 @@
+"""Tests for the inventory duplicate repair (app.services.device_merge).
+
+Two shapes, one merge: the user picks the survivor by hand, or an import proves
+two rows are one device by their shared MAC. What both must guarantee is that
+nothing is lost — not a fact, not a canvas node, not a rack mount, not a
+document, and not the *visibility* of the facts that just arrived on a canvas
+that never saw them.
+"""
+
+from datetime import datetime, timezone
+
+import pytest
+from sqlalchemy import select
+
+from app.db.models import (
+    Design,
+    Document,
+    InventoryDevice,
+    InventoryDeviceLink,
+    Node,
+    Rack,
+    RackDevice,
+)
+from app.services.device_merge import merge_devices, reconcile_duplicates
+
+
+def _at(day: int) -> datetime:
+    return datetime(2026, 1, day, tzinfo=timezone.utc)
+
+
+async def _design(db, name="d1"):
+    design = Design(name=name)
+    db.add(design)
+    await db.flush()
+    return design
+
+
+async def _device(db, **kwargs):
+    kwargs.setdefault("discovered_at", _at(1))
+    device = InventoryDevice(**kwargs)
+    db.add(device)
+    await db.flush()
+    return device
+
+
+async def _node(db, design, device, **kwargs):
+    node = Node(design_id=design.id, device_id=device.id, label=kwargs.pop("label", "n8n"),
+                type=kwargs.pop("type", "lxc"), **kwargs)
+    db.add(node)
+    await db.flush()
+    return node
+
+
+async def _rack(db, design):
+    rack = Rack(design_id=design.id, name="R1", u_height=42)
+    db.add(rack)
+    await db.flush()
+    return rack
+
+
+@pytest.mark.asyncio
+async def test_merge_unions_facts_without_overwriting_the_survivor(db_session):
+    winner = await _device(
+        db_session, id="w", ip="192.168.1.62", mac="bc:24:11:95:af:8c",
+        hostname="n8n", label="n8n", vendor="Proxmox VE", status="pending",
+        services=[{"service_name": "ssh", "port": 22, "protocol": "tcp"}],
+        properties=[{"key": "VMID", "value": "130", "visible": True}],
+        discovery_source="arp", discovery_sources=["arp", "proxmox"],
+        discovered_at=_at(5),
+    )
+    loser = await _device(
+        db_session, id="l", ip="10.0.0.9", mac=None, hostname="ignored",
+        notes="runs the automations", cpu_count=4, status="approved",
+        services=[{"service_name": "http", "port": 5678, "protocol": "tcp"}],
+        properties=[{"key": "Owner", "value": "me", "visible": True}],
+        discovery_source="canvas", discovery_sources=["canvas"],
+        discovered_at=_at(2),
+    )
+
+    result = await merge_devices(db_session, winner, [loser])
+    await db_session.flush()
+
+    assert result["merged"] == 1
+    assert await db_session.get(InventoryDevice, "l") is None
+    # Established facts are never overwritten by the folded-in row...
+    assert winner.hostname == "n8n"
+    # ...but every gap it can fill, it fills.
+    assert winner.notes == "runs the automations"
+    assert winner.cpu_count == 4
+    # Addresses and lists union; sources accumulate.
+    assert winner.ip == "192.168.1.62, 10.0.0.9"
+    assert {s["service_name"] for s in winner.services} == {"ssh", "http"}
+    assert {p["key"] for p in winner.properties} == {"VMID", "Owner"}
+    assert set(winner.discovery_sources) == {"arp", "proxmox", "canvas"}
+    # Drawn on a canvas, so the survivor cannot go back to the pending queue.
+    assert winner.status == "approved"
+    # Known since the earliest of the two rows saw it.
+    assert winner.discovered_at == _at(2)
+
+
+@pytest.mark.asyncio
+async def test_merge_repoints_canvas_nodes_and_rack_mounts(db_session):
+    design = await _design(db_session)
+    other = await _design(db_session, name="d2")
+    winner = await _device(db_session, id="w", ip="192.168.1.62", status="approved")
+    loser = await _device(db_session, id="l", ip="192.168.1.62", label="n8n", status="approved")
+
+    kept = await _node(db_session, design, winner, pos_x=10, pos_y=20)
+    moved = await _node(db_session, other, loser, pos_x=300, pos_y=400)
+    rack = await _rack(db_session, design)
+    mount = RackDevice(design_id=design.id, rack_id=rack.id, device_id=loser.id, label="n8n")
+    db_session.add(mount)
+    await db_session.flush()
+
+    await merge_devices(db_session, winner, [loser])
+    await db_session.flush()
+
+    # The node on the other canvas keeps its position and now draws the survivor.
+    await db_session.refresh(moved)
+    assert moved.device_id == "w"
+    assert (moved.pos_x, moved.pos_y) == (300, 400)
+    assert (await db_session.get(Node, kept.id)).device_id == "w"
+    # The mount follows too — a rack that rendered before still renders.
+    await db_session.refresh(mount)
+    assert mount.device_id == "w"
+
+
+@pytest.mark.asyncio
+async def test_merge_shows_the_new_facts_on_a_canvas_that_never_saw_them(db_session):
+    """The point of the merge: a poorer node must gain the richer row's facts.
+
+    `display_view` is a whitelist — without extending it the folded-in services
+    and properties would render hidden and the canvas would look unchanged.
+    """
+    design = await _design(db_session)
+    winner = await _device(
+        db_session, id="w", ip="192.168.1.62",
+        services=[{"service_name": "ssh", "port": 22, "protocol": "tcp"}],
+        properties=[{"key": "VMID", "value": "130", "visible": True}],
+    )
+    loser = await _device(
+        db_session, id="l", ip="192.168.1.62",
+        services=[{"service_name": "http", "port": 5678, "protocol": "tcp"}],
+        properties=[],
+    )
+    poor = await _node(db_session, design, loser)
+    poor.display_view = {
+        "services": [{"key": "5678|tcp|http", "visible": True}],
+        "properties": [],
+    }
+    await db_session.flush()
+
+    await merge_devices(db_session, winner, [loser])
+    await db_session.flush()
+    await db_session.refresh(poor)
+
+    services = poor.display_view["services"]
+    assert [e["visible"] for e in services] == [True, True]
+    assert {e["key"] for e in services} == {"5678|tcp|http", "22|tcp|ssh"}
+    # A property list this canvas had never seen picks up the survivor's.
+    assert [e["key"] for e in poor.display_view["properties"]] == ["vmid"]
+
+
+@pytest.mark.asyncio
+async def test_merge_keeps_a_deliberately_hidden_fact_hidden(db_session):
+    design = await _design(db_session)
+    winner = await _device(
+        db_session, id="w", ip="192.168.1.62",
+        services=[{"service_name": "ssh", "port": 22, "protocol": "tcp"}],
+    )
+    loser = await _device(db_session, id="l", ip="192.168.1.62", services=[])
+    node = await _node(db_session, design, loser)
+    node.display_view = {"services": [{"key": "22|tcp|ssh", "visible": False}], "properties": []}
+    await db_session.flush()
+
+    await merge_devices(db_session, winner, [loser])
+    await db_session.flush()
+    await db_session.refresh(node)
+
+    assert node.display_view["services"] == [{"key": "22|tcp|ssh", "visible": False}]
+
+
+@pytest.mark.asyncio
+async def test_merge_collapses_two_nodes_that_now_draw_one_device(db_session):
+    """Both rows drawn on the *same* canvas: one node survives, the oldest."""
+    design = await _design(db_session)
+    winner = await _device(db_session, id="w", ip="192.168.1.62", status="approved")
+    loser = await _device(db_session, id="l", ip="192.168.1.62", status="approved")
+    keep = await _node(db_session, design, winner, pos_x=10, pos_y=20)
+    await _node(db_session, design, loser, pos_x=99, pos_y=99)
+
+    await merge_devices(db_session, winner, [loser])
+    await db_session.flush()
+
+    nodes = (
+        await db_session.execute(select(Node).where(Node.design_id == design.id))
+    ).scalars().all()
+    assert [n.id for n in nodes] == [keep.id]
+    assert (nodes[0].pos_x, nodes[0].pos_y) == (10, 20)
+
+
+@pytest.mark.asyncio
+async def test_a_rack_mount_survives_the_node_collapse(db_session):
+    """`rack_devices.node_id` must not be left naming a deleted duplicate node."""
+    design = await _design(db_session)
+    winner = await _device(db_session, id="w", ip="192.168.1.62", status="approved")
+    loser = await _device(db_session, id="l", ip="192.168.1.62", status="approved")
+    keep = await _node(db_session, design, winner)
+    dup = await _node(db_session, design, loser)
+    rack = await _rack(db_session, design)
+    mount = RackDevice(
+        design_id=design.id, rack_id=rack.id, device_id=loser.id, node_id=dup.id, label="n8n"
+    )
+    db_session.add(mount)
+    await db_session.flush()
+
+    await merge_devices(db_session, winner, [loser])
+    await db_session.flush()
+    await db_session.refresh(mount)
+
+    assert mount.device_id == "w"
+    assert mount.node_id == keep.id
+    assert await db_session.get(Node, dup.id) is None
+
+
+@pytest.mark.asyncio
+async def test_merge_adopts_a_document_or_orphans_it(db_session):
+    winner = await _device(db_session, id="w", ip="192.168.1.62")
+    loser = await _device(db_session, id="l", ip="192.168.1.62")
+    doc = Document(title="n8n", slug="n8n", device_id=loser.id, body="# n8n")
+    db_session.add(doc)
+    await db_session.flush()
+
+    result = await merge_devices(db_session, winner, [loser])
+    await db_session.flush()
+    await db_session.refresh(doc)
+
+    # No document on the survivor, so the loser's is adopted rather than orphaned.
+    assert doc.device_id == "w"
+    assert result["documents_orphaned"] == 0
+
+
+@pytest.mark.asyncio
+async def test_a_second_document_is_orphaned_not_deleted(db_session):
+    winner = await _device(db_session, id="w", ip="192.168.1.62")
+    loser = await _device(db_session, id="l", ip="192.168.1.62")
+    mine = Document(title="n8n", slug="n8n", device_id=winner.id, body="kept")
+    theirs = Document(title="n8n (dup)", slug="n8n-dup", device_id=loser.id, body="written by hand")
+    db_session.add_all([mine, theirs])
+    await db_session.flush()
+
+    result = await merge_devices(db_session, winner, [loser])
+    await db_session.flush()
+    await db_session.refresh(theirs)
+
+    assert result["documents_orphaned"] == 1
+    assert theirs.device_id is None
+    assert theirs.body == "written by hand"  # survives as an orphan
+
+
+@pytest.mark.asyncio
+async def test_merge_moves_mesh_links_onto_the_survivor_ieee(db_session):
+    winner = await _device(db_session, id="w", ieee_address="pve-pve1-130", ip="192.168.1.62")
+    loser = await _device(db_session, id="l", ieee_address="0xAABB", ip="192.168.1.62")
+    db_session.add(InventoryDeviceLink(source_ieee="pve-host", target_ieee="0xAABB"))
+    db_session.add(InventoryDeviceLink(source_ieee="0xAABB", target_ieee="0xCCDD"))
+    await db_session.flush()
+
+    await merge_devices(db_session, winner, [loser])
+    await db_session.flush()
+
+    links = (await db_session.execute(select(InventoryDeviceLink))).scalars().all()
+    pairs = {(link.source_ieee, link.target_ieee) for link in links}
+    assert pairs == {("pve-host", "pve-pve1-130"), ("pve-pve1-130", "0xCCDD")}
+
+
+@pytest.mark.asyncio
+async def test_the_survivor_adopts_an_ieee_it_lacks(db_session):
+    winner = await _device(db_session, id="w", ip="192.168.1.62", ieee_address=None)
+    loser = await _device(db_session, id="l", ip="192.168.1.62", ieee_address="pve-pve1-130")
+
+    await merge_devices(db_session, winner, [loser])
+    await db_session.flush()
+
+    assert winner.ieee_address == "pve-pve1-130"
+
+
+@pytest.mark.asyncio
+async def test_reconcile_merges_rows_sharing_a_mac(db_session):
+    """The reported case: a Proxmox row and a canvas row, same NIC."""
+    scanned = await _device(
+        db_session, id="scanned", ip="192.168.1.62", mac="bc:24:11:95:af:8c",
+        ieee_address="pve-proxmox-ai-130", status="pending", discovered_at=_at(1),
+    )
+    from_canvas = await _device(
+        db_session, id="canvas", ip="192.168.1.62", mac="bc:24:11:95:af:8c",
+        label="n8n", status="approved", discovered_at=_at(20),
+    )
+
+    merged = await reconcile_duplicates(db_session)
+    await db_session.flush()
+
+    assert merged == 1
+    # The IEEE-bearing row wins: the Proxmox import and the link graph key on it.
+    assert await db_session.get(InventoryDevice, from_canvas.id) is None
+    assert (await db_session.get(InventoryDevice, scanned.id)).label == "n8n"
+
+
+@pytest.mark.asyncio
+async def test_reconcile_leaves_rows_that_only_share_an_ip(db_session):
+    """An IP is not an identity — a re-used lease must not merge two machines."""
+    await _device(db_session, id="a", ip="192.168.1.62", mac="aa:aa:aa:aa:aa:aa")
+    await _device(db_session, id="b", ip="192.168.1.62", mac="bb:bb:bb:bb:bb:bb")
+
+    assert await reconcile_duplicates(db_session) == 0
+    assert len((await db_session.execute(select(InventoryDevice))).scalars().all()) == 2
+
+
+@pytest.mark.asyncio
+async def test_reconcile_leaves_two_proxmox_guests_sharing_a_mac(db_session):
+    """Distinct synthetic IEEEs are decisive: two guests are never one device."""
+    await _device(db_session, id="a", mac="bc:24:11:95:af:8c", ieee_address="pve-pve1-130")
+    await _device(db_session, id="b", mac="bc:24:11:95:af:8c", ieee_address="pve-pve1-131")
+
+    assert await reconcile_duplicates(db_session) == 0
+    assert len((await db_session.execute(select(InventoryDevice))).scalars().all()) == 2
+
+
+@pytest.mark.asyncio
+async def test_reconcile_never_touches_a_hidden_row(db_session):
+    """A hidden row was hidden on purpose — merging it would resurrect it."""
+    await _device(db_session, id="visible", mac="bc:24:11:95:af:8c", status="pending")
+    await _device(db_session, id="hidden", mac="bc:24:11:95:af:8c", status="hidden")
+
+    assert await reconcile_duplicates(db_session) == 0
+    hidden = await db_session.get(InventoryDevice, "hidden")
+    assert hidden is not None and hidden.status == "hidden"
+
+
+@pytest.mark.asyncio
+async def test_reconcile_is_idempotent(db_session):
+    await _device(db_session, id="a", mac="bc:24:11:95:af:8c", ip="192.168.1.62")
+    await _device(db_session, id="b", mac="bc:24:11:95:af:8c", ip="192.168.1.62")
+
+    assert await reconcile_duplicates(db_session) == 1
+    await db_session.flush()
+    assert await reconcile_duplicates(db_session) == 0
+
+
+# --- The route -----------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_merge_route_returns_the_survivor(client, headers, db_session):
+    await _device(db_session, id="w", ip="192.168.1.62", label="n8n", status="approved")
+    await _device(db_session, id="l", hostname="n8n", notes="the good notes")
+    await db_session.commit()
+
+    res = await client.post(
+        "/api/v1/scan/pending/merge",
+        json={"winner_id": "w", "loser_ids": ["l"]},
+        headers=headers,
+    )
+
+    assert res.status_code == 200
+    body = res.json()
+    assert body["id"] == "w"
+    assert body["notes"] == "the good notes"
+    assert await db_session.get(InventoryDevice, "l") is None
+
+
+@pytest.mark.asyncio
+async def test_merge_route_rejects_a_single_device(client, headers, db_session):
+    await _device(db_session, id="w", ip="192.168.1.62")
+    await db_session.commit()
+
+    res = await client.post(
+        "/api/v1/scan/pending/merge",
+        json={"winner_id": "w", "loser_ids": ["w"]},
+        headers=headers,
+    )
+
+    assert res.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_merge_route_404s_on_an_unknown_row(client, headers, db_session):
+    await _device(db_session, id="w", ip="192.168.1.62")
+    await db_session.commit()
+
+    res = await client.post(
+        "/api/v1/scan/pending/merge",
+        json={"winner_id": "w", "loser_ids": ["nope"]},
+        headers=headers,
+    )
+
+    assert res.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_merge_route_requires_auth(client, db_session):
+    res = await client.post(
+        "/api/v1/scan/pending/merge", json={"winner_id": "w", "loser_ids": ["l"]}
+    )
+    assert res.status_code in (401, 403)

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_http_probe.py

@@ -1,10 +1,11 @@
 """Tests for the HTTP probe used by deep-scan service identification."""
-from unittest.mock import AsyncMock, patch
+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,
@@ -15,6 +16,39 @@ def _response(text: str = "", headers: dict | None = None, status: int = 200) ->
     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():
@@ -37,15 +71,18 @@ def test_extract_title_case_insensitive():
 
 @pytest.mark.asyncio
 async def test_probe_port_reads_title():
-    with patch("httpx.AsyncClient.get", new=AsyncMock(return_value=_response("<title>Jellyfin</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():
-    resp = _response("", headers={"Server": "nginx", "X-Powered-By": "Express"})
-    with patch("httpx.AsyncClient.get", new=AsyncMock(return_value=resp)):
+    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"}
 
@@ -53,30 +90,33 @@ async def test_probe_port_reads_headers():
 @pytest.mark.asyncio
 async def test_probe_port_falls_back_to_http():
     # https raises, http succeeds
-    calls = {"n": 0}
-
-    async def fake_get(self, url, **kw):
-        calls["n"] += 1
-        if url.startswith("https"):
+    def handler(request):
+        if str(request.url).startswith("https"):
             raise httpx.ConnectError("tls fail")
         return _response("<title>HTTP App</title>")
 
-    with patch("httpx.AsyncClient.get", new=fake_get):
+    ctx, factory = _patch_client(handler)
+    with ctx:
         result = await probe_port("10.0.0.5", 8080)
     assert result["title"] == "HTTP App"
-    assert calls["n"] == 2  # tried https then http
+    assert len(factory.requests) == 2  # tried https then http
 
 
 @pytest.mark.asyncio
 async def test_probe_port_no_signal_returns_none():
-    with patch("httpx.AsyncClient.get", new=AsyncMock(return_value=_response(""))):
+    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():
-    with patch("httpx.AsyncClient.get", new=AsyncMock(side_effect=httpx.TimeoutException("slow"))):
+    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
 
@@ -84,33 +124,126 @@ async def test_probe_port_timeout_returns_none():
 @pytest.mark.asyncio
 async def test_probe_port_skips_non_http_ports():
     # SSH should never trigger an HTTP request
-    get = AsyncMock()
-    with patch("httpx.AsyncClient.get", new=get):
+    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
-    get.assert_not_called()
+    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():
-    with patch("app.services.http_probe.httpx.AsyncClient") as client_cls:
-        instance = client_cls.return_value.__aenter__.return_value
-        instance.get = AsyncMock(return_value=_response("<title>X</title>"))
+    ctx, factory = _patch_client(lambda req: _response("<title>X</title>"))
+    with ctx:
         await probe_port("10.0.0.5", 8443, verify_tls=True)
-    assert client_cls.call_args.kwargs["verify"] is 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():
-    async def fake_get(self, url, **kw):
-        if ":8096" in url:
+    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"}]
-    with patch("httpx.AsyncClient.get", new=fake_get):
+    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}

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_inventory_sync.py

@@ -17,8 +17,11 @@ from app.services.inventory_sync import (
     backfill_node_devices,
     changed_facts,
     find_device_for,
+    hydrated_node,
+    link_facts,
     merge_properties,
     merge_services,
+    seed_node_views,
 )
 
 
@@ -82,6 +85,49 @@ class TestMergeRules:
         assert out[1]["port"] == 80
 
 
+    def test_a_scan_never_repaints_an_icon_the_user_picked(self):
+        """Every "Scan network" used to overwrite a hand-picked brand icon."""
+        base = [
+            {"port": 80, "protocol": "tcp", "service_name": "http",
+             "icon": "brand:pihole", "category": "network"},
+        ]
+        # What fingerprint_ports returns for the same port: its own guess.
+        incoming = [
+            {"port": 80, "protocol": "tcp", "service_name": "http",
+             "icon": "Globe", "category": "web"},
+        ]
+        out = merge_services(base, incoming, discovered=True)
+        assert len(out) == 1
+        assert out[0]["icon"] == "brand:pihole"
+        assert out[0]["category"] == "network"
+
+    def test_a_scan_still_fills_an_icon_the_service_never_had(self):
+        out = merge_services(
+            [{"port": 80, "protocol": "tcp", "service_name": "http"}],
+            [{"port": 80, "protocol": "tcp", "service_name": "http",
+              "icon": "Globe", "category": "web"}],
+            discovered=True,
+        )
+        assert out[0]["icon"] == "Globe"
+        assert out[0]["category"] == "web"
+
+    def test_a_user_edit_still_changes_the_icon(self):
+        """The guard is for scanner output only — an edit is an edit."""
+        out = merge_services(
+            [{"port": 80, "protocol": "tcp", "service_name": "http", "icon": "Globe"}],
+            [{"port": 80, "protocol": "tcp", "service_name": "http", "icon": "brand:pihole"}],
+        )
+        assert out[0]["icon"] == "brand:pihole"
+
+    def test_services_keep_an_established_icon_when_incoming_has_none(self):
+        """A blank field is silence, not a reset — mirrors merge_properties."""
+        out = merge_services(
+            [{"port": 80, "protocol": "tcp", "service_name": "http", "icon": "brand:pihole"}],
+            [{"port": 80, "protocol": "tcp", "service_name": "http", "icon": None}],
+        )
+        assert out[0]["icon"] == "brand:pihole"
+
+
 class TestChangedFacts:
     """What a save is allowed to write: its edit, not its whole snapshot."""
 
@@ -178,6 +224,92 @@ class TestFindDeviceFor:
         found = await find_device_for(db_session, ip="10.0.0.5", mac=None, ieee=None)
         assert found is not None and found.id == "d-hidden"
 
+    @pytest.mark.asyncio
+    async def test_matches_an_ieee_written_in_another_case(self, db_session):
+        """One radio, one row: `ieee_address` is UNIQUE, so a case-sensitive
+        match here would mint a second row the index then refuses."""
+        db_session.add(InventoryDevice(id="d-1", ieee_address="0x00124b0022334455"))
+        await db_session.commit()
+
+        found = await find_device_for(
+            db_session, ip=None, mac=None, ieee="0x00124B0022334455"
+        )
+        assert found is not None and found.id == "d-1"
+
+
+class TestIeeeCollisions:
+    """`device_inventory.ieee_address` is UNIQUE — a merge must never duplicate it."""
+
+    @pytest.mark.asyncio
+    async def test_an_address_another_row_owns_is_left_where_it_is(self, db_session):
+        """The node is already linked, so identity is settled — the IEEE is not
+        a reason to move it, and writing it here would violate the index."""
+        design = await _design(db_session)
+        db_session.add_all([
+            InventoryDevice(id="d-radio", ieee_address="0xAAA"),
+            InventoryDevice(id="d-host", ip="10.0.0.5"),
+        ])
+        node = _node(design, device_id="d-host")
+        db_session.add(node)
+        await db_session.commit()
+
+        device = await link_facts(
+            db_session, node, {"ip": "10.0.0.5", "ieee_address": "0xAAA"}, overwrite_scalars=True
+        )
+        await db_session.commit()
+
+        assert device is not None and device.id == "d-host"
+        assert device.ieee_address is None
+        radio = await db_session.get(InventoryDevice, "d-radio")
+        assert radio is not None and radio.ieee_address == "0xAAA"
+
+    @pytest.mark.asyncio
+    async def test_the_row_that_already_holds_it_keeps_writing_it(self, db_session):
+        design = await _design(db_session)
+        db_session.add(InventoryDevice(id="d-1", ip="10.0.0.5", ieee_address="0xAAA"))
+        node = _node(design)
+        db_session.add(node)
+        await db_session.commit()
+
+        device = await link_facts(
+            db_session, node, {"ip": "10.0.0.5", "ieee_address": "0xAAA"}, overwrite_scalars=True
+        )
+        await db_session.commit()
+
+        assert device is not None and device.ieee_address == "0xAAA"
+
+
+
+
+class TestStatusOnLink:
+    """A row a node draws is past the pending queue."""
+
+    @pytest.mark.asyncio
+    async def test_pending_row_is_approved_once_a_node_draws_it(self, db_session):
+        design = await _design(db_session)
+        db_session.add(InventoryDevice(id="d-1", ip="10.0.0.5", status="pending"))
+        node = _node(design)
+        db_session.add(node)
+        await db_session.commit()
+
+        device = await link_facts(db_session, node, {"ip": "10.0.0.5"})
+        await db_session.commit()
+
+        assert device is not None and device.status == "approved"
+
+    @pytest.mark.asyncio
+    async def test_hidden_row_stays_hidden(self, db_session):
+        """The user hid it on purpose — drawing it does not undo that."""
+        design = await _design(db_session)
+        db_session.add(InventoryDevice(id="d-1", ip="10.0.0.5", status="hidden"))
+        node = _node(design)
+        db_session.add(node)
+        await db_session.commit()
+
+        device = await link_facts(db_session, node, {"ip": "10.0.0.5"})
+        await db_session.commit()
+
+        assert device is not None and device.status == "hidden"
 
 # --- the backfill -----------------------------------------------------------
 
@@ -238,7 +370,7 @@ class TestBackfill:
         db_session.add(_node(design))
         await db_session.commit()
 
-        assert await backfill_node_devices(db_session) == {"linked": 0, "created": 0, "merged": 0}
+        assert await backfill_node_devices(db_session) == {"linked": 0, "created": 0, "merged": 0, "skipped": 0}
 
     @pytest.mark.asyncio
     async def test_links_a_node_to_its_existing_row(self, db_session):
@@ -251,7 +383,7 @@ class TestBackfill:
         stats = await backfill_node_devices(db_session)
         await db_session.commit()
 
-        assert stats == {"linked": 1, "created": 0, "merged": 1}
+        assert stats == {"linked": 1, "created": 0, "merged": 1, "skipped": 0}
         node = await db_session.get(Node, node_id)
         assert node is not None and node.device_id == "d-1"
 
@@ -266,7 +398,7 @@ class TestBackfill:
         stats = await backfill_node_devices(db_session)
         await db_session.commit()
 
-        assert stats == {"linked": 1, "created": 1, "merged": 0}
+        assert stats == {"linked": 1, "created": 1, "merged": 0, "skipped": 0}
         node = await db_session.get(Node, node_id)
         assert node is not None
         device = await db_session.get(InventoryDevice, node.device_id)
@@ -330,6 +462,133 @@ class TestBackfill:
         assert stats["linked"] == 0
         assert (await db_session.execute(select(InventoryDevice))).scalars().all() == []
 
+    @pytest.mark.asyncio
+    async def test_carries_over_timestamps_stored_as_text(self, db_session):
+        """The legacy columns are read with raw SQL, so SQLite hands the DATETIME
+        ones back as strings. Writing one straight into the row raises
+        ``TypeError: SQLite DateTime type only accepts Python datetime and date
+        objects`` — which used to abort the whole backfill (issue #347)."""
+        await self._legacy_nodes_table(db_session)
+        design = await _design(db_session)
+        node_id = await self._legacy_node(
+            db_session,
+            design,
+            ip="10.0.0.5",
+            label="Dockerhost",
+            status="online",
+            last_seen="2026-08-15 04:10:22.123456",
+            last_scan="2026-08-15 04:00:00",
+        )
+
+        stats = await backfill_node_devices(db_session)
+        await db_session.commit()
+
+        assert stats == {"linked": 1, "created": 1, "merged": 0, "skipped": 0}
+        node = await db_session.get(Node, node_id)
+        assert node is not None
+        device = await db_session.get(InventoryDevice, node.device_id)
+        assert device is not None
+        assert device.last_seen == datetime(2026, 8, 15, 4, 10, 22, 123456)
+        assert device.last_scan == datetime(2026, 8, 15, 4, 0, 0)
+        assert device.status_live == "online"
+
+    @pytest.mark.asyncio
+    async def test_a_stamp_it_cannot_parse_costs_only_the_stamp(self, db_session):
+        await self._legacy_nodes_table(db_session)
+        design = await _design(db_session)
+        await self._legacy_node(db_session, design, ip="10.0.0.5", last_seen="not a date")
+
+        stats = await backfill_node_devices(db_session)
+        await db_session.commit()
+
+        assert stats["linked"] == 1
+        device = (await db_session.execute(select(InventoryDevice))).scalars().one()
+        assert device.last_seen is None
+        assert device.ip == "10.0.0.5"
+
+    @pytest.mark.asyncio
+    async def test_one_unwritable_node_does_not_cost_the_others_their_link(self, db_session, monkeypatch):
+        """Whatever a single node raises — not only a constraint violation — the
+        rest of the canvas still gets linked."""
+        await self._legacy_nodes_table(db_session)
+        design = await _design(db_session)
+        await self._legacy_node(db_session, design, ip="10.0.0.5", label="good")
+        await self._legacy_node(db_session, design, ip="10.0.0.6", label="bad")
+
+        import app.services.inventory_sync as module
+
+        real = module.link_facts
+
+        async def link_facts(db, node, facts, **kwargs):
+            if facts.get("ip") == "10.0.0.6":
+                raise TypeError("SQLite DateTime type only accepts Python datetime")
+            return await real(db, node, facts, **kwargs)
+
+        monkeypatch.setattr(module, "link_facts", link_facts)
+
+        stats = await module.backfill_node_devices(db_session)
+        await db_session.commit()
+
+        assert stats["linked"] == 1
+        assert stats["skipped"] == 1
+        devices = (await db_session.execute(select(InventoryDevice))).scalars().all()
+        assert [d.ip for d in devices] == ["10.0.0.5"]
+
+    @pytest.mark.asyncio
+    async def test_fills_a_blank_row_a_stuck_canvas_save_created(self, db_session):
+        """A save made while an earlier migration was stuck linked the node to a
+        row minted from a blank UI. Those facts only exist in the legacy columns,
+        and the drop is about to remove them — so fill the row before it does."""
+        await self._legacy_nodes_table(db_session)
+        design = await _design(db_session)
+        db_session.add(InventoryDevice(id="d-blank", ip="", label="Dockerhost", services=[]))
+        await db_session.commit()
+        node_id = await self._legacy_node(
+            db_session, design, label="Dockerhost", ip="192.168.0.42", hostname="clara.lan",
+            notes="in the cupboard", services=[{"port": 443, "protocol": "tcp", "service_name": "https"}],
+        )
+        node = await db_session.get(Node, node_id)
+        node.device_id = "d-blank"
+        await db_session.commit()
+
+        stats = await backfill_node_devices(db_session)
+        await db_session.commit()
+
+        assert stats["linked"] == 1
+        device = await db_session.get(InventoryDevice, "d-blank")
+        assert device is not None
+        assert device.ip == "192.168.0.42"
+        assert device.hostname == "clara.lan"
+        assert device.notes == "in the cupboard"
+        assert [s["service_name"] for s in device.services] == ["https"]
+
+    @pytest.mark.asyncio
+    async def test_leaves_a_linked_row_that_already_has_the_facts_alone(self, db_session):
+        """The mirror of the above: a row a user has since edited is not reverted
+        to what the node's abandoned columns still say."""
+        await self._legacy_nodes_table(db_session)
+        design = await _design(db_session)
+        db_session.add(InventoryDevice(
+            id="d-1", ip="192.168.0.99", hostname="renamed.lan",
+            label="Dockerhost", type="docker_host",
+        ))
+        await db_session.commit()
+        node_id = await self._legacy_node(
+            db_session, design, ip="192.168.0.42", hostname="clara.lan", label="Dockerhost"
+        )
+        node = await db_session.get(Node, node_id)
+        node.device_id = "d-1"
+        await db_session.commit()
+
+        stats = await backfill_node_devices(db_session)
+        await db_session.commit()
+
+        assert stats["linked"] == 0
+        device = await db_session.get(InventoryDevice, "d-1")
+        assert device is not None
+        assert device.ip == "192.168.0.99"
+        assert device.hostname == "renamed.lan"
+
     @pytest.mark.asyncio
     async def test_is_a_no_op_on_a_second_run(self, db_session):
         await self._legacy_nodes_table(db_session)
@@ -342,10 +601,65 @@ class TestBackfill:
         await db_session.commit()
 
         assert first["linked"] == 1
-        assert second == {"linked": 0, "created": 0, "merged": 0}
+        assert second == {"linked": 0, "created": 0, "merged": 0, "skipped": 0}
         rows = (await db_session.execute(select(InventoryDevice))).scalars().all()
         assert len(rows) == 1
 
+    @pytest.mark.asyncio
+    async def test_each_canvas_keeps_showing_what_it_showed(self, db_session):
+        """The upgrade must not redraw a canvas.
+
+        Two canvases drew the same host with different service lists, and the
+        scanner's row for it holds a third the user never put on either. They
+        converge on one row — so each node keeps a view of the subset it drew,
+        and the scanner's guess appears on neither.
+        """
+        await self._legacy_nodes_table(db_session)
+        ssh = {"port": 22, "protocol": "tcp", "service_name": "ssh"}
+        https = {"port": 443, "protocol": "tcp", "service_name": "https"}
+        kuma = {"port": 3001, "protocol": "tcp", "service_name": "Uptime Kuma"}
+        db_session.add(InventoryDevice(id="d-1", ip="10.0.0.5", services=[kuma]))
+        await db_session.commit()
+
+        one, two = await _design(db_session, "Net"), await _design(db_session, "Rack")
+        a = await self._legacy_node(db_session, one, ip="10.0.0.5", services=[ssh])
+        b = await self._legacy_node(db_session, two, ip="10.0.0.5", services=[ssh, https])
+
+        await backfill_node_devices(db_session)
+        await db_session.commit()
+
+        device = await db_session.get(InventoryDevice, "d-1")
+        assert {s["service_name"] for s in device.services} == {"Uptime Kuma", "ssh", "https"}
+        drawn = {}
+        for node_id in (a, b):
+            node = await db_session.get(Node, node_id)
+            payload = hydrated_node(node, device)
+            drawn[node_id] = [s["service_name"] for s in payload["services"] if s.get("visible", True)]
+        assert drawn[a] == ["ssh"]
+        assert drawn[b] == ["ssh", "https"]
+
+    @pytest.mark.asyncio
+    async def test_a_node_that_drew_no_service_keeps_drawing_none(self, db_session):
+        """An empty legacy list is an answer: that canvas showed no services."""
+        await self._legacy_nodes_table(db_session)
+        db_session.add(
+            InventoryDevice(
+                id="d-1", ip="10.0.0.5",
+                services=[{"port": 3001, "protocol": "tcp", "service_name": "Uptime Kuma"}],
+            )
+        )
+        await db_session.commit()
+        design = await _design(db_session)
+        node_id = await self._legacy_node(db_session, design, ip="10.0.0.5", services=[])
+
+        await backfill_node_devices(db_session)
+        await db_session.commit()
+
+        node = await db_session.get(Node, node_id)
+        device = await db_session.get(InventoryDevice, "d-1")
+        payload = hydrated_node(node, device)
+        assert [s.get("visible", True) for s in payload["services"]] == [False]
+
 
 # --- routes -----------------------------------------------------------------
 
@@ -798,3 +1112,374 @@ class TestRoutesKeepTheLinkInStep:
         assert res.status_code == 200
         node = await db_session.get(Node, res.json()["node_id"])
         assert node is not None and node.device_id == "d-1"
+
+
+class TestPerNodeView:
+    """Order and visibility belong to the node, the facts to the row.
+
+    The same device drawn on two canvases is one inventory row, so without a
+    per-node view every canvas showing it inherits every service a scan ever
+    fingerprinted and every property any other canvas added.
+    """
+
+    async def _node_on(self, client, headers, design_id: str, **payload) -> dict:
+        body = {"type": "nas", "label": "NAS", "ip": "10.0.0.5", "design_id": design_id, "force": True}
+        body.update(payload)
+        res = await client.post("/api/v1/nodes", json=body, headers=body.pop("headers", None) or headers)
+        assert res.status_code == 201
+        return res.json()
+
+    @pytest.mark.asyncio
+    async def test_a_new_node_shows_what_the_row_already_holds(
+        self, client: AsyncClient, headers, db_session
+    ):
+        """An empty payload list means "I have nothing to say", not "hide it all"."""
+        db_session.add(
+            InventoryDevice(
+                id="d-1",
+                ip="10.0.0.5",
+                services=[{"port": 22, "protocol": "tcp", "service_name": "ssh"}],
+                properties=[{"key": "Rack", "value": "A1", "icon": None, "visible": True}],
+            )
+        )
+        await db_session.commit()
+        design = await _design(db_session)
+
+        node = await self._node_on(client, headers, design)
+        assert [s["service_name"] for s in node["services"]] == ["ssh"]
+        assert all(s.get("visible", True) for s in node["services"])
+        assert node["properties"][0]["visible"] is True
+
+    @pytest.mark.asyncio
+    async def test_hiding_a_service_on_one_node_leaves_the_other_alone(
+        self, client: AsyncClient, headers, db_session
+    ):
+        db_session.add(
+            InventoryDevice(
+                id="d-1",
+                ip="10.0.0.5",
+                services=[
+                    {"port": 22, "protocol": "tcp", "service_name": "ssh"},
+                    {"port": 3001, "protocol": "tcp", "service_name": "Uptime Kuma"},
+                ],
+            )
+        )
+        await db_session.commit()
+        one, two = await _design(db_session, "Net"), await _design(db_session, "Rack")
+        node_a = await self._node_on(client, headers, one)
+        node_b = await self._node_on(client, headers, two)
+
+        hidden = [
+            {"port": 22, "protocol": "tcp", "service_name": "ssh"},
+            {"port": 3001, "protocol": "tcp", "service_name": "Uptime Kuma", "visible": False},
+        ]
+        res = await client.patch(
+            f"/api/v1/nodes/{node_a['id']}", json={"services": hidden}, headers=headers
+        )
+        assert res.status_code == 200
+        assert [(s["service_name"], s.get("visible", True)) for s in res.json()["services"]] == [
+            ("ssh", True), ("Uptime Kuma", False),
+        ]
+
+        other = (await client.get(f"/api/v1/nodes/{node_b['id']}", headers=headers)).json()
+        assert [s.get("visible", True) for s in other["services"]] == [True, True]
+        # The service itself is untouched — hiding is not deleting.
+        device = await db_session.get(InventoryDevice, "d-1")
+        await db_session.refresh(device)
+        assert len(device.services) == 2
+
+    @pytest.mark.asyncio
+    async def test_the_order_is_per_node_too(self, client: AsyncClient, headers, db_session):
+        db_session.add(
+            InventoryDevice(
+                id="d-1",
+                ip="10.0.0.5",
+                properties=[
+                    {"key": "Rack", "value": "A1", "icon": None, "visible": True},
+                    {"key": "Owner", "value": "me", "icon": None, "visible": True},
+                ],
+            )
+        )
+        await db_session.commit()
+        one, two = await _design(db_session, "Net"), await _design(db_session, "Rack")
+        node_a = await self._node_on(client, headers, one)
+        node_b = await self._node_on(client, headers, two)
+
+        flipped = [
+            {"key": "Owner", "value": "me", "icon": None, "visible": True},
+            {"key": "Rack", "value": "A1", "icon": None, "visible": True},
+        ]
+        res = await client.patch(
+            f"/api/v1/nodes/{node_a['id']}", json={"properties": flipped}, headers=headers
+        )
+        assert [p["key"] for p in res.json()["properties"]] == ["Owner", "Rack"]
+
+        other = (await client.get(f"/api/v1/nodes/{node_b['id']}", headers=headers)).json()
+        assert [p["key"] for p in other["properties"]] == ["Rack", "Owner"]
+
+    @pytest.mark.asyncio
+    async def test_a_service_the_row_gains_later_stays_off_the_canvas(
+        self, client: AsyncClient, headers, db_session
+    ):
+        """The leak this column exists to stop: a scan must not redraw every canvas."""
+        db_session.add(
+            InventoryDevice(
+                id="d-1", ip="10.0.0.5",
+                services=[{"port": 22, "protocol": "tcp", "service_name": "ssh"}],
+            )
+        )
+        await db_session.commit()
+        design = await _design(db_session)
+        node = await self._node_on(client, headers, design)
+
+        device = await db_session.get(InventoryDevice, "d-1")
+        device.services = [
+            *device.services,
+            {"port": 3001, "protocol": "tcp", "service_name": "Uptime Kuma"},
+        ]
+        await db_session.commit()
+
+        after = (await client.get(f"/api/v1/nodes/{node['id']}", headers=headers)).json()
+        assert [(s["service_name"], s.get("visible", True)) for s in after["services"]] == [
+            ("ssh", True), ("Uptime Kuma", False),
+        ]
+
+    @pytest.mark.asyncio
+    async def test_removing_a_service_removes_it_from_the_device(
+        self, client: AsyncClient, headers, db_session
+    ):
+        """Delete is device-wide — hiding is what a single canvas does."""
+        db_session.add(
+            InventoryDevice(
+                id="d-1", ip="10.0.0.5",
+                services=[
+                    {"port": 22, "protocol": "tcp", "service_name": "ssh"},
+                    {"port": 3001, "protocol": "tcp", "service_name": "Uptime Kuma"},
+                ],
+            )
+        )
+        await db_session.commit()
+        one, two = await _design(db_session, "Net"), await _design(db_session, "Rack")
+        node_a = await self._node_on(client, headers, one)
+        node_b = await self._node_on(client, headers, two)
+
+        await client.patch(
+            f"/api/v1/nodes/{node_a['id']}",
+            json={"services": [{"port": 22, "protocol": "tcp", "service_name": "ssh"}]},
+            headers=headers,
+        )
+        other = (await client.get(f"/api/v1/nodes/{node_b['id']}", headers=headers)).json()
+        assert [s["service_name"] for s in other["services"]] == ["ssh"]
+
+    @pytest.mark.asyncio
+    async def test_a_canvas_save_records_the_view_even_when_no_fact_changed(
+        self, client: AsyncClient, headers, db_session
+    ):
+        """`changed_facts` guards the shared row, not the node's own view.
+
+        A canvas save reporting no edited fact is exactly what hiding a service
+        looks like from the row's side — nothing about the device changed. The
+        view still has to land, or the toggle would not survive the save.
+        """
+        db_session.add(
+            InventoryDevice(
+                id="d-1", ip="10.0.0.5",
+                services=[
+                    {"port": 22, "protocol": "tcp", "service_name": "ssh"},
+                    {"port": 3001, "protocol": "tcp", "service_name": "Uptime Kuma"},
+                ],
+            )
+        )
+        await db_session.commit()
+        design = await _design(db_session)
+        node = await self._node_on(client, headers, design)
+
+        res = await client.post(
+            "/api/v1/canvas/save",
+            json={
+                "design_id": design,
+                "nodes": [{
+                    "id": node["id"], "type": "nas", "label": "NAS", "ip": "10.0.0.5",
+                    "device_id": "d-1", "changed_facts": [], "pos_x": 10.0, "pos_y": 20.0,
+                    "services": [
+                        {"port": 3001, "protocol": "tcp", "service_name": "Uptime Kuma", "visible": False},
+                        {"port": 22, "protocol": "tcp", "service_name": "ssh"},
+                    ],
+                }],
+                "edges": [],
+                "viewport": {"x": 0, "y": 0, "zoom": 1},
+            },
+            headers=headers,
+        )
+        assert res.status_code == 200
+
+        loaded = (await client.get(f"/api/v1/canvas?design_id={design}", headers=headers)).json()
+        assert [(s["service_name"], s.get("visible", True)) for s in loaded["nodes"][0]["services"]] == [
+            ("Uptime Kuma", False), ("ssh", True),
+        ]
+        device = await db_session.get(InventoryDevice, "d-1")
+        await db_session.refresh(device)
+        assert [s["service_name"] for s in device.services] == ["ssh", "Uptime Kuma"]
+
+    @pytest.mark.asyncio
+    async def test_seeding_freezes_what_a_pre_upgrade_node_showed(self, db_session):
+        """`display_view` arrives NULL on every existing node; the seed fills it."""
+        design = await _design(db_session)
+        db_session.add(
+            InventoryDevice(
+                id="d-1", ip="10.0.0.5",
+                services=[{"port": 22, "protocol": "tcp", "service_name": "ssh"}],
+            )
+        )
+        node = _node(design, device_id="d-1")
+        db_session.add(node)
+        await db_session.commit()
+
+        assert await seed_node_views(db_session) == 1
+        await db_session.commit()
+        assert node.display_view == {
+            "services": [{"key": "22|tcp|ssh", "visible": True}],
+            "properties": [],
+        }
+        # Idempotent: a second boot finds nothing without a view.
+        assert await seed_node_views(db_session) == 0
+
+    @pytest.mark.asyncio
+    async def test_a_node_whose_device_was_deleted_does_not_keep_the_seed_alive(self, db_session):
+        """Deleting a device leaves `nodes.device_id` dangling — foreign keys are off.
+
+        Such a node can be seeded from nothing, so it must not keep matching the
+        query: it would re-open the pre-upgrade backup on every single boot and
+        log a recovery that recovers nothing.
+        """
+        design = await _design(db_session)
+        db_session.add(_node(design, device_id="d-gone"))
+        await db_session.commit()
+
+        reads = []
+
+        def drawn():
+            reads.append(1)
+            return {}
+
+        assert await seed_node_views(db_session, drawn=drawn) == 0
+        assert reads == []  # the backup was never opened
+
+    @pytest.mark.asyncio
+    async def test_seeding_leaves_furniture_alone(self, db_session):
+        design = await _design(db_session)
+        node = _node(design, type="groupRect")
+        db_session.add(node)
+        await db_session.commit()
+
+        assert await seed_node_views(db_session) == 0
+        assert node.display_view is None
+
+    @pytest.mark.asyncio
+    async def test_a_view_matching_nothing_left_on_the_row_shows_the_row(self, db_session):
+        """The row was replaced wholesale under the node — don't draw a blank node.
+
+        A view whose every key is gone tells us nothing about the list that
+        replaced it, and hiding all of it leaves a node showing no service while
+        "Show services" is on (#347). An *empty* view is a real answer and still
+        hides everything — that case is covered below.
+        """
+        device = InventoryDevice(
+            id="d-1",
+            services=[
+                {"port": 8080, "protocol": "tcp", "service_name": "HTTP Alt"},
+                {"port": 5001, "protocol": "tcp", "service_name": "Synology DSM HTTPS"},
+            ],
+        )
+        node = _node(
+            await _design(db_session),
+            device_id="d-1",
+            display_view={"services": [{"key": "9000|tcp|portainer", "visible": True}]},
+        )
+        assert [s["service_name"] for s in hydrated_node(node, device)["services"]] == [
+            "HTTP Alt", "Synology DSM HTTPS",
+        ]
+        assert all(s.get("visible", True) for s in hydrated_node(node, device)["services"])
+
+    @pytest.mark.asyncio
+    async def test_an_empty_view_still_hides_everything(self, db_session):
+        """"This canvas draws none of them" is an answer, not a missing view."""
+        device = InventoryDevice(
+            id="d-1", services=[{"port": 22, "protocol": "tcp", "service_name": "ssh"}]
+        )
+        node = _node(await _design(db_session), device_id="d-1", display_view={"services": []})
+        assert hydrated_node(node, device)["services"] == [
+            {"port": 22, "protocol": "tcp", "service_name": "ssh", "visible": False}
+        ]
+
+    @pytest.mark.asyncio
+    async def test_seeding_keeps_a_property_added_after_the_backup(self, db_session):
+        """The backup is 3.2.0-era: it cannot know a property added since.
+
+        Adding one while on 3.3.0-3.3.2 wrote it to the row, and every canvas
+        drew it. Seeding strictly from the backup would take it off all of them
+        at once (#347), so it is appended visible after what the backup places.
+        """
+        design = await _design(db_session)
+        db_session.add(
+            InventoryDevice(
+                id="d-1", ip="10.0.0.5",
+                properties=[
+                    {"key": "Rack", "value": "A", "icon": None, "visible": True},
+                    {"key": "Ports", "value": "8", "icon": None, "visible": True},
+                ],
+            )
+        )
+        node = _node(design, device_id="d-1")
+        db_session.add(node)
+        await db_session.commit()
+
+        # The backup only knew "Rack", and this canvas had it hidden.
+        drawn = {node.id: {
+            "services": [],
+            "properties": [{"key": "Rack", "value": "A", "icon": None, "visible": False}],
+        }}
+        assert await seed_node_views(db_session, drawn=lambda: drawn) == 1
+        await db_session.commit()
+
+        assert node.display_view["properties"] == [
+            {"key": "rack", "visible": False},   # recovered, still hidden here
+            {"key": "ports", "visible": True},   # added since the backup, kept
+        ]
+
+    @pytest.mark.asyncio
+    async def test_seeding_still_holds_back_a_service_found_since_the_backup(self, db_session):
+        """Services are not treated that way: a scan's find stays off the canvas."""
+        design = await _design(db_session)
+        db_session.add(
+            InventoryDevice(
+                id="d-1", ip="10.0.0.5",
+                services=[
+                    {"port": 22, "protocol": "tcp", "service_name": "ssh"},
+                    {"port": 5001, "protocol": "tcp", "service_name": "Synology DSM HTTPS"},
+                ],
+            )
+        )
+        node = _node(design, device_id="d-1")
+        db_session.add(node)
+        await db_session.commit()
+
+        drawn = {node.id: {
+            "services": [{"port": 22, "protocol": "tcp", "service_name": "ssh"}],
+            "properties": [],
+        }}
+        assert await seed_node_views(db_session, drawn=lambda: drawn) == 1
+        await db_session.commit()
+
+        assert node.display_view["services"] == [{"key": "22|tcp|ssh", "visible": True}]
+
+    @pytest.mark.asyncio
+    async def test_a_node_without_a_view_still_shows_everything(self, db_session):
+        """No view — furniture, or a node an older version linked — is not "hide all"."""
+        device = InventoryDevice(
+            id="d-1", services=[{"port": 22, "protocol": "tcp", "service_name": "ssh"}]
+        )
+        node = _node(await _design(db_session), device_id="d-1")
+        assert hydrated_node(node, device)["services"] == [
+            {"port": 22, "protocol": "tcp", "service_name": "ssh"}
+        ]

backend/tests/test_mqtt_common.py

@@ -2,13 +2,16 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 import ssl
 from unittest.mock import patch
 
 import pytest
 
+from app.core.config import settings
 from app.services.mqtt_common import (
+    _RESPONSE_TIMEOUT,
     _build_tls_context,
     _sanitize_mqtt_error,
     request_response,
@@ -181,3 +184,100 @@ async def test_test_connection_failure() -> None:
         mock_aiomqtt.MqttError = Exception
         with pytest.raises(ConnectionError):
             await _test_connection("bad", 1883)
+
+
+# ---------------------------------------------------------------------------
+# Response timeout — configurable via MQTT_RESPONSE_TIMEOUT (issue #380)
+# ---------------------------------------------------------------------------
+
+
+class _SilentClient:
+    """An MQTT client that connects but never delivers the response message."""
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_):
+        pass
+
+    async def subscribe(self, *_a, **_kw) -> None:
+        pass
+
+    async def publish(self, *_a, **_kw) -> None:
+        pass
+
+    @property
+    def messages(self):
+        async def _never():
+            await asyncio.Event().wait()
+            yield  # pragma: no cover
+
+        return _never()
+
+
+class _NeverMqttError(Exception):
+    """Stand-in for aiomqtt.MqttError that no test path actually raises."""
+
+
+async def _round_trip(**kwargs):
+    return await request_response(
+        mqtt_host="host",
+        mqtt_port=1883,
+        request_topic="req",
+        response_topic="res",
+        request_payload={},
+        **kwargs,
+    )
+
+
+@pytest.mark.asyncio
+async def test_request_response_uses_settings_timeout(monkeypatch) -> None:
+    monkeypatch.setattr(settings, "mqtt_response_timeout", 0.01)
+
+    with patch("app.services.mqtt_common.aiomqtt") as mock_aiomqtt:
+        mock_aiomqtt.Client.return_value = _SilentClient()
+        mock_aiomqtt.MqttError = _NeverMqttError
+
+        with pytest.raises(TimeoutError) as ei:
+            await _round_trip()
+
+    msg = str(ei.value)
+    assert "0.01s" in msg
+    assert "MQTT_RESPONSE_TIMEOUT" in msg
+
+
+@pytest.mark.asyncio
+async def test_request_response_explicit_timeout_overrides_settings(monkeypatch) -> None:
+    monkeypatch.setattr(settings, "mqtt_response_timeout", 999)
+
+    with patch("app.services.mqtt_common.aiomqtt") as mock_aiomqtt:
+        mock_aiomqtt.Client.return_value = _SilentClient()
+        mock_aiomqtt.MqttError = _NeverMqttError
+
+        with pytest.raises(TimeoutError) as ei:
+            await _round_trip(response_timeout=0.01)
+
+    assert "0.01s" in str(ei.value)
+
+
+@pytest.mark.asyncio
+async def test_request_response_non_positive_setting_falls_back(monkeypatch) -> None:
+    """A misconfigured 0 must not mean 'give up immediately'."""
+    monkeypatch.setattr(settings, "mqtt_response_timeout", 0)
+    captured: dict[str, float] = {}
+
+    async def _fake_wait_for(awaitable, timeout):
+        captured["timeout"] = timeout
+        awaitable.close()
+        raise asyncio.TimeoutError
+
+    with patch("app.services.mqtt_common.aiomqtt") as mock_aiomqtt:
+        mock_aiomqtt.Client.return_value = _SilentClient()
+        mock_aiomqtt.MqttError = _NeverMqttError
+        with (
+            patch("app.services.mqtt_common.asyncio.wait_for", _fake_wait_for),
+            pytest.raises(TimeoutError),
+        ):
+            await _round_trip()
+
+    assert captured["timeout"] == _RESPONSE_TIMEOUT

backend/tests/test_node_dedupe.py

@@ -134,6 +134,30 @@ async def test_repoints_child_parent(db_session):
     assert child.parent_id == keep.id
 
 
+@pytest.mark.asyncio
+async def test_canonical_nested_under_its_own_duplicate_is_detached(db_session):
+    """#370 — re-pointing the canonical node made it its own parent.
+
+    The canonical node had been nested under one of its duplicates, so the
+    blanket re-point wrote `parent_id = id` and froze it on the canvas.
+    """
+    d = await _design(db_session)
+    device = await _device(db_session, ieee="0xFFF")
+    keep = Node(label="Host", type="proxmox", design_id=d.id, device_id=device.id)
+    db_session.add(keep)
+    await db_session.flush()
+    dup = Node(label="Host", type="proxmox", design_id=d.id, device_id=device.id)
+    db_session.add(dup)
+    await db_session.flush()
+    # The oldest node is the one that survives, and it points at the newer twin.
+    keep.parent_id = dup.id
+    await db_session.flush()
+
+    await dedupe_nodes_by_device(db_session)
+    await db_session.refresh(keep)
+    assert keep.parent_id is None
+
+
 @pytest.mark.asyncio
 async def test_idempotent_noop_when_unique(db_session):
     d = await _design(db_session)

backend/tests/test_nodes.py

@@ -403,3 +403,87 @@ async def test_list_nodes_without_label_param_returns_all(client: AsyncClient, h
     res = await client.get("/api/v1/nodes", headers=headers)
     assert res.status_code == 200
     assert len(res.json()) == 3
+
+
+# ── self-parent guard (#370) ─────────────────────────────────────────────────
+
+async def test_update_node_ignores_a_parent_id_pointing_at_itself(client: AsyncClient, headers: dict):
+    create = await client.post(
+        "/api/v1/nodes", json={"type": "lxc", "label": "pihole", "status": "unknown"}, headers=headers
+    )
+    node_id = create.json()["id"]
+
+    res = await client.patch(
+        f"/api/v1/nodes/{node_id}", json={"parent_id": node_id, "label": "renamed"}, headers=headers
+    )
+
+    assert res.status_code == 200
+    assert res.json()["parent_id"] is None
+    # The key is dropped, not the whole edit.
+    assert res.json()["label"] == "renamed"
+
+
+async def test_update_node_self_parent_leaves_a_real_parent_alone(client: AsyncClient, headers: dict):
+    host = await client.post(
+        "/api/v1/nodes",
+        json={"type": "proxmox", "label": "pve", "status": "unknown", "container_mode": True},
+        headers=headers,
+    )
+    host_id = host.json()["id"]
+    child = await client.post(
+        "/api/v1/nodes",
+        json={"type": "lxc", "label": "pihole", "status": "unknown", "parent_id": host_id},
+        headers=headers,
+    )
+    child_id = child.json()["id"]
+
+    res = await client.patch(f"/api/v1/nodes/{child_id}", json={"parent_id": child_id}, headers=headers)
+
+    assert res.status_code == 200
+    assert res.json()["parent_id"] == host_id
+
+
+# ── furniture descriptions ───────────────────────────────────────────────────
+
+async def test_create_and_update_a_group_description(client: AsyncClient, headers: dict):
+    create = await client.post(
+        "/api/v1/nodes",
+        json={"type": "group", "label": "Cluster", "description": "The three Proxmox boxes."},
+        headers=headers,
+    )
+    assert create.status_code == 201
+    assert create.json()["description"] == "The three Proxmox boxes."
+    node_id = create.json()["id"]
+
+    res = await client.patch(f"/api/v1/nodes/{node_id}", json={"description": "Now four."}, headers=headers)
+    assert res.status_code == 200
+    assert res.json()["description"] == "Now four."
+    assert (await client.get(f"/api/v1/nodes/{node_id}", headers=headers)).json()["description"] == "Now four."
+
+
+async def test_update_a_zone_description_leaves_the_label_alone(client: AsyncClient, headers: dict):
+    create = await client.post("/api/v1/nodes", json={"type": "groupRect", "label": "Garage"}, headers=headers)
+    node_id = create.json()["id"]
+
+    res = await client.patch(f"/api/v1/nodes/{node_id}", json={"description": "Behind the door."}, headers=headers)
+    assert res.json()["label"] == "Garage"
+    assert res.json()["description"] == "Behind the door."
+
+
+async def test_a_device_node_never_keeps_a_description(client: AsyncClient, headers: dict):
+    # `description` is furniture-only: a node that draws a device writes what it
+    # is for to the inventory row, as `notes`.
+    create = await client.post(
+        "/api/v1/nodes",
+        json={"type": "nas", "label": "nas-01", "ip": "192.168.1.20", "description": "Not here."},
+        headers=headers,
+    )
+    assert create.json()["description"] is None
+
+    res = await client.patch(
+        f"/api/v1/nodes/{create.json()['id']}",
+        json={"description": "Still not here.", "notes": "Backs up nightly."},
+        headers=headers,
+    )
+    assert res.json()["description"] is None
+    assert res.json()["notes"] == "Backs up nightly."

backend/tests/test_proxmox_router.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import uuid
+from datetime import datetime, timezone
 from types import SimpleNamespace
 from unittest.mock import AsyncMock, MagicMock, patch
 
@@ -39,14 +40,17 @@ def _host_node() -> dict:
     }
 
 
-def _guest_node(vmid: int, ip: str | None, status: str = "online", mac: str | None = None) -> dict:
+def _guest_node(
+    vmid: int, ip: str | None, status: str = "online", mac: str | None = None,
+    host: str = "pve1",
+) -> dict:
     return {
-        "id": f"pve-pve1-{vmid}", "label": f"vm{vmid}", "type": "vm",
-        "ieee_address": f"pve-pve1-{vmid}", "hostname": f"vm{vmid}", "ip": ip,
+        "id": f"pve-{host}-{vmid}", "label": f"vm{vmid}", "type": "vm",
+        "ieee_address": f"pve-{host}-{vmid}", "hostname": f"vm{vmid}", "ip": ip,
         "mac": mac,
         "status": status, "cpu_count": 2, "ram_gb": 4.0, "disk_gb": 32.0,
         "vendor": "Proxmox VE", "model": "QEMU", "vmid": vmid,
-        "parent_ieee": "pve-node-pve1",
+        "parent_ieee": f"pve-node-{host}",
     }
 
 
@@ -273,6 +277,134 @@ async def test_persist_merges_pending_scan_row_by_mac(db_session) -> None:
     assert set(row.discovery_sources) == {"arp", "proxmox"}  # shows in both filters
 
 
+@pytest.mark.asyncio
+async def test_persist_never_overwrites_another_guest_row_on_a_shared_ip(db_session) -> None:
+    # Issue #419: two guests report the same address (duplicate lease, re-used
+    # DHCP, or a container bridge address the agent lists first). Importing 812
+    # used to match 802's row on that IP and overwrite its hostname and specs,
+    # leaving no row for the original guest.
+    db_session.add(InventoryDevice(
+        id=str(uuid.uuid4()), ieee_address="pve-pve1-802", ip="10.0.0.5",
+        hostname="vm802", suggested_type="vm", status="pending",
+        cpu_count=8, ram_gb=32.0, disk_gb=500.0,
+        discovery_source="proxmox", discovery_sources=["proxmox"],
+    ))
+    await db_session.commit()
+
+    await _persist_pending_import(db_session, [_guest_node(812, "10.0.0.5")], [])
+
+    rows = (await db_session.execute(select(InventoryDevice))).scalars().all()
+    assert len(rows) == 2                                  # 802 still its own row
+    kept = next(r for r in rows if r.ieee_address == "pve-pve1-802")
+    assert kept.hostname == "vm802"                        # not stomped by 812
+    assert (kept.cpu_count, kept.ram_gb, kept.disk_gb) == (8, 32.0, 500.0)
+    added = next(r for r in rows if r.ieee_address == "pve-pve1-812")
+    assert added.hostname == "vm812"
+
+
+@pytest.mark.asyncio
+async def test_persist_matches_ieee_before_a_shared_ip(db_session) -> None:
+    # Both rows exist and share an IP. The guest's own ieee wins over the other
+    # row's matching address, whichever order the database yields them in.
+    for vmid, hostname in ((802, "vm802"), (812, "stale")):
+        db_session.add(InventoryDevice(
+            id=str(uuid.uuid4()), ieee_address=f"pve-pve1-{vmid}", ip="10.0.0.5",
+            hostname=hostname, suggested_type="vm", status="pending",
+            discovery_source="proxmox", discovery_sources=["proxmox"],
+        ))
+    await db_session.commit()
+
+    await _persist_pending_import(db_session, [_guest_node(812, "10.0.0.5")], [])
+
+    rows = (await db_session.execute(select(InventoryDevice))).scalars().all()
+    assert len(rows) == 2
+    assert next(r for r in rows if r.ieee_address == "pve-pve1-802").hostname == "vm802"
+    assert next(r for r in rows if r.ieee_address == "pve-pve1-812").hostname == "vm812"
+
+
+@pytest.mark.asyncio
+async def test_persist_merges_the_oldest_scan_row_when_two_share_an_ip(db_session) -> None:
+    # Unclaimed scan rows on one address: pick deterministically (oldest), so a
+    # re-import lands on the same row instead of whichever comes back first.
+    for offset, mac in ((2, "aa:bb:cc:00:00:01"), (1, "aa:bb:cc:00:00:02")):
+        db_session.add(InventoryDevice(
+            id=str(uuid.uuid4()), ip="10.0.0.5", mac=mac,
+            suggested_type="generic", status="pending",
+            discovered_at=datetime(2026, 1, offset, tzinfo=timezone.utc),
+            discovery_source="arp", discovery_sources=["arp"],
+        ))
+    await db_session.commit()
+
+    for _ in range(2):
+        await _persist_pending_import(db_session, [_guest_node(101, "10.0.0.5")], [])
+
+    rows = (await db_session.execute(select(InventoryDevice))).scalars().all()
+    assert len(rows) == 2                                  # merged, never a third
+    merged = next(r for r in rows if r.ieee_address == "pve-pve1-101")
+    assert merged.mac == "aa:bb:cc:00:00:02"               # the older row
+
+
+@pytest.mark.asyncio
+async def test_persist_merges_a_guest_that_moved_to_another_host(db_session) -> None:
+    # The synthetic ieee embeds the host name, so a live migration or a node
+    # rename changes it for what is the same guest. The NIC MAC survives both:
+    # merge and re-point the row, rather than filing a new device and orphaning
+    # the old row (which would then never resolve as a host→guest link end).
+    await _persist_pending_import(
+        db_session, [_guest_node(802, "10.0.0.5", mac="bc:24:11:aa:bb:cc")], []
+    )
+    row = (await db_session.execute(select(InventoryDevice))).scalars().one()
+    row.status = "approved"
+    await db_session.commit()
+
+    await _persist_pending_import(
+        db_session,
+        [_guest_node(802, "10.0.0.5", mac="bc:24:11:aa:bb:cc", host="pve2")],
+        [],
+    )
+
+    rows = (await db_session.execute(select(InventoryDevice))).scalars().all()
+    assert len(rows) == 1                                  # no duplicate, no orphan
+    assert rows[0].ieee_address == "pve-pve2-802"          # re-pointed to the new host
+
+
+@pytest.mark.asyncio
+async def test_persist_never_repoints_a_mesh_ieee(db_session) -> None:
+    # A zigbee/zwave ieee is a real hardware address. A Proxmox import that
+    # merges into such a row by MAC must not overwrite it.
+    db_session.add(InventoryDevice(
+        id=str(uuid.uuid4()), ieee_address="0x00124b0022a1b2c3",
+        mac="bc:24:11:aa:bb:cc", suggested_type="zigbee_device", status="pending",
+        discovery_source="zigbee", discovery_sources=["zigbee"],
+    ))
+    await db_session.commit()
+
+    await _persist_pending_import(
+        db_session, [_guest_node(101, None, mac="bc:24:11:aa:bb:cc")], []
+    )
+
+    rows = (await db_session.execute(select(InventoryDevice))).scalars().all()
+    assert len(rows) == 1
+    assert rows[0].ieee_address == "0x00124b0022a1b2c3"
+
+
+@pytest.mark.asyncio
+async def test_persist_merges_two_guests_that_share_a_nic_mac(db_session) -> None:
+    # Accepted trade-off of matching on MAC: two guests configured with the same
+    # NIC MAC collapse into one row. That is a misconfiguration which already
+    # breaks their networking, and the alternative — excluding claimed rows from
+    # the MAC fallback — orphans every migrated guest. Shared *IPs* stay split;
+    # see test_persist_never_overwrites_another_guest_row_on_a_shared_ip.
+    nodes = [
+        _guest_node(802, "10.0.0.5", mac="bc:24:11:aa:bb:cc"),
+        _guest_node(812, "10.0.0.6", mac="bc:24:11:aa:bb:cc"),
+    ]
+    await _persist_pending_import(db_session, nodes, [])
+
+    rows = (await db_session.execute(select(InventoryDevice))).scalars().all()
+    assert len(rows) == 1
+
+
 @pytest.mark.asyncio
 async def test_persist_preserves_ip_tag_for_legacy_null_source_row(db_session) -> None:
     # Legacy inventory row from an old IP scan, before discovery_source(s) were
@@ -509,3 +641,62 @@ async def test_persist_never_deletes(db_session) -> None:
     rows = (await db_session.execute(select(InventoryDevice))).scalars().all()
     ieees = {r.ieee_address for r in rows}
     assert "pve-pve1-101" in ieees and "pve-pve1-202" in ieees
+
+
+@pytest.mark.asyncio
+async def test_canvas_import_also_lands_in_device_inventory(
+    client: AsyncClient, headers: dict, db_session
+) -> None:
+    """A canvas import is an import: the guests reach the Device Inventory too."""
+    nodes = [_host_node(), _guest_node(101, "10.0.0.5")]
+    with patch("app.api.routes.proxmox.fetch_proxmox_inventory") as mock_fetch:
+        mock_fetch.return_value = (nodes, [])
+        res = await client.post(
+            "/api/v1/proxmox/import",
+            json={
+                "host": "pve1",
+                "token_id": "root@pam!t",
+                "token_secret": "s",
+            },
+            headers=headers,
+        )
+    assert res.status_code == 200, res.text
+
+    rows = (
+        await db_session.execute(
+            select(InventoryDevice).where(InventoryDevice.discovery_source == "proxmox")
+        )
+    ).scalars().all()
+    by_ieee = {r.ieee_address: r for r in rows}
+    assert set(by_ieee) == {"pve-node-pve1", "pve-pve1-101"}
+    for node in res.json()["nodes"]:
+        assert node["device_id"] == by_ieee[node["ieee_address"]].id
+
+
+@pytest.mark.asyncio
+async def test_canvas_import_points_at_the_row_matched_by_ip(
+    client: AsyncClient, headers: dict, db_session
+) -> None:
+    """A guest merged into a scanned row by IP draws that row, not a new one."""
+    scanned = InventoryDevice(
+        id=str(uuid.uuid4()), ip="10.0.0.5", suggested_type="generic",
+        status="pending", discovery_source="arp", discovery_sources=["arp"],
+    )
+    db_session.add(scanned)
+    await db_session.commit()
+
+    with patch("app.api.routes.proxmox.fetch_proxmox_inventory") as mock_fetch:
+        mock_fetch.return_value = ([_guest_node(101, "10.0.0.5")], [])
+        res = await client.post(
+            "/api/v1/proxmox/import",
+            json={"host": "pve1", "token_id": "root@pam!t", "token_secret": "s"},
+            headers=headers,
+        )
+    assert res.status_code == 200, res.text
+    assert res.json()["nodes"][0]["device_id"] == scanned.id
+    rows = (
+        await db_session.execute(
+            select(InventoryDevice).where(InventoryDevice.ip == "10.0.0.5")
+        )
+    ).scalars().all()
+    assert len(rows) == 1

backend/tests/test_proxmox_service.py

@@ -30,6 +30,28 @@ def test_extract_qemu_ip_skips_loopback() -> None:
     assert svc._extract_qemu_ip({"result": []}) is None
 
 
+def test_extract_qemu_ip_prefers_the_configured_nic() -> None:
+    # A guest running k8s/Docker: the agent lists the CNI bridge first, and that
+    # address repeats across guests. Pick the interface holding the NIC MAC from
+    # /config instead (issue #419).
+    payload = {
+        "result": [
+            {
+                "name": "cni0", "hardware-address": "0a:58:0a:2a:00:01",
+                "ip-addresses": [{"ip-address-type": "ipv4", "ip-address": "10.42.0.1"}],
+            },
+            {
+                "name": "eth0", "hardware-address": "BC:24:11:AA:BB:CC",
+                "ip-addresses": [{"ip-address-type": "ipv4", "ip-address": "192.168.1.20"}],
+            },
+        ]
+    }
+    assert svc._extract_qemu_ip(payload, "bc:24:11:aa:bb:cc") == "192.168.1.20"
+    # No MAC known, or none matching: first non-loopback IPv4, as before.
+    assert svc._extract_qemu_ip(payload) == "10.42.0.1"
+    assert svc._extract_qemu_ip(payload, "de:ad:be:ef:00:00") == "10.42.0.1"
+
+
 def test_extract_lxc_ip_parses_net0_static() -> None:
     cfg = {"net0": "name=eth0,bridge=vmbr0,ip=192.168.1.30/24,gw=192.168.1.1"}
     assert svc._extract_lxc_ip(cfg) == "192.168.1.30"

backend/tests/test_racks.py

@@ -93,6 +93,210 @@ class TestDesignType:
         assert res.status_code == 422
 
 
+class TestDeviceRackModel:
+    """The inventory row owns the front panel; the mount only places it.
+
+    A device wears the same faceplate, size, colour and ports in every rack, so a
+    save writes them onto `device_inventory` and a load reads them back out.
+    """
+
+    async def _mounted(self, client: AsyncClient, headers: dict, db_session, **device) -> str:
+        design_id = await _design(client, headers)
+        db_session.add(InventoryDevice(id="inv-sw", ip="192.168.1.10", suggested_type="switch"))
+        await db_session.commit()
+        state = _state(design_id, cables=[])
+        state["devices"] = [{**state["devices"][0], "device_id": "inv-sw", **device}]
+        res = await client.post("/api/v1/racks/save", json=state, headers=headers)
+        assert res.status_code == 200, res.text
+        return design_id
+
+    async def test_writes_the_mount_panel_onto_the_inventory_row(
+        self, client: AsyncClient, headers, db_session
+    ):
+        await self._mounted(client, headers, db_session, color="#ff6e00")
+
+        entry = await db_session.get(InventoryDevice, "inv-sw")
+        await db_session.refresh(entry)
+        assert entry.rack_faceplate_id == "switch-24"
+        assert entry.rack_u_height == 1
+        assert entry.rack_col_span == 12
+        assert entry.rack_color == "#ff6e00"
+        assert entry.rack_ports == [{"id": "p1", "label": "1", "type": "rj45", "x": 0.4, "y": 0.5}]
+
+    async def test_leaves_the_inventory_alone_for_an_accessory(
+        self, client: AsyncClient, headers, db_session
+    ):
+        design_id = await _design(client, headers)
+        db_session.add(InventoryDevice(id="inv-untouched", ip="192.168.1.11"))
+        await db_session.commit()
+        state = _state(design_id, cables=[])
+        state["devices"] = [{**state["devices"][0], "faceplate_id": "shelf-1u", "ports": []}]
+        await client.post("/api/v1/racks/save", json=state, headers=headers)
+
+        entry = await db_session.get(InventoryDevice, "inv-untouched")
+        await db_session.refresh(entry)
+        assert entry.rack_faceplate_id is None
+
+    async def test_load_serves_the_inventory_panel_over_the_mount_copy(
+        self, client: AsyncClient, headers, db_session
+    ):
+        design_id = await self._mounted(client, headers, db_session)
+        # Another rack modelled the same device differently since this mount was
+        # written: the row wins, ports included.
+        entry = await db_session.get(InventoryDevice, "inv-sw")
+        entry.rack_faceplate_id = "switch-48"
+        entry.rack_color = "#a855f7"
+        entry.rack_ports = [{"id": "px", "label": "uplink", "type": "sfp+", "x": 0.9, "y": 0.4}]
+        await db_session.commit()
+
+        device = (
+            await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)
+        ).json()["devices"][0]
+        assert device["faceplate_id"] == "switch-48"
+        assert device["color"] == "#a855f7"
+        assert [p["id"] for p in device["ports"]] == ["px"]
+
+    async def test_load_keeps_a_size_that_no_longer_fits_this_rack(
+        self, client: AsyncClient, headers, db_session
+    ):
+        # The mount sits at U 10 of a 12U rack. Grown to 4U elsewhere, it would
+        # now run past the top rail — geometry is global, a rack is not.
+        design_id = await self._mounted(client, headers, db_session)
+        entry = await db_session.get(InventoryDevice, "inv-sw")
+        entry.rack_u_height = 4
+        entry.rack_col_span = 12
+        await db_session.commit()
+
+        device = (
+            await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)
+        ).json()["devices"][0]
+        assert device["u_height"] == 1
+        # The plate itself cannot overflow a rail, so it still comes from the row.
+        assert device["faceplate_id"] == "switch-24"
+
+    async def test_load_keeps_a_width_that_overruns_the_column_grid(
+        self, client: AsyncClient, headers, db_session
+    ):
+        design_id = await self._mounted(client, headers, db_session, col_start=6, col_span=6)
+        entry = await db_session.get(InventoryDevice, "inv-sw")
+        entry.rack_col_span = 12
+        await db_session.commit()
+
+        device = (
+            await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)
+        ).json()["devices"][0]
+        assert device["col_span"] == 6
+
+    async def test_the_tray_offers_the_saved_panel(
+        self, client: AsyncClient, headers, db_session
+    ):
+        design_id = await self._mounted(client, headers, db_session, color="#ff6e00")
+
+        items = (
+            await client.get(f"/api/v1/racks/inventory?design_id={design_id}", headers=headers)
+        ).json()["items"]
+        item = next(i for i in items if i["id"] == "inv-sw")
+        assert item["rack_faceplate_id"] == "switch-24"
+        assert item["rack_color"] == "#ff6e00"
+        assert [p["id"] for p in item["rack_ports"]] == ["p1"]
+
+    async def test_a_never_racked_device_reports_no_panel(
+        self, client: AsyncClient, headers, db_session
+    ):
+        design_id = await _design(client, headers)
+        db_session.add(InventoryDevice(id="inv-fresh", ip="192.168.1.12", suggested_type="nas"))
+        await db_session.commit()
+
+        items = (
+            await client.get(f"/api/v1/racks/inventory?design_id={design_id}", headers=headers)
+        ).json()["items"]
+        item = next(i for i in items if i["id"] == "inv-fresh")
+        assert item["rack_faceplate_id"] is None
+        assert item["rack_ports"] == []
+
+    async def test_a_clamped_size_is_not_written_back_over_the_model(
+        self, client: AsyncClient, headers, db_session
+    ):
+        # The mount is served 1U because 4U no longer fits above U 10. Saving the
+        # canvas then echoes that 1U back — and must not shrink the device in the
+        # rack where it really is 4U.
+        design_id = await self._mounted(client, headers, db_session)
+        entry = await db_session.get(InventoryDevice, "inv-sw")
+        entry.rack_u_height = 4
+        entry.rack_col_span = 12
+        await db_session.commit()
+
+        served = (
+            await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)
+        ).json()["devices"][0]
+        assert served["u_height"] == 1
+        state = _state(design_id, cables=[])
+        state["devices"] = [{**state["devices"][0], "device_id": "inv-sw", "u_height": 1}]
+        res = await client.post("/api/v1/racks/save", json=state, headers=headers)
+        assert res.status_code == 200, res.text
+
+        await db_session.refresh(entry)
+        assert entry.rack_u_height == 4
+
+    async def test_a_real_resize_still_reaches_the_model(
+        self, client: AsyncClient, headers, db_session
+    ):
+        design_id = await self._mounted(client, headers, db_session)
+        entry = await db_session.get(InventoryDevice, "inv-sw")
+        entry.rack_u_height = 1
+        await db_session.commit()
+
+        state = _state(design_id, cables=[])
+        state["devices"] = [
+            {**state["devices"][0], "device_id": "inv-sw", "u_start": 8, "u_height": 3}
+        ]
+        res = await client.post("/api/v1/racks/save", json=state, headers=headers)
+        assert res.status_code == 200, res.text
+
+        await db_session.refresh(entry)
+        assert entry.rack_u_height == 3
+
+    async def test_load_does_not_inflate_a_mount_onto_its_neighbour(
+        self, client: AsyncClient, headers, db_session
+    ):
+        # A 4U model fits the rails at U 1 of a 12U rack, but another device sits
+        # at U 2. Two plates drawn on the same U is not a state the canvas can
+        # produce, so the load must not invent it.
+        design_id = await _design(client, headers)
+        db_session.add(InventoryDevice(id="inv-sw", ip="192.168.1.10", suggested_type="switch"))
+        await db_session.commit()
+        state = _state(design_id, cables=[])
+        state["devices"] = [
+            {**state["devices"][0], "device_id": "inv-sw", "u_start": 1, "u_height": 1},
+            {**state["devices"][1], "u_start": 2, "u_height": 1},
+        ]
+        assert (
+            await client.post("/api/v1/racks/save", json=state, headers=headers)
+        ).status_code == 200
+        entry = await db_session.get(InventoryDevice, "inv-sw")
+        entry.rack_u_height = 4
+        await db_session.commit()
+
+        devices = (
+            await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)
+        ).json()["devices"]
+        assert next(d for d in devices if d["id"] == "dev-sw")["u_height"] == 1
+
+    async def test_load_inflates_a_mount_that_has_the_room(
+        self, client: AsyncClient, headers, db_session
+    ):
+        design_id = await self._mounted(client, headers, db_session, u_start=1, u_height=1)
+        entry = await db_session.get(InventoryDevice, "inv-sw")
+        entry.rack_u_height = 4
+        await db_session.commit()
+
+        device = (
+            await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)
+        ).json()["devices"][0]
+        assert device["u_height"] == 4
+
+
+
 class TestSaveAndLoad:
     async def test_round_trips_the_full_state(self, client: AsyncClient, headers):
         design_id = await _design(client, headers)
@@ -108,6 +312,35 @@ class TestSaveAndLoad:
         assert loaded["cables"][0]["from_port_id"] == "p1"
         assert loaded["viewport"] == {"x": 10, "y": 20, "zoom": 1.5}
 
+    async def test_round_trips_the_port_visibility_override(
+        self, client: AsyncClient, headers
+    ):
+        # When a plate draws its sockets is a per-mount display choice, so it
+        # rides on the mount and not on the inventory row behind it.
+        design_id = await _design(client, headers)
+        state = _state(design_id, cables=[])
+        state["devices"][0]["port_visibility"] = "hover"
+        state["devices"][1]["port_visibility"] = "always"
+        res = await client.post("/api/v1/racks/save", json=state, headers=headers)
+        assert res.status_code == 200, res.text
+
+        loaded = (await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)).json()
+        by_id = {d["id"]: d for d in loaded["devices"]}
+        assert by_id["dev-sw"]["port_visibility"] == "hover"
+        assert by_id["dev-nas"]["port_visibility"] == "always"
+
+    async def test_defaults_port_visibility_to_auto(self, client: AsyncClient, headers):
+        # A payload from before the field existed — and any unknown value —
+        # keeps the old behaviour: the faceplate decides.
+        design_id = await _design(client, headers)
+        state = _state(design_id, cables=[])
+        state["devices"][1]["port_visibility"] = "sometimes"
+        res = await client.post("/api/v1/racks/save", json=state, headers=headers)
+        assert res.status_code == 200, res.text
+
+        loaded = (await client.get(f"/api/v1/racks?design_id={design_id}", headers=headers)).json()
+        assert {d["port_visibility"] for d in loaded["devices"]} == {"auto"}
+
     async def test_keeps_a_mount_that_follows_its_node_check(
         self, client: AsyncClient, headers
     ):
@@ -802,3 +1035,35 @@ class TestDesignLifecycle:
         copied_ids = {d["id"] for d in loaded["devices"]}
         assert loaded["cables"][0]["from_device_id"] in copied_ids
         assert loaded["cables"][0]["to_device_id"] in copied_ids
+
+
+class TestOverlappingMounts:
+    async def test_rejects_two_mounts_claiming_the_same_u(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        state = _state(design_id, cables=[])
+        state["devices"][1]["u_start"] = 10  # straight onto dev-sw
+
+        res = await client.post("/api/v1/racks/save", json=state, headers=headers)
+        assert res.status_code == 422
+        assert "overlap" in res.text
+
+    async def test_accepts_two_mounts_sharing_a_u_side_by_side(
+        self, client: AsyncClient, headers
+    ):
+        # Half-width plates on the same U are the whole point of the column grid.
+        design_id = await _design(client, headers)
+        state = _state(design_id, cables=[])
+        state["devices"][0].update(col_start=0, col_span=6)
+        state["devices"][1].update(u_start=10, u_height=1, col_start=6, col_span=6)
+
+        res = await client.post("/api/v1/racks/save", json=state, headers=headers)
+        assert res.status_code == 200, res.text
+
+    async def test_lets_two_racks_use_the_same_u(self, client: AsyncClient, headers):
+        design_id = await _design(client, headers)
+        state = _state(design_id, cables=[])
+        state["racks"].append({**state["racks"][0], "id": "rack-2", "name": "Second"})
+        state["devices"][1].update(rack_id="rack-2", u_start=10, u_height=1)
+
+        res = await client.post("/api/v1/racks/save", json=state, headers=headers)
+        assert res.status_code == 200, res.text

backend/tests/test_scan_proxmox_children.py

@@ -0,0 +1,103 @@
+"""GET /api/v1/scan/pending/{id}/proxmox-children.
+
+Resolves the host -> guest links the Proxmox import records into the inventory
+rows the UI needs to offer "add the guests too" when a host reaches a canvas.
+"""
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import InventoryDevice, InventoryDeviceLink
+
+
+async def _seed(db: AsyncSession) -> dict[str, str]:
+    host = InventoryDevice(
+        ieee_address="pve-node-pve1", hostname="pve1", suggested_type="proxmox", status="pending"
+    )
+    vm = InventoryDevice(
+        ieee_address="pve-pve1-101", hostname="web", suggested_type="vm", status="pending"
+    )
+    lxc = InventoryDevice(
+        ieee_address="pve-pve1-102", hostname="dns", suggested_type="lxc", status="pending"
+    )
+    other = InventoryDevice(ip="192.168.1.9", hostname="nas", status="pending")
+    db.add_all([host, vm, lxc, other])
+    await db.flush()
+    db.add_all([
+        InventoryDeviceLink(
+            source_ieee="pve-node-pve1", target_ieee="pve-pve1-101", discovery_source="proxmox"
+        ),
+        InventoryDeviceLink(
+            source_ieee="pve-node-pve1", target_ieee="pve-pve1-102", discovery_source="proxmox"
+        ),
+    ])
+    await db.commit()
+    return {"host": host.id, "vm": vm.id, "lxc": lxc.id, "other": other.id}
+
+
+@pytest.mark.asyncio
+async def test_returns_the_guests_of_a_host(client: AsyncClient, headers, db_session):
+    ids = await _seed(db_session)
+    res = await client.get(f"/api/v1/scan/pending/{ids['host']}/proxmox-children", headers=headers)
+    assert res.status_code == 200
+    assert {d["id"] for d in res.json()} == {ids["vm"], ids["lxc"]}
+
+
+@pytest.mark.asyncio
+async def test_empty_for_a_guest(client: AsyncClient, headers, db_session):
+    ids = await _seed(db_session)
+    res = await client.get(f"/api/v1/scan/pending/{ids['vm']}/proxmox-children", headers=headers)
+    assert res.status_code == 200
+    assert res.json() == []
+
+
+@pytest.mark.asyncio
+async def test_empty_for_a_device_with_no_ieee(client: AsyncClient, headers, db_session):
+    ids = await _seed(db_session)
+    res = await client.get(f"/api/v1/scan/pending/{ids['other']}/proxmox-children", headers=headers)
+    assert res.status_code == 200
+    assert res.json() == []
+
+
+@pytest.mark.asyncio
+async def test_skips_hidden_guests(client: AsyncClient, headers, db_session):
+    ids = await _seed(db_session)
+    lxc = await db_session.get(InventoryDevice, ids["lxc"])
+    lxc.status = "hidden"
+    await db_session.commit()
+    res = await client.get(f"/api/v1/scan/pending/{ids['host']}/proxmox-children", headers=headers)
+    assert [d["id"] for d in res.json()] == [ids["vm"]]
+
+
+@pytest.mark.asyncio
+async def test_ignores_cluster_links(client: AsyncClient, headers, db_session):
+    """A host↔host cluster link is not a parent/child relation."""
+    ids = await _seed(db_session)
+    peer = InventoryDevice(
+        ieee_address="pve-node-pve2", hostname="pve2", suggested_type="proxmox", status="pending"
+    )
+    db_session.add(peer)
+    db_session.add(
+        InventoryDeviceLink(
+            source_ieee="pve-node-pve1",
+            target_ieee="pve-node-pve2",
+            discovery_source="proxmox_cluster",
+        )
+    )
+    await db_session.commit()
+    res = await client.get(f"/api/v1/scan/pending/{ids['host']}/proxmox-children", headers=headers)
+    assert {d["id"] for d in res.json()} == {ids["vm"], ids["lxc"]}
+
+
+@pytest.mark.asyncio
+async def test_404_for_an_unknown_device(client: AsyncClient, headers):
+    res = await client.get("/api/v1/scan/pending/nope/proxmox-children", headers=headers)
+    assert res.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_requires_auth(client: AsyncClient, db_session):
+    ids = await _seed(db_session)
+    res = await client.get(f"/api/v1/scan/pending/{ids['host']}/proxmox-children")
+    assert res.status_code == 401

backend/tests/test_scanner.py

@@ -1,5 +1,6 @@
 """Tests for scanner: two-phase nmap, mDNS discovery, run_scan integration."""
 import uuid
+from datetime import datetime, timezone
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
@@ -375,6 +376,79 @@ def test_nmap_scan_single_non_root_uses_connect_scan():
     assert result["open_ports"][0]["banner"] == "nginx 1.24"
 
 
+def test_nmap_scan_single_discovery_is_unbounded_by_default():
+    """The range scan's discovery pass keeps its authoritative, untimed run."""
+    from app.services.scanner import _nmap_scan_single
+
+    host = {"ip": "192.168.1.14", "hostname": None, "mac": None, "os": None, "open_ports": []}
+    disc = _fake_scanner("192.168.1.14", {})
+
+    with patch("app.services.scanner.nmap.PortScanner", side_effect=[disc]), \
+         patch("app.services.scanner.os.geteuid", return_value=1000):
+        _nmap_scan_single(host)
+
+    args = disc.scan.call_args.kwargs["arguments"]
+    assert "--host-timeout" not in args
+    assert "--min-rate" not in args
+
+
+def test_nmap_scan_single_bounded_never_sets_a_host_timeout():
+    """A deep slice drops retries — never --host-timeout.
+
+    nmap answers a host timeout with "Skipping host <ip> due to host timeout"
+    and throws away every port it had already found, so a ceiling here turns a
+    slow scan into one that reports nothing. The time on a dropping host goes to
+    the retry pass — measured 2x — so that is what the deep scan gives up.
+    """
+    from app.services.scanner import _nmap_scan_single
+
+    host = {"ip": "192.168.1.15", "hostname": None, "mac": None, "os": None, "open_ports": []}
+    disc = _fake_scanner("192.168.1.15", {})
+
+    with patch("app.services.scanner.nmap.PortScanner", side_effect=[disc]), \
+         patch("app.services.scanner.os.geteuid", return_value=1000):
+        _nmap_scan_single(host, "1-8192", True)
+
+    args = disc.scan.call_args.kwargs["arguments"]
+    assert "-p 1-8192" in args
+    assert "--host-timeout" not in args
+    assert "--max-retries 0" in args
+
+
+def test_deep_port_chunks_cover_every_port_once():
+    from app.services.scanner import _deep_port_chunks
+
+    chunks = _deep_port_chunks(8192)
+    assert chunks[0] == "1-8192"
+    assert chunks[-1].endswith("-65535")
+    covered = []
+    for c in chunks:
+        lo, hi = (int(x) for x in c.split("-"))
+        covered.extend(range(lo, hi + 1))
+    assert covered == list(range(1, 65536))
+
+
+def test_port_chunks_pack_ranges_and_honour_the_slice_size():
+    from app.services.scanner import _port_chunks
+
+    # Small ranges share one call instead of one call each.
+    assert _port_chunks("80,443,8000-9000") == ["80,443,8000-9000"]
+    # A range wider than the slice is cut at the slice boundary.
+    assert _port_chunks("1-100", 40) == ["1-40", "41-80", "81-100"]
+    # Overlapping input is merged before slicing, so no port is scanned twice.
+    assert _port_chunks("1-100,50-200", 1000) == ["1-200"]
+    assert _port_chunks("nonsense") == []
+
+
+def test_parse_port_spec_rejects_what_nmap_could_not_use():
+    from app.services.scanner import _parse_port_spec, _valid_port_spec
+
+    for bad in ["", "  ", "0", "65536", "100-50", "80,", "http", "-80"]:
+        assert _parse_port_spec(bad) == [], bad
+        assert _valid_port_spec(bad) is False, bad
+    assert _valid_port_spec("80,443,8000-9000") is True
+
+
 # ---------------------------------------------------------------------------
 # _nmap_scan
 # ---------------------------------------------------------------------------
@@ -750,6 +824,48 @@ async def test_run_scan_merges_proxmox_row_by_mac(mem_db):
     assert set(row.discovery_sources) == {"proxmox", "arp"}  # both filters
 
 
+@pytest.mark.asyncio
+async def test_run_scan_keeps_services_the_fingerprint_cannot_see(mem_db):
+    """A re-scan unions its fingerprint onto the row — it never replaces it.
+
+    Since 3.3.0 the row is the only copy of a device's services and every canvas
+    drawing it reads that list, so overwriting it with what nmap happened to
+    match would delete hand-added services everywhere at once (#347).
+    """
+    from app.services.scanner import run_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(_make_scan_run(run_id))
+        session.add(InventoryDevice(
+            id="row-1", ip="192.168.1.60", status="approved",
+            discovery_source="arp", discovery_sources=["arp"],
+            services=[
+                {"port": 9000, "protocol": "tcp", "service_name": "Portainer", "path": "/#!/home"},
+                {"port": 22, "protocol": "tcp", "service_name": "ssh"},
+            ],
+        ))
+        await session.commit()
+
+    nmap_hosts = [{"ip": "192.168.1.60", "hostname": "docker.lan", "mac": None, "os": None,
+                   "open_ports": [{"port": 22, "protocol": "tcp", "banner": "OpenSSH 9.2"}]}]
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan", return_value=nmap_hosts), \
+             patch("app.services.scanner._mdns_discover", new_callable=AsyncMock, return_value=[]), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_scan(["192.168.1.0/24"], session, run_id)
+
+    async with mem_db() as session:
+        row = await session.get(InventoryDevice, "row-1")
+
+    by_port = {s["port"]: s for s in row.services}
+    assert by_port[9000]["service_name"] == "Portainer"  # hand-added, untouched
+    assert by_port[9000]["path"] == "/#!/home"
+    assert 22 in by_port                                 # what the scan saw is still there
+    assert row.status == "approved"
+
+
 @pytest.mark.asyncio
 async def test_run_scan_mdns_skipped_if_already_in_nmap(mem_db):
     """If nmap and mDNS both find the same IP, it should not be double-counted."""
@@ -988,3 +1104,580 @@ async def test_run_scan_no_probe_when_disabled(mem_db):
             await run_scan(["192.168.1.0/24"], session, run_id)
 
     probe.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# run_device_scan — per-device deep rescan (issue #350)
+# ---------------------------------------------------------------------------
+
+def test_build_port_spec_full_covers_every_tcp_port():
+    from app.services.scanner import _build_port_spec
+
+    # full wins over the curated list *and* over user ranges — the deep rescan
+    # is only worth its minutes if it really scans everything.
+    assert _build_port_spec(None, full=True) == "1-65535"
+    assert _build_port_spec(["8000-8100"], full=True) == "1-65535"
+
+
+@pytest.mark.asyncio
+async def test_run_device_scan_refreshes_services_and_marks_run_done(mem_db):
+    from app.services.scanner import run_device_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(ScanRun(id=run_id, status="running", kind="device", ranges=["192.168.1.9/32"]))
+        session.add(InventoryDevice(id="d1", ip="192.168.1.9", status="approved", services=[]))
+        await session.commit()
+
+    seen_specs = []
+
+    def _scanned(host_dict, port_spec, bounded=False):
+        seen_specs.append(port_spec)
+        # A full-range rescan is always bounded, or it never ends.
+        assert bounded is True
+        # Only the slice holding 22 reports it — the union is the caller's job.
+        if port_spec == "1-8192":
+            host_dict["open_ports"] = [{"port": 22, "protocol": "tcp", "banner": "OpenSSH 9.2"}]
+        return host_dict
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan_single", side_effect=_scanned), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_device_scan("d1", session, run_id)
+
+    async with mem_db() as session:
+        device = await session.get(InventoryDevice, "d1")
+        run = await session.get(ScanRun, run_id)
+
+    assert device is not None and run is not None
+    assert run.status == "done"
+    assert device.last_scan is not None
+    assert any(s.get("port") == 22 for s in device.services)
+    # A rescan refreshes an existing row; it never spawns a second one.
+    assert device.status == "approved"
+
+
+@pytest.mark.asyncio
+async def test_run_device_scan_keeps_hand_added_services(mem_db):
+    """Regression: the rescan unions, it does not replace.
+
+    Services the user typed in by hand are the only copy that exists — every
+    canvas drawing the device reads this list.
+    """
+    from app.services.scanner import run_device_scan
+
+    run_id = _make_run_id()
+    hand_added = {"port": 9000, "protocol": "tcp", "service_name": "My App"}
+    async with mem_db() as session:
+        session.add(ScanRun(id=run_id, status="running", kind="device", ranges=["192.168.1.9/32"]))
+        session.add(InventoryDevice(id="d1", ip="192.168.1.9", status="pending", services=[hand_added]))
+        await session.commit()
+
+    def _scanned(host_dict, port_spec, bounded=False):
+        host_dict["open_ports"] = [{"port": 22, "protocol": "tcp", "banner": "OpenSSH 9.2"}]
+        return host_dict
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan_single", side_effect=_scanned), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_device_scan("d1", session, run_id)
+
+    async with mem_db() as session:
+        device = await session.get(InventoryDevice, "d1")
+
+    assert device is not None
+    ports = {s.get("port") for s in device.services}
+    assert ports == {22, 9000}
+
+
+@pytest.mark.asyncio
+async def test_scan_keeps_the_icon_the_user_picked_for_a_service(mem_db):
+    """Regression: every scan used to repaint hand-picked service icons.
+
+    The fingerprint guesses an icon from the port; the user's choice is the
+    only one that means anything, so a rescan leaves it where it is.
+    """
+    from app.services.scanner import run_device_scan
+
+    run_id = _make_run_id()
+    curated = {
+        "port": 22,
+        "protocol": "tcp",
+        "service_name": "ssh",
+        "icon": "brand:openssh",
+        "category": "remote",
+    }
+    async with mem_db() as session:
+        session.add(ScanRun(id=run_id, status="running", kind="device", ranges=["192.168.1.9/32"]))
+        session.add(InventoryDevice(id="d1", ip="192.168.1.9", status="approved", services=[curated]))
+        await session.commit()
+
+    def _scanned(host_dict, port_spec, bounded=False):
+        host_dict["open_ports"] = [{"port": 22, "protocol": "tcp", "banner": "OpenSSH 9.2"}]
+        return host_dict
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan_single", side_effect=_scanned), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_device_scan("d1", session, run_id)
+
+    async with mem_db() as session:
+        device = await session.get(InventoryDevice, "d1")
+
+    assert device is not None
+    matches = [s for s in device.services if s.get("port") == 22]
+    # Merged in place — the name key is case-insensitive, so "SSH" from the
+    # signature does not append a second row next to the user's "ssh".
+    assert len(matches) == 1
+    ssh = matches[0]
+    assert ssh["icon"] == "brand:openssh"
+    assert ssh["category"] == "remote"
+
+
+@pytest.mark.asyncio
+async def test_run_device_scan_keeps_the_device_own_discovery_source(mem_db):
+    """A rescan re-observes a device; it does not discover it on the network.
+
+    Tagging every rescanned device "arp" told a Proxmox guest or a hand-added
+    host that the network scanner found it, and it then answered that filter.
+    """
+    from app.services.scanner import run_device_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(ScanRun(id=run_id, status="running", kind="device", ranges=["192.168.1.9/32"]))
+        session.add(InventoryDevice(
+            id="d1",
+            ip="192.168.1.9",
+            status="approved",
+            services=[],
+            discovery_source="proxmox",
+            discovery_sources=["proxmox"],
+        ))
+        await session.commit()
+
+    def _scanned(host_dict, port_spec, bounded=False):
+        host_dict["open_ports"] = [{"port": 8006, "protocol": "tcp", "banner": ""}]
+        return host_dict
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan_single", side_effect=_scanned), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_device_scan("d1", session, run_id, ports="8006")
+
+    async with mem_db() as session:
+        device = await session.get(InventoryDevice, "d1")
+
+    assert device is not None
+    assert device.discovery_sources == ["proxmox"]
+    assert device.discovery_source == "proxmox"
+
+
+@pytest.mark.asyncio
+async def test_run_device_scan_marks_run_error_when_device_has_no_ip(mem_db):
+    from app.services.scanner import run_device_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(ScanRun(id=run_id, status="running", kind="device", ranges=["/32"]))
+        session.add(InventoryDevice(id="d1", ip=None, status="pending", services=[]))
+        await session.commit()
+
+    async with mem_db() as session:
+        with patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_device_scan("d1", session, run_id)
+
+    async with mem_db() as session:
+        run = await session.get(ScanRun, run_id)
+
+    assert run is not None
+    assert run.status == "error"
+    assert run.error is not None
+
+
+@pytest.mark.asyncio
+async def test_run_device_scan_skips_nmap_when_cancelled(mem_db):
+    from app.services.scanner import _cancelled_runs, request_cancel, run_device_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(ScanRun(id=run_id, status="running", kind="device", ranges=["192.168.1.9/32"]))
+        session.add(InventoryDevice(id="d1", ip="192.168.1.9", status="pending", services=[]))
+        await session.commit()
+
+    request_cancel(run_id)
+    single = MagicMock()
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan_single", new=single), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_device_scan("d1", session, run_id)
+
+    async with mem_db() as session:
+        run = await session.get(ScanRun, run_id)
+
+    single.assert_not_called()
+    assert run is not None
+    assert run.status == "cancelled"
+    # The run cleans up its cancellation flag on the way out.
+    assert run_id not in _cancelled_runs
+
+
+@pytest.mark.asyncio
+async def test_run_device_scan_unions_ports_across_slices(mem_db):
+    """Every slice contributes; a slow one costs only its own ports."""
+    from app.services.scanner import _deep_port_chunks, run_device_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(ScanRun(id=run_id, status="running", kind="device", ranges=["192.168.1.9/32"]))
+        session.add(InventoryDevice(id="d1", ip="192.168.1.9", status="pending", services=[]))
+        await session.commit()
+
+    def _scanned(host_dict, port_spec, bounded=False):
+        lo = int(port_spec.split("-")[0])
+        if lo == 1:
+            host_dict["open_ports"] = [{"port": 22, "protocol": "tcp", "banner": ""}]
+        elif lo == 8193:
+            host_dict["open_ports"] = [{"port": 8096, "protocol": "tcp", "banner": ""}]
+        return host_dict
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan_single", side_effect=_scanned), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_device_scan("d1", session, run_id)
+
+    async with mem_db() as session:
+        device = await session.get(InventoryDevice, "d1")
+        run = await session.get(ScanRun, run_id)
+
+    assert device is not None and run is not None
+    assert {s.get("port") for s in device.services} == {22, 8096}
+    # A complete sweep carries no advisory.
+    assert run.error is None
+    assert len(_deep_port_chunks()) == 8
+
+
+@pytest.mark.asyncio
+async def test_run_device_scan_honours_a_requested_port_range(mem_db):
+    """A user-chosen range replaces the full sweep — and skips retry-free timing.
+
+    A handful of ports is cheap enough to scan properly; the bounded flags only
+    pay off over thousands of them.
+    """
+    from app.services.scanner import run_device_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(ScanRun(id=run_id, status="running", kind="device", ranges=["192.168.1.9/32"]))
+        session.add(InventoryDevice(id="d1", ip="192.168.1.9", status="pending", services=[]))
+        await session.commit()
+
+    calls = []
+
+    def _scanned(host_dict, port_spec, bounded=False):
+        calls.append((port_spec, bounded))
+        host_dict["open_ports"] = [{"port": 8096, "protocol": "tcp", "banner": ""}]
+        return host_dict
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan_single", side_effect=_scanned), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_device_scan("d1", session, run_id, ports="8000-9000")
+
+    async with mem_db() as session:
+        device = await session.get(InventoryDevice, "d1")
+        run = await session.get(ScanRun, run_id)
+
+    assert calls == [("8000-9000", False)]
+    assert device is not None and run is not None
+    assert {s.get("port") for s in device.services} == {8096}
+    assert run.status == "done"
+    assert run.error is None
+
+
+@pytest.mark.asyncio
+async def test_run_device_scan_keeps_what_it_found_when_the_budget_runs_out(mem_db):
+    """A spent budget stops the sweep — it never discards the ports found.
+
+    The earlier --host-timeout did exactly that (nmap skips the host wholesale),
+    which is why a deep scan could come back empty on a slow host.
+    """
+    from app.services.scanner import run_device_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(ScanRun(id=run_id, status="running", kind="device", ranges=["192.168.1.9/32"]))
+        session.add(InventoryDevice(id="d1", ip="192.168.1.9", status="pending", services=[]))
+        await session.commit()
+
+    calls = []
+
+    def _scanned(host_dict, port_spec, bounded=False):
+        calls.append(port_spec)
+        host_dict["open_ports"] = [{"port": 22, "protocol": "tcp", "banner": ""}]
+        return host_dict
+
+    async with mem_db() as session:
+        # Budget already spent when the first slice returns.
+        with patch("app.services.scanner._nmap_scan_single", side_effect=_scanned), \
+             patch("app.services.scanner.settings") as mock_settings, \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            mock_settings.scanner_deep_host_timeout = -1
+            await run_device_scan("d1", session, run_id)
+
+    async with mem_db() as session:
+        device = await session.get(InventoryDevice, "d1")
+        run = await session.get(ScanRun, run_id)
+
+    assert calls == ["1-8192"]
+    assert device is not None and run is not None
+    assert {s.get("port") for s in device.services} == {22}
+    assert run.status == "done"
+    # Partial coverage is reported, never passed off as a full sweep.
+    assert run.error is not None
+    assert "1/8" in run.error
+
+
+# ---------------------------------------------------------------------------
+# Multi-IP devices — one row per device, not one per address (issue #373)
+# ---------------------------------------------------------------------------
+
+def _host(ip: str, *, mac: str | None = None, hostname: str | None = None):
+    return {"ip": ip, "hostname": hostname, "mac": mac, "os": None, "open_ports": []}
+
+
+@pytest.mark.asyncio
+async def test_process_host_folds_into_declared_secondary_ip(mem_db):
+    """A scan of a device's second address refreshes its row, never mints one.
+
+    The user declares the extra addresses by hand — a router's LAN and VLAN
+    legs, a host behind a VIP — precisely so the scanner stops reporting them
+    as separate discoveries.
+    """
+    from app.services.scanner import DeepScanOptions, process_host
+
+    async with mem_db() as session:
+        session.add(InventoryDevice(
+            id="d1", ip="192.168.1.1, 192.168.10.1", status="approved", label="router",
+        ))
+        await session.commit()
+
+    async with mem_db() as session:
+        outcome = await process_host(
+            session, _host("192.168.10.1", hostname="router-vlan.lan"),
+            hidden_ips=set(), deep_scan=DeepScanOptions(),
+        )
+
+    async with mem_db() as session:
+        devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+    assert outcome == "updated"
+    assert len(devices) == 1
+    # The declared list is the user's, not the scanner's — it survives the merge.
+    assert devices[0].ip == "192.168.1.1, 192.168.10.1"
+    assert devices[0].hostname == "router-vlan.lan"
+
+
+@pytest.mark.asyncio
+async def test_process_host_does_not_match_an_address_prefix(mem_db):
+    """`192.168.1.4` is a substring of `192.168.1.40` — and a different host.
+
+    The query narrows with a substring match, so the per-token confirmation is
+    what stops a false match. It matters more than usual here: the losing rows
+    of a match are deleted, not skipped.
+    """
+    from app.services.scanner import DeepScanOptions, process_host
+
+    async with mem_db() as session:
+        session.add(InventoryDevice(id="d1", ip="192.168.1.40", status="approved"))
+        await session.commit()
+
+    async with mem_db() as session:
+        outcome = await process_host(
+            session, _host("192.168.1.4"), hidden_ips=set(), deep_scan=DeepScanOptions(),
+        )
+
+    async with mem_db() as session:
+        devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+    assert outcome == "created"
+    assert {d.ip for d in devices} == {"192.168.1.40", "192.168.1.4"}
+
+
+@pytest.mark.asyncio
+async def test_process_host_matches_a_single_token_row_exactly_as_before(mem_db):
+    """The ordinary one-address case is untouched by the token matching."""
+    from app.services.scanner import DeepScanOptions, process_host
+
+    async with mem_db() as session:
+        session.add(InventoryDevice(id="d1", ip="192.168.1.5", status="pending"))
+        await session.commit()
+
+    async with mem_db() as session:
+        outcome = await process_host(
+            session, _host("192.168.1.5", hostname="nas.lan"),
+            hidden_ips=set(), deep_scan=DeepScanOptions(),
+        )
+
+    async with mem_db() as session:
+        devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+    assert outcome == "updated"
+    assert len(devices) == 1 and devices[0].hostname == "nas.lan"
+
+
+@pytest.mark.asyncio
+async def test_run_scan_skips_the_secondary_ip_of_a_hidden_device(mem_db):
+    """Hiding a multi-address device hides it at every one of its addresses."""
+    from app.services.scanner import run_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(_make_scan_run(run_id))
+        session.add(InventoryDevice(id="d1", ip="192.168.1.1, 192.168.10.1", status="hidden"))
+        await session.commit()
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan", return_value=[_host("192.168.10.1")]), \
+             patch("app.services.scanner._mdns_discover", new_callable=AsyncMock, return_value=[]), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_scan(["192.168.1.0/24"], session, run_id)
+
+    async with mem_db() as session:
+        devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+    assert len(devices) == 1
+    assert devices[0].status == "hidden"
+
+
+@pytest.mark.asyncio
+async def test_dedupe_collapses_a_single_ip_row_into_a_multi_ip_one(mem_db):
+    """Declaring an extra address folds in the duplicate row it already spawned.
+
+    The approved row wins even though it is the younger of the two: it carries
+    the canvas links.
+    """
+    from app.services.scanner import _dedupe_pending_by_ip
+
+    async with mem_db() as session:
+        session.add(InventoryDevice(
+            id="stale", ip="192.168.10.1", status="pending",
+            discovered_at=datetime(2026, 1, 1, tzinfo=timezone.utc),
+        ))
+        session.add(InventoryDevice(
+            id="keep", ip="192.168.1.1, 192.168.10.1", status="approved",
+            discovered_at=datetime(2026, 2, 1, tzinfo=timezone.utc),
+        ))
+        await session.commit()
+
+    async with mem_db() as session:
+        deleted = await _dedupe_pending_by_ip(session)
+
+    async with mem_db() as session:
+        devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+    assert deleted == 1
+    assert [d.id for d in devices] == ["keep"]
+
+
+@pytest.mark.asyncio
+async def test_dedupe_leaves_rows_that_share_no_address(mem_db):
+    from app.services.scanner import _dedupe_pending_by_ip
+
+    async with mem_db() as session:
+        session.add(InventoryDevice(id="a", ip="192.168.1.1, 192.168.10.1", status="pending"))
+        session.add(InventoryDevice(id="b", ip="192.168.1.2, 192.168.10.2", status="pending"))
+        await session.commit()
+
+    async with mem_db() as session:
+        deleted = await _dedupe_pending_by_ip(session)
+
+    async with mem_db() as session:
+        devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+    assert deleted == 0
+    assert len(devices) == 2
+
+
+def test_group_by_shared_ip_is_transitive():
+    """`A,B` next to `A` and `B` is one device, not two pairs."""
+    from app.services.scanner import _group_by_shared_ip
+
+    rows = [
+        InventoryDevice(id="a", ip="10.0.0.1"),
+        InventoryDevice(id="b", ip="10.0.1.1"),
+        InventoryDevice(id="bridge", ip="10.0.0.1, 10.0.1.1"),
+        InventoryDevice(id="other", ip="10.0.2.1"),
+    ]
+
+    groups = {frozenset(r.id for r in group) for group in _group_by_shared_ip(rows)}
+
+    assert groups == {frozenset({"a", "b", "bridge"}), frozenset({"other"})}
+
+
+@pytest.mark.asyncio
+async def test_dedupe_never_deletes_a_second_approved_row(mem_db):
+    """Two approved rows sharing an address both keep their canvas links.
+
+    An approved row is what nodes and rack mounts point at, so collapsing one
+    into the other would silently unlink whatever drew it. The scan collapses
+    the pending row and leaves the pair for the user to resolve.
+    """
+    from app.services.scanner import _dedupe_pending_by_ip
+
+    async with mem_db() as session:
+        session.add(InventoryDevice(
+            id="a", ip="10.0.0.1", status="approved",
+            discovered_at=datetime(2026, 1, 1, tzinfo=timezone.utc),
+        ))
+        session.add(InventoryDevice(
+            id="b", ip="10.0.0.1, 10.0.0.2", status="approved",
+            discovered_at=datetime(2026, 2, 1, tzinfo=timezone.utc),
+        ))
+        session.add(InventoryDevice(
+            id="pending", ip="10.0.0.2", status="pending",
+            discovered_at=datetime(2026, 3, 1, tzinfo=timezone.utc),
+        ))
+        await session.commit()
+
+    async with mem_db() as session:
+        deleted = await _dedupe_pending_by_ip(session)
+
+    async with mem_db() as session:
+        devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+    assert deleted == 1
+    assert sorted(d.id for d in devices) == ["a", "b"]
+
+
+@pytest.mark.asyncio
+async def test_process_host_never_deletes_a_second_approved_row(mem_db):
+    """The same guard on the scan path: the merge target refreshes, no row goes."""
+    from app.services.scanner import DeepScanOptions, process_host
+
+    async with mem_db() as session:
+        session.add(InventoryDevice(
+            id="a", ip="10.0.0.1", status="approved",
+            discovered_at=datetime(2026, 1, 1, tzinfo=timezone.utc),
+        ))
+        session.add(InventoryDevice(
+            id="b", ip="10.0.0.1, 10.0.0.2", status="approved",
+            discovered_at=datetime(2026, 2, 1, tzinfo=timezone.utc),
+        ))
+        await session.commit()
+
+    async with mem_db() as session:
+        outcome = await process_host(
+            session, _host("10.0.0.1", hostname="claimed.lan"),
+            hidden_ips=set(), deep_scan=DeepScanOptions(),
+        )
+
+    async with mem_db() as session:
+        devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+        oldest = await session.get(InventoryDevice, "a")
+
+    assert outcome == "updated"
+    assert sorted(d.id for d in devices) == ["a", "b"]
+    # The oldest approved row is the merge target.
+    assert oldest is not None and oldest.hostname == "claimed.lan"

backend/tests/test_self_parent_repair.py

@@ -0,0 +1,92 @@
+"""Detaching nodes recorded as their own parent (#370).
+
+A ``parent_id = id`` row is fatal on the canvas: every parent walk assumes 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, sitting wherever its stored coordinates put
+it rather than inside the container it appears to belong to.
+
+The repair runs at startup because the bad rows are already in users' databases;
+the write-path guards shipped alongside it only stop new ones.
+"""
+import pytest
+from sqlalchemy.ext.asyncio import create_async_engine
+
+import app.db.database as database
+
+pytestmark = pytest.mark.asyncio
+
+_DDL = "CREATE TABLE nodes (id VARCHAR PRIMARY KEY, label VARCHAR, parent_id VARCHAR)"
+
+
+async def _engine(tmp_path, rows):
+    engine = create_async_engine(f"sqlite+aiosqlite:///{tmp_path / 'selfparent.db'}")
+    async with engine.begin() as conn:
+        await conn.exec_driver_sql(_DDL)
+        for node_id, parent_id in rows:
+            await conn.exec_driver_sql(
+                "INSERT INTO nodes (id, label, parent_id) VALUES (?, ?, ?)",
+                (node_id, node_id, parent_id),
+            )
+    return engine
+
+
+async def _parents(engine) -> dict[str, str | None]:
+    async with engine.begin() as conn:
+        rows = (await conn.exec_driver_sql("SELECT id, parent_id FROM nodes")).fetchall()
+    return {r[0]: r[1] for r in rows}
+
+
+async def _run(engine, monkeypatch) -> None:
+    monkeypatch.setattr(database, "engine", engine)
+    await database._repair_self_parent_nodes()
+
+
+async def test_detaches_a_self_parented_node(tmp_path, monkeypatch):
+    engine = await _engine(tmp_path, [("pihole", "pihole")])
+
+    await _run(engine, monkeypatch)
+
+    assert (await _parents(engine))["pihole"] is None
+
+
+async def test_leaves_real_parents_alone(tmp_path, monkeypatch):
+    engine = await _engine(
+        tmp_path,
+        [("pve", None), ("vm", "pve"), ("broken", "broken")],
+    )
+
+    await _run(engine, monkeypatch)
+
+    parents = await _parents(engine)
+    assert parents == {"pve": None, "vm": "pve", "broken": None}
+
+
+async def test_is_idempotent(tmp_path, monkeypatch):
+    engine = await _engine(tmp_path, [("a", "a"), ("b", None)])
+
+    await _run(engine, monkeypatch)
+    await _run(engine, monkeypatch)
+
+    assert await _parents(engine) == {"a": None, "b": None}
+
+
+async def test_does_not_touch_a_two_node_cycle(tmp_path, monkeypatch):
+    """Only the exact self-parent case is repairable here.
+
+    A longer cycle has no single right answer for which link to cut, and the
+    runtime cycle guards keep the canvas usable, so the rows are left as they
+    are rather than guessed at.
+    """
+    engine = await _engine(tmp_path, [("a", "b"), ("b", "a")])
+
+    await _run(engine, monkeypatch)
+
+    assert await _parents(engine) == {"a": "b", "b": "a"}
+
+
+async def test_survives_a_missing_table(tmp_path, monkeypatch):
+    """Boot must not die on a repair; the canvas works either way."""
+    engine = create_async_engine(f"sqlite+aiosqlite:///{tmp_path / 'empty.db'}")
+
+    await _run(engine, monkeypatch)

backend/tests/test_settings.py

@@ -255,3 +255,57 @@ def test_valid_oidc_configuration_is_accepted():
     configured = _valid_oidc_settings()
     assert configured.auth_mode == "oidc"
     assert configured.oidc_cookie_secure is True
+
+
+# --- Env values arriving still quoted (podman-compose, issue #410) ---
+
+
+def test_quoted_password_hash_is_unwrapped():
+    """podman-compose passes .env quotes through verbatim; Docker Compose strips them."""
+    configured = Settings(
+        _env_file=None,
+        secret_key="test-secret",
+        auth_password_hash="'$2b$12$RtMbyw17l4N5UGzeXMNAWuzCaVV.XFBY7ZetWheQhxcBDcxahapkG'",
+    )
+    assert configured.auth_password_hash == "$2b$12$RtMbyw17l4N5UGzeXMNAWuzCaVV.XFBY7ZetWheQhxcBDcxahapkG"
+
+
+def test_double_quoted_password_hash_is_unwrapped():
+    configured = Settings(
+        _env_file=None,
+        secret_key="test-secret",
+        auth_password_hash='"$2b$12$RtMbyw17l4N5UGzeXMNAWuzCaVV.XFBY7ZetWheQhxcBDcxahapkG"',
+    )
+    assert configured.auth_password_hash.startswith("$2b$12$")
+
+
+def test_unquoted_password_hash_is_left_alone():
+    raw = "$2b$12$RtMbyw17l4N5UGzeXMNAWuzCaVV.XFBY7ZetWheQhxcBDcxahapkG"
+    configured = Settings(_env_file=None, secret_key="test-secret", auth_password_hash=raw)
+    assert configured.auth_password_hash == raw
+
+
+def test_unmatched_quote_is_not_stripped():
+    """Only a matched pair is unwrapped, so a truly broken value still fails validation."""
+    configured = Settings(
+        _env_file=None,
+        secret_key="test-secret",
+        auth_password_hash="'$2b$12$RtMbyw17l4N5UGzeXMNAWu",
+    )
+    assert configured.auth_password_hash.startswith("'")
+
+
+def test_quoted_secret_key_is_unwrapped():
+    configured = _valid_oidc_settings(secret_key="'test-secret-key-that-is-at-least-32-bytes'")
+    assert configured.secret_key == "test-secret-key-that-is-at-least-32-bytes"
+
+
+def test_secret_key_length_is_checked_after_unwrapping():
+    """The quotes must not pad a too-short key past the 32-byte OIDC floor."""
+    with pytest.raises(ValueError, match="SECRET_KEY must be at least 32 bytes"):
+        _valid_oidc_settings(secret_key="'" + "a" * 31 + "'")
+
+
+def test_quoted_oidc_client_secret_is_unwrapped():
+    configured = _valid_oidc_settings(oidc_client_secret="'sup3r$ecret'")
+    assert configured.oidc_client_secret == "sup3r$ecret"

backend/tests/test_status_checker.py

@@ -1,6 +1,7 @@
 """Tests for status_checker service: each check method."""
 from unittest.mock import AsyncMock, MagicMock, patch
 
+import httpx
 import pytest
 
 from app.services.status_checker import (
@@ -13,16 +14,31 @@ from app.services.status_checker import (
 )
 
 
+class _TransportClient:
+    """
+    Patch target for httpx.AsyncClient that routes through a MockTransport.
+
+    Real client, fake network: _http_get exercises the genuine httpx request
+    path (including .stream()) instead of a mock that would happily accept any
+    call shape.
+    """
+
+    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 = []
+
+    def __call__(self, **kwargs):
+        self.kwargs.append(dict(kwargs))
+        kwargs.pop("verify", None)
+        return self._real(transport=httpx.MockTransport(self._handler), **kwargs)
+
+
 def _mock_httpx_client(status_code):
     """Build a stand-in for httpx.AsyncClient whose GET returns status_code."""
-    resp = MagicMock()
-    resp.status_code = status_code
-    client = MagicMock()
-    client.get = AsyncMock(return_value=resp)
-    ctx = MagicMock()
-    ctx.__aenter__ = AsyncMock(return_value=client)
-    ctx.__aexit__ = AsyncMock(return_value=False)
-    return MagicMock(return_value=ctx)
+    return _TransportClient(lambda request: httpx.Response(status_code))
 
 # --- check_node dispatcher ---
 
@@ -434,6 +450,37 @@ async def test_check_service_non_http_port_is_unknown():
     mock_http.assert_not_called()
 
 
+@pytest.mark.parametrize("port", [515, 9100, 9101, 9107])
+@pytest.mark.asyncio
+async def test_check_service_never_touches_a_raw_printing_port(port):
+    """Issue #404: a GET to JetDirect/LPD makes the printer print it.
+
+    The status checker runs every 60 s, so a printer approved as a node used to
+    print one page a minute, forever. These ports get no request at all.
+    """
+    svc = {"port": port, "protocol": "tcp", "service_name": "jetdirect"}
+    with patch("app.services.status_checker._tcp_connect", new_callable=AsyncMock) as mock_tcp, \
+         patch("app.services.status_checker._http_get", new_callable=AsyncMock) as mock_http:
+        result = await check_service(svc, "10.0.0.1")
+    assert result == "unknown"
+    mock_tcp.assert_not_called()
+    mock_http.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_check_service_printer_port_named_http_is_still_skipped():
+    """A service_name saying "http" must not talk the checker onto 9100.
+
+    Fingerprinting labels 9100 "Node Exporter", and an override can put any
+    name there — the port decides, not the label.
+    """
+    svc = {"port": 9100, "protocol": "tcp", "service_name": "http-node-exporter"}
+    with patch("app.services.status_checker._http_get", new_callable=AsyncMock) as mock_http:
+        result = await check_service(svc, "10.0.0.1")
+    assert result == "unknown"
+    mock_http.assert_not_called()
+
+
 @pytest.mark.asyncio
 async def test_check_service_ssh_port_22_is_unknown():
     """SSH (port 22) is never checked — keep it grey, not red/green."""
@@ -500,7 +547,14 @@ async def _captured_url(svc, host):
 @pytest.mark.asyncio
 async def test_check_service_uses_the_host_override():
     svc = {"port": 8080, "protocol": "tcp", "service_name": "blog", "host": "blog.example.com"}
-    assert await _captured_url(svc, "10.0.0.1") == "http://blog.example.com:8080"
+    assert await _captured_url(svc, "10.0.0.1") == "http://blog.example.com"
+
+
+@pytest.mark.asyncio
+async def test_check_service_drops_the_scanned_port_behind_a_reverse_proxy():
+    """Issue #382 — an override points at a proxy; the internal port breaks it."""
+    svc = {"port": 8083, "protocol": "tcp", "service_name": "blog", "host": "https://mywebserver.mydomain.com"}
+    assert await _captured_url(svc, "192.168.100.100") == "https://mywebserver.mydomain.com"
 
 
 @pytest.mark.asyncio
@@ -522,21 +576,21 @@ async def test_check_service_takes_the_port_from_the_override():
 
 
 @pytest.mark.asyncio
-async def test_check_service_lets_the_service_port_beat_the_override_port():
+async def test_check_service_keeps_the_port_typed_into_the_override():
     svc = {"port": 3000, "protocol": "tcp", "service_name": "blog", "host": "blog.example.com:8443"}
-    assert await _captured_url(svc, "10.0.0.1") == "http://blog.example.com:3000"
+    assert await _captured_url(svc, "10.0.0.1") == "http://blog.example.com:8443"
 
 
 @pytest.mark.asyncio
 async def test_check_service_uses_the_first_host_of_a_comma_list_override():
     svc = {"port": 8080, "protocol": "tcp", "service_name": "blog", "host": "blog.example.com, alt.example.com"}
-    assert await _captured_url(svc, "10.0.0.1") == "http://blog.example.com:8080"
+    assert await _captured_url(svc, "10.0.0.1") == "http://blog.example.com"
 
 
 @pytest.mark.asyncio
 async def test_check_service_brackets_an_ipv6_override():
     svc = {"port": 80, "protocol": "tcp", "service_name": "http", "host": "[2001:db8::1]:8080"}
-    assert await _captured_url(svc, "10.0.0.1") == "http://[2001:db8::1]:80"
+    assert await _captured_url(svc, "10.0.0.1") == "http://[2001:db8::1]:8080"
 
 
 @pytest.mark.asyncio
@@ -554,6 +608,43 @@ async def test_check_services_empty_list():
 
 # --- _http_get status-code interpretation (real primitive, mocked transport) ---
 
+# --- Regression: an endless response body must not be buffered (issue #375) ---
+
+_CHUNK = b"\0" * 65536
+
+
+def _endless_body(counter: dict):
+    """
+    A body that never ends and declares no Content-Length — the Freebox
+    bandwidth-test endpoint from issue #375. Bounded at 512 chunks (32 MiB) so
+    a regression fails the test instead of hanging the suite forever.
+    """
+
+    async def gen():
+        for _ in range(512):
+            counter["chunks"] += 1
+            yield _CHUNK
+
+    return gen()
+
+
+@pytest.mark.asyncio
+async def test_http_get_does_not_read_the_body():
+    # _http_get only needs the status line. Buffering the body of an endless
+    # stream is what OOM-killed the backend, so assert not one byte is pulled.
+    counter = {"chunks": 0}
+    factory = _TransportClient(
+        lambda request: httpx.Response(
+            200,
+            headers={"Content-Type": "application/octet-stream"},
+            content=_endless_body(counter),
+        )
+    )
+    with patch("app.services.status_checker.httpx.AsyncClient", factory):
+        assert await _http_get("http://192.168.1.254:8095/") is True
+    assert counter["chunks"] == 0
+
+
 @pytest.mark.asyncio
 async def test_http_get_true_on_2xx():
     with patch("app.services.status_checker.httpx.AsyncClient", _mock_httpx_client(200)):

backend/tests/test_zigbee_router.py

@@ -7,10 +7,34 @@ from unittest.mock import AsyncMock, patch
 import pytest
 from httpx import AsyncClient
 
+from app.services.import_jobs import reset_jobs
+
 # ---------------------------------------------------------------------------
 # Fixtures
 # ---------------------------------------------------------------------------
 
+
+@pytest.fixture(autouse=True)
+def _clear_import_jobs() -> None:
+    """The canvas-import job registry is process-global; isolate each test."""
+    reset_jobs()
+
+
+async def _start_canvas_import(
+    client: AsyncClient, headers: dict, body: dict
+) -> str:
+    """POST /zigbee/import and return the job id.
+
+    The route is fire-and-poll: it answers 202 immediately and the fetch runs as
+    a Starlette background task, which the ASGI transport completes before this
+    await returns — so the job is already settled by the time we poll.
+    """
+    res = await client.post("/api/v1/zigbee/import", json=body, headers=headers)
+    assert res.status_code == 202, res.text
+    job_id: str = res.json()["job_id"]
+    assert res.json()["status"] == "running"
+    return job_id
+
 # ---------------------------------------------------------------------------
 # /api/v1/zigbee/test-connection
 # ---------------------------------------------------------------------------
@@ -104,18 +128,18 @@ _SAMPLE_EDGES = [
 async def test_import_success(client: AsyncClient, headers: dict) -> None:
     with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
         mock_fetch.return_value = (_SAMPLE_NODES, _SAMPLE_EDGES)
-        res = await client.post(
-            "/api/v1/zigbee/import",
-            json={
-                "mqtt_host": "localhost",
-                "mqtt_port": 1883,
-                "base_topic": "zigbee2mqtt",
-            },
-            headers=headers,
+        job_id = await _start_canvas_import(
+            client,
+            headers,
+            {"mqtt_host": "localhost", "mqtt_port": 1883, "base_topic": "zigbee2mqtt"},
         )
 
+    res = await client.get(f"/api/v1/zigbee/import/{job_id}", headers=headers)
     assert res.status_code == 200
-    data = res.json()
+    body = res.json()
+    assert body["status"] == "done"
+    assert body["job_id"] == job_id
+    data = body["result"]
     assert data["device_count"] == 2
     assert len(data["nodes"]) == 2
     assert len(data["edges"]) == 1
@@ -123,22 +147,57 @@ async def test_import_success(client: AsyncClient, headers: dict) -> None:
     assert coordinator["ieee_address"] == "0x00000000"
 
 
+@pytest.mark.asyncio
+async def test_import_post_does_not_block_on_the_fetch(
+    client: AsyncClient, headers: dict
+) -> None:
+    """The POST answers 202 without a payload — that is what keeps a slow mesh
+    from outliving a reverse proxy's read timeout (issue #380)."""
+    with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
+        mock_fetch.return_value = (_SAMPLE_NODES, _SAMPLE_EDGES)
+        res = await client.post(
+            "/api/v1/zigbee/import",
+            json={"mqtt_host": "localhost", "mqtt_port": 1883},
+            headers=headers,
+        )
+    assert res.status_code == 202
+    assert set(res.json()) == {"job_id", "status"}
+
+
+@pytest.mark.asyncio
+async def test_import_job_unknown_id_returns_404(
+    client: AsyncClient, headers: dict
+) -> None:
+    res = await client.get("/api/v1/zigbee/import/no-such-job", headers=headers)
+    assert res.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_import_job_requires_auth(client: AsyncClient, headers: dict) -> None:
+    with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
+        mock_fetch.return_value = ([], [])
+        job_id = await _start_canvas_import(
+            client, headers, {"mqtt_host": "localhost", "mqtt_port": 1883}
+        )
+    res = await client.get(f"/api/v1/zigbee/import/{job_id}")
+    assert res.status_code == 401
+
+
 @pytest.mark.asyncio
 async def test_import_with_credentials(client: AsyncClient, headers: dict) -> None:
     with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
         mock_fetch.return_value = ([], [])
-        res = await client.post(
-            "/api/v1/zigbee/import",
-            json={
+        await _start_canvas_import(
+            client,
+            headers,
+            {
                 "mqtt_host": "localhost",
                 "mqtt_port": 1883,
                 "mqtt_username": "admin",
                 "mqtt_password": "secret",
                 "base_topic": "z2m",
             },
-            headers=headers,
         )
-    assert res.status_code == 200
     mock_fetch.assert_called_once_with(
         mqtt_host="localhost",
         mqtt_port=1883,
@@ -154,11 +213,10 @@ async def test_import_with_credentials(client: AsyncClient, headers: dict) -> No
 async def test_import_connection_error_returns_502(client: AsyncClient, headers: dict) -> None:
     with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
         mock_fetch.side_effect = ConnectionError("broker unreachable")
-        res = await client.post(
-            "/api/v1/zigbee/import",
-            json={"mqtt_host": "bad-host", "mqtt_port": 1883},
-            headers=headers,
+        job_id = await _start_canvas_import(
+            client, headers, {"mqtt_host": "bad-host", "mqtt_port": 1883}
         )
+    res = await client.get(f"/api/v1/zigbee/import/{job_id}", headers=headers)
     assert res.status_code == 502
     assert "broker unreachable" in res.json()["detail"]
 
@@ -167,23 +225,22 @@ async def test_import_connection_error_returns_502(client: AsyncClient, headers:
 async def test_import_timeout_returns_504(client: AsyncClient, headers: dict) -> None:
     with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
         mock_fetch.side_effect = TimeoutError("timed out")
-        res = await client.post(
-            "/api/v1/zigbee/import",
-            json={"mqtt_host": "localhost", "mqtt_port": 1883},
-            headers=headers,
+        job_id = await _start_canvas_import(
+            client, headers, {"mqtt_host": "localhost", "mqtt_port": 1883}
         )
+    res = await client.get(f"/api/v1/zigbee/import/{job_id}", headers=headers)
     assert res.status_code == 504
+    assert "timed out" in res.json()["detail"]
 
 
 @pytest.mark.asyncio
 async def test_import_malformed_payload_returns_422(client: AsyncClient, headers: dict) -> None:
     with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
         mock_fetch.side_effect = ValueError("malformed response")
-        res = await client.post(
-            "/api/v1/zigbee/import",
-            json={"mqtt_host": "localhost", "mqtt_port": 1883},
-            headers=headers,
+        job_id = await _start_canvas_import(
+            client, headers, {"mqtt_host": "localhost", "mqtt_port": 1883}
         )
+    res = await client.get(f"/api/v1/zigbee/import/{job_id}", headers=headers)
     assert res.status_code == 422
 
 
@@ -201,13 +258,12 @@ async def test_import_empty_network(client: AsyncClient, headers: dict) -> None:
     """An empty Zigbee network (coordinator only) is a valid response."""
     with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
         mock_fetch.return_value = ([], [])
-        res = await client.post(
-            "/api/v1/zigbee/import",
-            json={"mqtt_host": "localhost", "mqtt_port": 1883},
-            headers=headers,
+        job_id = await _start_canvas_import(
+            client, headers, {"mqtt_host": "localhost", "mqtt_port": 1883}
         )
+    res = await client.get(f"/api/v1/zigbee/import/{job_id}", headers=headers)
     assert res.status_code == 200
-    data = res.json()
+    data = res.json()["result"]
     assert data["device_count"] == 0
     assert data["nodes"] == []
     assert data["edges"] == []
@@ -227,16 +283,11 @@ async def test_import_missing_mqtt_host(client: AsyncClient, headers: dict) -> N
 async def test_import_with_tls_passes_flags(client: AsyncClient, headers: dict) -> None:
     with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
         mock_fetch.return_value = ([], [])
-        res = await client.post(
-            "/api/v1/zigbee/import",
-            json={
-                "mqtt_host": "broker.example.com",
-                "mqtt_port": 8883,
-                "mqtt_tls": True,
-            },
-            headers=headers,
+        await _start_canvas_import(
+            client,
+            headers,
+            {"mqtt_host": "broker.example.com", "mqtt_port": 8883, "mqtt_tls": True},
         )
-    assert res.status_code == 200
     kwargs = mock_fetch.call_args.kwargs
     assert kwargs["tls"] is True
     assert kwargs["tls_insecure"] is False
@@ -864,3 +915,91 @@ async def test_sync_now_rejected_without_host(
 async def test_sync_now_requires_auth(client: AsyncClient) -> None:
     res = await client.post("/api/v1/zigbee/sync-now")
     assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_canvas_import_also_lands_in_device_inventory(
+    client: AsyncClient, headers: dict, db_session
+) -> None:
+    """A canvas import is an import: the devices reach the Device Inventory too."""
+    from sqlalchemy import select
+
+    from app.db.models import InventoryDevice
+
+    with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
+        mock_fetch.return_value = (_SAMPLE_NODES, _SAMPLE_EDGES)
+        job_id = await _start_canvas_import(
+            client, headers, {"mqtt_host": "localhost", "mqtt_port": 1883}
+        )
+
+    res = await client.get(f"/api/v1/zigbee/import/{job_id}", headers=headers)
+    nodes = res.json()["result"]["nodes"]
+
+    rows = (
+        await db_session.execute(
+            select(InventoryDevice).where(InventoryDevice.discovery_source == "zigbee")
+        )
+    ).scalars().all()
+    by_ieee = {r.ieee_address: r for r in rows}
+    assert set(by_ieee) == {"0x00000000", "0x00000001"}
+
+    # Each node names the row it draws, so the canvas save links to it rather
+    # than minting a second, IEEE-less row.
+    for node in nodes:
+        assert node["device_id"] == by_ieee[node["ieee_address"]].id
+
+
+@pytest.mark.asyncio
+async def test_canvas_import_reuses_the_existing_inventory_row(
+    client: AsyncClient, headers: dict, db_session
+) -> None:
+    from sqlalchemy import select
+
+    from app.db.models import InventoryDevice
+
+    existing = InventoryDevice(
+        ieee_address="0x00000001",
+        friendly_name="router_1",
+        status="pending",
+        discovery_source="zigbee",
+    )
+    db_session.add(existing)
+    await db_session.commit()
+    existing_id = existing.id
+
+    with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
+        mock_fetch.return_value = (_SAMPLE_NODES, _SAMPLE_EDGES)
+        job_id = await _start_canvas_import(
+            client, headers, {"mqtt_host": "localhost", "mqtt_port": 1883}
+        )
+
+    res = await client.get(f"/api/v1/zigbee/import/{job_id}", headers=headers)
+    router = next(
+        n for n in res.json()["result"]["nodes"] if n["ieee_address"] == "0x00000001"
+    )
+    assert router["device_id"] == existing_id
+    rows = (
+        await db_session.execute(
+            select(InventoryDevice).where(InventoryDevice.ieee_address == "0x00000001")
+        )
+    ).scalars().all()
+    assert len(rows) == 1
+
+
+@pytest.mark.asyncio
+async def test_canvas_import_failure_is_reported_on_the_job(
+    client: AsyncClient, headers: dict
+) -> None:
+    """A failed inventory write fails the job rather than returning half a map."""
+    with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch, patch(
+        "app.api.routes.zigbee._persist_pending_import",
+        new=AsyncMock(side_effect=ValueError("inventory write failed")),
+    ):
+        mock_fetch.return_value = (_SAMPLE_NODES, _SAMPLE_EDGES)
+        job_id = await _start_canvas_import(
+            client, headers, {"mqtt_host": "localhost", "mqtt_port": 1883}
+        )
+
+    res = await client.get(f"/api/v1/zigbee/import/{job_id}", headers=headers)
+    assert res.status_code == 422
+    assert "inventory write failed" in res.json()["detail"]

backend/tests/test_zigbee_service.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 from typing import Any
 from unittest.mock import patch
@@ -9,7 +10,9 @@ from unittest.mock import patch
 import aiomqtt  # noqa: F401
 import pytest
 
+from app.core.config import settings
 from app.services.zigbee_service import (
+    _NETWORKMAP_TIMEOUT,
     _find_parent_router,
     _z2m_type_to_homelable,
     fetch_networkmap,
@@ -433,6 +436,10 @@ async def test_test_mqtt_connection_failure() -> None:
             await _test_mqtt_connection("bad-host", 1883)
 
 
+class _NeverMqttError(Exception):
+    """Stand-in for aiomqtt.MqttError that no test path actually raises."""
+
+
 # ---------------------------------------------------------------------------
 # TLS context
 # ---------------------------------------------------------------------------
@@ -571,3 +578,95 @@ async def test_fetch_networkmap_does_not_leak_creds_in_connection_error() -> Non
     assert "hunter2" not in msg
     assert "admin" not in msg
     assert msg == "Authentication failed"
+
+
+# ---------------------------------------------------------------------------
+# Networkmap response timeout — configurable via ZIGBEE_NETWORKMAP_TIMEOUT
+# (issue #380: a 200+ device mesh needs longer than the hard-coded 300 s)
+# ---------------------------------------------------------------------------
+
+
+class _SilentClient:
+    """An MQTT client that connects but never delivers the response message."""
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_):
+        pass
+
+    async def subscribe(self, *_a, **_kw) -> None:
+        pass
+
+    async def publish(self, *_a, **_kw) -> None:
+        pass
+
+    @property
+    def messages(self):
+        async def _never():
+            await asyncio.Event().wait()
+            yield  # pragma: no cover
+
+        return _never()
+
+
+@pytest.mark.asyncio
+async def test_fetch_networkmap_uses_settings_timeout(monkeypatch) -> None:
+    monkeypatch.setattr(settings, "zigbee_networkmap_timeout", 0.01)
+
+    with patch("app.services.zigbee_service.aiomqtt") as mock_aiomqtt:
+        mock_aiomqtt.Client.return_value = _SilentClient()
+        mock_aiomqtt.MqttError = _NeverMqttError
+
+        with pytest.raises(TimeoutError) as ei:
+            await fetch_networkmap(
+                mqtt_host="host", mqtt_port=1883, base_topic="zigbee2mqtt"
+            )
+
+    msg = str(ei.value)
+    assert "0.01s" in msg
+    assert "ZIGBEE_NETWORKMAP_TIMEOUT" in msg
+
+
+@pytest.mark.asyncio
+async def test_fetch_networkmap_explicit_timeout_overrides_settings(monkeypatch) -> None:
+    monkeypatch.setattr(settings, "zigbee_networkmap_timeout", 999)
+
+    with patch("app.services.zigbee_service.aiomqtt") as mock_aiomqtt:
+        mock_aiomqtt.Client.return_value = _SilentClient()
+        mock_aiomqtt.MqttError = _NeverMqttError
+
+        with pytest.raises(TimeoutError) as ei:
+            await fetch_networkmap(
+                mqtt_host="host",
+                mqtt_port=1883,
+                base_topic="zigbee2mqtt",
+                response_timeout=0.01,
+            )
+
+    assert "0.01s" in str(ei.value)
+
+
+@pytest.mark.asyncio
+async def test_fetch_networkmap_non_positive_setting_falls_back(monkeypatch) -> None:
+    """A misconfigured 0 must not mean 'give up immediately'."""
+    monkeypatch.setattr(settings, "zigbee_networkmap_timeout", 0)
+    captured: dict[str, float] = {}
+
+    async def _fake_wait_for(awaitable, timeout):
+        captured["timeout"] = timeout
+        awaitable.close()
+        raise asyncio.TimeoutError
+
+    with patch("app.services.zigbee_service.aiomqtt") as mock_aiomqtt:
+        mock_aiomqtt.Client.return_value = _SilentClient()
+        mock_aiomqtt.MqttError = _NeverMqttError
+        with (
+            patch("app.services.zigbee_service.asyncio.wait_for", _fake_wait_for),
+            pytest.raises(TimeoutError),
+        ):
+            await fetch_networkmap(
+                mqtt_host="host", mqtt_port=1883, base_topic="zigbee2mqtt"
+            )
+
+    assert captured["timeout"] == _NETWORKMAP_TIMEOUT

backend/tests/test_zone_size_migration.py

@@ -0,0 +1,139 @@
+"""Moving 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 kept it inside the style JSON. Get this backfill wrong and
+every zone a user ever drew comes back at the default 360x240, losing a layout
+they arranged by hand.
+"""
+import json
+
+import pytest
+from sqlalchemy.ext.asyncio import create_async_engine
+
+import app.db.database as database
+
+pytestmark = pytest.mark.asyncio
+
+_DDL = (
+    "CREATE TABLE nodes ("
+    "id VARCHAR PRIMARY KEY, type VARCHAR, label VARCHAR, "
+    "custom_colors JSON, width FLOAT, height FLOAT)"
+)
+
+
+async def _engine(tmp_path, rows):
+    engine = create_async_engine(f"sqlite+aiosqlite:///{tmp_path / 'zones.db'}")
+    async with engine.begin() as conn:
+        await conn.exec_driver_sql(_DDL)
+        for node_id, node_type, colors, width, height in rows:
+            await conn.exec_driver_sql(
+                "INSERT INTO nodes (id, type, label, custom_colors, width, height) "
+                "VALUES (?, ?, ?, ?, ?, ?)",
+                (node_id, node_type, node_id, json.dumps(colors) if colors else None, width, height),
+            )
+    return engine
+
+
+async def _sizes(engine) -> dict[str, tuple]:
+    async with engine.begin() as conn:
+        rows = (await conn.exec_driver_sql("SELECT id, width, height FROM nodes")).fetchall()
+    return {r[0]: (r[1], r[2]) for r in rows}
+
+
+async def _run(engine, monkeypatch) -> None:
+    monkeypatch.setattr(database, "engine", engine)
+    await database._backfill_zone_size()
+
+
+async def test_moves_the_size_from_the_blob_to_the_columns(tmp_path, monkeypatch):
+    engine = await _engine(
+        tmp_path,
+        [("z1", "groupRect", {"width": 640, "height": 480, "border": "#0ff"}, None, None)],
+    )
+
+    await _run(engine, monkeypatch)
+
+    assert (await _sizes(engine))["z1"] == (640, 480)
+    # The style the blob actually owns is untouched.
+    async with engine.begin() as conn:
+        blob = (await conn.exec_driver_sql("SELECT custom_colors FROM nodes")).scalar()
+    assert json.loads(blob)["border"] == "#0ff"
+    await engine.dispose()
+
+
+async def test_never_overwrites_a_size_already_in_the_columns(tmp_path, monkeypatch):
+    # A zone resized since the upgrade: the column is the truth, and a stale
+    # blob left over from before must not win.
+    engine = await _engine(
+        tmp_path,
+        [("z1", "groupRect", {"width": 111, "height": 222}, 800, None)],
+    )
+
+    await _run(engine, monkeypatch)
+
+    assert (await _sizes(engine))["z1"] == (800, 222)
+    await engine.dispose()
+
+
+async def test_leaves_other_node_types_alone(tmp_path, monkeypatch):
+    # Only zones ever stashed their size in the blob. A width key on any other
+    # type is not geometry we should be moving.
+    engine = await _engine(tmp_path, [("s1", "server", {"width": 999}, None, None)])
+
+    await _run(engine, monkeypatch)
+
+    assert (await _sizes(engine))["s1"] == (None, None)
+    await engine.dispose()
+
+
+async def test_skips_a_blob_with_no_usable_size(tmp_path, monkeypatch):
+    engine = await _engine(
+        tmp_path,
+        [
+            ("colors_only", "groupRect", {"border": "#0ff"}, None, None),
+            ("not_a_number", "groupRect", {"width": "wide", "height": True}, None, None),
+            ("no_blob", "groupRect", None, None, None),
+        ],
+    )
+
+    await _run(engine, monkeypatch)
+
+    sizes = await _sizes(engine)
+    assert sizes["colors_only"] == (None, None)
+    assert sizes["not_a_number"] == (None, None)
+    assert sizes["no_blob"] == (None, None)
+    await engine.dispose()
+
+
+async def test_survives_a_corrupt_blob_without_killing_boot(tmp_path, monkeypatch):
+    engine = create_async_engine(f"sqlite+aiosqlite:///{tmp_path / 'zones.db'}")
+    async with engine.begin() as conn:
+        await conn.exec_driver_sql(_DDL)
+        await conn.exec_driver_sql(
+            "INSERT INTO nodes (id, type, label, custom_colors) VALUES ('bad', 'groupRect', 'b', '{oops')"
+        )
+        await conn.exec_driver_sql(
+            "INSERT INTO nodes (id, type, label, custom_colors) "
+            "VALUES ('good', 'groupRect', 'g', '{\"width\": 500, \"height\": 400}')"
+        )
+
+    await _run(engine, monkeypatch)
+
+    sizes = await _sizes(engine)
+    assert sizes["bad"] == (None, None)
+    # One unreadable row must not cost the others their size.
+    assert sizes["good"] == (500, 400)
+    await engine.dispose()
+
+
+async def test_is_idempotent(tmp_path, monkeypatch):
+    engine = await _engine(
+        tmp_path,
+        [("z1", "groupRect", {"width": 640, "height": 480}, None, None)],
+    )
+
+    await _run(engine, monkeypatch)
+    await _run(engine, monkeypatch)
+
+    assert (await _sizes(engine))["z1"] == (640, 480)
+    await engine.dispose()

backend/tests/test_zwave_router.py

@@ -601,3 +601,79 @@ async def test_sync_now_rejected_without_host(
 async def test_sync_now_requires_auth(client: AsyncClient) -> None:
     res = await client.post("/api/v1/zwave/sync-now")
     assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_import_also_lands_in_device_inventory(
+    client: AsyncClient, headers: dict, db_session
+) -> None:
+    """A canvas import is an import: the devices reach the Device Inventory too."""
+    from sqlalchemy import select
+
+    from app.db.models import InventoryDevice
+
+    with patch("app.api.routes.zwave.fetch_zwave_network") as mock_fetch:
+        mock_fetch.return_value = (_SAMPLE_NODES, _SAMPLE_EDGES)
+        res = await client.post(
+            "/api/v1/zwave/import",
+            json={"mqtt_host": "localhost", "mqtt_port": 1883},
+            headers=headers,
+        )
+    assert res.status_code == 200
+
+    rows = (
+        await db_session.execute(
+            select(InventoryDevice).where(InventoryDevice.discovery_source == "zwave")
+        )
+    ).scalars().all()
+    by_ieee = {r.ieee_address: r for r in rows}
+    assert set(by_ieee) == {"zwave-0xh-1", "zwave-0xh-2"}
+
+    # Every returned node names the row it draws, so the canvas save links to it
+    # rather than minting a second one.
+    for node in res.json()["nodes"]:
+        assert node["device_id"] == by_ieee[node["ieee_address"]].id
+
+
+@pytest.mark.asyncio
+async def test_import_reuses_the_existing_inventory_row(
+    client: AsyncClient, headers: dict, db_session
+) -> None:
+    """A device already in the inventory is pointed at, not duplicated."""
+    from sqlalchemy import select
+
+    from app.db.models import InventoryDevice
+
+    existing = InventoryDevice(
+        ieee_address="zwave-0xh-1",
+        friendly_name="Controller",
+        status="pending",
+        discovery_source="zwave",
+    )
+    db_session.add(existing)
+    await db_session.commit()
+    existing_id = existing.id
+
+    with patch("app.api.routes.zwave.fetch_zwave_network") as mock_fetch:
+        mock_fetch.return_value = (_SAMPLE_NODES, _SAMPLE_EDGES)
+        res = await client.post(
+            "/api/v1/zwave/import",
+            json={"mqtt_host": "localhost", "mqtt_port": 1883},
+            headers=headers,
+        )
+    assert res.status_code == 200
+
+    count = len(
+        (
+            await db_session.execute(
+                select(InventoryDevice).where(
+                    InventoryDevice.ieee_address == "zwave-0xh-1"
+                )
+            )
+        ).scalars().all()
+    )
+    assert count == 1
+    coordinator = next(
+        n for n in res.json()["nodes"] if n["ieee_address"] == "zwave-0xh-1"
+    )
+    assert coordinator["device_id"] == existing_id

docker-compose.prebuilt.yml

@@ -13,6 +13,12 @@ services:
       - homelable
     cap_add:
       - NET_RAW
+    # MAC addresses: on this bridge network the scanner can never see them —
+    # ARP is layer 2 and every LAN host is one hop away behind the Docker
+    # gateway. To collect MACs (and so keep DHCP devices matched across an IP
+    # change), put the backend on the LAN: comment out the `networks:` key
+    # above and uncomment the line below (Linux hosts only).
+    # network_mode: host
 
   frontend:
     image: ghcr.io/pouzor/homelable-frontend:latest

docker-compose.yml

@@ -16,6 +16,12 @@ services:
     # Required for ping-based status checks
     cap_add:
       - NET_RAW
+    # MAC addresses: on this bridge network the scanner can never see them —
+    # ARP is layer 2 and every LAN host is one hop away behind the Docker
+    # gateway. To collect MACs (and so keep DHCP devices matched across an IP
+    # change), put the backend on the LAN: comment out the `networks:` key
+    # above and uncomment the line below (Linux hosts only).
+    # network_mode: host
     healthcheck:
       test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/health"]
       interval: 10s
@@ -43,6 +49,10 @@ services:
     build:
       context: .
       dockerfile: Dockerfile.frontend
+      args:
+        # Serve Homelable under a subpath, e.g. VITE_BASE_PATH=/homelab/ in .env.
+        # Defaults to the root — see docs/INSTALLATION.md.
+        VITE_BASE_PATH: ${VITE_BASE_PATH:-/}
     restart: unless-stopped
     ports:
       - "3000:80"

docker/nginx.standalone.subpath.conf.template

@@ -0,0 +1,26 @@
+# Standalone (no backend) Homelable served under a subpath (__BASE__).
+# Generated at image build time — see docker/nginx.subpath.conf.template.
+server {
+    listen 80;
+    server_name _;
+    root /usr/share/nginx/html;
+    index index.html;
+    # Relative Location headers — the port and scheme belong to whatever proxy is
+    # in front, not to this server block.
+    absolute_redirect off;
+
+    location = __BASE_NO_SLASH__ {
+        return 301 __BASE__;
+    }
+
+    # SPA fallback under the prefix — no backend proxy
+    location __BASE__ {
+        try_files $uri $uri/ __BASE__index.html;
+    }
+
+    # Same, for a front proxy that strips the prefix before forwarding
+    location / {
+        root /usr/share/nginx/html__BASE_NO_SLASH__;
+        try_files $uri $uri/ /index.html;
+    }
+}

docker/nginx.subpath.conf.template

@@ -0,0 +1,86 @@
+# Homelable served under a subpath (__BASE__) instead of the root of the origin.
+#
+# Generated at image build time by Dockerfile.frontend when VITE_BASE_PATH is set:
+# __BASE__ is the prefix with its trailing slash, __BASE_NO_SLASH__ without it. A
+# default build keeps docker/nginx.conf and this file is never read.
+#
+# The static build is copied to /usr/share/nginx/html__BASE__, so every block below
+# uses plain `root` semantics — `alias` plus `try_files` mis-resolves $uri.
+#
+# Both reverse-proxy styles work against this config:
+#   - prefix forwarded intact  (proxy_pass http://homelable;)  -> the __BASE__ blocks
+#   - prefix stripped          (proxy_pass http://homelable/;) -> the trailing blocks
+server {
+    listen 80;
+    server_name _;
+    root /usr/share/nginx/html;
+    index index.html;
+    # Relative Location headers — the port and scheme belong to whatever proxy is
+    # in front, not to this server block.
+    absolute_redirect off;
+
+    # --- prefix forwarded intact ------------------------------------------------
+    location = __BASE_NO_SLASH__ {
+        return 301 __BASE__;
+    }
+
+    # WebSocket (must come before the API block to take priority)
+    location __BASE__api/v1/status/ws/ {
+        proxy_pass http://backend:8000/api/v1/status/ws/;
+        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 __BASE__api/ {
+        proxy_pass http://backend:8000/api/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    # Legacy /ws/ path
+    location __BASE__ws/ {
+        proxy_pass http://backend:8000/ws/;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+    }
+
+    # SPA fallback under the prefix
+    location __BASE__ {
+        try_files $uri $uri/ __BASE__index.html;
+    }
+
+    # --- prefix already stripped by the front proxy -----------------------------
+    # No redirect to __BASE__ here: the front proxy would strip it again and loop.
+    location /api/v1/status/ws/ {
+        proxy_pass http://backend: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://backend:8000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    location /ws/ {
+        proxy_pass http://backend:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+    }
+
+    location / {
+        root /usr/share/nginx/html__BASE_NO_SLASH__;
+        try_files $uri $uri/ /index.html;
+    }
+}

docs/documentation.md

@@ -0,0 +1,249 @@
+# Documentation
+
+A markdown document per device, plus a free-form Library of pages and folders,
+behind the **Documentation** entry in the left sidebar.
+
+Before this, the only writing surface in Homelable was `device_inventory.notes`
+— one `TEXT` column rendered as plain text. This replaces it with something that
+can be structured, linked, searched and kept honest, without ever throwing the
+old notes away.
+
+---
+
+## The model
+
+Three tables. See `docs/database-model.md` for the columns.
+
+| Table | What |
+|---|---|
+| `documents` | One markdown document. Either a Library `page`/`folder`, or a `device` / `node` / `design` document describing exactly one thing. |
+| `document_revisions` | Prior bodies, pruned to the most recent 50 per document. |
+| `documents_fts` | The FTS5 search index. Optional — see *Search* below. |
+
+**A document attaches to the device, not to the node.** Since 3.3.0 a node draws
+a device and the facts live on `device_inventory`, so one device reads the same
+on every canvas it appears on.
+
+**Every link is `SET NULL` and the title is denormalized.** Deleting a device or
+a canvas never destroys what was written: the document survives as an orphan and
+can be re-linked or filed into the Library. Foreign keys are off in this SQLite
+setup, so the delete paths clear the columns by hand through
+`app/services/doc_links.py::unlink_documents` — `nodes`, `scan` and `designs`
+each call it before they delete.
+
+**A folder is a document** (`kind='folder'`). That is what allows an empty
+folder, and lets a folder carry an index body.
+
+**One document per target.** Enforced twice: a 409 in the route, and partial
+unique indexes created in `init_db` (`DOCUMENT_DDL` in `db/database.py` —
+`create_all` cannot express a partial index or a virtual table).
+
+---
+
+## The generated header
+
+`app/services/doc_template.py` scaffolds a device document from the live facts:
+addresses, hardware, one section per fingerprinted service, rack and zone
+placement, canvas neighbours, custom properties. Old `notes` are appended
+verbatim under `## Notes` behind an HTML-comment provenance marker.
+
+**It is generated once and then belongs to the user.** Nothing rewrites a body
+that already exists. Two things keep it from going stale silently:
+
+- `facts_snapshot` records the facts as they read at generation time, so the UI
+  can say *the device has changed* and list what.
+- `GET /api/v1/documents/blocks?block=…&device_id=…` renders any single block on
+  demand — that is what the editor's `/device`, `/services`, `/rack`… commands
+  insert. Regeneration is always one keystroke away, and never automatic.
+
+A section whose data is empty is still emitted, with an italic prompt: the
+document is a checklist of what has not been written yet. Sections that are
+structural rather than descriptive — the rack position of an unracked device —
+are dropped instead.
+
+Service URLs in a document follow `frontend/src/utils/serviceUrl.ts`, including
+its non-HTTP port denylist, so a link in a document is the link the canvas
+offers.
+
+---
+
+## The tree
+
+Two roots, with different natures.
+
+**Devices** is a pivot, rebuilt client-side in
+`frontend/src/documentation/tree.ts` from data the app already holds. Grouping
+by zone, group, type, physical/virtual, subnet, canvas, rack, vendor, discovery
+source, status, tag, or flat A–Z is instant and needs no server round trip.
+
+- Zone and group come from walking `parent_id` up to the nearest `groupRect` /
+  `group` node.
+- Subnet prefers a configured scanner range, else the address's own /24. A
+  device with several IPs appears under each subnet it reaches.
+- Physical / Virtual / Host is derived: `vm`/`lxc`/`docker_container` are
+  virtual, `proxmox`/`docker_host` and anything drawn as a container are hosts.
+- Canvas answers "on the loaded canvas or not" — the app only holds one at a
+  time.
+
+**Library** is the real folder tree, ordered by `sort_order` then title.
+
+Badges: `·` no document, `○` only the generated header, `●` written, `⚠` the
+device changed since, `⏰` past its `review_every`.
+
+---
+
+## Editing
+
+Markdown source on the left, live preview on the right. Source rather than a
+rich editor on purpose: the body is exported verbatim, so what is typed is what
+the file holds.
+
+**Saving is explicit** — Ctrl/Cmd+S or the Save button — matching the canvas
+rule that nothing persists on a timer. An unsaved body is mirrored to
+`localStorage` under `homelable_docdraft:<id>` on every keystroke and cleared on
+save. On reopening, a draft taken against the version being opened is *offered*;
+a draft taken against an older version is discarded, because replaying it would
+revert a change made elsewhere.
+
+`/` at the start of a line opens the insert menu: the generated blocks above,
+plus table, checklist, callout, wiki-link and date.
+
+`[[` opens the link picker, anywhere in the line: filter by title, pick, and the
+finished link is written for you. It offers documents only — a device with no
+document is not a link target yet — and it addresses a document by title, or by
+`[[doc:<id>]]` when another document shares that title, since a bare link
+resolves by title and an ambiguous one would silently pick the first. The second
+bracket is held back while the menu is open (opening it moves focus, and a
+keystroke landing mid-move belongs to neither box) and given back if you cancel,
+so what you typed survives either way.
+
+---
+
+## Links between documents
+
+`[[device:nas-01]]`, `[[doc:vlan-plan]]`, `[[node:<id>]]`, or a bare
+`[[VLAN plan]]`; `[[…|label]]` sets the text. A device resolves by id or label,
+a document by id, slug, then title, all case-insensitively. An unresolved link
+renders red and offers to create the document.
+
+Parsed as a text pass over the rendered children (`wikilinks.ts` +
+`markdown/WikiText.tsx`) rather than as a remark plugin, so the file stays
+ordinary markdown for anything else that reads it.
+
+**Raw HTML is deliberately not rendered** — `rehype-raw` is absent — so a
+document cannot inject markup and no sanitiser is needed.
+
+### Backlinks
+
+Every document lists what points at it, under **Linked from**, with the line the
+link was written on and the label it was written as.
+
+The inversion is done **server-side** (`services/doc_backlinks.py`,
+`GET /documents/{id}/backlinks`), because the browser holds no bodies but the
+open one: `GET /documents` is metadata-only so the tree can badge without
+downloading the space. That service mirrors the resolution rules in
+`wikilinks.ts` — same prefixes, same id → slug → title fallback, same
+case-insensitivity — the way the generator's `service_url` mirrors
+`utils/serviceUrl.ts`. Change one and change the other;
+`test_doc_backlinks.py` pins the rules.
+
+Repeated links from the same document collapse into one entry with a count, and
+a document never backlinks itself. The inventory is only loaded when some body
+actually carries a `[[device:…]]`.
+
+---
+
+## History
+
+Every explicit save that changes the body snapshots the previous one, capped at
+`REVISION_LIMIT` (50) per document; so do restore, regenerate, scaffold and the
+notes migration, each recording why.
+
+The clock-arrow button in the header opens the history rail: what each version
+was (Saved, Regenerated, Restored, Migrated from notes…), when, and how big.
+Selecting one replaces the body with that version — same title, same chips, same
+rail — and **Changes** turns it into a line diff against the current body, with
+long unchanged runs collapsed. **Restore** brings it back, snapshotting the body
+it replaces first, so a restore is itself undoable.
+
+A revision's body is fetched only when it is opened: the list carries a size, not
+the text, so fifty versions cost one small request.
+
+The diff is a plain LCS over lines (`documentation/diff.ts`), after the common
+head and tail are trimmed — no diff library, and a pathological pair of long,
+wholly different bodies degrades to "replaced wholesale" instead of building a
+250k-cell matrix.
+
+---
+
+## Search
+
+`GET /api/v1/documents/search?q=` over title, tags and body.
+
+The same index answers the canvas' own search modal (Ctrl/Cmd+K), which lists
+matching documents under the nodes and pending devices; picking one switches to
+Documentation and opens it. The request is debounced and skipped below two
+characters, and a failure there costs only the document rows — the node and
+device halves filter lists already in memory.
+
+FTS5 is **not** assumed: the SQLite shipped in the LXC and Docker images may be
+built without it, the same reason `database.py` avoids JSON1. `doc_search.py`
+probes once and falls back to `LIKE`, and the response says which engine
+answered (`fts5` or `like`) so the UI can drop snippet highlighting. The index is
+maintained from Python on every write — no triggers — and `_reindex_documents_fts`
+catches up on boot after an upgrade or a restored backup.
+
+User input is never FTS5 syntax: `build_match_query` quotes every term, so an
+IP or a stray quote is data.
+
+---
+
+## Migrating the old notes
+
+Non-destructive and repeatable.
+
+1. `GET /api/v1/documents/coverage` reports `notes_unmigrated`.
+2. A banner offers to migrate.
+3. `POST /api/v1/documents/scaffold {"only_with_notes": true}` creates one
+   document per device, old notes appended verbatim, with a `migrate` revision.
+4. **`device_inventory.notes` is left exactly as it was.** It is still the
+   column the HACS integration, the YAML export, the MCP tools and the canvas
+   search read. Deprecating it is a separate decision.
+
+---
+
+## API
+
+| Method | Path |
+|---|---|
+| `GET` | `/api/v1/documents` — metadata only, filterable by `kind`, `parent_id`, `device_id`, `tag` |
+| `GET` | `/api/v1/documents/{id}` |
+| `POST` | `/api/v1/documents` |
+| `PATCH` | `/api/v1/documents/{id}` |
+| `DELETE` | `/api/v1/documents/{id}` — a folder takes its subtree |
+| `GET` | `/api/v1/documents/{id}/revisions`, `/revisions/{rev_id}` |
+| `GET` | `/api/v1/documents/{id}/backlinks` — the documents linking here |
+| `POST` | `/api/v1/documents/{id}/revisions/{rev_id}/restore` |
+| `POST` | `/api/v1/documents/{id}/regenerate` — erase the body and scaffold it again |
+| `GET` | `/api/v1/documents/search?q=&limit=` |
+| `GET` | `/api/v1/documents/blocks?block=&device_id=` |
+| `GET` | `/api/v1/documents/coverage` |
+| `POST` | `/api/v1/documents/scaffold` |
+
+---
+
+## Standalone mode
+
+Documents are **full-mode only**. Standalone has no backend to store or search
+them, and the same reasoning as ADR-001 applies: the section is hidden in the
+sidebar and explains itself if reached directly, rather than being polyfilled
+into `localStorage` with no search and no history.
+
+---
+
+## Not built yet
+
+Export/import of the tree as `.md` files, a print/handbook view, an aggregated
+open-tasks view, image upload inside a document (would reuse
+`api/routes/media.py`, full-mode only), and the MCP tools — those are the
+planned second lot.

docs/rack-canvas.md

@@ -236,7 +236,8 @@ diagram's online/offline tally. **PNG export** works here too.
 - No power draw or outlet budgeting.
 - No undo/redo on a rack canvas (the diagram canvas keeps its own).
 - Rack canvases are not shown by the read-only [Live View](../README.md#live-view-read-only-public-canvas).
-- The MCP server exposes diagram nodes and links only, not racks.
+- The MCP server can read and edit a rack canvas, but its save is last-writer-wins:
+  an AI write while you have the canvas open with unsaved changes loses one side.
 
 ---
 

docs/zigbee-import.md

@@ -55,9 +55,25 @@ Click **Fetch Devices**. Homelable will:
 1. Connect to the broker
 2. Subscribe to the response topic
 3. Publish `{"type": "raw", "routes": false}` to the request topic
-4. Wait up to 60 seconds for the network map response (large meshes can take 30 s+)
+4. Wait up to `ZIGBEE_NETWORKMAP_TIMEOUT` seconds (default 300) for the network map response
 5. Parse and group devices by type
 
+The fetch runs server-side and the browser polls for the result, so a mesh that
+takes minutes to answer cannot be cut short by a reverse proxy's read timeout.
+
+### Large meshes and timeouts
+
+A network of 200+ devices can take several minutes to build its map. Two knobs:
+
+| Variable | Default | What it bounds |
+|---|---|---|
+| `ZIGBEE_NETWORKMAP_TIMEOUT` | `300` | Seconds to wait for the Z2M bridge to answer a networkmap request. Raise it if an import fails with *Timed out waiting for networkmap response*. |
+| `MQTT_RESPONSE_TIMEOUT` | `300` | The same bound for the Z-Wave MQTT round-trip. |
+
+Both apply to manual imports and to auto-sync. If you reverse-proxy the API,
+these are the only timeouts that matter — the import request itself returns
+immediately.
+
 ### 5. Select and add to canvas
 
 Devices are grouped by type (Coordinator / Router / End Device).  

frontend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frontend",
   "private": true,
-  "version": "3.3.0",
+  "version": "3.4.1",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -31,6 +31,9 @@
     "next-themes": "^0.4.6",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
+    "react-markdown": "^10.1.0",
+    "rehype-slug": "^6.0.0",
+    "remark-gfm": "^4.0.1",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
     "tw-animate-css": "^1.4.0",

frontend/public/brand/homelable.svg

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

frontend/src/App.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useCallback, useMemo, useRef, useState } from 'react'
+import { useEffect, useCallback, useMemo, useRef, useState, lazy, Suspense } from 'react'
 import { ReactFlowProvider, type Connection, type Edge } from '@xyflow/react'
 import { type Node } from '@xyflow/react'
 import { applyDagreLayout } from '@/utils/layout'
@@ -9,12 +9,15 @@ import { resolveVirtualEdgeParent } from '@/utils/virtualEdgeParent'
 import { generateMarkdownTable } from '@/utils/exportMarkdown'
 import { copyToClipboard } from '@/utils/clipboard'
 import { getDesignIdFromUrl, setDesignIdInUrl } from '@/utils/designUrl'
+import { useDocsUrlSync } from '@/hooks/useDocsUrlSync'
+import { withBase } from '@/utils/basePath'
 import { ExportModal } from '@/components/modals/ExportModal'
 import { exportCanvasToYaml, downloadYaml } from '@/utils/exportYaml'
 import { parseYamlToCanvas } from '@/utils/importYaml'
 import { TooltipProvider } from '@/components/ui/tooltip'
 import { Toaster } from '@/components/ui/sonner'
 import { toast } from 'sonner'
+import { isZoneSubnetCandidate } from '@/utils/subnet'
 import { CanvasContainer } from '@/components/canvas/CanvasContainer'
 import { Sidebar } from '@/components/panels/Sidebar'
 import { Toolbar } from '@/components/panels/Toolbar'
@@ -52,24 +55,35 @@ import { WalkthroughOverlay } from '@/walkthrough/WalkthroughOverlay'
 import { DEMO_SCAN_RUNS, DEMO_INVENTORY_DEVICES } from '@/walkthrough/demoTourData'
 import { useStatusPolling } from '@/hooks/useStatusPolling'
 import { bootstrapAuth } from '@/auth/bootstrap'
+// Code-split: the Documentation section pulls in the markdown renderer, which a
+// user who never leaves the canvas should not pay for on first load.
+const DocumentationView = lazy(async () => ({
+  default: (await import('@/documentation/components/DocumentationView')).DocumentationView,
+}))
+import { useDocsStore } from '@/documentation/store'
+import { useUiStore } from '@/stores/uiStore'
 import { RackCanvas } from '@/rack/components/RackCanvas'
 import { RackCablePanel } from '@/rack/components/RackCablePanel'
 import { useRackStore } from '@/rack/store'
 import type { NodeData, EdgeData, CustomStyleDef, DesignType, FloorMapConfig, NodeType } from '@/types'
 import type { ZigbeeNode, ZigbeeEdge } from '@/components/zigbee/types'
 import type { ZwaveNode, ZwaveEdge } from '@/components/zwave/types'
-import type { ProxmoxNode, ProxmoxEdge } from '@/components/proxmox/types'
+import type { ProxmoxNode, ProxmoxEdge, ProxmoxCanvasMode } from '@/components/proxmox/types'
 import { buildProxmoxClusterEdges } from '@/components/proxmox/clusterEdges'
+import { groupProxmoxGuests, layoutProxmoxContainers, measureProxmoxContainers } from '@/utils/proxmoxContainerLayout'
 
 const STANDALONE = import.meta.env.VITE_STANDALONE === 'true'
 
 export default function App() {
-  const { loadCanvas, applyLayout, markSaved, markUnsaved, hasUnsavedChanges, editSeq, selectedNodeId, selectedNodeIds, addNode, updateNode, deleteNode, onConnect, updateEdge, deleteEdge, setProxmoxContainerMode, setNodeZIndex, editingGroupRectId, setEditingGroupRectId, editingTextId, setEditingTextId, nodes, edges, snapshotHistory, undo, redo, addToGroup, addToContainer, addToZone, floorMap, setFloorMap } = useCanvasStore()
+  const { loadCanvas, applyLayout, markSaved, markUnsaved, hasUnsavedChanges, editSeq, selectedNodeId, selectedNodeIds, addNode, updateNode, deleteNode, onConnect, updateEdge, deleteEdge, setProxmoxContainerMode, setNodeZIndex, editingGroupRectId, setEditingGroupRectId, editingTextId, setEditingTextId, nodes, edges, snapshotHistory, undo, redo, addNodesToGroup, addNodesToContainer, addNodesToZone, importZoneSubnet, floorMap, setFloorMap } = useCanvasStore()
   const canvasRef = useRef<HTMLDivElement>(null)
   const { isAuthenticated, isInitialized } = useAuthStore()
   const authBootstrapStarted = useRef(false)
   const { activeTheme, setTheme, customStyle, setCustomStyle } = useThemeStore()
   const { activeDesignId, activeDesignType, setDesigns, setActiveDesign } = useDesignStore()
+  const appView = useUiStore((s) => s.view)
+  const setAppView = useUiStore((s) => s.setView)
+  const openDocId = useDocsStore((s) => s.openDoc?.id ?? null)
   const isRackDesign = activeDesignType === 'rack'
   const rackDirty = useRackStore((s) => s.hasUnsavedChanges)
   const rackEditSeq = useRackStore((s) => s.editSeq)
@@ -131,9 +145,14 @@ export default function App() {
   const [addTextOpen, setAddTextOpen] = useState(false)
   const [editNodeId, setEditNodeId] = useState<string | null>(null)
   const [pendingConnection, setPendingConnection] = useState<Connection | null>(null)
-  const [pendingGroupAdd, setPendingGroupAdd] = useState<{ nodeId: string; groupId: string } | null>(null)
-  const [pendingContainerAdd, setPendingContainerAdd] = useState<{ nodeId: string; containerId: string } | null>(null)
-  const [pendingZoneAdd, setPendingZoneAdd] = useState<{ nodeId: string; zoneId: string } | null>(null)
+  const [pendingGroupAdd, setPendingGroupAdd] = useState<{ nodeIds: string[]; groupId: string } | null>(null)
+  const [pendingContainerAdd, setPendingContainerAdd] = useState<{ nodeIds: string[]; containerId: string } | null>(null)
+  const [pendingZoneAdd, setPendingZoneAdd] = useState<{ nodeIds: string[]; zoneId: string } | null>(null)
+  // Labels for the add-to-group/container/zone confirmation, in the order dropped.
+  const labelsOf = useCallback(
+    (ids: string[]) => ids.map((id) => nodes.find((n) => n.id === id)?.data.label ?? ''),
+    [nodes],
+  )
   const [editEdgeId, setEditEdgeId] = useState<string | null>(null)
   const [scanConfigOpen, setScanConfigOpen] = useState(false)
   const [settingsOpen, setSettingsOpen] = useState(false)
@@ -470,6 +489,35 @@ export default function App() {
     if (activeDesignId) setDesignIdInUrl(activeDesignId)
   }, [activeDesignId])
 
+  // A document is linkable in the same way: `?view=docs&doc=<id>` — written on
+  // every change, and read back on boot so a refresh reopens it.
+  const restoreDocsUrl = useCallback(
+    async (docId: string | null) => {
+      setAppView('documentation')
+      if (docId) await useDocsStore.getState().open(docId)
+    },
+    [setAppView],
+  )
+  useDocsUrlSync({
+    view: appView,
+    openDocId,
+    ready: isAuthenticated,
+    enabled: !STANDALONE,
+    onRestore: restoreDocsUrl,
+  })
+
+  // The canvas' way into Documentation: it knows a device id, and the section
+  // resolves that to a document — writing one from the device's facts when
+  // there is none, exactly as picking the device in its tree would.
+  const openDocumentationFor = useCallback(
+    async (deviceId: string, label: string) => {
+      setAppView('documentation')
+      const ok = await useDocsStore.getState().openForDevice(deviceId, label)
+      if (!ok) toast.error('Could not open the documentation for that device')
+    },
+    [setAppView],
+  )
+
   // Keep refs for store actions so keydown handler is always up-to-date without re-registering
   const undoRef = useRef(undo)
   const redoRef = useRef(redo)
@@ -485,8 +533,19 @@ export default function App() {
       const isInput = tag === 'INPUT' || tag === 'TEXTAREA' || (e.target as HTMLElement).isContentEditable
 
       if (ctrl && e.key === 's') { e.preventDefault(); handleSaveRef.current(); return }
-      if (ctrl && e.key === 'z') { e.preventDefault(); undoRef.current(); return }
-      if (ctrl && (e.key === 'y' || (e.shiftKey && e.key === 'z'))) { e.preventDefault(); redoRef.current(); return }
+      // Undo belongs to whatever is being typed in — the document editor keeps
+      // its own history, a plain field has the browser's — and the canvas only
+      // gets it when nothing has the caret.
+      if (ctrl && e.key.toLowerCase() === 'z') {
+        if (isInput) return
+        e.preventDefault()
+        // Shift+Z is the other redo, and matched neither branch while both
+        // compared a lowercase key — a shifted `z` arrives as `Z`.
+        if (e.shiftKey) redoRef.current()
+        else undoRef.current()
+        return
+      }
+      if (ctrl && e.key.toLowerCase() === 'y') { if (isInput) return; e.preventDefault(); redoRef.current(); return }
       if (ctrl && e.key === 'k') { e.preventDefault(); setSearchOpen(true); return }
       // Copy/paste (Ctrl/Cmd+C/V) handled in CanvasContainer so paste can place
       // nodes under the cursor / viewport center.
@@ -526,6 +585,26 @@ export default function App() {
     toast.success(`Added "${data.label}"`)
   }, [addNode, nodes, snapshotHistory])
 
+  // Subnet import is a one-shot action on an existing zone, so on the Add modal
+  // there is no zone to run it against yet: the CIDR is held here and applied
+  // once, right after the zone is created. Cleared whenever that modal closes.
+  const pendingZoneSubnet = useRef<string | null>(null)
+
+  const countSubnetMatches = useCallback(
+    (cidr: string, zoneId?: string) =>
+      nodes.filter((n) => isZoneSubnetCandidate(n, cidr, zoneId)).length,
+    [nodes],
+  )
+
+  const reportSubnetImport = useCallback((moved: number, cidr: string) => {
+    if (moved === 0) toast.info(`No unparented device in ${cidr}`)
+    else toast.success(`Moved ${moved} device${moved > 1 ? 's' : ''} from ${cidr} into the zone`)
+  }, [])
+
+  const handleImportSubnetIntoZone = useCallback((zoneId: string, cidr: string) => {
+    reportSubnetImport(importZoneSubnet(zoneId, cidr), cidr)
+  }, [importZoneSubnet, reportSubnetImport])
+
   const handleAddGroupRect = useCallback((data: GroupRectFormData) => {
     snapshotHistory()
     const id = generateUUID()
@@ -535,6 +614,7 @@ export default function App() {
       position: getCenteredPosition(360, 240),
       data: {
         label: data.label,
+        description: data.description,
         type: 'groupRect',
         status: 'unknown',
         services: [],
@@ -556,7 +636,12 @@ export default function App() {
       zIndex: data.z_order - 10,
     }
     addNode(newNode)
-  }, [addNode, snapshotHistory])
+
+    const cidr = pendingZoneSubnet.current
+    pendingZoneSubnet.current = null
+    // addNode has already committed, so the zone is in the store by now.
+    if (cidr) reportSubnetImport(importZoneSubnet(id, cidr), cidr)
+  }, [addNode, snapshotHistory, importZoneSubnet, reportSubnetImport])
 
   const handleUpdateGroupRect = useCallback((data: GroupRectFormData) => {
     if (!editingGroupRectId) return
@@ -564,6 +649,7 @@ export default function App() {
     const existing = nodes.find((n) => n.id === editingGroupRectId)
     updateNode(editingGroupRectId, {
       label: data.label,
+      description: data.description,
       custom_colors: {
         ...existing?.data.custom_colors,
         border: data.border_color,
@@ -740,7 +826,9 @@ export default function App() {
     if (STANDALONE) {
       // Standalone reads canvas from localStorage; pass the active design id so
       // the read-only tab renders the same canvas the user is viewing.
-      const url = activeDesignId ? `/view?design=${encodeURIComponent(activeDesignId)}` : '/view'
+      const url = activeDesignId
+        ? withBase(`view?design=${encodeURIComponent(activeDesignId)}`)
+        : withBase('view')
       window.open(url, '_blank', 'noopener,noreferrer')
       return
     }
@@ -752,7 +840,7 @@ export default function App() {
       }
       const params = new URLSearchParams({ key: res.data.key })
       if (activeDesignId) params.set('design', activeDesignId)
-      window.open(`/view?${params.toString()}`, '_blank', 'noopener,noreferrer')
+      window.open(withBase(`view?${params.toString()}`), '_blank', 'noopener,noreferrer')
     } catch {
       toast.error('Failed to open live view')
     }
@@ -787,6 +875,9 @@ export default function App() {
           type: zn.type as NodeData['type'],
           status: 'unknown' as const,
           services: [],
+          // The import already upserted the Device Inventory row; carry its id so
+          // the canvas save links to that row instead of minting a second one.
+          ...(zn.device_id ? { device_id: zn.device_id } : {}),
           ...(zn.lqi != null ? { properties: [{ key: 'LQI', value: String(zn.lqi), icon: 'signal', visible: true }] } : {}),
           ...(zn.model ? { os: zn.model } : {}),
           ...(zn.parent_id ? { parent_id: zn.parent_id } : {}),
@@ -837,6 +928,8 @@ export default function App() {
           type: zn.type as NodeData['type'],
           status: 'unknown' as const,
           services: [],
+          // Same as the Zigbee import: the row exists already, point at it.
+          ...(zn.device_id ? { device_id: zn.device_id } : {}),
           ...(zn.model ? { os: zn.model } : {}),
           ...(zn.parent_id ? { parent_id: zn.parent_id } : {}),
         },
@@ -862,42 +955,84 @@ export default function App() {
     markUnsaved()
   }, [addNode, onConnect, snapshotHistory, markUnsaved])
 
-  const handleProxmoxAddToCanvas = useCallback((pmNodes: ProxmoxNode[], pmEdges: ProxmoxEdge[]) => {
+  const handleProxmoxAddToCanvas = useCallback((
+    pmNodes: ProxmoxNode[],
+    pmEdges: ProxmoxEdge[],
+    mode: ProxmoxCanvasMode = 'linked',
+  ) => {
     snapshotHistory()
     const COLS = 4
     const SPACING_X = 190
     const SPACING_Y = 110
-    const cols = Math.min(COLS, pmNodes.length)
-    const rows = Math.ceil(pmNodes.length / COLS)
-    const origin = getCenteredPosition(cols * SPACING_X, rows * SPACING_Y)
     // Multiple hosts from one import = a cluster → chain them via left/right
     // 'cluster' edges. Those endpoints need one left + one right handle each
     // (both default to 0), so grant them to the host nodes up front.
     const clusterEdges = buildProxmoxClusterEdges(pmNodes)
     const cluster = clusterEdges.length > 0
-    pmNodes.forEach((pn, i) => {
-      const col = i % COLS
-      const row = Math.floor(i / COLS)
-      const position = { x: origin.x + col * SPACING_X, y: origin.y + row * SPACING_Y }
+
+    // Container mode: each host becomes a box and its guests are nested inside
+    // it. Anything the import gives no host for stays a loose node below.
+    const { hostIds, childrenByHost, hostOfChild, looseIds } = groupProxmoxGuests(pmNodes, pmEdges)
+    const hostIdSet = new Set(hostIds)
+
+    let placement: Record<string, { x: number; y: number }>
+    let hostSizes: Record<string, { width: number; height: number }> = {}
+    if (mode === 'container') {
+      const measured = measureProxmoxContainers(hostIds, childrenByHost, looseIds.length)
+      const origin = getCenteredPosition(measured.width, measured.height)
+      const laid = layoutProxmoxContainers(hostIds, childrenByHost, looseIds, origin)
+      placement = laid.positions
+      hostSizes = laid.hostSizes
+    } else {
+      const cols = Math.min(COLS, pmNodes.length)
+      const rows = Math.ceil(pmNodes.length / COLS)
+      const origin = getCenteredPosition(cols * SPACING_X, rows * SPACING_Y)
+      placement = {}
+      pmNodes.forEach((pn, i) => {
+        placement[pn.id] = {
+          x: origin.x + (i % COLS) * SPACING_X,
+          y: origin.y + Math.floor(i / COLS) * SPACING_Y,
+        }
+      })
+    }
+
+    // Hosts first: addNode resolves `data.parent_id` against the nodes already
+    // in the store, so a guest added before its container would not nest.
+    const ordered = mode === 'container'
+      ? [...pmNodes.filter((n) => hostIdSet.has(n.id)), ...pmNodes.filter((n) => !hostIdSet.has(n.id))]
+      : pmNodes
+    ordered.forEach((pn) => {
+      const position = placement[pn.id] ?? getCenteredPosition()
       const isClusterHost = cluster && pn.type === 'proxmox'
+      const isContainerHost = mode === 'container' && hostIdSet.has(pn.id)
+      const parentId = mode === 'container' ? hostOfChild[pn.id] : undefined
+      const size = hostSizes[pn.id]
       const newNode: import('@xyflow/react').Node<NodeData> = {
         id: pn.id,
         type: pn.type,
         position,
+        ...(isContainerHost && size ? { width: size.width, height: size.height } : {}),
         data: {
           label: pn.label,
           type: pn.type as NodeData['type'],
           status: (pn.status === 'online' ? 'online' : 'unknown') as NodeData['status'],
           services: [],
+          // Same as the Zigbee import: the row exists already, point at it.
+          ...(pn.device_id ? { device_id: pn.device_id } : {}),
           ...(pn.ip ? { ip: pn.ip } : {}),
           ...(pn.hostname ? { hostname: pn.hostname } : {}),
           ...(isClusterHost ? { left_handles: 1, right_handles: 1 } : {}),
+          ...(isContainerHost ? { container_mode: true } : {}),
+          ...(parentId ? { parent_id: parentId } : {}),
         },
       }
       addNode(newNode)
     })
-    // Host → guest links render as 'virtual' edges (VM/LXC ↔ host).
+    // Host → guest links render as 'virtual' edges (VM/LXC ↔ host). A nested
+    // guest gets none: sitting inside the host already says it runs there, and
+    // the edge just loops out of the box and back (#399 follow-up).
     pmEdges.forEach((pe) => {
+      if (hostOfChild[pe.target] === pe.source && mode === 'container') return
       onConnect({
         source: pe.source,
         sourceHandle: 'bottom',
@@ -1032,6 +1167,14 @@ export default function App() {
                 </button>
               </div>
             )}
+            {appView === 'documentation' ? (
+              <Suspense
+                fallback={<div className="flex flex-1 items-center justify-center text-xs text-muted-foreground">Loading documentation…</div>}
+              >
+                <DocumentationView />
+              </Suspense>
+            ) : (
+            <>
             <Toolbar
               onSave={handleSave}
               onAutoLayout={handleAutoLayout}
@@ -1073,9 +1216,16 @@ export default function App() {
                       // Standalone has no Device Inventory to open (ADR-001 style
                       // gate: the whole scan surface is backend-only).
                       onOpenInventory={STANDALONE ? undefined : (deviceId) => openInventoryModal(deviceId)}
+                      onOpenDocumentation={
+                        STANDALONE
+                          ? undefined
+                          : (deviceId, label) => void openDocumentationFor(deviceId, label)
+                      }
                     />
                   )}
             </div>
+            </>
+            )}
           </div>
         </div>
 
@@ -1190,8 +1340,11 @@ export default function App() {
 
         <GroupRectModal
           open={addGroupRectOpen}
-          onClose={() => setAddGroupRectOpen(false)}
+          onClose={() => { pendingZoneSubnet.current = null; setAddGroupRectOpen(false) }}
           onSubmit={handleAddGroupRect}
+          onImportSubnet={(cidr) => { pendingZoneSubnet.current = cidr }}
+          countSubnetMatches={(cidr) => countSubnetMatches(cidr)}
+          importOnSubmit
           title="Add Zone"
         />
 
@@ -1202,12 +1355,17 @@ export default function App() {
           onClose={() => setEditingGroupRectId(null)}
           onSubmit={handleUpdateGroupRect}
           onDelete={handleDeleteGroupRect}
+          onImportSubnet={(cidr) => { if (editingGroupRectId) handleImportSubnetIntoZone(editingGroupRectId, cidr) }}
+          countSubnetMatches={(cidr) => countSubnetMatches(cidr, editingGroupRectId ?? undefined)}
           initial={(() => {
             const n = editingGroupRectId ? nodes.find((nd) => nd.id === editingGroupRectId) : null
             if (!n) return undefined
             const rc = n.data.custom_colors ?? {}
             return {
               label: n.data.label,
+              // `notes` is where a zone description used to try to live; read it
+              // as a fallback so a canvas loaded before the fix still shows it.
+              description: n.data.description ?? n.data.notes ?? '',
               font: rc.font ?? 'inter',
               text_color: rc.text_color ?? '#e6edf3',
               text_position: rc.text_position ?? 'top-left',
@@ -1274,15 +1432,23 @@ export default function App() {
           open={searchOpen}
           onClose={() => setSearchOpen(false)}
           onOpenInventory={(deviceId) => openInventoryModal(deviceId)}
+          onOpenDocument={
+            STANDALONE
+              ? undefined
+              : (docId) => {
+                  setAppView('documentation')
+                  void useDocsStore.getState().open(docId)
+                }
+          }
         />
         <ShortcutsModal open={shortcutsOpen} onClose={() => setShortcutsOpen(false)} />
 
         <ConfirmAddToGroupModal
           open={!!pendingGroupAdd}
-          nodeLabel={pendingGroupAdd ? (nodes.find((n) => n.id === pendingGroupAdd.nodeId)?.data.label ?? '') : ''}
+          nodeLabels={pendingGroupAdd ? labelsOf(pendingGroupAdd.nodeIds) : []}
           targetLabel={pendingGroupAdd ? (nodes.find((n) => n.id === pendingGroupAdd.groupId)?.data.label ?? '') : ''}
           onConfirm={() => {
-            if (pendingGroupAdd) addToGroup(pendingGroupAdd.groupId, pendingGroupAdd.nodeId)
+            if (pendingGroupAdd) addNodesToGroup(pendingGroupAdd.groupId, pendingGroupAdd.nodeIds)
             setPendingGroupAdd(null)
           }}
           onCancel={() => setPendingGroupAdd(null)}
@@ -1291,10 +1457,10 @@ export default function App() {
         <ConfirmAddToGroupModal
           open={!!pendingContainerAdd}
           variant="container"
-          nodeLabel={pendingContainerAdd ? (nodes.find((n) => n.id === pendingContainerAdd.nodeId)?.data.label ?? '') : ''}
+          nodeLabels={pendingContainerAdd ? labelsOf(pendingContainerAdd.nodeIds) : []}
           targetLabel={pendingContainerAdd ? (nodes.find((n) => n.id === pendingContainerAdd.containerId)?.data.label ?? '') : ''}
           onConfirm={() => {
-            if (pendingContainerAdd) addToContainer(pendingContainerAdd.containerId, pendingContainerAdd.nodeId)
+            if (pendingContainerAdd) addNodesToContainer(pendingContainerAdd.containerId, pendingContainerAdd.nodeIds)
             setPendingContainerAdd(null)
           }}
           onCancel={() => setPendingContainerAdd(null)}
@@ -1303,10 +1469,10 @@ export default function App() {
         <ConfirmAddToGroupModal
           open={!!pendingZoneAdd}
           variant="zone"
-          nodeLabel={pendingZoneAdd ? (nodes.find((n) => n.id === pendingZoneAdd.nodeId)?.data.label ?? '') : ''}
+          nodeLabels={pendingZoneAdd ? labelsOf(pendingZoneAdd.nodeIds) : []}
           targetLabel={pendingZoneAdd ? (nodes.find((n) => n.id === pendingZoneAdd.zoneId)?.data.label ?? '') : ''}
           onConfirm={() => {
-            if (pendingZoneAdd) addToZone(pendingZoneAdd.zoneId, pendingZoneAdd.nodeId)
+            if (pendingZoneAdd) addNodesToZone(pendingZoneAdd.zoneId, pendingZoneAdd.nodeIds)
             setPendingZoneAdd(null)
           }}
           onCancel={() => setPendingZoneAdd(null)}
@@ -1319,6 +1485,14 @@ export default function App() {
         <DeviceInventoryModal
           open={inventoryModalOpen}
           onClose={() => setInventoryModalOpen(false)}
+          onOpenDocumentation={
+            STANDALONE
+              ? undefined
+              : (deviceId, label) => {
+                  setInventoryModalOpen(false)
+                  void openDocumentationFor(deviceId, label)
+                }
+          }
           highlightId={inventoryHighlightId}
           initialStatus={inventoryModalStatus}
           demoDevices={tourInventoryDemo ? DEMO_INVENTORY_DEVICES : undefined}

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

@@ -70,6 +70,19 @@ describe('api/client', () => {
     expect(publicApi.defaults.baseURL).toBe('/api/v1')
   })
 
+  it('mounts both instances under a configured base path', async () => {
+    const before = instances.length
+    vi.stubEnv('BASE_URL', '/homelab/')
+    vi.resetModules()
+    await import('../client')
+    const [subApi, subPublicApi] = instances.slice(before)
+    expect(subApi.defaults.baseURL).toBe('/homelab/api/v1')
+    expect(subApi.defaults.withCredentials).toBe(true)
+    expect(subPublicApi.defaults.baseURL).toBe('/homelab/api/v1')
+    vi.unstubAllEnvs()
+    vi.resetModules()
+  })
+
   it('exports `api` matching the first created instance', () => {
     expect(mod.api).toBe(api)
   })
@@ -242,6 +255,11 @@ describe('api/client', () => {
     expect(api.post).toHaveBeenCalledWith('/zigbee/import-pending', cfg)
   })
 
+  it('zigbeeApi.getImportJob polls the job by id', () => {
+    mod.zigbeeApi.getImportJob('job-1')
+    expect(api.get).toHaveBeenCalledWith('/zigbee/import/job-1')
+  })
+
   it('zwaveApi.testConnection/importNetwork/importToPending', () => {
     const cfg = { mqtt_host: 'h', mqtt_port: 1883, prefix: 'zwave', gateway_name: 'zwavejs2mqtt' }
     mod.zwaveApi.testConnection(cfg)

frontend/src/api/client.ts

@@ -1,15 +1,16 @@
 import axios from 'axios'
+import { API_BASE_URL } from '@/utils/basePath'
 import { useAuthStore } from '@/stores/authStore'
 import type { AuthMode, AuthUser } from '@/stores/authStore'
 import type { InventoryEntry } from '@/types'
 
 export const api = axios.create({
-  baseURL: '/api/v1',
+  baseURL: API_BASE_URL,
   withCredentials: true,
 })
 
 // Unauthenticated axios instance — no JWT, no 401 redirect (used for public endpoints)
-const publicApi = axios.create({ baseURL: '/api/v1' })
+const publicApi = axios.create({ baseURL: API_BASE_URL })
 
 api.interceptors.request.use((config) => {
   const { token, csrfToken } = useAuthStore.getState()
@@ -109,6 +110,20 @@ export interface DeepScanConfig {
 
 export type ScanConfigData = { ranges: string[] } & DeepScanConfig
 
+/** A row of `scan_runs` — what `/scan/runs` and the device rescan return. */
+export interface ScanRunSummary {
+  id: string
+  // 'failed' is legacy: runs recorded before the backend settled on 'error'
+  // for the same condition. Still read, never written.
+  status: 'running' | 'done' | 'cancelled' | 'error' | 'failed'
+  kind: string
+  ranges: string[]
+  devices_found: number
+  started_at: string
+  finished_at: string | null
+  error: string | null
+}
+
 // A device the backend refused to place because an equivalent node already
 // exists on the target design (same ip/mac/ieee). `existing_node_id` points at
 // the node already there so the UI can link to it.
@@ -158,8 +173,23 @@ export const scanApi = {
    */
   updatePending: (id: string, data: Partial<Omit<InventoryEntry, 'id' | 'status' | 'discovered_at'>>) =>
     api.patch<InventoryEntry>(`/scan/pending/${id}`, data),
+  /**
+   * Deep-rescan one known device: every TCP port, then re-fingerprint. Answers
+   * "this device predates the scanner knowing that service" (issue #350).
+   * Returns the ScanRun, so the caller polls `run` and can `stop` it.
+   * 409 when the device has no IP, is hidden, or is already being rescanned.
+   */
+  rescanDevice: (id: string, opts?: { full_ports?: boolean; ports?: string; http_probe_enabled?: boolean; verify_tls?: boolean }) =>
+    api.post<ScanRunSummary>(`/scan/pending/${id}/rescan`, opts ?? {}),
   hidden: () => api.get('/scan/hidden'),
+  /**
+   * Inventory rows for the guests a Proxmox host runs, resolved from the
+   * host→guest links the Proxmox import records. Empty for a non-host device.
+   */
+  proxmoxChildren: (id: string) =>
+    api.get<InventoryEntry[]>(`/scan/pending/${id}/proxmox-children`),
   runs: () => api.get('/scan/runs'),
+  run: (runId: string) => api.get<ScanRunSummary>(`/scan/runs/${runId}`),
   clearPending: () => api.delete('/scan/pending'),
   /** Remove one inventory entry. 409 when a rack still mounts it. */
   deletePending: (id: string) => api.delete<{ deleted: boolean }>(`/scan/pending/${id}`),
@@ -182,6 +212,14 @@ export const scanApi = {
       skipped: number
       skipped_devices: SkippedDevice[]
     }>('/scan/pending/bulk-approve', { device_ids: ids, design_id: designId ?? undefined }),
+  /**
+   * Fold several inventory rows into one, keeping `winnerId`. Returns the
+   * survivor. The losers' facts, canvas nodes, rack mounts and documents move
+   * onto it first — the identity match only runs when a row is created, so two
+   * rows for one host never converge on their own.
+   */
+  merge: (winnerId: string, loserIds: string[]) =>
+    api.post<InventoryEntry>('/scan/pending/merge', { winner_id: winnerId, loser_ids: loserIds }),
   bulkHide: (ids: string[]) => api.post<{ hidden: number; skipped: number }>('/scan/pending/bulk-hide', { device_ids: ids }),
   restore: (id: string) => api.post<{ restored: boolean; device_id: string }>(`/scan/pending/${id}/restore`),
   bulkRestore: (ids: string[]) => api.post<{ restored: number; skipped: number }>('/scan/pending/bulk-restore', { device_ids: ids }),
@@ -271,6 +309,62 @@ export const designsApi = {
   delete: (id: string) => api.delete(`/designs/${id}`),
 }
 
+export const documentsApi = {
+  list: (params?: { kind?: string; parent_id?: string; device_id?: string; tag?: string }) =>
+    api.get<import('@/documentation/types').DocumentSummary[]>('/documents', { params }),
+  get: (id: string) => api.get<import('@/documentation/types').Doc>(`/documents/${id}`),
+  create: (data: {
+    title: string
+    kind?: string
+    parent_id?: string | null
+    device_id?: string | null
+    node_id?: string | null
+    design_id?: string | null
+    template_id?: string | null
+    body?: string
+  }) => api.post<import('@/documentation/types').Doc>('/documents', data),
+  update: (
+    id: string,
+    data: {
+      title?: string
+      icon?: string | null
+      body?: string
+      parent_id?: string | null
+      sort_order?: number
+      starred?: boolean
+      reviewed?: boolean
+      resync_facts?: boolean
+    },
+  ) => api.patch<import('@/documentation/types').Doc>(`/documents/${id}`, data),
+  delete: (id: string) => api.delete(`/documents/${id}`),
+  revisions: (id: string) =>
+    api.get<import('@/documentation/types').DocRevision[]>(`/documents/${id}/revisions`),
+  revision: (revisionId: string) =>
+    api.get<import('@/documentation/types').DocRevision & { body: string }>(
+      `/documents/revisions/${revisionId}`,
+    ),
+  restore: (id: string, revisionId: string) =>
+    api.post<import('@/documentation/types').Doc>(`/documents/${id}/revisions/${revisionId}/restore`),
+  backlinks: (id: string) =>
+    api.get<import('@/documentation/types').DocBacklink[]>(`/documents/${id}/backlinks`),
+  regenerate: (id: string) =>
+    api.post<import('@/documentation/types').Doc>(`/documents/${id}/regenerate`),
+  search: (q: string, limit = 25) =>
+    api.get<import('@/documentation/types').DocSearchResult>('/documents/search', {
+      params: { q, limit },
+    }),
+  block: (block: string, deviceId: string) =>
+    api.get<{ block: string; markdown: string }>('/documents/blocks', {
+      params: { block, device_id: deviceId },
+    }),
+  coverage: () => api.get<import('@/documentation/types').DocCoverage>('/documents/coverage'),
+  scaffold: (data: { device_ids?: string[]; only_with_notes?: boolean }) =>
+    api.post<{ created: import('@/documentation/types').DocumentSummary[]; skipped: number }>(
+      '/documents/scaffold',
+      data,
+    ),
+}
+
 export const racksApi = {
   load: (designId: string) =>
     api.get<import('@/utils/rackSerializer').ApiRackState>('/racks', { params: { design_id: designId } }),
@@ -282,6 +376,8 @@ export const racksApi = {
     }),
 }
 
+export type ZigbeeImportJobStatus = 'running' | 'done' | 'error'
+
 export interface ZigbeeConfigData {
   mqtt_host: string
   mqtt_port: number
@@ -335,11 +431,20 @@ export const zigbeeApi = {
     mqtt_tls?: boolean
     mqtt_tls_insecure?: boolean
   }) =>
-    api.post<{
-      nodes: import('@/components/zigbee/types').ZigbeeNode[]
-      edges: import('@/components/zigbee/types').ZigbeeEdge[]
-      device_count: number
-    }>('/zigbee/import', data),
+    api.post<{ job_id: string; status: ZigbeeImportJobStatus }>('/zigbee/import', data),
+
+  // Poll a canvas import started by importNetwork. The fetch runs server-side
+  // so a slow mesh cannot outlive a reverse proxy's read timeout.
+  getImportJob: (jobId: string) =>
+    api.get<{
+      job_id: string
+      status: ZigbeeImportJobStatus
+      result: {
+        nodes: import('@/components/zigbee/types').ZigbeeNode[]
+        edges: import('@/components/zigbee/types').ZigbeeEdge[]
+        device_count: number
+      } | null
+    }>(`/zigbee/import/${jobId}`),
 
   importToPending: (data: {
     mqtt_host: string

frontend/src/components/LoginPage.tsx

@@ -7,6 +7,7 @@ import { Logo } from '@/components/ui/Logo'
 import { authApi } from '@/api/client'
 import { useAuthStore } from '@/stores/authStore'
 import { cn } from '@/lib/utils'
+import { API_BASE_URL, resolveServerPath } from '@/utils/basePath'
 
 export function LoginPage() {
   const [username, setUsername] = useState('')
@@ -111,7 +112,7 @@ export function LoginPage() {
               Continue through the configured OpenID Connect provider.
             </p>
             <a
-              href={oidcLoginUrl ?? '/api/v1/auth/oidc/login'}
+              href={resolveServerPath(oidcLoginUrl ?? `${API_BASE_URL}/auth/oidc/login`)}
               className={cn(
                 buttonVariants(),
                 'bg-[#00d4ff] text-[#0d1117] hover:bg-[#00d4ff]/90 font-medium',

frontend/src/components/canvas/CanvasContainer.tsx

@@ -11,6 +11,7 @@ import {
   type Node,
   type Edge,
   type Connection,
+  type Viewport,
 } from '@xyflow/react'
 import { MousePointer2, Hand } from 'lucide-react'
 import '@xyflow/react/dist/style.css'
@@ -32,9 +33,9 @@ interface CanvasContainerProps {
   onEdgeDoubleClick?: (edge: Edge<EdgeData>) => void
   onNodeDoubleClick?: (node: Node<NodeData>) => void
   onNodeDragStart?: () => void
-  onRequestAddToGroup?: (payload: { nodeId: string; groupId: string }) => void
-  onRequestAddToContainer?: (payload: { nodeId: string; containerId: string }) => void
-  onRequestAddToZone?: (payload: { nodeId: string; zoneId: string }) => void
+  onRequestAddToGroup?: (payload: { nodeIds: string[]; groupId: string }) => void
+  onRequestAddToContainer?: (payload: { nodeIds: string[]; containerId: string }) => void
+  onRequestAddToZone?: (payload: { nodeIds: string[]; zoneId: string }) => void
   onOpenInventory?: (deviceId: string) => void
 }
 
@@ -45,10 +46,16 @@ export function CanvasContainer({ onConnect: onConnectProp, onEdgeDoubleClick, o
     onNodesChange, onEdgesChange,
     setSelectedNode, snapshotHistory,
     fitViewPending, clearFitViewPending,
+    savedViewport, setSavedViewport,
     copySelectedNodes, pasteNodes,
-    removeFromGroup,
+    removeNodesFromGroup,
   } = useCanvasStore()
-  const { fitView, screenToFlowPosition, getIntersectingNodes } = useReactFlow<Node<NodeData>>()
+  const { fitView, getViewport, screenToFlowPosition, getIntersectingNodes } = useReactFlow<Node<NodeData>>()
+
+  // React Flow reads defaultViewport once, on mount. Leaving the canvas
+  // (Documentation) unmounts it, so hold the stored pan/zoom as it was at first
+  // render: later saves must not feed back into the prop.
+  const [initialViewport] = useState(savedViewport)
 
   // Track the last cursor position over the canvas so paste lands under it.
   const cursorRef = useRef<{ x: number; y: number } | null>(null)
@@ -93,11 +100,14 @@ export function CanvasContainer({ onConnect: onConnectProp, onEdgeDoubleClick, o
   useEffect(() => {
     if (!fitViewPending || nodes.length === 0) return
     const id = setTimeout(() => {
-      fitView({ padding: 0.12, duration: 350 })
+      void fitView({ padding: 0.12, duration: 350 }).then(() => {
+        // Where the fit landed is the viewport to come back to.
+        setSavedViewport(getViewport())
+      })
       clearFitViewPending()
     }, 50)
     return () => clearTimeout(id)
-  }, [fitViewPending, nodes.length, fitView, clearFitViewPending])
+  }, [fitViewPending, nodes.length, fitView, getViewport, setSavedViewport, clearFitViewPending])
 
   const activeTheme = useThemeStore((s) => s.activeTheme)
   const theme = THEMES[activeTheme]
@@ -125,6 +135,12 @@ export function CanvasContainer({ onConnect: onConnectProp, onEdgeDoubleClick, o
     setSelectedNode(null)
   }, [setSelectedNode])
 
+  // Every pan / zoom the user ends is remembered, so leaving the canvas and
+  // coming back does not reset the view to 1:1 at the origin.
+  const handleMoveEnd = useCallback((_: unknown, viewport: Viewport) => {
+    setSavedViewport(viewport)
+  }, [setSavedViewport])
+
   const handleEdgeDoubleClick = useCallback((_: React.MouseEvent, edge: Edge<EdgeData>) => {
     onEdgeDoubleClick?.(edge)
   }, [onEdgeDoubleClick])
@@ -145,38 +161,61 @@ export function CanvasContainer({ onConnect: onConnectProp, onEdgeDoubleClick, o
 
   const { guides, onNodeDrag, onNodeDragStop } = useAlignmentGuides()
 
-  // Drop a top-level node onto a group → ask App to confirm adding it. Runs
-  // before the alignment snap so detection uses the dropped position.
+  // Drop a selection onto a group → ask App to confirm adding it. Runs before
+  // the alignment snap so detection uses the dropped position. `dragNodes` is
+  // the whole multi-selection being dragged; `dragNode` (the one under the
+  // cursor) only picks the destination.
   const handleNodeDragStop = useCallback<NonNullable<typeof onNodeDragStop>>((event, dragNode, dragNodes) => {
-    if (dragNode && dragNode.data.type !== 'group' && dragNode.data.type !== 'groupRect') {
+    // A single drag reports an empty `dragNodes` in some React Flow paths, so
+    // fall back to the dragged node itself.
+    const dragged = dragNodes && dragNodes.length > 0 ? dragNodes : dragNode ? [dragNode] : []
+    // Groups and zones are containers, never contents.
+    const movable = dragged.filter((n) => n.data.type !== 'group' && n.data.type !== 'groupRect')
+
+    if (dragNode && dragNode.data.type !== 'group' && dragNode.data.type !== 'groupRect' && movable.length > 0) {
       const intersecting = getIntersectingNodes(dragNode)
       const zoneParent = dragNode.parentId
         ? nodes.find((n) => n.id === dragNode.parentId && n.data.type === 'groupRect')
         : undefined
       if (zoneParent) {
         // Zone children are not extent-clamped, so a drop outside the zone is
-        // how the user takes a node back out of it.
+        // how the user takes a node back out of it. The whole selection leaves
+        // with it, not only the node under the cursor.
         if (!intersecting.some((n) => n.id === zoneParent.id)) {
-          removeFromGroup(zoneParent.id, dragNode.id)
+          const leaving = movable.filter((n) => n.parentId === zoneParent.id).map((n) => n.id)
+          // One history entry, so a single undo puts the whole selection back —
+          // symmetric with the batched add.
+          removeNodesFromGroup(zoneParent.id, leaving)
         }
       } else if (!dragNode.parentId) {
+        // Only free nodes join a new parent; one already nested elsewhere in the
+        // selection keeps its own parent.
+        const nodeIds = movable.filter((n) => !n.parentId).map((n) => n.id)
         const group = intersecting.find((n) => n.data.type === 'group')
         const container = intersecting.find((n) => n.id !== dragNode.id && n.data.container_mode === true)
+        // The destination can be part of the dragged selection (lasso over
+        // everything); it cannot also be one of its own new children.
+        const targetless = (targetId: string) => nodeIds.filter((id) => id !== targetId)
         if (group) {
-          onRequestAddToGroup?.({ nodeId: dragNode.id, groupId: group.id })
+          const ids = targetless(group.id)
+          if (ids.length > 0) onRequestAddToGroup?.({ nodeIds: ids, groupId: group.id })
         } else if (container) {
           // Any node in container_mode (proxmox, docker_host, …) accepts children.
-          onRequestAddToContainer?.({ nodeId: dragNode.id, containerId: container.id })
+          const ids = targetless(container.id)
+          if (ids.length > 0) onRequestAddToContainer?.({ nodeIds: ids, containerId: container.id })
         } else {
           // Zones come last: they are the loosest container and the largest, so
           // a group/container inside one still wins the drop.
           const zone = intersecting.find((n) => n.data.type === 'groupRect')
-          if (zone) onRequestAddToZone?.({ nodeId: dragNode.id, zoneId: zone.id })
+          if (zone) {
+            const ids = targetless(zone.id)
+            if (ids.length > 0) onRequestAddToZone?.({ nodeIds: ids, zoneId: zone.id })
+          }
         }
       }
     }
     onNodeDragStop(event, dragNode, dragNodes)
-  }, [onRequestAddToGroup, onRequestAddToContainer, onRequestAddToZone, removeFromGroup, nodes, getIntersectingNodes, onNodeDragStop])
+  }, [onRequestAddToGroup, onRequestAddToContainer, onRequestAddToZone, removeNodesFromGroup, nodes, getIntersectingNodes, onNodeDragStop])
 
   return (
     <div ref={wrapperRef} className="w-full h-full" style={{ background: theme.colors.canvasBackground }} onMouseMove={onMouseMove}>
@@ -193,6 +232,8 @@ export function CanvasContainer({ onConnect: onConnectProp, onEdgeDoubleClick, o
         onNodeDragStart={onNodeDragStart}
         onNodeDrag={onNodeDrag}
         onNodeDragStop={handleNodeDragStop}
+        onMoveEnd={handleMoveEnd}
+        defaultViewport={initialViewport ?? undefined}
         nodeTypes={nodeTypes}
         edgeTypes={edgeTypes}
         deleteKeyCode={['Backspace', 'Delete']}

frontend/src/components/canvas/FloorMapLayer.tsx

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
 import { ViewportPortal, useReactFlow, useStore } from '@xyflow/react'
 import { useCanvasStore } from '@/stores/canvasStore'
+import { resolveServerPath } from '@/utils/basePath'
 
 interface ResizeState {
   startMouseX: number
@@ -152,7 +153,7 @@ export function FloorMapLayer() {
         onDoubleClick={locked ? undefined : (e) => { e.stopPropagation(); requestFloorMapEdit() }}
       >
         <img
-          src={imageData}
+          src={resolveServerPath(imageData)}
           alt="Floor plan"
           draggable={false}
           style={{

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

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest'
-import { render } from '@testing-library/react'
+import { act, render } from '@testing-library/react'
 import { CanvasContainer } from '../CanvasContainer'
 import { useCanvasStore } from '@/stores/canvasStore'
 import { useThemeStore } from '@/stores/themeStore'
@@ -10,7 +10,11 @@ import type { NodeData, EdgeData } from '@/types'
 let rfProps: Record<string, unknown> = {}
 
 // Hoisted holder so the mock factory can read the configurable intersection set.
-const rf = vi.hoisted(() => ({ intersecting: [] as unknown[] }))
+const rf = vi.hoisted(() => ({
+  intersecting: [] as unknown[],
+  viewport: { x: 0, y: 0, zoom: 1 },
+  fitView: vi.fn(() => Promise.resolve(true)),
+}))
 
 vi.mock('@xyflow/react', () => ({
   ReactFlow: (props: Record<string, unknown>) => {
@@ -25,7 +29,8 @@ vi.mock('@xyflow/react', () => ({
   SelectionMode: { Partial: 'partial' },
   Position: { Top: 'top', Right: 'right', Bottom: 'bottom', Left: 'left' },
   useReactFlow: () => ({
-    fitView: vi.fn(),
+    fitView: rf.fitView,
+    getViewport: () => rf.viewport,
     screenToFlowPosition: vi.fn(),
     getIntersectingNodes: () => rf.intersecting,
     setNodes: vi.fn(),
@@ -52,7 +57,12 @@ describe('CanvasContainer', () => {
   beforeEach(() => {
     rfProps = {}
     rf.intersecting = []
-    useCanvasStore.setState({ nodes: [], edges: [], selectedNodeId: null })
+    rf.viewport = { x: 0, y: 0, zoom: 1 }
+    rf.fitView.mockClear()
+    useCanvasStore.setState({
+      nodes: [], edges: [], selectedNodeId: null,
+      savedViewport: null, fitViewPending: false,
+    })
     useThemeStore.setState({ activeTheme: 'default' })
   })
 
@@ -177,7 +187,7 @@ describe('CanvasContainer', () => {
     rf.intersecting = [group]
     render(<CanvasContainer onRequestAddToGroup={onRequestAddToGroup} />)
     ;(rfProps.onNodeDragStop as (...args: unknown[]) => unknown)({} as MouseEvent, node, [node])
-    expect(onRequestAddToGroup).toHaveBeenCalledWith({ nodeId: 'n1', groupId: 'g1' })
+    expect(onRequestAddToGroup).toHaveBeenCalledWith({ nodeIds: ['n1'], groupId: 'g1' })
   })
 
   it('does not fire onRequestAddToGroup when no group is under the node', () => {
@@ -219,7 +229,7 @@ describe('CanvasContainer', () => {
     rf.intersecting = [containerNode('px1')]
     render(<CanvasContainer onRequestAddToContainer={onRequestAddToContainer} />)
     ;(rfProps.onNodeDragStop as (...args: unknown[]) => unknown)({} as MouseEvent, node, [node])
-    expect(onRequestAddToContainer).toHaveBeenCalledWith({ nodeId: 'n1', containerId: 'px1' })
+    expect(onRequestAddToContainer).toHaveBeenCalledWith({ nodeIds: ['n1'], containerId: 'px1' })
   })
 
   it('prefers a group over a container when both intersect', () => {
@@ -229,7 +239,7 @@ describe('CanvasContainer', () => {
     rf.intersecting = [containerNode('px1'), groupNode('g1')]
     render(<CanvasContainer onRequestAddToGroup={onRequestAddToGroup} onRequestAddToContainer={onRequestAddToContainer} />)
     ;(rfProps.onNodeDragStop as (...args: unknown[]) => unknown)({} as MouseEvent, node, [node])
-    expect(onRequestAddToGroup).toHaveBeenCalledWith({ nodeId: 'n1', groupId: 'g1' })
+    expect(onRequestAddToGroup).toHaveBeenCalledWith({ nodeIds: ['n1'], groupId: 'g1' })
     expect(onRequestAddToContainer).not.toHaveBeenCalled()
   })
 
@@ -263,7 +273,7 @@ describe('CanvasContainer', () => {
     rf.intersecting = [zoneNode('z1')]
     render(<CanvasContainer onRequestAddToZone={onRequestAddToZone} />)
     ;(rfProps.onNodeDragStop as (...args: unknown[]) => unknown)({} as MouseEvent, node, [node])
-    expect(onRequestAddToZone).toHaveBeenCalledWith({ nodeId: 'n1', zoneId: 'z1' })
+    expect(onRequestAddToZone).toHaveBeenCalledWith({ nodeIds: ['n1'], zoneId: 'z1' })
   })
 
   it('prefers a group and a container over a zone when they overlap', () => {
@@ -273,7 +283,7 @@ describe('CanvasContainer', () => {
     rf.intersecting = [zoneNode('z1'), containerNode('px1')]
     render(<CanvasContainer onRequestAddToZone={onRequestAddToZone} onRequestAddToContainer={onRequestAddToContainer} />)
     ;(rfProps.onNodeDragStop as (...args: unknown[]) => unknown)({} as MouseEvent, node, [node])
-    expect(onRequestAddToContainer).toHaveBeenCalledWith({ nodeId: 'n1', containerId: 'px1' })
+    expect(onRequestAddToContainer).toHaveBeenCalledWith({ nodeIds: ['n1'], containerId: 'px1' })
     expect(onRequestAddToZone).not.toHaveBeenCalled()
   })
 
@@ -308,6 +318,64 @@ describe('CanvasContainer', () => {
     expect(useCanvasStore.getState().nodes.find((n) => n.id === 'n1')?.parentId).toBe('z1')
   })
 
+  // ── Multi-selection drops (#365) ──────────────────────────────────────────
+
+  it('fires onRequestAddToZone with every dragged node, not just the one under the cursor', () => {
+    const onRequestAddToZone = vi.fn()
+    const dragged = [makeNode('n1'), makeNode('n2'), makeNode('n3')]
+    rf.intersecting = [zoneNode('z1')]
+    render(<CanvasContainer onRequestAddToZone={onRequestAddToZone} />)
+    ;(rfProps.onNodeDragStop as (...args: unknown[]) => unknown)({} as MouseEvent, dragged[0], dragged)
+    expect(onRequestAddToZone).toHaveBeenCalledWith({ nodeIds: ['n1', 'n2', 'n3'], zoneId: 'z1' })
+  })
+
+  it('leaves zones and groups out of a dragged selection', () => {
+    const onRequestAddToZone = vi.fn()
+    const dragged = [makeNode('n1'), zoneNode('z1'), groupNode('g1')]
+    rf.intersecting = [zoneNode('z2')]
+    render(<CanvasContainer onRequestAddToZone={onRequestAddToZone} />)
+    ;(rfProps.onNodeDragStop as (...args: unknown[]) => unknown)({} as MouseEvent, dragged[0], dragged)
+    expect(onRequestAddToZone).toHaveBeenCalledWith({ nodeIds: ['n1'], zoneId: 'z2' })
+  })
+
+  it('never asks to add the destination container to itself', () => {
+    const onRequestAddToContainer = vi.fn()
+    const target = containerNode('px1')
+    const dragged = [makeNode('n1'), target]
+    rf.intersecting = [target]
+    render(<CanvasContainer onRequestAddToContainer={onRequestAddToContainer} />)
+    ;(rfProps.onNodeDragStop as (...args: unknown[]) => unknown)({} as MouseEvent, dragged[0], dragged)
+    expect(onRequestAddToContainer).toHaveBeenCalledWith({ nodeIds: ['n1'], containerId: 'px1' })
+  })
+
+  it('keeps an already-parented node in the selection with its own parent', () => {
+    const onRequestAddToZone = vi.fn()
+    const dragged = [makeNode('n1'), { ...makeNode('n2'), parentId: 'pxOther' }]
+    rf.intersecting = [zoneNode('z1')]
+    render(<CanvasContainer onRequestAddToZone={onRequestAddToZone} />)
+    ;(rfProps.onNodeDragStop as (...args: unknown[]) => unknown)({} as MouseEvent, dragged[0], dragged)
+    expect(onRequestAddToZone).toHaveBeenCalledWith({ nodeIds: ['n1'], zoneId: 'z1' })
+  })
+
+  it('detaches every dragged child when a selection leaves its zone', () => {
+    const zone = { ...zoneNode('z1'), position: { x: 100, y: 100 } }
+    const c1 = { ...makeNode('n1'), parentId: 'z1', position: { x: 20, y: 20 } }
+    const c2 = { ...makeNode('n2'), parentId: 'z1', position: { x: 40, y: 40 } }
+    useCanvasStore.setState({ nodes: [zone, c1, c2] })
+    rf.intersecting = []
+    render(<CanvasContainer />)
+    ;(rfProps.onNodeDragStop as (...args: unknown[]) => unknown)({} as MouseEvent, c1, [c1, c2])
+    const after = useCanvasStore.getState().nodes
+    expect(after.find((n) => n.id === 'n1')!.parentId).toBeUndefined()
+    expect(after.find((n) => n.id === 'n2')!.parentId).toBeUndefined()
+    expect(after.find((n) => n.id === 'n2')!.position).toEqual({ x: 140, y: 140 })
+    // One history entry for the whole selection: a single undo puts both back.
+    useCanvasStore.getState().undo()
+    const restored = useCanvasStore.getState().nodes
+    expect(restored.find((n) => n.id === 'n1')!.parentId).toBe('z1')
+    expect(restored.find((n) => n.id === 'n2')!.parentId).toBe('z1')
+  })
+
   // ── Canvas settings ───────────────────────────────────────────────────────
 
   it('enables snapToGrid', () => {
@@ -386,4 +454,60 @@ describe('CanvasContainer', () => {
     expect(snapshotHistory).toHaveBeenCalledOnce()
     expect(result).toBe(true)
   })
+
+  // ── Viewport persistence across unmount (#docs round-trip) ────────────────
+
+  it('onMoveEnd stores the viewport the user ended on', () => {
+    render(<CanvasContainer />)
+    act(() => {
+      ;(rfProps.onMoveEnd as (...args: unknown[]) => unknown)({}, { x: -300, y: 120, zoom: 0.5 })
+    })
+    expect(useCanvasStore.getState().savedViewport).toEqual({ x: -300, y: 120, zoom: 0.5 })
+  })
+
+  it('mounts at the stored viewport — leaving for Documentation must not reset to 1:1', () => {
+    useCanvasStore.setState({ savedViewport: { x: -300, y: 120, zoom: 0.5 } })
+    render(<CanvasContainer />)
+    expect(rfProps.defaultViewport).toEqual({ x: -300, y: 120, zoom: 0.5 })
+  })
+
+  it('keeps the stored viewport across an unmount / remount round-trip', () => {
+    const first = render(<CanvasContainer />)
+    act(() => {
+      ;(rfProps.onMoveEnd as (...args: unknown[]) => unknown)({}, { x: -80, y: 15, zoom: 0.75 })
+    })
+    first.unmount()
+    render(<CanvasContainer />)
+    expect(rfProps.defaultViewport).toEqual({ x: -80, y: 15, zoom: 0.75 })
+  })
+
+  it('leaves defaultViewport undefined on a first load, so React Flow fits', () => {
+    render(<CanvasContainer />)
+    expect(rfProps.defaultViewport).toBeUndefined()
+  })
+
+  it('does not feed a later pan back into defaultViewport (read once, on mount)', () => {
+    render(<CanvasContainer />)
+    act(() => {
+      ;(rfProps.onMoveEnd as (...args: unknown[]) => unknown)({}, { x: -80, y: 15, zoom: 0.75 })
+    })
+    expect(rfProps.defaultViewport).toBeUndefined()
+  })
+
+  it('stores where fitView landed, so the fitted view survives the round-trip', async () => {
+    vi.useFakeTimers()
+    try {
+      rf.viewport = { x: -42, y: 7, zoom: 0.6 }
+      useCanvasStore.setState({ nodes: [makeNode('n1')], fitViewPending: true })
+      render(<CanvasContainer />)
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(100)
+      })
+      expect(rf.fitView).toHaveBeenCalledOnce()
+      expect(useCanvasStore.getState().savedViewport).toEqual({ x: -42, y: 7, zoom: 0.6 })
+      expect(useCanvasStore.getState().fitViewPending).toBe(false)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
 })

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

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest'
-import { render, screen, fireEvent } from '@testing-library/react'
+import { render, screen, fireEvent, act } from '@testing-library/react'
 import { FloorMapLayer } from '../FloorMapLayer'
 import { useCanvasStore } from '@/stores/canvasStore'
 import type { FloorMapConfig } from '@/types'
@@ -43,6 +43,16 @@ describe('FloorMapLayer', () => {
     expect(container.querySelector('img')).toBeNull()
   })
 
+  it('renders the stored image URL as-is at the root, base64 plans included', () => {
+    setFloorMap()
+    const { rerender } = render(<FloorMapLayer />)
+    expect(screen.getByAltText('Floor plan').getAttribute('src')).toBe('/api/v1/media/abc.png')
+
+    act(() => setFloorMap({ imageData: 'data:image/png;base64,abc' }))
+    rerender(<FloorMapLayer />)
+    expect(screen.getByAltText('Floor plan').getAttribute('src')).toBe('data:image/png;base64,abc')
+  })
+
   it('hides resize handles until the plan is selected, then shows them (unlocked)', () => {
     setFloorMap()
     render(<FloorMapLayer />)

frontend/src/components/canvas/edges/__tests__/HomelableEdge.animation.test.tsx

@@ -1,4 +1,6 @@
 import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
 import { render } from '@testing-library/react'
 import { ReactFlowProvider } from '@xyflow/react'
 import type { EdgeProps, Edge } from '@xyflow/react'
@@ -13,15 +15,18 @@ import type { EdgeData } from '@/types'
  * CSS animations pause when the tab is hidden and don't leak — so the rendered
  * output must contain a CSS `animation` on the path and zero <animate> nodes.
  */
-function renderEdge(data: Partial<EdgeData> = {}) {
+function renderEdge(
+  data: Partial<EdgeData> = {},
+  coords: { sourceY?: number; targetY?: number } = {},
+) {
   const props = {
     id: 'e1',
     source: 'a',
     target: 'b',
     sourceX: 0,
-    sourceY: 0,
+    sourceY: coords.sourceY ?? 0,
     targetX: 100,
-    targetY: 100,
+    targetY: coords.targetY ?? 100,
     sourcePosition: 'bottom',
     targetPosition: 'top',
     data: { type: 'ethernet', ...data } as EdgeData,
@@ -65,6 +70,53 @@ describe('HomelableEdge animation', () => {
     expect(animated).toBeTruthy()
   })
 
+  /**
+   * Regression (#395): the basic dash used to flip to `animation-direction:
+   * reverse` whenever the source sat below the target on screen, so an edge
+   * drawn bottom-to-top animated as if it went target→source. Direction comes
+   * from the data (the path is built source→target), never from the geometry.
+   */
+  it('basic dash animates source→target when the target is below', () => {
+    const { container } = renderEdge({ animated: 'basic' }, { sourceY: 0, targetY: 100 })
+    const dashed = Array.from(container.querySelectorAll('path')).find((p) =>
+      (p.getAttribute('style') ?? '').includes('homelable-basic-dash'),
+    )
+    expect(dashed).toBeTruthy()
+    expect(dashed!.getAttribute('style') ?? '').not.toContain('reverse')
+  })
+
+  it('basic dash keeps the same direction when the target is above', () => {
+    const { container } = renderEdge({ animated: 'basic' }, { sourceY: 100, targetY: 0 })
+    const dashed = Array.from(container.querySelectorAll('path')).find((p) =>
+      (p.getAttribute('style') ?? '').includes('homelable-basic-dash'),
+    )
+    expect(dashed).toBeTruthy()
+    expect(dashed!.getAttribute('style') ?? '').not.toContain('reverse')
+  })
+
+  /**
+   * Regression (#395): the basic dash marched against snake and flow because
+   * its keyframes decreased stroke-dashoffset while theirs increase it. All
+   * three must move the same way along the path.
+   */
+  it('basic dash keyframes march the same way as snake and flow', () => {
+    const css = readFileSync(resolve(__dirname, '../../../../index.css'), 'utf8')
+    const offsets = (name: string) => {
+      const block = css.match(new RegExp(`@keyframes ${name} \\{([^}]*\\}[^}]*)\\}`))
+      expect(block, `${name} keyframes not found`).toBeTruthy()
+      const values = [...block![1].matchAll(/stroke-dashoffset:\s*(-?\d+)/g)].map((m) => Number(m[1]))
+      expect(values).toHaveLength(2)
+      return values
+    }
+    const rising = (name: string) => {
+      const [from, to] = offsets(name)
+      return to > from
+    }
+    expect(rising('homelable-basic-dash')).toBe(true)
+    expect(rising('homelable-snake')).toBe(true)
+    expect(rising('homelable-flow')).toBe(true)
+  })
+
   it('non-animated edge has no flow animation and no <animate>', () => {
     const { container } = renderEdge({ animated: false })
     expect(container.querySelector('animate')).toBeNull()

frontend/src/components/canvas/edges/index.tsx

@@ -442,8 +442,11 @@ export function HomelableEdge({ id, source, target, sourceHandleId, targetHandle
           strokeDasharray="5"
           style={{
             pointerEvents: 'none',
+            // Direction comes from the keyframes alone (see index.css), never
+            // from the endpoints' screen positions: an edge drawn bottom-to-top
+            // marches the same way as one drawn top-to-bottom, like the snake
+            // and flow modes.
             animation: 'homelable-basic-dash 0.5s linear infinite',
-            animationDirection: sourceY <= targetY ? 'normal' : 'reverse',
           }}
         />
       )}