howone 0.1.23 → 0.1.25

package/templates/vite/.howone/skills/howone-sdk/03-sdk/03-auth.md

@@ -1,553 +1,372 @@
 # Auth
 
-## Two Auth Layers
+## Environment (read this first — dev must not hit prod)
 
-HowOne has two distinct auth layers:
+All auth APIs (`sendEmailVerificationCode`, `loginWithEmailCode`, `unifiedAuth.*`, `howone.auth.logout` revoke) use the **same `env` as `createClient`**, not the browser hostname and not a frozen default.
 
-1. **Client-level auth** (`client.auth.*`) — low-level token management, login/logout redirects.  
-2. **HowOne Auth service** (`unifiedAuth`, standalone functions) — headless OTP and OAuth flows for building custom login UIs.
-
-For React auth UI, see `03-sdk/04-react-integration.md` (`HowOneProvider`, `useHowoneContext`).
-
----
-
-## client.auth — Token Management
+| `VITE_HOWONE_ENV` / `createClient({ env })` | Auth REST API origin | Hosted login root (`auth: 'hosted'`) |
+|---------------------------------------------|----------------------|--------------------------------------|
+| `local` | `http://localhost:3002` | `https://howone.dev` |
+| `dev` | `https://api.howone.dev` | `https://howone.dev` |
+| `prod` | `https://api.howone.ai` | `https://howone.ai` |
 
 ```ts
-import howone from '@/lib/sdk'
+// src/lib/sdk.ts — canonical (no extra auth fields required)
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+})
+```
 
-// Check if the current user is authenticated
-howone.auth.isAuthenticated() // boolean
+Defaults when `auth` is omitted:
 
-// Get the current JWT token (null if not logged in)
-const token = howone.auth.getToken()
+- Auth mode: **hosted** — login/logout redirect to HowOne (`howone.dev` / `howone.ai` by `env`)
+- Auth APIs still follow `env` (`dev` → `api.howone.dev`, `prod` → `api.howone.ai`)
 
-// Manually set a token (after a custom login flow)
-howone.auth.setToken(jwtToken)
+Custom in-app login UI is **opt-in**: `auth: 'custom'` (see below).
 
-// Clear the token
-howone.auth.setToken(null)
+```ts
+// main.tsx
+import './lib/sdk' // registers env first
+import { sendEmailVerificationCode } from '@howone/sdk'
+```
 
-// Redirect to the HowOne login page
-howone.auth.login()
-howone.auth.login('/dashboard') // optional return path after login
+Rules for agents:
 
-// Log out and clear session
-howone.auth.logout()
-```
+- **Do not** hardcode `api.howone.ai` or `howone.ai` in app code.
+- **Do not** import auth helpers before `./lib/sdk` (env would stay default `prod`).
+- **Do not** rely on `localhost` hostname to pick `local`; use `env: 'local'` or `env: 'dev'` explicitly.
+- Entity, AI, upload, and auth endpoints all follow this single `env` pin.
 
 ---
 
-## User Profile
+## Custom login (opt-in only)
 
-```ts
-import { HowOneAuthError } from '@howone/sdk'
-import howone from '@/lib/sdk'
+Add `auth: 'custom'` when the app renders its own `/login` page but still uses HowOne OTP/OAuth APIs:
 
-type UserProfile = {
-  id: string       // backend owner id; same as userId when JWT has userId
-  userId?: string  // authenticated backend user id when present in JWT
-  puid?: string    // public UUID; do not use as public ownerId scope
-  email?: string
-  name?: string
-  avatarUrl?: string
-  appId?: string
-  roles?: string[]
-  metadata?: Record<string, unknown>
-}
+```ts
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+  auth: 'custom',
+  loginPath: '/login',
+})
+```
 
-// Returns null if not authenticated
-const user = await howone.me()
+That wires:
 
-// Returns the profile or throws HowOneAuthError if not authenticated
-const user = await howone.requireMe()
+| Behavior | Result |
+|----------|--------|
+| `howone.auth.logout()` | Clears token + revokes server session → stays on your app → navigates to `loginPath` |
+| `howone.auth.login()` | Navigates to `loginPath` (never howone.dev / howone.ai) |
+| `HowOneProvider` `useHowoneContext().logout()` | Same as `howone.auth.logout()` when `createClient` ran first |
 
-// Alias for me()
-const user = await howone.session.user()
+Pair with React:
 
-// Force refresh from server (skip cache)
-const user = await howone.me({ refresh: true })
+```tsx
+<HowOneProvider auth="none" brand="visible">
+  <App />
+</HowOneProvider>
 ```
 
-### Identity fields
-
-HowOne JWTs may contain both `userId` and `puid`. The SDK preserves both:
+`auth="none"` on the provider means **no automatic redirect**; route guards call `howone.me()` and `navigate('/login')` yourself. Keep `brand="visible"` unless the user explicitly asks to hide the bottom-right HowOne logo.
 
-- `user.id` / `user.userId` identifies the authenticated backend user.
-- `user.puid` is the public UUID and should not be used for entity owner filters.
-- `query.mine()` requires auth and lets the backend derive ownership from the JWT.
+| `createClient({ auth })` | Login UI | `auth.login()` | `auth.logout()` default redirect |
+|--------------------------|----------|----------------|----------------------------------|
+| *(omit)* | **HowOne hosted** | → howone `/auth` | → howone `/auth` |
+| `'custom'` | Your `/login` + HowOne APIs | → `loginPath` | → `loginPath` |
+| `'hosted'` | HowOne hosted (same as default) | → howone `/auth` | → howone `/auth` |
+| `'headless'` | External (Clerk, etc.) | no-op | no redirect |
+| `'none'` | N/A (public app) | no-op | no redirect |
 
-For public share URLs that need scoped owner data, use `howone.public.entities.*`
-and pass the schema-required public scope, usually the shared owner id stored on a record.
-Do not pass `puid` as `ownerId`.
+Legacy alias: `'managed'` → `'hosted'`.
 
-### Pattern: guard a page
+### Advanced object form
 
-```tsx
-import { useEffect, useState } from 'react'
-import { HowOneAuthError } from '@howone/sdk'
-import howone, { type UserProfile } from '@/lib/sdk'
-
-function useCurrentUser() {
-  const [user, setUser] = useState<UserProfile | null>(null)
-  const [loading, setLoading] = useState(true)
-
-  useEffect(() => {
-    howone.me()
-      .then(setUser)
-      .catch(err => {
-        if (err instanceof HowOneAuthError) {
-          howone.auth.login()
-        }
-      })
-      .finally(() => setLoading(false))
-  }, [])
-
-  return { user, loading }
+```ts
+auth: {
+  mode: 'custom',
+  loginPath: '/sign-in',
+  logoutPath: '/sign-in', // optional; defaults to loginPath
+  guard: 'required', // optional; use with HowOneProvider auth="required" for auto-redirect to loginPath
+  getToken: async () => null, // only for headless
 }
 ```
 
 ---
 
-## Email OTP Login
+## Two auth layers
 
-Use `sendEmailVerificationCode` → `loginWithEmailCode` to build a custom email login form.
+1. **`createClient({ auth })`** — strategy for login/logout destinations (hosted vs custom).
+2. **`unifiedAuth` / standalone OTP & OAuth functions** — headless APIs to build your login UI.
 
-The SDK normalizes HowOne auth envelopes. Both of these backend response shapes are valid:
+React: `HowOneProvider` + `useHowoneContext` — route guard only (`auth="required" | "optional" | "none"`).
 
-```ts
-{ success: true, token: 'jwt...' }
-{ code: 0, data: { success: true, token: 'jwt...' } }
-```
+The underlying SDK auth state is managed by `AuthManager`. App code normally uses `client.auth`,
+`client.me()`, `client.requireMe()`, and `HowOneProvider`; SDK contributors use `AuthAdapter` when
+custom token ownership is required.
 
-After normalization, read `result.success`, `result.token`, and `result.message` from the top level.
+---
 
-### Standalone functions (imported directly)
+## `client.auth` API
 
 ```ts
-import {
-  sendEmailVerificationCode,
-  loginWithEmailCode,
-} from '@howone/sdk'
+import howone from '@/lib/sdk'
 
-// Step 1 — send OTP
-const sendResult = await sendEmailVerificationCode(
-  'user@example.com',
-  'MyAppName', // optional, shown in the email
-)
-// sendResult.success: boolean
-// sendResult.expiresIn: number (seconds until expiry)
-// sendResult.message: string (error message if !success)
-// sendResult.code: number (business error code if any)
-
-// Step 2 — verify OTP and get token
-const loginResult = await loginWithEmailCode(
-  'user@example.com',
-  '123456', // 6-digit OTP from email
-)
-// loginResult.success: boolean
-// loginResult.token: string (JWT, present on success)
-// loginResult.user: { email, name? }
-// loginResult.redirect_url: string (if configured)
-// loginResult.message: string
-// loginResult.code: number
-
-if (loginResult.success && loginResult.token) {
-  howone.auth.setToken(loginResult.token)
-  // Persists the token and updates the active SDK client.
-}
+howone.auth.mode        // 'custom' | 'hosted' | 'headless' | 'none'
+howone.auth.guard       // 'required' | 'optional' | 'none'
+howone.auth.loginPath   // e.g. '/login'
+howone.auth.logoutPath  // e.g. '/login'
+
+howone.auth.setToken(jwt)
+howone.auth.getToken()
+howone.auth.isAuthenticated()
+
+howone.auth.login(returnUrl?)       // respects auth mode
+await howone.auth.logout()          // respects auth mode
+await howone.auth.clearSession()    // clear only; redirect: false
+await howone.auth.clearSession({ redirect: '/goodbye' })
+await howone.auth.logout({ redirect: false })
+howone.auth.subscribe((state) => {
+  // state: { token, user, isAuthenticated, isLoading }
+})
 ```
 
-### Using the unifiedAuth service
-
-```ts
-import { unifiedAuth } from '@howone/sdk'
+---
 
-// Same API as standalone functions
-const sendResult = await unifiedAuth.sendEmailVerificationCode(email, appName)
-const loginResult = await unifiedAuth.loginWithEmailCode(email, code)
+## AuthManager / AuthAdapter extension point
 
-// Verify an existing token
-const { valid, user } = await unifiedAuth.verifyToken(token)
+Use an adapter when the token is owned outside the default HowOne local session, for example an
+external auth provider, embedded shell, native app bridge, or custom host application.
 
-// Logout (server-side invalidation)
-await unifiedAuth.logout(token)
+```ts
+const client = createClient({
+  projectId,
+  env,
+  auth: {
+    mode: 'headless',
+    adapter: {
+      name: 'external-auth',
+      getToken: () => externalAuth.getToken(),
+      setToken: (token) => externalAuth.setToken(token),
+      getUser: async (token) => externalAuth.getUser(token),
+      login: ({ returnUrl } = {}) => {
+        router.push(`/login?redirect=${encodeURIComponent(returnUrl ?? '/')}`)
+      },
+      logout: () => {
+        externalAuth.clear()
+        router.push('/')
+      },
+      subscribe: (listener) => externalAuth.onChange(() => {
+        listener({
+          token: externalAuth.getToken(),
+          user: externalAuth.getUserSync(),
+          isAuthenticated: Boolean(externalAuth.getToken()),
+          isLoading: false,
+        })
+      }),
+    },
+    tokenCacheMs: 30_000,
+  },
+})
 ```
 
-### React component — email OTP form
-
-```tsx
-import { useState } from 'react'
-import { sendEmailVerificationCode, loginWithEmailCode } from '@howone/sdk'
-import howone from '@/lib/sdk'
-
-type Step = 'email' | 'code' | 'done'
-
-export function EmailLoginForm({ onSuccess }: { onSuccess: () => void }) {
-  const [step, setStep] = useState<Step>('email')
-  const [email, setEmail] = useState('')
-  const [code, setCode] = useState('')
-  const [loading, setLoading] = useState(false)
-  const [error, setError] = useState<string | null>(null)
-
-  async function handleSendCode(e: React.FormEvent) {
-    e.preventDefault()
-    setLoading(true)
-    setError(null)
-    try {
-      const result = await sendEmailVerificationCode(email)
-      if (!result.success) {
-        setError(result.message ?? 'Failed to send code')
-        return
-      }
-      setStep('code')
-    } finally {
-      setLoading(false)
-    }
-  }
-
-  async function handleVerifyCode(e: React.FormEvent) {
-    e.preventDefault()
-    setLoading(true)
-    setError(null)
-    try {
-      const result = await loginWithEmailCode(email, code)
-      if (!result.success || !result.token) {
-        setError(result.message ?? 'Invalid code')
-        return
-      }
-      howone.auth.setToken(result.token)
-      setStep('done')
-      onSuccess()
-    } finally {
-      setLoading(false)
-    }
-  }
-
-  if (step === 'email') {
-    return (
-      <form onSubmit={handleSendCode}>
-        <input
-          type="email"
-          value={email}
-          onChange={e => setEmail(e.target.value)}
-          placeholder="Enter your email"
-          required
-        />
-        {error && <p className="error">{error}</p>}
-        <button type="submit" disabled={loading}>
-          {loading ? 'Sending...' : 'Send Code'}
-        </button>
-      </form>
-    )
-  }
-
-  if (step === 'code') {
-    return (
-      <form onSubmit={handleVerifyCode}>
-        <p>Enter the code sent to {email}</p>
-        <input
-          type="text"
-          value={code}
-          onChange={e => setCode(e.target.value)}
-          placeholder="6-digit code"
-          maxLength={6}
-          required
-        />
-        {error && <p className="error">{error}</p>}
-        <button type="submit" disabled={loading}>
-          {loading ? 'Verifying...' : 'Login'}
-        </button>
-        <button type="button" onClick={() => setStep('email')}>
-          Back
-        </button>
-      </form>
-    )
-  }
+Adapter rules:
 
-  return <p>Login successful!</p>
-}
-```
+- Use `mode: 'headless'` for external token providers.
+- Use `mode: 'custom'` for in-app login pages that still call HowOne OTP/OAuth APIs.
+- Do not create extra token storage keys in app code. Route all token writes through `client.auth.setToken()`.
+- Do not implement app UI in the adapter. It may navigate or notify through callbacks, but visible UI belongs to the app.
+- `getToken` may be sync or async; the SDK caches external tokens according to `tokenCacheMs`.
+- `subscribe` is optional but recommended when the external auth provider can change outside SDK calls.
 
 ---
 
-## Phone OTP Login
+## Custom login page (full pattern for AI codegen)
 
-Same flow as email, using E.164 phone number format (e.g. `+14155552671`).
+### 1. SDK (`src/lib/sdk.ts`)
 
 ```ts
-import {
-  sendPhoneVerificationCode,
-  loginWithPhoneCode,
-} from '@howone/sdk'
+import { createClient, defineEntities, withEntities } from '@howone/sdk'
 
-// Step 1 — send SMS OTP
-const sendResult = await sendPhoneVerificationCode(
-  '+14155552671', // must be E.164 format
-  'MyAppName',    // optional
-)
-// sendResult.success: boolean
-// sendResult.expires_in: number (seconds)
-
-// Step 2 — verify OTP
-const loginResult = await loginWithPhoneCode(
-  '+14155552671',
-  '123456',
-)
-// loginResult.success: boolean
-// loginResult.token: string (JWT on success)
-// loginResult.user: { phone_e164?, email?, name? }
-
-if (loginResult.success && loginResult.token) {
-  howone.auth.setToken(loginResult.token)
-}
-```
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+})
 
-### Phone number validation note
+export default withEntities(client, defineEntities({ /* ... */ }))
+```
 
-The SDK validates that phone numbers are in E.164 format internally. Always pass the number with country code (e.g. `+1`, `+44`, `+86`).
+### 2. Provider (`main.tsx`)
 
----
+```tsx
+import { HowOneProvider } from '@howone/sdk/react'
+import './lib/sdk' // registers auth config
 
-## OAuth — Google and GitHub
+<HowOneProvider auth="none" brand="visible">
+  <App />
+</HowOneProvider>
+```
 
-### Google Login
+### 3. Login route (`/login`) — your styles, HowOne APIs
 
-```ts
-import { unifiedAuth } from '@howone/sdk'
+```tsx
+import {
+  sendEmailVerificationCode,
+  loginWithEmailCode,
+  unifiedAuth,
+} from '@howone/sdk'
 import howone from '@/lib/sdk'
 
-async function loginWithGoogle() {
-  // Opens a popup window for Google OAuth
-  const result = await unifiedAuth.initiateGoogleLogin()
-  // result.token: string (JWT)
-  // result.user: any
-
+// Email OTP
+const send = await sendEmailVerificationCode(email)
+const result = await loginWithEmailCode(email, code)
+if (result.success && result.token) {
   howone.auth.setToken(result.token)
+  const user = await howone.me({ refresh: true })
+  navigate('/')
 }
-```
-
-### GitHub Login
 
-```ts
-import { unifiedAuth } from '@howone/sdk'
+// Google (popup — user stays on your page)
+const { token } = await unifiedAuth.initiateGoogleLogin()
+howone.auth.setToken(token)
 
-async function loginWithGitHub() {
-  const result = await unifiedAuth.initiateGitHubLogin()
-  howone.auth.setToken(result.token)
-}
+// GitHub
+const { token } = await unifiedAuth.initiateGitHubLogin()
+howone.auth.setToken(token)
 ```
 
-### Handle OAuth redirect callback
+Phone OTP: `sendPhoneVerificationCode` + `loginWithPhoneCode` (E.164, e.g. `+8613800138000`).
 
-If you redirect instead of using a popup, call `checkOAuthCallback()` on the return page:
+OAuth full-page callback (optional route `/auth/callback`):
 
 ```ts
 import { unifiedOAuth } from '@howone/sdk'
-import howone from '@/lib/sdk'
 
-// Call on the OAuth callback page (e.g. /auth/callback)
-function handleOAuthReturn() {
-  const result = unifiedOAuth.checkOAuthCallback()
-  // result.success: boolean
-  // result.token: string (if success)
-  // result.error: string (if failure)
-  // result.user: any
-
-  if (result.success && result.token) {
-    howone.auth.setToken(result.token)
-    window.location.href = '/dashboard'
-  } else {
-    console.error('OAuth failed:', result.error)
-  }
+const result = unifiedOAuth.checkOAuthCallback()
+if (result.success && result.token) {
+  howone.auth.setToken(result.token)
+  navigate('/')
 }
 ```
 
-### React — OAuth buttons
+### 4. Protected routes
 
 ```tsx
-import { unifiedAuth } from '@howone/sdk'
-import howone from '@/lib/sdk'
-
-export function OAuthButtons({ onSuccess }: { onSuccess: () => void }) {
-  const [loading, setLoading] = useState<'google' | 'github' | null>(null)
-  const [error, setError] = useState<string | null>(null)
-
-  async function handleGoogle() {
-    setLoading('google')
-    setError(null)
-    try {
-      const { token } = await unifiedAuth.initiateGoogleLogin()
-      howone.auth.setToken(token)
-      onSuccess()
-    } catch (err) {
-      setError(err instanceof Error ? err.message : 'Google login failed')
-    } finally {
-      setLoading(null)
-    }
-  }
-
-  async function handleGitHub() {
-    setLoading('github')
-    setError(null)
-    try {
-      const { token } = await unifiedAuth.initiateGitHubLogin()
-      howone.auth.setToken(token)
-      onSuccess()
-    } catch (err) {
-      setError(err instanceof Error ? err.message : 'GitHub login failed')
-    } finally {
-      setLoading(null)
-    }
-  }
-
-  return (
-    <div>
-      <button onClick={handleGoogle} disabled={loading !== null}>
-        {loading === 'google' ? 'Connecting...' : 'Continue with Google'}
-      </button>
-      <button onClick={handleGitHub} disabled={loading !== null}>
-        {loading === 'github' ? 'Connecting...' : 'Continue with GitHub'}
-      </button>
-      {error && <p className="error">{error}</p>}
-    </div>
-  )
-}
+useEffect(() => {
+  howone.me()
+    .then(setUser)
+    .catch(() => navigate('/login', { replace: true }))
+}, [])
 ```
 
----
+Use `howone.me()`, not `howone.auth.isAuthenticated()`, for first load.
 
-## Token Verification
+### 5. Logout button
 
 ```ts
-import { unifiedAuth } from '@howone/sdk'
-
-async function checkToken(token: string) {
-  const { valid, user } = await unifiedAuth.verifyToken(token)
-  if (valid) {
-    console.log('User:', user)
-  } else {
-    console.log('Token is invalid or expired')
-  }
-}
+await howone.auth.logout()
+// custom mode: already navigates to loginPath; no howone.dev redirect
 ```
 
-## Custom Login UI Pattern
+Do **not** call hosted-only patterns when `auth: 'custom'` is set:
 
-Use this when the app should show its own login page instead of redirecting to `/howone/auth`.
+- ~~`howone.auth.login()` expecting howone.ai~~ (goes to `/login` instead — OK)
+- ~~Manual `window.location` to howone.dev~~
 
-### SDK setup
+---
 
-```ts
-// src/lib/sdk.ts
-import { createClient } from '@howone/sdk'
+## Hosted login (default)
 
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
-  env: import.meta.env.VITE_HOWONE_ENV,
-  auth: { mode: 'managed' },
-})
+Omit `auth` — this is the default for `createClient({ projectId, env })`:
 
-export default client
+```ts
+createClient({ projectId, env })
 ```
 
-`managed` is still correct for most custom login pages because `howone.auth.setToken(token)`
-persists the token through the SDK auth store. Use `headless` only when an external auth
-provider owns token storage.
-
-### Provider setup
-
 ```tsx
-<HowOneProvider auth="none" brand="hidden">
+<HowOneProvider auth="required">
   <App />
 </HowOneProvider>
 ```
 
-`auth="none"` disables the provider redirect so the app can render its own login form.
+Unauthenticated users redirect to HowOne hosted `/auth`.
 
-### App startup
+---
 
-```tsx
-useEffect(() => {
-  let cancelled = false
+## Headless external auth
 
-  howone.me()
-    .then((user) => {
-      if (!cancelled) setUser(user)
-    })
-    .catch(() => {
-      if (!cancelled) setUser(null)
-    })
-    .finally(() => {
-      if (!cancelled) setLoading(false)
-    })
-
-  return () => {
-    cancelled = true
-  }
-}, [])
+```ts
+createClient({
+  projectId,
+  env,
+  auth: {
+    mode: 'headless',
+    adapter: {
+      getToken: async () => externalAuth.getJwt(),
+      login: ({ returnUrl } = {}) => externalAuth.login({ returnUrl }),
+      logout: () => externalAuth.logout(),
+    },
+    tokenCacheMs: 30_000,
+  },
+})
 ```
 
-Do not use `howone.auth.isAuthenticated()` as the first-load gate for protected UI. It is a
-synchronous token presence check. `howone.me()` verifies/restores the current session and is the
-right source of truth for initial render.
+Do not use `howone.auth.setToken` for Clerk/Supabase unless bridging into HowOne JWT.
+
+Headless mode should not redirect to HowOne hosted auth by default. The external adapter decides
+what `login` and `logout` mean.
+
+---
+
+## Email / phone / OAuth API reference
+
+(Same as before — see sections below for request/response shapes.)
 
-### Login success
+### Email OTP
 
 ```ts
-const result = await loginWithEmailCode(email, code)
-if (!result.success || !result.token) {
-  setError(result.message ?? 'Invalid code')
-  return
-}
+import { sendEmailVerificationCode, loginWithEmailCode } from '@howone/sdk'
 
-howone.auth.setToken(result.token)
-const user = await howone.me({ refresh: true })
-setUser(user)
+await sendEmailVerificationCode(email, appName?)
+const result = await loginWithEmailCode(email, code)
+// result.token on success → howone.auth.setToken(result.token)
 ```
 
-Use the same pattern for phone OTP and OAuth popup results.
-
-### Logout
+### Phone OTP
 
 ```ts
-const token = howone.auth.getToken()
-if (token) await unifiedAuth.logout(token)
-howone.auth.logout()
-setUser(null)
+import { sendPhoneVerificationCode, loginWithPhoneCode } from '@howone/sdk'
 ```
 
-`howone.auth.logout()` clears the SDK token store and active client token.
+### OAuth popup
+
+```ts
+import { unifiedAuth } from '@howone/sdk'
 
-## Headless External Auth Pattern
+await unifiedAuth.initiateGoogleLogin()
+await unifiedAuth.initiateGitHubLogin()
+```
 
-Use `auth.mode = "headless"` only when another auth system owns the token lifecycle.
+### Server logout
 
 ```ts
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
-  env: import.meta.env.VITE_HOWONE_ENV,
-  auth: {
-    mode: 'headless',
-    getToken: async () => externalAuth.getJwt(),
-    tokenCacheMs: 30_000,
-  },
-})
+import { unifiedAuth } from '@howone/sdk'
+
+const token = howone.auth.getToken()
+if (token) await unifiedAuth.logout(token)
+await howone.auth.logout()
 ```
 
-Do not invent a second localStorage key for HowOne OTP/OAuth login. Use `howone.auth.setToken`
-unless the user explicitly asks to integrate an external auth provider.
+With `auth: 'custom'`, `howone.auth.logout()` already revokes and navigates locally.
 
 ---
 
-## Logout
+## User profile
 
 ```ts
-// Client-side logout (clears local token storage)
-howone.auth.logout()
-
-// Server-side invalidation via unifiedAuth
-await unifiedAuth.logout(token)
+const user = await howone.me()
+const user = await howone.requireMe() // throws HowOneAuthError
 ```
 
 ---
@@ -558,59 +377,38 @@ await unifiedAuth.logout(token)
 import { HowOneAuthError } from '@howone/sdk'
 
 try {
-  const user = await howone.requireMe()
+  await howone.requireMe()
 } catch (err) {
   if (err instanceof HowOneAuthError) {
-    // err.code === 'UNAUTHENTICATED'
-    howone.auth.login('/current-page')
+    howone.auth.login() // custom → /login; hosted → howone.ai
   }
 }
 ```
 
 ---
 
-## Auth Mode in createClient
-
-Choose the auth mode that matches your login strategy:
-
-```ts
-// Managed (default) — SDK owns the token lifecycle
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
-  env: import.meta.env.VITE_HOWONE_ENV,
-  auth: { mode: 'managed' },
-})
+## Common mistakes (AI agents)
 
-// Headless — you own the token (for Clerk, Supabase, custom JWTs, etc.)
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
-  env: import.meta.env.VITE_HOWONE_ENV,
-  auth: {
-    mode: 'headless',
-    getToken: async () => {
-      return localStorage.getItem('auth_token')
-    },
-    tokenCacheMs: 30_000,
-  },
-})
-
-// None — unauthenticated, public API access only
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
-  env: import.meta.env.VITE_HOWONE_ENV,
-  auth: { mode: 'none' },
-})
-```
+| Mistake | Fix |
+|---------|-----|
+| Custom `/login` page with HowOne OTP/OAuth | Add `auth: 'custom'` in `createClient` |
+| `HowOneProvider auth="required"` + custom login | Use `auth="none"`; guard with `howone.me()` |
+| `howone.auth.logout()` expecting no redirect before this change | Now respects `auth: 'custom'` |
+| `auth.isAuthenticated()` on first paint | Use `await howone.me()` |
+| Phone without country code | E.164 `+86...` |
+| JSON Schema in `defineAiAction` | Convert manifest JSON Schema to Zod |
+| Second localStorage key for token | Only `howone.auth.setToken` |
+| Custom external provider wired with `getToken` only but no logout | Add an `adapter.logout` if the host owns session clearing |
+| App UI inside SDK auth adapter | Move UI to frontend components and use callbacks/navigation only |
 
 ---
 
-## Common Mistakes
+## Non-negotiable for agents
 
-| Mistake | Correct Pattern |
-|---|---|
-| Phone number without country code: `'13800138000'` | Use E.164: `'+8613800138000'` |
-| Using `loginWithEmailCode` without first calling `sendEmailVerificationCode` | Always send the code first |
-| Hand-writing a separate localStorage token key for HowOne OTP/OAuth | Use `howone.auth.setToken(token)` |
-| Using `auth.isAuthenticated()` to decide first render after refresh | Use `await howone.me()` |
-| Setting `HowOneProvider auth="required"` with a custom in-app login form | Use `auth="none"` so the provider does not redirect |
-| Calling `unifiedAuth.logout()` without the token argument | Pass `token`: `await unifiedAuth.logout(howone.auth.getToken()!)` |
+- Default **`createClient({ projectId, env })`** = HowOne hosted login. Add **`auth: 'custom'`** only for in-app login pages.
+- Never hardcode howone.dev / howone.ai URLs in app login/logout when `auth: 'custom'`.
+- Implement login UI with `sendEmailVerificationCode` / `loginWithEmailCode` / `unifiedAuth` — not iframe to hosted auth.
+- After any successful login: `howone.auth.setToken(token)` then `await howone.me({ refresh: true })`.
+- Logout: `await howone.auth.logout()` only (no manual redirect needed when `auth: 'custom'`).
+- For external auth, use `auth.adapter`; do not patch request headers manually.
+- SDK auth exposes state/callbacks only. Visible feedback, loading spinners, account menus, and errors are frontend app code.