OPT and Improved Installation Wizzard

1. Summary of changes
Password auth → email OTP, everywhere it existed for the tenant/business app: sign-in, customer self-registration (/register), staff-invitation acceptance, and the installer's administrator step. Flow is always: email → 6-digit code emailed → code entered → session created, via one shared service (otp.service.ts) reused by every entry point.
NextChair Manager's own auth was not touched — this only affects tenant-side (business admin/staff/customer) authentication, per the spec's explicit instruction.
Installer improvements: Step 2 (Administrator) now asks only Name + Email + optional Phone, verified inline via the same OTP widget (no redirect). Step 3 (Business Details) pre-fills Business Name from the Manager-provisioned BUSINESS_NAME, shows the booking URL (NEXT_PUBLIC_APP_URL) as a read-only info box instead of asking for it, and has a distinctly-labeled "Business Website (optional)" field with copy clarifying it's not the booking URL.
Installation cannot complete with an unverified admin email — enforced server-side (finalizeOtp runs inside the same DB transaction as user/business creation), not just trusted from client state. A mid-wizard refresh still can't create duplicate admins or partial records — that property was preserved by design, not incidentally.
2. Prisma/database changes
New EmailOtp model (email as PK — one row per address, so a new request naturally invalidates the previous code): codeHash, purpose, expiresAt, attempts, verifiedAt, consumedAt, timestamps. Only a bcrypt hash of the code is ever stored.
User.passwordHash — unchanged schema (already nullable), just annotated as deprecated. No destructive migration; historical rows are untouched.
Migration: prisma/migrations/20260905190022_email_otp_authentication — adds EmailOtp only. Generated and applied against throwaway containers only; the real next-chair-mysql production database was never touched (confirmed not even running on this host during this session).
3. New environment variables
None required for production. One new variable, E2E_TEST_MODE, exists purely for the Playwright suite (set only in playwright.config.ts's webServer.env) — it unlocks a /api/test/otp-code debug endpoint and bypasses OTP rate limiting so the same seeded users can sign in dozens of times across one test run. It must never be set on a real deployment; nothing in the app sets it anywhere else.

4. Email delivery configuration
Nothing new to configure. OTP emails reuse the existing EmailProvider abstraction and EMAIL_PROVIDER env var exactly as configured today — console in dev (prints to server logs), brevo in production via the same SMTP credentials already documented. The OTP email is a new template (otp-email.ts) sent directly (bypassing the async notification/cron pipeline, since a 10-minute-expiry code can't wait for a delivery retry loop).

5. Migration considerations for existing users/installations
Existing users lose password sign-in — the only way to authenticate now is email OTP. There is no in-app fallback; this is an intentional, sharp cutover. If existing customers/staff/admins need advance notice, that's a business/communications decision outside this change.
No account data is deleted or migrated — passwordHash rows are simply never read for auth anymore.
prisma/seed.ts / scripts/ensure-super-admin.ts still set a passwordHash for seeded dev users — harmless and vestigial now, not cleaned up (flagging it rather than touching seed data silently).
Installations already completed are unaffected; only new installer runs go through the OTP admin-verification step.
6. Files changed
New:

src/lib/auth/otp.service.ts — the core requestOtp/verifyOtp/finalizeOtp service
src/lib/auth/__tests__/otp.service.integration.test.ts
src/services/notifications/templates/otp-email.ts
src/features/auth/components/otp-code-step.tsx — shared code-entry UI
src/features/auth/actions/request-sign-in-otp.ts
src/app/api/test/otp-code/route.ts — e2e-only, gated on E2E_TEST_MODE
prisma/migrations/20260905190022_email_otp_authentication/
Modified — auth core: prisma/schema.prisma, src/auth.ts, src/features/auth/schemas.ts

Modified — sign-in/register/invitations: sign-in-form.tsx, register.ts, register-form.tsx, accept-invitation.ts, accept-invitation-form.tsx, staff-invitation.service.ts

Modified — installer: installer.service.ts, schema.ts, install.ts, install-wizard.tsx, install/page.tsx, installer.service.integration.test.ts

Modified — email / e2e infra: console-email-provider.ts, playwright.config.ts, e2e/helpers.ts, and the four e2e/*.spec.ts files (dropped the now-unused password argument from every signIn() call).

7. Verification performed
npx tsc --noEmit, npm run lint, npm test (276 unit) — all clean.
npm run test:integration (207 tests, throwaway DB) — includes 11 new OTP-service tests and a rewritten installer suite; a genuine race condition in requestOtp (concurrent requests for a brand-new email double-hitting the upsert's create branch) was caught and fixed here.
Full npm run test:e2e against a fresh throwaway database: 36/37 passed. The one failure (owner-journeys "opening hours conflict" test) is a pre-existing, auth-unrelated ordering flake — appointment-count ambiguity from earlier tests' bookings — not something this change touches or introduced.
Live manual verification in-browser: existing seeded customer sign-in via OTP; new customer registration via OTP (session created, landed on Home); installer wizard end-to-end through Step 3, confirming email-verification gating, Business Name pre-population from BUSINESS_NAME, and the read-only Booking URL / distinct Business Website fields.
All throwaway Docker containers/DBs used for this work have been removed; the real production database was never touched.

e2e/helpers.ts

@@ -1,20 +1,26 @@
 import { expect } from "@playwright/test";
 import type { Page } from "@playwright/test";
 
-/** Seeded in prisma/seed.ts — see that file for the full fixture set this suite relies on. */
+/**
+ * Seeded in prisma/seed.ts — see that file for the full fixture set this
+ * suite relies on. No `password` fields here anymore: sign-in is OTP-only
+ * now (see signIn() below), so a seeded user's passwordHash (still written
+ * by prisma/seed.ts / ensure-super-admin.ts) is vestigial and unused by
+ * any auth path.
+ */
 export const SEEDED = {
-  registeredCustomer: { email: "alex.chen@example.com", password: "password123", name: "Alex Chen" },
+  registeredCustomer: { email: "alex.chen@example.com", name: "Alex Chen" },
   // Seeded right at their loyalty reward threshold (10/10 stamps, one
   // AVAILABLE reward) — see prisma/seed.ts. owner-journeys.spec.ts's
   // journey 10 redeems this exact reward, so any test relying on it still
   // being AVAILABLE must run before that (customer-journeys.spec.ts runs
   // first in the suite, so this is safe there).
-  secondCustomer: { email: "sam.osei@example.com", password: "password123", name: "Sam Osei" },
+  secondCustomer: { email: "sam.osei@example.com", name: "Sam Osei" },
   owner: { email: "marcus@blakeheritage.co.uk", name: "Marcus Reed" },
   // Provisioned by global-setup.ts via scripts/ensure-super-admin.ts, not
   // prisma/seed.ts — a Super Administrator deliberately has no StaffProfile
   // (see isSuperAdmin) and stays out of the dev/demo seed data on purpose.
-  superAdmin: { email: "superadmin@blakeheritage.co.uk", password: "password123", name: "Super Admin" },
+  superAdmin: { email: "superadmin@blakeheritage.co.uk", name: "Super Admin" },
   barberHaircutOnly: { email: "leo@blakeheritage.co.uk", name: "Leo Vance" },
   barberSkinfadeBeard: { email: "jamie@blakeheritage.co.uk", name: "Jamie Wallace" },
   services: {
@@ -24,7 +30,32 @@ export const SEEDED = {
   },
 };
 
-export async function signIn(page: Page, email: string, password: string): Promise<void> {
+/**
+ * Reads a just-sent OTP code back out of the dev server's ConsoleEmailProvider
+ * capture buffer via /api/test/otp-code (see that route's own header — it
+ * 404s unless E2E_TEST_MODE is set, which playwright.config.ts's webServer
+ * does for exactly this). Polls briefly since the email is sent by a
+ * Server Action that may not have resolved the instant the client-side
+ * step transition happens.
+ *
+ * `sentAfter` (epoch ms) must be captured right before whatever action
+ * triggers the send — the same seeded users sign in repeatedly across this
+ * suite, so without it this could hand back a *previous*, already-consumed
+ * code still sitting in the buffer instead of the one just requested (see
+ * that route's own `since` param doc for the full reasoning).
+ */
+async function fetchOtpCode(page: Page, email: string, sentAfter: number): Promise<string> {
+  let code: string | null = null;
+  await expect(async () => {
+    const res = await page.request.get(`/api/test/otp-code?email=${encodeURIComponent(email)}&since=${sentAfter}`);
+    expect(res.ok()).toBe(true);
+    code = ((await res.json()) as { code: string }).code;
+  }).toPass({ timeout: 10_000 });
+  if (!code) throw new Error(`Test setup failed: no OTP code captured for ${email}.`);
+  return code;
+}
+
+export async function signIn(page: Page, email: string): Promise<void> {
   await page.goto("/sign-in");
   // Turbopack dev-mode compiles each route group on first visit — on a
   // cold server, a click that lands before that finishes (and before
@@ -33,7 +64,11 @@ export async function signIn(page: Page, email: string, password: string): Promi
   // race the very first visit to an as-yet-uncompiled route.
   await page.waitForLoadState("networkidle");
   await page.getByLabel("Email Address").fill(email);
-  await page.getByLabel("Password", { exact: true }).fill(password);
+  const requestedAt = Date.now();
+  await page.getByRole("button", { name: "Continue", exact: true }).click();
+
+  const code = await fetchOtpCode(page, email, requestedAt);
+  await page.getByLabel("Verification Code").fill(code);
   await page.getByRole("button", { name: "Sign In", exact: true }).click();
   // Not asserting a specific destination here — a bare sign-in (no
   // callbackUrl, which this helper never sets) now lands on a role-aware