initial commit

.agents/skills/convex-setup-auth/references/clerk.md

@@ -0,0 +1,141 @@
+# Clerk
+
+Official docs:
+
+- https://docs.convex.dev/auth/clerk
+- https://clerk.com/docs/guides/development/integrations/databases/convex
+
+Use this when the app already uses Clerk or the user wants Clerk's hosted auth
+features.
+
+## Workflow
+
+1. Confirm the user wants Clerk
+2. Make sure the user has a Clerk account and a Clerk application
+3. Determine the app framework:
+   - React
+   - Next.js
+   - TanStack Start
+4. Ask whether the user wants local-only setup or production-ready setup now
+5. Gather the Clerk keys and the Clerk Frontend API URL
+6. Follow the correct framework section in the official docs
+7. Complete the backend and client wiring
+8. Verify Convex reports the user as authenticated after login
+9. If the user wants production-ready setup, make sure the production Clerk
+   config is also covered
+
+## What To Do
+
+- Read the official Convex and Clerk guide before writing setup code
+- If the user does not already have Clerk set up, send them to
+  `https://dashboard.clerk.com/sign-up` to create an account and
+  `https://dashboard.clerk.com/apps/new` to create an application
+- Send the user to `https://dashboard.clerk.com/apps/setup/convex` if the Convex
+  integration is not already active
+- Match the guide to the app's framework, usually React, Next.js, or TanStack
+  Start
+- Use the official examples for `ConvexProviderWithClerk`, `ClerkProvider`, and
+  `useAuth`
+
+## Key Setup Areas
+
+- install the Clerk SDK for the framework in use
+- configure `convex/auth.config.ts` with the Clerk issuer domain
+- set the required Clerk environment variables
+- wrap the app with `ClerkProvider` and `ConvexProviderWithClerk`
+- use Convex auth-aware UI patterns such as `Authenticated`, `Unauthenticated`,
+  and `AuthLoading`
+
+## Files and Env Vars To Expect
+
+- `convex/auth.config.ts`
+- React or Vite client entry such as `src/main.tsx`
+- Next.js client wrapper for Convex if using App Router
+- Clerk account sign-up page: `https://dashboard.clerk.com/sign-up`
+- Clerk app creation page: `https://dashboard.clerk.com/apps/new`
+- Clerk Convex integration page: `https://dashboard.clerk.com/apps/setup/convex`
+- Clerk API keys page: `https://dashboard.clerk.com/last-active?path=api-keys`
+- Clerk environment variables:
+  - `CLERK_JWT_ISSUER_DOMAIN` for Convex backend validation in the Convex docs
+  - `CLERK_FRONTEND_API_URL` in the Clerk docs
+  - `VITE_CLERK_PUBLISHABLE_KEY` for Vite apps
+  - `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` for Next.js apps
+  - `CLERK_SECRET_KEY` for Next.js server-side Clerk setup where required
+
+`CLERK_JWT_ISSUER_DOMAIN` and `CLERK_FRONTEND_API_URL` refer to the same Clerk
+Frontend API URL value. Do not treat them as two different URLs.
+
+## Concrete Steps
+
+1. If needed, create a Clerk account at `https://dashboard.clerk.com/sign-up`
+2. If needed, create a Clerk application at
+   `https://dashboard.clerk.com/apps/new`
+3. Open `https://dashboard.clerk.com/last-active?path=api-keys` and copy the
+   publishable key, plus the secret key for Next.js where needed
+4. Open `https://dashboard.clerk.com/apps/setup/convex`
+5. Activate the Convex integration in Clerk if it is not already active
+6. Copy the Clerk Frontend API URL shown there
+7. Install the Clerk package for the app's framework
+8. Create or update `convex/auth.config.ts` so Convex validates Clerk tokens
+9. Set the publishable key in the frontend environment
+10. Set the issuer domain or Frontend API URL so Convex can validate the JWT
+11. Replace plain `ConvexProvider` wiring with `ConvexProviderWithClerk`
+12. Wrap the app in `ClerkProvider`
+13. Use Convex auth helpers for authenticated rendering
+14. Run the normal Convex dev or deploy flow after updating backend auth config
+15. If the user wants production-ready setup, configure the production Clerk
+    values and production issuer domain too
+
+## Gotchas
+
+- Prefer `useConvexAuth()` over raw Clerk auth state when deciding whether
+  Convex-authenticated UI can render
+- For Next.js, keep server and client boundaries in mind when creating the
+  Convex provider wrapper
+- After changing `convex/auth.config.ts`, run the normal Convex dev or deploy
+  flow so the backend picks up the new config
+- Do not stop at "Clerk login works". The important check is that Convex also
+  sees the session and can authenticate requests.
+- If the repo already uses Clerk, preserve its existing auth flow unless the
+  user asked to change it.
+- Do not assume the same Clerk values work for both dev and production. Check
+  the production issuer domain and publishable key separately.
+- The Convex setup page is where you get the Clerk Frontend API URL for Convex.
+  Keep using the Clerk API keys page for the publishable key and the secret key.
+- If Convex says no auth provider matched the token, first confirm the Clerk
+  Convex integration was activated at
+  `https://dashboard.clerk.com/apps/setup/convex`
+- After activating the Clerk Convex integration, sign out completely and sign
+  back in before retesting. An old Clerk session can keep using a token that
+  Convex rejects.
+
+## Production
+
+- Ask whether the user wants dev-only setup or production-ready setup
+- If the answer is production-ready, make sure production Clerk keys and issuer
+  configuration are included
+- Verify production redirect URLs and any production Clerk domain values before
+  calling the task complete
+- Do not silently write a notes file into the repo by default. If the user wants
+  rollout or handoff docs, create one explicitly.
+
+## Validation
+
+- Verify the user can sign in with Clerk
+- If the Clerk integration was just activated, verify after a full Clerk
+  sign-out and fresh sign-in
+- Verify `useConvexAuth()` reaches the authenticated state after Clerk login
+- Verify protected Convex queries run successfully inside authenticated UI
+- Verify `ctx.auth.getUserIdentity()` is non-null in protected backend functions
+- If production-ready setup was requested, verify the production Clerk
+  configuration is also covered
+
+## Checklist
+
+- [ ] Confirm the user wants Clerk
+- [ ] Ask whether the user wants local-only setup or production-ready setup
+- [ ] Follow the correct framework section in the official guide
+- [ ] Set Clerk environment variables
+- [ ] Configure `convex/auth.config.ts`
+- [ ] Verify Convex authenticated state after login
+- [ ] If requested, configure the production deployment too