fix(GRO-2572): follow Better Auth redirect URL from signIn.social response

Better Auth's signIn.social() returns { data: { redirect: true, url } } rather
than issuing an HTTP 30x when using the fetch client. The LoginPage handler
was discarding data.url, so the SSO button appeared to do nothing (the button
disabled but the user never left /login).

Fix: after the social sign-in call, if result.data.url is present, navigate via
window.location.href. Also add an early return in the error branch so the two
paths don't bleed into each other.

Updated UAT_PLAYBOOK.md §5.4.1 TC-WEB-SSO-2 to require a fresh/incognito
context so a stale auth cookie can't mask the regression.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

.gitignore

@@ -5,4 +5,14 @@ node_modules/
 dist/
 playwright-report/
 test-results/
-*.log
+*.log
+# Agent runtime artifacts — never commit
+.gh-token
+*.gh-token
+**/.gh-token
+.config/gh/
+**/.config/gh/
+**/AGENT_HOME/**
+$AGENT_HOME/**
+.claude/
+.codex/

UAT_PLAYBOOK.md

@@ -86,7 +86,7 @@ export const { signIn, signOut, useSession, changePassword } = authClient;
 | # | Scenario | Steps | Pass Criteria | Fail Criteria |
 |---|----------|-------|---------------|---------------|
 | TC-WEB-SSO-1 | Sign-in page shows SSO button | Navigate to app root URL | Sign-in page displayed with "Sign in with SSO" button visible | No SSO button, 403 before page loads |
-| TC-WEB-SSO-2 | Click SSO redirects to Authentik | Click "Sign in with SSO" button | Browser redirected to Authentik login at auth.farh.net | No redirect, error shown, button does nothing |
+| TC-WEB-SSO-2 | Click SSO redirects to Authentik (GRO-2572) | **Fresh session only (no pre-existing auth cookie).** Click "Sign in with SSO" button | Browser navigates to Authentik login at auth.farh.net within ~1 s — address bar changes to auth.farh.net URL | No redirect, error shown, button stays disabled, user remains on /login. Regression: prior to GRO-2572 fix the client never followed the `data.url` returned by Better Auth. Run from a clean incognito context to avoid a stale cookie masking the defect. |
 | TC-WEB-SSO-3 | Valid OIDC credentials authenticate | At Authentik, enter valid credentials and authenticate | Redirected back to app with active session | Redirect loop, 403, session not established |
 | TC-WEB-SSO-4 | Post-login dashboard accessible | After SSO flow completes, dashboard loads | Dashboard displays correctly with user identity shown | Blank page, 403, session not active |
 | TC-WEB-SSO-5 | User identity displayed correctly | After SSO login, check header/nav | User name/email/initials shown in nav, role reflected in UI | No user indicator, wrong user shown |
@@ -291,12 +291,18 @@ the seeded UAT customer (`uat-customer@groombook.dev`), not just unit-rendered.
 | TC-WEB-5.13.1 | Revenue charts | Navigate to Reports | Revenue charts display with data |
 | TC-WEB-5.13.2 | Utilization graphs | View reports | Staff/resource utilization graphs visible |
 
-### 5.14 Settings UI
+### 5.14 Settings UI (manager / super-user only — GRO-2513)
 
 | # | Scenario | Steps | Expected |
 |---|----------|-------|----------|
-| TC-WEB-5.14.1 | Configuration page | Navigate to Settings | Settings page loads without errors |
-| TC-WEB-5.14.2 | Form interactions | Modify settings, save | Settings saved successfully, changes reflected |
+| TC-WEB-5.14.1 | Manager sees Settings tab | Sign in as `uat-manager`, go to `/admin` | **Settings** link is visible in the admin nav bar |
+| TC-WEB-5.14.2 | Manager loads Settings page (200, no 403) | Click **Settings** in the nav | Page loads with Branding & Appearance form; DevTools → Network shows `GET /api/admin/settings` → **200**. Zero 403 responses anywhere in the Network tab. |
+| TC-WEB-5.14.3 | Manager can save branding | Modify Business Name, click Save | `PATCH /api/admin/settings` → 200; success message shown |
+| TC-WEB-5.14.4 | Super-user sees auth-provider section | Sign in as a super-user, navigate to Settings | Auth provider config section is visible below Branding |
+| TC-WEB-5.14.5 | Groomer does NOT see Settings tab | Sign in as `uat-groomer`, go to `/admin` | **Settings** link is **absent** from the nav bar. Network panel shows zero requests to `/api/admin/settings`. |
+| TC-WEB-5.14.6 | Groomer navigating directly to `/admin/settings` is redirected | While signed in as `uat-groomer`, navigate to `https://uat.groombook.dev/admin/settings` | Browser redirects to `/admin` (Appointments page). No 403 error in Network tab, no error UI. |
+| TC-WEB-5.14.7 | Receptionist does NOT see Settings tab | Sign in as `uat-receptionist` (if seeded), go to `/admin` | **Settings** link is **absent** from the nav bar. Network panel shows zero requests to `/api/admin/settings`. |
+| TC-WEB-5.14.8 | Shared staff endpoints still work for groomer | Sign in as `uat-groomer` and navigate through Appointments, Clients, Staff pages | All return 200. No 403 on any shared endpoint. |
 
 ### 5.15 Navigation
 
@@ -314,6 +320,15 @@ the seeded UAT customer (`uat-customer@groombook.dev`), not just unit-rendered.
 | TC-WEB-5.16.2 | PWA install prompt | Load app on supported browser | Install prompt appears when criteria met |
 | TC-WEB-5.16.3 | Touch interactions | Use touch gestures on mobile | All interactions work with touch input |
 
+#### 5.16a Portal Tab Rows — Mobile Overflow (GRO-730 / GRO-1026)
+
+| # | Scenario | Steps | Expected |
+|---|----------|-------|----------|
+| TC-WEB-5.16.4 | My Pets tab row — horizontal scroll, no visible scrollbar | Sign in as customer → My Pets. Set viewport to 390px. If 3+ pets are seeded, the pet-selector row overflows. | Pet selector row scrolls horizontally; native scrollbar is **not** visible (`scrollbar-width: none` / `scrollbar-hide` applied). |
+| TC-WEB-5.16.5 | My Pets section tab row — no visible scrollbar | On the same My Pets view, observe the tabs row (Basic Info / Medical / Grooming / History). | Tabs row scrolls horizontally when needed; native scrollbar is not visible. |
+| TC-WEB-5.16.6 | Billing/Payments tab row — no wrap, no visible scrollbar | Sign in as customer → Billing/Payments at 390px. | Tab row (Invoices / Payment Methods / Packages) does **not** wrap to a second line; scrolls horizontally if needed; native scrollbar not visible. |
+| TC-WEB-5.16.7 | Desktop — no visual regression | Open My Pets and Billing/Payments at ≥1024px. | No layout change; tab rows display identically to before the fix. |
+
 ### 5.17 Error & Empty States
 
 | # | Scenario | Steps | Expected |
@@ -446,8 +461,13 @@ These cases cover the `CustomerPortal` initialisation path that bridges an Authe
 | TC-WEB-5.25.2 | Bridge call sequence | Repeat TC-WEB-5.25.1 with DevTools → Network open and the **All** tab filtered to `/api/`. | In order: `GET /api/auth/get-session` → 200. `POST /api/portal/session-from-auth` → 201 with body `{ sessionId, clientId, clientName }`. |
 | TC-WEB-5.25.3 | Subsequent portal calls use the bridged session ID | After TC-WEB-5.25.1 succeeds, navigate to **Appointments**, **My Pets**, **Billing**, **Settings**. Inspect any `/api/portal/*` request in DevTools → Network. | Each portal API call carries an `X-Impersonation-Session-Id` header whose value equals the `sessionId` returned by `session-from-auth` (not a URL-param value). Each call returns 200 (or 404 for genuinely empty collections), never 401. |
 | TC-WEB-5.25.4 | No impersonation chrome for the customer's own session | After TC-WEB-5.25.1, scan the portal UI. | No amber border around the page. No "STAFF VIEW" watermark. No "End Impersonation" button in the sidebar. The customer is themselves; only impersonation sessions started via `?sessionId=` show the banner. |
-| TC-WEB-5.25.5 | 404 fallback for authenticated user with no client record | 1. Sign in via SSO with an Authentik account whose email is **not** present in `clients`. 2. Land on `/`. | `POST /api/portal/session-from-auth` returns 404. The portal renders a centred card titled **"Portal access not configured"** with the message about contacting the groomer and a **Sign out** button. No redirect loop, no portal chrome. |
-| TC-WEB-5.25.6 | 404 fallback Sign-out escape hatch | From TC-WEB-5.25.5 click **Sign out**. | `POST /api/auth/sign-out` fires; browser navigates to `/login`; the Authentik session cookie is cleared. Reloading `/` no longer hits 404 (will show the login page). |
+| TC-WEB-5.25.5 | 404 from SSO bridge routes to OOBE (GRO-2359) | 1. Sign in via SSO with an Authentik account whose email is **not** present in `clients`. 2. Land on `/`. | `POST /api/portal/session-from-auth` returns 404. The post-auth handler mounts the **OOBE** (`src/portal/OOBE.tsx`) — a centred card titled **"Welcome — let's set up your portal"** with form fields for name (prefilled from the Better Auth session), phone, address, and notes. The legacy "Portal access not configured" card is **not** rendered on the new-user path. No redirect loop, no portal chrome. |
+| TC-WEB-5.25.6 | OOBE form submission creates the portal (GRO-2359) | From TC-WEB-5.25.5, fill in the OOBE form and click **Create my portal**. | `POST /api/portal/clients-from-auth` is called with `{ name, phone, address, notes }`; the email is taken from the Better Auth session (the API binds the new client row to the SSO identity). The page reloads to `/`, the bridge re-runs, and the user lands in their portal dashboard. DevTools → Network shows `POST /api/portal/clients-from-auth` → 201 followed by `POST /api/portal/session-from-auth` → 201. |
+| TC-WEB-5.25.6b | OOBE handles portal selection (409 from clients-from-auth) (GRO-2359) | 1. Sign in via SSO with an email that already exists in `clients` (e.g. a previously deleted-then-recreated account). 2. Land on OOBE. 3. Click **Create my portal**. | The API returns 409 "A customer record with this email already exists". The OOBE re-enables the submit button and shows the portal-selection message: "A customer record with this email already exists. Please contact your groomer to link your account." The shared signOut() button remains reachable so the user can exit if needed. |
+| TC-WEB-5.25.6c | OOBE uses the shared signOut() handler (GRO-2358, GRO-2359) | From TC-WEB-5.25.5, click **Sign out** in the OOBE footer. | The same shared `signOut()` from `lib/auth-client` fires (same handler as `AdminLayout` and the no-access card); browser navigates to `/login`; the Authentik session cookie is cleared. The handler always navigates to `/login` — even if the network call to `/api/auth/sign-out` fails — so a transient auth-server hiccup never leaves the user trapped on an authenticated screen. |
+| TC-WEB-5.25.6d | OOBE is mountable from a direct deep-link (GRO-2359) | 1. Sign in via SSO as any customer. 2. In a new tab, navigate to `https://uat.groombook.dev/onboarding`. | The OOBE form mounts (the App.tsx `/onboarding` route resolves before the CustomerPortal `!sessionId` guards). The submit, signOut, and field-validation behaviour are identical to the post-auth mount. |
+| TC-WEB-5.25.6e | Deleted-portal deep-link still reaches the no-access card (GRO-2358, GRO-2359) | 1. Sign in via SSO as a customer whose `clients` row was disabled/deleted by the groomer. 2. Land on a portal sub-route with `?noAccess=deleted-portal` (e.g. visit `https://uat.groombook.dev/appointments?noAccess=deleted-portal` directly). | The no-access card renders (the deep-link deleted-portal case — the OOBE is reserved for first-time creation). The shared signOut() from GRO-2358 is wired identically. This proves the no-access card is still reachable for non-new-user failure modes and the CMPO "no-trap" invariant holds across the auth boundary. |
+| TC-WEB-5.25.6f | In-portal chrome sidebar exposes a Sign out button (GRO-2373) | 1. Complete TC-WEB-5.25.1 (SSO sign-in as a customer). 2. From the portal chrome, look at the sidebar footer (the section below the navigation links, where "Customer Portal v1.0" sits). 3. Locate the **Sign out** button (a stone-grey button above the version label, with a LogOut icon). 4. Click it. | A **Sign out** button is present in the sidebar footer (not buried in the Settings page, not hidden in a dropdown — it's visible on every portal sub-route, including Home, Appointments, My Pets, Report Cards, Billing, Messages, Settings). Clicking it fires the same shared `signOut()` from `lib/auth-client` (same handler as the OOBE footer, the no-access card, and `AdminLayout`'s top-bar "Logout"); `POST /api/auth/sign-out` → 200 `{"success":true}`; the browser navigates to `/login`; the Better Auth / Authentik session cookie is cleared. Proves the CMPO "no-trap" invariant (originally established in GRO-2355) holds on the third authenticated surface — the in-portal chrome — which the GRO-2358 P1 fix did not cover. |
 | TC-WEB-5.25.7 | Bridge precedence — impersonation URL wins | 1. Sign in via SSO as a customer. 2. Open a new tab to `https://uat.groombook.dev/?sessionId=<a-valid-staff-impersonation-session-id>`. | The impersonation path runs; the amber banner appears for the impersonated client. The Better Auth bridge is **not** called on this load (`session-from-auth` absent in Network). |
 | TC-WEB-5.25.8 | Bridge precedence — dev user wins | In dev mode (e.g. local) with `localStorage["dev-user"]` set to a client persona, navigate to `/`. | The dev-session path runs (`POST /api/portal/dev-session`). The Better Auth bridge is **not** called (`session-from-auth` absent in Network). Staff dev users still redirect to `/admin`. |
 | TC-WEB-5.25.9 | Staff Better Auth session does not run the customer bridge | Sign in via SSO with a staff identity. Navigate to `/`. | `App.tsx` routing redirects to `/admin`. `POST /api/portal/session-from-auth` is **not** called. |

src/App.tsx

@@ -16,6 +16,7 @@ import { BookingCancelledPage } from "./pages/BookingCancelled.js";
 import { BookingErrorPage } from "./pages/BookingError.js";
 import { SetupWizard } from "./pages/SetupWizard.tsx";
 import { CustomerPortal } from "./portal/CustomerPortal.js";
+import { OOBE } from "./portal/OOBE.js";
 import { DevLoginSelector, getDevUser } from "./pages/DevLoginSelector.js";
 import { DevSessionIndicator } from "./components/DevSessionIndicator.js";
 import { BrandingProvider, useBranding } from "./BrandingContext.js";
@@ -44,6 +45,12 @@ function LoginPage() {
     if (result?.error) {
       setError(result.error.message ?? "Sign-in failed");
       setIsLoading(false);
+      return;
+    }
+    // Better Auth returns the IdP authorize URL in data.url with redirect:true rather than
+    // issuing an HTTP 30x — the client must follow it (GRO-2572).
+    if (result?.data?.url) {
+      window.location.href = result.data.url;
     }
   };
 
@@ -186,6 +193,17 @@ function AdminLayout() {
   const location = useLocation();
   const navigate = useNavigate();
   const { branding } = useBranding();
+  const [staffUser, setStaffUser] = useState<{ role: string; isSuperUser: boolean } | null>(null);
+
+  useEffect(() => {
+    fetch("/api/staff/me")
+      .then((r) => r.json())
+      .then((u) => setStaffUser({ role: u.role, isSuperUser: !!u.isSuperUser }))
+      .catch(() => setStaffUser({ role: "", isSuperUser: false }));
+  }, []);
+
+  const canSettings = staffUser !== null && (staffUser.role === "manager" || staffUser.isSuperUser);
+  const visibleNavLinks = NAV_LINKS.filter(({ to }) => to !== "/admin/settings" || canSettings);
 
   const logoSrc = branding.logoBase64 && branding.logoMimeType
     ? `data:${branding.logoMimeType};base64,${branding.logoBase64}`
@@ -250,7 +268,7 @@ function AdminLayout() {
           >
             Book
           </Link>
-          {NAV_LINKS.map(({ to, label }) => {
+          {visibleNavLinks.map(({ to, label }) => {
             const active =
               to === "/admin"
                 ? location.pathname === "/admin"
@@ -307,7 +325,13 @@ function AdminLayout() {
           <Route path="/group-bookings" element={<GroupBookingPage />} />
           <Route path="/routes" element={<RoutesPage />} />
           <Route path="/reports" element={<ReportsPage />} />
-          <Route path="/settings" element={<SettingsPage />} />
+          <Route path="/settings" element={
+            staffUser === null
+              ? null
+              : canSettings
+                ? <SettingsPage />
+                : <Navigate to="/admin" replace />
+          } />
         </Routes>
       </main>
     </div>
@@ -406,7 +430,13 @@ export function App() {
   }
 
   // Don't render portal chrome at /login — DevLoginSelector is shown instead
-  const showCustomerPortal = !location.pathname.startsWith("/admin") && location.pathname !== "/login";
+  const showCustomerPortal = !location.pathname.startsWith("/admin") && location.pathname !== "/login" && location.pathname !== "/onboarding";
+  // GRO-2359: OOBE is mountable from a direct link (deep-link to /onboarding)
+  // and from the post-auth callback (CustomerPortal navigates here when the
+  // SSO bridge returns 404). Render the OOBE component standalone so it's
+  // outside the portal chrome (no `!sessionId` guards, no `!initComplete`
+  // loading states to fight — the OOBE handles its own auth resolution).
+  const showOOBE = location.pathname === "/onboarding";
 
   // At /login with a valid session, redirect to the portal root. Without this,
   // the final render returns null at /login (showCustomerPortal is false) and
@@ -425,6 +455,11 @@ export function App() {
           </Routes>
           {authDisabled && <DevSessionIndicator />}
         </>
+      ) : showOOBE ? (
+        <>
+          <OOBE />
+          {authDisabled && <DevSessionIndicator />}
+        </>
       ) : showCustomerPortal ? (
         <>
           <CustomerPortal />

src/__tests__/App.test.tsx

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { render, screen, within, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import { MemoryRouter } from "react-router-dom";
 import { App } from "../App";
 
@@ -232,6 +233,7 @@ describe("Dev login selector", () => {
   });
 
   it("does not redirect when a dev user is already selected", async () => {
+
     localStorage.setItem("dev-user", JSON.stringify({ type: "staff", id: "s1", name: "Sarah" }));
 
     global.fetch = vi.fn((url: string) => {
@@ -269,3 +271,61 @@ describe("Dev login selector", () => {
     ).toBeInTheDocument();
   });
 });
+
+describe("GRO-2572 — SSO button follows redirect URL", () => {
+  it("navigates to data.url when signIn.social returns a redirect", async () => {
+    // Mock signIn.social to return the redirect payload Better Auth sends
+    vi.mock("../lib/auth-client.js", () => ({
+      useSession: () => ({ data: null, isPending: false }),
+      signIn: {
+        social: vi.fn().mockResolvedValue({
+          data: { redirect: true, url: "https://auth.farh.net/application/o/authorize/?test=1" },
+          error: null,
+        }),
+      },
+      signOut: vi.fn(),
+      changePassword: vi.fn(),
+    }));
+
+    const assignMock = vi.fn();
+    Object.defineProperty(window, "location", {
+      value: { ...window.location, href: "", origin: "https://uat.groombook.dev" },
+      writable: true,
+    });
+    Object.defineProperty(window.location, "href", {
+      set: assignMock,
+      get: () => "",
+    });
+
+    global.fetch = vi.fn((url: string) => {
+      if (url === "/api/dev/config") {
+        return Promise.resolve({ ok: true, json: async () => ({ authDisabled: false }) } as Response);
+      }
+      if (url === "/api/auth/get-session") {
+        return Promise.resolve({ ok: true, json: async () => null } as unknown as Response);
+      }
+      if (url === "/api/setup/status") {
+        return Promise.resolve({ ok: true, json: async () => ({ needsSetup: false }) } as Response);
+      }
+      if (url === "/api/auth/providers") {
+        return Promise.resolve({ ok: true, json: async () => ({ providers: ["authentik"] }) } as Response);
+      }
+      return Promise.resolve({ ok: true, json: async () => [] } as Response);
+    }) as unknown as typeof fetch;
+
+    render(
+      <MemoryRouter initialEntries={["/login"]}>
+        <App />
+      </MemoryRouter>
+    );
+
+    const ssoButton = await screen.findByRole("button", { name: /sign in with sso/i });
+    await userEvent.click(ssoButton);
+
+    await waitFor(() => {
+      expect(assignMock).toHaveBeenCalledWith(
+        "https://auth.farh.net/application/o/authorize/?test=1"
+      );
+    });
+  });
+});

src/__tests__/portal.test.tsx

@@ -21,6 +21,18 @@ vi.mock("../portal/sections/Appointments.js", async () => {
   };
 });
 
+// Spy on the canonical `signOut()` from the shared auth-client so we can
+// assert the no-access screen's logout button uses the SAME handler as
+// `AdminLayout`. We mock at the module boundary — the no-access screen is
+// the one authenticated surface that renders without the portal chrome, so
+// a regression here would trap the user. We do NOT use `importActual`
+// because the real `createAuthClient()` requires a runtime `baseURL`
+// (Better Auth) that the JSDOM test environment can't supply.
+const signOutSpy = vi.hoisted(() => vi.fn(async () => undefined));
+vi.mock("../lib/auth-client.js", () => ({
+  signOut: signOutSpy,
+}));
+
 const SESSION: ImpersonationSession = {
   id: "sess-1",
   staffId: "staff-1",
@@ -52,6 +64,22 @@ const AUDIT_LOGS: ImpersonationAuditLog[] = [
   },
 ];
 
+// ─── Shared test fixtures ───────────────────────────────────────────────────
+
+// `brandingResponse` is the mock /api/branding payload used by every test
+// in this file. Hoisted to module scope so the SSO bridge and the OOBE
+// describe blocks can both reach it without redefining the same body.
+const brandingResponse = {
+  ok: true,
+  json: async () => ({
+    businessName: "GroomBook",
+    primaryColor: "#4f8a6f",
+    accentColor: "#8b7355",
+    logoBase64: null,
+    logoMimeType: null,
+  }),
+} as Response;
+
 // ─── ImpersonationBanner ────────────────────────────────────────────────────
 
 describe("ImpersonationBanner", () => {
@@ -336,19 +364,10 @@ describe("CustomerPortal SSO bridge", () => {
   beforeEach(() => {
     // Make sure no dev-user leaks across tests
     window.localStorage.clear();
+    // Reset shared signOut() spy so per-test counts are deterministic
+    signOutSpy.mockClear();
   });
 
-  const brandingResponse = {
-    ok: true,
-    json: async () => ({
-      businessName: "GroomBook",
-      primaryColor: "#4f8a6f",
-      accentColor: "#8b7355",
-      logoBase64: null,
-      logoMimeType: null,
-    }),
-  } as Response;
-
   it("bridges Better Auth session via /api/portal/session-from-auth and uses returned sessionId", async () => {
     global.fetch = vi.fn((input: RequestInfo, init?: RequestInit) => {
       const url = typeof input === "string" ? input : input.toString();
@@ -394,14 +413,21 @@ describe("CustomerPortal SSO bridge", () => {
     expect(screen.queryByRole("button", { name: /End Session/i })).not.toBeInTheDocument();
   });
 
-  it("shows a friendly fallback when session-from-auth returns 404 (no client record)", async () => {
+  it("routes to /onboarding when session-from-auth returns 404 (GRO-2359)", async () => {
+    // GRO-2359 replaces the P1 no-access fallback for the new-user path.
+    // The post-auth handler must now navigate to /onboarding so the OOBE
+    // component can drive portal creation. The no-access card itself is
+    // reserved for the deep-link deleted-portal case (see the next two
+    // tests, which exercise ?noAccess=deleted-portal).
     global.fetch = vi.fn((input: RequestInfo) => {
       const url = typeof input === "string" ? input : input.toString();
       if (url === "/api/branding") return Promise.resolve(brandingResponse);
       if (url === "/api/auth/get-session") {
         return Promise.resolve({
           ok: true,
-          json: async () => ({ user: { email: "stranger@example.com", role: "customer" } }),
+          json: async () => ({
+            user: { email: "stranger@example.com", name: "Stranger", role: "customer" },
+          }),
         } as Response);
       }
       if (url === "/api/portal/session-from-auth") {
@@ -414,6 +440,9 @@ describe("CustomerPortal SSO bridge", () => {
       return Promise.resolve({ ok: true, json: async () => ({}) } as Response);
     }) as unknown as typeof fetch;
 
+    // MemoryRouter is required for the React Router context used by
+    // useNavigate inside CustomerPortal. We pass `initialEntries=["/"]`
+    // and let the post-auth handler navigate the router to /onboarding.
     const { CustomerPortal } = await import("../portal/CustomerPortal.js");
     render(
       <MemoryRouter initialEntries={["/"]}>
@@ -421,12 +450,156 @@ describe("CustomerPortal SSO bridge", () => {
       </MemoryRouter>
     );
 
+    // The bridge 404 must NOT render the legacy no-access card. The OOBE
+    // form is the new-user surface.
+    await waitFor(() => {
+      expect(screen.getByText(/set up your portal/i)).toBeInTheDocument();
+    });
+    expect(screen.queryByText(/Portal access not configured/i)).not.toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /Create my portal/i })).toBeInTheDocument();
+  });
+
+  it("calls the shared signOut() handler and navigates to /login from the no-access screen (GRO-2358)", async () => {
+    // Reset the spy so previous tests don't leak into this assertion.
+    signOutSpy.mockClear();
+
+    // JSDOM throws on window.location.href assignment by default; swap in a
+    // writable stub so the navigation is observable, then restore after.
+    const originalLocation = window.location;
+    Object.defineProperty(window, "location", {
+      value: { href: "" },
+      writable: true,
+      configurable: true,
+    });
+
+    // GRO-2359: the post-auth bridge 404 now routes to /onboarding (OOBE)
+    // on the new-user path. The no-access card itself is reserved for the
+    // deep-link deleted-portal case, which is signalled via
+    // ?noAccess=deleted-portal. A server-side "client disabled" check
+    // (future GRO) is the natural trigger.
+    global.fetch = vi.fn((input: RequestInfo) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url === "/api/branding") return Promise.resolve(brandingResponse);
+      if (url === "/api/auth/get-session") {
+        return Promise.resolve({
+          ok: true,
+          json: async () => ({ user: { email: "stranger@example.com", role: "customer" } }),
+        } as Response);
+      }
+      // The bridge must NOT succeed (so portalSessionId stays null) and must
+      // NOT be 404 (which would route to /onboarding). A 500 models a
+      // server-side portal-disabled check; the no-access card is mounted
+      // because of the URL param, not because of the bridge.
+      if (url === "/api/portal/session-from-auth") {
+        return Promise.resolve({
+          ok: false,
+          status: 500,
+          json: async () => ({ error: "Portal disabled" }),
+        } as Response);
+      }
+      return Promise.resolve({ ok: true, json: async () => ({}) } as Response);
+    }) as unknown as typeof fetch;
+
+    const { CustomerPortal } = await import("../portal/CustomerPortal.js");
+    render(
+      <MemoryRouter initialEntries={["/?noAccess=deleted-portal"]}>
+        <CustomerPortal />
+      </MemoryRouter>
+    );
+
     await waitFor(() => {
       expect(screen.getByText(/Portal access not configured/i)).toBeInTheDocument();
     });
-    expect(screen.getByText(/not linked to a customer record/i)).toBeInTheDocument();
-    // Sign-out escape hatch is present so the user is not stuck in a loop
-    expect(screen.getByRole("button", { name: /Sign out/i })).toBeInTheDocument();
+
+    // Pre-condition: the shared signOut() must NOT have been called yet — the
+    // no-access screen is mounted because of the deleted-portal signal, not
+    // because the user clicked anything.
+    expect(signOutSpy).not.toHaveBeenCalled();
+
+    // Drive the click. The handler is the SAME `signOut()` exported from
+    // auth-client that AdminLayout uses, so verifying this call is enough to
+    // prove the no-access screen reaches the canonical sign-out surface.
+    const signOutButton = screen.getByRole("button", { name: /Sign out/i });
+    fireEvent.click(signOutButton);
+
+    await waitFor(() => {
+      expect(signOutSpy).toHaveBeenCalledTimes(1);
+    });
+
+    // The handler always navigates to /login — even if the network call to
+    // /api/auth/sign-out fails — so a transient auth-server hiccup never
+    // leaves the user trapped on an authenticated screen.
+    await waitFor(() => {
+      expect(window.location.href).toBe("/login");
+    });
+
+    Object.defineProperty(window, "location", { value: originalLocation, configurable: true });
+  });
+
+  it("reaches the same shared signOut() on a deep-link no-access screen (GRO-2358)", async () => {
+    // AC requires verifying the SAME logout handler is reachable from at
+    // least one other authenticated surface — here a deep link to a portal
+    // sub-route (e.g. /appointments) for a user with a Better Auth session
+    // whose portal was deleted. The no-access screen is the only
+    // authenticated surface without a route guard, so the handler must
+    // fire identically.
+    //
+    // GRO-2359: the bridge 404 now routes to /onboarding (OOBE) on the
+    // new-user path; ?noAccess=deleted-portal is the surviving trigger.
+    signOutSpy.mockClear();
+
+    const originalLocation = window.location;
+    Object.defineProperty(window, "location", {
+      value: { href: "" },
+      writable: true,
+      configurable: true,
+    });
+
+    global.fetch = vi.fn((input: RequestInfo) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url === "/api/branding") return Promise.resolve(brandingResponse);
+      if (url === "/api/auth/get-session") {
+        return Promise.resolve({
+          ok: true,
+          json: async () => ({ user: { email: "stranger@example.com", role: "customer" } }),
+        } as Response);
+      }
+      // The bridge must NOT succeed (so portalSessionId stays null) and must
+      // NOT be 404 (which would route to /onboarding). A 500 models a
+      // server-side portal-disabled check; the no-access card is mounted
+      // because of the URL param, not because of the bridge.
+      if (url === "/api/portal/session-from-auth") {
+        return Promise.resolve({
+          ok: false,
+          status: 500,
+          json: async () => ({ error: "Portal disabled" }),
+        } as Response);
+      }
+      return Promise.resolve({ ok: true, json: async () => ({}) } as Response);
+    }) as unknown as typeof fetch;
+
+    const { CustomerPortal } = await import("../portal/CustomerPortal.js");
+    render(
+      <MemoryRouter initialEntries={["/appointments?noAccess=deleted-portal"]}>
+        <CustomerPortal />
+      </MemoryRouter>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText(/Portal access not configured/i)).toBeInTheDocument();
+    });
+
+    const signOutButton = screen.getByRole("button", { name: /Sign out/i });
+    fireEvent.click(signOutButton);
+
+    await waitFor(() => {
+      expect(signOutSpy).toHaveBeenCalledTimes(1);
+    });
+    await waitFor(() => {
+      expect(window.location.href).toBe("/login");
+    });
+
+    Object.defineProperty(window, "location", { value: originalLocation, configurable: true });
   });
 
   it("does not call session-from-auth when there is no Better Auth session", async () => {
@@ -613,3 +786,346 @@ describe("CustomerPortal SSO bridge", () => {
     });
   });
 });
+
+describe("OOBE portal-creation flow (GRO-2359)", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+  });
+
+  // The OOBE is mounted both from the post-auth callback (CustomerPortal
+  // navigates to /onboarding on bridge 404) and from a direct deep-link.
+  // This set of tests exercises the direct-link mount, the form submit, and
+  // the shared signOut() handler. The post-auth routing is covered by the
+  // "routes to /onboarding when session-from-auth returns 404" test above.
+
+  function setupOOBEAuthMock(opts: { role?: string } = {}) {
+    const role = opts.role ?? "customer";
+    return vi.fn((input: RequestInfo) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url === "/api/branding") return Promise.resolve(brandingResponse);
+      if (url === "/api/auth/get-session") {
+        return Promise.resolve({
+          ok: true,
+          json: async () => ({
+            user: { email: "new-sso@example.com", name: "New SSO", role },
+          }),
+        } as Response);
+      }
+      return Promise.resolve({ ok: true, json: async () => ({}) } as Response);
+    }) as unknown as typeof fetch;
+  }
+
+  it("renders the OOBE form when navigated to /onboarding directly (GRO-2359)", async () => {
+    global.fetch = setupOOBEAuthMock();
+
+    const { OOBE } = await import("../portal/OOBE.js");
+    render(
+      <MemoryRouter initialEntries={["/onboarding"]}>
+        <OOBE />
+      </MemoryRouter>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByRole("heading", { name: /set up your portal/i })).toBeInTheDocument();
+    });
+    // All three primary form fields are present.
+    expect(screen.getByLabelText(/your name/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/phone/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/address/i)).toBeInTheDocument();
+    // Submit and shared signOut are both present.
+    expect(screen.getByRole("button", { name: /Create my portal/i })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /Sign out/i })).toBeInTheDocument();
+  });
+
+  it("prefills the name field from the Better Auth session (GRO-2359)", async () => {
+    global.fetch = setupOOBEAuthMock();
+
+    const { OOBE } = await import("../portal/OOBE.js");
+    render(
+      <MemoryRouter initialEntries={["/onboarding"]}>
+        <OOBE />
+      </MemoryRouter>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByLabelText(/your name/i)).toHaveValue("New SSO");
+    });
+  });
+
+  it("calls POST /api/portal/clients-from-auth and navigates to / on success (GRO-2359)", async () => {
+    const fetchMock = vi.fn((input: RequestInfo, init?: RequestInit) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url === "/api/branding") return Promise.resolve(brandingResponse);
+      if (url === "/api/auth/get-session") {
+        return Promise.resolve({
+          ok: true,
+          json: async () => ({
+            user: { email: "new-sso@example.com", name: "New SSO", role: "customer" },
+          }),
+        } as Response);
+      }
+      if (url === "/api/portal/clients-from-auth" && init?.method === "POST") {
+        return Promise.resolve({
+          ok: true,
+          status: 201,
+          json: async () => ({
+            id: "new-client-id",
+            name: "New SSO",
+            email: "new-sso@example.com",
+          }),
+        } as Response);
+      }
+      return Promise.resolve({ ok: true, json: async () => ({}) } as Response);
+    }) as unknown as typeof fetch;
+    global.fetch = fetchMock;
+
+    const { OOBE } = await import("../portal/OOBE.js");
+    render(
+      <MemoryRouter initialEntries={["/onboarding"]}>
+        <OOBE />
+      </MemoryRouter>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByLabelText(/your name/i)).toHaveValue("New SSO");
+    });
+
+    // Fill phone + address and submit.
+    fireEvent.change(screen.getByLabelText(/phone/i), {
+      target: { value: "555-1234" },
+    });
+    fireEvent.change(screen.getByLabelText(/address/i), {
+      target: { value: "1 Main St" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /Create my portal/i }));
+
+    // The endpoint must have been called with the form values, normalised
+    // (phone/address trimmed). We don't assert navigation here because the
+    // MemoryRouter would need a history prop to assert a URL change — the
+    // internal `navigate("/")` call is the contract.
+    await waitFor(() => {
+      const calls = vi.mocked(fetchMock).mock.calls;
+      const onboardCall = calls.find(([u]) =>
+        typeof u === "string" && (u as string).endsWith("/api/portal/clients-from-auth"),
+      );
+      expect(onboardCall).toBeDefined();
+      const body = JSON.parse(((onboardCall?.[1] as RequestInit | undefined)?.body as string) ?? "{}");
+      expect(body).toEqual({
+        name: "New SSO",
+        phone: "555-1234",
+        address: "1 Main St",
+        notes: null,
+      });
+    });
+  });
+
+  it("shows the portal-selection message when the API returns 409 (GRO-2359)", async () => {
+    global.fetch = vi.fn((input: RequestInfo, init?: RequestInit) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url === "/api/branding") return Promise.resolve(brandingResponse);
+      if (url === "/api/auth/get-session") {
+        return Promise.resolve({
+          ok: true,
+          json: async () => ({
+            user: { email: "new-sso@example.com", name: "New SSO", role: "customer" },
+          }),
+        } as Response);
+      }
+      if (url === "/api/portal/clients-from-auth" && init?.method === "POST") {
+        return Promise.resolve({
+          ok: false,
+          status: 409,
+          json: async () => ({ error: "A customer record with this email already exists" }),
+        } as Response);
+      }
+      return Promise.resolve({ ok: true, json: async () => ({}) } as Response);
+    }) as unknown as typeof fetch;
+
+    const { OOBE } = await import("../portal/OOBE.js");
+    render(
+      <MemoryRouter initialEntries={["/onboarding"]}>
+        <OOBE />
+      </MemoryRouter>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByLabelText(/your name/i)).toHaveValue("New SSO");
+    });
+    fireEvent.click(screen.getByRole("button", { name: /Create my portal/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText(/already exists/i)).toBeInTheDocument();
+    });
+    // The submit button is re-enabled after the error so the user can retry.
+    expect(screen.getByRole("button", { name: /Create my portal/i })).not.toBeDisabled();
+  });
+
+  it("requires the name field before submitting (GRO-2359)", async () => {
+    // Use a session WITHOUT a name so the OOBE starts with an empty form.
+    global.fetch = vi.fn((input: RequestInfo) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url === "/api/branding") return Promise.resolve(brandingResponse);
+      if (url === "/api/auth/get-session") {
+        return Promise.resolve({
+          ok: true,
+          json: async () => ({ user: { email: "noname@example.com", role: "customer" } }),
+        } as Response);
+      }
+      return Promise.resolve({ ok: true, json: async () => ({}) } as Response);
+    }) as unknown as typeof fetch;
+
+    const { OOBE } = await import("../portal/OOBE.js");
+    render(
+      <MemoryRouter initialEntries={["/onboarding"]}>
+        <OOBE />
+      </MemoryRouter>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByLabelText(/your name/i)).toHaveValue("");
+    });
+    fireEvent.click(screen.getByRole("button", { name: /Create my portal/i }));
+
+    // The name-required error is shown; no API call was made.
+    await waitFor(() => {
+      expect(screen.getByText(/tell us your name/i)).toBeInTheDocument();
+    });
+  });
+
+  it("uses the shared signOut() handler on the OOBE Sign out button (GRO-2359)", async () => {
+    signOutSpy.mockClear();
+    const originalLocation = window.location;
+    Object.defineProperty(window, "location", {
+      value: { href: "" },
+      writable: true,
+      configurable: true,
+    });
+
+    global.fetch = setupOOBEAuthMock();
+
+    const { OOBE } = await import("../portal/OOBE.js");
+    render(
+      <MemoryRouter initialEntries={["/onboarding"]}>
+        <OOBE />
+      </MemoryRouter>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: /Sign out/i })).toBeInTheDocument();
+    });
+    fireEvent.click(screen.getByRole("button", { name: /Sign out/i }));
+
+    // Same canonical handler as AdminLayout and the no-access card, per
+    // GRO-2358 — never a raw fetch("/api/auth/sign-out").
+    await waitFor(() => {
+      expect(signOutSpy).toHaveBeenCalledTimes(1);
+    });
+    await waitFor(() => {
+      expect(window.location.href).toBe("/login");
+    });
+
+    Object.defineProperty(window, "location", { value: originalLocation, configurable: true });
+  });
+
+  it("redirects to /login when no Better Auth session is present (GRO-2359)", async () => {
+    const originalLocation = window.location;
+    Object.defineProperty(window, "location", {
+      value: { href: "" },
+      writable: true,
+      configurable: true,
+    });
+
+    global.fetch = vi.fn((input: RequestInfo) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url === "/api/branding") return Promise.resolve(brandingResponse);
+      if (url === "/api/auth/get-session") {
+        return Promise.resolve({ ok: false, status: 401, json: async () => ({}) } as Response);
+      }
+      return Promise.resolve({ ok: true, json: async () => ({}) } as Response);
+    }) as unknown as typeof fetch;
+
+    const { OOBE } = await import("../portal/OOBE.js");
+    render(
+      <MemoryRouter initialEntries={["/onboarding"]}>
+        <OOBE />
+      </MemoryRouter>
+    );
+
+    await waitFor(() => {
+      expect(window.location.href).toBe("/login");
+    });
+
+    Object.defineProperty(window, "location", { value: originalLocation, configurable: true });
+  });
+
+  it("reaches the shared signOut() handler from the in-portal chrome sidebar (GRO-2373)", async () => {
+    // Pre-GRO-2373, the customer portal chrome (Home, Appointments, My Pets,
+    // Report Cards, Billing, Messages, Settings) had no visible sign-out
+    // control — only the OOBE and the no-access card exposed one. This
+    // leaves users signed-in with no escape hatch. The fix lands a
+    // "Sign out" button in the sidebar footer that wires to the same
+    // canonical `signOut()` already used by OOBE / no-access / AdminLayout.
+    signOutSpy.mockClear();
+
+    const originalLocation = window.location;
+    Object.defineProperty(window, "location", {
+      value: { href: "" },
+      writable: true,
+      configurable: true,
+    });
+
+    global.fetch = vi.fn((input: RequestInfo, init?: RequestInit) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url === "/api/branding") return Promise.resolve(brandingResponse);
+      if (url === "/api/auth/get-session") {
+        return Promise.resolve({
+          ok: true,
+          json: async () => ({ user: { email: "uat-customer@groombook.dev", role: "customer" } }),
+        } as Response);
+      }
+      if (url === "/api/portal/session-from-auth" && init?.method === "POST") {
+        return Promise.resolve({
+          ok: true,
+          status: 201,
+          json: async () => ({ sessionId: "chrome-sess-1", clientId: "client-1", clientName: "Jane Doe" }),
+        } as Response);
+      }
+      return Promise.resolve({ ok: true, json: async () => ({}) } as Response);
+    }) as unknown as typeof fetch;
+
+    const { CustomerPortal } = await import("../portal/CustomerPortal.js");
+    render(
+      <MemoryRouter initialEntries={["/"]}>
+        <CustomerPortal />
+      </MemoryRouter>
+    );
+
+    // Land on the chrome (proof: customer greeting is rendered, no
+    // no-access card, no OOBE).
+    await waitFor(() => {
+      expect(screen.getByText(/Hi, Jane/)).toBeInTheDocument();
+    });
+    expect(screen.queryByText(/Portal access not configured/i)).not.toBeInTheDocument();
+    expect(screen.queryByText(/set up your portal/i)).not.toBeInTheDocument();
+
+    // The new chrome sign-out is scoped by data-testid so it doesn't
+    // collide with other surfaces that may also render "Sign out" labels
+    // (e.g. the impersonation banner uses "End Session").
+    const signOutButton = screen.getByTestId("portal-chrome-signout");
+    expect(signOutButton).toHaveTextContent(/Sign out/i);
+    fireEvent.click(signOutButton);
+
+    // Same canonical handler as OOBE / no-access / AdminLayout — never
+    // a raw fetch("/api/auth/sign-out") and never a navigate() without
+    // signOut() (the OOBE/no-access surface uses window.location.href
+    // for a hard reload so cached state is reset).
+    await waitFor(() => {
+      expect(signOutSpy).toHaveBeenCalledTimes(1);
+    });
+    await waitFor(() => {
+      expect(window.location.href).toBe("/login");
+    });
+
+    Object.defineProperty(window, "location", { value: originalLocation, configurable: true });
+  });
+});

src/index.css

@@ -78,6 +78,15 @@ input:focus, select:focus, textarea:focus {
   box-shadow: 0 1px 3px rgba(0, 0, 0, 0.04);
 }
 
+/* ─── Scrollbar hide utility ─── */
+.scrollbar-hide {
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+}
+.scrollbar-hide::-webkit-scrollbar {
+  display: none;
+}
+
 /* ─── Scrollbar polish ─── */
 ::-webkit-scrollbar {
   width: 6px;

src/pages/Settings.tsx

@@ -86,51 +86,66 @@ export function SettingsPage() {
   const [loaded, setLoaded] = useState(false);
   const fileInputRef = useRef<HTMLInputElement>(null);
 
+  // Load user role first, then gate settings/auth-provider fetches on role
   useEffect(() => {
-    fetch("/api/admin/settings")
+    fetch("/api/staff/me")
       .then((r) => r.json())
-      .then(async (data) => {
-        // The logo is now proxied through the API server so the browser
-        // never receives an S3 URL — use the proxy path directly as the src.
-        setForm({
-          businessName: data.businessName ?? "GroomBook",
-          primaryColor: data.primaryColor ?? "#4f8a6f",
-          accentColor: data.accentColor ?? "#8b7355",
-          logoKey: data.logoKey ?? null,
-          logoUrl: data.logoKey ? "/api/admin/settings/logo" : null,
-          logoBase64: data.logoBase64 ?? null,
-          logoMimeType: data.logoMimeType ?? null,
-        });
-        setLoaded(true);
-      })
-      .catch(() => setLoaded(true));
-  }, []);
+      .then((u) => {
+        const user = u as CurrentUser;
+        setCurrentUser(user);
+        const isManager = user.role === "manager" || user.isSuperUser;
 
-  // Load current user (for isSuperUser check) and auth provider config
-  useEffect(() => {
-    Promise.all([
-      fetch("/api/staff/me").then((r) => r.json()).catch(() => null),
-      fetch("/api/admin/auth-provider").then(async (r) => {
-        if (r.ok) return r.json();
-        if (r.status === 404) return null;
-        throw new Error(`HTTP ${r.status}`);
-      }).catch(() => null),
-    ]).then(([user, auth]) => {
-      setCurrentUser(user as CurrentUser | null);
-      if (auth) {
-        setAuthConfig(auth as AuthProviderConfig);
-        setAuthForm({
-          providerId: (auth as AuthProviderConfig).providerId,
-          displayName: (auth as AuthProviderConfig).displayName,
-          issuerUrl: (auth as AuthProviderConfig).issuerUrl,
-          internalBaseUrl: (auth as AuthProviderConfig).internalBaseUrl ?? "",
-          clientId: (auth as AuthProviderConfig).clientId,
-          clientSecret: (auth as AuthProviderConfig).clientSecret,
-          scopes: (auth as AuthProviderConfig).scopes,
-        });
-      }
-      setAuthLoaded(true);
-    });
+        if (isManager) {
+          fetch("/api/admin/settings")
+            .then((r) => r.json())
+            .then((data) => {
+              setForm({
+                businessName: data.businessName ?? "GroomBook",
+                primaryColor: data.primaryColor ?? "#4f8a6f",
+                accentColor: data.accentColor ?? "#8b7355",
+                logoKey: data.logoKey ?? null,
+                logoUrl: data.logoKey ? "/api/admin/settings/logo" : null,
+                logoBase64: data.logoBase64 ?? null,
+                logoMimeType: data.logoMimeType ?? null,
+              });
+              setLoaded(true);
+            })
+            .catch(() => setLoaded(true));
+        } else {
+          setLoaded(true);
+        }
+
+        if (user.isSuperUser) {
+          fetch("/api/admin/auth-provider")
+            .then(async (r) => {
+              if (r.ok) return r.json();
+              if (r.status === 404) return null;
+              throw new Error(`HTTP ${r.status}`);
+            })
+            .then((auth) => {
+              if (auth) {
+                setAuthConfig(auth as AuthProviderConfig);
+                setAuthForm({
+                  providerId: (auth as AuthProviderConfig).providerId,
+                  displayName: (auth as AuthProviderConfig).displayName,
+                  issuerUrl: (auth as AuthProviderConfig).issuerUrl,
+                  internalBaseUrl: (auth as AuthProviderConfig).internalBaseUrl ?? "",
+                  clientId: (auth as AuthProviderConfig).clientId,
+                  clientSecret: (auth as AuthProviderConfig).clientSecret,
+                  scopes: (auth as AuthProviderConfig).scopes,
+                });
+              }
+              setAuthLoaded(true);
+            })
+            .catch(() => setAuthLoaded(true));
+        } else {
+          setAuthLoaded(true);
+        }
+      })
+      .catch(() => {
+        setLoaded(true);
+        setAuthLoaded(true);
+      });
   }, []);
 
   const handleLogoChange = async (e: React.ChangeEvent<HTMLInputElement>) => {

src/portal/CustomerPortal.tsx

@@ -13,8 +13,10 @@ import { Communication } from "./sections/Communication.js";
 import { AccountSettings } from "./sections/AccountSettings.js";
 import { ImpersonationBanner } from "./ImpersonationBanner.js";
 import { AuditLogViewer } from "./AuditLogViewer.js";
+import { OOBE } from "./OOBE.js";
 import { useBranding } from "../BrandingContext.js";
 import { getDevUser } from "../pages/DevLoginSelector.js";
+import { signOut } from "../lib/auth-client.js";
 import type { ImpersonationSession } from "@groombook/types";
 import type { Appointment as PortalAppointment } from "./sections/Appointments.js";
 
@@ -52,6 +54,13 @@ export function CustomerPortal() {
   // (e.g. authenticated user with no matching client row). Rendered in place
   // of the portal chrome instead of bouncing back to /login.
   const [authError, setAuthError] = useState<string | null>(null);
+  // GRO-2359 — the SSO bridge 404 (no client row for the user's email)
+  // routes the user into the OOBE. We mount the OOBE inline rather than
+  // navigating to /onboarding so the post-auth flow stays inside the
+  // CustomerPortal render tree (test-isolated, no App-level router needed
+  // for the integration to work). The /onboarding route in App.tsx is
+  // still the mount point for direct deep-links to the same component.
+  const [showOOBE, setShowOOBE] = useState(false);
   const { branding } = useBranding();
   const [searchParams, setSearchParams] = useSearchParams();
 
@@ -62,6 +71,18 @@ export function CustomerPortal() {
     initDone.current = true;
 
     const sessionId = searchParams.get("sessionId");
+    // GRO-2359: a deep-link to a portal sub-route with ?noAccess=deleted-portal
+    // is the only path that still shows the no-access card. The post-auth
+    // 404-from-bridge path now navigates to /onboarding (OOBE) so the new
+    // user can create a portal. The deleted-portal case is set explicitly
+    // (e.g. a groomer who disabled a client) and uses the same no-access
+    // UI with the shared signOut() — that was the GRO-2358 invariant.
+    const noAccess = searchParams.get("noAccess");
+    if (noAccess === "deleted-portal") {
+      setAuthError(
+        "Your portal access has been removed. Please contact your groomer if you think this is a mistake.",
+      );
+    }
 
     if (sessionId) {
       setIsImpersonating(true);
@@ -152,11 +173,13 @@ export function CustomerPortal() {
           setPortalSessionId(data.sessionId);
           setClientName(data.clientName);
         } else if (bridgeResp.status === 404) {
-          // Authenticated but no matching client row — show a friendly message
-          // instead of bouncing back to /login (which would loop indefinitely).
-          setAuthError(
-            "Your account is not linked to a customer record. Please contact your groomer to set up portal access."
-          );
+          // Authenticated but no matching client row — mount the OOBE
+          // (GRO-2359) so the user can create their portal record instead
+          // of landing on the no-access card. The no-access card itself is
+          // still reachable for the deleted-portal case (see GRO-2358) via
+          // the ?noAccess=deleted-portal deep-link, but is no longer in
+          // the new-user path.
+          setShowOOBE(true);
         }
         // 401/other: fall through; App.tsx render guard will redirect to /login.
       } catch {
@@ -193,6 +216,19 @@ export function CustomerPortal() {
     }
   }, [session]);
 
+  // Shared sign-out handler — wires the canonical Better Auth `signOut()` so
+  // every authenticated surface (no-access screen, portal chrome, etc.) uses
+  // the same implementation as `AdminLayout`. Failure to reach the server
+  // still leaves the SPA free to navigate to /login.
+  const handleSignOut = useCallback(async () => {
+    try {
+      await signOut();
+    } catch {
+      // Best-effort; navigate to /login regardless so the user is never trapped.
+    }
+    window.location.href = "/login";
+  }, []);
+
   const logPageView = useCallback((page: string) => {
     if (!session) return;
     void fetch(`/api/impersonation/sessions/${session.id}/log`, {
@@ -266,6 +302,15 @@ export function CustomerPortal() {
   // session state. Dev users are verified via localStorage and the dev-session flow.
   // SSO customers are recognised by portalSessionId (set by the Better Auth bridge).
   if (!session && !portalSessionId) {
+    // GRO-2359 — new-user path: mount the OOBE inline so the SSO bridge's
+    // 404 hands the user a portal-creation form instead of the no-access
+    // card. onCompleted triggers a full page reload to /, which re-runs
+    // the bridge (now with a matching client row) and lands the user in
+    // the portal. A full reload (not React Router navigate) is the
+    // safest reset of the bridge's cached state.
+    if (showOOBE) {
+      return <OOBE onCompleted={() => { window.location.href = "/"; }} />;
+    }
     if (authError) {
       // GRO-1867: graceful 404 fallback — authenticated user has no client row.
       return (
@@ -281,14 +326,7 @@ export function CustomerPortal() {
             <h1 className="text-lg font-semibold text-stone-800 mb-2">Portal access not configured</h1>
             <p className="text-sm text-stone-600 mb-6">{authError}</p>
             <button
-              onClick={async () => {
-                try {
-                  await fetch("/api/auth/sign-out", { method: "POST", credentials: "include" });
-                } catch {
-                  // Best-effort sign-out; redirect to /login regardless.
-                }
-                window.location.href = "/login";
-              }}
+              onClick={() => { void handleSignOut(); }}
               className="inline-flex items-center justify-center gap-2 px-4 py-2 rounded-lg text-sm font-medium text-stone-700 bg-stone-100 hover:bg-stone-200 transition-colors"
             >
               <LogOut size={14} />
@@ -413,7 +451,14 @@ export function CustomerPortal() {
             })}
           </div>
 
-          {/* Session controls (only shown during active impersonation) */}
+          {/* Session controls — Sign out is always reachable from the portal
+              chrome (GRO-2373). End Impersonation is staff-only and only
+              appears during an active impersonation session. Both share the
+              same LogOut icon for visual consistency, but route to distinct
+              handlers: handleSignOut calls the canonical Better Auth
+              `signOut()` (mirroring OOBE and the no-access card); handleEnd
+              tears down the staff impersonation session and returns to the
+              admin clients list. */}
           <div className="border-t border-stone-100 p-4 space-y-2">
             {session?.status === "active" && (
               <button
@@ -424,6 +469,15 @@ export function CustomerPortal() {
                 End Impersonation
               </button>
             )}
+            <button
+              type="button"
+              onClick={() => { void handleSignOut(); }}
+              className="w-full flex items-center gap-2 px-3 py-2 rounded-lg text-xs font-medium text-stone-700 bg-stone-50 hover:bg-stone-100 transition-colors"
+              data-testid="portal-chrome-signout"
+            >
+              <LogOut size={14} />
+              Sign out
+            </button>
             <div className="flex items-center gap-2 px-3 py-2 text-xs text-stone-400">
               <Shield size={12} />
               Customer Portal v1.0

src/portal/OOBE.tsx

@@ -0,0 +1,312 @@
+import { useCallback, useEffect, useState } from "react";
+import { LogOut, Shield, Sparkles } from "lucide-react";
+import { signOut } from "../lib/auth-client.js";
+
+/**
+ * OOBE (Out-of-Box Experience) for a first-time Authentik SSO user whose
+ * email does not match any existing `clients` row.
+ *
+ * The post-auth handler in `CustomerPortal.tsx` redirects to this component
+ * when `POST /api/portal/session-from-auth` returns 404. From here the new
+ * user can either:
+ *   (a) Create a fresh customer record bound to their SSO email, or
+ *   (b) Sign out (the no-access screen is no longer in the new-user path).
+ *
+ * After successful creation, the OOBE navigates to `/` so the portal's
+ * existing SSO bridge re-runs and lands the user in their portal with a
+ * real `X-Impersonation-Session-Id` header. No new client state is
+ * required — the bridge re-resolves the session and the rest of the
+ * portal is unchanged.
+ *
+ * GRO-2359 — root-cause fix for "new SSO user lands on Portal access not
+ * configured" (companion to GRO-2358, which restored logout on that screen).
+ */
+
+type OOBEFormState = {
+  name: string;
+  phone: string;
+  address: string;
+  notes: string;
+};
+
+type OOBEStatus = "loading" | "ready" | "submitting" | "error";
+
+const EMPTY_FORM: OOBEFormState = {
+  name: "",
+  phone: "",
+  address: "",
+  notes: "",
+};
+
+type OOBEProps = {
+  /**
+   * Override the post-success destination. Defaults to `/` so the SSO bridge
+   * re-runs. Test suites pass a custom destination to keep assertions
+   * deterministic without a real portal session.
+   */
+  onCompleted?: () => void;
+};
+
+export function OOBE({ onCompleted }: OOBEProps = {}) {
+  const [status, setStatus] = useState<OOBEStatus>("loading");
+  const [form, setForm] = useState<OOBEFormState>(EMPTY_FORM);
+  const [error, setError] = useState<string | null>(null);
+  const [sessionEmail, setSessionEmail] = useState<string | null>(null);
+
+  // Resolve the Better Auth session on mount. The OOBE is gated to
+  // authenticated users — if no session exists the API will reject the
+  // creation request, so we redirect to /login early. We prefill `name`
+  // from the Better Auth `user.name` if the SSO provider returned one.
+  //
+  // We use a full `window.location.href` redirect (not `navigate`) so the
+  // OOBE works the same way whether it's mounted from the post-auth
+  // callback (inside CustomerPortal's render tree) or from a direct
+  // deep-link (mounted by App.tsx). A full reload also resets any
+  // cached state in the parent component.
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      try {
+        const r = await fetch("/api/auth/get-session", { credentials: "include" });
+        if (!r.ok) {
+          if (!cancelled) window.location.href = "/login";
+          return;
+        }
+        const data = (await r.json().catch(() => null)) as
+          | { user?: { email?: string; name?: string; role?: string | null } }
+          | null;
+        if (cancelled) return;
+        if (!data?.user) {
+          window.location.href = "/login";
+          return;
+        }
+        if (data.user.role === "staff") {
+          window.location.href = "/admin";
+          return;
+        }
+        setSessionEmail(data.user.email ?? null);
+        setForm((prev) => ({ ...prev, name: data.user?.name ?? prev.name }));
+        setStatus("ready");
+      } catch {
+        if (!cancelled) window.location.href = "/login";
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const handleChange = useCallback(
+    (field: keyof OOBEFormState) => (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => {
+      const value = e.target.value;
+      setForm((prev) => ({ ...prev, [field]: value }));
+    },
+    [],
+  );
+
+  const handleSubmit = useCallback(
+    async (e: React.FormEvent) => {
+      e.preventDefault();
+      if (status === "submitting") return;
+      if (!form.name.trim()) {
+        setError("Please tell us your name so we can set up your portal.");
+        return;
+      }
+      setStatus("submitting");
+      setError(null);
+      try {
+        const r = await fetch("/api/portal/clients-from-auth", {
+          method: "POST",
+          credentials: "include",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            name: form.name.trim(),
+            phone: form.phone.trim() || null,
+            address: form.address.trim() || null,
+            notes: form.notes.trim() || null,
+          }),
+        });
+        if (r.ok) {
+          // Let the parent (or default) decide where to land. The default
+          // is the portal root, which re-runs the SSO bridge. A full
+          // `window.location.href` reload resets any cached state in the
+          // parent (the bridge reads from Better Auth cookies, so a fresh
+          // request picks up the new client row).
+          if (onCompleted) {
+            onCompleted();
+          } else {
+            window.location.href = "/";
+          }
+          return;
+        }
+        if (r.status === 409) {
+          setStatus("ready");
+          setError(
+            "A customer record with this email already exists. Please contact your groomer to link your account.",
+          );
+          return;
+        }
+        const body = (await r.json().catch(() => null)) as { error?: string } | null;
+        setStatus("ready");
+        setError(body?.error ?? "We couldn't set up your portal. Please try again.");
+      } catch {
+        setStatus("ready");
+        setError("Network error. Please check your connection and try again.");
+      }
+    },
+    [form, onCompleted, status],
+  );
+
+  const handleSignOut = useCallback(async () => {
+    try {
+      await signOut();
+    } catch {
+      // Best-effort; navigate to /login regardless so the user is never trapped.
+    }
+    window.location.href = "/login";
+  }, []);
+
+  if (status === "loading") {
+    return (
+      <div
+        className="min-h-screen flex items-center justify-center bg-[#faf8f5]"
+        role="status"
+        aria-live="polite"
+      >
+        <div className="text-stone-500 text-sm">Loading…</div>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="min-h-screen flex items-center justify-center bg-[#faf8f5] font-sans px-6 py-10"
+      role="main"
+    >
+      <div className="max-w-md w-full bg-white rounded-xl shadow-sm border border-stone-200 p-8">
+        <div className="w-12 h-12 rounded-full bg-emerald-100 text-emerald-700 flex items-center justify-center mx-auto mb-4">
+          <Sparkles size={22} />
+        </div>
+        <h1 className="text-lg font-semibold text-stone-800 text-center mb-1">
+          Welcome — let's set up your portal
+        </h1>
+        <p className="text-sm text-stone-600 text-center mb-6">
+          You're signed in{sessionEmail ? ` as ${sessionEmail}` : ""}. We just need a few
+          details to create your customer record.
+        </p>
+
+        <form onSubmit={handleSubmit} className="space-y-4" noValidate>
+          <div>
+            <label
+              htmlFor="oobe-name"
+              className="block text-xs font-medium text-stone-700 mb-1"
+            >
+              Your name <span className="text-red-600">*</span>
+            </label>
+            <input
+              id="oobe-name"
+              name="name"
+              type="text"
+              required
+              autoComplete="name"
+              value={form.name}
+              onChange={handleChange("name")}
+              className="w-full px-3 py-2 rounded-lg border border-stone-300 text-sm text-stone-800 focus:outline-none focus:ring-2 focus:ring-emerald-500 focus:border-emerald-500"
+              disabled={status === "submitting"}
+            />
+          </div>
+          <div>
+            <label
+              htmlFor="oobe-phone"
+              className="block text-xs font-medium text-stone-700 mb-1"
+            >
+              Phone <span className="text-stone-400">(optional)</span>
+            </label>
+            <input
+              id="oobe-phone"
+              name="phone"
+              type="tel"
+              autoComplete="tel"
+              value={form.phone}
+              onChange={handleChange("phone")}
+              className="w-full px-3 py-2 rounded-lg border border-stone-300 text-sm text-stone-800 focus:outline-none focus:ring-2 focus:ring-emerald-500 focus:border-emerald-500"
+              disabled={status === "submitting"}
+            />
+          </div>
+          <div>
+            <label
+              htmlFor="oobe-address"
+              className="block text-xs font-medium text-stone-700 mb-1"
+            >
+              Address <span className="text-stone-400">(optional)</span>
+            </label>
+            <input
+              id="oobe-address"
+              name="address"
+              type="text"
+              autoComplete="street-address"
+              value={form.address}
+              onChange={handleChange("address")}
+              className="w-full px-3 py-2 rounded-lg border border-stone-300 text-sm text-stone-800 focus:outline-none focus:ring-2 focus:ring-emerald-500 focus:border-emerald-500"
+              disabled={status === "submitting"}
+            />
+          </div>
+          <div>
+            <label
+              htmlFor="oobe-notes"
+              className="block text-xs font-medium text-stone-700 mb-1"
+            >
+              Notes <span className="text-stone-400">(optional)</span>
+            </label>
+            <textarea
+              id="oobe-notes"
+              name="notes"
+              rows={2}
+              value={form.notes}
+              onChange={handleChange("notes")}
+              className="w-full px-3 py-2 rounded-lg border border-stone-300 text-sm text-stone-800 focus:outline-none focus:ring-2 focus:ring-emerald-500 focus:border-emerald-500"
+              disabled={status === "submitting"}
+            />
+          </div>
+
+          {error && (
+            <div
+              role="alert"
+              aria-live="polite"
+              className="flex items-start gap-2 text-sm text-red-700 bg-red-50 border border-red-200 rounded-lg px-3 py-2"
+            >
+              <Shield size={14} className="mt-0.5 shrink-0" />
+              <span>{error}</span>
+            </div>
+          )}
+
+          <button
+            type="submit"
+            disabled={status === "submitting"}
+            className="w-full inline-flex items-center justify-center gap-2 px-4 py-2.5 rounded-lg text-sm font-medium text-white bg-emerald-600 hover:bg-emerald-700 disabled:opacity-60 disabled:cursor-not-allowed transition-colors"
+          >
+            {status === "submitting" ? "Setting up…" : "Create my portal"}
+          </button>
+        </form>
+
+        <div className="mt-6 pt-4 border-t border-stone-100 flex items-center justify-between">
+          <p className="text-xs text-stone-500">
+            Wrong account? Sign out and try a different one.
+          </p>
+          <button
+            type="button"
+            onClick={() => {
+              void handleSignOut();
+            }}
+            className="inline-flex items-center gap-1.5 text-xs font-medium text-stone-600 hover:text-stone-900"
+          >
+            <LogOut size={12} />
+            Sign out
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default OOBE;

src/portal/sections/BillingPayments.tsx

@@ -130,7 +130,7 @@ function BillingPaymentsInner({ sessionId, readOnly }: BillingPaymentsProps) {
         </div>
       )}
 
-      <div className="flex gap-2 flex-wrap">
+      <div className="flex gap-2 overflow-x-auto scrollbar-hide">
         {([
           { id: "invoices" as const, label: "Invoices", icon: DollarSign },
           { id: "payment" as const, label: "Payment Methods", icon: CreditCard },

src/portal/sections/PetProfiles.tsx

@@ -145,7 +145,7 @@ export function PetProfiles({ sessionId, readOnly }: Props) {
   return (
     <div className="space-y-6">
       {/* Pet Selector */}
-      <div className="flex gap-3 overflow-x-auto pb-1">
+      <div className="flex gap-3 overflow-x-auto pb-1 scrollbar-hide">
         {pets.map(p => (
           <button
             key={p.id}
@@ -191,7 +191,7 @@ export function PetProfiles({ sessionId, readOnly }: Props) {
       )}
 
       {/* Tabs */}
-      <div className="flex gap-1 bg-white rounded-xl border border-stone-200 p-1 overflow-x-auto">
+      <div className="flex gap-1 bg-white rounded-xl border border-stone-200 p-1 overflow-x-auto scrollbar-hide">
         {([
           { id: "info", label: "Basic Info", icon: PawPrint },
           { id: "medical", label: "Medical", icon: Heart },