feat(nuxt-better-auth): optional app session enrich hook

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

@@ -137,6 +137,12 @@ export default defineServerAuth((ctx) => ({
 }))
 ```
 
+### Session Enrichment
+
+You can enrich session payloads with Better Auth's `custom-session` plugin through `plugins` in `defineServerAuth`. This module does not provide a separate `appSession.enrich` option.
+
+See the full recipe in [Server Utilities](/api/server-utils#session-enrichment-with-custom-session).
+
 ## Base URL Configuration
 
 The module resolves `siteUrl` using this priority:

docs/content/5.api/2.server-utils.md

@@ -55,6 +55,35 @@ export default defineEventHandler(async (event) => {
 - `{ user: AuthUser, session: AuthSession }` if authenticated.
 - `null` if unauthenticated.
 
+## Session Enrichment with `custom-session`
+
+Use Better Auth's `custom-session` plugin when your app needs computed fields in the session payload returned by server helpers. Define the enrichment in `server/auth.config.ts`, and `getUserSession` or `getAppSession` will return the enriched shape.
+
+```ts [server/auth.config.ts]
+import { customSession } from 'better-auth/plugins'
+import { defineServerAuth } from '@onmax/nuxt-better-auth/config'
+
+export default defineServerAuth({
+  plugins: [
+    customSession(async ({ user, session }) => {
+      return {
+        user: {
+          ...user,
+          role: user.email?.endsWith('@company.com') ? 'member' : 'guest',
+        },
+        session: {
+          ...session,
+        },
+      }
+    }),
+  ],
+})
+```
+
+::note
+This uses Better Auth's plugin API and does not require a module-specific option.
+::
+
 ## requireUserSession
 
 Ensures the user is authenticated and optionally matches specific criteria. Throws a `401 Unauthorized` or `403 Forbidden` error if checks fail.