# Proposal: fpagent-tools-ui

## Why

The python server (`app.py`) that served this project's enrollment UI is being
replaced by the `fpagent` binary (see `fingerprint-agent`), which owns scanner
capture on `127.0.0.1:9000` and enforces PocketBase + OpenFGA authorization per
enroll. The UI must be re-modeled onto fpagent's enroll-only event vocabulary
and YOUreka Auth, or this repo has no reason to exist alongside fpagent.

## What Changes

- **BREAKING**: Add a new Express app in `tools/` that replaces `app.py` as the
  UI host: a landing page linking two YOUreka tools — Image Cropper
  (`https://smart-pxa.yrka.app`) and Fingerprint Agent (`/fingerprint`).
- New `/fingerprint` enrollment wizard (re-modeled from `public/capture/`) that
  captures via fpagent Socket.IO: `fprint-enroll {token, domain, finger,
  reference}` → `fprint-enroll-status` → `fprint-enroll-done`, with
  `fprint-enroll-stop` cancel and `agent-hello` version display.
- Operator authentication via YOUreka Auth cookie session (portal
  `/api/web/auth` redirect flow; PocketBase session refresh server-side), same
  pattern as `one-school-chat`.
- Domain selection: a hardcoded catalog (UNICAL `uc`, Metropolitan Hotel `mtr`,
  UCTH `ucth`, UNICAL Radio International `uri`, YOUreka `yrka`) filtered after
  login against the same public OpenFGA verify URL fpagent uses; only permitted
  domains are offered. Results are cached per operator for 5 minutes, with an
  explicit refresh control available once the cache elapses.
- a2loft integration (staff lookup, fingerprint save) kept, but moved behind
  same-origin Express proxies; OTP input retained per a2loft call, validated by
  a2loft exactly as before (`?phone=&otp=`, phone injected server-side).
- **BREAKING**: Remove the python server and its UI: `app.py`,
  `requirement.txt`, `public/` (after the new UI reaches parity).
- clockio mode is not ported: fpagent is enroll-only by design.
- All configuration is hardcoded in source: port `4173`, portal
  `https://portal.yrka.app`, PocketBase `https://pb.itcass.net`, a2loft
  `https://apis.a2loft.net`, agent `http://127.0.0.1:9000`.

## Capabilities

### New Capabilities

- `tools-app`: the Express tools host — landing page, YOUreka Auth cookie
  session, hardcoded configuration, same-origin a2loft proxies.
- `fingerprint-wizard`: the `/fingerprint` enrollment wizard — domain
  permission filtering, fpagent capture wiring, OTP-validated lookup/save flow.

### Modified Capabilities

(none — this repo has no existing specs)

## Impact

- New code: `tools/` (Express app, static pages, auth session module, domain
  permit module). New dependencies: `express`, `pocketbase`.
- Removed code: `app.py`, `requirement.txt`, `public/capture/`,
  `public/clockio/`, `.config.json` handling.
- Deployment: fpagent must run with `-allowed-origins` including the tools app
  origin (`http://localhost:4173` in dev); the wizard page calls fpagent
  cross-origin from the browser.
- External systems: `portal.yrka.app` (web-auth + OpenFGA verify), `pb.itcass.net`
  (PocketBase session), `apis.a2loft.net` (staff lookup + fingerprint save, unchanged
  contract), fpagent on loopback.