@wix/agent-skills 1.15.1 → 1.16.0

package/skills/wix-vibe-headless/references/members/INSTRUCTIONS.md

@@ -1,211 +1,299 @@
+# Wix Members — ready-made custom-login client
 
-# Wix Members — custom login (client-only REST)
+The members client is **shipped as real files**, not snippets to regenerate. It's a complete
+**custom login** — email+password sign-up/sign-in, "Continue with Google/Facebook" (and custom SSO),
+a member session, an account area, and route gating — styled with your app's design tokens (base44's
+`src/index.css` — the shadcn palette the design phase already set). Copy it into the app and wire the
+routes — you generate almost none of the auth code (the OAuth state machine, PKCE, the hidden-iframe
+token exchange, and the social `/callback` all ship and are correct).
 
-> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and this
-> vertical's `references/members/wix-members-auth.js`. Copy **both** into your app's `src/rest/` side by
-> side — the helper does `import { … } from "./wix-client.js"`, so they must land in the same folder.
+**Custom login only.** The member types credentials in **your own form on your own page** (or clicks
+your own social button) — they are **never redirected to a Wix-hosted login page**. Talks to Wix
+directly over the public `WIX_CLIENT_ID`; login swaps the token set on the one shared client, so
+**every later `wixApiRequest` runs as the member** (their cart, orders, plans, "my …" reads). Never
+mock a logged-in member; never mint a second client after login.
 
-Adds real **member accounts** to a client-only headless front end: sign up, log in, log out, and
-member-gated surfaces — all from the browser over the public `WIX_CLIENT_ID`, no SDK, no backend.
+## Prerequisites
+- The site's **Wix OAuth app** (headless) is the auth target — members **self-register**, so there is
+  **nothing to seed** (see **Seeding** below); the client renders the shipped logged-out state until a
+  member signs in.
+- The **Members Area app** installed *only if* you need member **profile** data (name, photo, roles,
+  custom fields). Pure "logged-in vs. not" gating needs no app — see **Identity vs. profile** below.
+- The public headless **`WIX_CLIENT_ID`** from your prompt (buyer-facing, safe to hardcode/commit).
+- **OAuth-app allow-listing — the #1 gotcha, a manual owner-only step you can't do from client code.**
+  Two *different* fields gate the two mechanisms:
 
-**This is *custom* login: the front owns its login UI.** The member types credentials in **your own
-form on your own page** (or clicks your own social button) — they are **never redirected to a
-Wix-hosted login page**. This is the REST equivalent of the SDK `OAuthStrategy` recipe; the older
-"redirect the user to a Wix login page" flow is deliberately **not** used here.
+  | Mechanism | What must be allow-listed | OAuth-app field | On `localhost:4321`? |
+  | :-- | :-- | :-- | :-- |
+  | **credential** (your form) | your app **origin** (the hidden iframe `postMessage`s the code back) | `allowedRedirectDomains` | ✅ allowed by default |
+  | **social / SSO** | the **exact `/callback` URL** (full-page redirect target) | `allowedRedirectUris` | ❌ **must be added** |
 
-## When to use
-- User wants members to **sign up / log in** on a page they built (email+password, "Continue with
-  Google/Facebook", or custom SSO), with the login UI living in their own app.
-- User wants **member-gated** content, an **account / profile** page, or a "my orders / my bookings /
-  my plans" view (those reads need a logged-in member).
-- **Pricing-plans is present.** Buying/reading a member's plans is members-only — pair this vertical
-  with `pricing-plans` so the member can log in *before* the subscribe / "my subscription" surface.
+  `localhost:4321` is Wix's default-allowed dev **origin**, so **credential login works there with zero
+  setup**; social **still fails** until you add `http://localhost:4321/callback` to `allowedRedirectUris`.
+  Any non-default origin (deployed domain, other port) needs both the origin and `<origin>/callback`.
+  **Symptoms:** unregistered origin → credential login hangs then throws `MemberAuthError('timeout')`
+  (+ a console *"postMessage… target origin does not match"*); unregistered callback → the Wix
+  authorize page shows *"Invalid redirect URI"* before returning, so the client can't catch it.
 
-## Two mechanisms — pick by the brief (a page may use both)
+  > **⚠️ AGENT: surface this proactively.** As soon as a run uses social/SSO (or deploys credential
+  > login to a non-`4321` origin), **tell the user the exact URIs to add and where** (deep link under
+  > **Point the user to their dashboard**), and note that **social login stays dead until they do it**.
 
-| | **(A) Direct-credential** | **(B) Social / SSO** |
-| :-- | :-- | :-- |
-| **Use when** | your own email+password form, or custom sign-up fields | "Sign in with Google / Facebook", or enterprise SSO |
-| **User leaves your page?** | **No** — silent iframe token exchange | **Yes** — full-page redirect to the provider, back to your `/callback` |
-| **Kick-off** | `register()` / `login()` | `startSocialLogin(idp, callbackUri)` |
-| **Finish** | automatic on `SUCCESS` | `completeSocialLogin()` on the `/callback` page |
-| **Custom sign-up fields?** | Yes (`register`'s `profile`) | No — the provider owns the identity |
-| **Needs an allow-listed origin/URI?** | **Yes** — your app **origin** (postMessage target) | **Yes** — your `/callback` **URL** |
+## STEP 1 — The client is already in `src/`
+The install step (base44.md STEP 1) deployed the whole members UI client + REST scaffolds into
+`src/` (imports use the `@/` alias → `src/`). Here's every file and what it is — **this is your map,
+so you don't need to open them:**
 
-Both converge on the **same end state**: member tokens written onto the shared client, so **every
-later `wixApiRequest` runs as the member** (login just swaps the token set on the client you already
-have). Don't blend their exchange calls — the helper handles each internally.
+| file | what it is |
+|---|---|
+| `context/MemberContext.jsx` | `useMember()` provider: current member, `loggedIn`, `refresh()`, `logout()` |
+| `hooks/useLoginForm.js` | credential state machine (login/register/verify, error mapping) — logic only |
+| `components/LoginForm.jsx` | email+password form UI (sign-in/sign-up tabs, verify-code + pending phases) |
+| `components/SocialButtons.jsx` | "Continue with Google/Facebook" buttons (kick off the redirect) |
+| `components/MemberMenu.jsx` | header account control — "Log in" vs. member name + log-out (like a cart button) |
+| `components/RequireAuth.jsx` | route gate: renders children for a member, else redirects to `/login` |
+| `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 4) |
+| `pages/Login.jsx`, `pages/Account.jsx` | the shipped login + account routes (`/login`, `/account`) |
+| `pages/Callback.jsx` | social/SSO return route — mount at **exactly** `/callback` |
+| `rest/wix-config.js` | **you set the ids here** (STEP 2) |
+| `rest/wix-client.js` + `rest/wix-members-auth.js` | REST transport + the auth helper (copy verbatim) |
 
-## Prerequisites
-1. A Wix site with the **Members Area app installed** if you need member *profile* data (name, photo,
-   roles) or custom field definitions. Pure "logged-in vs. not" gating needs no app — see the
-   identity-vs-profile split below.
-2. The site's public headless **`WIX_CLIENT_ID`** (from the handoff prompt), pasted into
-   `src/rest/wix-client.js`. Public, buyer-facing credential — safe to hardcode/commit.
-3. **OAuth-app allow-listing — the #1 gotcha. Two *different* fields gate the two mechanisms:**
-
-   | Mechanism | What must be allow-listed | OAuth-app field | On `localhost:4321`? |
-   | :-- | :-- | :-- | :-- |
-   | **(A) direct-credential** | your app **origin** (the hidden iframe `postMessage`s the code back to it) | `allowedRedirectDomains` | ✅ allowed by default |
-   | **(B) social / SSO** | the **exact `/callback` URL** (full-page redirect target) | `allowedRedirectUris` | ❌ **must be added** |
-
-   - `localhost:4321` is Wix's default-allowed dev **origin**, so **credential login works there with zero
-     setup**. But social **still fails on `localhost:4321`** until you add `http://localhost:4321/callback`
-     to `allowedRedirectUris` — the default covers the origin, not the callback URI. (These are genuinely
-     two separate fields; matching Oz's SDK `wix-headless` `managed/DEPLOYMENT.md`.)
-   - **Any non-default origin** — your deployed domain, a different localhost port —
-     must be registered too: the origin (for A) and the `<origin>/callback` (for B).
-   - **Symptoms:** (A) unregistered origin → login hangs, then `MemberAuthError('timeout')` + a console
-     *"Failed to execute 'postMessage'… target origin … does not match"*. (B) unregistered callback →
-     the Wix authorize page shows *"Invalid redirect URI. Please add an allowed URI to your OAuth App"*
-     **before** returning — so the client can't catch it; you must register it up front.
-   - Google & Facebook are enabled by default; **custom SSO** also needs an IDP connection created in
-     the Business Manager, whose **connection id** you pass as `idp` (see "Custom SSO" below).
-
-   > **⚠️ AGENT: this is a manual, owner-only step you cannot do from client-only code — surface it
-   > proactively.** As soon as a run uses social/SSO (or deploys credential login to a non-`4321`
-   > origin), **tell the user** the exact URIs to add and where, and note that **social login stays
-   > dead until they do it** (a client-only front has no account token to register it via the API).
-   > See "Point the user to their dashboard" below for the deep link and the exact values.
-
-## The API (copy as-is; do not re-derive it)
-Copy `wix-client.js` + `wix-members-auth.js` into `src/rest/` and set `WIX_CLIENT_ID`. Exports of
-`wix-members-auth.js`:
-- **Direct-credential:** `register(email, password, profile?)`, `login(email, password)`,
-  `verifyEmail(code, stateToken)`, `sendPasswordResetEmail(email, redirectUri)`
-- **Social / SSO:** `startSocialLogin(idp, callbackUri, returnTo?)`, `completeSocialLogin()`, `IDP`
-- **Session:** `isLoggedIn()`, `getCurrentMember()`, `logout(returnTo?)`
-- **Errors:** `MemberAuthError` (`.code` + `.message`)
-
-The full state-machine, `profile`, and error semantics are documented as JSDoc at the top of
-`wix-members-auth.js`. **Read it before wiring the UI.**
-
-> **⚠️ Copy `wix-members-auth.js` verbatim — do NOT rewrite its internals.** Wire the UI to the
-> exported functions, but leave the helper's bodies alone. The OAuth request shapes are **exact and
-> unforgiving** — the `createRedirectSession` body in particular needs the `auth.authRequest` wrapper,
-> flat PKCE fields, and `responseType`/`scope`; "simplifying" it into a spread of the input object
-> returns **400 Bad Request** and login dies. Extend by *calling* the exports, not by editing them.
-
-## How to wire it (UI is the project's choice — the skill ships the REST layer only)
-
-### (A) Credential form + the state machine — handle every branch (not just SUCCESS)
-`register()` / `login()` / `verifyEmail()` resolve to `{ state, member?, stateToken? }`:
-- **`"SUCCESS"`** → logged in; `member` is populated (or `null` if the Members Area app isn't
-  installed). Render the account UI / navigate.
-- **`"REQUIRE_EMAIL_VERIFICATION"`** → a 6-digit code was emailed. Collect it and call
-  `verifyEmail(code, stateToken)`. (Fires when a new registrant's email already exists as a contact,
-  or when email verification is enabled in Member Settings.)
-- **`"REQUIRE_OWNER_APPROVAL"`** → show a "pending approval" notice; not an error.
-
-Hard failures **throw** a `MemberAuthError` — catch it and show `err.message` (`.code` is stable:
-`invalidCredentials`, `emailAlreadyExists`, …). `emailAlreadyExists` on register → route to log in.
+They're already in place — go **straight to theming + wiring**, nothing to verify first. **Don't
+`read_file` the shipped page/component/hook source to inspect it** — the table says what each is and
+every shape you need is in the snippets below. Read a shipped file's source **only** on a real
+fallback — a runtime error, or a field the snippets don't cover (see "Fallback only" at the end).
+(Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
+`references/members/app/` → `src/`.)
+
+> **⚠️ Copy `wix-members-auth.js` verbatim — do NOT rewrite its internals.** The OAuth wire shapes are
+> exact and unforgiving: the `createRedirectSession` body needs the `auth.authRequest` wrapper, flat
+> PKCE fields, and `responseType`/`scope` — "simplifying" it returns **400** and login dies. Extend by
+> *calling* the exports, never by editing them. Its full JSDoc (state machine, `profile`, errors) is at
+> the top of the file — read that, not the whole body, if you need the contract.
+
+## STEP 2 — Credentials
+Write `src/rest/wix-config.js` with your `WIX_CLIENT_ID` and `WIX_METASITE_ID` from the prompt — the
+one place both ids live.
+
+## STEP 3 — Theme (nothing to style on the shipped components)
+The shipped components carry **no palette of their own** — they render from base44's design tokens
+in `src/index.css` (`:root`/`.dark`: `--background`, `--foreground`, `--card`, `--primary`, `--muted`,
+`--border`, `--radius`, `--font-*`) via shadcn Tailwind classes (`bg-card`, `text-foreground`,
+`bg-primary`, `text-muted-foreground`, `border-border`, `rounded-lg`, `font-display`). Those tokens
+are **already set to the brand by the design phase**, so the shipped auth surfaces are themed with
+zero work here. To adjust the palette, edit `index.css` (`:root` **and** `.dark`) — the base44 way;
+**never add a parallel theme file (e.g. a `theme.css`) or restyle the shipped JSX.** Build the
+Home/Header you add (STEP 4) from the **same** base44 tokens/classes so it matches automatically. A
+dark brand is just base44's dark palette in `index.css` — no per-component work.
+
+## STEP 4 — Wire routes + provider (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+**No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
+`App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`, the **Base44 builder
+account**) — edit it in, don't replace it. The Wix member session is separate and ships under its own
+name, **`MemberProvider`/`useMember`**, so the two never collide (do NOT rename it to `useAuth`).
+- Wrap the routed tree in `<MemberProvider>` (from `@/context/MemberContext`).
+- Put your **header + footer in a `Layout`** that renders `<Outlet/>` between them, and nest every
+  route under one pathless `<Route element={<Layout/>}>`. Your brand chrome then wraps **every** page
+  — including the shipped `Login`/`Account`/`Callback` — so you **never edit the shipped pages to add
+  a header/footer** (they render inside `<Outlet/>` as-is).
+- **Pin the top chrome as one fixed block.** Put `<WixManageBanner/>` (shipped, preview-only) **above**
+  your `<Header/>` inside a single `position:fixed` top region — the header itself is plain in-flow
+  markup, the region owns the fixing — so banner + header ride together (no scroll drift/gap). Pad
+  the content by the region's measured height so it clears the chrome and self-corrects when the
+  banner is dismissed.
+- Routes under the Layout: `/login` → `Login`, `/callback` → `Callback` (both shipped, as-is), and
+  `/account` → `Account` **wrapped in `<RequireAuth>`** so a visitor is bounced to `/login`. **You add
+  `/` → your own Home** page. Gate your own member-only routes ("my orders", "my plans") the same way.
+
+```jsx
+import { useRef, useState, useEffect } from "react";
+import { Routes, Route, Outlet } from "react-router-dom";
+import { MemberProvider } from "@/context/MemberContext";
+import WixManageBanner from "@/components/WixManageBanner";   // shipped, preview-only · default export, no props
+import RequireAuth from "@/components/RequireAuth";           // shipped route gate
+import Login from "@/pages/Login";                     // shipped · default export, no props
+import Account from "@/pages/Account";                 // shipped · default export, no props
+import Callback from "@/pages/Callback";               // shipped · default export, no props
+import Home from "@/pages/Home";       // YOU build
+import Header from "@/components/Header";   // YOU build — plain in-flow markup, NOT position:fixed
+import Footer from "@/components/Footer";   // YOU build
+
+function Layout() {
+  const topRef = useRef(null);
+  const [offset, setOffset] = useState(0);
+  useEffect(() => {                                  // measure the fixed region → pad content below it
+    const ro = new ResizeObserver(() => setOffset(topRef.current?.offsetHeight ?? 0));
+    if (topRef.current) ro.observe(topRef.current);
+    return () => ro.disconnect();
+  }, []);
+  return (<>
+    <div ref={topRef} style={{ position: "fixed", top: 0, left: 0, right: 0, zIndex: 50 }}>
+      <WixManageBanner />                    {/* null on the published site / when dismissed */}
+      <Header />                             {/* your brand header, in-flow inside this fixed block */}
+    </div>
+    <div style={{ paddingTop: offset }}>     {/* clears the chrome; shrinks when the banner is dismissed */}
+      <Outlet />                             {/* shipped Login/Account/Callback render here, untouched */}
+      <Footer />
+    </div>
+  </>);
+}
+
+<MemberProvider>
+  <Routes>
+    <Route element={<Layout />}>                                          {/* chrome wraps all */}
+      <Route path="/" element={<Home />} />                               {/* yours */}
+      <Route path="/login" element={<Login />} />                         {/* shipped, as-is */}
+      <Route path="/callback" element={<Callback />} />                   {/* shipped — must be /callback */}
+      <Route path="/account" element={<RequireAuth><Account /></RequireAuth>} />  {/* gated, shipped */}
+    </Route>
+  </Routes>
+</MemberProvider>
+```
+
+## What you build (not shipped)
+The **home / landing page**, the **`Header`** (mount `<MemberMenu/>` in it) and a **`Footer`** — the
+two you drop into the `Layout` (STEP 4) so they wrap every route — plus the overall brand story,
+styled from the same base44 tokens/classes. The nav's account control is a `<MemberMenu/>` (shows
+"Log in" for a visitor, the member's name + log-out once signed in — render it as-is, don't wrap it in
+your own auth text button):
+
+```jsx
+import { useState, useEffect } from "react";
+import { Link } from "react-router-dom";
+import MemberMenu from "@/components/MemberMenu";
+
+// Responsive header: choose ONE branch with a state flag, so <MemberMenu/> mounts once.
+// Do NOT render a desktop nav AND a mobile nav toggled by `hidden md:flex` / `md:hidden`:
+// these navs are inline-styled, and an inline `display` beats a Tailwind class, so `hidden`
+// never applies — BOTH branches render and you get two menus. One branch = one menu.
+export function Header() {
+  const [mobile, setMobile] = useState(() => window.innerWidth < 768);
+  useEffect(() => {
+    const onResize = () => setMobile(window.innerWidth < 768);
+    window.addEventListener("resize", onResize);            // keep it reactive to viewport changes
+    return () => window.removeEventListener("resize", onResize);
+  }, []);
+  return (
+    <nav style={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}>
+      {/* brand/logo */}
+      {mobile
+        ? <YourMenu />                                       // your hamburger + <MemberMenu/> here
+        : <div style={{ display: "flex", gap: 24 }}><Link to="/">Home</Link><MemberMenu /></div>}
+    </nav>
+  );
+}
+```
+Everything visual reads base44's design tokens (`index.css`), so your home/nav match the shipped pages automatically.
+
+**Editing a component and the change doesn't show? It's the preview, not your code.** The dev preview
+can serve a stale module after a write. Before diagnosing a visual bug you just "fixed", do a fresh
+full navigate/reload of the preview and re-check — don't keep rewriting correct code against a stale
+render.
+
+## Using the client from your own UI (session, gating, "my …" reads)
+
+```jsx
+import { useMember } from "@/context/MemberContext";
+
+// useMember() gives:
+// { member, loggedIn, loading, refresh(), logout(returnTo?) }
+// - member is null for a visitor OR when the Members Area app isn't installed (loggedIn still true).
+// - login/register happen in the shipped LoginForm; call refresh() after your own login call.
+
+function Greeting() {
+  const { loggedIn, member, loading } = useMember();
+  if (loading) return null;
+  return loggedIn ? <span>Hi, {member?.profile?.nickname || "member"}</span> : <a href="/login">Log in</a>;
+}
+
+// A member-only read runs as the member on the SAME shared client — no extra auth, no `elevate`:
+import { wixApiRequest } from "@/rest/wix-client";
+const { orders } = await wixApiRequest("/ecom/v1/orders/query", { body: { query: {} } }); // member's own
+```
+
+**"My items" in a CMS collection** (member-owned rows) → the **OWNED RECORDS** recipe in
+`references/cms/INSTRUCTIONS.md`. Two facts from this vertical carry over: the member id lives at
+**`member.id`**, and `member` is `null` for a logged-in member whenever the Members Area app is absent
+(see *Identity vs. profile* below). Because of that second one, prefer a collection seeded
+`read: SITE_MEMBER_AUTHOR` — the server scopes reads by the caller's own token, so it works in both states.
+
+## Extending the client — the auth helper's exports (copy as-is, do NOT re-derive)
+Building auth UI beyond the shipped pages? Call these exports (from `@/rest/wix-members-auth`) — the
+same ones the shipped hook/pages use:
 
 ```js
-import { login, register, verifyEmail, isLoggedIn, getCurrentMember, logout, MemberAuthError } from "./rest/wix-members-auth.js";
+// (A) Credential — handle EVERY branch, not just SUCCESS. register/login/verifyEmail → { state, ... }:
+import { login, register, verifyEmail, MemberAuthError } from "@/rest/wix-members-auth";
 try {
   const res = await login(email, password);
-  if (res.state === "SUCCESS") showAccount(res.member);
-  else if (res.state === "REQUIRE_EMAIL_VERIFICATION") promptForCode(res.stateToken);
-  else if (res.state === "REQUIRE_OWNER_APPROVAL") showPending();
+  if (res.state === "SUCCESS") { /* logged in; res.member (or null w/o Members Area app) */ }
+  else if (res.state === "REQUIRE_EMAIL_VERIFICATION") { /* 6-digit code emailed; verifyEmail(code, res.stateToken) */ }
+  else if (res.state === "REQUIRE_OWNER_APPROVAL") { /* show a pending notice — not an error */ }
 } catch (e) {
-  if (e instanceof MemberAuthError) showError(e.message); else throw e;
+  if (e instanceof MemberAuthError) show(e.message); else throw e;   // .code: invalidCredentials, emailAlreadyExists, …
 }
-```
-
-Custom sign-up fields go in `register`'s `profile` (`{ firstName, lastName, nickname, addresses, … }`).
-Standard fields work as-is; arbitrary `customFields` keys must first be defined in the Members Area
-app or they're silently dropped.
+// Custom sign-up fields → register's 3rd arg `profile` ({ firstName, lastName, nickname, addresses, … }).
+// Arbitrary customFields keys must be defined in the Members Area app first, or they're silently dropped.
 
-### (B) Social / SSO — your button + a `/callback` route
-```js
-// on your login page:
-import { startSocialLogin, IDP } from "./rest/wix-members-auth.js";
-const callbackUri = new URL("/callback", window.location.origin).href; // must be allow-listed
-onGoogleClick   = () => startSocialLogin(IDP.GOOGLE,   callbackUri, window.location.pathname);
-onFacebookClick = () => startSocialLogin(IDP.FACEBOOK, callbackUri, window.location.pathname);
-
-// on the /callback page (a route/page at exactly that path):
-import { completeSocialLogin } from "./rest/wix-members-auth.js";
-const { member, returnTo } = await completeSocialLogin();
-window.location.replace(returnTo || "/");
+// (B) Social / SSO — button + the shipped /callback page:
+import { startSocialLogin, IDP } from "@/rest/wix-members-auth";
+const callbackUri = new URL("/callback", window.location.origin).href;   // must be allow-listed
+startSocialLogin(IDP.GOOGLE, callbackUri, window.location.pathname);      // custom SSO: pass a connectionId as idp
 ```
-**Custom SSO:** identical call — pass your connection id as `idp` instead of `IDP.GOOGLE`:
-`startSocialLogin("<connectionId>", callbackUri)`. The connection id comes from an IDP connection you
-create in the Business Manager (dashboard link below).
-
-### Session, account area, logout
-- **Gate UI** on `isLoggedIn()`. Read the member with `await getCurrentMember()` (name / photo / roles
-  / custom fields) — returns `null` for a visitor or when the Members Area app isn't installed.
-- **Logout:** `await logout()` — clears local tokens and redirects through the Wix logout URL; the
-  client is a clean anonymous visitor afterward.
-- **Persistence is automatic.** Member tokens live in the same `localStorage` the visitor token used,
-  so a reload stays logged in and tokens auto-refresh via `wix-client.js` — do **not** add your own.
+
+Every export in `wix-members-auth.js` links its own reference page inline. The two areas they sit in
+map onto the identity / profile split below — auth is the headless OAuth app, the profile is the
+Members Area app:
+- Headless authentication (login, register, verify, tokens): https://dev.wix.com/docs/api-reference/business-management/headless/authentication.md
+- Headless redirects (social/SSO + logout): https://dev.wix.com/docs/api-reference/business-management/headless/redirects.md
+- Members (the member profile, needs the Members Area app): https://dev.wix.com/docs/api-reference/crm/members-contacts/members.md
 
 ## Identity vs. profile — don't conflate them
 - **Identity / auth** — sign up, log in, log out, "is this caller a member?". Native to the headless
   OAuth app. **No app install needed** — every login mechanism here runs on this layer alone.
-- **Member profile / Members Area** — name / photo / roles, an account page, and custom-field
-  definitions. Served by the **Members Area app**, which must be installed. If `getCurrentMember()`
-  returns `null` while `isLoggedIn()` is `true`, suspect the app isn't installed — not a code bug.
-
-## Hard rules (do not violate)
-- ✅ **Custom login only.** The member logs in on **your** UI; never redirect them to a Wix-hosted
-  login page, and never use a Wix login-page redirect for member auth.
-- ✅ **One shared client.** Member login swaps the token set on `wix-client.js` — reuse the same
-  transport for everything so the member identity (and their cart) carries across the app. Never mint
-  a second client or re-mint anonymously after login (it drops the member).
-- ✅ **For a Wix-backed feature, use the Wix member as the identity — keep it consistent.** When the
-  feature is about **Wix members** (the user gave you a `WIX_CLIENT_ID`), log in and gate on the
-  **Wix member** (`getCurrentMember()` / the Wix member token), and key member-owned Wix rows on
-  `_owner` (see the `cms` vertical). Don't identify one feature's user from two different sessions —
-  the ids won't match.
-- ❌ **Don't blend the two exchanges.** Credential login finishes via the hidden iframe; social
-  finishes via `/callback`. The helper keeps them separate — don't cross-wire.
-- ❌ **Never fake a member.** No mock "logged-in" state, no invented profile, roles, or member counts.
-  Render the real member or the logged-out state.
-- ✅ **Fail loudly.** The helper throws `MemberAuthError` on bad credentials, state mismatch, timeout,
-  and token-exchange failure — surface them; don't swallow.
-- ⛔ **No `elevate` / admin scope.** A member reading their **own** data (profile, own orders /
-  bookings / plans) is authorized by the member token alone. There is no admin elevation on a
-  client-only front, and own-data reads don't need it.
-- ⛔ **MFA / TOTP is not available headless.** The security layers are password + email verification +
-  reCAPTCHA, all **dashboard-governed** — document them as host-configurable, don't set them from code.
-
-## Beyond the snippets
-The helper covers sign-up / login / social / SSO / logout / current-member. For a genuine gap, extend
-with `wixApiRequest` — but confirm the endpoint, method, and body in the API reference first (or via
-the co-installed **`wix-docs`** skill). Never guess.
-- Custom login (JS SDK, concepts mirror the REST calls): https://dev.wix.com/docs/go-headless/self-managed-headless/authentication/members/custom-login-page/custom-login/custom-login-using-the-js-sdk.md
-- External / social login (REST): https://dev.wix.com/docs/rest/business-management/headless-authentication/redirects/create-redirect-session
-- Retrieve Tokens (REST): https://dev.wix.com/docs/rest/business-management/headless-authentication/authentication/retrieve-tokens
-- Members API (read/update profile, query members): https://dev.wix.com/docs/api-reference/members/members/members-v1/introduction
+- **Member profile / Members Area** — name / photo / roles, an account page, custom-field definitions.
+  Served by the **Members Area app**, which must be installed. If `getCurrentMember()`/`useMember().member`
+  is `null` while `loggedIn` is `true`, suspect the app isn't installed — **not a code bug**.
+
+Fallback only — when you hit an error or need something not shown here (password reset, custom SSO
+connection ids, a profile field these snippets don't have): read the relevant shipped file under
+`src/rest/`, or look it up via the **`wix-docs`** skill.
+
+## Hard rules
+- Set `WIX_CLIENT_ID` (STEP 2) — not the placeholder.
+- Style via base44 design tokens (`index.css` / shadcn Tailwind classes), never by rewriting the shipped components or adding a parallel theme file.
+- **Custom login only** — the member logs in on **your** UI; never redirect them to a Wix-hosted login page.
+- **One shared client** — login swaps the token set on `wix-client.js`; reuse it for everything so the
+  member identity carries across the app. Never mint a second client or re-mint anonymously after login.
+- Copy `wix-members-auth.js` verbatim; extend by *calling* its exports, never by editing them.
+- Header/footer live in a `Layout` around `<Outlet/>` (STEP 4) — never edit the shipped `Login`/`Account`/`Callback` to add chrome; the fixed top region owns positioning (`<WixManageBanner/>` above a plain in-flow `<Header/>`).
+- **Never fake a member** — no mock logged-in state, invented profile, or roles. Render the real member or the real logged-out state.
+- **Fail loudly** — the helper throws `MemberAuthError`; surface `.message`, don't swallow it.
+- No `elevate` / admin scope, and no headless MFA/TOTP — those security layers are dashboard-governed.
 
 ## Point the user to their dashboard
-Some setup only happens in the Wix dashboard — always give the user the deep links:
-- **Members Area app** (for profile data + custom fields) — `https://manage.wix.com/dashboard/{metaSiteId}/member-permissions`
-- **Signup security** (email verification, owner approval, reCAPTCHA) — `Dashboard → Settings → Login & Security` / member signup settings
-- **Allowed authorization redirect URIs** — the OAuth-app / **Headless Settings** for the project:
-  `https://manage.wix.com/dashboard/{metaSiteId}/oauth-apps-settings`. Add:
-  - the **app origin** (e.g. `https://myapp.example.com`) — needed for direct-credential login from a
-    non-default origin (`localhost:4321` is pre-allowed);
-  - the **exact `/callback` URL** (e.g. `https://myapp.example.com/callback`) — required for social/SSO;
-  - also add password-reset / logout return URLs if you use them.
-  Tell the user these exact values; the callback URL must match your `startSocialLogin` `callbackUri`
-  character-for-character.
-- **Custom SSO connection** (to obtain a `connectionId`) — created under the project's IAM / SSO
-  settings in the Business Manager.
-
-Substitute the site's `metaSiteId` (from the handoff / `ListWixSites`).
-
-## Verification checklist (before declaring done)
-- [ ] `WIX_CLIENT_ID` set to the prompt's value (not the `<YOUR-CLIENT-ID>` placeholder)
-- [ ] Sign-up: `register()` returns `SUCCESS` (or `REQUIRE_EMAIL_VERIFICATION` handled via `verifyEmail`)
-- [ ] Log-in: `login()` reaches `SUCCESS`; wrong password shows `invalidCredentials`, not a crash
-- [ ] After login `isLoggedIn()` is `true` and `getCurrentMember()` returns the member (or `null` with
-      the Members Area app not installed — documented, not a bug)
-- [ ] A member-scoped read (e.g. pricing-plans "my plans") now returns the member's data via the same client
-- [ ] Social: the button redirects to the provider and `/callback` logs the member in (callback URL
-      allow-listed); custom SSO works with its `connectionId` (or is flagged as pending host setup)
-- [ ] Logout clears the session and the next load is a clean anonymous visitor
-- [ ] No mocked member state, profile, or roles anywhere
-- [ ] Told the user about any required dashboard setup (Members Area app, allowed redirect URIs) with deep links
+Some setup only happens in the Wix dashboard — always give the user the deep links (substitute the
+site's `metaSiteId` from the handoff / `ListWixSites`):
+- **Allowed authorization redirect URIs** (the #1 gotcha) — `https://manage.wix.com/dashboard/{metaSiteId}/oauth-apps-settings`.
+  Add the **app origin** (for credential login off `localhost:4321`) and the **exact `/callback` URL**
+  (for social/SSO) — character-for-character matching your `startSocialLogin` `callbackUri`.
+- **Members Area app** (profile data + custom fields) — `https://manage.wix.com/dashboard/{metaSiteId}/member-permissions`
+- **Signup security** (email verification, owner approval, reCAPTCHA) — `Dashboard → Settings → Login & Security`
+- **Custom SSO connection** (to obtain a `connectionId`) — the project's IAM / SSO settings in the Business Manager.
+
+## Seeding
+**Nothing to seed** — members self-register; there is no build-time member to create. See
+`seed/SEED.md` (separate from this client build; the members work is entirely frontend wiring).
+
+## Verify (before declaring done)
+- [ ] Client files copied into `src/`; `WIX_CLIENT_ID` set (not the placeholder).
+- [ ] Brand palette lives in `index.css` (`:root`/`.dark`); no parallel theme file; shipped components/pages not restyled or rewritten.
+- [ ] Opened the vertical's data route(s) (not just the home page) — `/login` and `/account` — and confirmed the shipped components render themed (surface, text, brand) with images.
+- [ ] `Layout` (fixed `<WixManageBanner/>` + `<Header/>` region, then `<Outlet/>` + Footer) wraps all routes; shipped `Login`/`Account`/`Callback` untouched; content clears the fixed chrome; `<MemberProvider>` wraps the tree; `<MemberMenu/>` in the header.
+- [ ] Sign-up: `register()` reaches `SUCCESS` (or `REQUIRE_EMAIL_VERIFICATION` handled via the code entry).
+- [ ] Log-in: `login()` reaches `SUCCESS`; wrong password shows `invalidCredentials`, not a crash.
+- [ ] After login `useMember().loggedIn` is `true`; `/account` renders the member (or the identity-only fallback with the Members Area app not installed — documented, not a bug). `/account` bounces a visitor to `/login`.
+- [ ] Session survives reload (same client); logout clears it and the next load is a clean anonymous visitor.
+- [ ] Social: the button redirects to the provider and `/callback` logs the member in (callback URL allow-listed), or is flagged as pending host setup.
+- [ ] No mocked member state, profile, or roles anywhere.
+- [ ] Told the user about any required dashboard setup (allowed redirect URIs, Members Area app) with deep links.