opencastle 0.33.9 → 0.34.0

package/src/orchestrator/plugins/convex/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: convex-database
-description: "Convex reactive database patterns, schema design, real-time queries, mutations, actions, and deployment best practices. Use when designing Convex schemas, writing queries/mutations, or managing the Convex backend."
+description: "Convex reactive database patterns, schema design, real-time queries, mutations, actions, authentication, migrations, performance optimization, and component creation. Use when designing Convex schemas, writing queries/mutations, managing the Convex backend, setting up auth, migrating data, optimizing performance, or building Convex components."
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
@@ -9,6 +9,18 @@ description: "Convex reactive database patterns, schema design, real-time querie
 
 For project-specific schema, functions, and deployment details, see [database-config.md](../../.opencastle/stack/database-config.md).
 
+## Topic Routing
+
+Read the matching reference file before writing code for any of these topics:
+
+| Topic | Reference |
+|-------|-----------|
+| Project setup & scaffolding | `references/quickstart.md` |
+| Schema & data migrations | `references/migrations.md` |
+| Performance optimization | `references/performance-audit.md` |
+| Authentication & access control | `references/auth-setup.md` |
+| Component creation & isolation | `references/components.md` |
+
 ## Critical Development Rules
 
 **Function Registration**
@@ -21,9 +33,14 @@ For project-specific schema, functions, and deployment details, see [database-co
 
 **Queries**
 - Do NOT use `.filter()` — define an index in the schema and use `.withIndex()` instead
+- Convex `.filter()` is equivalent to JS filtering — neither pushes the filter to storage; only `.withIndex()` actually reduces documents scanned
 - Use `.unique()` for single document queries
 - No `.delete()` on queries — collect results, then call `ctx.db.delete(row._id)` on each
 
+**Mutations**
+- Schema changes must not break existing documents — use widen-migrate-narrow when adding required fields; see `references/migrations.md`
+- Skip no-op writes: check if values changed before calling `ctx.db.patch()` — no-op writes still trigger invalidation and replication
+
 **Actions**
 - Add `"use node";` at the top of files containing actions that use Node.js built-in modules
 - Never use `ctx.db` inside actions — actions don't have database access; use `ctx.runQuery`/`ctx.runMutation` instead
@@ -32,19 +49,23 @@ For project-specific schema, functions, and deployment details, see [database-co
 - Index name must include all fields: `["field1", "field2"]` → `"by_field1_and_field2"`
 - Index fields must be queried in definition order
 - Do NOT define `_id` or `_creationTime` — they are automatic system fields
+- Prefer compound indexes over redundant single-field indexes (e.g. `by_team_and_user` covers both `by_team` queries and `by_team_and_user` queries)
+
+**Components**
+- Authentication and environment variables must stay in the app — components cannot access `ctx.auth` or `process.env`
+- Pass parent app IDs across the component boundary as `v.string()`, not `v.id("parentTable")`
+- Import `query`/`mutation`/`action` from the component's own `./_generated/server`, not the app's generated files
 
 **General**
 - Schema-first design: define in `convex/schema.ts` using `defineSchema`/`defineTable`
 - Mutations are ACID transactional; use actions for external API calls or side effects
-- Never await queries in mutations — they run in separate contexts
-- Use `.paginate()` for large result sets
-- Use `Id<'tableName'>` for document ID types (from `./_generated/dataModel`)
 - Use `v.null()` not `v.undefined()` — `undefined` is not a valid Convex value
 - Environment variables: set via Convex dashboard; access with `process.env` in actions only
 
 ## Schema Patterns
 
 ### Defining Tables
+
 ```typescript
 import { defineSchema, defineTable } from "convex/server";
 import { v } from "convex/values";
@@ -61,6 +82,7 @@ export default defineSchema({
 ```
 
 ### Query Functions
+
 ```typescript
 import { query } from "./_generated/server";
 import { v } from "convex/values";
@@ -80,6 +102,7 @@ export const list = query({
 ```
 
 ### Mutations
+
 ```typescript
 import { mutation } from "./_generated/server";
 import { v } from "convex/values";
@@ -93,28 +116,47 @@ export const create = mutation({
 });
 ```
 
-## Real-Time Patterns
-
-- Use `useQuery` hook for automatic real-time subscriptions
-- Queries re-run when any referenced table data changes
-- Use `useMutation` for optimistic updates
-- Paginated queries support real-time updates with `.paginate()`
+### Protecting Functions with Auth
 
-## Deployment
+```typescript
+import { query } from "./_generated/server";
 
-- Deploy with `npx convex deploy`
-- Use `npx convex dev` for local development with hot reload
-- Schema changes are automatically migrated
-- Use `npx convex import` / `npx convex export` for data management
+export const getMyProfile = query({
+  args: {},
+  handler: async (ctx) => {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) throw new Error("Not authenticated");
+
+    return await ctx.db
+      .query("users")
+      .withIndex("by_tokenIdentifier", (q) =>
+        q.eq("tokenIdentifier", identity.tokenIdentifier)
+      )
+      .unique();
+  },
+});
+```
 
 ## Quick Workflow: Implement a schema change and deploy
-1. Add or modify schema in `convex/schema.ts` and run `npx convex dev` locally; confirm the dev server starts and responds (checkpoint: `http://localhost:8888` or the configured port). Run a small validation script or sample queries to verify schema changes (validation checkpoint).
-2. Write queries/mutations with `returns` validators and unit test against the dev server.
-3. Run `npx convex deploy` to push the change to production.
-4. Verify real-time queries in the app, run a small data migration if required (`convex import/export`), and run a quick smoke check against your app (example):
+
+1. Read `references/migrations.md` if the change is breaking (adding required fields, changing types, deleting fields)
+2. Add or modify schema in `convex/schema.ts` and run `npx convex dev` locally; confirm the dev server starts and responds. Run a small validation script or sample queries to verify schema changes.
+3. Write queries/mutations with `returns` validators and unit test against the dev server.
+4. Run `npx convex deploy` to push the change to production.
+5. Verify real-time queries in the app and run a quick smoke check:
 
 ```bash
 curl -fsS https://<APP_URL>/health || (echo "health check failed" && exit 1)
 ```
 
-If an issue occurs: roll back via `npx convex import` of the last good export, fix locally, and re-deploy. After a rollback, re-run the same smoke check to confirm services are restored.
+If an issue occurs: roll back via `npx convex import` of the last good export, fix locally, and re-deploy.
+
+## Validation Checkpoints
+
+| Step | Checkpoint |
+|------|-----------|
+| Schema change | `npx convex dev` starts without errors |
+| Migration needed | `references/migrations.md` checklist completed |
+| Auth function | `ctx.auth.getUserIdentity()` returns non-null in test |
+| Deploy | Smoke check passes; no `convex insights` regressions |
+| Component | `npx convex codegen` succeeds; sibling functions inspected |

package/src/orchestrator/plugins/convex/references/auth-auth0.md

@@ -0,0 +1,116 @@
+# Auth0
+
+Official docs:
+
+- https://docs.convex.dev/auth/auth0
+- https://auth0.github.io/auth0-cli/
+- https://auth0.github.io/auth0-cli/auth0_apps_create.html
+
+Use this when the app already uses Auth0 or the user wants Auth0 specifically.
+
+## Workflow
+
+1. Confirm the user wants Auth0
+2. Determine the app framework and whether Auth0 is already partly set up
+3. Ask whether the user wants local-only setup or production-ready setup now
+4. Read the official Convex and Auth0 guides before making changes
+5. Ask whether they want the fastest setup path by installing the Auth0 CLI
+6. If they agree, install the Auth0 CLI and do as much of the Auth0 app setup as possible through the CLI
+7. If they do not want the CLI path, use the Auth0 dashboard path instead
+8. Complete the relevant Auth0 frontend quickstart if the app does not already have Auth0 wired up
+9. Configure `convex/auth.config.ts` with the Auth0 domain and client ID
+10. Set environment variables for local and production environments
+11. Wrap the app with `Auth0Provider` and `ConvexProviderWithAuth0`
+12. Gate Convex-backed UI with Convex auth state
+13. Try to verify Convex reports the user as authenticated after Auth0 login
+14. If the refresh-token path fails, stop improvising and send the user back to the official docs
+15. If the user wants production-ready setup, make sure the production Auth0 tenant and env vars are also covered
+
+## What To Do
+
+- Read the official Convex and Auth0 guide before writing setup code
+- Prefer the Auth0 CLI path for mechanical setup if the user is willing to install it, but do not present it as a fully validated end-to-end path yet
+- Ask the user directly: "The fastest path is to install the Auth0 CLI so I can do more of this for you. If you want, I can install it and then only ask you to log in when needed. Would you like me to do that?"
+- Make sure the app has already completed the relevant Auth0 quickstart for its frontend
+- Use the official examples for `Auth0Provider` and `ConvexProviderWithAuth0`
+- If the Auth0 login or refresh flow starts failing in a way that is not clearly explained by the docs, say that plainly and fall back to the official docs instead of pretending the flow is validated
+
+## Key Setup Areas
+
+- install the Auth0 SDK for the app's framework
+- configure `convex/auth.config.ts` with the Auth0 domain and client ID
+- set environment variables for local and production environments
+- wrap the app with `Auth0Provider` and `ConvexProviderWithAuth0`
+- use Convex auth state when gating Convex-backed UI
+
+## Files and Env Vars To Expect
+
+- `convex/auth.config.ts`
+- frontend app entry or provider wrapper
+- Auth0 CLI install docs: `https://auth0.github.io/auth0-cli/`
+- Auth0 environment variables commonly include:
+  - `AUTH0_DOMAIN`
+  - `AUTH0_CLIENT_ID`
+  - `VITE_AUTH0_DOMAIN`
+  - `VITE_AUTH0_CLIENT_ID`
+
+## Concrete Steps
+
+1. Start by reading `https://docs.convex.dev/auth/auth0` and the relevant Auth0 quickstart for the app's framework
+2. Ask whether the user wants the Auth0 CLI path
+3. If yes, install Auth0 CLI and have the user authenticate it with `auth0 login`
+4. Use `auth0 apps create` with SPA settings, callback URL, logout URL, and web origins if creating a new app
+5. If not using the CLI path, complete the relevant Auth0 frontend quickstart and create the Auth0 app in the dashboard
+6. Get the Auth0 domain and client ID from the CLI output or the Auth0 dashboard
+7. Install the Auth0 SDK for the app's framework
+8. Create or update `convex/auth.config.ts` with the Auth0 domain and client ID
+9. Set frontend and backend environment variables
+10. Wrap the app in `Auth0Provider`
+11. Replace plain `ConvexProvider` wiring with `ConvexProviderWithAuth0`
+12. Run the normal Convex dev or deploy flow after backend config changes
+13. Try the official provider config shown in the Convex docs
+14. If login works but Convex auth or token refresh fails in a way you cannot clearly resolve, stop and tell the user to follow the official docs manually for now
+15. Only claim success if the user can sign in and Convex recognizes the authenticated session
+16. If the user wants production-ready setup, configure the production Auth0 tenant values and production environment variables too
+
+## Gotchas
+
+- The Convex docs assume the Auth0 side is already set up, so do not skip the Auth0 quickstart if the app is starting from scratch
+- The Auth0 CLI is often the fastest path for a fresh setup, but it still requires the user to authenticate the CLI to their Auth0 tenant
+- If the user agrees to install the Auth0 CLI, do the mechanical setup yourself instead of bouncing them through the dashboard
+- If login succeeds but Convex still reports unauthenticated, double-check `convex/auth.config.ts` and whether the backend config was synced
+- We were able to automate Auth0 app creation and Convex config wiring, but we did not fully validate the refresh-token path end to end
+- In validation, the documented `useRefreshTokens={true}` and `cacheLocation="localstorage"` setup hit refresh-token failures, so do not present that path as settled
+- If you hit Auth0 errors like `Unknown or invalid refresh token`, do not keep inventing fixes indefinitely, send the user back to the official docs and explain that this path is still under investigation
+- Keep dev and prod tenants separate if the project uses different Auth0 environments
+- Do not confuse "Auth0 login works" with "Convex can validate the Auth0 token". Both need to work.
+- If the repo already uses Auth0, preserve existing redirect and tenant configuration unless the user asked to change it.
+- Do not assume the local Auth0 tenant settings match production. Verify the production domain, client ID, and callback URLs separately.
+- For local dev, make sure the Auth0 app settings match the app's real local port for callback URLs, logout URLs, and web origins
+
+## Production
+
+- Ask whether the user wants dev-only setup or production-ready setup
+- If the answer is production-ready, make sure the production Auth0 tenant values, callback URLs, and Convex deployment config are all covered
+- Verify production environment variables and redirect settings 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 complete the Auth0 login flow
+- Verify Convex-authenticated UI renders only after Convex auth state is ready
+- Verify protected Convex queries succeed after login
+- Verify `ctx.auth.getUserIdentity()` is non-null in protected backend functions
+- Verify the Auth0 app settings match the real local callback and logout URLs during development
+- If the Auth0 refresh-token path fails, mark the setup as not fully validated and direct the user to the official docs instead of claiming the skill completed successfully
+- If production-ready setup was requested, verify the production Auth0 configuration is also covered
+
+## Checklist
+
+- [ ] Confirm the user wants Auth0
+- [ ] Ask whether the user wants local-only setup or production-ready setup
+- [ ] Complete the relevant Auth0 frontend setup
+- [ ] Configure `convex/auth.config.ts`
+- [ ] Set environment variables
+- [ ] Verify Convex authenticated state after login, or explicitly tell the user this path is still under investigation and send them to the official docs
+- [ ] If requested, configure the production deployment too

package/src/orchestrator/plugins/convex/references/auth-clerk.md

@@ -0,0 +1,113 @@
+# 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

package/src/orchestrator/plugins/convex/references/auth-convex-auth.md

@@ -0,0 +1,143 @@
+# Convex Auth
+
+Official docs: https://docs.convex.dev/auth/convex-auth
+Setup guide: https://labs.convex.dev/auth/setup
+
+Use this when the user wants auth handled directly in Convex rather than through a third-party provider.
+
+## Workflow
+
+1. Confirm the user wants Convex Auth specifically
+2. Determine which sign-in methods the app needs:
+   - magic links or OTPs
+   - OAuth providers
+   - passwords and password reset
+3. Ask whether the user wants local-only setup or production-ready setup now
+4. Read the Convex Auth setup guide before writing code
+5. Make sure the project has a configured Convex deployment:
+   - run `npx convex dev` first if `CONVEX_DEPLOYMENT` is not set
+   - if CLI configuration requires interactive human input, stop and ask the user to complete that step before continuing
+6. Install the auth packages:
+   - `npm install @convex-dev/auth @auth/core@0.37.0`
+7. Run the initialization command:
+   - `npx @convex-dev/auth`
+8. Confirm the initializer created:
+   - `convex/auth.config.ts`
+   - `convex/auth.ts`
+   - `convex/http.ts`
+9. Add the required `authTables` to `convex/schema.ts`
+10. Replace plain `ConvexProvider` wiring with `ConvexAuthProvider`
+11. Configure at least one auth method in `convex/auth.ts`
+12. Run `npx convex dev --once` or the normal dev flow to push the updated schema and generated code
+13. Verify the client can sign in successfully
+14. Verify Convex receives authenticated identity in backend functions
+15. If the user wants production-ready setup, make sure the same auth setup is configured for the production deployment as well
+16. Only add a `users` table and `storeUser` flow if the app needs app-level user records inside Convex
+
+## What This Reference Is For
+
+- choosing Convex Auth as the default provider for a new Convex app
+- understanding whether the app wants magic links, OTPs, OAuth, or passwords
+- keeping the setup provider-specific while using the official Convex Auth docs for identity and authorization behavior
+
+## What To Do
+
+- Read the Convex Auth setup guide before writing setup code
+- Follow the setup flow from the docs rather than recreating it from memory
+- If the app is new, consider starting from the official starter flow instead of hand-wiring everything
+- Treat `npx @convex-dev/auth` as a required initialization step for existing apps, not an optional extra
+
+## Concrete Steps
+
+1. Install `@convex-dev/auth` and `@auth/core@0.37.0`
+2. Run `npx convex dev` if the project does not already have a configured deployment
+3. If `npx convex dev` blocks on interactive setup, ask the user explicitly to finish configuring the Convex deployment
+4. Run `npx @convex-dev/auth`
+5. Confirm the generated auth setup is present before continuing:
+   - `convex/auth.config.ts`
+   - `convex/auth.ts`
+   - `convex/http.ts`
+6. Add `authTables` to `convex/schema.ts`
+7. Replace `ConvexProvider` with `ConvexAuthProvider` in the app entry
+8. Configure the selected auth methods in `convex/auth.ts`
+9. Run `npx convex dev --once` or the normal dev flow so the updated schema and auth files are pushed
+10. Verify login locally
+11. If the user wants production-ready setup, repeat the required auth configuration against the production deployment
+
+## Expected Files and Decisions
+
+- `convex/schema.ts`
+- frontend app entry such as `src/main.tsx` or the framework-equivalent provider file
+- generated Convex Auth setup produced by `npx @convex-dev/auth`
+- an existing configured Convex deployment, or the ability to create one with `npx convex dev`
+- `convex/auth.ts` starts with `providers: []` until the app configures actual sign-in methods
+
+- Decide whether the user is creating a new app or adding auth to an existing app
+- For a new app, prefer the official starter flow instead of rebuilding setup by hand
+- Decide which auth methods the app needs:
+  - magic links or OTPs
+  - OAuth providers
+  - passwords
+- Decide whether the user wants local-only setup or production-ready setup now
+- Decide whether the app actually needs a `users` table inside Convex, or whether provider identity alone is enough
+
+## Gotchas
+
+- Do not assume a specific sign-in method. Ask which methods the app needs before wiring UI and backend behavior.
+- `npx @convex-dev/auth` is important because it initializes the auth setup, including the key material. Do not skip it when adding Convex Auth to an existing project.
+- `npx @convex-dev/auth` will fail if the project does not already have a configured `CONVEX_DEPLOYMENT`.
+- `npx convex dev` may require interactive setup for deployment creation or project selection. If that happens, ask the user explicitly for that human step instead of guessing.
+- `npx @convex-dev/auth` does not finish the whole integration by itself. You still need to add `authTables`, swap in `ConvexAuthProvider`, and configure at least one auth method.
+- A project can still build even if `convex/auth.ts` still has `providers: []`, so do not treat a successful build as proof that sign-in is fully configured.
+- Convex Auth does not mean every app needs a `users` table. If the app only needs authentication gates, `ctx.auth.getUserIdentity()` may be enough.
+- If the app is greenfield, starting from the official starter flow is usually better than partially recreating it by hand.
+- Do not stop at local dev setup if the user expects production-ready auth. The production deployment needs the auth setup too.
+- Keep provider-specific setup and Convex Auth authorization behavior in the official docs instead of inventing shared patterns from memory.
+
+## Production
+
+- Ask whether the user wants dev-only setup or production-ready setup
+- If the answer is production-ready, make sure the auth configuration is applied to the production deployment, not just the dev deployment
+- Verify production-specific redirect URLs, auth method configuration, and deployment settings 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.
+
+## Human Handoff
+
+If `npx convex dev` or deployment setup requires human input:
+
+- stop and explain exactly what the user needs to do
+- say why that step is required
+- resume the auth setup immediately after the user confirms it is done
+
+## Validation
+
+- Verify the user can complete a sign-in flow
+- Offer to validate sign up, sign out, and sign back in with the configured auth method
+- If browser automation is available in the environment, you can do this directly
+- If browser automation is not available, give the user a short manual validation checklist instead
+- Verify `ctx.auth.getUserIdentity()` returns an identity in protected backend functions
+- Verify protected UI only renders after Convex-authenticated state is ready
+- Verify environment variables and redirect settings match the current app environment
+- Verify `convex/auth.ts` no longer has an empty `providers: []` configuration once the app is meant to support real sign-in
+- Run `npx convex dev --once` or the normal dev flow after setup changes and confirm Convex codegen and push succeed
+- If production-ready setup was requested, verify the production deployment is also configured correctly
+
+## Checklist
+
+- [ ] Confirm the user wants Convex Auth specifically
+- [ ] Ask whether the user wants local-only setup or production-ready setup
+- [ ] Ensure a Convex deployment is configured before running auth initialization
+- [ ] Install `@convex-dev/auth` and `@auth/core@0.37.0`
+- [ ] Run `npx convex dev` first if needed
+- [ ] Run `npx @convex-dev/auth`
+- [ ] Confirm `convex/auth.config.ts`, `convex/auth.ts`, and `convex/http.ts` were created
+- [ ] Follow the setup guide for package install and wiring
+- [ ] Add `authTables` to `convex/schema.ts`
+- [ ] Replace `ConvexProvider` with `ConvexAuthProvider`
+- [ ] Configure at least one auth method in `convex/auth.ts`
+- [ ] Run `npx convex dev --once` or the normal dev flow after setup changes
+- [ ] Confirm which sign-in methods the app needs
+- [ ] Verify the client can sign in and the backend receives authenticated identity
+- [ ] Offer end-to-end validation of sign up, sign out, and sign back in
+- [ ] If requested, configure the production deployment too
+- [ ] Only add extra `users` table sync if the app needs app-level user records

package/src/orchestrator/plugins/convex/references/auth-setup.md

@@ -0,0 +1,87 @@
+# Convex Authentication Setup
+
+Implement secure authentication in Convex with user management and access control.
+
+## Step 1: Choose the Auth Provider
+
+Do not assume a provider. Before writing setup code:
+1. Ask the user which auth solution they want, unless the repository already makes it obvious
+2. If the repo already uses a provider, continue with that provider unless the user wants to switch
+
+Check for signals: dependencies like `@clerk/*`, `@workos-inc/*`, `@auth0/*`, or Convex Auth packages; files like `convex/auth.config.ts`; environment variables pointing at a provider.
+
+| Provider | Use when |
+|----------|----------|
+| Convex Auth | Good default when the user wants auth handled directly in Convex |
+| Clerk | App already uses Clerk or user wants Clerk's hosted auth features |
+| WorkOS AuthKit | App already uses WorkOS or user wants AuthKit specifically |
+| Auth0 | App already uses Auth0 |
+| Custom JWT | Integrating an existing auth system not covered above |
+
+## Provider References
+
+- Convex Auth: [official docs](https://docs.convex.dev/auth/convex-auth) + `references/auth-convex-auth.md`
+- Clerk: [official docs](https://docs.convex.dev/auth/clerk) + `references/auth-clerk.md`
+- WorkOS AuthKit: [official docs](https://docs.convex.dev/auth/authkit/) + `references/auth-workos.md`
+- Auth0: [official docs](https://docs.convex.dev/auth/auth0) + `references/auth-auth0.md`
+
+## Core Pattern: Protecting Backend Functions
+
+```ts
+// Bad: trusting a client-provided userId
+export const getMyProfile = query({
+  args: { userId: v.id("users") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.userId);
+  },
+});
+```
+
+```ts
+// Good: verifying identity server-side
+export const getMyProfile = query({
+  args: {},
+  handler: async (ctx) => {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) throw new Error("Not authenticated");
+
+    return await ctx.db
+      .query("users")
+      .withIndex("by_tokenIdentifier", (q) =>
+        q.eq("tokenIdentifier", identity.tokenIdentifier)
+      )
+      .unique();
+  },
+});
+```
+
+## Workflow
+
+1. Determine the provider (ask or infer from repo)
+2. Read the matching provider reference file
+3. Follow the official provider docs for current setup details
+4. Follow the official Convex docs for shared backend auth behavior:
+   - [Auth in Functions](https://docs.convex.dev/auth/functions-auth) — `ctx.auth.getUserIdentity()`
+   - [Storing Users](https://docs.convex.dev/auth/database-auth) — optional app-level user storage
+5. Only add a `users` table and `storeUser` flow if the app actually needs user documents in Convex
+6. Add authorization checks for ownership, roles, or team access only where the app needs them
+7. Verify login state, protected queries, environment variables, and production configuration
+
+## Key Rules
+
+- For Convex Auth, follow built-in auth tables — don't add a parallel `users` table + `storeUser` flow
+- For third-party providers, only add app-level user storage if the app needs user documents in Convex
+- After running provider initialization commands, verify generated files and complete post-init wiring
+- Prefer `useConvexAuth()` over raw provider auth state when deciding whether Convex-authenticated UI can render
+
+## Checklist
+
+- [ ] Chosen auth provider
+- [ ] Read the matching provider reference file
+- [ ] Used official provider docs for provider-specific wiring
+- [ ] Used official Convex docs for shared auth behavior
+- [ ] Only added app-level user storage if the app needs it
+- [ ] Added `ctx.auth.getUserIdentity()` checks in protected backend functions
+- [ ] Clear error messages ("Not authenticated", "Unauthorized")
+- [ ] Client auth provider configured
+- [ ] Production auth setup covered if requested