Pair displays at the platform's own /display/setup, with or without modules

Displays are platform-owned, but a screen could only start pairing on a
module's display page: every pairing request named a module, so an
installation with no module that uses displays could not set one up.

- /display/setup is the platform's own display page, served whenever
  the deployment has device support, whatever is installed. It pairs a
  platform display with no module. Once paired, it opens the module it
  is set to show; with none set, it shows its name and waits, rechecking
  so it stays alive and notices revocation. "setup" is now a reserved
  module id.
- Migration core:0009_platform_display_pairing lets a pairing request
  name no module. It relaxes module_id and permission_id and adds a
  both-or-neither check. It is additive and destroys nothing.
- POST /api/v1/device-pairing/requests accepts {} for a platform
  display. Approval accepts an optional moduleId, so the administrator
  can choose an installed display module and the device gets that
  module's declared permission. A module display's own request can't be
  redirected.
- GET /api/v1/device-pairing/self lets a paired device describe itself:
  its name and the module displays it may show. It renews the device's
  cookie.
- GET /api/v1/devices/setup is replaced by
  GET /api/v1/devices/display-modules: the modules a display can be set
  to show.
- Settings -> Displays always offers the /display/setup address, Copy
  setup link and Add display. Add display has an optional "Show on this
  screen" choice, and each paired display says what it shows.
- /display/<module-id> is unchanged, so released Signage 0.1.5 works as
  before.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

docs/development/api.md

@@ -980,25 +980,33 @@ what it is accepting.
 ## Display device pairing and management
 
 Host-owned, and reachable by no module
-([ADR 0036](../architecture/decisions/0036-managed-device-identity-and-pairing.md)). Two sibling
-prefixes: `/api/v1/device-pairing` and `/api/v1/devices`.
+([ADR 0036](../architecture/decisions/0036-managed-device-identity-and-pairing.md),
+[ADR 0065](../architecture/decisions/0065-display-setup-phone-forms-and-drawer-scroll-lock.md)). Two
+sibling prefixes: `/api/v1/device-pairing` and `/api/v1/devices`.
+
+A new screen starts at the platform's own display page, `/display/setup`, which every installation
+serves, whatever modules are installed. It pairs a **platform display** with no module; the
+administrator may choose, when approving it, which installed display module it shows. A screen that
+opens a module's display page, `/display/<module-id>`, still pairs with that module directly.
 
 **The screen's side** (no identity required; authority is the HttpOnly claim cookie the first call
 sets, never the code):
 
 | route | purpose |
 | --- | --- |
-| `POST /api/v1/device-pairing/requests` | Body `{moduleId}`. Returns `{code, expiresAt, pollIntervalMs}` and sets `ekklesia_device_pairing`. The permission is read from that module's validated display declaration — a request cannot name one. |
+| `POST /api/v1/device-pairing/requests` | Body `{}` from `/display/setup` (a platform display, no module), or `{moduleId}` from a module's display page. Returns `{code, expiresAt, pollIntervalMs}` and sets `ekklesia_device_pairing`. A module's permission is read from its validated display declaration — a request can never name one, and any other key is ignored. |
 | `POST /api/v1/device-pairing/claims` | Polls. Returns `{status}`; on `paired` it sets `ekklesia_device_session` and clears the pairing cookie. |
+| `GET /api/v1/device-pairing/self` | A **paired device** only: `{name, displays: [{moduleId, url}]}`, the module display pages it may show. Renews the device cookie. Anyone else — a person, an unpaired or revoked screen — is `403`. |
 
 **The administrator's side** (requires the restricted `core.devices.manage` and an exact trusted
 `Origin`):
 
 | route | purpose |
 | --- | --- |
-| `POST /api/v1/device-pairing/lookups` | Body `{code}`. Shows the module and permission a screen is asking for, before approving. |
-| `POST /api/v1/device-pairing/approvals` | Body `{code, deviceName}`. The administrator names the screen; the screen never names itself. |
+| `POST /api/v1/device-pairing/lookups` | Body `{code}`. Shows the module and permission a screen is asking for — both `null` for a platform display — before approving. |
+| `POST /api/v1/device-pairing/approvals` | Body `{code, deviceName, moduleId?}`. The administrator names the screen; the screen never names itself. `moduleId`, for a platform display, is the running display module it shows; its declared display permission is granted. A module display's own request cannot be given a different module. |
 | `GET /api/v1/devices` | Paired devices: name, permissions, created, last seen, revoked. Never a credential. |
+| `GET /api/v1/devices/display-modules` | `{modules: [{moduleId, name, permissionId}]}`: the running modules a display can be set to show. |
 | `POST /api/v1/devices/:deviceId/revoke` | `204`. Server-side revocation, checked on every principal resolution. |
 
 The pairing code travels in request **bodies**, never a path or query, so it does not land in access
@@ -1012,7 +1020,7 @@ instead, which now carries `viewer: {kind: "authenticated", userId} | {kind: "de
 **Cookies.** `ekklesia_device_session` is `HttpOnly`, `SameSite=Strict`, host-only, `Path=/`, and
 `Secure` when the identity base URL is https. Deployment note: because it is host-only and
 `SameSite=Strict`, a display must be served from the same origin as the API — which the platform's
-own `/display/<module-id>` route is.
+own `/display/setup` and `/display/<module-id>` routes are.
 
 ## Outbound email
 

docs/development/testing.md

@@ -488,11 +488,27 @@ The second review's corrections
 ([ADR 0065](../architecture/decisions/0065-display-setup-phone-forms-and-drawer-scroll-lock.md)) are
 proven here:
 
-- `apps/api/tests/device-pairing.integration.ts` covers `GET /api/v1/devices/setup`. It names each
-  display page, is `no-store`, and refuses an unpaired or paired screen.
-- `surfaces/shell/tests/displays-settings.test.tsx` covers the setup steps on the API origin: Copy
-  link with and without a clipboard, several modules, none installed, a failed read, and a refused
-  non-root-relative page.
+- `apps/api/tests/device-pairing.integration.ts`, on real PostgreSQL:
+  - with **zero** modules installed, a screen at `/display/setup` pairs as a platform display with
+    no permission;
+  - the display can describe itself, an administrator cannot impersonate it, and revocation works;
+  - an administrator can choose the module a platform display shows at approval;
+  - a module display's own request cannot be redirected, and unknown keys and modules are refused.
+- `apps/api/tests/module-display-routes.test.ts` serves `/display/setup` and the display host with
+  zero display modules, and only with device support.
+- `core/tests/device-pairing-schema.test.ts` pins migration `0009` to its three additive statements.
+- `surfaces/shell/tests/display-setup-app.test.tsx` covers the setup page:
+  - it pairs with no module and waits, named;
+  - it opens the module it is set to show;
+  - it opens a module as soon as one is set;
+  - it returns to a code when revoked;
+  - it never pairs on a server failure.
+- `surfaces/shell/tests/displays-settings.test.tsx` covers:
+  - the platform setup address, and **Copy setup link**;
+  - **Add display** with zero display modules;
+  - the **Show on this screen** choice;
+  - a module display's request showing its fixed module;
+  - pairing still working when the module list cannot be read.
 - `surfaces/shell/tests/scroll-lock.test.ts` covers:
   - the root locked and its previous styles restored;
   - drags outside the drawer cancelled, and drags inside it allowed except past its ends;
@@ -503,7 +519,11 @@ proven here:
 - `surfaces/shell/tests/viewport.test.ts` keeps zoom available on both shell pages.
 - `packages/ui/tests/tokens.test.ts` holds text controls at 16px or more on phones and touch screens.
 - `packages/ui/tests/interaction.test.tsx` checks that the focus trap returns focus without scrolling.
-- The deploy smoke checks, in real Chromium:
+- The deploy smoke checks:
+  - `/display/setup` and a module-less pairing request through the proxy, in both topologies, so in
+    the same-origin run with no module at all;
+  - in real Chromium, a screen in its own browser context at `/display/setup` showing a code, being
+    added through Settings, and then opening its chosen module, or waiting, named;
   - the setup steps on the API origin;
   - the page locked behind the open drawer and released after;
   - the pairing field at 16px or more on a phone.