docs: clarify type augmentation placement (#171)

Author: onmax

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

@@ -44,9 +44,9 @@ if (user.value?.role === 'admin') {
 
 Manually extend types when automatic inference doesn't work:
 
-Create a file `types/auth.d.ts`:
+Create a file next to `nuxt.config.ts`, for example `nuxt-better-auth.d.ts` (or `nuxt.d.ts`):
 
-```ts [types/auth.d.ts]
+```ts [nuxt-better-auth.d.ts]
 import '#nuxt-better-auth'
 
 declare module '#nuxt-better-auth' {
@@ -60,12 +60,21 @@ declare module '#nuxt-better-auth' {
 The `#nuxt-better-auth` virtual module exports `AuthUser` and `AuthSession` interfaces that reflect your current configuration.
 ::
 
+::tip
+If you prefer putting declaration files under `types/`, make sure they are included by TypeScript in your project:
+- Add them to `tsconfig.json` `include`, or
+- Reference them from a root `nuxt.d.ts` file (e.g. `/// <reference path="./types/auth.d.ts" />`).
+
+Otherwise, Nuxt/TypeScript may not pick them up and your augmentation will have no effect.
+::
+
 ## Troubleshooting
 
 **Types not updating?**
 1. Restart your IDE's TypeScript server
 2. Run `npx nuxi prepare` to regenerate types
 3. Check that your `server/auth.config.ts` has no syntax errors
+4. Ensure your augmentation `.d.ts` file is included by TypeScript (see note above)
 
 ::callout{icon="i-lucide-arrow-right" to="/getting-started/how-it-works"}
 Now that you are set up, learn **How it Works**.

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

@@ -58,6 +58,11 @@ export default defineNuxtConfig({
 
 If `redirectTo` is omitted, shorthand defaults apply (`'user' -> '/login'`, `'guest' -> '/'`).
 
+::tip
+If `auth: { user: { ... } }` complains about missing fields (e.g. `role`), ensure your Better Auth plugin fields are inferred or that you have a working `#nuxt-better-auth` type augmentation in a root `*.d.ts` file.
+:read-more{to="/getting-started/type-augmentation" title="Type Augmentation"}
+::
+
 ::note
 These rules are automatically synced to the client-side router, ensuring instant redirects without server roundtrips for navigation.
 ::