@netlify/agent-runner-cli 1.88.0-alpha.1 → 1.89.0

package/dist/skills/netlify-identity/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: netlify-identity
-description: Add user authentication with Netlify Identity. Use when implementing signups, logins, password recovery, role-based access control, OAuth providers, or protecting Netlify Functions with user tokens.
+description: Add user authentication with Netlify Identity. Use when implementing signups, logins, password recovery, role-based access control, OAuth providers, protecting Netlify Functions, or server-side auth in SSR frameworks.
 ---
 
 # Netlify Identity
@@ -8,227 +8,404 @@ description: Add user authentication with Netlify Identity. Use when implementin
 Netlify Identity is a user management service for signups, logins, password recovery, user metadata, and role-based
 access control. It is built on [GoTrue](https://github.com/netlify/gotrue) and issues JSON Web Tokens (JWTs).
 
-There are two integration paths:
+**NEVER use `netlify-identity-widget` or `gotrue-js`. Always use `@netlify/identity`.** It provides a unified, headless
+TypeScript API that works in both browser and server contexts (Netlify Functions, Edge Functions, SSR frameworks). It
+replaces all previous Identity client libraries.
 
-- **Widget** (`netlify-identity-widget`) — Drop-in UI modal for login, signup, and password recovery. Zero framework
-  dependencies. Best when you want auth working quickly without building custom forms.
-- **gotrue-js** — Programmatic client for full control over authentication flows. Best when you need custom UI or
-  headless auth logic.
+## Setup
+
+```bash
+npm install @netlify/identity
+```
+
+Identity is automatically enabled when the deploy includes Identity code. Default settings:
 
-Both communicate with the Identity endpoint at `/.netlify/identity` on your site.
+- **Registration** - Open (anyone can sign up). Change to Invite only in **Project configuration > Identity** if needed.
+- **Autoconfirm** - Off (new signups require email confirmation). Enable in **Project configuration > Identity** to skip
+  confirmation during development.
+
+For local development, use `netlify dev` so the Identity endpoint is available.
 
 ## Quick Start
 
-Add the widget CDN script and a menu element for instant auth:
+Log in from the browser:
+
+```typescript
+import { login, getUser } from '@netlify/identity'
 
-```html
-<script type="text/javascript" src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
-<div data-netlify-identity-menu></div>
+const user = await login('jane@example.com', 'password123')
+console.log(`Hello, ${user.name}`)
+
+// Later, check auth state
+const currentUser = await getUser()
 ```
 
-Handle logins:
+Protect a Netlify Function:
 
-```javascript
-netlifyIdentity.on('login', async (user) => {
-  const jwt = await netlifyIdentity.refresh()
-  await fetch('/.netlify/functions/protected', {
-    headers: { Authorization: `Bearer ${jwt}` },
-  })
-})
+```typescript
+// netlify/functions/protected.mts
+import { getUser } from '@netlify/identity'
+import type { Context } from '@netlify/functions'
+
+export default async (req: Request, context: Context) => {
+  const user = await getUser()
+  if (!user) return new Response('Unauthorized', { status: 401 })
+  return Response.json({ id: user.id, email: user.email })
+}
 ```
 
-### When to Use Widget vs gotrue-js
+## Error Handling
 
-- **Prefer the widget** when the user wants auth working quickly, doesn't have custom UI requirements, or is building a
-  simple site. It requires minimal code and automatically sets the `nf_jwt` cookie needed for role-based redirects.
-- **Use gotrue-js** when the user needs custom login/signup forms, headless auth, or programmatic control over the auth
-  flow. Pass `setCookie: true` if you need role-based redirects (see below).
-- **Never mix both** in the same page unless accessing `netlifyIdentity.gotrue` for low-level operations while using the
-  widget for UI.
+`@netlify/identity` throws two error classes:
 
-## Setup
+- **`AuthError`** - Thrown by auth operations (login, signup, logout, etc.). Has `message`, optional `status` (HTTP
+  status code from GoTrue), and optional `cause` (original error).
+- **`MissingIdentityError`** - Thrown when Identity is not configured in the current environment (site doesn't have
+  Identity enabled, or not running via `netlify dev`).
 
-Identity is automatically enabled when the deploy includes Identity code. Default settings:
+`getUser()` and `isAuthenticated()` never throw - they return `null` and `false` respectively on failure.
 
-- **Registration** — Open (anyone can sign up). Change to Invite only in **Project configuration > Identity** if needed.
-- **Autoconfirm** — Off (new signups require email confirmation). Enable in **Project configuration > Identity** to skip confirmation during development.
+### Try/Catch Pattern
 
-## Widget (Drop-in UI)
+```typescript
+import { login, AuthError, MissingIdentityError } from '@netlify/identity'
+
+try {
+  const user = await login(email, password)
+} catch (error) {
+  if (error instanceof MissingIdentityError) {
+    // Identity not configured - show setup instructions
+    showError('Identity is not enabled on this site.')
+    return
+  }
+  if (error instanceof AuthError) {
+    switch (error.status) {
+      case 401:
+        showError('Invalid email or password.')
+        break
+      case 403:
+        showError('Signups are not allowed for this site.')
+        break
+      case 422:
+        showError('Invalid input. Check your email and password.')
+        break
+      case 404:
+        showError('User not found.')
+        break
+      default:
+        showError(error.message)
+    }
+    return
+  }
+  throw error
+}
+```
 
-### CDN Script Tag
+### Common Status Codes
 
-Include the widget script and add HTML attributes for automatic controls:
+| Status | Meaning |
+|--------|---------|
+| 401 | Invalid credentials or expired token |
+| 403 | Action not allowed (e.g., signups disabled) |
+| 422 | Validation error (e.g., weak password, malformed email) |
+| 404 | User or resource not found |
 
-```html
-<script type="text/javascript" src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
+## Authentication Flows
 
-<!-- Login/Signup menu (shows username + logout when logged in) -->
-<div data-netlify-identity-menu></div>
+### Login
 
-<!-- Simple button that opens the modal -->
-<div data-netlify-identity-button>Login with Netlify Identity</div>
+```typescript
+import { login, AuthError } from '@netlify/identity'
+
+let loading = false
+
+async function handleLogin(email: string, password: string) {
+  loading = true
+  try {
+    const user = await login(email, password)
+    showSuccess(`Welcome back, ${user.name ?? user.email}`)
+  } catch (error) {
+    if (error instanceof AuthError) {
+      showError(error.status === 401 ? 'Invalid email or password.' : error.message)
+    }
+  } finally {
+    loading = false
+  }
+}
 ```
 
-The widget attaches itself to `window.netlifyIdentity` automatically.
+### Signup
 
-### npm Module
+After signup, check `user.emailVerified` to determine if the user was auto-confirmed (logged in immediately) or needs
+to confirm their email first.
 
-```bash
-npm install netlify-identity-widget
+```typescript
+import { signup, AuthError } from '@netlify/identity'
+
+async function handleSignup(email: string, password: string, name: string) {
+  try {
+    const user = await signup(email, password, { full_name: name })
+    if (user.emailVerified) {
+      // Autoconfirm is ON - user is logged in
+      showSuccess('Account created. You are now logged in.')
+    } else {
+      // Autoconfirm is OFF - confirmation email sent, user is NOT logged in
+      showSuccess('Check your email to confirm your account.')
+    }
+  } catch (error) {
+    if (error instanceof AuthError) {
+      showError(error.status === 403 ? 'Signups are not allowed.' : error.message)
+    }
+  }
+}
 ```
 
-```javascript
-import netlifyIdentity from 'netlify-identity-widget'
+When autoconfirm is off, the confirmation email contains a link that redirects the user back to the site with
+`#confirmation_token=<token>` in the URL hash. `handleAuthCallback()` processes this automatically - it calls
+`confirmEmail()` under the hood, logs the user in, and returns `{ type: 'confirmation', user }`. This is why
+`handleAuthCallback()` must be called on page load (see the OAuth section below for the full switch).
 
-netlifyIdentity.init({
-  container: '#netlify-modal', // defaults to document.body
-  locale: 'en',               // language code (en, fr, es, pt, de, etc.)
-  // APIUrl: 'https://your-site.netlify.app/.netlify/identity', // only for non-Netlify hosts
-})
-```
-
-Set `APIUrl` only when the app is served from a different domain than the Identity endpoint (Cordova, Electron, or
-custom domains).
+### OAuth
 
-### Events
+OAuth is a two-step flow: `oauthLogin(provider)` redirects away from the site, then `handleAuthCallback()` processes
+the redirect when the user returns.
 
-```javascript
-netlifyIdentity.on('init', (user) => console.log('init', user))
-netlifyIdentity.on('login', (user) => console.log('login', user))
-netlifyIdentity.on('logout', () => console.log('Logged out'))
-netlifyIdentity.on('error', (err) => console.error('Error', err))
+```typescript
+import { oauthLogin } from '@netlify/identity'
 
-netlifyIdentity.off('login')           // unbind all login handlers
-netlifyIdentity.off('login', handler)  // unbind a specific handler
+// Step 1: Redirect to OAuth provider (this navigates away - never returns)
+function handleOAuthClick(provider: 'google' | 'github' | 'gitlab' | 'bitbucket') {
+  oauthLogin(provider)
+}
 ```
 
-### Key Methods
-
-```javascript
-netlifyIdentity.open()                                // open modal (default tab)
-netlifyIdentity.open('login')                         // open to login tab
-netlifyIdentity.open('signup')                        // open to signup tab
-netlifyIdentity.open('signup', { full_name: 'Jane' }) // pre-fill signup metadata
-netlifyIdentity.close()
-netlifyIdentity.logout()
-const user = netlifyIdentity.currentUser()            // null if not logged in
-const jwt = await netlifyIdentity.refresh()           // refresh the JWT
-const gotrueClient = netlifyIdentity.gotrue           // underlying GoTrue client
+```typescript
+import { handleAuthCallback, AuthError } from '@netlify/identity'
+
+// Step 2: Process the redirect on page load
+async function processCallback() {
+  try {
+    const result = await handleAuthCallback()
+    if (!result) return // No callback hash present - normal page load
+
+    switch (result.type) {
+      case 'oauth':
+        showSuccess(`Logged in as ${result.user?.email}`)
+        break
+      case 'confirmation':
+        showSuccess('Email confirmed. You are now logged in.')
+        break
+      case 'recovery':
+        // User is authenticated but must set a new password
+        showPasswordResetForm(result.user)
+        break
+      case 'invite':
+        // User must set a password to accept the invite
+        showInviteAcceptForm(result.token)
+        break
+      case 'email_change':
+        showSuccess('Email address updated.')
+        break
+    }
+  } catch (error) {
+    if (error instanceof AuthError) {
+      showError(error.message)
+    }
+  }
+}
 ```
 
-## gotrue-js (Programmatic Client)
-
-### Install
+Always call `handleAuthCallback()` on page load in any app that uses OAuth, password recovery, invites, or email
+confirmation. It handles all callback types via the URL hash.
 
-```bash
-npm install gotrue-js
-```
+### Password Recovery
 
-### Initialize
+Three-step flow: request recovery email, handle the callback, then set a new password.
 
 ```typescript
-import GoTrue from 'gotrue-js'
+import { requestPasswordRecovery, handleAuthCallback, updateUser, AuthError } from '@netlify/identity'
+
+// Step 1: Send recovery email
+async function handleForgotPassword(email: string) {
+  try {
+    await requestPasswordRecovery(email)
+    showSuccess('Check your email for a password reset link.')
+  } catch (error) {
+    if (error instanceof AuthError) showError(error.message)
+  }
+}
 
-const auth = new GoTrue({
-  APIUrl: 'https://<your-site>.netlify.app/.netlify/identity',
-  setCookie: false,
-})
+// Step 2: handleAuthCallback() returns { type: 'recovery', user } - show password reset form
+// (See the handleAuthCallback switch above)
+
+// Step 3: Set new password
+async function handlePasswordReset(newPassword: string) {
+  try {
+    await updateUser({ password: newPassword })
+    showSuccess('Password updated.')
+  } catch (error) {
+    if (error instanceof AuthError) showError(error.message)
+  }
+}
 ```
 
-`setCookie: true` tells the server to set HttpOnly cookies, which protects tokens from XSS but is required if you need
-role-based redirects without the widget (the CDN reads an `nf_jwt` cookie to evaluate redirect conditions). Use `false`
-when you manage tokens entirely in JavaScript and don't need CDN-level access control.
+Note: The recovery callback fires a `'recovery'` auth event, not `'login'`. The user is authenticated but should be
+prompted to set a new password before navigating away.
 
-### Core Methods
+### Invite Acceptance
 
-```javascript
-// Signup (sends confirmation email if autoconfirm is off)
-const response = await auth.signup(email, password)
-// Pass user_metadata during signup: auth.signup(email, password, { full_name: 'Jane' })
+When a user clicks an invite link, `handleAuthCallback()` returns `{ type: 'invite', user: null, token }`. Use the
+token to accept the invite and set a password.
 
-// Confirm email (token from confirmation email URL fragment)
-const user = await auth.confirm(token, true)        // remember = persist session
+```typescript
+import { acceptInvite, AuthError } from '@netlify/identity'
+
+async function handleAcceptInvite(token: string, password: string) {
+  try {
+    const user = await acceptInvite(token, password)
+    showSuccess(`Welcome, ${user.email}! Your account is ready.`)
+  } catch (error) {
+    if (error instanceof AuthError) showError(error.message)
+  }
+}
+```
 
-// Login
-const user = await auth.login(email, password, true) // remember = persist session
+### Email Change
 
-// Current user (from localStorage)
-const user = auth.currentUser()
+When a user verifies an email change, `handleAuthCallback()` returns `{ type: 'email_change', user }`. This requires an
+active browser session - the user must be logged in when clicking the verification link.
 
-// Get fresh JWT (auto-refreshes if expired; pass true to force)
-const token = await user.jwt()
+```typescript
+import { verifyEmailChange, AuthError } from '@netlify/identity'
+
+// If you need to verify programmatically with a token:
+async function handleEmailChangeVerification(token: string) {
+  try {
+    const user = await verifyEmailChange(token)
+    showSuccess(`Email updated to ${user.email}`)
+  } catch (error) {
+    if (error instanceof AuthError) showError(error.message)
+  }
+}
+```
 
-// Update user
-await user.update({ email: 'new@example.com', password: 'newpassword' })
-await user.update({ data: { full_name: 'Jane Doe' } }) // update user_metadata
+### Session Hydration
 
-// Logout
-await user.logout()
+`hydrateSession()` bridges server-set cookies to the browser session. Call it on page load when using server-side login
+(e.g., login inside a Netlify Function followed by a redirect).
 
-// Password recovery
-await auth.requestPasswordRecovery(email)               // sends recovery email
-const user = await auth.recover(recoveryToken, true)    // remember = persist session
+```typescript
+import { hydrateSession } from '@netlify/identity'
 
-// Check server settings (signup enabled? autoconfirm? OAuth providers?)
-const settings = await auth.settings()
+// On page load
+const user = await hydrateSession()
+if (user) {
+  // Browser session is now in sync with server-set cookies
+}
 ```
 
-### Error Handling
+Note: `getUser()` auto-hydrates from the `nf_jwt` cookie if no browser session exists, so explicit `hydrateSession()`
+is only needed when you want to restore the full session (including token refresh timers) after a server-side login.
 
-gotrue-js exports `JSONHTTPError`, `TextHTTPError`, and `HTTPError` for granular error catching. Use `error.json`,
-`error.data`, or `error.status` respectively.
+## Auth Events
 
-## Token Handling
+Subscribe to auth state changes with `onAuthChange`. Returns an unsubscribe function. No-op on server.
 
-- Access tokens expire after **1 hour**
-- Both `user.jwt()` (gotrue-js) and `netlifyIdentity.refresh()` (widget) auto-refresh using the refresh token
-- Always call `jwt()` or `refresh()` before authenticated requests — do not cache tokens
-- Send the token as `Authorization: Bearer <token>`
+```typescript
+import { onAuthChange, AUTH_EVENTS } from '@netlify/identity'
+
+const unsubscribe = onAuthChange((event, user) => {
+  switch (event) {
+    case AUTH_EVENTS.LOGIN:
+      console.log('User logged in:', user?.email)
+      break
+    case AUTH_EVENTS.LOGOUT:
+      console.log('User logged out')
+      break
+    case AUTH_EVENTS.TOKEN_REFRESH:
+      // Token auto-refreshed in background
+      break
+    case AUTH_EVENTS.USER_UPDATED:
+      console.log('User profile updated:', user?.email)
+      break
+    case AUTH_EVENTS.RECOVERY:
+      // Recovery token processed - prompt for new password
+      console.log('Password recovery initiated')
+      break
+  }
+})
 
-## Roles and Authorization
+// Later: unsubscribe()
+```
 
-### Metadata Types
+Auth events are automatically detected across browser tabs via the storage event listener - no extra setup needed.
 
-- **`app_metadata.roles`** — Server-controlled. Only settable via the Netlify UI, admin API, or server-side code
-  (Identity event functions, protected functions with admin token). Do not allow users to set their own roles.
-- **`user_metadata`** — User-controlled. Users can update this via `user.update({ data: { ... } })`.
+## Settings-Driven UI
 
-### Role-Based Redirects
+Fetch the project's Identity settings to conditionally render signup forms and OAuth buttons.
 
-Use `netlify.toml` to restrict paths by role:
+```typescript
+import { getSettings } from '@netlify/identity'
 
-```toml
-[[redirects]]
-  from = "/admin/*"
-  to = "/admin/:splat"
-  status = 200
-  conditions = { Role = ["admin"] }
+const settings = await getSettings()
+// settings.autoconfirm - boolean, whether email confirmation is skipped
+// settings.disableSignup - boolean, whether registration is closed
+// settings.providers - Record<AuthProvider, boolean>, e.g. { google: true, github: true, ... }
 
-[[redirects]]
-  from = "/admin/*"
-  to = "/"
-  status = 302
+// Conditionally render signup
+if (!settings.disableSignup) {
+  showSignupForm()
+}
+
+// Conditionally render OAuth buttons
+for (const [provider, enabled] of Object.entries(settings.providers)) {
+  if (enabled) {
+    showOAuthButton(provider)
+  }
+}
 ```
 
-Rules are evaluated top-to-bottom. The first redirect matches users with the `admin` role; everyone else falls through
-to the second rule and is redirected away.
+## Full API Reference
+
+For the complete API reference - all function signatures, type definitions, OAuth helpers, admin operations, session
+management, auth events, and framework-specific integration examples - read the package README:
+
+```
+node_modules/@netlify/identity/README.md
+```
+
+The README is shipped with the npm package and is always in sync with the installed version.
+
+## SSR Integration Patterns
 
-**How it works:** The widget sets an `nf_jwt` cookie that the CDN reads to evaluate `conditions = { Role = [...] }`.
-Without this cookie, role-based redirects will not work. If using gotrue-js instead of the widget, pass
-`setCookie: true` when initializing GoTrue so the server sets this cookie.
+For SSR frameworks, the recommended pattern is:
+
+- **Browser-side** for auth mutations: `login()`, `signup()`, `logout()`, `oauthLogin()`
+- **Server-side** for reading auth state: `getUser()`, `getSettings()`, `getIdentityConfig()`
+
+Browser-side auth mutations set the `nf_jwt` cookie and localStorage, and emit `onAuthChange` events. The
+server reads the cookie on the next request.
+
+The library also supports server-side mutations (`login()`, `signup()`, `logout()` inside Netlify Functions), but these
+require the Netlify Functions runtime to set cookies. After a server-side mutation, use a full page navigation so the
+browser sends the new cookie.
+
+Always use `window.location.href` (not framework router navigation) after server-side auth mutations in Next.js,
+TanStack Start, and SvelteKit. Remix `redirect()` is safe because Remix actions return real HTTP responses.
 
 ## Identity Event Functions
 
 Special serverless functions that trigger on Identity lifecycle events. These use the **legacy named `handler` export**
 (not the modern default export) because they receive `event.body` containing the user payload.
 
-**Event names:** `identity-validate`, `identity-signup`, `identity-login`
+Always use the legacy named `handler` export (not default export) for Identity event functions. The filename must match
+the event name exactly (e.g., `netlify/functions/identity-signup.mts`).
 
-- `identity-signup` — fires when a new user signs up (email/password or OAuth)
-- `identity-login` — fires on each login
-- `identity-validate` — fires during signup before the user is created; return a non-200 status to reject the signup
+**Event names:** `identity-validate`, `identity-signup`, `identity-login`
 
-The filename must match the event name exactly (e.g. `netlify/functions/identity-signup.mts`).
+- `identity-signup` - fires when a new user signs up (email/password or OAuth)
+- `identity-login` - fires on each login
+- `identity-validate` - fires during signup before the user is created; return a non-200 status to reject
 
 ### Example: Assign Default Role on Signup
 
@@ -253,77 +430,183 @@ const handler: Handler = async (event: HandlerEvent, context: HandlerContext) =>
 export { handler }
 ```
 
-The response body replaces `app_metadata` and/or `user_metadata` on the user record — include all fields you want to
+The response body replaces `app_metadata` and/or `user_metadata` on the user record - include all fields you want to
 keep, not just new ones.
 
-## Protected Functions
+For bulk user management or role changes outside lifecycle events, use the `admin` API instead of Identity event
+functions.
+
+## Roles and Authorization
+
+### Metadata Types
+
+- **`app_metadata.roles`** - Server-controlled. Only settable via the Netlify UI, admin API, or Identity event functions.
+  Do not allow users to set their own roles.
+- **`user_metadata`** - User-controlled. Users can update this via `updateUser({ data: { ... } })`.
 
-Functions that verify the calling user's identity. Use the legacy `handler` export to access `context.clientContext`.
+### Role-Based Redirects
+
+Use `netlify.toml` to restrict paths by role:
+
+```toml
+[[redirects]]
+  from = "/admin/*"
+  to = "/admin/:splat"
+  status = 200
+  conditions = { Role = ["admin"] }
+
+[[redirects]]
+  from = "/admin/*"
+  to = "/"
+  status = 302
+```
+
+Rules are evaluated top-to-bottom. The first redirect matches users with the `admin` role; everyone else falls through
+to the second rule and is redirected away.
+
+**How it works:** The `nf_jwt` cookie is read by the CDN to evaluate `conditions = { Role = [...] }`. Without this
+cookie, role-based redirects will not work.
+
+## Common Errors & Solutions
+
+### "Signups not allowed for this instance" (403)
+
+**Cause:** Registration is set to Invite only.
+
+**Fix:**
+
+1. Change to Open in **Project configuration > Identity**
+2. Or invite users from the Identity tab in the Netlify UI
 
 ```typescript
-// netlify/functions/protected-action.mts
-import type { Handler, HandlerEvent, HandlerContext } from '@netlify/functions'
+if (error instanceof AuthError && error.status === 403) {
+  showError('Signups are disabled. Contact the site admin for an invite.')
+}
+```
 
-const handler: Handler = async (event: HandlerEvent, context: HandlerContext) => {
-  const { identity, user } = context.clientContext || {}
+### Invalid credentials (401)
 
-  if (!user) {
-    return { statusCode: 401, body: JSON.stringify({ error: 'Unauthorized' }) }
-  }
+**Cause:** Wrong email or password on login.
+
+**Fix:** Show a user-facing error and let the user retry. Do not reveal whether the email or password was wrong.
 
-  // user.sub — user ID
-  // user.email — email address
-  // user.app_metadata.roles — assigned roles
-  // user.user_metadata — user-controlled data
-
-  // Use identity.token (admin token) to call the Identity admin API:
-  const adminAuthHeader = `Bearer ${identity.token}`
-  const response = await fetch(`${identity.url}/admin/users/${user.sub}`, {
-    method: 'PUT',
-    headers: { Authorization: adminAuthHeader },
-    body: JSON.stringify({ app_metadata: { roles: ['editor'] } }),
-  })
-
-  const data = await response.json()
-  return { statusCode: 200, body: JSON.stringify(data) }
+```typescript
+if (error instanceof AuthError && error.status === 401) {
+  showError('Invalid email or password.')
 }
+```
 
-export { handler }
+### "Email not confirmed"
+
+**Cause:** User tries to log in before confirming their email (autoconfirm is off).
+
+**Fix:** Tell the user to check their inbox. Optionally provide a way to resend the confirmation email via `signup()`
+with the same credentials.
+
+### "Token expired" / 401 on API calls
+
+**Cause:** Stale access token.
+
+**Fix:**
+
+1. Always use `getUser()` before authenticated requests - it auto-hydrates from cookies
+2. In the browser, the library auto-refreshes tokens via `startTokenRefresh()`
+3. On the server, call `refreshSession()` in middleware to handle near-expiry tokens
+
+```typescript
+const newToken = await refreshSession()
+if (newToken) {
+  // Token was refreshed - retry the request
+}
 ```
 
-**Note:** Operations using `identity.token` (admin token) do **not** work locally with `netlify dev`. Deploy to Netlify
-to test server-side admin operations.
+### Identity event function not triggering
+
+**Cause:** Filename or export format does not match expected convention.
 
-## External OAuth Providers
+**Fix:**
 
-Netlify Identity supports Google, GitHub, GitLab, and BitBucket as built-in OAuth providers.
+1. Verify filename matches exactly: `identity-signup`, `identity-validate`, or `identity-login`
+2. Place in `netlify/functions/` with `.mts` or `.mjs` extension
+3. Use named `handler` export (not default export)
 
-**Enable in Netlify UI:** Project configuration > Identity > Registration > External providers
+### `MissingIdentityError`
 
-### Widget
+**Cause:** Identity is not configured in the current environment.
 
-Once enabled in the UI, the widget automatically shows OAuth provider buttons. No additional code needed.
+**Fix:**
 
-### gotrue-js
+1. Ensure Identity is enabled on the project
+2. Use `netlify dev` for local development so the Identity endpoint is available
 
-```javascript
-const url = auth.loginExternalUrl('github')
-// Redirect the user to this URL to start the OAuth flow
-window.location.href = url
+```typescript
+if (error instanceof MissingIdentityError) {
+  showError('Identity is not enabled. Run "netlify dev" or enable Identity in project settings.')
+}
 ```
 
-Available provider names: `'google'`, `'github'`, `'gitlab'`, `'bitbucket'`
+### `AuthError` on server - missing Netlify runtime
 
-## Common Errors & Solutions
+**Cause:** Server-side `login()`, `signup()`, or `logout()` require the Netlify Functions runtime to set cookies.
+
+**Fix:**
+
+1. Deploy to Netlify to use server-side auth mutations
+2. Or use `netlify dev` for local development
+
+### "User not found" after OAuth login
+
+**Cause:** OAuth provider is not enabled for the project.
+
+**Fix:**
+
+1. Enable the provider in **Project configuration > Identity > External providers**
+2. Users are created automatically on first OAuth login
+
+### Account operations fail after server-side login
+
+**Cause:** Browser-side session is not bootstrapped from server-set cookies.
+
+**Fix:** Call `hydrateSession()` on page load to bridge server-set cookies to the browser session. Then use
+`updateUser()`, `verifyEmailChange()`, or other account operations.
+
+```typescript
+import { hydrateSession, updateUser } from '@netlify/identity'
+
+// On page load after server-side login
+await hydrateSession()
+
+// Now account operations work
+await updateUser({ data: { full_name: 'Jane' } })
+```
+
+### "Email change verification requires an active browser session"
+
+**Cause:** `verifyEmailChange()` was called without an active session. The user must be logged in when clicking the
+email change verification link.
+
+**Fix:** Ensure the user is logged in before processing the `email_change` callback. If the session expired, prompt
+the user to log in first.
+
+### "No user is currently logged in"
+
+**Cause:** An account operation (`updateUser`, `verifyEmailChange`) was called without an authenticated user.
+
+**Fix:** Check `getUser()` before calling account operations. If `null`, redirect to login.
+
+```typescript
+const user = await getUser()
+if (!user) {
+  redirectToLogin()
+  return
+}
+await updateUser({ data: { full_name: 'Jane' } })
+```
+
+### Stale session - user deleted server-side
+
+**Cause:** `getUser()` returns `null` when the `nf_jwt` cookie is gone but localStorage still has a stale
+session. This happens when a user is deleted via the admin API or Netlify UI.
 
-- **"Signups not allowed for this instance" (403)** — Registration is set to Invite only. Change to Open in Project
-  configuration > Identity, or invite users from the Identity tab.
-- **"Token expired" / 401 on API calls** — Stale access token. Always call `user.jwt()` or `netlifyIdentity.refresh()`
-  before authenticated requests.
-- **Identity event function not triggering** — Verify filename matches exactly (`identity-signup`, `identity-validate`,
-  or `identity-login`), is in `netlify/functions/`, and uses `.mts`/`.mjs`.
-- **`clientContext` is undefined** — Use named `handler` export (not `export default`), send `Authorization: Bearer`
-  header, and verify token is fresh.
-- **Admin methods not working locally** — `identity.token` is unavailable in local dev. Deploy to Netlify to test.
-- **"User not found" after OAuth login** — Enable the OAuth provider in Project configuration > Identity > External
-  providers. Users are created on first OAuth login.
+**Fix:** `getUser()` handles this gracefully - it returns `null` and the stale localStorage entry is ignored. Always
+check for `null` before using the user object.