Consider optional minimal Convex Auth password setup after onboarding

[nicu-chiciuc]

Context

We discussed whether this template should ship with Convex Auth enabled from the start. The goal is to give users a simple way to protect a small app for themselves, family, or friends without turning the initial onboarding into an auth/deployment exercise.

The main tension: Convex Auth is the right auth system to use, but enabling it during first-run onboarding introduces deployment-specific setup:

• JWT_PRIVATE_KEY and JWKS are still required, even for password or guest-style auth, because Convex Auth issues JWTs.
• Those values are per Convex deployment, so production and preview deployments can become confusing.
• SITE_URL is not needed for password-only auth, but the Convex Auth initializer asks for it because it also supports OAuth and magic links.
• We do not want to invent our own password/session system just to avoid Convex Auth setup.
• We also do not want to expand the README with too much advanced auth material before the user has finished deploying the starter app.

Current leaning

Keep the first onboarding flow focused on deploying the app successfully. Treat Convex Auth as an optional, recommended next step after onboarding.

For the simplest useful auth, prefer Convex Auth's built-in Password provider rather than custom auth. Passwords are hashed by Convex Auth's provider, and sessions/tokens remain managed by Convex Auth.

Possible design

Add an optional "Enable private login" path after the main onboarding:

1. Run the official Convex Auth setup for the relevant Convex deployment.
2. Configure Convex Auth with the Password provider only.
3. Do not enable OAuth, magic links, public signup, reset emails, or email verification by default.
4. Add a Convex Dashboard-only internal setup function, for example setup:createPasswordUser.
5. The setup function creates a Convex Auth password account for a username/email and password.
6. The app login UI only supports sign-in/sign-out.
7. Users can create accounts for themselves or trusted family/friends from the Convex Dashboard.

This keeps the app on Convex Auth while avoiding public signup and avoiding a custom password/session implementation.

Environment notes

• JWT_PRIVATE_KEY and JWKS are required for Convex Auth token signing/verification.
• These should not be committed to the template.
• They must be generated/set for each deployment where auth should work.
• SITE_URL should not be part of the password-only setup story unless OAuth, magic links, email verification, or reset links are added later.
• Preview deployments need separate thought because auth env vars are deployment-specific.

Open questions

• Should the optional setup remain CLI-first with vp dlx @convex-dev/auth, or should the template provide a Dashboard-run helper to generate/copy key material?
• Should preview auth be unsupported by default, documented as advanced, or handled through project/default env var guidance?
• What is the cleanest way to block public signup while still using Convex Auth's Password provider for Dashboard-created users?
• Where should the optional instructions live so the main README remains approachable?

Acceptance criteria for a future implementation

• First-time deployment remains simple and does not require auth setup.
• Optional private login uses Convex Auth, not a custom auth/session system.
• Password-only setup does not require SITE_URL.
• JWT_PRIVATE_KEY and JWKS setup is clearly explained and not stored in git.
• Production vs preview deployment implications are documented without overwhelming first-time users.
• The README stays focused; deeper auth notes can live in an issue, short appendix, or linked follow-up guide.