@helloleo/plugins 0.2.0-beta.7 → 0.2.0

package/src/tools/setup-netsuite.ts

@@ -1,262 +1,675 @@
-import { mkdir } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import type { Plugin } from "@opencode-ai/plugin";
 import { tool } from "@opencode-ai/plugin";
 
 /**
- * Adds NetSuite OAuth wiring on top of an existing scaffold: the netsuite
- * OAuth client, a NetSuite auth context (auth.tsx), and the AuthLayout /
- * LoginPage / SignInWithNetSuite components. It never overwrites a
- * scaffold file -- the one manual step is wrapping the root route's
- * <Outlet /> with <AuthLayout> (the tool's output shows the snippet).
- * All NetSuite-specific templates live in this file -- one place to read
- * or change anything NetSuite-related.
+ * NetSuite runtime OAuth for a TanStack Start (SSR) project.
  *
- * Called AFTER `scaffold`, never instead of it.
+ * TanStack Start IS the backend: the app runs as one Cloudflare Worker —
+ * `vite dev` (workerd) inside the Fly preview machine in dev, the published
+ * Worker in prod. So the OAuth backend is a set of **server routes inside the
+ * app**, NOT a separate Worker. There is no VITE_WORKER_URL and nothing is
+ * cross-site: the SPA calls its own /auth/netsuite/* and /api/me.
+ *
+ * What this writes (all additive; only src/db/schema.ts is appended to):
+ *   - src/db/schema.ts            += netsuite_flows + netsuite_sessions tables
+ *   - src/lib/netsuite-server.ts   server OAuth helpers (env, PKCE, token
+ *                                  exchange, session refresh, netsuiteFetch)
+ *   - src/routes/auth/netsuite/start.ts     GET  begin PKCE flow -> NetSuite
+ *   - src/routes/auth/netsuite/callback.ts  GET  code -> tokens -> session
+ *   - src/routes/auth/netsuite/logout.ts    POST destroy session
+ *   - src/routes/api/me.ts                  GET  bearer sid -> session (auth check)
+ *   - src/lib/netsuite.ts          client (same-origin, bearer-in-fragment)
+ *   - src/lib/auth.tsx             NetSuiteAuthProvider / useNetSuiteAuth
+ *   - src/components/auth/{AuthLayout,LoginPage,SignInWithNetSuite}.tsx
+ *
+ * This login uses NetSuite Integration Record #2 (scope: rest_webservices) —
+ * a SEPARATE record from the MCP one (scope: mcp) used only to BUILD the app.
+ *
+ * Config (read via @helloleo/runtime env): NETSUITE_ACCOUNT_ID / _CLIENT_ID /
+ * _CLIENT_SECRET (secret optional for a PKCE public client) and optional
+ * PUBLIC_APP_URL. Same var names everywhere, different source per environment:
+ * in DEV (Fly preview) the app reads them from the project .env; in PROD they
+ * are HelloLeo Cloud secrets on the published Worker (the publish step promotes
+ * them from .env). Never in code; they never reach the browser.
+ *
+ * The redirect URI is derived at runtime from the request origin
+ * (`${origin}/auth/netsuite/callback`), so the SAME code works at the Fly
+ * preview URL and the published prod URL — register BOTH on Integration
+ * Record #2 (NetSuite allows multiple redirect URIs).
+ *
+ * Call AFTER `scaffold`, never instead of it.
  */
 
-function netsuiteTs(): string {
+// --- emitted: src/db/schema.ts (appended) --------------------------------
+function schemaAppend(): string {
+	return `
+// --- NetSuite OAuth (added by setup_netsuite) ---
+// Short-lived PKCE + return-to state between /auth/netsuite/start and its
+// callback. Single-use: the callback deletes the row after reading it.
+export const netsuiteFlows = sqliteTable('netsuite_flows', {
+  flowId: text('flow_id').primaryKey(),
+  codeVerifier: text('code_verifier').notNull(),
+  returnTo: text('return_to').notNull(),
+  createdAt: integer('created_at')
+    .notNull()
+    .default(sql\`(unixepoch())\`),
+})
+
+// Opaque session id -> NetSuite tokens. Tokens stay server-side; the browser
+// only ever holds the sid (sent as a bearer).
+export const netsuiteSessions = sqliteTable('netsuite_sessions', {
+  sid: text('sid').primaryKey(),
+  accountId: text('account_id').notNull(),
+  accessToken: text('access_token').notNull(),
+  refreshToken: text('refresh_token'),
+  expiresAt: integer('expires_at'),
+  userId: text('user_id'),
+  email: text('email'),
+  createdAt: integer('created_at')
+    .notNull()
+    .default(sql\`(unixepoch())\`),
+})
+`;
+}
+
+// --- emitted: src/lib/netsuite-server.ts ---------------------------------
+function netsuiteServerTs(): string {
 	return `/*
- * NetSuite OAuth client helper (bearer-token-in-fragment).
- *
- * Two NetSuite Integration Records back this:
- *   1. MCP (scope: mcp)            -- used by HelloLeo at build time.
- *   2. Runtime (scope: rest_webservices) -- used here at sign-in time.
- * Runtime credentials live as HelloLeo Cloud secrets on the project's Worker
- * (env.NETSUITE_ACCOUNT_ID / _CLIENT_ID / _CLIENT_SECRET). They never reach
- * the browser. Cookies are NOT used -- frontend ↔ Worker are cross-site
- * (e.g. *.helloleo.dev <-> *.workers.dev) and Chrome partitions / drops
- * third-party cookies in the HelloLeo preview iframe.
+ * NetSuite runtime OAuth -- server side (TanStack Start server routes).
  *
- * Flow:
- *   1. User clicks "Sign in with NetSuite".
- *   2. Browser navigates to the Worker /auth/netsuite/start.
- *   3. Worker redirects to NetSuite's OAuth UI with PKCE.
- *   4. NetSuite redirects back to the Worker /auth/netsuite/callback.
- *   5. Worker exchanges the code, mints a session id, then redirects to
- *      <return_to>#nssid=<sid>. URL fragments stay in the browser only.
- *   6. This module reads the fragment on load, stashes the sid in
- *      sessionStorage, and sends it as Authorization: Bearer on every
- *      Worker call.
+ * Runs wherever the app runs: \`vite dev\` (workerd) in the Fly preview machine
+ * in dev, and the published Cloudflare Worker in prod. There is no separate
+ * backend Worker -- these helpers back the /auth/netsuite/* + /api/me routes.
  *
- * NEVER use a hardcoded password gate. NEVER use sessionStorage as the
- * authoritative auth state -- the only acceptable check is /api/me on the
- * Worker. sessionStorage here is just a cache of the bearer token.
+ * Config is read from the Cloudflare env binding via @helloleo/runtime.
+ * Set NETSUITE_ACCOUNT_ID / _CLIENT_ID / _CLIENT_SECRET (secret optional for a
+ * PKCE public client) and optional PUBLIC_APP_URL as HelloLeo Cloud secrets
+ * (prod) or dev vars (preview). They never reach the browser.
+ */
+import { eq } from 'drizzle-orm'
+import { env as runtimeEnv } from '@helloleo/runtime'
+import { db } from '#/db'
+import { netsuiteSessions } from '#/db/schema'
+
+interface NsEnv {
+  NETSUITE_ACCOUNT_ID?: string
+  NETSUITE_CLIENT_ID?: string
+  NETSUITE_CLIENT_SECRET?: string
+  PUBLIC_APP_URL?: string
+  HELLOLEO_URL?: string
+}
+const nsEnv = runtimeEnv as unknown as NsEnv
+
+// Runtime record scope. The app signs end-users in for REST/SuiteQL.
+export const SCOPE = 'rest_webservices'
+const REFRESH_LEEWAY_SECONDS = 60
+
+export function requireConfig() {
+  const accountId = nsEnv.NETSUITE_ACCOUNT_ID
+  const clientId = nsEnv.NETSUITE_CLIENT_ID
+  if (!accountId || !clientId) {
+    throw new Error(
+      'NetSuite not configured: set NETSUITE_ACCOUNT_ID and NETSUITE_CLIENT_ID (and NETSUITE_CLIENT_SECRET for a confidential client) as HelloLeo Cloud secrets / dev vars.',
+    )
+  }
+  return { accountId, clientId, clientSecret: nsEnv.NETSUITE_CLIENT_SECRET || '' }
+}
+
+// Account id -> DNS host form: lowercase, underscores to hyphens.
+function host(accountId: string) {
+  return accountId.trim().toLowerCase().replace(/_/g, '-')
+}
+export function authorizeUrl(accountId: string) {
+  return \`https://\${host(accountId)}.app.netsuite.com/app/login/oauth2/authorize.nl\`
+}
+export function tokenUrl(accountId: string) {
+  return \`https://\${host(accountId)}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token\`
+}
+export function restBase(accountId: string) {
+  return \`https://\${host(accountId)}.suitetalk.api.netsuite.com\`
+}
+
+function stripTrailingSlash(s: string) {
+  return s.endsWith('/') ? s.slice(0, -1) : s
+}
+
+// Public origin of THIS app, used to build the redirect URI. Prefer an explicit
+// PUBLIC_APP_URL; else derive from the request (honouring the preview proxy's
+// forwarded headers). Must match a redirect URI registered on the NetSuite
+// Integration Record exactly.
+export function appOrigin(request: Request) {
+  // 1) Explicit override wins (set by the platform per environment).
+  if (nsEnv.PUBLIC_APP_URL) return stripTrailingSlash(nsEnv.PUBLIC_APP_URL)
+  // 2) HELLOLEO_URL is injected on every deploy (the app's canonical origin), so
+  //    it's set even when the NetSuite wizard's PUBLIC_APP_URL pin wasn't.
+  if (nsEnv.HELLOLEO_URL) return stripTrailingSlash(nsEnv.HELLOLEO_URL)
+  // 3) Preview/prod proxies rewrite Host, so trust the forwarded/original host
+  //    they set (HelloLeo's nginx sends X-Original-Host) — that's the public URL
+  //    the browser loaded, not an internal upstream host.
+  const url = new URL(request.url)
+  const proto = request.headers.get('x-forwarded-proto') || url.protocol.replace(':', '')
+  const hostHeader =
+    request.headers.get('x-forwarded-host') ||
+    request.headers.get('x-original-host') ||
+    url.host
+  return \`\${proto}://\${hostHeader}\`
+}
+export function redirectUri(request: Request) {
+  return \`\${appOrigin(request)}/auth/netsuite/callback\`
+}
+
+// Coerce ?return_to= to our OWN origin. The callback appends the session bearer
+// as a #nssid=... fragment; an off-origin return_to would leak that live
+// credential to an attacker-controlled page (open-redirect -> token theft).
+export function safeReturnTo(request: Request, raw: string | null): string {
+  const origin = appOrigin(request)
+  if (!raw) return origin
+  try {
+    const u = new URL(raw, origin)
+    return u.origin === origin ? u.toString() : origin
+  } catch {
+    return origin
+  }
+}
+
+// --- PKCE (Web Crypto: works on workerd and Node) ---
+function b64url(bytes: Uint8Array) {
+  let s = ''
+  for (const b of bytes) s += String.fromCharCode(b)
+  return btoa(s).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '')
+}
+export async function pkce() {
+  const verifier = b64url(crypto.getRandomValues(new Uint8Array(48)))
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
+  const challenge = b64url(new Uint8Array(digest))
+  return { verifier, challenge }
+}
+
+interface TokenResponse {
+  access_token?: string
+  refresh_token?: string
+  expires_in?: number
+  error?: string
+  error_description?: string
+}
+
+// Confidential client -> HTTP Basic. Public (PKCE-only) -> client_id in body.
+function authHeaders(clientId: string, clientSecret: string, params: Record<string, string>) {
+  const headers: Record<string, string> = { 'Content-Type': 'application/x-www-form-urlencoded' }
+  if (clientSecret) headers.Authorization = 'Basic ' + btoa(\`\${clientId}:\${clientSecret}\`)
+  else params.client_id = clientId
+  return headers
+}
+
+// POST the token endpoint and parse tolerantly. NetSuite returns JSON for both
+// success and OAuth errors, but a gateway (502/504) can return HTML -- never let
+// res.json() throw into the route handler (that would surface as an opaque 500
+// instead of a clean "token exchange failed").
+async function postToken(
+  accountId: string,
+  params: Record<string, string>,
+  headers: Record<string, string>,
+): Promise<TokenResponse> {
+  let res: Response
+  try {
+    res = await fetch(tokenUrl(accountId), { method: 'POST', headers, body: new URLSearchParams(params) })
+  } catch (e) {
+    return { error: 'network_error', error_description: String(e) }
+  }
+  const text = await res.text()
+  let data: TokenResponse = {}
+  try {
+    data = JSON.parse(text) as TokenResponse
+  } catch {
+    // non-JSON body (e.g. gateway HTML) -- leave data empty, fall through
+  }
+  if (!res.ok && !data.error) {
+    data = { error: 'token_request_failed', error_description: 'HTTP ' + res.status }
+  }
+  return data
+}
+
+export async function exchangeCode(request: Request, code: string, verifier: string) {
+  const { accountId, clientId, clientSecret } = requireConfig()
+  const params: Record<string, string> = {
+    grant_type: 'authorization_code',
+    code,
+    redirect_uri: redirectUri(request),
+    code_verifier: verifier,
+  }
+  return postToken(accountId, params, authHeaders(clientId, clientSecret, params))
+}
+
+async function refreshToken(refresh: string) {
+  const { accountId, clientId, clientSecret } = requireConfig()
+  const params: Record<string, string> = { grant_type: 'refresh_token', refresh_token: refresh }
+  return postToken(accountId, params, authHeaders(clientId, clientSecret, params))
+}
+
+export interface NsSession {
+  sid: string
+  accountId: string
+  accessToken: string
+  refreshToken: string | null
+  expiresAt: number | null
+  userId: string | null
+  email: string | null
+}
+
+// Load a session by sid, transparently refreshing the access token when it's
+// within the leeway of expiry. Returns null if unknown or unrefreshable.
+export async function getSession(sid: string): Promise<NsSession | null> {
+  if (!sid) return null
+  const rows = await db.select().from(netsuiteSessions).where(eq(netsuiteSessions.sid, sid)).limit(1)
+  const s = rows[0]
+  if (!s) return null
+  const now = Math.floor(Date.now() / 1000)
+  // A missing expiry is treated as EXPIRED (force a refresh) rather than trusting
+  // the token forever -- NetSuite normally sends expires_in, so this is defensive.
+  const expired = s.expiresAt == null ? true : now + REFRESH_LEEWAY_SECONDS >= s.expiresAt
+  if (expired) {
+    // Token expired (or about to). It MUST refresh; if it can't, the session is
+    // dead — delete it and return null so /api/me reports signed-out and the user
+    // re-auths, rather than a "logged in" app whose every NetSuite call 401s.
+    if (!s.refreshToken) { await deleteSession(sid); return null }
+    const tok = await refreshToken(s.refreshToken)
+    if (!tok.access_token) { await deleteSession(sid); return null }
+    const expiresAt = now + (tok.expires_in || 3600)
+    const refreshTok = tok.refresh_token ?? s.refreshToken
+    await db
+      .update(netsuiteSessions)
+      .set({ accessToken: tok.access_token, refreshToken: refreshTok, expiresAt })
+      .where(eq(netsuiteSessions.sid, sid))
+    return { ...s, accessToken: tok.access_token, refreshToken: refreshTok, expiresAt }
+  }
+  return s
+}
+
+export async function deleteSession(sid: string) {
+  if (sid) await db.delete(netsuiteSessions).where(eq(netsuiteSessions.sid, sid))
+}
+
+export function bearer(request: Request) {
+  const h = request.headers.get('authorization') || ''
+  return h.startsWith('Bearer ') ? h.slice(7) : ''
+}
+
+/**
+ * Call NetSuite REST / SuiteQL for the signed-in session. Use this from your
+ * data routes (src/routes/api/*). \`path\` is relative to the account's
+ * suitetalk host, e.g. '/services/rest/query/v1/suiteql'. Returns the raw
+ * fetch Response (401 if the sid is unknown). Access token is auto-refreshed.
  */
+export async function netsuiteFetch(sid: string, path: string, init: RequestInit = {}): Promise<Response> {
+  const session = await getSession(sid)
+  if (!session) return new Response(JSON.stringify({ error: 'unauthorized' }), { status: 401 })
+  const url = path.startsWith('http') ? path : \`\${restBase(session.accountId)}\${path}\`
+  const headers = new Headers(init.headers)
+  headers.set('Authorization', \`Bearer \${session.accessToken}\`)
+  if (init.body && !headers.has('Content-Type')) headers.set('Content-Type', 'application/json')
+  return fetch(url, { ...init, headers })
+}
+`;
+}
+
+// --- emitted: src/routes/auth/netsuite/start.ts --------------------------
+function startRouteTs(): string {
+	return `import { createFileRoute } from '@tanstack/react-router'
+import { db } from '#/db'
+import { netsuiteFlows } from '#/db/schema'
+import {
+  authorizeUrl,
+  pkce,
+  redirectUri,
+  requireConfig,
+  safeReturnTo,
+  SCOPE,
+} from '#/lib/netsuite-server'
+
+// GET /auth/netsuite/start -- begin the NetSuite OAuth (PKCE) flow.
+export const Route = createFileRoute('/auth/netsuite/start')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const { accountId, clientId } = requireConfig()
+        const url = new URL(request.url)
+        // Same-origin only: the callback returns the bearer in a URL fragment.
+        const returnTo = safeReturnTo(request, url.searchParams.get('return_to'))
+
+        const { verifier, challenge } = await pkce()
+        const flowId = crypto.randomUUID()
+        await db.insert(netsuiteFlows).values({ flowId, codeVerifier: verifier, returnTo })
+
+        const authorize = new URL(authorizeUrl(accountId))
+        authorize.searchParams.set('response_type', 'code')
+        authorize.searchParams.set('client_id', clientId)
+        authorize.searchParams.set('redirect_uri', redirectUri(request))
+        authorize.searchParams.set('scope', SCOPE)
+        authorize.searchParams.set('state', flowId)
+        authorize.searchParams.set('code_challenge', challenge)
+        authorize.searchParams.set('code_challenge_method', 'S256')
+
+        return new Response(null, { status: 302, headers: { Location: authorize.toString() } })
+      },
+    },
+  },
+})
+`;
+}
+
+// --- emitted: src/routes/auth/netsuite/callback.ts -----------------------
+function callbackRouteTs(): string {
+	return `import { createFileRoute } from '@tanstack/react-router'
+import { eq } from 'drizzle-orm'
+import { db } from '#/db'
+import { netsuiteFlows, netsuiteSessions } from '#/db/schema'
+import { exchangeCode, requireConfig } from '#/lib/netsuite-server'
+
+// GET /auth/netsuite/callback -- exchange the code, mint a session, hand the
+// bearer back to the SPA via the URL fragment (#nssid=...). The fragment
+// survives the HelloLeo preview iframe, where third-party cookies are dropped.
+export const Route = createFileRoute('/auth/netsuite/callback')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const url = new URL(request.url)
+        const err = url.searchParams.get('error')
+        if (err) return new Response(\`NetSuite authorization failed: \${err}\`, { status: 400 })
+
+        const code = url.searchParams.get('code')
+        const state = url.searchParams.get('state')
+        if (!code || !state) return new Response('Missing code or state', { status: 400 })
+
+        const rows = await db
+          .select()
+          .from(netsuiteFlows)
+          .where(eq(netsuiteFlows.flowId, state))
+          .limit(1)
+        const flow = rows[0]
+        if (!flow) return new Response('Unknown or expired flow -- start again', { status: 400 })
+        // Single-use: burn the flow row immediately.
+        await db.delete(netsuiteFlows).where(eq(netsuiteFlows.flowId, state))
+        // Reject stale flows: the PKCE verifier must not stay valid indefinitely
+        // for an abandoned or leaked authorize URL (createdAt is unixepoch seconds).
+        const nowSec = Math.floor(Date.now() / 1000)
+        if (flow.createdAt && nowSec - flow.createdAt > 600) {
+          return new Response('Flow expired -- start again', { status: 400 })
+        }
+
+        const tok = await exchangeCode(request, code, flow.codeVerifier)
+        if (!tok.access_token) {
+          return new Response(
+            \`Token exchange failed: \${tok.error_description || tok.error || 'unknown error'}\`,
+            { status: 400 },
+          )
+        }
+
+        const sid = crypto.randomUUID()
+        const now = Math.floor(Date.now() / 1000)
+        await db.insert(netsuiteSessions).values({
+          sid,
+          accountId: requireConfig().accountId,
+          accessToken: tok.access_token,
+          refreshToken: tok.refresh_token ?? null,
+          expiresAt: now + (tok.expires_in || 3600),
+        })
+
+        const dest = new URL(flow.returnTo)
+        dest.hash = \`nssid=\${sid}\`
+        return new Response(null, { status: 302, headers: { Location: dest.toString() } })
+      },
+    },
+  },
+})
+`;
+}
 
-export const WORKER_URL = import.meta.env.VITE_WORKER_URL ?? '';
-const TOKEN_KEY = 'nssid';
-
-// Capture-and-strip the #nssid=... fragment as early as possible so URLs
-// shown to the user stay clean. Runs once at module load.
-(function bootstrapTokenFromHash() {
-  if (typeof window === 'undefined') return;
-  const hash = window.location.hash.replace(/^#/, '');
-  if (!hash) return;
-  const params = new URLSearchParams(hash);
-  const sid = params.get(TOKEN_KEY);
+// --- emitted: src/routes/auth/netsuite/logout.ts -------------------------
+function logoutRouteTs(): string {
+	return `import { createFileRoute } from '@tanstack/react-router'
+import { bearer, deleteSession } from '#/lib/netsuite-server'
+
+// POST /auth/netsuite/logout -- destroy the current session.
+export const Route = createFileRoute('/auth/netsuite/logout')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        await deleteSession(bearer(request))
+        return Response.json({ ok: true })
+      },
+    },
+  },
+})
+`;
+}
+
+// --- emitted: src/routes/api/me.ts ---------------------------------------
+function meRouteTs(): string {
+	return `import { createFileRoute } from '@tanstack/react-router'
+import { bearer, getSession } from '#/lib/netsuite-server'
+
+// GET /api/me -- resolve the bearer sid to a session. The ONLY authoritative
+// auth check; the client must never trust sessionStorage on its own.
+export const Route = createFileRoute('/api/me')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const session = await getSession(bearer(request))
+        if (!session) return Response.json({ authenticated: false })
+        return Response.json({
+          authenticated: true,
+          account_id: session.accountId,
+        })
+      },
+    },
+  },
+})
+`;
+}
+
+// --- emitted: src/routes/auth/netsuite/config.ts -------------------------
+function configRouteTs(): string {
+	return `import { createFileRoute } from '@tanstack/react-router'
+import { env as runtimeEnv } from '@helloleo/runtime'
+import { appOrigin, redirectUri } from '#/lib/netsuite-server'
+
+// GET /auth/netsuite/config -- single source of truth for the redirect URI.
+// Whatever this returns is EXACTLY what /auth/netsuite/start sends NetSuite, so
+// show the user THIS value to register on their Integration Record. Never
+// hardcode or guess a callback URL.
+export const Route = createFileRoute('/auth/netsuite/config')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const e = runtimeEnv as unknown as {
+          NETSUITE_ACCOUNT_ID?: string
+          NETSUITE_CLIENT_ID?: string
+        }
+        return Response.json({
+          redirect_uri: redirectUri(request),
+          origin: appOrigin(request),
+          configured: Boolean(e.NETSUITE_ACCOUNT_ID && e.NETSUITE_CLIENT_ID),
+        })
+      },
+    },
+  },
+})
+`;
+}
+
+// --- emitted: src/lib/netsuite.ts (client) -------------------------------
+function netsuiteClientTs(): string {
+	return `/*
+ * NetSuite auth -- client (same-origin). The OAuth backend is THIS app's own
+ * server routes (src/routes/auth/netsuite/* + src/routes/api/me.ts), so every
+ * call is relative -- no separate Worker, no VITE_WORKER_URL.
+ *
+ * The browser only ever holds an opaque session id (sid), handed back in the
+ * callback's URL fragment (#nssid=...) so it survives the HelloLeo preview
+ * iframe (third-party cookies are partitioned/dropped there). The sid rides as
+ * Authorization: Bearer on every call; NetSuite tokens stay server-side. The
+ * only authoritative auth check is GET /api/me.
+ *
+ * NEVER use a password gate. NEVER trust sessionStorage as the auth state --
+ * it's just a cache of the bearer.
+ */
+const TOKEN_KEY = 'nssid'
+
+// Capture-and-strip #nssid=... as early as possible so URLs stay clean.
+;(function bootstrapTokenFromHash() {
+  if (typeof window === 'undefined') return
+  const hash = window.location.hash.replace(/^#/, '')
+  if (!hash) return
+  const params = new URLSearchParams(hash)
+  const sid = params.get(TOKEN_KEY)
   if (sid) {
-    try { sessionStorage.setItem(TOKEN_KEY, sid); } catch {}
-    params.delete(TOKEN_KEY);
-    const remaining = params.toString();
-    const newHash = remaining ? '#' + remaining : '';
-    window.history.replaceState(null, '', window.location.pathname + window.location.search + newHash);
+    try {
+      sessionStorage.setItem(TOKEN_KEY, sid)
+    } catch {}
+    params.delete(TOKEN_KEY)
+    const rest = params.toString()
+    window.history.replaceState(
+      null,
+      '',
+      window.location.pathname + window.location.search + (rest ? '#' + rest : ''),
+    )
   }
-})();
+})()
 
 export function getSessionToken(): string | null {
-  try { return sessionStorage.getItem(TOKEN_KEY); } catch { return null; }
+  try {
+    return sessionStorage.getItem(TOKEN_KEY)
+  } catch {
+    return null
+  }
 }
 
 export function signInWithNetSuite(returnTo: string = window.location.href) {
-  if (!WORKER_URL) {
-    throw new Error(
-      'VITE_WORKER_URL is not set. HelloLeo Cloud must be provisioned before sign-in works.',
-    );
-  }
-  const url = new URL(\`\${WORKER_URL.replace(/\\/$/, '')}/auth/netsuite/start\`);
-  url.searchParams.set('return_to', returnTo);
-  // The app usually renders inside the HelloLeo preview iframe. NetSuite's
-  // OAuth page sets X-Frame-Options: DENY, so navigating the iframe to the
-  // Worker (which 302s to NetSuite) ends up loading a page the browser
-  // refuses to render -- looks like "nothing happens" to the user. Navigate
-  // the top frame instead so the OAuth flow runs at the top level and the
-  // callback redirect lands on the same top frame, which then reads the
-  // #nssid= fragment. Use \`location.href =\` (NOT \`location.assign()\`):
-  // reading the \`.assign\` method off a cross-origin \`window.top.location\`
-  // throws a SecurityError, which would drop us into the same-frame fallback
-  // and load NetSuite inside the iframe (X-Frame-Options: DENY -> "refused to
-  // connect"). Assigning \`.href\` is a navigation, allowed cross-origin.
+  const url = new URL('/auth/netsuite/start', window.location.origin)
+  url.searchParams.set('return_to', returnTo)
+  // The app renders inside the HelloLeo preview iframe; /start 302s to
+  // NetSuite, whose OAuth page sends X-Frame-Options: DENY. Navigate the TOP
+  // frame so the flow runs at top level and the callback lands there to read
+  // #nssid=. Assign .href (NOT .assign(): reading .assign off a cross-origin
+  // window.top.location throws, dropping us into the iframe fallback ->
+  // "refused to connect").
   try {
     if (window.top && window.top !== window) {
-      window.top.location.href = url.toString();
-      return;
+      window.top.location.href = url.toString()
+      return
     }
   } catch {
-    /* top window not accessible — fall through to same-frame navigation */
+    /* top window unreachable -- fall through to same-frame navigation */
   }
-  window.location.href = url.toString();
+  window.location.href = url.toString()
 }
 
 export interface NetSuiteSession {
-  authenticated: boolean;
-  account_id?: string;
-  user_id?: string;
-  email?: string;
+  authenticated: boolean
+  account_id?: string
 }
 
 export async function getNetSuiteSession(): Promise<NetSuiteSession> {
-  if (!WORKER_URL) return { authenticated: false };
-  const sid = getSessionToken();
-  if (!sid) return { authenticated: false };
-  const res = await fetch(\`\${WORKER_URL.replace(/\\/$/, '')}/api/me\`, {
-    headers: { Authorization: 'Bearer ' + sid },
-  });
-  if (!res.ok) return { authenticated: false };
-  const data = await res.json();
-  return { authenticated: Boolean(data?.account_id), ...data };
+  const sid = getSessionToken()
+  if (!sid) return { authenticated: false }
+  const res = await fetch('/api/me', { headers: { Authorization: 'Bearer ' + sid } })
+  if (!res.ok) return { authenticated: false }
+  const data = await res.json()
+  return { authenticated: Boolean(data?.authenticated), ...data }
 }
 
 export async function signOutNetSuite(): Promise<void> {
-  if (!WORKER_URL) return;
-  const sid = getSessionToken();
+  const sid = getSessionToken()
   if (sid) {
     try {
-      await fetch(\`\${WORKER_URL.replace(/\\/$/, '')}/auth/netsuite/logout\`, {
+      await fetch('/auth/netsuite/logout', {
         method: 'POST',
         headers: { Authorization: 'Bearer ' + sid },
-      });
+      })
     } catch {}
   }
-  try { sessionStorage.removeItem(TOKEN_KEY); } catch {}
-  window.location.reload();
+  try {
+    sessionStorage.removeItem(TOKEN_KEY)
+  } catch {}
+  window.location.reload()
 }
 
 /**
- * Helper for ALL other Worker calls (your dashboard endpoints, etc.).
- * Always go through this instead of bare fetch -- it injects the bearer
- * token and routes through the Worker so NetSuite tokens stay server-side.
+ * Fetch YOUR data routes (src/routes/api/*) with the bearer attached. Use this
+ * instead of bare fetch for authenticated calls.
  */
-export async function workerFetch(pathOrUrl: string, init: RequestInit = {}): Promise<Response> {
-  if (!WORKER_URL) throw new Error('VITE_WORKER_URL is not set');
-  const url = pathOrUrl.startsWith('http')
-    ? pathOrUrl
-    : \`\${WORKER_URL.replace(/\\/$/, '')}\${pathOrUrl.startsWith('/') ? '' : '/'}\${pathOrUrl}\`;
-  const sid = getSessionToken();
-  const headers = new Headers(init.headers ?? {});
-  if (sid) headers.set('Authorization', 'Bearer ' + sid);
-  return fetch(url, { ...init, headers });
-}
-`;
+export async function apiFetch(path: string, init: RequestInit = {}): Promise<Response> {
+  const sid = getSessionToken()
+  const headers = new Headers(init.headers)
+  if (sid) headers.set('Authorization', 'Bearer ' + sid)
+  return fetch(path, { ...init, headers })
 }
 
-function signInButtonTsx(): string {
-	return `import { signInWithNetSuite } from '../../lib/netsuite';
-
-export function SignInWithNetSuite() {
-  return (
-    <button
-      onClick={() => signInWithNetSuite()}
-      className="inline-flex items-center justify-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground shadow hover:bg-primary/90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-    >
-      Sign in with NetSuite
-    </button>
-  );
-}
-`;
-}
-
-function netsuiteLoginPageTsx(): string {
-	return `import { SignInWithNetSuite } from './SignInWithNetSuite';
-
 /**
- * Default unauthenticated landing page. Replaces any password gate.
- * Customise copy / imagery freely but keep <SignInWithNetSuite /> as the
- * only call-to-action -- it points to the Worker's /auth/netsuite/start.
+ * The exact redirect URI this app will send NetSuite, read from the server so
+ * it can never drift from what /auth/netsuite/start actually uses. Show it to
+ * whoever registers the Integration Record; never hardcode a callback URL.
  */
-export function LoginPage() {
-  return (
-    <div className="min-h-screen bg-background text-foreground flex">
-      <div className="hidden lg:flex lg:w-1/2 bg-primary text-primary-foreground p-12 flex-col justify-between">
-        <div className="text-xl font-semibold">NetSuite App</div>
-        <div>
-          <h1 className="text-4xl font-bold leading-tight">
-            Connect your NetSuite account
-          </h1>
-          <p className="mt-4 text-primary-foreground/80 max-w-md">
-            Sign in with your NetSuite credentials to access your data securely.
-            Tokens stay server-side on HelloLeo Cloud -- they never reach the
-            browser.
-          </p>
-        </div>
-        <div className="text-xs text-primary-foreground/60">
-          Powered by HelloLeo
-        </div>
-      </div>
-      <div className="flex-1 flex items-center justify-center px-6 py-12">
-        <div className="w-full max-w-sm space-y-6">
-          <div>
-            <h2 className="text-2xl font-semibold">Welcome</h2>
-            <p className="mt-2 text-sm text-muted-foreground">
-              Use the button below to sign in. You'll be redirected to NetSuite
-              to authorise access, then back here.
-            </p>
-          </div>
-          <SignInWithNetSuite />
-        </div>
-      </div>
-    </div>
-  );
+export async function getNetSuiteRedirectUri(): Promise<string | null> {
+  try {
+    const res = await fetch('/auth/netsuite/config')
+    if (!res.ok) return null
+    const data = await res.json()
+    return data?.redirect_uri ?? null
+  } catch {
+    return null
+  }
 }
 `;
 }
 
+// --- emitted: src/lib/auth.tsx (client) ----------------------------------
 function authTsx(): string {
-	return `import * as React from 'react';
+	return `import * as React from 'react'
 import {
   getNetSuiteSession,
   signInWithNetSuite,
   signOutNetSuite,
   type NetSuiteSession,
-} from './netsuite';
+} from './netsuite'
 
 /**
- * NetSuite auth context. Holds the current session (resolved from the Worker's
- * /api/me via getNetSuiteSession) and exposes sign-in / sign-out. The only
- * authoritative auth check is /api/me -- never trust sessionStorage directly.
+ * NetSuite auth context. Holds the session (resolved client-side from /api/me
+ * via getNetSuiteSession) and exposes sign-in / sign-out. /api/me is the only
+ * authoritative check -- never trust sessionStorage directly.
  */
 export interface NetSuiteAuthContextValue {
-  pending: boolean;
-  isAuthenticated: boolean;
-  session: NetSuiteSession | null;
-  signIn: () => void;
-  signOut: () => Promise<void>;
-  refresh: () => Promise<void>;
+  pending: boolean
+  isAuthenticated: boolean
+  session: NetSuiteSession | null
+  signIn: () => void
+  signOut: () => Promise<void>
+  refresh: () => Promise<void>
 }
 
-const NetSuiteAuthContext =
-  React.createContext<NetSuiteAuthContextValue | null>(null);
+const NetSuiteAuthContext = React.createContext<NetSuiteAuthContextValue | null>(null)
 
-export function NetSuiteAuthProvider({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  const [session, setSession] = React.useState<NetSuiteSession | null>(null);
-  const [pending, setPending] = React.useState(true);
+export function NetSuiteAuthProvider({ children }: { children: React.ReactNode }) {
+  const [session, setSession] = React.useState<NetSuiteSession | null>(null)
+  // Start pending on BOTH server and client render so SSR and first paint match
+  // (a spinner), avoiding a hydration mismatch. The effect (client-only)
+  // resolves it.
+  const [pending, setPending] = React.useState(true)
 
   const refresh = React.useCallback(async () => {
-    setPending(true);
+    setPending(true)
     try {
-      setSession(await getNetSuiteSession());
+      setSession(await getNetSuiteSession())
     } finally {
-      setPending(false);
+      setPending(false)
     }
-  }, []);
+  }, [])
 
   React.useEffect(() => {
-    refresh();
-  }, [refresh]);
+    refresh()
+  }, [refresh])
 
   const value: NetSuiteAuthContextValue = {
     pending,
@@ -265,137 +678,255 @@ export function NetSuiteAuthProvider({
     signIn: () => signInWithNetSuite(),
     signOut: signOutNetSuite,
     refresh,
-  };
+  }
 
-  return (
-    <NetSuiteAuthContext.Provider value={value}>
-      {children}
-    </NetSuiteAuthContext.Provider>
-  );
+  return <NetSuiteAuthContext.Provider value={value}>{children}</NetSuiteAuthContext.Provider>
 }
 
 export function useNetSuiteAuth(): NetSuiteAuthContextValue {
-  const ctx = React.useContext(NetSuiteAuthContext);
+  const ctx = React.useContext(NetSuiteAuthContext)
   if (!ctx) {
-    throw new Error('useNetSuiteAuth must be used within <NetSuiteAuthProvider>');
+    throw new Error('useNetSuiteAuth must be used within <NetSuiteAuthProvider>')
   }
-  return ctx;
+  return ctx
 }
 `;
 }
 
+// --- emitted: src/components/auth/AuthLayout.tsx --------------------------
 function authLayoutTsx(): string {
-	return `import type { ReactNode } from 'react';
-import { NetSuiteAuthProvider, useNetSuiteAuth } from '../../lib/auth';
-import { LoginPage } from './LoginPage';
+	return `import type { ReactNode } from 'react'
+import { NetSuiteAuthProvider, useNetSuiteAuth } from '../../lib/auth'
+import { LoginPage } from './LoginPage'
 
 /**
- * NetSuite auth layout. This is the ONLY wiring you need to add by hand --
- * wrap the root route's <Outlet /> with it:
+ * NetSuite auth layout. The ONE manual wiring step: wrap the root route's
+ * <Outlet /> with it in src/routes/__root.tsx:
  *
- *   // src/routes/__root.tsx
- *   import { AuthLayout } from '../components/auth/AuthLayout';
+ *   import { AuthLayout } from '../components/auth/AuthLayout'
  *   ...
  *   function RootComponent() {
  *     return (
- *       <>
+ *       <RootDocument>
  *         <AuthLayout>
  *           <Outlet />
  *         </AuthLayout>
- *         { ...devtools... }
- *       </>
- *     );
+ *       </RootDocument>
+ *     )
  *   }
  *
- * It provides NetSuite auth context to the whole tree and gates rendering:
- * while the session resolves it shows a spinner, unauthenticated users see
- * <LoginPage />, authenticated users see your routes. Use useNetSuiteAuth()
- * anywhere below it to read the session or sign out. NEVER swap this for a
- * password gate -- real OAuth is the only supported login.
+ * It provides auth context and gates rendering: a spinner while the session
+ * resolves, <LoginPage /> for signed-out users, your routes once signed in.
+ * NEVER swap this for a password gate -- real OAuth is the only login.
  */
 export function AuthLayout({ children }: { children: ReactNode }) {
   return (
     <NetSuiteAuthProvider>
       <Gate>{children}</Gate>
     </NetSuiteAuthProvider>
-  );
+  )
 }
 
 function Gate({ children }: { children: ReactNode }) {
-  const { pending, isAuthenticated } = useNetSuiteAuth();
+  const { pending, isAuthenticated } = useNetSuiteAuth()
 
   if (pending) {
     return (
       <div className="min-h-screen flex items-center justify-center bg-background">
         <div className="h-8 w-8 rounded-full border-2 border-primary border-t-transparent animate-spin" />
       </div>
-    );
+    )
   }
 
-  if (!isAuthenticated) return <LoginPage />;
+  if (!isAuthenticated) return <LoginPage />
 
-  return <>{children}</>;
+  return <>{children}</>
+}
+`;
+}
+
+// --- emitted: src/components/auth/LoginPage.tsx ---------------------------
+function loginPageTsx(): string {
+	return `import { SignInWithNetSuite } from './SignInWithNetSuite'
+
+/**
+ * Default unauthenticated landing page. Replaces any password gate. Customise
+ * the copy / imagery freely but keep <SignInWithNetSuite /> as the only
+ * call-to-action -- it points to /auth/netsuite/start.
+ */
+export function LoginPage() {
+  return (
+    <div className="min-h-screen bg-background text-foreground flex">
+      <div className="hidden lg:flex lg:w-1/2 bg-primary text-primary-foreground p-12 flex-col justify-between">
+        <div className="text-xl font-semibold">NetSuite App</div>
+        <div>
+          <h1 className="text-4xl font-bold leading-tight">Connect your NetSuite account</h1>
+          <p className="mt-4 text-primary-foreground/80 max-w-md">
+            Sign in with your NetSuite credentials to access your data securely. Tokens stay
+            server-side -- they never reach the browser.
+          </p>
+        </div>
+        <div className="text-xs text-primary-foreground/60">Powered by HelloLeo</div>
+      </div>
+      <div className="flex-1 flex items-center justify-center px-6 py-12">
+        <div className="w-full max-w-sm space-y-6">
+          <div>
+            <h2 className="text-2xl font-semibold">Welcome</h2>
+            <p className="mt-2 text-sm text-muted-foreground">
+              Use the button below to sign in. You'll be redirected to NetSuite to authorise
+              access, then back here.
+            </p>
+          </div>
+          <SignInWithNetSuite />
+        </div>
+      </div>
+    </div>
+  )
+}
+`;
+}
+
+// --- emitted: src/components/auth/SignInWithNetSuite.tsx ------------------
+function signInButtonTsx(): string {
+	return `import { signInWithNetSuite } from '../../lib/netsuite'
+
+export function SignInWithNetSuite() {
+  return (
+    <button
+      onClick={() => signInWithNetSuite()}
+      className="inline-flex items-center justify-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground shadow hover:bg-primary/90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      Sign in with NetSuite
+    </button>
+  )
 }
 `;
 }
 
 export const setupNetsuite = tool({
 	description:
-		"Add NetSuite OAuth wiring to an existing project. Call scaffold first, " +
-		"then this. Writes the OAuth client, auth provider and login components. " +
-		"All files are additive, nothing is overwritten. Real OAuth is wired " +
-		"from day one, never replace <AuthLayout> with a password placeholder.",
+		"Add NetSuite runtime OAuth (end-user LOGIN) to a TanStack Start project. " +
+		"Call scaffold first, then this. This login uses NetSuite Integration " +
+		"Record #2 (scope: rest_webservices) -- a SEPARATE record from the MCP one " +
+		"(scope: mcp) that was used only to BUILD the app; do not confuse them. " +
+		"Emits server routes (the OAuth backend lives IN the app -- no separate " +
+		"Worker, no VITE_WORKER_URL), the netsuite_flows + netsuite_sessions " +
+		"drizzle tables, and the same-origin client + auth components. Config " +
+		"(NETSUITE_ACCOUNT_ID/_CLIENT_ID/_CLIENT_SECRET) comes from the project " +
+		".env in dev and HelloLeo Cloud secrets in prod -- same var names, never " +
+		"in code. Real OAuth from day one -- never replace <AuthLayout> with a " +
+		"password placeholder. Setup guide (link the user to it): " +
+		"https://docs.helloleo.dev/integrations/netsuite",
 	args: {},
 	async execute(_args, context) {
 		const dir = context.directory;
 
+		await mkdir(path.join(dir, "src", "lib"), { recursive: true });
 		await mkdir(path.join(dir, "src", "components", "auth"), {
 			recursive: true,
 		});
+		await mkdir(path.join(dir, "src", "routes", "auth", "netsuite"), {
+			recursive: true,
+		});
+		await mkdir(path.join(dir, "src", "routes", "api"), { recursive: true });
+
+		// Append the NetSuite tables to the drizzle schema (single source of
+		// truth: createDb pushes them in dev, migrations carry them to prod).
+		// Idempotent -- skip if already present.
+		const schemaPath = path.join(dir, "src", "db", "schema.ts");
+		let schemaAppended = false;
+		try {
+			const current = await readFile(schemaPath, "utf8");
+			if (!current.includes("netsuite_flows")) {
+				await Bun.write(schemaPath, current + schemaAppend());
+				schemaAppended = true;
+			}
+		} catch {
+			// No base schema.ts -- scaffold wasn't run. Write a minimal one.
+			await Bun.write(
+				schemaPath,
+				`import { sql } from 'drizzle-orm'\nimport { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'\n${schemaAppend()}`,
+			);
+			schemaAppended = true;
+		}
 
-		// All additive -- nothing the base scaffold wrote is touched.
-		const nsFiles: [string, string][] = [
-			[path.join("src", "lib", "netsuite.ts"), netsuiteTs()],
+		const files: [string, string][] = [
+			[path.join("src", "lib", "netsuite-server.ts"), netsuiteServerTs()],
+			[
+				path.join("src", "routes", "auth", "netsuite", "start.ts"),
+				startRouteTs(),
+			],
+			[
+				path.join("src", "routes", "auth", "netsuite", "callback.ts"),
+				callbackRouteTs(),
+			],
+			[
+				path.join("src", "routes", "auth", "netsuite", "logout.ts"),
+				logoutRouteTs(),
+			],
+			[
+				path.join("src", "routes", "auth", "netsuite", "config.ts"),
+				configRouteTs(),
+			],
+			[path.join("src", "routes", "api", "me.ts"), meRouteTs()],
+			[path.join("src", "lib", "netsuite.ts"), netsuiteClientTs()],
 			[path.join("src", "lib", "auth.tsx"), authTsx()],
 			[
 				path.join("src", "components", "auth", "AuthLayout.tsx"),
 				authLayoutTsx(),
 			],
-			[
-				path.join("src", "components", "auth", "LoginPage.tsx"),
-				netsuiteLoginPageTsx(),
-			],
+			[path.join("src", "components", "auth", "LoginPage.tsx"), loginPageTsx()],
 			[
 				path.join("src", "components", "auth", "SignInWithNetSuite.tsx"),
 				signInButtonTsx(),
 			],
 		];
 
-		for (const [filePath, content] of nsFiles) {
+		for (const [filePath, content] of files) {
 			await Bun.write(path.join(dir, filePath), content);
 		}
 
 		return [
-			`Wrote ${nsFiles.length} NetSuite OAuth files (all additive, nothing overwritten):`,
-			"  - src/lib/netsuite.ts (OAuth client: signIn, session, workerFetch)",
-			"  - src/lib/auth.tsx (NetSuiteAuthProvider and useNetSuiteAuth)",
-			"  - src/components/auth/AuthLayout.tsx (provider and auth gate)",
-			"  - src/components/auth/LoginPage.tsx (unauthenticated view)",
-			"  - src/components/auth/SignInWithNetSuite.tsx (sign-in button)",
+			`Wrote ${files.length} NetSuite files${schemaAppended ? " + appended src/db/schema.ts" : ""}:`,
+			"DOCS -- the authoritative setup guide is https://docs.helloleo.dev/integrations/netsuite . When you tell the user what to do in NetSuite, follow and link these steps verbatim; do not invent steps.",
+			"  - Record #2 (runtime): https://docs.helloleo.dev/integrations/netsuite#step-4-%E2%80%94-create-integration-record-2-runtime",
+			"  - Send runtime creds to Leo: https://docs.helloleo.dev/integrations/netsuite#step-5-%E2%80%94-send-the-runtime-credentials-to-leo",
 			"",
-			"Notes:",
-			"- AuthLayout shows LoginPage to signed-out users and renders the app's routes once they sign in with NetSuite.",
-			"- Read the session anywhere with useNetSuiteAuth() from src/lib/auth.tsx.",
-			"- Never replace AuthLayout with a password gate. Real OAuth is the only supported login.",
-			"- The auth worker (deployed via the cloudflare-backend MCP) serves /auth/netsuite/start, /auth/netsuite/callback, /api/me and /auth/netsuite/logout. It reads env.NETSUITE_ACCOUNT_ID, _CLIENT_ID and _CLIENT_SECRET. VITE_WORKER_URL must be set (HelloLeo Cloud seeds it).",
+			"  server (OAuth backend lives in the app -- no separate Worker):",
+			"  - src/lib/netsuite-server.ts (env, PKCE, token exchange, session refresh, netsuiteFetch)",
+			"  - src/routes/auth/netsuite/start.ts    GET  begin PKCE flow",
+			"  - src/routes/auth/netsuite/callback.ts GET  code -> tokens -> session",
+			"  - src/routes/auth/netsuite/logout.ts   POST destroy session",
+			"  - src/routes/auth/netsuite/config.ts   GET  the exact redirect URI to register",
+			"  - src/routes/api/me.ts                 GET  bearer -> session (auth check)",
+			"  - src/db/schema.ts += netsuite_flows + netsuite_sessions",
+			"  client:",
+			"  - src/lib/netsuite.ts (same-origin: signIn, session, apiFetch)",
+			"  - src/lib/auth.tsx (NetSuiteAuthProvider + useNetSuiteAuth)",
+			"  - src/components/auth/{AuthLayout,LoginPage,SignInWithNetSuite}.tsx",
 			"",
-			"Next: in src/routes/__root.tsx, import AuthLayout and wrap <Outlet /> with it. Keep any existing providers.",
+			"WIRE IT UP (one manual step): in src/routes/__root.tsx, wrap <Outlet /> with <AuthLayout>:",
 			"",
 			"    import { AuthLayout } from '../components/auth/AuthLayout'",
 			"",
 			"    <AuthLayout>",
 			"      <Outlet />",
 			"    </AuthLayout>",
+			"",
+			"Then:",
+			"- Build your dashboard inside <AuthLayout>. Read the session with useNetSuiteAuth().",
+			"- Data routes: add src/routes/api/*.ts and call netsuiteFetch(bearer(request), '/services/rest/query/v1/suiteql', {...}) from the handler.",
+			"",
+			"TWO INTEGRATION RECORDS -- do not confuse them:",
+			"- Record #1 (scope: mcp): already connected, used ONLY to build the app (schema discovery). This login does NOT use it.",
+			"- Record #2 (scope: rest_webservices): THIS login uses it -- the end user signs into NetSuite through it, and the redirect URI is registered on THIS record. If it doesn't exist yet, tell the user to create it (a second Integration Record, scope rest_webservices only).",
+			"",
+			"CONFIG -- NETSUITE_ACCOUNT_ID, NETSUITE_CLIENT_ID, NETSUITE_CLIENT_SECRET (secret optional for PKCE public clients). Never hardcode; never put in code. Same var names in every environment, different SOURCE:",
+			"- DEV (Fly preview): read from the project .env. HelloLeo writes them there (the setup wizard, or the env tooling). In dev the app uses .env -- do NOT tell the user to use HelloLeo Cloud here.",
+			"- PROD (published Worker): the SAME names live as HelloLeo Cloud secrets; the publish step promotes them from .env onto the Worker automatically. Same code path (@helloleo/runtime env), just a different source per environment.",
+			"- PUBLIC_APP_URL / HELLOLEO_URL are set by the platform per environment; don't hardcode them.",
+			"- REDIRECT URI -- never guess or hardcode it. It is derived server-side and auto-corrects behind the preview proxy. Read the exact value from GET /auth/netsuite/config (or getNetSuiteRedirectUri() on the client) and tell the user to register THAT on Integration Record #2 (scope: rest_webservices). Register both the preview and published URLs -- NetSuite allows multiple redirect URIs.",
+			"- Never replace <AuthLayout> with a password gate. Real OAuth is the only supported login.",
 		].join("\n");
 	},
 });