docs: comprehensive rewrite of authentication documentation

[rblalock]

Summary

Complete rewrite of the @agentuity/auth documentation to fix inaccuracies, add missing features, and improve developer experience.

What Changed

Section	Change
Hero Section	✨ NEW - "Full-Stack Auth in Seconds" with tabbed Frontend/API/Agent snippets
What You Get	✨ NEW - Quick bullet list of features
Quick Start	🔄 Expanded - 3 paths (New Project, Existing, Manual)
Default Plugins	✨ NEW - Table documenting auto-included plugins (organization, jwt, bearer, apiKey)
Middleware	🔄 Expanded - hasOrgRole, hasPermission, optional options now documented
Auth Context	✨ NEW - Full table of c.var.auth / ctx.auth methods
Agent Auth	🔄 Expanded - ctx.auth interface + agent-to-agent propagation
Environment Variables	🔄 Expanded - Defaults and auto-resolution documented
Built-in Features	✨ NEW - Organizations, API Keys, JWT with BetterAuth links
CLI Commands	🔄 Expanded - Both init and generate with options

Why

The previous documentation had several issues:

• Missing explanation of default plugins
• Incomplete middleware options
• Limited auth context documentation
• Missing agent auth propagation
• Incomplete environment variable documentation

Links Added

• Auth package types
• Auth testing app
• BetterAuth plugin docs (Organization, API Key, JWT)

Size

• Before: 265 lines
• After: 519 lines (+362, -108)

Summary by CodeRabbit

• Documentation
  • Updated authentication documentation with comprehensive frontend, API, and agent setup examples
  • Added new client-side auth helpers and provider setup guidance
  • Expanded middleware, auth context, and API key documentation
  • Included environment variable and deployment security guidance
  • Refreshed CLI commands and agent-to-agent auth propagation examples

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The authentication documentation is restructured to introduce a unified multi-tab narrative covering frontend, API, and agent contexts. Client-side auth examples are added (useAuth hook, helper functions), middleware and API key sections are expanded, and code examples are updated to reflect new public API patterns and type import paths.

Changes

Cohort / File(s)

Summary

Authentication Documentation content/Frontend/authentication.mdx

Restructures guide from isolated examples into multi-tab frontend/API/Agent narrative; adds client-side auth surface with useAuth hook, signIn/signUp/signOut helpers, and AuthProvider setup; expands middleware sections with session and role-based patterns; introduces API Keys, JWT/Bearer tokens, and Auth Context capabilities (getUser, getOrg, getOrgRole, hasPermission); adds agent-to-agent auth propagation examples; updates CLI section with init/generate commands; refreshes all code examples and type import paths to reflect updated public API

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 1

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch better-auth-docs

---

🧹 Recent nitpick comments

content/Frontend/authentication.mdx (1)

255-271: Consider importing authClient instead of recreating it.

The example at lines 260 creates a new createAuthClient() instance, but lines 242-249 already show creating and exporting authClient from auth-client.ts. For consistency and to avoid multiple client instances, consider importing from auth-client.ts:

📝 Suggested documentation update

 ```tsx title="src/web/frontend.tsx"
 import { AgentuityProvider } from '@agentuity/react';
-import { AuthProvider, createAuthClient } from '@agentuity/auth/react';
+import { AuthProvider } from '@agentuity/auth/react';
+import { authClient } from './auth-client';
 import { App } from './App';

-const authClient = createAuthClient();
-
 export function Root() {
   return (

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4859b6b and 6019007.

📒 Files selected for processing (1)

• content/Frontend/authentication.mdx

🔇 Additional comments (10)

content/Frontend/authentication.mdx (10)

8-45: Well-structured hero section with clear multi-context examples.

The tabbed examples effectively demonstrate the three key contexts (Frontend, API Route, Agent) in a concise manner. The feature list provides a good overview of capabilities.

---

46-80: Clear quick start paths for different scenarios.

The three-tab approach (New Project, Existing Project, Manual Setup) provides appropriate guidance for each user journey.

---

82-147: Comprehensive server setup documentation.

The progression from basic to advanced configuration is well-structured. The default plugins table clearly documents what's included automatically.

---

149-236: Thorough middleware documentation with clear options.

The session and API key middleware sections cover required, optional, and role-based patterns well. The auth context table provides a complete reference of available methods.

---

311-369: Clear agent authentication examples.

The ctx.auth interface documentation and agent-to-agent propagation examples effectively demonstrate how auth context flows through the system.

---

371-391: Good environment variable documentation with security guidance.

The fallback behavior for secrets and the warning about replacing dev secrets before deployment are helpful for developers.

---

393-426: Clear database configuration options.

The two patterns (connection string vs Bring Your Own Drizzle) accommodate both simple and advanced use cases. The schema export documentation is helpful for understanding what's included.

---

427-484: Good coverage of built-in features with external documentation links.

The examples for organizations, API keys, and JWT tokens provide a starting point while appropriately directing users to BetterAuth documentation for the complete API.

---

486-512: CLI documentation is consistent and complete.

The commands and options align with the Quick Start section, and the ORM detection behavior is clearly explained.

---

513-518: Helpful next steps with relevant cross-references.

The links provide clear paths to related documentation and practical examples.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}