Shop Floor Kiosk

The kiosk is Forge's shared-screen surface: a full-screen, touch-first display mounted on the floor where workers clock in and out, pick up and advance jobs, and scan stock — without anyone holding a laptop or remembering a password. It is one of the surfaces described on App Surfaces, but it is the only one with a real installation procedure, because a terminal has to be paired before it works and the people using it have to be provisioned with something they can tap. This page is that procedure.

The kiosk routes

Everything the kiosk does lives under one route prefix. Point the terminal's browser at the one that matches the station.

Route	What it is
/display/shop-floor	The main floor display — worker cards, job assignments, timers, receiving and shipping actions
/display/shop-floor/clock	A team-scoped time clock: badge scan or manual clock in/out for one team
/display/shop-floor/scan	A stock scan station — move, count, receive, issue, ship, inspect
/display/shop-floor/scan-log	The day's scan history for that station
/display/shop-floor/preview	An inert training preview (see below)

The sidebar entry for the shop floor is visible only to Admin and Manager users; a terminal reaches these routes by URL, not by navigating the app.

Opening a kiosk route clears whatever session that browser profile is holding. This is deliberate — it is what stops one worker's token lingering for the next person at the screen — but it means you should not open the kiosk in a tab of your own office browser and expect to still be signed in afterwards.

Before you pair anything

Two sets of prerequisites, and both are easy to discover only after the tablet is already on the wall.

Capabilities. The shop-floor API surface is gated on CAP-MFG-SHOPFLOOR, which is on by default; turn it off and the kiosk stops working with a clean capability refusal rather than an error. The catalog also carries CAP-EXT-SHOPFLOOR-KIOSK (the kiosk UI as an install choice) and CAP-IDEN-AUTH-KIOSK (badge-and-PIN as an authentication tier). Both ship off and both are switched on by the shop-shaped discovery presets; CAP-IDEN-AUTH-KIOSK declares a dependency on the kiosk surface, so the dependency resolver will not let you enable the auth tier alone. Enable them to record the decision — see Capability Gating.

Per-worker credentials. Badge sign-in resolves a scanned value against the worker's scan identifiers (RFID, NFC, barcode or biometric) or, failing that, against their employee barcode field, and then checks a PIN. Both halves have to exist first:

• Scan identifiers are managed per user from the admin user screens, so a badge, sticker or printed label can be registered against a person and later revoked without touching their account.
• A PIN is set by the worker, never by an admin. An admin "reset PIN" clears the stored PIN rather than choosing a new one, and the worker sets it again themselves. That is the same stance Forge takes on passwords — see Access and Roles.
• For shops where production workers have no web login at all, there is an admin-only, one-shot provisioning call that creates the account with its role, badge value and initial PIN together, so a floor-only workforce can be brought up without every person first signing in to a browser.

Pairing a terminal

An unpaired browser shows the setup screen instead of the floor display. Pairing is two steps at the terminal itself:

1. An Admin or Manager signs in once, on that screen, with email and password.
2. They give the terminal a name and assign it to a team — picking an existing team or creating one on the spot.

Saving mints a device token, stores it in that browser profile alongside the terminal record, and immediately clears the admin's session. From that moment the terminal authenticates as a device, not as a person; the admin who paired it is not signed in to it.

Consequences worth planning for:

• The pairing lives in the browser profile. Clearing site data, using a private window, switching browsers or reimaging the tablet all mean pairing again. Pair on the profile the kiosk will actually run in, and leave it alone.
• An admin can revoke a terminal. Terminals are listed alongside teams in the admin panel and can be removed there; a removed or deactivated terminal's next request comes back unauthorised and the screen drops itself back to the setup gate. (A team cannot be deleted while terminals are still assigned to it.)
• Pairing is a per-terminal act. Ten screens on the floor is ten pairings.

What a paired terminal may do

The device token travels as a request header, and the app attaches it only to shop-floor endpoints plus a small read-only reference-data allowlist needed to render the screen before anybody has signed in. A kiosk browser therefore cannot reach the rest of the API on its device token alone — the token is not a general-purpose credential and there is no way to browse the office app from it.

Anything a worker actually does runs under that worker's own short-lived session, so the ordinary role and capability checks still apply. Two useful examples: stock scan mutations need a signed-in worker, not just a paired device; and assigning or completing a job is supervisory, restricted to Admin and Manager, because taking a job off someone or closing one out is not a floor-level action. Receiving and shipping actions on the display are likewise limited to the roles that should hold them. API Access describes the header-based schemes and the refusal envelopes in general.

How workers sign in

Workers authenticate per action, not per session. There are two paths, and they are not equivalent:

• Scan, then PIN. Tap or scan a badge, NFC sticker or barcode; the screen asks for a numeric PIN on an on-screen keypad. No keyboard needed. This is the intended floor flow.
• Tap your card on screen, then password. If a worker taps their own card in the worker grid instead of scanning, the terminal has no scan value to authenticate with, so it asks for their account password, not their PIN. Anyone who expects the PIN to work here will be confused; give people badges. The clock station additionally offers a manual email-and-password fallback for the same reason.

A scan can also start from the job end: scan a job barcode first and the terminal asks for the badge second, in either order.

Several workers can hold sessions on one terminal at once — a session bar lets them switch between foregrounded work — with a small default cap (oldest evicted) and a short idle expiry. Sessions are persisted in the browser's local database, so a page reload or a browser restart does not lose someone's half-finished action. The cap and the idle window are read from per-terminal local settings with built-in defaults, so a busy station can be tuned without changing anything server-side. Independently of that, the screen returns to the roster on its own after a brief idle, and the PIN and job-select prompts time out faster still — a worker who walks away mid-prompt does not leave the terminal sitting on their identity.

Hardware

Barcode scanners need no setup at all. Any keyboard-wedge reader — the ordinary kind that types what it scans — works out of the box: the app watches for the burst of keystrokes a scanner produces and treats it as a scan rather than typing. Nothing to install, nothing to configure, no field to focus first.

RFID and NFC readers have two transports, tried in that order:

1. A local relay. A small PC/SC relay service runs on the terminal itself and the browser connects to it over a loopback socket. It ships in the deploy repo under tools/rfid-relay, with a Windows installer and a service install script, and it works in any browser.
2. WebHID. If no relay is running and the browser is Chromium-based, the kiosk can talk to the reader directly through WebHID after a one-time device permission prompt.

If neither is available the kiosk says so rather than failing silently, and badge sign-in falls back to whatever barcode credential the worker carries.

Each terminal keeps its own look

The kiosk stores its theme and font size per terminal, in that browser, independent of the office app and of the signed-in user's own preference — and unlike the office app it starts light rather than dark. Set it once per machine to suit that corner's lighting and the distance people stand at; a bright bay can run light while the office runs dark. Everything else about branding — application name, colours, lockups — comes from the install and is covered on Customizing an Install.

Training preview

/display/shop-floor/preview renders the same screen on representative mock data behind an ordinary login. It is deliberately inert: it makes no backend calls, performs no sign-in, changes nothing, and does not clear the trainee's own session, so a new hire can be walked through the kiosk from their normal account without touching a live terminal or a real clock event.

The static evaluation demo behaves similarly — with no backend to pair against it renders the kiosk already paired, so you can look at the surface before installing anything. See Try Forge First.

Where the detail lives

• docs/functional-reference/shop-floor.md — screen-by-screen reference for the display and clock stations
• docs/ui-flows/24-shop-floor.md — the flow walkthrough
• Mobile and Offline — the other floor surface: a phone in a pocket rather than a screen on a wall, with a different offline story
• App Surfaces · Access and Roles · Capability Gating

Both repo docs predate some of the current behaviour. Between them they name an older route without the display/ prefix, an older name for the stored device-token key, and describe pairing as something that happens only on the clock page — the display page gates on pairing too. Where a doc and the code disagree, the code wins; the routes and the pairing flow above are what is on main.