docs: improve published auth skill (#406)

Author: onmax

docs/public/.well-known/skills/index.json

@@ -1,7 +1,7 @@
 {
   "skills": [{
     "name": "nuxt-better-auth",
-    "description": "Use when implementing auth in Nuxt apps with @nuxtjs/better-auth - provides client composables, server helpers, route protection, session refresh helpers, and Better Auth plugin integration.",
+    "description": "Guides authentication in Nuxt apps using @nuxtjs/better-auth. Use when installing or configuring the module, using its client or server APIs, protecting routes, refreshing sessions, or integrating Better Auth plugins.",
     "files": [
       "SKILL.md",
       "references/client-auth.md",

docs/public/.well-known/skills/nuxt-better-auth/SKILL.md

@@ -1,99 +1,37 @@
 ---
 name: nuxt-better-auth
-description: Use when implementing auth in Nuxt apps with @nuxtjs/better-auth - provides client composables, server helpers, route protection, session refresh helpers, and Better Auth plugin integration.
+description: Guides authentication in Nuxt apps using @nuxtjs/better-auth. Use when installing or configuring the module, using its client or server APIs, protecting routes, refreshing sessions, or integrating Better Auth plugins.
 license: MIT
 ---
 
 # Nuxt Better Auth
 
-Authentication module for Nuxt built on [Better Auth](https://www.better-auth.com/). It adds Nuxt-specific setup, route protection, server helpers, and typed auth state.
+Use the smallest reference that matches the task.
 
-> Alpha status: the package is still pre-stable. Verify behavior against the current docs and source before relying on edge cases.
+## Pick a reference
 
-## When to Use
+| Task | Read |
+| --- | --- |
+| Install the module, configure environment variables, or create config files | [references/installation.md](references/installation.md) |
+| Read client session state, build auth forms, call plugins, or fetch auth-bound data | [references/client-auth.md](references/client-auth.md) |
+| Read or enforce sessions in server handlers, create sessions, or refresh cached session data | [references/server-auth.md](references/server-auth.md) |
+| Protect pages or API routes and configure redirects | [references/route-protection.md](references/route-protection.md) |
+| Register Better Auth plugins and their client companions | [references/plugins.md](references/plugins.md) |
+| Configure NuxtHub, generated schema, or secondary storage | [references/database.md](references/database.md) |
+| Connect a Nuxt frontend to an external Better Auth server | [references/client-only.md](references/client-only.md) |
+| Use inferred auth types or add project fields | [references/types.md](references/types.md) |
 
-- Installing/configuring `@nuxtjs/better-auth`
-- Implementing sign-in, sign-up, sign-out, or custom auth flows
-- Protecting routes (client and server)
-- Accessing user session in API routes
-- Refreshing session state after custom auth endpoints or server-side session changes
-- Integrating Better Auth plugins (admin, passkey, 2FA)
-- Setting up database with NuxtHub
-- Using clientOnly mode for external auth backends
+## Rules that apply across tasks
 
-## Available Guidance
+- Confirm the consumer's installed package version supports each API you use. The published skill may be newer than the consumer's lockfile.
+- Enforce protected API reads and mutations server-side with `requireUserSession(event)`. Route rules and page meta also control navigation.
+- Navigate only to validated local redirect paths.
+- In `clientOnly` mode, do not use local server helpers or expect SSR session hydration.
+- After server-side changes to session payload fields, call `refreshSessionCookieCache(event)`. Wrap custom client auth endpoints that create or change the current session with `runWithSessionRefresh()`.
 
-| File                                                                 | Topics                                                                 |
-| -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| **[references/installation.md](references/installation.md)**         | install flow, env vars, config files                                   |
-| **[references/client-auth.md](references/client-auth.md)**           | `useUserSession`, client methods, redirects, loading states, custom actions |
-| **[references/server-auth.md](references/server-auth.md)**           | `serverAuth`, session helpers, `refreshSessionCookieCache`, API enforcement |
-| **[references/route-protection.md](references/route-protection.md)** | route rules, page meta, API protection                                 |
-| **[references/plugins.md](references/plugins.md)**                   | plugin pairing between server and client                               |
-| **[references/database.md](references/database.md)**                 | NuxtHub schema generation, secondary storage                           |
-| **[references/client-only.md](references/client-only.md)**           | external Better Auth backends and `clientOnly` mode                    |
-| **[references/types.md](references/types.md)**                       | public auth types and augmentation                                     |
-
-## Usage Pattern
-
-- Installing module? → [references/installation.md](references/installation.md)
-- Login/signup forms? → [references/client-auth.md](references/client-auth.md)
-- API route protection? → [references/server-auth.md](references/server-auth.md)
-- Route rules/page meta? → [references/route-protection.md](references/route-protection.md)
-- Using plugins? → [references/plugins.md](references/plugins.md)
-- Database setup? → [references/database.md](references/database.md)
-- External auth backend? → [references/client-only.md](references/client-only.md)
-- TypeScript types? → [references/types.md](references/types.md)
-
-Do not load every reference file by default. Pick the smallest file that matches the task.
-
-## Key Concepts
-
-| Concept                | Description                                                     |
-| ---------------------- | --------------------------------------------------------------- |
-| `useUserSession()`     | Client composable - user, session, loggedIn, refresh, sign-out |
-| `runWithSessionRefresh()` | Refresh local session after custom auth endpoints |
-| `requireUserSession()` | Server helper - throws 401/403 if not authenticated             |
-| `refreshSessionCookieCache()` | Refresh Better Auth's cached session cookie after server updates |
-| `auth` route mode      | `'user'`, `'guest'`, `{ user: {...} }`, or `false`              |
-| `serverAuth()`         | Get Better Auth instance in server routes                       |
-
-## Quick Reference
-
-```ts
-// Client: useUserSession()
-const { user, loggedIn, signIn, signOut } = useUserSession()
-await signIn.email({ email, password }, { onSuccess: () => navigateTo('/') })
-```
-
-```ts
-// Client: custom auth endpoint
-await runWithSessionRefresh(() => $fetch('/api/custom-login', { method: 'POST', body }))
-```
-
-```ts
-// Server: requireUserSession()
-const { user } = await requireUserSession(event, { user: { role: 'admin' } })
-```
-
-```ts
-// Server: after updating fields returned by session helpers
-await updateCurrentUser(event)
-await refreshSessionCookieCache(event)
-```
-
-```ts
-// nuxt.config.ts: Route protection
-routeRules: {
-  '/admin/**': { auth: { user: { role: 'admin' } } },
-  '/login': { auth: 'guest' },
-  '/app/**': { auth: 'user' }
-}
-```
-
-Broad rules such as `'/**': { auth: 'user' }` skip framework/module internals like `/_nuxt/**`, `/_ipx/**`, `/api/auth/**`, `/api/_better-auth/**`, and `/api/_nuxt_icon/**`.
+Before finishing an implementation, run the consumer's typecheck and the narrowest relevant auth test.
 
 ## Resources
 
 - [Documentation site](https://better-auth.nuxt.dev)
-- [Better Auth Docs](https://www.better-auth.com/)
+- [Better Auth docs](https://www.better-auth.com/)

docs/public/.well-known/skills/nuxt-better-auth/references/client-auth.md

@@ -1,15 +1,28 @@
 # Client-side authentication
 
-## Primary entry points
+## Choose an API
+
+| Need | API |
+| --- | --- |
+| Session state and lifecycle actions | `useUserSession()` |
+| Direct Better Auth client or plugin methods | `useAuthClient()` |
+| Sign-in or sign-up form state | `useSignIn()` or `useSignUp()` |
+| Action state for a client or plugin method | `useAuthClientAction()` |
+| Action state for any async function | `useAction()` |
+| Refresh session state after a custom auth endpoint | `runWithSessionRefresh()` |
+| Request-scoped auth fetch with typed endpoints | `useAuthRequestFetch()` |
+| SSR-safe auth-bound data | `useAuthAsyncData()` |
+
+`useUserSessionState()` is a deprecated alias for `useUserSession()`.
+
+## Session state and direct client access
 
 ```ts
 const { user, session, loggedIn, ready, fetchSession, signOut, updateUser } = useUserSession()
 const client = useAuthClient()
 ```
 
-`useUserSession()` is the store-safe session API. It returns auth state plus session lifecycle actions. It does not expose raw Better Auth client namespaces.
-
-Use `useAuthClient()` when you need direct Better Auth client/plugin methods. It returns the client in the browser and `null` during SSR.
+`useUserSession()` is safe to return from a Pinia setup store. `useAuthClient()` returns the client in the browser and `null` during SSR.
 
 ## Sign-in and sign-up forms
 
@@ -40,6 +53,8 @@ const openPortal = useAuthClientAction(client => client.customer.portal)
 await openPortal.execute()
 ```
 
+Use `useAction()` for the same action state around an arbitrary async function.
+
 ## Custom auth endpoints
 
 Use `runWithSessionRefresh()` around custom endpoints that create or change the current session.
@@ -55,6 +70,26 @@ await runWithSessionRefresh(() =>
 
 The helper awaits your request, then refreshes local session state unless the result is a Better Auth action error result.
 
+## Auth-bound data
+
+Use `useAuthRequestFetch()` for low-level request control. During SSR it forwards the request context, including cookies.
+
+The endpoint below comes from a configured custom customer plugin. Replace it with an endpoint generated by the consumer's Better Auth config.
+
+```ts
+const requestFetch = useAuthRequestFetch()
+const customerState = await requestFetch('/api/auth/customer/state')
+```
+
+Use `useAuthAsyncData()` for keyed SSR data with Nuxt loading and error state. It requires an authenticated user by default and resolves to `null` without calling the endpoint when the user is signed out.
+
+```ts
+const { data, pending, error } = await useAuthAsyncData(
+  'customer-state',
+  requestFetch => requestFetch('/api/auth/customer/state'),
+)
+```
+
 ## Force refresh
 
 ```ts

docs/public/.well-known/skills/nuxt-better-auth/references/installation.md

@@ -18,14 +18,20 @@ Required files:
 NUXT_BETTER_AUTH_SECRET=replace-with-a-random-32-character-secret
 ```
 
-Optional but commonly required in production:
+Set the public site URL when the deployment platform cannot detect it:
 
 ```ini
 NUXT_PUBLIC_SITE_URL=https://your-domain.com
 ```
 
 `BETTER_AUTH_SECRET` is still accepted as a fallback. Prefer `NUXT_BETTER_AUTH_SECRET`.
 
+For non-destructive secret rotation, keep the current and previous secrets in Better Auth's versioned variable:
+
+```ini
+BETTER_AUTH_SECRETS=2:current-secret-must-be-at-least-32-characters,1:previous-secret-must-be-at-least-32-characters
+```
+
 ## Minimal module setup
 
 ```ts
@@ -54,7 +60,7 @@ import { defineClientAuth } from '@nuxtjs/better-auth/config'
 export default defineClientAuth({})
 ```
 
-## Important rules
+## Module-owned values
 
 - Do not set `secret` manually in `defineServerAuth()`. The module injects it.
 - Do not set `baseURL` manually in full mode. The module resolves it.

docs/public/.well-known/skills/nuxt-better-auth/references/route-protection.md

@@ -13,9 +13,9 @@ Use route rules and page meta for navigation UX. Use `requireUserSession(event)`
 ```ts
 export default defineNuxtConfig({
   routeRules: {
-    '/app/**': { auth: 'user' },
-    '/login': { auth: 'guest' },
-    '/admin/**': { auth: { user: { role: 'admin' } } },
+    '/app/**': { auth: { only: 'user', redirectTo: '/login' } },
+    '/login': { auth: { only: 'guest', redirectTo: '/app' } },
+    '/admin/**': { auth: { only: 'user', user: { role: 'admin' } } },
   },
 })
 ```
@@ -31,6 +31,29 @@ The same auth keys work under `nitro.routeRules`. If both `routeRules` and `nitr
 - multiple fields mean AND matching
 - `false`: disable auth for that route/page
 
+The string forms remain available as shorthand. `auth: 'user'` redirects to the configured login fallback, and `auth: 'guest'` redirects to the configured guest fallback.
+
+## Redirects
+
+```ts
+export default defineNuxtConfig({
+  auth: {
+    redirects: {
+      login: '/login',
+      guest: '/',
+      authenticated: '/app',
+      logout: '/goodbye',
+    },
+    preserveRedirect: true,
+    redirectQueryKey: 'redirect',
+  },
+})
+```
+
+- Per-route `redirectTo` takes precedence over `auth.redirects.login` and `auth.redirects.guest`.
+- A validated local redirect query takes precedence over `auth.redirects.authenticated` after sign-in or sign-up.
+- `auth.redirects.logout` applies after sign-out unless the caller supplies `onSuccess`.
+
 ## Broad rules and internals
 
 Broad rules such as `'/**': { auth: 'user' }` intentionally skip framework and module internals that must stay reachable:

test/public-skill.test.ts

@@ -0,0 +1,49 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import yaml from 'yaml'
+
+const bundleRoot = resolve('docs/public/.well-known/skills')
+const skillRoot = join(bundleRoot, 'nuxt-better-auth')
+
+function listFiles(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(dir, entry.name)
+    return entry.isDirectory() ? listFiles(path) : [relative(skillRoot, path)]
+  }).sort()
+}
+
+describe('public skill bundle', () => {
+  it('keeps its manifest, frontmatter, links, and code fences valid', () => {
+    const manifest = JSON.parse(readFileSync(join(bundleRoot, 'index.json'), 'utf8'))
+    const skill = manifest.skills.find((entry: { name: string }) => entry.name === 'nuxt-better-auth')
+    const skillMarkdown = readFileSync(join(skillRoot, 'SKILL.md'), 'utf8')
+    const frontmatterMatch = skillMarkdown.match(/^---\n([\s\S]*?)\n---/)
+
+    expect(skill).toBeDefined()
+    expect(frontmatterMatch).not.toBeNull()
+    if (!skill || !frontmatterMatch)
+      return
+
+    const frontmatter = yaml.parse(frontmatterMatch[1])
+    expect(skill.name).toBe(frontmatter.name)
+    expect(skill.description).toBe(frontmatter.description)
+    expect([...skill.files].sort()).toEqual(listFiles(skillRoot))
+
+    for (const file of skill.files as string[]) {
+      const path = join(skillRoot, file)
+      const contents = readFileSync(path, 'utf8')
+      const fences = contents.match(/^```/gm) ?? []
+
+      expect(fences.length % 2, `${file} has an unclosed code fence`).toBe(0)
+
+      for (const match of contents.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)) {
+        const target = match[1]
+        if (/^(?:https?:|#)/.test(target))
+          continue
+
+        expect(existsSync(resolve(dirname(path), target)), `${file} links to missing ${target}`).toBe(true)
+      }
+    }
+  })
+})