Device-agnostic driver registry + first-run setup

Make the device-adapter pattern selectable so the admin chooses hardware at
install — per lane, from a catalog of supported drivers. Adding a device =
registering one more driver; no business-logic change.

packages/devices:
- interfaces.ts: AccessControlDevice / ReaderDevice / CameraDevice / PrinterDevice
  (adds CameraDevice for entry/exit snapshot-on-event; access relay stays
  intent-only per "a barrier is not a door").
- registry.ts: driver catalog with per-driver config fields + factory, config
  validation, and a catalog payload for the setup UI.
- drivers/: stub adapters — access (zkteco, esp32-relay), reader (wiegand,
  tcp-ip), camera (hikvision, dahua). Real vendor protocols TBD.

packages/db:
- lane_devices + setup_state tables (migration 0001); re-export query helpers.

apps/server:
- routes/setup.ts: GET /api/setup/catalog (public schema), and admin-only
  /assign, /state, /complete with registry validation before persisting.
- extract auth.ts (requireJwtSecret, requireRole, JWT type aug).

apps/web:
- SetupWizard scaffold + api client: pick a driver per category for a lane,
  render its config fields.

wiki: device-registry + first-run-setup concept pages; cross-link from
device-adapter-pattern; index + log updated.

Verified: full turbo build (5/5); catalog lists all drivers; admin assign
persists; missing-config and no-token requests are rejected.

wiki/concepts/device-adapter-pattern.md

@@ -30,3 +30,9 @@ interface RelayDevice {
 
 Note the `RelayDevice` expresses **intent only** — see the [[barrier-not-a-door]] safety
 principle. The choice of *which* adapter to trust is the [[trust-boundary]] decision.
+
+> **In practice** the adapters are made *selectable*: a [[device-registry]] catalogs the
+> supported drivers (ZKTeco / ESP32 relay, Wiegand / TCP-IP readers, Hikvision / Dahua cameras),
+> and the admin assigns one per lane during [[first-run-setup]]. Adding hardware support = one
+> more registered driver, no business-logic change. (The implemented interfaces add a
+> `CameraDevice` for entry/exit snapshots alongside reader/relay/printer.)

wiki/concepts/device-registry.md

@@ -0,0 +1,43 @@
+---
+type: concept
+tags: [parking, architecture, devices, configurable]
+sources: [parking-system-architecture]
+updated: 2026-06-15
+---
+
+# Device Registry (selectable drivers)
+
+How the system goes from "device-agnostic in principle" ([[device-adapter-pattern]]) to
+"**admin picks the device at setup**" in practice. A **registry** holds a catalog of supported
+**drivers**, grouped by category; the [[first-run-setup]] UI reads it so an
+operator can choose a device per lane and fill in its connection config.
+
+> Implementation-derived (from `packages/devices`), not the source doc.
+
+## The four categories
+
+| Category | Examples (drivers) | Interface |
+| --- | --- | --- |
+| **access** | ZKTeco, ESP32 relay (also UHPPOTE) | `AccessControlDevice` — intent-only relay ([[barrier-not-a-door]]) |
+| **reader** | Wiegand-into-controller, TCP/IP reader | `ReaderDevice` — RF/optical; two paths ([[entry-exit-readers]]) |
+| **camera** | Hikvision, Dahua | `CameraDevice` — entry/exit snapshot-on-event |
+| **printer** | (ticket dispenser / booth printer) | `PrinterDevice` |
+
+## How a driver is described
+
+Each driver declares: a stable `id`, its `category`, a human `label`/`description`, the
+`transports` it uses (`tcp-ip`, `wiegand`, …), a list of **`configFields`** (host, port,
+credentials, selects — what the setup UI renders), and a `create(config)` **factory** that
+validates config and returns a live adapter. Adding hardware support = registering one more
+driver; **no business-logic change** — this is the [[device-adapter-pattern]] made selectable.
+
+## Why a registry (not hard-coded wiring)
+
+- The admin chooses between **multiple devices per category** at install time, per lane
+  (mirrors the "mixable per lane" principle — see [[trust-boundary]], [[entry-exit-readers]]).
+- Config is **validated against the driver's declared fields** before persisting.
+- Selections persist in the `lane_devices` table and drive runtime adapter construction.
+
+Cameras are modelled as **snapshot-on-event**: the host requests an image at entry/exit; it's
+stored and referenced from the signed event as an **independent record** — a fraud-control input
+to the [[append-only-event-chain]] (cf. [[lpr-camera]] as the recognition-based identity source).

wiki/concepts/first-run-setup.md

@@ -0,0 +1,37 @@
+---
+type: concept
+tags: [parking, architecture, devices, admin]
+sources: [parking-system-architecture]
+updated: 2026-06-15
+---
+
+# First-Run Setup (device selection)
+
+The admin install flow that makes the system **device-agnostic in practice**: on first run, an
+admin assigns devices **per lane** by choosing from the [[device-registry]] catalog and entering
+each device's connection config.
+
+> Implementation-derived (from `apps/server` + `apps/web`), not the source doc.
+
+## Flow
+
+1. **Read the catalog** — `GET /api/setup/catalog` returns supported drivers per category (no
+   secrets, just schema). The web `SetupWizard` renders a picker + the driver's config fields.
+2. **Assign per lane** — `POST /api/setup/assign` (admin-only, role-guarded; see
+   [[local-jwt-auth]]). The server validates the chosen driver + config against the registry
+   before persisting to the `lane_devices` table; unknown drivers / missing required fields are
+   rejected.
+3. **Complete** — `POST /api/setup/complete` marks the single-row `setup_state`.
+
+## Config granularity
+
+Organized **per lane** — each lane gets an access controller, reader(s), and camera(s), each with
+its own connection settings. Matches the architecture's "mixable per lane" reality (a lane can
+serve permit holders via [[wiegand]] and casual via host-side reads on one relay — see
+[[entry-exit-readers]]).
+
+## Security notes
+
+- The assign/state/complete endpoints require the **admin** role ([[local-jwt-auth]]).
+- Device **credentials are stored in `lane_devices.config`** — protect at rest
+  ([[disk-os-hardening]]); device hosts belong on the isolated VLAN ([[network-isolation]]).

wiki/index.md

@@ -50,6 +50,8 @@ Counts: 1 source · 14 entities · 10 concepts · 2 decision records.
 
 ## Concepts — device architecture & safety
 - [[device-adapter-pattern]] — business logic talks to interfaces; swap hardware → new adapter.
+- [[device-registry]] — catalog of selectable drivers per category (admin-configurable).
+- [[first-run-setup]] — admin assigns devices per lane from the catalog at install.
 - [[barrier-not-a-door]] — never timed-close a barrier; safety lives in barrier firmware.
 - [[trust-boundary]] — the core fork: network vs. device; auditable vs. unforgeable.
 - [[fail-state-safety]] — entry fails closed, exit fails open; manual override; watchdog.

wiki/log.md

@@ -18,3 +18,13 @@ property). Marked [[esp32-custom-controller]] `status: deferred` per decision no
 implement device-level auth for now (access control stays on UHPPOTE + network
 isolation); noted in [[open-questions]] #6. Updated [[local-jwt-auth]] (hardened secret
 handling + 8h expiry, asymmetric-key pointer) and the index.
+
+## [2026-06-15] decision | Device-agnostic registry + first-run setup
+From app work. Made the [[device-adapter-pattern]] selectable: added a
+[[device-registry]] (catalog of drivers per category) and a [[first-run-setup]]
+flow so the admin picks a device per lane at install. Categories: access
+(ZKTeco / ESP32 relay), reader (Wiegand / TCP-IP), camera (Hikvision / Dahua,
+snapshot-on-event), printer. Added a `CameraDevice` interface; new `lane_devices`
++ `setup_state` tables (migration 0001); admin-only setup endpoints. Stub drivers
+for now (no real vendor protocols yet). Verified catalog + assign + validation +
+auth end to end.