@payez/next-mvp 4.8.1 → 4.8.3

package/POST-INSTALL.md

@@ -1,408 +1,408 @@
-# Post-Install Debt
-
-**A running tab of everything a consuming site must do BY HAND after `npm install @payez/next-mvp`.**
-
-This file exists because "works out of the box" is the product claim and it is currently
-false. Every row below is work the package pushed onto the consumer. The tab is the backlog:
-the goal is to empty it, not to document it more thoroughly.
-
-Started 2026-08-26 from the UMI Browser (`umi_browser_website`, client 16) integration, where
-every single row was hit in one sitting. UMI is the honest measure of the out-of-box
-experience because nobody had pre-wired it — unlike idealresume.online and idealvibe.online,
-which were built alongside the package and quietly absorbed each of these as they appeared.
-
-**Add a row the moment you hand-write something the package could have shipped.** A step you
-only discover by hitting it is the same defect class this codebase keeps paying for: present,
-plausible and inert.
-
----
-
-## Scoring
-
-- **P1** — site is broken or insecure until done, and nothing tells you
-- **P2** — site is degraded or wrong until done
-- **P3** — friction; you get there, but slower than you should
-
-**Fix class:**
-- `auto` — the package could just do this, no consumer action at all
-- `codemod` — a generator / `npx @payez/next-mvp init` could write it
-- `doc` — genuinely a consumer choice; it only needs to be findable
-
----
-
-## The tab
-
-| # | What you must hand-write | P | Fix class | Status |
-|---|---|---|---|---|
-| 1 | 16 CSS variables in `globals.css` | P1 | auto | open |
-| 2 | `/api/auth/[...nextauth]` route file | P1 | codemod | open |
-| 3 | `/api/auth/settings` route file | P1 | codemod | open |
-| 4 | `/login` page mounting `ModeAwareLoginPage` | P1 | codemod | open |
-| 5 | `instrumentation.ts` + the node split | P1 | codemod | open |
-| 6 | `next.config.js` transpile + tracing keys | P1 | doc | open |
-| 7 | `--primary` vs `--color-primary` collision | P2 | auto | open |
-| 8 | `/test-env/*` mounts + `ENABLE_TEST_ROUTES` | P2 | doc | open |
-| 9 | Local user record (route + lib + hook) | P2 | codemod | open |
-| 10 | `server-auth.ts` wrapper | P3 | auto | open |
-| 11 | `REDIS_URL` and the required env set | P3 | doc | open |
-| 12 | `providers.tsx` provider nesting | P3 | codemod | open |
-| 13 | `/api/internal/session-data` — page ships, endpoint does not | P1 | auto | open |
-| 14 | **`routes/auth/nextauth` is a trap — do not mount it** | P1 | auto | open |
-| 15 | `id_token` dropped by a module-scoped ALS | P1 | auto | **CLOSED 4.3.4** |
-| 16 | Tenant-side: `VIBE_COLLECTION` is doing double duty | P2 | doc | open |
-| 17 | Tenant-side: vibe-client 0.2.3 sends the wrong filter shape | P2 | — | open (not this package) |
-
-**Nothing is closed yet. There is no `postinstall` script and no `init` command.**
-
----
-
-## 1. Sixteen CSS variables, and `ThemeProvider` emits none of them — P1
-
-The worst row on the tab, because it is invisible: the site renders, it just looks wrong, and
-the fallbacks make it look *deliberately* wrong rather than unstyled.
-
-Measured 2026-08-26 against installed `dist`:
-
-```
-components/ and pages/ READ   16 CSS variables
-theme/ThemeProvider WRITES     0
-```
-
-The sixteen:
-
-```
---background  --bg-card  --bg-default  --border  --border-default  --card
---color-error --color-primary --foreground --input --muted --muted-foreground
---primary --text-muted --text-primary --text-secondary
-```
-
-`ThemeProvider` takes a theme object and emits **nothing to CSS**. So all three sites
-independently hand-authored the same variable block in their own `globals.css` — three
-copies, already drifting.
-
-**Fix:** `ThemeProvider` maps the theme object onto these sixteen and sets them. That is the
-entire job it appears to exist to do. Until then a site that installs the package and uses a
-component gets silent fallbacks.
-
-## 2–4. The package exports routes and pages; you mount every one — P1
-
-`@payez/next-mvp` exports working handlers and pages. It cannot create files in your `app/`
-directory, so **every one of them is a 404 until you write a re-export by hand** — and
-nothing tells you which exist.
-
-UMI had **zero of them mounted** and looked like a working site. The login page rendered a
-demo gate against hardcoded strings; `/api/auth/*` did not exist at all, so the sign-in
-screen's request for what the client offers 404'd and it drew nothing.
-
-```
-app/api/auth/[...nextauth]/route.ts   export { GET, POST } from '@payez/next-mvp/routes/auth/nextauth';
-app/api/auth/settings/route.ts        export { GET }       from '@payez/next-mvp/routes/auth/settings';
-app/login/page.tsx                    ModeAwareLoginPage + your branding
-```
-
-**Fix:** `npx @payez/next-mvp init` writes these. Failing that, one page in the README that
-lists every mountable export — there is currently no such list anywhere.
-
-## 5. `instrumentation.ts`, and the part the template gets wrong — P1
-
-A template ships at `src/templates/instrumentation.ts` — the only template in the package —
-but you still copy it in by hand, and it is **not** the shape that works.
-
-Two things it does not tell you:
-
-- **`instrumentation.ts` is compiled for BOTH the node and edge runtimes.** `NEXT_RUNTIME` is
-  a *runtime* guard; imports resolve at *build* time, so node-only dependencies still get
-  traced into the edge bundle and the build fails. The working shape is a thin
-  `instrumentation.ts` that dynamic-imports `instrumentation-node.ts`.
-- **`await import()` does not stay dynamic under `module: CommonJS`.** TypeScript emits
-  `Promise.resolve().then(() => require(...))`, which is statically traced exactly like a
-  top-level import. Cost us three failed fixes.
-
-Also: the template's catch block used to log *"Will retry initialization on first request"*
-and continue. It does not retry. A site whose IDP handshake failed would serve requests
-with no auth config and say so nowhere. Now `process.exit(1)`.
-
-**Fix:** ship the two-file split as the template, and put both facts above in it as comments.
-
-## 6. `next.config.js` — two keys, and one that must never come back — P1
-
-```js
-transpilePackages: ['@payez/next-mvp'],
-outputFileTracingRoot: path.join(__dirname),
-```
-
-Mentioned in two docs, in passing, not as a required step.
-
-**Do not add a `webpack:` key to work around a bundler warning.** It disables Turbopack and
-turns a cosmetic warning into a hard `UnhandledSchemeError`. A note now sits in UMI's
-`next.config.js` saying so.
-
-**Related, and the reason a day was lost:** `next dev` uses **webpack** by default in Next
-15.5. Turbopack is opt-in via `--turbopack`. Assuming otherwise sent three bundler fixes at
-the wrong bundler.
-
-## 7. `--primary` and `--color-primary` are two names for one value — P2
-
-Components read both. Nothing defines the relationship. `TraditionalAuthSection`'s submit
-button hardcodes `var(--color-primary, #10b981)` — so a site that defines `--primary` and not
-`--color-primary` gets a **green** button no matter what its brand colour is. UMI is
-`#FF6B5B`; it defines both, as a workaround.
-
-This is the CLAUDE.md rule the package itself breaks: **one value gets one name.** Pick
-`--color-primary`, and drop the hardcoded emerald — a fallback that silently substitutes
-another product's brand colour is worse than no fallback.
-
-## 8. `/test-env/*` — four pages, a flag, and a trap — P2
-
-Four diagnostics ship (`TestEnvPage`, `JwtInspectPage`, `RefreshTokenPage`,
-`EmergencyLogoutPage`). Documented in **zero** docs. idealvibe mounts five routes; UMI mounted
-none and every URL 404'd.
-
-They are exported **only** as guarded server components — the raw client pages are not
-exported. The guard reads `ENABLE_TEST_ROUTES`, exact-match `'true'`, fail-closed, and returns
-a real 404 rather than a 403 so probing cannot confirm the route exists. All of that is
-correct and should not be softened.
-
-**The trap:** putting `'use client'` on the page file that re-exports the guard. Non-`NEXT_PUBLIC_`
-variables do not exist in the browser, so the guard reads `undefined` and denies **forever** —
-a gate that greps as present and protects nothing. Hit on 2026-08-26.
-
-These pages show a **live session token with a copy button**. `ENABLE_TEST_ROUTES=true` belongs
-in `.env.development` and nowhere else. Verified both ways on UMI: flag off, all four 404 while
-`/login` stays 200.
-
-**Fix:** document the four exports, the server-component requirement, and the flag — together,
-in one place, with the `'use client'` trap called out.
-
-## 9. The local user record — three files, written three times — P2
-
-The IDP owns identity; the tenant app needs its own row so application data can join to a user.
-The package ships **none** of it, so all three sites wrote the same three files:
-
-```
-app/api/auth/record-login/route.ts    upsert on sign-in
-app/lib/vibe-user.ts                  find-or-create by idp_user_id
-app/hooks/useLoginRecorder.ts         fire once per session
-```
-
-Two things every consumer must get right and has no way to know:
-
-- **Identity is `idp_user_id`, never email.** Email changes and gets reused; matching on it
-  silently merges two people.
-- **The effect needs a ref guard.** Without one, a re-render or Fast Refresh posts again —
-  harmless for the row, but it inflates `login_count`, which is then wrong in a way nobody
-  would think to question.
-
-The app-specific parts (tiers, credits, milestones — idealresume's runs to 1,567 lines) are
-genuinely the site's. The find-or-create core is not.
-
-## 10. `server-auth.ts` — a wrapper over one export — P3
-
-Every site writes the same ~60-line wrapper over `getFreshIdpToken` to assemble the refresh
-config from env and normalise the result. Package-side, this is a default config reader.
-
-## 11. Env vars — no single list, no startup validation of the set — P3
-
-`IDP_URL`, `CLIENT_ID`, `REFRESH_ENDPOINT`, `REDIS_URL`, `ENABLE_TEST_ROUTES`, plus the broker
-secret. `REDIS_URL` was missing from UMI and surfaced as an unrelated-looking failure.
-
-**`CLIENT_ID` is the only spelling.** Until 4.2.5 the package accepted `CLIENT_ID`,
-`NEXT_PUBLIC_CLIENT_ID` and `NEXT_CLIENT_ID` for one value; that cost a live defect. All six
-read sites are collapsed and `idp-client-config.ts` carries the banner. Do not reintroduce a
-second name here.
-
-**Fix:** ship `.env.example` with every variable, what reads it, and whether it is required.
-
-## 12. `providers.tsx` — nesting order matters and is unstated — P3
-
-```
-AuthProvider → LoginRecorderProvider → ThemeProvider
-```
-
-`ModeAwareLoginPage` reads `useAuthConfig()`, so without `AuthProvider` the sign-in screen
-renders **no controls at all** — no Google button, no email form — even while
-`/api/auth/settings` correctly reports `enabledProviders: ["google"]`. It fails as a blank
-card, which reads as a styling problem.
-
-**Do not set `mode` in a site's auth config.** What sign-in offers comes from the IDP via
-`/api/auth/settings` (4.3.0+). A site hardcoding its own auth mode is how a login screen and
-its own IDP end up disagreeing.
-
-## 13. The Session Inspector fetches an endpoint the package does not ship — P1
-
-`JwtInspectPage` fetches `/api/internal/session-data`. **No such handler exists in the
-package and none is exported.** Line 39 of the page says the quiet part — "reads them from
-the *consuming app's* `/api/internal/session-data` route" — which is a defensible design
-call (a session record's shape is the app's business) documented in the one place no
-consumer will ever read: the source of a page they did not write.
-
-**It fails invisibly**, which is the real defect. The page does:
-
-```ts
-fetch('/api/internal/session-data').then(r => r.ok ? r.json() : null).catch(() => {})
-```
-
-A 404 and a session with no data render **identically**: every field `N/A`, and
-`Error: N/A` underneath, which reads as "no error". The inspector looked like it was
-reporting a broken session. It was reporting a missing route. Found only by watching the
-network tab.
-
-UMI now owns `app/api/internal/session-data/route.ts`. Two things any implementation must
-get right:
-
-- **The 16 field names are a contract** (`JwtInspectPage` reads `ss.userId`, `ss.roles`,
-  `ss.idpAccessToken`, …). Rename one and that row silently goes `N/A` forever.
-- **It returns the live IDP access AND refresh token.** The package's own `better-auth.ts`
-  names this exact endpoint as the leak path it refuses to put `id_token` behind. UMI gates
-  it on `ENABLE_TEST_ROUTES` — same fail-closed exact-match, read at request time, 404 not
-  403. Verified both ways.
-
-**Fix:** either ship the route (it is mechanical — `getSession` + `getSession` from
-`lib/session-store`, both already exported), or make the page say `endpoint missing` instead
-of swallowing the 404. Preferably both.
-
-## 14. `routes/auth/nextauth` is a trap. Do not mount it. — P1
-
-**This one cost the most and looked the most correct.** The package ships
-`routes/auth/nextauth`, its own docblock calls it "Ready-to-Use", and its usage example is
-the obvious one-liner:
-
-```ts
-export { GET, POST } from '@payez/next-mvp/routes/auth/nextauth';   // WRONG
-```
-
-It signs users in. It never provisions them.
-
-```
-routes/auth/nextauth GET  ->  toNextJsHandler(auth)       — signs in. Stops.
-createAuthGetHandler GET  ->  ba.GET + IDP token exchange — signs in AND provisions.
-```
-
-Only `createAuthGetHandler` runs `exchangeOAuthForIdpTokens` after the OAuth callback. With
-the re-export, Better Auth creates a **perfectly convincing session** — cookie, user id,
-email, Google avatar — and the Redis record holding the IDP access token, refresh token and
-roles is **never written**.
-
-The damage surfaces nowhere near the cause:
-
-- `/test-env/jwt-inspect` → `NO_REDIS_SESSION`, no tokens, no roles
-- anything calling `getFreshIdpToken` → `NO_SESSION` **for a user who is visibly signed in**
-- `record-login` → 401, so the app never creates its local user row
-
-Correct wiring, and what idealvibe.online and idealresume.online **both** hand-write:
-
-```ts
-export const GET = createAuthGetHandler('/login');   // your login path
-export async function POST(request: Request) {
-  const ba = await getBetterAuthHandler();
-  return ba!.POST(request);
-}
-```
-
-Neither working site uses the re-export. That is not boilerplate they failed to factor out —
-it is the only wiring that works.
-
-**This row is also a correction to row 2 of this tab.** Row 2's advice — prefer the package
-re-export over copying another site's file — is right for `settings` and wrong here, and I
-followed it into this exact bug on UMI. A codemod that generates the "obvious" re-export
-would ship this defect to every new consumer.
-
-**Fix:** `routes/auth/nextauth` should either export the exchanging handler or refuse to
-exist. A "Ready-to-Use" export that yields a half-provisioned session is worse than no
-export, because it looks like the sanctioned path.
-
-## 15. `id_token` was dropped because the ALS was module-scoped — P1, CLOSED in 4.3.4
-
-The most expensive one, and the package's own fault end to end.
-
-`state` (the Better Auth instance) was moved to `globalThis` by 181814 **because this module
-loads more than once per process** — instrumentation and the auth route are separate chunks
-with separate registries. `idTokenScope`, the AsyncLocalStorage that carries the provider's
-raw `id_token` from `getUserInfo` to the IDP exchange, was left in module scope.
-
-So the two copies shared the instance and **not** the scope:
-
-```
-copy A builds the instance   -> the getUserInfo closure captures A's idTokenScope
-copy B serves the callback   -> createAuthGetHandler runs .run({}) on B's
-getUserInfo fires, reads A   -> getStore() undefined, `if (scope)` skips SILENTLY
-the exchange reads B         -> empty, so id_token is omitted from the body
-```
-
-Sign-in succeeds at every visible step — cookie, user id, email, avatar. The IDP then
-answers `401 UNVERIFIED_ASSERTION`, and its own log names the reason:
-`reason="id_token missing"` (idp.payez.net, correlationId 0HNO2755RESR1, 2026-08-26).
-
-**The consequence is a security control that shipped as a no-op.** 472fb75c added the raw
-`id_token` because `/api/ExternalAuth/oauth-callback` would mint an IDP access+refresh pair
-for any *asserted* email, on a public LoadBalancer — the only verifiable field in that body
-is the provider's signed token. Wherever this module double-loads, that fix never arrived.
-
-Fixed in 4.3.4: `idTokenScope` now lives on `globalThis` under the same pattern as `state`,
-and the silent `if (scope)` skip warns and names its two causes.
-
-**The lesson generalises past this bug: shared instance + per-copy request scope is the worst
-combination.** Everything looks wired, and the one field that proves identity is dropped. If
-any other module-scoped singleton in this package participates in a request, audit it the
-same way.
-
-## 16. Tenant-side: one env var, two unrelated jobs — P2
-
-Not this package's bug, but every consumer that has a marketing form will hit it.
-
-`createVibeClient` resolves the collection as
-`config.defaultCollection || process.env.VIBE_COLLECTION || 'vibe_app'`. The library default
-is already correct. UMI set `VIBE_COLLECTION=payez_contact_list` for its **waitlist form**,
-and that variable is global to the client — so it silently retargeted every collection call
-in the app, including user identity. Sign-in queried the waitlist's collection for a `users`
-table that does not live there.
-
-Same rule as `CLIENT_ID`, from the other direction: there, one value had three names; here,
-one name carries two values. Pin the collection at the call site.
-
-## 17. Tenant-side: vibe-client 0.2.3 sends a filter shape the API rejects — P2
-
-`list({ filter })` serialises through `convertFiltersToVibeFormat`, which returns an **array**
-`[{ field, operator, value }]`. `PayEz.Vibe.Public.Api` binds `filter` to a single
-`VibeFilterNode` **object** (`VibeQueryModels.cs:63`), so the request fails to deserialise
-before the query builder ever runs:
-
-```
-400 VALIDATION_ERROR  $.filter
-"The JSON value could not be converted to ...QueryBuilder.VibeFilterNode"
-```
-
-The API is not being arbitrary — `VibeQueryBuilder.cs:355` documents this exact query as
-supported (`{ "idp_user_id": { "eq": 22 } }`), and :94 accepts the flat
-`{ field, operator, value }` form too. The array wrapper is the whole defect, and the API
-change is deliberate.
-
-**This affects every filtered query from 0.2.3, on all three sites.** UMI was only the first
-to make one — measured in the IDP proxy logs, UMI's client was the sole source of `$.filter`
-400s in 24h while idealresume queried cleanly, because idealresume's calls in that window did
-not filter.
-
-UMI hand-rolls the single lookup against the proxy with the correct node, reusing the
-library's `resolveConfig()`. That is a workaround with a cost: it duplicates the HMAC recipe
-(`timestamp|method|endpoint`, key base64-decoded) because `generateHmacSignature` is not
-exported, so a signing change in the library breaks that call with a 401. **The real fix is a
-vibe-client release that emits a `VibeFilterNode`**; its source is not in this workspace.
-
----
-
-## What the tab says about the package
-
-Fourteen rows; **eleven are `auto` or `codemod`** — the package could do them, or generate
-them, with no judgement call from the consumer. Only three are real consumer choices.
-
-The three P1 route/page rows share one root cause: **the package can export a thing but cannot
-mount it**, and nothing enumerates what is mountable. That is one fix, not three — a list, or
-an `init` command that writes the re-exports.
-
-Eight of the fourteen appear in **no doc at all**. `QUICK_START.md` is a stub with a single
-heading. Row 14 is worse than undocumented — the wrong path is the one with the usage example.
-
-The recurring shape, which is the same one this codebase keeps paying for: **things present,
-plausible and inert.** A `ThemeProvider` that provides no theme. A template whose comment
-promises a retry that never happens. A guard that greps as a gate and denies everything. An
-exported page nothing mounts. None of them announce themselves; all of them look done.
+# Post-Install Debt
+
+**A running tab of everything a consuming site must do BY HAND after `npm install @payez/next-mvp`.**
+
+This file exists because "works out of the box" is the product claim and it is currently
+false. Every row below is work the package pushed onto the consumer. The tab is the backlog:
+the goal is to empty it, not to document it more thoroughly.
+
+Started 2026-08-26 from the UMI Browser (`umi_browser_website`, client 16) integration, where
+every single row was hit in one sitting. UMI is the honest measure of the out-of-box
+experience because nobody had pre-wired it — unlike idealresume.online and idealvibe.online,
+which were built alongside the package and quietly absorbed each of these as they appeared.
+
+**Add a row the moment you hand-write something the package could have shipped.** A step you
+only discover by hitting it is the same defect class this codebase keeps paying for: present,
+plausible and inert.
+
+---
+
+## Scoring
+
+- **P1** — site is broken or insecure until done, and nothing tells you
+- **P2** — site is degraded or wrong until done
+- **P3** — friction; you get there, but slower than you should
+
+**Fix class:**
+- `auto` — the package could just do this, no consumer action at all
+- `codemod` — a generator / `npx @payez/next-mvp init` could write it
+- `doc` — genuinely a consumer choice; it only needs to be findable
+
+---
+
+## The tab
+
+| # | What you must hand-write | P | Fix class | Status |
+|---|---|---|---|---|
+| 1 | 16 CSS variables in `globals.css` | P1 | auto | open |
+| 2 | `/api/auth/[...nextauth]` route file | P1 | codemod | open |
+| 3 | `/api/auth/settings` route file | P1 | codemod | open |
+| 4 | `/login` page mounting `ModeAwareLoginPage` | P1 | codemod | open |
+| 5 | `instrumentation.ts` + the node split | P1 | codemod | open |
+| 6 | `next.config.js` transpile + tracing keys | P1 | doc | open |
+| 7 | `--primary` vs `--color-primary` collision | P2 | auto | open |
+| 8 | `/test-env/*` mounts + `ENABLE_TEST_ROUTES` | P2 | doc | open |
+| 9 | Local user record (route + lib + hook) | P2 | codemod | open |
+| 10 | `server-auth.ts` wrapper | P3 | auto | open |
+| 11 | `REDIS_URL` and the required env set | P3 | doc | open |
+| 12 | `providers.tsx` provider nesting | P3 | codemod | open |
+| 13 | `/api/internal/session-data` — page ships, endpoint does not | P1 | auto | open |
+| 14 | **`routes/auth/nextauth` is a trap — do not mount it** | P1 | auto | open |
+| 15 | `id_token` dropped by a module-scoped ALS | P1 | auto | **CLOSED 4.3.4** |
+| 16 | Tenant-side: `VIBE_COLLECTION` is doing double duty | P2 | doc | open |
+| 17 | Tenant-side: vibe-client 0.2.3 sends the wrong filter shape | P2 | — | open (not this package) |
+
+**Nothing is closed yet. There is no `postinstall` script and no `init` command.**
+
+---
+
+## 1. Sixteen CSS variables, and `ThemeProvider` emits none of them — P1
+
+The worst row on the tab, because it is invisible: the site renders, it just looks wrong, and
+the fallbacks make it look *deliberately* wrong rather than unstyled.
+
+Measured 2026-08-26 against installed `dist`:
+
+```
+components/ and pages/ READ   16 CSS variables
+theme/ThemeProvider WRITES     0
+```
+
+The sixteen:
+
+```
+--background  --bg-card  --bg-default  --border  --border-default  --card
+--color-error --color-primary --foreground --input --muted --muted-foreground
+--primary --text-muted --text-primary --text-secondary
+```
+
+`ThemeProvider` takes a theme object and emits **nothing to CSS**. So all three sites
+independently hand-authored the same variable block in their own `globals.css` — three
+copies, already drifting.
+
+**Fix:** `ThemeProvider` maps the theme object onto these sixteen and sets them. That is the
+entire job it appears to exist to do. Until then a site that installs the package and uses a
+component gets silent fallbacks.
+
+## 2–4. The package exports routes and pages; you mount every one — P1
+
+`@payez/next-mvp` exports working handlers and pages. It cannot create files in your `app/`
+directory, so **every one of them is a 404 until you write a re-export by hand** — and
+nothing tells you which exist.
+
+UMI had **zero of them mounted** and looked like a working site. The login page rendered a
+demo gate against hardcoded strings; `/api/auth/*` did not exist at all, so the sign-in
+screen's request for what the client offers 404'd and it drew nothing.
+
+```
+app/api/auth/[...nextauth]/route.ts   export { GET, POST } from '@payez/next-mvp/routes/auth/nextauth';
+app/api/auth/settings/route.ts        export { GET }       from '@payez/next-mvp/routes/auth/settings';
+app/login/page.tsx                    ModeAwareLoginPage + your branding
+```
+
+**Fix:** `npx @payez/next-mvp init` writes these. Failing that, one page in the README that
+lists every mountable export — there is currently no such list anywhere.
+
+## 5. `instrumentation.ts`, and the part the template gets wrong — P1
+
+A template ships at `src/templates/instrumentation.ts` — the only template in the package —
+but you still copy it in by hand, and it is **not** the shape that works.
+
+Two things it does not tell you:
+
+- **`instrumentation.ts` is compiled for BOTH the node and edge runtimes.** `NEXT_RUNTIME` is
+  a *runtime* guard; imports resolve at *build* time, so node-only dependencies still get
+  traced into the edge bundle and the build fails. The working shape is a thin
+  `instrumentation.ts` that dynamic-imports `instrumentation-node.ts`.
+- **`await import()` does not stay dynamic under `module: CommonJS`.** TypeScript emits
+  `Promise.resolve().then(() => require(...))`, which is statically traced exactly like a
+  top-level import. Cost us three failed fixes.
+
+Also: the template's catch block used to log *"Will retry initialization on first request"*
+and continue. It does not retry. A site whose IDP handshake failed would serve requests
+with no auth config and say so nowhere. Now `process.exit(1)`.
+
+**Fix:** ship the two-file split as the template, and put both facts above in it as comments.
+
+## 6. `next.config.js` — two keys, and one that must never come back — P1
+
+```js
+transpilePackages: ['@payez/next-mvp'],
+outputFileTracingRoot: path.join(__dirname),
+```
+
+Mentioned in two docs, in passing, not as a required step.
+
+**Do not add a `webpack:` key to work around a bundler warning.** It disables Turbopack and
+turns a cosmetic warning into a hard `UnhandledSchemeError`. A note now sits in UMI's
+`next.config.js` saying so.
+
+**Related, and the reason a day was lost:** `next dev` uses **webpack** by default in Next
+15.5. Turbopack is opt-in via `--turbopack`. Assuming otherwise sent three bundler fixes at
+the wrong bundler.
+
+## 7. `--primary` and `--color-primary` are two names for one value — P2
+
+Components read both. Nothing defines the relationship. `TraditionalAuthSection`'s submit
+button hardcodes `var(--color-primary, #10b981)` — so a site that defines `--primary` and not
+`--color-primary` gets a **green** button no matter what its brand colour is. UMI is
+`#FF6B5B`; it defines both, as a workaround.
+
+This is the CLAUDE.md rule the package itself breaks: **one value gets one name.** Pick
+`--color-primary`, and drop the hardcoded emerald — a fallback that silently substitutes
+another product's brand colour is worse than no fallback.
+
+## 8. `/test-env/*` — four pages, a flag, and a trap — P2
+
+Four diagnostics ship (`TestEnvPage`, `JwtInspectPage`, `RefreshTokenPage`,
+`EmergencyLogoutPage`). Documented in **zero** docs. idealvibe mounts five routes; UMI mounted
+none and every URL 404'd.
+
+They are exported **only** as guarded server components — the raw client pages are not
+exported. The guard reads `ENABLE_TEST_ROUTES`, exact-match `'true'`, fail-closed, and returns
+a real 404 rather than a 403 so probing cannot confirm the route exists. All of that is
+correct and should not be softened.
+
+**The trap:** putting `'use client'` on the page file that re-exports the guard. Non-`NEXT_PUBLIC_`
+variables do not exist in the browser, so the guard reads `undefined` and denies **forever** —
+a gate that greps as present and protects nothing. Hit on 2026-08-26.
+
+These pages show a **live session token with a copy button**. `ENABLE_TEST_ROUTES=true` belongs
+in `.env.development` and nowhere else. Verified both ways on UMI: flag off, all four 404 while
+`/login` stays 200.
+
+**Fix:** document the four exports, the server-component requirement, and the flag — together,
+in one place, with the `'use client'` trap called out.
+
+## 9. The local user record — three files, written three times — P2
+
+The IDP owns identity; the tenant app needs its own row so application data can join to a user.
+The package ships **none** of it, so all three sites wrote the same three files:
+
+```
+app/api/auth/record-login/route.ts    upsert on sign-in
+app/lib/vibe-user.ts                  find-or-create by idp_user_id
+app/hooks/useLoginRecorder.ts         fire once per session
+```
+
+Two things every consumer must get right and has no way to know:
+
+- **Identity is `idp_user_id`, never email.** Email changes and gets reused; matching on it
+  silently merges two people.
+- **The effect needs a ref guard.** Without one, a re-render or Fast Refresh posts again —
+  harmless for the row, but it inflates `login_count`, which is then wrong in a way nobody
+  would think to question.
+
+The app-specific parts (tiers, credits, milestones — idealresume's runs to 1,567 lines) are
+genuinely the site's. The find-or-create core is not.
+
+## 10. `server-auth.ts` — a wrapper over one export — P3
+
+Every site writes the same ~60-line wrapper over `getFreshIdpToken` to assemble the refresh
+config from env and normalise the result. Package-side, this is a default config reader.
+
+## 11. Env vars — no single list, no startup validation of the set — P3
+
+`IDP_URL`, `CLIENT_ID`, `REFRESH_ENDPOINT`, `REDIS_URL`, `ENABLE_TEST_ROUTES`, plus the broker
+secret. `REDIS_URL` was missing from UMI and surfaced as an unrelated-looking failure.
+
+**`CLIENT_ID` is the only spelling.** Until 4.2.5 the package accepted `CLIENT_ID`,
+`NEXT_PUBLIC_CLIENT_ID` and `NEXT_CLIENT_ID` for one value; that cost a live defect. All six
+read sites are collapsed and `idp-client-config.ts` carries the banner. Do not reintroduce a
+second name here.
+
+**Fix:** ship `.env.example` with every variable, what reads it, and whether it is required.
+
+## 12. `providers.tsx` — nesting order matters and is unstated — P3
+
+```
+AuthProvider → LoginRecorderProvider → ThemeProvider
+```
+
+`ModeAwareLoginPage` reads `useAuthConfig()`, so without `AuthProvider` the sign-in screen
+renders **no controls at all** — no Google button, no email form — even while
+`/api/auth/settings` correctly reports `enabledProviders: ["google"]`. It fails as a blank
+card, which reads as a styling problem.
+
+**Do not set `mode` in a site's auth config.** What sign-in offers comes from the IDP via
+`/api/auth/settings` (4.3.0+). A site hardcoding its own auth mode is how a login screen and
+its own IDP end up disagreeing.
+
+## 13. The Session Inspector fetches an endpoint the package does not ship — P1
+
+`JwtInspectPage` fetches `/api/internal/session-data`. **No such handler exists in the
+package and none is exported.** Line 39 of the page says the quiet part — "reads them from
+the *consuming app's* `/api/internal/session-data` route" — which is a defensible design
+call (a session record's shape is the app's business) documented in the one place no
+consumer will ever read: the source of a page they did not write.
+
+**It fails invisibly**, which is the real defect. The page does:
+
+```ts
+fetch('/api/internal/session-data').then(r => r.ok ? r.json() : null).catch(() => {})
+```
+
+A 404 and a session with no data render **identically**: every field `N/A`, and
+`Error: N/A` underneath, which reads as "no error". The inspector looked like it was
+reporting a broken session. It was reporting a missing route. Found only by watching the
+network tab.
+
+UMI now owns `app/api/internal/session-data/route.ts`. Two things any implementation must
+get right:
+
+- **The 16 field names are a contract** (`JwtInspectPage` reads `ss.userId`, `ss.roles`,
+  `ss.idpAccessToken`, …). Rename one and that row silently goes `N/A` forever.
+- **It returns the live IDP access AND refresh token.** The package's own `better-auth.ts`
+  names this exact endpoint as the leak path it refuses to put `id_token` behind. UMI gates
+  it on `ENABLE_TEST_ROUTES` — same fail-closed exact-match, read at request time, 404 not
+  403. Verified both ways.
+
+**Fix:** either ship the route (it is mechanical — `getSession` + `getSession` from
+`lib/session-store`, both already exported), or make the page say `endpoint missing` instead
+of swallowing the 404. Preferably both.
+
+## 14. `routes/auth/nextauth` is a trap. Do not mount it. — P1
+
+**This one cost the most and looked the most correct.** The package ships
+`routes/auth/nextauth`, its own docblock calls it "Ready-to-Use", and its usage example is
+the obvious one-liner:
+
+```ts
+export { GET, POST } from '@payez/next-mvp/routes/auth/nextauth';   // WRONG
+```
+
+It signs users in. It never provisions them.
+
+```
+routes/auth/nextauth GET  ->  toNextJsHandler(auth)       — signs in. Stops.
+createAuthGetHandler GET  ->  ba.GET + IDP token exchange — signs in AND provisions.
+```
+
+Only `createAuthGetHandler` runs `exchangeOAuthForIdpTokens` after the OAuth callback. With
+the re-export, Better Auth creates a **perfectly convincing session** — cookie, user id,
+email, Google avatar — and the Redis record holding the IDP access token, refresh token and
+roles is **never written**.
+
+The damage surfaces nowhere near the cause:
+
+- `/test-env/jwt-inspect` → `NO_REDIS_SESSION`, no tokens, no roles
+- anything calling `getFreshIdpToken` → `NO_SESSION` **for a user who is visibly signed in**
+- `record-login` → 401, so the app never creates its local user row
+
+Correct wiring, and what idealvibe.online and idealresume.online **both** hand-write:
+
+```ts
+export const GET = createAuthGetHandler('/login');   // your login path
+export async function POST(request: Request) {
+  const ba = await getBetterAuthHandler();
+  return ba!.POST(request);
+}
+```
+
+Neither working site uses the re-export. That is not boilerplate they failed to factor out —
+it is the only wiring that works.
+
+**This row is also a correction to row 2 of this tab.** Row 2's advice — prefer the package
+re-export over copying another site's file — is right for `settings` and wrong here, and I
+followed it into this exact bug on UMI. A codemod that generates the "obvious" re-export
+would ship this defect to every new consumer.
+
+**Fix:** `routes/auth/nextauth` should either export the exchanging handler or refuse to
+exist. A "Ready-to-Use" export that yields a half-provisioned session is worse than no
+export, because it looks like the sanctioned path.
+
+## 15. `id_token` was dropped because the ALS was module-scoped — P1, CLOSED in 4.3.4
+
+The most expensive one, and the package's own fault end to end.
+
+`state` (the Better Auth instance) was moved to `globalThis` by 181814 **because this module
+loads more than once per process** — instrumentation and the auth route are separate chunks
+with separate registries. `idTokenScope`, the AsyncLocalStorage that carries the provider's
+raw `id_token` from `getUserInfo` to the IDP exchange, was left in module scope.
+
+So the two copies shared the instance and **not** the scope:
+
+```
+copy A builds the instance   -> the getUserInfo closure captures A's idTokenScope
+copy B serves the callback   -> createAuthGetHandler runs .run({}) on B's
+getUserInfo fires, reads A   -> getStore() undefined, `if (scope)` skips SILENTLY
+the exchange reads B         -> empty, so id_token is omitted from the body
+```
+
+Sign-in succeeds at every visible step — cookie, user id, email, avatar. The IDP then
+answers `401 UNVERIFIED_ASSERTION`, and its own log names the reason:
+`reason="id_token missing"` (idp.payez.net, correlationId 0HNO2755RESR1, 2026-08-26).
+
+**The consequence is a security control that shipped as a no-op.** 472fb75c added the raw
+`id_token` because `/api/ExternalAuth/oauth-callback` would mint an IDP access+refresh pair
+for any *asserted* email, on a public LoadBalancer — the only verifiable field in that body
+is the provider's signed token. Wherever this module double-loads, that fix never arrived.
+
+Fixed in 4.3.4: `idTokenScope` now lives on `globalThis` under the same pattern as `state`,
+and the silent `if (scope)` skip warns and names its two causes.
+
+**The lesson generalises past this bug: shared instance + per-copy request scope is the worst
+combination.** Everything looks wired, and the one field that proves identity is dropped. If
+any other module-scoped singleton in this package participates in a request, audit it the
+same way.
+
+## 16. Tenant-side: one env var, two unrelated jobs — P2
+
+Not this package's bug, but every consumer that has a marketing form will hit it.
+
+`createVibeClient` resolves the collection as
+`config.defaultCollection || process.env.VIBE_COLLECTION || 'vibe_app'`. The library default
+is already correct. UMI set `VIBE_COLLECTION=payez_contact_list` for its **waitlist form**,
+and that variable is global to the client — so it silently retargeted every collection call
+in the app, including user identity. Sign-in queried the waitlist's collection for a `users`
+table that does not live there.
+
+Same rule as `CLIENT_ID`, from the other direction: there, one value had three names; here,
+one name carries two values. Pin the collection at the call site.
+
+## 17. Tenant-side: vibe-client 0.2.3 sends a filter shape the API rejects — P2
+
+`list({ filter })` serialises through `convertFiltersToVibeFormat`, which returns an **array**
+`[{ field, operator, value }]`. `PayEz.Vibe.Public.Api` binds `filter` to a single
+`VibeFilterNode` **object** (`VibeQueryModels.cs:63`), so the request fails to deserialise
+before the query builder ever runs:
+
+```
+400 VALIDATION_ERROR  $.filter
+"The JSON value could not be converted to ...QueryBuilder.VibeFilterNode"
+```
+
+The API is not being arbitrary — `VibeQueryBuilder.cs:355` documents this exact query as
+supported (`{ "idp_user_id": { "eq": 22 } }`), and :94 accepts the flat
+`{ field, operator, value }` form too. The array wrapper is the whole defect, and the API
+change is deliberate.
+
+**This affects every filtered query from 0.2.3, on all three sites.** UMI was only the first
+to make one — measured in the IDP proxy logs, UMI's client was the sole source of `$.filter`
+400s in 24h while idealresume queried cleanly, because idealresume's calls in that window did
+not filter.
+
+UMI hand-rolls the single lookup against the proxy with the correct node, reusing the
+library's `resolveConfig()`. That is a workaround with a cost: it duplicates the HMAC recipe
+(`timestamp|method|endpoint`, key base64-decoded) because `generateHmacSignature` is not
+exported, so a signing change in the library breaks that call with a 401. **The real fix is a
+vibe-client release that emits a `VibeFilterNode`**; its source is not in this workspace.
+
+---
+
+## What the tab says about the package
+
+Fourteen rows; **eleven are `auto` or `codemod`** — the package could do them, or generate
+them, with no judgement call from the consumer. Only three are real consumer choices.
+
+The three P1 route/page rows share one root cause: **the package can export a thing but cannot
+mount it**, and nothing enumerates what is mountable. That is one fix, not three — a list, or
+an `init` command that writes the re-exports.
+
+Eight of the fourteen appear in **no doc at all**. `QUICK_START.md` is a stub with a single
+heading. Row 14 is worse than undocumented — the wrong path is the one with the usage example.
+
+The recurring shape, which is the same one this codebase keeps paying for: **things present,
+plausible and inert.** A `ThemeProvider` that provides no theme. A template whose comment
+promises a retry that never happens. A guard that greps as a gate and denies everything. An
+exported page nothing mounts. None of them announce themselves; all of them look done.