create-ailk 0.8.0 → 0.10.0

package/templates/.claude/skills/add-auth/SKILL.md

@@ -1,68 +1,95 @@
 ---
 name: add-auth
-description: Activate auth providers (magic-link via Resend, Google OAuth, GitHub OAuth) on an AILK consumer site. Use when the user says "wire up auth", "add login", "set up sign-in", "I need users to log in", or asks how to enable any of magic-link / Google / GitHub auth on their AILK site. The skill writes env vars for whichever subset of providers the consumer activates and prints (plus saves) an OAuth-app-setup runbook. It does NOT modify `auth.config.ts` and does NOT emit any pages.
+description: Activate the site's sign-in providers (email-and-password, Google OAuth, GitHub OAuth) on an AILK consumer site. Use when the user says "wire up auth", "add login", "set up sign-in", "I need users to log in", or asks how to enable email / Google / GitHub sign-in on their AILK site. The skill writes env vars for whichever subset of providers the consumer activates and prints (plus saves) an OAuth-app-setup runbook. It does NOT modify `apps/web/auth.ts` and does NOT emit any pages.
 ---
 
 # add-auth
 
-Activate one or more auth providers on an AILK site by writing the env
-vars NextAuth reads to detect them, plus a `RUNBOOK.md` that documents
-the OAuth-app-creation steps for the consumer's records.
+Activate one or more sign-in providers on an AILK site by writing the
+env vars `getActiveProviderIds()` (`apps/web/lib/auth-env.ts`) reads
+to detect them, plus a `RUNBOOK.md` that documents the OAuth-app-creation
+steps for the consumer's records.
+
+The site's auth library is **Better Auth**, configured in
+`apps/web/auth.ts` and mounted at `apps/web/app/api/auth/[...all]/route.ts`.
 
 ## When to use
 
 The user has a working AILK site (post-`pnpm create ailk`) and wants
-to gate routes behind sign-in, send magic-link emails, or accept
-Google / GitHub OAuth. Phrases that should trigger this skill:
+to gate routes behind sign-in or accept email, Google or GitHub
+sign-in. Phrases that should trigger this skill:
 
 - "wire up auth" / "add login" / "set up sign-in"
 - "I want users to log in"
 - "enable Google sign-in" / "enable GitHub login"
-- "set up magic-link auth"
+- "set up email login" / "set up magic-link auth"
 - "add OAuth"
 
+A magic link is not wired: Better Auth core ships no magic-link
+provider, so the `email` provider id switches on email-and-password
+sign-in instead. Say so when the consumer asks for a magic link, and
+offer `email` on those terms.
+
 Skip this skill when:
 
-- The user wants a `/login` or `/account` _page_ — those are pages, not
-  auth wiring. Use `add-page` for that.
-- The user is asking about a third-party provider that isn't in the
-  AILK locked set (Apple, Microsoft, Twitter, etc.). The locked set is
-  magic-link + Google + GitHub at v1; broader provider support is a
-  future PR. Acknowledge the request and stop.
+- The user wants a new page. The site already ships its sign-in and
+  sign-up pages (`apps/web/app/[locale]/(auth)/`), which list whichever
+  providers are active. Any other page is `add-page`'s job.
+- The user is asking about a third-party provider outside the three
+  provider ids below (Apple, Microsoft, Twitter, etc.). Adding one is a
+  code change to `apps/web/auth.ts`, not env wiring. Acknowledge the
+  request and stop.
 - The user is in production and needs production callback URLs. v1
   ships dev-mode callbacks (`http://localhost:3000`) only —
   production callback setup is deferred to `setup-deploy`
   or a future deploy skill. Note this and stop.
 
+## The provider ids
+
+`getActiveProviderIds()` in `apps/web/lib/auth-env.ts` returns a
+provider id only when every one of its env vars is set to a non-empty
+value:
+
+| Provider id | Env vars                                    | What it switches on                                             |
+| ----------- | ------------------------------------------- | --------------------------------------------------------------- |
+| `email`     | `AUTH_EMAIL_SERVER` + `AUTH_EMAIL_FROM`     | Email-and-password sign-in (Better Auth's `emailAndPassword`)   |
+| `google`    | `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` | Google OAuth (Better Auth's `socialProviders.google`)           |
+| `github`    | `GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET` | GitHub OAuth (Better Auth's `socialProviders.github`)           |
+
+`references/env-vars.md` is the full contract, including the auxiliary
+vars (`BETTER_AUTH_URL`, `BETTER_AUTH_SECRET`, `AILK_AUTH_REQUIRED`,
+`AILK_AUTH_SIGNUP_OPEN`, `AILK_AUTH_PASSWORD_RESET`,
+`AUTH_EMAIL_WEBHOOK_SECRET`).
+
 ## What this skill does (and does not do)
 
 **Does:**
 
-- Reads `.env.local` to see which providers are already activated.
-- Asks the consumer which of the three locked providers
-  (magic-link, Google, GitHub) they want to activate _this session_.
+- Reads `.env.local` to see which provider ids are already active.
+- Asks the consumer which of the three provider ids (`email`,
+  `google`, `github`) they want to activate _this session_.
 - For each picked provider, walks the consumer through
-  OAuth-app-creation (Google / GitHub) or Resend-key setup
-  (magic-link), then writes the resulting secrets to `.env.local`.
-- Auto-detects whether `@working-theory/database` is installed with User /
-  Session models (Prisma adapter mode) or not (JWT-only mode), and
-  states which mode the site is in.
+  OAuth-app creation (`google` / `github`) or the Resend sender setup
+  (`email`), then writes the resulting values to `.env.local`.
+- Checks that sign-in has a database to write to. Better Auth always
+  runs its Prisma adapter with database sessions, so sign-in needs
+  `DATABASE_URL` and the auth tables in place.
 - Writes (or merges) a `RUNBOOK.md` in the consumer's repo root
   with the same setup instructions the consumer just followed, so
   they can refer back later or hand to a collaborator.
 
 **Does not:**
 
-- Modify `auth.config.ts`. The locked-set providers are env-var-driven
-  — present env vars activate the matching provider in
-  `auth.config.ts`'s `buildProviders()`. No code changes are needed.
+- Modify `apps/web/auth.ts`. The three provider ids are env-var-driven
+  — `apps/web/auth.ts` reads `getActiveProviderIds()` at startup and
+  builds only the providers it returns. No code changes are needed.
 - Create any new files under `app/`, `pages/`, or `content/`. The
   emit is limited to `.env.local` writes and a `RUNBOOK.md` write.
 - Set up production callback URLs. Dev-mode (`http://localhost:3000`)
   only at v1.
-- Add, remove, or modify any provider entry in `auth.config.ts`
-  outside of magic-link / Google / GitHub. Consumer-added providers
-  (e.g., Apple) are preserved as-is and never touched by this skill.
+- Add, remove, or modify any provider in `apps/web/auth.ts`. A
+  provider the consumer added there by hand (e.g., Apple) is preserved
+  as-is and never touched by this skill.
 - Accept production OAuth credentials. If the consumer pastes a
   production-looking secret, that's acceptable, but the runbook still
   documents only the dev callback URL.
@@ -71,28 +98,28 @@ Skip this skill when:
 
 ### Step 1 — Show the menu
 
-Greet the consumer and present the three locked providers, marking
-which are already activated (env vars present in `.env.local`):
+Greet the consumer and present the three provider ids, marking
+which are already active (env vars present in `.env.local`):
 
 ```
-Which auth providers do you want to activate?
+Which sign-in providers do you want to activate?
 
-  [ ] magic-link  (passwordless email login via Resend)
-  [ ] Google OAuth
-  [ ] GitHub OAuth
+  [ ] email   (email-and-password sign-in)
+  [ ] google  (Google OAuth)
+  [ ] github  (GitHub OAuth)
 
 You can pick any subset, including "none of the above" (in which case
 this skill exits without writing anything). You can also re-run this
-skill later to activate more providers — already-activated providers
+skill later to activate more providers — already-active providers
 will be skipped automatically.
 ```
 
-If `.env.local` already has any of these activated, mark them:
+If `.env.local` already has any of these active, mark them:
 
 ```
-  [x] magic-link  (already activated — AUTH_EMAIL_SERVER + AUTH_EMAIL_FROM are set)
-  [ ] Google OAuth
-  [ ] GitHub OAuth
+  [x] email   (already active — AUTH_EMAIL_SERVER + AUTH_EMAIL_FROM are set)
+  [ ] google  (Google OAuth)
+  [ ] github  (GitHub OAuth)
 ```
 
 Wait for the consumer to pick a subset. Then, for each picked
@@ -100,12 +127,13 @@ provider, run the matching sub-flow.
 
 ### Step 2 — Run per-provider sub-flows
 
-#### magic-link sub-flow
+#### `email` sub-flow
 
-1. Tell the consumer: _"Magic-link uses Resend as the email provider
-   at AILK v1. Other email providers ship as additive future PRs.
-   You'll need a Resend API key (free tier is fine for development).
-   Get one at <https://resend.com/api-keys>."_
+1. Tell the consumer: _"The `email` provider turns on
+   email-and-password sign-in. It switches on when `AUTH_EMAIL_SERVER`
+   and `AUTH_EMAIL_FROM` are both set. You'll need a Resend API key
+   (free tier is fine for development). Get one at
+   <https://resend.com/api-keys>."_
 2. Wait for the consumer to paste the API key.
 3. Ask for the `AUTH_EMAIL_FROM` address. This must be a verified
    sender on the consumer's Resend account. For development it's
@@ -118,16 +146,33 @@ provider, run the matching sub-flow.
    AUTH_EMAIL_SERVER=smtp://resend:re_...@smtp.resend.com:465
    AUTH_EMAIL_FROM=onboarding@resend.dev
    ```
-
-#### Google OAuth sub-flow
+6. Tell the consumer who actually sends the mail. `apps/web` sends
+   none: `AUTH_EMAIL_SERVER` is read for its presence only, and
+   `apps/web/lib/auth-email.ts` relays each auth email (verification,
+   password reset) to `apps/api`, which sends it with `RESEND_API_KEY`
+   from `AUTH_EMAIL_FROM`. For that mail to go out, `RESEND_API_KEY`
+   and `AUTH_EMAIL_FROM` must be set for `apps/api`, and
+   `AUTH_EMAIL_WEBHOOK_SECRET` (any long random string, the same value)
+   for both apps. Password reset — and the verification mail with it —
+   is off until `AILK_AUTH_PASSWORD_RESET=1`, and also needs
+   `BETTER_AUTH_URL` and `BETTER_AUTH_SECRET` (`resetSendConfigured()`
+   in `apps/web/lib/auth-env.ts`).
+7. Tell the consumer that public sign-up stays closed until they set
+   `AILK_AUTH_SIGNUP_OPEN=1` (read by `isSignUpOpen()` in
+   `apps/web/lib/auth-env.ts`). With sign-up closed and `email` the only
+   provider, nobody can create the first account — so either open
+   sign-up long enough to create it, or activate `google` or `github`
+   as well. Ask which they want; leave the flag unset otherwise.
+
+#### `google` sub-flow
 
 1. Tell the consumer the steps in chat AND queue the same content for
    the runbook (see Step 3). Steps:
    - Go to <https://console.cloud.google.com/apis/credentials>.
    - Click **Create Credentials → OAuth client ID**. If prompted,
      configure the OAuth consent screen first (**External** → fill
-     name, support email, developer contact email; scopes are
-     auto-populated by NextAuth).
+     name, support email, developer contact email; Better Auth
+     requests the scopes at runtime, so leave the scope list empty).
    - Application type: **Web application**.
    - Name: anything (e.g., "AILK dev").
    - **Authorized redirect URIs** — add exactly:
@@ -141,7 +186,7 @@ provider, run the matching sub-flow.
    GOOGLE_CLIENT_SECRET=...
    ```
 
-#### GitHub OAuth sub-flow
+#### `github` sub-flow
 
 1. Tell the consumer the steps in chat AND queue the same content for
    the runbook. Steps:
@@ -171,49 +216,56 @@ or refer back later.
 Use `references/oauth-app-setup.md` as the template. Replace
 `<provider>` headings as appropriate, and only include sections for
 providers actually activated this session. If `RUNBOOK.md` already
-exists with sections for already-activated providers, do not
+exists with sections for already-active providers, do not
 duplicate — add only the new sections beneath any existing content.
 
-### Step 4 — Detect the database adapter mode
+### Step 4 — Check the database
 
-Before printing the closing summary, check the consumer's setup:
+Sign-in always reads and writes the database: `apps/web/auth.ts`
+runs Better Auth's Prisma adapter, and sessions are rows, not
+cookie-only tokens. There is no database-free mode. Before printing
+the closing summary, check:
 
-- If `package.json` lists `@working-theory/database` as a dependency AND
-  `database/prisma/schema.prisma` defines `User` and `Session` models
-  → **Prisma adapter mode**. Sessions persist across server restarts.
-- Otherwise → **JWT-only mode**. Sessions are cookies, no database.
+- `DATABASE_URL` (and `DATABASE_URL_NON_POOLED`, which the migrations
+  use) is set in `.env.local`. If it is not, sign-in will fail on its
+  first request — point the consumer at the `setup-database` skill,
+  which sets both and creates the tables.
+- The auth tables exist. The Prisma schema is `database/schema.prisma`
+  (Prisma reads the whole `database/` folder; the `User`, `Session`,
+  `Account` and `Verification` models are in `database/auth/schema.prisma`).
+  If the consumer has not applied the migrations yet, they run
+  `pnpm db:migrate:deploy`.
 
-State the mode in the closing summary so the consumer is never
+State what you found in the closing summary so the consumer is never
 surprised:
 
-> "Your site is running in **Prisma adapter mode** — sessions persist
-> in the `User` and `Session` tables. Run `pnpm db:push` after this
-> skill if you haven't applied the migration yet."
+> "Sign-in stores its users and sessions in your database (the
+> `User` and `Session` tables). Run `pnpm db:migrate:deploy` if you
+> haven't applied the migrations yet."
 
-or
+or, when `DATABASE_URL` is unset:
 
-> "Your site is running in **JWT-only mode** — sessions are
-> cookie-only and don't require a database. To switch to persistent
-> sessions, install `@working-theory/database` and add the `User` / `Session`
-> models from `database/prisma/schema.prisma`."
+> "Sign-in needs a database and none is configured yet. Run the
+> `setup-database` skill before you try to sign in."
 
 ### Step 5 — Closing summary
 
 Print:
 
-- Which providers are now active (subset picked this session +
-  already-activated providers).
-- The database adapter mode (Prisma or JWT).
+- Which provider ids are now active (subset picked this session +
+  already-active providers).
+- What Step 4 found about the database.
 - A reminder to set `AILK_AUTH_REQUIRED=1` in `.env.local` if they
   want protected routes (default is auth-disabled / public).
 - A pointer to `RUNBOOK.md` for future reference.
-- A pointer to `setup-deploy` for production callback URL
-  setup when the consumer is ready to deploy.
+- A pointer to `setup-deploy` for production callback URLs and
+  `BETTER_AUTH_URL` / `BETTER_AUTH_SECRET` when the consumer is ready
+  to deploy — a production deploy fails without `BETTER_AUTH_SECRET`.
 
 ## Re-invocation
 
 The skill is idempotent. On a second run, the menu in Step 1 marks
-already-activated providers with `[x]` (read from `.env.local`), and
+already-active providers with `[x]` (read from `.env.local`), and
 the per-provider sub-flows skip those and only run for the new ones.
 The closing summary lists everything, not just what changed this
 session.
@@ -225,37 +277,37 @@ existing values in `.env.local`. Confirm before overwriting.
 
 ## Customization preservation
 
-If `auth.config.ts` has been modified by the consumer to add a
+If `apps/web/auth.ts` has been modified by the consumer to add a
 third-party provider (e.g., Apple), this skill leaves that file
-completely untouched. The skill never reads, edits, or even opens
-`auth.config.ts`. Activation of the AILK locked set happens entirely
-through env vars — `getActiveProviderIds()` in
-`apps/web/lib/auth-env.ts` is what reads them at startup.
+completely untouched. The skill never edits `apps/web/auth.ts`.
+Activation of the three provider ids happens entirely through env
+vars — `getActiveProviderIds()` in `apps/web/lib/auth-env.ts` is what
+reads them at startup.
 
 ## What "activation" means under the hood
 
-- **Provider list is computed at startup from env-var presence** in
-  `apps/web/auth.config.ts` → `buildProviders()`.
-- A provider is included only when every required env var is set:
-  - `email` (magic-link): `AUTH_EMAIL_SERVER` + `AUTH_EMAIL_FROM`
-  - `google`: `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET`
-  - `github`: `GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET`
+- **The provider list is computed at startup from env-var presence**
+  by `getActiveProviderIds()` in `apps/web/lib/auth-env.ts`.
+- `apps/web/auth.ts` consumes that list: `google` and `github` become
+  Better Auth `socialProviders` entries built from their env vars, and
+  `email` switches `emailAndPassword` on.
+- A provider id is returned only when every one of its env vars is set
+  (the table under § The provider ids).
 - A site with zero auth env vars boots cleanly with no active
-  providers (`apps/web/lib/auth-env.ts` returns an empty array).
+  providers (`getActiveProviderIds()` returns an empty array).
 
 This means the skill's job is purely env-var wiring + documentation.
 
 ## References
 
 - `references/oauth-app-setup.md` — RUNBOOK template the skill instantiates per session.
-- `references/env-vars.md` — env-var contract (which vars activate which provider).
+- `references/env-vars.md` — env-var contract (which vars activate which provider id).
 
 ## Coordination
 
-- **`add-page`** — `/login` or `/account` pages. This skill
-  emits no pages.
-- **`setup-deploy`** — production callback URL setup. v1
-  is dev-only.
-- **`@working-theory/database`** — Prisma adapter detection. Install
-  `@working-theory/database` separately to upgrade from JWT-only to persistent
-  sessions.
+- **`add-page`** — any new page. This skill emits no pages; the
+  sign-in and sign-up pages already ship.
+- **`setup-database`** — `DATABASE_URL` and the tables sign-in
+  needs.
+- **`setup-deploy`** — production callback URLs and the production
+  auth env vars. v1 of this skill is dev-only.

package/templates/.claude/skills/add-auth/references/env-vars.md

@@ -8,35 +8,51 @@ The activation logic lives in `apps/web/lib/auth-env.ts` →
 `getActiveProviderIds()`. A provider is active **only when every
 required var is set to a non-empty value**. Partial wiring (e.g.,
 `GOOGLE_CLIENT_ID` set but `GOOGLE_CLIENT_SECRET` missing) is treated
-as inactive — NextAuth never tries to construct that provider.
+as inactive — `apps/web/auth.ts` never constructs that provider.
+
+The site's auth library is **Better Auth** (`apps/web/auth.ts`,
+`betterAuth({ secret, baseURL, socialProviders, … })`).
 
 ## Provider activation table
 
 | Provider ID | Required env vars                            | Source                       |
 | ----------- | -------------------------------------------- | ---------------------------- |
-| `email`     | `AUTH_EMAIL_SERVER` + `AUTH_EMAIL_FROM`      | Magic-link (Resend at v1)    |
+| `email`     | `AUTH_EMAIL_SERVER` + `AUTH_EMAIL_FROM`      | Email sign-in (Resend)¹      |
 | `google`    | `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET`  | Google OAuth                 |
 | `github`    | `GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET`  | GitHub OAuth                 |
 
+¹ Better Auth core ships no magic-link provider, so `email` is an
+env-presence signal: it switches on the password method
+(`emailAndPassword`) in `apps/web/auth.ts`, not a wired magic link.
+
 ## Auxiliary auth env vars
 
 | Var                    | Default | Effect                                                                                |
 | ---------------------- | ------- | ------------------------------------------------------------------------------------- |
-| `AILK_AUTH_REQUIRED`   | unset   | When `"1"` or `"true"`, the middleware redirects unauthenticated users to `/api/auth/signin` for protected routes. Default is auth-disabled / public, so a fresh scaffold boots without requiring any auth wiring. |
-| `NEXTAUTH_URL`         | unset   | NextAuth uses this as the base URL when constructing callback URLs in production. Local dev defaults to `http://localhost:3000` so you can leave this unset for development. |
-| `NEXTAUTH_SECRET`      | unset   | NextAuth uses this to sign JWT tokens. **Must** be set for production — generate with `openssl rand -base64 32`. Optional for `next dev` (auto-generated for local-only sessions). |
-
-The skill writes none of these auxiliary vars on its own. It mentions
+| `AILK_AUTH_REQUIRED`   | unset   | Read by `isAuthRequired()` in `apps/web/lib/auth-env.ts` (`"1"` or `"true"`). Default is auth-disabled / public, so a fresh scaffold boots without requiring any auth wiring. |
+| `BETTER_AUTH_URL`      | unset   | The site's public origin (e.g. `https://your-domain.com`). Better Auth builds OAuth callback URLs on it and it is the one trusted origin; unset, Better Auth derives both from each request. Set it in production. Local dev can leave it unset. |
+| `BETTER_AUTH_SECRET`   | unset   | Signs session cookies and email-verification tokens. **Required in production** — `apps/web/auth.ts` throws when it is unset there, rather than fall back to the development secret published in the source. Generate with `openssl rand -base64 32`. Optional for `next dev`. |
+| `AILK_AUTH_SIGNUP_OPEN` | unset | Read by `isSignUpOpen()` in `apps/web/lib/auth-env.ts` (`"1"` or `"true"`). Unset, public sign-up is closed: with `email` active, the password form signs existing accounts in but creates none. |
+| `AILK_AUTH_PASSWORD_RESET` | unset | Read by `isResetAvailable()` (`"1"` or `"true"`). Password reset also needs `BETTER_AUTH_URL`, `BETTER_AUTH_SECRET` and `AUTH_EMAIL_WEBHOOK_SECRET` (`resetSendConfigured()`). |
+| `AUTH_EMAIL_WEBHOOK_SECRET` | unset | Signs the auth-mail relay from `apps/web` to `apps/api`, which sends with `RESEND_API_KEY` from `AUTH_EMAIL_FROM`. Set the same value for both apps; unset, no auth mail is sent. |
+
+The skill writes none of these auxiliary vars unasked. It mentions
 them in the closing summary so the consumer is aware:
 
 - `AILK_AUTH_REQUIRED` is the consumer's call (skill always defaults
   to leaving it unset).
-- `NEXTAUTH_URL` and `NEXTAUTH_SECRET` are deferred to production-time
-  setup (`setup-deploy` or future deploy skill).
+- `AILK_AUTH_SIGNUP_OPEN` is the consumer's call too; the skill asks
+  when `email` is active, because with sign-up closed and no OAuth
+  provider nobody can create the first account.
+- `AILK_AUTH_PASSWORD_RESET` and `AUTH_EMAIL_WEBHOOK_SECRET` are the
+  auth-mail setup the `email` sub-flow describes.
+- `BETTER_AUTH_URL` and `BETTER_AUTH_SECRET` are deferred to
+  production-time setup (`setup-deploy`), and a production deploy
+  fails without `BETTER_AUTH_SECRET`.
 
 ## Env-var formats — what valid values look like
 
-### `AUTH_EMAIL_SERVER` (magic-link via Resend)
+### `AUTH_EMAIL_SERVER` (email sign-in via Resend)
 
 ```
 smtp://resend:<RESEND_API_KEY>@smtp.resend.com:465
@@ -46,7 +62,7 @@ The Resend API key starts with `re_`. The literal username is the
 string `resend` (Resend's SMTP convention). Port 465 is implicit-TLS
 SMTP.
 
-### `AUTH_EMAIL_FROM` (magic-link via Resend)
+### `AUTH_EMAIL_FROM` (email sign-in via Resend)
 
 A verified sender address on the consumer's Resend account. For
 development, `onboarding@resend.dev` works without verification.
@@ -73,7 +89,7 @@ The skill's Step 1 menu marks providers as `[x]` when both required
 vars are set in `.env.local`. The detection is presence-only — the
 skill does not validate that the values actually work (no Google
 API ping, no GitHub API ping, no test SMTP connection). A consumer
-who pasted typos will get a runtime auth error from NextAuth on
+who pasted typos will get a runtime auth error from Better Auth on
 their first sign-in attempt; the fix is to re-run the skill and
 overwrite.
 
@@ -81,11 +97,10 @@ overwrite.
 
 - `apps/web/lib/auth-env.ts` — `getActiveProviderIds()` and
   `isAuthRequired()`.
-- `apps/web/auth.config.ts` — `buildProviders()` consumes the
-  active-provider list and constructs NextAuth provider objects with
-  the matching env vars.
-- `apps/web/middleware.ts` — `isAuthRequired()` decides whether to
-  redirect unauthenticated users.
+- `apps/web/auth.ts` — `buildSocialProviders()` consumes the
+  active-provider list and builds Better Auth's `socialProviders`
+  from the matching env vars; `resolveSecret()` reads
+  `BETTER_AUTH_SECRET`, and `baseURL` is `BETTER_AUTH_URL`.
 
 The skill never modifies any of those files. All activation is
 env-var-driven.

package/templates/.claude/skills/add-auth/references/oauth-app-setup.md

@@ -1,4 +1,4 @@
-# OAuth + Magic-Link Setup — RUNBOOK Template
+# OAuth + Email Sign-In Setup — RUNBOOK Template
 
 The `add-auth` skill writes (or merges into) `RUNBOOK.md` at the
 consumer's repo root using the per-provider sections below. Only the
@@ -10,13 +10,13 @@ sections appear in the final runbook.
 
 ---
 
-## Provider section: magic-link (Resend)
+## Provider section: email (Resend)
 
 ```markdown
-## Auth — magic-link (Resend)
+## Auth — email sign-in (Resend)
 
-Magic-link sign-in uses Resend as the email provider. Activation is
-keyed off two env vars in `.env.local`:
+Email-and-password sign-in is activated when both env vars are present
+in `.env.local`:
 
 - `AUTH_EMAIL_SERVER` — `smtp://resend:<API_KEY>@smtp.resend.com:465`
 - `AUTH_EMAIL_FROM` — verified sender address on your Resend account
@@ -30,6 +30,14 @@ keyed off two env vars in `.env.local`:
    Resend's shared dev sender and works without verification. For
    production, verify your own sending domain in the Resend dashboard.
 
+`AUTH_EMAIL_SERVER` is read for its presence only. The auth mail
+(verification, password reset) is sent by `apps/api` with
+`RESEND_API_KEY` from `AUTH_EMAIL_FROM`, so set both for the API, and
+set `AUTH_EMAIL_WEBHOOK_SECRET` to the same random value for both apps.
+
+Public sign-up stays closed until you set `AILK_AUTH_SIGNUP_OPEN=1` in
+`.env.local`.
+
 ### `.env.local` entries
 
 \`\`\`
@@ -62,7 +70,7 @@ Google sign-in is activated when both env vars are present in
 2. If you haven't yet, configure the OAuth consent screen:
    - User type: **External** (unless you're inside a Workspace org).
    - Fill in app name, support email, and developer contact email.
-   - Scopes are auto-populated by NextAuth at runtime — leave the
+   - Scopes are requested by Better Auth at runtime — leave the
      consent screen scope list empty.
 3. Click **Create Credentials → OAuth client ID**.
 4. Application type: **Web application**.
@@ -152,13 +160,14 @@ The Client ID stays the same.
 
 | Provider    | Env vars                                          | Active |
 | ----------- | ------------------------------------------------- | ------ |
-| magic-link  | `AUTH_EMAIL_SERVER` + `AUTH_EMAIL_FROM`           | <fill> |
+| email       | `AUTH_EMAIL_SERVER` + `AUTH_EMAIL_FROM`           | <fill> |
 | Google      | `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET`       | <fill> |
 | GitHub      | `GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET`       | <fill> |
 
 A provider is **active** when both required env vars are set in
 `.env.local`. The provider list is computed at server startup from env
-vars only — there are no `auth.config.ts` edits to make.
+vars only (`getActiveProviderIds()` in `apps/web/lib/auth-env.ts`) — there
+are no `apps/web/auth.ts` edits to make.
 
 To require sign-in for protected routes, set in `.env.local`: