@strayl/agent 0.1.10 → 0.1.11

package/skills/authentication/SKILL.md

@@ -1,294 +1,294 @@
----
-name: authentication
-description: Add authentication to a TanStack Start app using Neon Auth (managed Better Auth). Handles sign-in, sign-up, OAuth, email verification, password reset, session management, route protection, and pre-built auth UI. Use when the user needs user accounts, login, or protected routes.
----
-
-# Authentication (Neon Auth)
-
-## When to Use
-
-- User asks to add authentication, login, sign-up, or user accounts
-- User wants to protect routes (dashboard, settings, profile, etc.)
-- User mentions "auth", "login", "register", "sign up", "sign in", "logout", "session", "password", "OAuth", "Google sign-in"
-- User needs user management or access control in their app
-- User wants OAuth (Google, GitHub) login
-
-## When NOT to Use
-
-- User only needs a public site with no user accounts
-- User wants API key authentication (not session-based)
-- User explicitly wants to build auth from scratch without Neon Auth
-
-## Prerequisites
-
-- A TanStack Start project (scaffolded with `web-application-creation` skill or existing)
-- A database created with `database-management` skill (or will be created in this workflow)
-- `AUTH_BASE_URL` and `VITE_AUTH_BASE_URL` env vars are automatically available after database creation (both set by `create_database`)
-
-## Architecture
-
-Neon Auth is a **managed authentication service** built on Better Auth. It runs as a REST API deployed in the same region as the Neon database.
-
-| Concern | Solution |
-|---------|----------|
-| Auth service | Neon Auth (managed Better Auth) |
-| User storage | `neon_auth` schema in Neon DB (automatic) |
-| UI components | `@neondatabase/neon-js/auth/react/ui` (pre-built) |
-| Session | HTTP-only cookie (`__Secure-neonauth.session_token`), managed by SDK |
-| OAuth | Google works out of the box; GitHub/Vercel need custom credentials |
-
-**No custom user table needed.** Users, sessions, and accounts are stored automatically in the `neon_auth` schema.
-
-## Workflow
-
-### Step 1: Ensure Database Exists
-
-```
-universal({ tool: "list_databases", params: {} })
-```
-
-If no databases exist, create one first:
-```
-universal({ tool: "create_database", params: { name: "main" } })
-```
-
-Auth is automatically provisioned when the database is created. The `AUTH_BASE_URL`, `VITE_AUTH_BASE_URL`, and `AUTH_COOKIE_SECRET` env vars are already set in the sandbox and `.env`.
-
-### Step 2: Install Neon Auth SDK
-
-```bash
-exec({ command: "cd {app-name} && npm install @neondatabase/neon-js", background: true })
-```
-
-### Step 3: Add Auth Styles
-
-**Edit** `src/styles.css` — add the Neon UI import right after the Tailwind import:
-
-```css
-@import 'tailwindcss';
-@import '@neondatabase/neon-js/ui/tailwind';
-```
-
-If the project does NOT use Tailwind, import the pre-built CSS bundle instead. Add to the root layout or entry point:
-```typescript
-import '@neondatabase/neon-js/ui/css';
-```
-
-### Step 4: Create Auth Client
-
-Create `src/auth.ts`. Uses `VITE_AUTH_BASE_URL` which is auto-set by `create_database` — no manual env var setup needed.
-
-```typescript
-import { createAuthClient } from '@neondatabase/neon-js/auth';
-import { BetterAuthReactAdapter } from '@neondatabase/neon-js/auth/react';
-
-export const authClient = createAuthClient(
-  import.meta.env.VITE_AUTH_BASE_URL,
-  { adapter: BetterAuthReactAdapter() }
-);
-```
-
-### Step 5: Add Auth Provider to Root Route
-
-**Edit** `src/routes/__root.tsx` — wrap the app with `NeonAuthUIProvider`:
-
-```typescript
-import { NeonAuthUIProvider } from '@neondatabase/neon-js/auth/react';
-import { authClient } from '../auth';
-```
-
-Wrap the existing `<Outlet />` (or app content) with the provider:
-
-```tsx
-<NeonAuthUIProvider authClient={authClient}>
-  <Outlet />
-</NeonAuthUIProvider>
-```
-
-**Optional props** for `NeonAuthUIProvider`:
-- `social={{ providers: ['google'] }}` — show OAuth buttons (Google works out of the box)
-- `emailOTP` — enable Email OTP sign-in
-- `credentials={{ forgotPassword: true }}` — enable forgot password flow
-- `navigate={navigate}` — for React Router integration
-
-**Do NOT replace** the existing root route — just add the import and wrap the content with the provider.
-
-### Step 6: Create Auth Page Route
-
-Create `src/routes/auth.$pathname.tsx`:
-
-```typescript
-import { createFileRoute } from '@tanstack/react-router';
-import { AuthView } from '@neondatabase/neon-js/auth/react/ui';
-
-export const Route = createFileRoute('/auth/$pathname')({
-  component: Auth,
-});
-
-function Auth() {
-  const { pathname } = Route.useParams();
-  return (
-    <div className="flex min-h-screen items-center justify-center">
-      <AuthView pathname={pathname} />
-    </div>
-  );
-}
-```
-
-This single route handles `/auth/sign-in`, `/auth/sign-up`, `/auth/forgot-password`, etc.
-
-### Step 7: Create Account Page Route
-
-Create `src/routes/account.$pathname.tsx`:
-
-```typescript
-import { createFileRoute } from '@tanstack/react-router';
-import { AccountView } from '@neondatabase/neon-js/auth/react/ui';
-
-export const Route = createFileRoute('/account/$pathname')({
-  component: Account,
-});
-
-function Account() {
-  const { pathname } = Route.useParams();
-  return (
-    <div className="flex min-h-screen items-center justify-center">
-      <AccountView pathname={pathname} />
-    </div>
-  );
-}
-```
-
-This handles `/account/settings`, `/account/profile`, etc.
-
-### Step 8: Protect Routes
-
-**Edit** the main page (e.g., `src/routes/index.tsx`) to require authentication:
-
-```typescript
-import { createFileRoute } from '@tanstack/react-router';
-import { SignedIn, UserButton, RedirectToSignIn } from '@neondatabase/neon-js/auth/react/ui';
-import { authClient } from '../auth';
-
-export const Route = createFileRoute('/')({
-  component: Home,
-});
-
-function Home() {
-  const { data } = authClient.useSession();
-
-  return (
-    <>
-      <SignedIn>
-        <div className="container mx-auto p-6">
-          <div className="flex items-center justify-between">
-            <h1 className="text-2xl font-bold">Welcome, {data?.user?.name}!</h1>
-            <UserButton />
-          </div>
-        </div>
-      </SignedIn>
-      <RedirectToSignIn />
-    </>
-  );
-}
-```
-
-**Key components:**
-- `<SignedIn>` — renders children only when authenticated
-- `<SignedOut>` — renders children only when NOT authenticated
-- `<RedirectToSignIn>` — redirects to `/auth/sign-in` if not authenticated
-- `<UserButton />` — user avatar/menu dropdown with sign-out
-
-### Step 9: Restart and Preview
-
-Restart the dev server to pick up new routes and env vars, then `showPreview`. Tell the user to test `/auth/sign-in` and `/auth/sign-up`.
-
-## File Structure (after completion)
-
-```
-src/
-├── auth.ts                      # Auth client configuration (NEW)
-├── styles.css                   # EDITED: added neon-js/ui/tailwind import
-└── routes/
-    ├── __root.tsx                # EDITED: wrapped with NeonAuthUIProvider
-    ├── auth.$pathname.tsx        # NEW: handles sign-in, sign-up, forgot-password
-    ├── account.$pathname.tsx     # NEW: handles account settings, profile
-    └── index.tsx                 # EDITED: added route protection
-```
-
-## Available UI Components
-
-| Component | Import | Purpose |
-|-----------|--------|---------|
-| `<AuthView>` | `@neondatabase/neon-js/auth/react/ui` | Full auth page (sign-in/sign-up/reset) |
-| `<AccountView>` | `@neondatabase/neon-js/auth/react/ui` | Account management page |
-| `<SignedIn>` | `@neondatabase/neon-js/auth/react/ui` | Render children only when authenticated |
-| `<SignedOut>` | `@neondatabase/neon-js/auth/react/ui` | Render children only when NOT authenticated |
-| `<RedirectToSignIn>` | `@neondatabase/neon-js/auth/react/ui` | Redirect to sign-in if not authenticated |
-| `<RedirectToSignUp>` | `@neondatabase/neon-js/auth/react/ui` | Redirect to sign-up if not authenticated |
-| `<UserButton>` | `@neondatabase/neon-js/auth/react/ui` | User avatar dropdown with sign-out |
-| `<UserAvatar>` | `@neondatabase/neon-js/auth/react/ui` | User profile picture |
-| `<SignInForm>` | `@neondatabase/neon-js/auth/react/ui` | Standalone sign-in form |
-| `<SignUpForm>` | `@neondatabase/neon-js/auth/react/ui` | Standalone sign-up form |
-| `<ForgotPasswordForm>` | `@neondatabase/neon-js/auth/react/ui` | Password recovery form |
-
-## Hooks
-
-| Hook | Import | Returns |
-|------|--------|---------|
-| `authClient.useSession()` | from auth client | `{ data: { session, user }, isPending }` |
-
-## Important Notes
-
-- **No custom user table.** Users are stored automatically in the `neon_auth` schema. Query with `SELECT * FROM neon_auth.user;`
-- **No password hashing.** Neon Auth handles all credential management.
-- **No session management.** Sessions are managed by the SDK via HTTP-only cookies.
-- **Google OAuth works immediately** with shared credentials for development. GitHub/Vercel require custom OAuth app setup.
-- **AUTH_BASE_URL is branch-specific.** Each Neon branch has its own auth environment — dev and prod are isolated.
-- Do NOT import both `@neondatabase/neon-js/ui/css` AND `@neondatabase/neon-js/ui/tailwind` — pick one based on whether the project uses Tailwind.
-- Do NOT install `bcryptjs`, `better-auth`, or other auth libraries — Neon Auth replaces them.
-
-## SDK Methods Reference
-
-For programmatic auth (building custom UI instead of pre-built components):
-
-```typescript
-import { authClient } from './auth';
-
-// Sign up
-await authClient.signUp.email({ email, password, name });
-
-// Sign in with email/password
-await authClient.signIn.email({ email, password });
-
-// Sign in with OAuth
-await authClient.signIn.social({ provider: 'google', callbackURL: '/' });
-
-// Sign out
-await authClient.signOut();
-
-// Get current session
-const { data } = await authClient.getSession();
-// data.session, data.user
-
-// React hook for session
-const { data } = authClient.useSession();
-
-// Update user profile
-await authClient.updateUser({ name: 'New Name' });
-
-// Change password
-await authClient.changePassword({ currentPassword, newPassword });
-
-// Email OTP verification
-await authClient.emailOtp.verifyEmail({ email, otp: code });
-```
-
-## Extending
-
-- **OAuth providers** — add `social={{ providers: ['google', 'github', 'vercel'] }}` to `NeonAuthUIProvider`
-- **Forgot password** — add `credentials={{ forgotPassword: true }}` to `NeonAuthUIProvider`, or use `<ForgotPasswordForm>` and `<ResetPasswordForm>` components
-- **Email verification** — enable in Neon Console (Settings > Auth). Use verification codes (works out of the box) or verification links (requires custom SMTP)
-- **Custom sign-up fields** — use `additionalFields` and `signUp` props on `NeonAuthUIProvider`
-- **Custom localization** — use `localization` prop to change labels (e.g., `{ SIGN_IN: 'Welcome Back' }`)
-- **Protected route layout** — create `src/routes/_authed.tsx` with `<SignedIn>` check for route groups
+---
+name: authentication
+description: Add authentication to a TanStack Start app using Neon Auth (managed Better Auth). Handles sign-in, sign-up, OAuth, email verification, password reset, session management, route protection, and pre-built auth UI. Use when the user needs user accounts, login, or protected routes.
+---
+
+# Authentication (Neon Auth)
+
+## When to Use
+
+- User asks to add authentication, login, sign-up, or user accounts
+- User wants to protect routes (dashboard, settings, profile, etc.)
+- User mentions "auth", "login", "register", "sign up", "sign in", "logout", "session", "password", "OAuth", "Google sign-in"
+- User needs user management or access control in their app
+- User wants OAuth (Google, GitHub) login
+
+## When NOT to Use
+
+- User only needs a public site with no user accounts
+- User wants API key authentication (not session-based)
+- User explicitly wants to build auth from scratch without Neon Auth
+
+## Prerequisites
+
+- A TanStack Start project (scaffolded with `web-application-creation` skill or existing)
+- A database created with `database-management` skill (or will be created in this workflow)
+- `AUTH_BASE_URL` and `VITE_AUTH_BASE_URL` env vars are automatically available after database creation (both set by `create_database`)
+
+## Architecture
+
+Neon Auth is a **managed authentication service** built on Better Auth. It runs as a REST API deployed in the same region as the Neon database.
+
+| Concern | Solution |
+|---------|----------|
+| Auth service | Neon Auth (managed Better Auth) |
+| User storage | `neon_auth` schema in Neon DB (automatic) |
+| UI components | `@neondatabase/neon-js/auth/react/ui` (pre-built) |
+| Session | HTTP-only cookie (`__Secure-neonauth.session_token`), managed by SDK |
+| OAuth | Google works out of the box; GitHub/Vercel need custom credentials |
+
+**No custom user table needed.** Users, sessions, and accounts are stored automatically in the `neon_auth` schema.
+
+## Workflow
+
+### Step 1: Ensure Database Exists
+
+```
+universal({ tool: "list_databases", params: {} })
+```
+
+If no databases exist, create one first:
+```
+universal({ tool: "create_database", params: { name: "main" } })
+```
+
+Auth is automatically provisioned when the database is created. The `AUTH_BASE_URL`, `VITE_AUTH_BASE_URL`, and `AUTH_COOKIE_SECRET` env vars are already set in the sandbox and `.env`.
+
+### Step 2: Install Neon Auth SDK
+
+```bash
+exec({ command: "cd {app-name} && npm install @neondatabase/neon-js", background: true })
+```
+
+### Step 3: Add Auth Styles
+
+**Edit** `src/styles.css` — add the Neon UI import right after the Tailwind import:
+
+```css
+@import 'tailwindcss';
+@import '@neondatabase/neon-js/ui/tailwind';
+```
+
+If the project does NOT use Tailwind, import the pre-built CSS bundle instead. Add to the root layout or entry point:
+```typescript
+import '@neondatabase/neon-js/ui/css';
+```
+
+### Step 4: Create Auth Client
+
+Create `src/auth.ts`. Uses `VITE_AUTH_BASE_URL` which is auto-set by `create_database` — no manual env var setup needed.
+
+```typescript
+import { createAuthClient } from '@neondatabase/neon-js/auth';
+import { BetterAuthReactAdapter } from '@neondatabase/neon-js/auth/react';
+
+export const authClient = createAuthClient(
+  import.meta.env.VITE_AUTH_BASE_URL,
+  { adapter: BetterAuthReactAdapter() }
+);
+```
+
+### Step 5: Add Auth Provider to Root Route
+
+**Edit** `src/routes/__root.tsx` — wrap the app with `NeonAuthUIProvider`:
+
+```typescript
+import { NeonAuthUIProvider } from '@neondatabase/neon-js/auth/react';
+import { authClient } from '../auth';
+```
+
+Wrap the existing `<Outlet />` (or app content) with the provider:
+
+```tsx
+<NeonAuthUIProvider authClient={authClient}>
+  <Outlet />
+</NeonAuthUIProvider>
+```
+
+**Optional props** for `NeonAuthUIProvider`:
+- `social={{ providers: ['google'] }}` — show OAuth buttons (Google works out of the box)
+- `emailOTP` — enable Email OTP sign-in
+- `credentials={{ forgotPassword: true }}` — enable forgot password flow
+- `navigate={navigate}` — for React Router integration
+
+**Do NOT replace** the existing root route — just add the import and wrap the content with the provider.
+
+### Step 6: Create Auth Page Route
+
+Create `src/routes/auth.$pathname.tsx`:
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router';
+import { AuthView } from '@neondatabase/neon-js/auth/react/ui';
+
+export const Route = createFileRoute('/auth/$pathname')({
+  component: Auth,
+});
+
+function Auth() {
+  const { pathname } = Route.useParams();
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <AuthView pathname={pathname} />
+    </div>
+  );
+}
+```
+
+This single route handles `/auth/sign-in`, `/auth/sign-up`, `/auth/forgot-password`, etc.
+
+### Step 7: Create Account Page Route
+
+Create `src/routes/account.$pathname.tsx`:
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router';
+import { AccountView } from '@neondatabase/neon-js/auth/react/ui';
+
+export const Route = createFileRoute('/account/$pathname')({
+  component: Account,
+});
+
+function Account() {
+  const { pathname } = Route.useParams();
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <AccountView pathname={pathname} />
+    </div>
+  );
+}
+```
+
+This handles `/account/settings`, `/account/profile`, etc.
+
+### Step 8: Protect Routes
+
+**Edit** the main page (e.g., `src/routes/index.tsx`) to require authentication:
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router';
+import { SignedIn, UserButton, RedirectToSignIn } from '@neondatabase/neon-js/auth/react/ui';
+import { authClient } from '../auth';
+
+export const Route = createFileRoute('/')({
+  component: Home,
+});
+
+function Home() {
+  const { data } = authClient.useSession();
+
+  return (
+    <>
+      <SignedIn>
+        <div className="container mx-auto p-6">
+          <div className="flex items-center justify-between">
+            <h1 className="text-2xl font-bold">Welcome, {data?.user?.name}!</h1>
+            <UserButton />
+          </div>
+        </div>
+      </SignedIn>
+      <RedirectToSignIn />
+    </>
+  );
+}
+```
+
+**Key components:**
+- `<SignedIn>` — renders children only when authenticated
+- `<SignedOut>` — renders children only when NOT authenticated
+- `<RedirectToSignIn>` — redirects to `/auth/sign-in` if not authenticated
+- `<UserButton />` — user avatar/menu dropdown with sign-out
+
+### Step 9: Restart and Preview
+
+Restart the dev server to pick up new routes and env vars, then `showPreview`. Tell the user to test `/auth/sign-in` and `/auth/sign-up`.
+
+## File Structure (after completion)
+
+```
+src/
+├── auth.ts                      # Auth client configuration (NEW)
+├── styles.css                   # EDITED: added neon-js/ui/tailwind import
+└── routes/
+    ├── __root.tsx                # EDITED: wrapped with NeonAuthUIProvider
+    ├── auth.$pathname.tsx        # NEW: handles sign-in, sign-up, forgot-password
+    ├── account.$pathname.tsx     # NEW: handles account settings, profile
+    └── index.tsx                 # EDITED: added route protection
+```
+
+## Available UI Components
+
+| Component | Import | Purpose |
+|-----------|--------|---------|
+| `<AuthView>` | `@neondatabase/neon-js/auth/react/ui` | Full auth page (sign-in/sign-up/reset) |
+| `<AccountView>` | `@neondatabase/neon-js/auth/react/ui` | Account management page |
+| `<SignedIn>` | `@neondatabase/neon-js/auth/react/ui` | Render children only when authenticated |
+| `<SignedOut>` | `@neondatabase/neon-js/auth/react/ui` | Render children only when NOT authenticated |
+| `<RedirectToSignIn>` | `@neondatabase/neon-js/auth/react/ui` | Redirect to sign-in if not authenticated |
+| `<RedirectToSignUp>` | `@neondatabase/neon-js/auth/react/ui` | Redirect to sign-up if not authenticated |
+| `<UserButton>` | `@neondatabase/neon-js/auth/react/ui` | User avatar dropdown with sign-out |
+| `<UserAvatar>` | `@neondatabase/neon-js/auth/react/ui` | User profile picture |
+| `<SignInForm>` | `@neondatabase/neon-js/auth/react/ui` | Standalone sign-in form |
+| `<SignUpForm>` | `@neondatabase/neon-js/auth/react/ui` | Standalone sign-up form |
+| `<ForgotPasswordForm>` | `@neondatabase/neon-js/auth/react/ui` | Password recovery form |
+
+## Hooks
+
+| Hook | Import | Returns |
+|------|--------|---------|
+| `authClient.useSession()` | from auth client | `{ data: { session, user }, isPending }` |
+
+## Important Notes
+
+- **No custom user table.** Users are stored automatically in the `neon_auth` schema. Query with `SELECT * FROM neon_auth.user;`
+- **No password hashing.** Neon Auth handles all credential management.
+- **No session management.** Sessions are managed by the SDK via HTTP-only cookies.
+- **Google OAuth works immediately** with shared credentials for development. GitHub/Vercel require custom OAuth app setup.
+- **AUTH_BASE_URL is branch-specific.** Each Neon branch has its own auth environment — dev and prod are isolated.
+- Do NOT import both `@neondatabase/neon-js/ui/css` AND `@neondatabase/neon-js/ui/tailwind` — pick one based on whether the project uses Tailwind.
+- Do NOT install `bcryptjs`, `better-auth`, or other auth libraries — Neon Auth replaces them.
+
+## SDK Methods Reference
+
+For programmatic auth (building custom UI instead of pre-built components):
+
+```typescript
+import { authClient } from './auth';
+
+// Sign up
+await authClient.signUp.email({ email, password, name });
+
+// Sign in with email/password
+await authClient.signIn.email({ email, password });
+
+// Sign in with OAuth
+await authClient.signIn.social({ provider: 'google', callbackURL: '/' });
+
+// Sign out
+await authClient.signOut();
+
+// Get current session
+const { data } = await authClient.getSession();
+// data.session, data.user
+
+// React hook for session
+const { data } = authClient.useSession();
+
+// Update user profile
+await authClient.updateUser({ name: 'New Name' });
+
+// Change password
+await authClient.changePassword({ currentPassword, newPassword });
+
+// Email OTP verification
+await authClient.emailOtp.verifyEmail({ email, otp: code });
+```
+
+## Extending
+
+- **OAuth providers** — add `social={{ providers: ['google', 'github', 'vercel'] }}` to `NeonAuthUIProvider`
+- **Forgot password** — add `credentials={{ forgotPassword: true }}` to `NeonAuthUIProvider`, or use `<ForgotPasswordForm>` and `<ResetPasswordForm>` components
+- **Email verification** — enable in Neon Console (Settings > Auth). Use verification codes (works out of the box) or verification links (requires custom SMTP)
+- **Custom sign-up fields** — use `additionalFields` and `signUp` props on `NeonAuthUIProvider`
+- **Custom localization** — use `localization` prop to change labels (e.g., `{ SIGN_IN: 'Welcome Back' }`)
+- **Protected route layout** — create `src/routes/_authed.tsx` with `<SignedIn>` check for route groups