docs: add copy-paste AI prompts (#273)

Author: onmax

docs/app/components/content/CodeCollapse.vue

@@ -0,0 +1,14 @@
+<script setup lang="ts">
+const open = ref(false)
+</script>
+
+<template>
+  <UCollapsible v-model:open="open" class="my-4">
+    <UButton variant="ghost" size="sm" :icon="open ? 'i-lucide-chevron-down' : 'i-lucide-chevron-right'" trailing-icon="i-lucide-sparkles" label="AI Prompt" @click="open = !open" />
+    <template #content>
+      <div class="pt-2">
+        <ContentSlot :use="$slots.default" unwrap="p" />
+      </div>
+    </template>
+  </UCollapsible>
+</template>

docs/content/1.getting-started/1.installation.md

@@ -4,6 +4,24 @@ description: Learn how to add Nuxt Better Auth to your Nuxt project.
 navigation.icon: i-lucide-download
 ---
 
+::code-collapse
+
+```txt [Prompt]
+Install @onmax/nuxt-better-auth in my Nuxt 4 app.
+
+- Run `npx nuxi module add @onmax/nuxt-better-auth@alpha`
+- Set `BETTER_AUTH_SECRET` in `.env` (at least 32 chars, high entropy). Optionally prefix with `NUXT_` for runtime config
+- Optionally set `NUXT_PUBLIC_SITE_URL` for non-auto-detected platforms
+- Create `server/auth.config.ts` using `defineServerAuth` from `@onmax/nuxt-better-auth/config`
+- Create `app/auth.config.ts` using `defineClientAuth` from `@onmax/nuxt-better-auth/config`
+- The module auto-injects `secret` and `baseURL` — do not configure them manually
+
+Read more: https://better-auth.nuxt.dev/raw/getting-started/installation.md
+Source: https://github.com/nuxt-modules/better-auth
+```
+
+::
+
 ## Prerequisites
 
 - Nuxt v4.0+

docs/content/1.getting-started/2.configuration.md

@@ -4,6 +4,25 @@ description: Configure the module options and your Better Auth server instance.
 navigation.icon: i-lucide-settings
 ---
 
+::code-collapse
+
+```txt [Prompt]
+Configure @onmax/nuxt-better-auth module options and server auth.
+
+- In `nuxt.config.ts`, set `auth.redirects` (login, guest, authenticated, logout) and `auth.preserveRedirect`
+- Use `routeRules` or `nitro.routeRules` to define per-route auth: `{ auth: { only: 'user', redirectTo: '/login' } }`
+- In `server/auth.config.ts`, use `defineServerAuth` (object or function syntax) to configure plugins and providers
+- The function syntax receives `ctx` with `runtimeConfig` and `db` (NuxtHub)
+- The module auto-injects `secret` and `baseURL` — do not set them in defineServerAuth
+- Base URL priority: runtimeConfig > request URL > platform env vars > localhost
+- Set `NUXT_PUBLIC_SITE_URL` for custom domains or deterministic OAuth callbacks
+
+Read more: https://better-auth.nuxt.dev/raw/getting-started/configuration.md
+Source: https://github.com/nuxt-modules/better-auth
+```
+
+::
+
 ## Module Configuration
 
 ```ts [nuxt.config.ts]

docs/content/1.getting-started/3.client-setup.md

@@ -4,6 +4,23 @@ description: Configure the client-side authentication client.
 navigation.icon: i-lucide-monitor
 ---
 
+::code-collapse
+
+```txt [Prompt]
+Set up the client auth config for @onmax/nuxt-better-auth.
+
+- Create `app/auth.config.ts` with a default export using `defineClientAuth` from `@onmax/nuxt-better-auth/config`
+- Object syntax: `defineClientAuth({})` or function syntax: `defineClientAuth(({ siteUrl }) => ({}))`
+- Add client plugin equivalents for every server plugin (e.g. `adminClient()` from `better-auth/client/plugins`)
+- The module calls the factory with the correct `baseURL` at runtime
+- `useUserSession()` is auto-imported and provides `user`, `session`, `loggedIn`, `ready`, `signIn`, `signUp`, `signOut`
+
+Read more: https://better-auth.nuxt.dev/raw/getting-started/client-setup.md
+Source: https://github.com/nuxt-modules/better-auth
+```
+
+::
+
 ## Create the Client Config
 
 Create `app/auth.config.ts` with a default export using `defineClientAuth`.

docs/content/1.getting-started/4.type-augmentation.md

@@ -4,6 +4,23 @@ description: Learn how the module automatically infers types from your configura
 navigation.icon: i-lucide-type
 ---
 
+::code-collapse
+
+```txt [Prompt]
+Set up type augmentation for @onmax/nuxt-better-auth plugins.
+
+- Types are automatically inferred from plugins in `server/auth.config.ts` — no extra config needed
+- For manual augmentation, create `nuxt-better-auth.d.ts` next to `nuxt.config.ts`
+- Import `#nuxt-better-auth` and declare module to extend `AuthUser` or `AuthSession` interfaces
+- If types don't update: restart TS server, run `npx nuxi prepare`, check config for syntax errors
+- Ensure `.d.ts` files are included by TypeScript (`tsconfig.json` include or `/// <reference>`)
+
+Read more: https://better-auth.nuxt.dev/raw/getting-started/type-augmentation.md
+Source: https://github.com/nuxt-modules/better-auth
+```
+
+::
+
 When you add Better Auth plugins that extend the user or session objects, TypeScript needs to know about these new fields. The module automatically infers types from your configuration, but you can also augment types manually.
 
 ## Automatic Type Inference

docs/content/1.getting-started/5.schema-generation.md

@@ -5,6 +5,24 @@ description: Auto-generate Drizzle ORM schemas for Better Auth tables when using
 navigation.icon: i-lucide-database
 ---
 
+::code-collapse
+
+```txt [Prompt]
+Set up auto schema generation for @onmax/nuxt-better-auth with NuxtHub.
+
+- Requires NuxtHub integration — the module generates Drizzle ORM schemas at build time
+- Supports sqlite (default), postgresql, and mysql dialects via `hub.db.dialect` in `nuxt.config.ts`
+- The module reads `server/auth.config.ts` plugins to determine required tables (user, session, account, verification + plugin tables)
+- After adding/removing plugins: restart the dev server to regenerate schemas
+- For production (Cloudflare D1): run `npx nuxt db migrate`
+- No manual Drizzle schema writing needed for auth tables
+
+Read more: https://better-auth.nuxt.dev/raw/getting-started/schema-generation.md
+Source: https://github.com/nuxt-modules/better-auth
+```
+
+::
+
 ::note
 This feature requires **NuxtHub**. See [NuxtHub Integration](/integrations/nuxthub) for setup.
 ::

docs/content/2.core-concepts/1.server-auth.md

@@ -3,6 +3,23 @@ title: serverAuth()
 description: When to reach for the full Better Auth server instance.
 ---
 
+::code-collapse
+
+```txt [Prompt]
+Use server-side auth utilities in @onmax/nuxt-better-auth.
+
+- `serverAuth(event?)` — returns the Better Auth instance. Pass `event` in Nitro handlers for request-aware base URLs
+- `getUserSession(event)` — get current session (auto-imported in `server/`)
+- `requireUserSession(event, options?)` — throws 401 if not authenticated, supports role matching
+- `getRequestSession(event)` — request-cached session, preferred over repeated `getUserSession` in same request
+- All server utils are auto-imported, no import statements needed
+
+Read more: https://better-auth.nuxt.dev/raw/core-concepts/server-auth.md
+Source: https://github.com/nuxt-modules/better-auth
+```
+
+::
+
 `serverAuth(event?)` returns the Better Auth instance (module-level singleton). In Nitro handlers, you should pass `event` so the module can resolve request-aware base URLs on initialization. Outside request contexts (seed scripts, tasks, plugins), you can call `serverAuth()` without an event.
 
 ## When to Use What

docs/content/2.core-concepts/2.sessions.md

@@ -3,6 +3,25 @@ title: Sessions
 description: Access reactive session state with SSR support using `useUserSession()`.
 ---
 
+::code-collapse
+
+```txt [Prompt]
+Handle sessions with @onmax/nuxt-better-auth using useUserSession().
+
+- `useUserSession()` is auto-imported and returns: user, session, loggedIn, ready, signIn, signUp, signOut, fetchSession
+- SSR: session is fetched server-side via cookies and hydrated — `ready` is `true` after hydration
+- Client: `.client` is `null` during SSR, available after hydration
+- Split model: use `useUserSession()` in pages/components, use `requireUserSession(event)` in server handlers
+- Configure session lifetime in `server/auth.config.ts` via `session.expiresIn` and `session.cookieCache`
+- Use `<BetterAuthState>` or `ready` ref to avoid loading flashes
+- Force refresh: `fetchSession({ force: true })`
+
+Read more: https://better-auth.nuxt.dev/raw/core-concepts/sessions.md
+Source: https://github.com/nuxt-modules/better-auth
+```
+
+::
+
 ```ts [pages/dashboard.vue]
 const {
   user,

docs/content/2.core-concepts/3.route-protection.md

@@ -3,6 +3,26 @@ title: Route Protection
 description: Learn how to protect your pages and API routes using a layered approach.
 ---
 
+::code-collapse
+
+```txt [Prompt]
+Protect routes and API endpoints with @onmax/nuxt-better-auth.
+
+- Route Rules in `nuxt.config.ts`: `routeRules: { '/app/**': { auth: { only: 'user', redirectTo: '/login' } } }`
+- Guest-only pages: `{ auth: { only: 'guest', redirectTo: '/app' } }`
+- Role-based: `{ auth: { user: { role: 'admin' } } }` — arrays use OR logic
+- Page Meta: `definePageMeta({ auth: 'user' })` for per-page control
+- Server API: `await requireUserSession(event)` — throws 401 if not authenticated
+- Role + custom rules: `requireUserSession(event, { user: { role: 'admin' }, rule: ({ user }) => user.verified })`
+- Route rules auto-sync to client router for instant redirects
+- Always protect API endpoints with `requireUserSession` — route rules are UX only
+
+Read more: https://better-auth.nuxt.dev/raw/core-concepts/route-protection.md
+Source: https://github.com/nuxt-modules/better-auth
+```
+
+::
+
 ## Quick Reference
 
 | Method | Scope | Use Case |

docs/content/2.core-concepts/4.auto-imports-aliases.md

@@ -3,6 +3,23 @@ title: Auto‑Imports and Aliases
 description: What the module registers for you.
 ---
 
+::code-collapse
+
+```txt [Prompt]
+Use auto-imported utilities from @onmax/nuxt-better-auth.
+
+- Client (auto-imported in Vue): `useUserSession()`, `useSignIn()`, `useSignUp()`
+- Server (auto-imported in `server/`): `serverAuth(event?)`, `getRequestSession(event)`, `getUserSession(event)`, `requireUserSession(event, options?)`
+- Component: `<BetterAuthState>` for auth-ready rendering
+- Alias `#nuxt-better-auth` exports types: `AuthUser`, `AuthSession`, `AuthSocialProviderId`
+- Use `getRequestSession(event)` over repeated `getUserSession(event)` calls — it caches per request
+
+Read more: https://better-auth.nuxt.dev/raw/core-concepts/auto-imports-aliases.md
+Source: https://github.com/nuxt-modules/better-auth
+```
+
+::
+
 ## Auto‑imports
 
 **Client**