@githat/nextjs 0.4.0 → 0.4.2

package/README.md

@@ -11,7 +11,7 @@ GitHat is your backend. This SDK connects your app to `api.githat.io` with pre-b
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/badge/License-Proprietary-red.svg)](./LICENSE)
 
-[Quick Start](#quick-start) · [Components](#components) · [Hooks](#hooks) · [Middleware](#middleware) · [Docs](https://githat.io/docs)
+[Quick Start](#quick-start) · [Components](#components) · [Hooks](#hooks) · [Middleware](#middleware) · [Server-Side](#server-side-authentication) · [Docs](https://githat.io/docs)
 
 </div>
 
@@ -19,9 +19,11 @@ GitHat is your backend. This SDK connects your app to `api.githat.io` with pre-b
 
 ## Features
 
-- **Pre-built UI Components** — Sign-in, sign-up, user button, org switcher — all themed and ready to go
-- **React Hooks** — `useAuth()` and `useGitHat()` for full control over auth state and API calls
+- **Pre-built UI Components** — Sign-in, sign-up, password reset, email verification — all themed and ready to go
+- **React Hooks** — `useAuth()`, `useGitHat()`, and `useData()` for full control over auth state and API calls
 - **Next.js Middleware** — Protect routes at the edge with a single line of config
+- **Server-Side Auth** — Verify tokens, wrap API routes, and inject auth headers
+- **Customer Data API** — Store and query app data in GitHat's managed DynamoDB
 - **Multi-Tenant** — Organizations, team invitations, and role-based access — managed by GitHat's backend
 - **MCP & Agent Verification** — Verify MCP servers and AI agents on-chain
 - **Dark Theme Included** — Import `@githat/nextjs/styles` for a polished dark UI out of the box
@@ -99,6 +101,10 @@ export default function SignUpPage() {
 
 ### 5. Protect Routes with Middleware
 
+<!-- tabs:start -->
+
+#### **Next.js 14-15 (middleware.ts)**
+
 ```ts
 // middleware.ts (project root)
 import { authMiddleware } from '@githat/nextjs/middleware';
@@ -112,6 +118,23 @@ export const config = {
 };
 ```
 
+#### **Next.js 16+ (proxy.ts)**
+
+```ts
+// proxy.ts (project root)
+import { authProxy } from '@githat/nextjs/proxy';
+
+export const proxy = authProxy({
+  publicRoutes: ['/', '/sign-in', '/sign-up', '/forgot-password'],
+});
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+};
+```
+
+<!-- tabs:end -->
+
 ### 6. Use Auth State Anywhere
 
 ```tsx
@@ -142,32 +165,91 @@ That's it. You now have a fully authenticated app with sign-in, sign-up, route p
 
 ### Provider
 
-| Component        | Description                              | Key Props                                               |
-|------------------|------------------------------------------|---------------------------------------------------------|
+| Component        | Description                              | Key Props                                                 |
+|------------------|------------------------------------------|-----------------------------------------------------------|
 | `GitHatProvider` | Wraps your app and provides auth context | `config` (required) — see [Configuration](#configuration) |
 
 ### Authentication Forms
 
-| Component    | Description                          | Props                                            |
-|--------------|--------------------------------------|--------------------------------------------------|
-| `SignInForm` | Email + password sign-in form        | `onSuccess?`, `signUpUrl?`, `forgotPasswordUrl?` |
-| `SignUpForm` | Name + email + password sign-up form | `onSuccess?`, `signInUrl?`                       |
+| Component            | Description                          | Props                                               |
+|----------------------|--------------------------------------|-----------------------------------------------------|
+| `SignInForm`         | Email + password sign-in form        | `onSuccess?`, `signUpUrl?`, `forgotPasswordUrl?`    |
+| `SignUpForm`         | Name + email + password sign-up form | `onSuccess?`, `signInUrl?`                          |
+| `ForgotPasswordForm` | Request password reset email         | `onSuccess?`, `onError?`, `signInUrl?`              |
+| `ResetPasswordForm`  | Reset password with token            | `token`, `onSuccess?`, `onError?`, `signInUrl?`, `minPasswordLength?` |
+| `VerifyEmailStatus`  | Auto-verify email from URL token     | `token`, `onSuccess?`, `onError?`, `signInUrl?`, `redirectDelay?` |
+| `ChangePasswordForm` | Change password (authenticated)      | `onSuccess?`, `onError?`, `minPasswordLength?`      |
 
 ### Navigation
 
-| Component      | Description                                  | Props                                    |
-|----------------|----------------------------------------------|------------------------------------------|
-| `SignInButton` | Link/button to your sign-in page             | `className?`, `children?`, `href?`       |
-| `SignUpButton` | Link/button to your sign-up page             | `className?`, `children?`, `href?`       |
-| `UserButton`   | Avatar dropdown with user info and sign-out  | — (uses context)                         |
-| `OrgSwitcher`  | Dropdown to switch between organizations     | — (uses context)                         |
+| Component      | Description                                 | Props                              |
+|----------------|---------------------------------------------|------------------------------------|
+| `SignInButton` | Link/button to your sign-in page            | `className?`, `children?`, `href?` |
+| `SignUpButton` | Link/button to your sign-up page            | `className?`, `children?`, `href?` |
+| `UserButton`   | Avatar dropdown with user info and sign-out | — (uses context)                   |
+| `OrgSwitcher`  | Dropdown to switch between organizations    | — (uses context)                   |
 
 ### Protection & Verification
 
-| Component        | Description                                | Props                                                        |
-|------------------|--------------------------------------------|--------------------------------------------------------------|
-| `ProtectedRoute` | Redirects unauthenticated users to sign-in | `children`, `fallback?`                                      |
-| `VerifiedBadge`  | Displays MCP/agent verification status     | `type: 'mcp' \| 'agent'`, `identifier`, `label?`            |
+| Component        | Description                                | Props                                            |
+|------------------|--------------------------------------------|--------------------------------------------------|
+| `ProtectedRoute` | Redirects unauthenticated users to sign-in | `children`, `fallback?`                          |
+| `VerifiedBadge`  | Displays MCP/agent verification status     | `type: 'mcp' \| 'agent'`, `identifier`, `label?` |
+
+### Example: Password Reset Flow
+
+```tsx
+// app/forgot-password/page.tsx
+import { ForgotPasswordForm } from '@githat/nextjs';
+
+export default function ForgotPasswordPage() {
+  return (
+    <div style={{ maxWidth: 400, margin: '80px auto' }}>
+      <ForgotPasswordForm signInUrl="/sign-in" />
+    </div>
+  );
+}
+```
+
+```tsx
+// app/reset-password/page.tsx
+'use client';
+
+import { ResetPasswordForm } from '@githat/nextjs';
+import { useSearchParams } from 'next/navigation';
+
+export default function ResetPasswordPage() {
+  const searchParams = useSearchParams();
+  const token = searchParams.get('token') || '';
+
+  return (
+    <div style={{ maxWidth: 400, margin: '80px auto' }}>
+      <ResetPasswordForm token={token} signInUrl="/sign-in" />
+    </div>
+  );
+}
+```
+
+### Example: Email Verification
+
+```tsx
+// app/verify-email/page.tsx
+'use client';
+
+import { VerifyEmailStatus } from '@githat/nextjs';
+import { useSearchParams } from 'next/navigation';
+
+export default function VerifyEmailPage() {
+  const searchParams = useSearchParams();
+  const token = searchParams.get('token') || '';
+
+  return (
+    <div style={{ maxWidth: 400, margin: '80px auto' }}>
+      <VerifyEmailStatus token={token} signInUrl="/sign-in" />
+    </div>
+  );
+}
+```
 
 ### Example: Protected Dashboard
 
@@ -256,14 +338,30 @@ export function CustomLogin() {
 
 ### `useGitHat()`
 
-Access the GitHat API client for authenticated requests, org management, and verification.
+Access the GitHat API client for authenticated requests, org management, password reset, email verification, and more.
 
 ```tsx
 const {
-  fetch,         // <T>(path: string, init?: RequestInit) => Promise<T>
-  getUserOrgs,   // () => Promise<{ orgs: GitHatOrg[] }>
-  verifyMCP,     // (domain: string) => Promise<{ verified: boolean }>
-  verifyAgent,   // (wallet: string) => Promise<{ verified: boolean }>
+  // API Client
+  fetch,                    // <T>(path: string, init?: RequestInit) => Promise<T>
+  getUserOrgs,              // () => Promise<{ orgs: GitHatOrg[] }>
+
+  // MCP & Agent Verification
+  verifyMCP,                // (domain: string) => Promise<{ verified: boolean }>
+  verifyAgent,              // (wallet: string) => Promise<{ verified: boolean }>
+
+  // Organization Metadata
+  getOrgMetadata,           // () => Promise<OrgMetadata>
+  updateOrgMetadata,        // (updates: OrgMetadata) => Promise<OrgMetadata>
+
+  // Password Management
+  forgotPassword,           // (email: string) => Promise<{ success: boolean }>
+  resetPassword,            // (token: string, newPassword: string) => Promise<{ success: boolean }>
+  changePassword,           // (currentPassword: string, newPassword: string) => Promise<{ success: boolean }>
+
+  // Email Verification
+  verifyEmail,              // (token: string) => Promise<{ success: boolean }>
+  resendVerificationEmail,  // (email: string) => Promise<{ success: boolean }>
 } = useGitHat();
 ```
 
@@ -303,6 +401,143 @@ const { fetch } = useGitHat();
 const apps = await fetch<{ apps: App[] }>('/user/apps');
 ```
 
+#### Example: Organization metadata
+
+```tsx
+const { getOrgMetadata, updateOrgMetadata } = useGitHat();
+
+// Read metadata
+const meta = await getOrgMetadata();
+console.log(meta.stripeAccountId);
+
+// Update metadata (requires admin or owner role)
+await updateOrgMetadata({ stripeAccountId: 'acct_xxx', features: ['pos'] });
+
+// Delete a key by setting it to null
+await updateOrgMetadata({ oldKey: null });
+```
+
+#### Example: Password reset flow (programmatic)
+
+```tsx
+const { forgotPassword, resetPassword, changePassword } = useGitHat();
+
+// Request reset email
+await forgotPassword('user@example.com');
+
+// Reset with token (from email link)
+await resetPassword(token, 'NewSecurePassword123!');
+
+// Change password (authenticated user)
+await changePassword('currentPassword', 'newSecurePassword123!');
+```
+
+#### Example: Email verification (programmatic)
+
+```tsx
+const { verifyEmail, resendVerificationEmail } = useGitHat();
+
+// Verify with token from email link
+await verifyEmail(token);
+
+// Resend verification email
+await resendVerificationEmail('user@example.com');
+```
+
+### `useData()`
+
+Access GitHat's Customer Data API for storing app data in managed DynamoDB. Must be used within a `<GitHatProvider>`.
+
+```tsx
+const {
+  put,     // <T>(collection: string, data: T) => Promise<PutResult<T>>
+  get,     // <T>(collection: string, id: string) => Promise<T | null>
+  query,   // <T>(collection: string, options?: QueryOptions) => Promise<QueryResult<T>>
+  remove,  // (collection: string, id: string) => Promise<DeleteResult>
+  batch,   // (collection: string, operations: BatchOperation[]) => Promise<BatchResult>
+} = useData();
+```
+
+#### Example: CRUD operations
+
+```tsx
+'use client';
+
+import { useData } from '@githat/nextjs';
+
+interface Order {
+  id: string;
+  amount: number;
+  status: 'pending' | 'completed' | 'cancelled';
+  createdAt: string;
+}
+
+export function OrderManager() {
+  const { put, get, query, remove, batch } = useData();
+
+  // Create or update an item
+  const createOrder = async () => {
+    const result = await put<Order>('orders', {
+      id: 'order_123',
+      amount: 99.99,
+      status: 'pending',
+      createdAt: new Date().toISOString(),
+    });
+    console.log(result.created ? 'Created' : 'Updated');
+  };
+
+  // Get a single item
+  const getOrder = async () => {
+    const order = await get<Order>('orders', 'order_123');
+    if (order) {
+      console.log(`Order: $${order.amount}`);
+    }
+  };
+
+  // Query with filters and pagination
+  const getPendingOrders = async () => {
+    const { items, nextCursor } = await query<Order>('orders', {
+      filter: { status: 'pending' },
+      limit: 20,
+    });
+    console.log(`Found ${items.length} pending orders`);
+  };
+
+  // Delete an item
+  const deleteOrder = async () => {
+    await remove('orders', 'order_123');
+  };
+
+  // Batch operations (max 100 per request)
+  const bulkUpdate = async () => {
+    await batch('orders', [
+      { type: 'put', id: 'order_1', data: { amount: 50, status: 'completed' } },
+      { type: 'put', id: 'order_2', data: { amount: 75, status: 'pending' } },
+      { type: 'delete', id: 'order_3' },
+    ]);
+  };
+
+  return (
+    <div>
+      <button onClick={createOrder}>Create Order</button>
+      <button onClick={getOrder}>Get Order</button>
+      <button onClick={getPendingOrders}>List Pending</button>
+      <button onClick={deleteOrder}>Delete Order</button>
+      <button onClick={bulkUpdate}>Bulk Update</button>
+    </div>
+  );
+}
+```
+
+#### Data API Tier Limits
+
+| Tier       | Max Items |
+|------------|-----------|
+| Free       | 1,000     |
+| Basic      | 10,000    |
+| Pro        | 100,000   |
+| Enterprise | Unlimited |
+
 ---
 
 ## Middleware
@@ -310,13 +545,13 @@ const apps = await fetch<{ apps: App[] }>('/user/apps');
 The `authMiddleware` function protects your Next.js routes at the edge. Unauthenticated users are redirected to your sign-in page with a `redirect_url` query parameter for post-login redirect.
 
 ```ts
-// middleware.ts
+// middleware.ts (Next.js 14-15)
 import { authMiddleware } from '@githat/nextjs/middleware';
 
 export default authMiddleware({
   publicRoutes: ['/', '/sign-in', '/sign-up', '/pricing'],
-  signInUrl: '/sign-in',     // default: '/sign-in'
-  tokenKey: 'githat_access_token', // default: 'githat_access_token'
+  signInUrl: '/sign-in',
+  injectHeaders: true, // Optional: inject x-githat-* headers
 });
 
 export const config = {
@@ -326,13 +561,193 @@ export const config = {
 
 ### Middleware Options
 
-| Option         | Type       | Default                 | Description                              |
-|----------------|------------|-------------------------|------------------------------------------|
-| `publicRoutes` | `string[]` | `['/']`                 | Routes accessible without authentication |
-| `signInUrl`    | `string`   | `'/sign-in'`            | Where to redirect unauthenticated users  |
-| `tokenKey`     | `string`   | `'githat_access_token'` | Cookie name to check for the auth token  |
+| Option             | Type       | Default                 | Description                                          |
+|--------------------|------------|-------------------------|------------------------------------------------------|
+| `publicRoutes`     | `string[]` | `['/']`                 | Routes accessible without authentication             |
+| `signInUrl`        | `string`   | `'/sign-in'`            | Where to redirect unauthenticated users              |
+| `tokenCookie`      | `string`   | `'githat_access'`       | Cookie name for httpOnly access token                |
+| `legacyTokenCookie`| `string`   | `'githat_access_token'` | Legacy cookie name (localStorage bridge)             |
+| `injectHeaders`    | `boolean`  | `false`                 | Inject `x-githat-*` headers into requests            |
+| `secretKey`        | `string`   | —                       | Secret key for local JWT verification (recommended)  |
+
+### Header Injection
+
+When `injectHeaders: true`, the middleware decodes the JWT and adds these headers to downstream requests:
+
+| Header              | Value                      |
+|---------------------|----------------------------|
+| `x-githat-user-id`  | User's unique ID           |
+| `x-githat-email`    | User's email address       |
+| `x-githat-org-id`   | Current organization ID    |
+| `x-githat-org-slug` | Current organization slug  |
+| `x-githat-role`     | User's role (owner/admin/member) |
+
+This allows API routes to access user info without re-verifying the token.
 
-> **Note:** Since tokens are stored in `localStorage` on the client, middleware performs a cookie presence check. Full token validation happens server-side on API calls. Use the optional cookie bridge pattern to sync `localStorage` tokens to cookies for edge protection.
+> **⚠️ Important: API routes are NOT protected by the middleware/proxy.** Both `authMiddleware` and `authProxy` automatically skip all `/api` routes (`pathname.startsWith('/api')` → pass-through). This is by design — API routes should use `withAuth()` or `getAuth()` from `@githat/nextjs/server` to verify tokens. See [Server-Side Authentication](#server-side-authentication) below.
+
+---
+
+## Next.js 16+ Proxy
+
+Next.js 16 renamed `middleware.ts` to `proxy.ts` and the export from `export default middleware` to `export const proxy`. Use `authProxy` for Next.js 16+:
+
+```ts
+// proxy.ts (Next.js 16+)
+import { authProxy } from '@githat/nextjs/proxy';
+
+export const proxy = authProxy({
+  publicRoutes: ['/', '/about', '/pricing', '/sign-in', '/sign-up'],
+  signInUrl: '/sign-in',
+  injectHeaders: true,
+  secretKey: process.env.GITHAT_SECRET_KEY, // Recommended
+});
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+};
+```
+
+The `authProxy` function accepts the same options as `authMiddleware`.
+
+> **⚠️ Important: API routes are NOT protected by `authProxy` or `authMiddleware`.** Both automatically skip all `/api` routes. You **must** use `withAuth()` or `getAuth()` from `@githat/nextjs/server` to protect your API route handlers. See below.
+
+---
+
+## Server-Side Authentication
+
+The `@githat/nextjs/server` module provides utilities for server-side token verification in API routes and middleware.
+
+### Import
+
+```ts
+import {
+  verifyToken,
+  getAuth,
+  withAuth,
+  getOrgMetadata,
+  updateOrgMetadata,
+  COOKIE_NAMES,
+  type AuthPayload,
+  type VerifyOptions,
+} from '@githat/nextjs/server';
+```
+
+### `verifyToken(token, options?)`
+
+Verify a JWT token and return the decoded auth payload.
+
+```ts
+// Local verification (fast, ~1ms) — recommended for production
+const auth = await verifyToken(token, {
+  secretKey: process.env.GITHAT_SECRET_KEY,
+});
+
+// API-based verification (simpler setup, ~50-100ms)
+const auth = await verifyToken(token);
+```
+
+Returns `AuthPayload`:
+
+```ts
+interface AuthPayload {
+  userId: string;
+  email: string;
+  orgId: string | null;
+  orgSlug: string | null;
+  role: 'owner' | 'admin' | 'member' | null;
+  tier: 'free' | 'basic' | 'pro' | 'enterprise' | null;
+}
+```
+
+### `getAuth(request, options?)`
+
+Extract and verify the auth token from a Next.js request. Checks cookies first, then Authorization header.
+
+```ts
+// app/api/orders/route.ts
+import { getAuth } from '@githat/nextjs/server';
+
+export async function GET(request: Request) {
+  const auth = await getAuth(request, {
+    secretKey: process.env.GITHAT_SECRET_KEY,
+  });
+
+  if (!auth) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  // auth.userId, auth.orgId, auth.role available
+  return Response.json({ userId: auth.userId });
+}
+```
+
+### `withAuth(handler, options?)`
+
+Wrap an API route handler with authentication. The handler only runs if the request has a valid token. **This is required for every protected API route** — the middleware/proxy does not protect `/api` routes.
+
+```ts
+// app/api/orders/route.ts
+import { withAuth } from '@githat/nextjs/server';
+
+export const GET = withAuth(
+  async (request, auth) => {
+    // auth is guaranteed to be valid here
+    const orders = await db.orders.findMany({
+      where: { orgId: auth.orgId },
+    });
+    return Response.json({ orders });
+  },
+  { secretKey: process.env.GITHAT_SECRET_KEY }
+);
+```
+
+#### Custom unauthorized response
+
+```ts
+export const GET = withAuth(
+  async (request, auth) => {
+    return Response.json({ userId: auth.userId });
+  },
+  {
+    secretKey: process.env.GITHAT_SECRET_KEY,
+    onUnauthorized: () => Response.redirect('/sign-in'),
+  }
+);
+```
+
+### `getOrgMetadata(orgId, options)` / `updateOrgMetadata(orgId, metadata, options)`
+
+Server-side org metadata operations.
+
+```ts
+import { getOrgMetadata, updateOrgMetadata } from '@githat/nextjs/server';
+
+// Get metadata
+const meta = await getOrgMetadata(orgId, {
+  token: accessToken,
+  apiUrl: 'https://api.githat.io',
+});
+console.log(meta.stripeAccountId);
+
+// Update metadata
+await updateOrgMetadata(
+  orgId,
+  { stripeAccountId: 'acct_xxx' },
+  { token: accessToken }
+);
+```
+
+### `COOKIE_NAMES`
+
+Constants for cookie names used by the SDK.
+
+```ts
+import { COOKIE_NAMES } from '@githat/nextjs/server';
+
+// COOKIE_NAMES.accessToken = 'githat_access'
+// COOKIE_NAMES.refreshToken = 'githat_refresh'
+```
 
 ---
 
@@ -342,20 +757,36 @@ export const config = {
 
 Pass this to `<GitHatProvider config={...}>`:
 
-| Property          | Type     | Required | Default                   | Description                 |
-|-------------------|----------|----------|---------------------------|-----------------------------|
-| `publishableKey`  | `string` | Yes      | —                         | Your GitHat publishable key |
-| `apiUrl`          | `string` | No       | `'https://api.githat.io'` | API base URL                |
-| `signInUrl`       | `string` | No       | `'/sign-in'`              | Sign-in page route          |
-| `signUpUrl`       | `string` | No       | `'/sign-up'`              | Sign-up page route          |
-| `afterSignInUrl`  | `string` | No       | `'/'`                     | Redirect after sign-in      |
-| `afterSignOutUrl` | `string` | No       | `'/'`                     | Redirect after sign-out     |
+| Property         | Type                           | Required | Default                   | Description                          |
+|------------------|--------------------------------|----------|---------------------------|--------------------------------------|
+| `publishableKey` | `string`                       | Yes      | —                         | Your GitHat publishable key          |
+| `apiUrl`         | `string`                       | No       | `'https://api.githat.io'` | API base URL                         |
+| `signInUrl`      | `string`                       | No       | `'/sign-in'`              | Sign-in page route                   |
+| `signUpUrl`      | `string`                       | No       | `'/sign-up'`              | Sign-up page route                   |
+| `afterSignInUrl` | `string`                       | No       | `'/'`                     | Redirect after sign-in               |
+| `afterSignOutUrl`| `string`                       | No       | `'/'`                     | Redirect after sign-out              |
+| `tokenStorage`   | `'localStorage' \| 'cookie'`   | No       | `'localStorage'`          | Token storage mode (see below)       |
+
+### Token Storage Modes
+
+| Mode           | Description                                                              |
+|----------------|--------------------------------------------------------------------------|
+| `localStorage` | Default. Tokens stored in browser localStorage. Simple client-side setup. |
+| `cookie`       | Tokens stored in httpOnly cookies. More secure, XSS-resistant. Better for SSR. |
+
+When using `cookie` mode:
+
+- Login/refresh automatically set httpOnly cookies
+- SDK reads auth state from cookies server-side
+- Better security for apps with server-side rendering
+- Required for `getAuth()` and `withAuth()` server utilities
 
 ### Environment Variables
 
 ```env
 # .env.local
-NEXT_PUBLIC_GITHAT_KEY=pk_live_xxxxxxxxxxxxx
+NEXT_PUBLIC_GITHAT_KEY=pk_live_your_key_here
+GITHAT_SECRET_KEY=sk_live_your_secret_key  # For server-side verification
 ```
 
 ### React/Vite Setup
@@ -375,7 +806,7 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
 );
 ```
 
-> **Note:** The middleware export (`@githat/nextjs/middleware`) is Next.js-specific. For Vite/CRA apps, use `<ProtectedRoute>` for client-side route protection.
+> **Note:** The middleware/proxy exports are Next.js-specific. For Vite/CRA apps, use `<ProtectedRoute>` for client-side route protection.
 
 ---
 
@@ -387,7 +818,7 @@ Import the built-in dark theme:
 import '@githat/nextjs/styles';
 ```
 
-This provides styled defaults for all components (`SignInForm`, `SignUpForm`, `UserButton`, `OrgSwitcher`, etc.). All class names are prefixed with `githat-` to avoid conflicts.
+This provides styled defaults for all components (`SignInForm`, `SignUpForm`, `ForgotPasswordForm`, `ResetPasswordForm`, `VerifyEmailStatus`, `ChangePasswordForm`, `UserButton`, `OrgSwitcher`, etc.). All class names are prefixed with `githat-` to avoid conflicts.
 
 ### Customization
 
@@ -417,6 +848,7 @@ Every export is fully typed. Import types directly:
 
 ```tsx
 import type {
+  // Core types
   GitHatUser,
   GitHatOrg,
   GitHatConfig,
@@ -425,6 +857,30 @@ import type {
   SignUpData,
   SignUpResult,
   GitHatContextValue,
+
+  // Password & Email
+  PasswordResetResult,
+  EmailVerificationResult,
+
+  // Server-side
+  AuthPayload,
+  VerifyOptions,
+  OrgMetadata,
+  WithAuthOptions,
+  AuthenticatedHandler,
+
+  // Customer Data API
+  DataItem,
+  QueryOptions,
+  QueryResult,
+  PutResult,
+  DeleteResult,
+  BatchOperation,
+  BatchResult,
+
+  // Middleware/Proxy
+  AuthHandlerOptions,
+  AuthProxyOptions,
 } from '@githat/nextjs';
 ```
 
@@ -447,6 +903,15 @@ interface GitHatOrg {
   tier: string;
 }
 
+interface AuthPayload {
+  userId: string;
+  email: string;
+  orgId: string | null;
+  orgSlug: string | null;
+  role: 'owner' | 'admin' | 'member' | null;
+  tier: 'free' | 'basic' | 'pro' | 'enterprise' | null;
+}
+
 interface SignUpData {
   email: string;
   password: string;
@@ -470,7 +935,77 @@ Use the companion CLI to scaffold a complete Next.js or React app with GitHat au
 npx create-githat-app my-app
 ```
 
-This generates a full project connected to GitHat's hosted backend — sign-in, sign-up, dashboard, settings, and team management pages. No backend to deploy.
+This generates a full project connected to GitHat's hosted backend — sign-in, sign-up, password reset, email verification, dashboard, settings, and team management pages. No backend to deploy.
+
+---
+
+## Known Limitations
+
+These are things GitHat does **not** provide today. They are not blockers — each has a recommended workaround.
+
+### No webhooks / event system
+
+GitHat does not send server-side notifications when users register, verify email, or delete accounts. Use `onSuccess` callbacks on form components to call your own API endpoint instead:
+
+```tsx
+<SignUpForm
+  onSuccess={async (result) => {
+    // result: { requiresVerification: boolean, email: string }
+    // Call your API to sync user, send welcome email, etc.
+    await fetch('/api/on-signup', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email: result.email }),
+    });
+  }}
+/>
+
+<VerifyEmailStatus
+  token={token}
+  onSuccess={async () => {
+    // Email verified — trigger your post-verification logic
+    await fetch('/api/on-email-verified', { method: 'POST' });
+  }}
+/>
+```
+
+### No user metadata API
+
+Org metadata exists (`getOrgMetadata` / `updateOrgMetadata`), but there is no per-user equivalent. Use the [Customer Data API](https://githat.io/docs/data) or your own database:
+
+```tsx
+import { useData, useAuth } from '@githat/nextjs';
+
+function useUserPreferences() {
+  const { user } = useAuth();
+  const { put, get } = useData();
+
+  const getPreferences = async () => {
+    if (!user) return null;
+    return get('user-preferences', user.id);
+  };
+
+  const updatePreferences = async (prefs: Partial<Preferences>) => {
+    if (!user) throw new Error('Not authenticated');
+    const current = await getPreferences() || { theme: 'dark', notifications: true };
+    return put('user-preferences', { id: user.id, ...current, ...prefs });
+  };
+
+  return { getPreferences, updatePreferences };
+}
+```
+
+### No bulk user import
+
+There is no self-service API to import existing users from another auth provider. For beta or new apps, users re-register. For production migrations, contact us for enterprise import.
+
+### API routes not protected by middleware
+
+`authMiddleware` and `authProxy` skip `/api` routes by design. Use `withAuth()` or `getAuth()` per-route — see [Server-Side Authentication](#server-side-authentication).
+
+### Migrating from Clerk?
+
+See the [Clerk Migration Guide](https://githat.io/docs/clerk-migration) for a step-by-step walkthrough of switching from Clerk to GitHat with zero downtime.
 
 ---