# Booking kiosk (Agent Skill)

> A self-service touchscreen kiosk: a stepped walk-up booking flow, on-screen keyboard, automatic reset, payment at the counter or by QR code, and server-priced bookings.

Page: https://timerise.ai/skills/booking-kiosk

Agent Skill `booking-kiosk`: https://github.com/timerise-ai/booking-kiosk. Category: In-venue. Runs on Next.js; backend: Backend- and payment-agnostic `KioskBackend` seam, Firestore reference implementation.

Latest release: v0.1.8 (2026-09-29).

Install: npx skills add timerise-ai/booking-kiosk. Timerise builds it on a brief; the price comes from the brief.

A walk-up kiosk is a booking website with the trust turned inside out. The screen is shared, nobody is logged in, and anyone can tap anything. Prices, capacity and double-booking protection have to live on the server. Whatever is on the screen has to disappear when the customer walks away.

This skill builds the kiosk for a gym, karting track, bowling alley, climbing wall, escape room or clinic: a stepped flow from service to confirmation, an on-screen keyboard, automatic reset after inactivity, payment at the counter or by QR code, live availability, and a find-my-booking screen for changes.

The booking backend sits behind a seam, so it works with your existing system. A Firestore reference implementation is included.

Build a self-service touchscreen booking kiosk for a venue: a stepped walk-up flow from service, date and time slot through stations and participant names, equipment and consumables, to summary and confirmation, with an on-screen keyboard, inactivity auto-reset, pay-at-counter or pay-by-QR, live availability refresh and a find-my-booking edit flow. Use when: (1) a venue (gym, karting, bowling, climbing, escape room, clinic) wants an unattended booking terminal, (2) an app that already books online needs a kiosk mode, (3) an existing kiosk needs auditing against the hard rules, (4) the user mentions: kiosk mode, self-service kiosk, touch screen booking, walk-up terminal, on-screen keyboard, inputMode none, inactivity reset, counter payment, PENDING_COUNTER_PAYMENT, x-kiosk-api-key, SET_SLOT, REFRESH_SLOT, PROMO_INVALID, stock lock. Carries the session reducer with its 14-test suite, the screen contract and dictionary key tree, a server-priced idempotent API contract with guard tables, stock locks released on every failure path, and offline failover against a LAN server. Next.js App Router with React context; the KioskBackend interface is the seam, so the booking store, payment provider and realtime channel are the host's. Not a staff POS, not digital signage and not the on-prem fallback server itself.

It was written by the engineers who have shipped this kiosk module. The earlier implementation it was audited against ran as one of several surfaces sharing a booking engine at a multi-location venue with a LAN fallback server. The templates carry its state machine, screen flow, timers, stock model, capacity transaction and offline failover, and hold the properties a kiosk has to hold: every price, capacity check and promo decision is computed on the server; every submit is idempotent; a configured device key makes a missing header a 401; a stock lock is released on every failure path; a session lives in memory and resets on inactivity. Each one is stated as what the reducer suite and the route guard tables verify. [`references/provenance.md`](references/provenance.md) is the record of what the audit changed, what was kept deliberately, and what is new in the skill.

What it builds:
- Walk-up booking flow
- On-screen keyboard
- Pay-at-counter or pay-by-QR
- Server-priced idempotent booking API
- LAN failover contract

When to use:
- Building a walk-up booking terminal for slot-based capacity (stations by time windows) with optional equipment and consumable add-ons.
- Adding kiosk mode to an app that already has online booking.
- Auditing an existing kiosk against the hard rules below; [provenance.md](references/provenance.md) records the reason behind each.

When not to use:
- **On-prem offline fallback server**: that is the sibling `island-mode-server` skill; this skill only defines the kiosk's client-side failover contract.
- **Digital signage / display screens**: different capability (playback, no input), different skill.
- **Staff-facing POS or admin booking tools**: staff are authenticated and trusted; this skill's trust model is wrong for them.
- **A plain booking website**: take the backend seam if useful, but the kiosk machinery (keyboard, timers, touch hardening) is dead weight there.

Non-negotiables:
- Never persist kiosk session state. In memory, 120 s inactivity reset, 30 s confirmation reset, so an abandoned session never shows one customer's name to the next. The reducer suite covers the reset paths.
- Never trust the client for prices, capacity, or promo validity. The server computes every amount and answers an invalid promo with `PROMO_INVALID` instead of a full-price fallback, because a customer at a kiosk has no way to check the amount. The guard tables in `references/api-contract.md` state each check.
- One fetch wrapper for every kiosk request. The wrapper carries the device header, the error envelope and the failover base URL, so auth, errors and offline failover apply to every request at once.
- If the device key is configured, a missing header is a 401. Rejecting only a wrong key is the same as no auth. The device-auth guard in `references/api-contract.md` checks presence before value.
- Release stock locks on every failure path after acquiring them. A 409 that keeps the reservation freezes stock for the full 15-minute TTL. The failure-mode table in `references/booking-backend.md` lists every path.

Not this:
- The on-prem offline fallback server: The sibling [`island-mode-server`](https://github.com/timerise-ai/island-mode-server) skill; this one defines only the kiosk's client-side failover contract
- Digital signage or display screens: The sibling [`digital-signage`](https://github.com/timerise-ai/digital-signage) skill: playback, no input
- Staff-facing POS or admin booking tools: The host's authenticated admin; staff are trusted, and this skill's trust model is wrong for them
- A plain booking website: The backend seam if useful; the kiosk machinery (keyboard, timers, touch hardening) is dead weight there

Booking features we build with it:
- Self-service kiosk and check-in: /features/kiosk-and-check-in

What to tell your agent:
- Build a self-service booking kiosk for our karting track: pick a session, a time slot, the number of karts and the driver names, then pay at the counter. Go back to the start after two minutes without a touch.
- Add kiosk mode to our booking app: a touchscreen flow with an on-screen keyboard, pay by QR code, and a find-my-booking screen to change a reservation.
- Audit our kiosk against the skill's hard rules and list every place it breaks one.

Agent eval results (newest per agent and prompt):
- Gemini CLI (gemini-3.8-flash) on v0.1.8, 2026-09-29: pass (Firestore)
- Codex CLI (gpt-6-astra) on v0.1.8, 2026-09-29: pass (Firestore)
- Claude Code (claude-opus-5-5) on v0.1.8, 2026-09-29: pass (Firestore)

Recent releases:
- v0.1.8 (2026-09-29): Fix release, from the prompt-1 agent eval runs against 0.1.7: one agent reported four template defects in its handover instead of editing them, and each was reproduced before the fix.
- v0.1.7 (2026-09-29): Fix release, from scoring the prompt-1 agent eval runs against 0.1.6 and verifying every template.
- v0.1.6 (2026-09-29): Wording release that brings the repository to the skill standard. The templates behave as in 0.1.5; only their comments, diagrams and two glyphs are written in ASCII.