create-ailk 0.9.0 → 0.10.0

package/templates/.claude/agents/web.md

@@ -22,8 +22,8 @@ upstream packages; don't try to edit them locally.
 ## Read before edit
 
 1. `.claude/rules/architecture.md` — confirm what `apps/web` may
-   import. NextAuth handlers are the only API-shaped code allowed in
-   `apps/web`; everything else server-side goes through `apps/api`.
+   import, including its one database exception (the Better Auth
+   adapter). Everything else server-side goes through `apps/api`.
 2. The page or component you're modifying, plus any sibling files in
    the same directory.
 3. Any project-local theme override file before touching styles —
@@ -46,7 +46,8 @@ Run `pnpm preflight` before opening a PR.
 - Need a new content type? Add it under `content/<TypeName>/` and
   reference the schema from `@working-theory/schema`.
 - Need a database read? Wrong layer — `apps/web` does not read the
-  database. Route through `apps/api`.
+  database outside the one exception `.claude/rules/architecture.md`
+  names. Route through `apps/api`.
 
 ## Domain conventions
 
@@ -55,23 +56,24 @@ Run `pnpm preflight` before opening a PR.
   Adding `'use client'` to a file that just renders JSX is the
   default failure mode — resist it.
 - **Tailwind tokens only.** No raw hex, rgb, or arbitrary colors.
-  Use semantic tokens from `@working-theory/theme` (`bg-canvas`, `text-fg`,
+  Use semantic tokens from `@working-theory/theme` (`bg-surface`, `text-fg`,
   `border-border`, etc.). If a token doesn't exist, extend the theme;
   don't bypass.
 - **Mobile-first responsive.** Default styles target mobile;
   `md:`/`lg:` modifiers for larger viewports.
 - **MDX rendering** uses `next-mdx-remote/rsc`, never `@next/mdx`
   (the latter requires runtime config that fights Server Components).
-- **NextAuth handlers** are the only API-shaped code in `apps/web`
-  — they live at `apps/web/app/api/auth/[...nextauth]/route.ts`.
+- **Better Auth's route handler** is the only API-shaped code in
+  `apps/web` — it lives at `apps/web/app/api/auth/[...all]/route.ts`.
   Everything else goes to `apps/api`.
 
 ## Forbidden
 
 - Importing from `apps/api` or `apps/mcp` — these are peer apps;
   speak to the API via `@working-theory/api-client`.
-- Importing `@working-theory/database` — `apps/web` does not touch the DB;
-  route through `apps/api`.
+- Importing `@working-theory/database` outside the Better Auth adapter
+  (the exception `.claude/rules/architecture.md` names) — route through
+  `apps/api`.
 - Importing `resend`, `@react-email/*` directly — wrap through
   `@working-theory/email`, server-side via `apps/api`.
 - Adding a `utils.ts`, `helpers.ts`, `common.ts`, or `misc.ts` file

package/templates/.claude/rules/architecture.md

@@ -25,13 +25,16 @@ other.
   or `@working-theory/schema` (schema.org types).
 - Need an HTTP call from `apps/web` to `apps/api`? Use
   `@working-theory/api-client`. Don't import API route handlers directly.
-- Need database access? Only `apps/api` and `apps/mcp` import
-  `@working-theory/database`. `apps/web` never reads the database directly — it
-  goes through the HTTP API.
-- Cross-cutting integrations (auth, email, analytics) go through their
-  wrapper packages: `@working-theory/auth-client`, `@working-theory/email`,
-  `@working-theory/analytics`. Never import `next-auth`, `resend`, etc.
-  directly.
+- Need database access? `apps/api` and `apps/mcp` import
+  `@working-theory/database`. `apps/web` does not read the database — it goes
+  through `apps/api` via the published HTTP client. The one exception is the
+  Better Auth adapter (`apps/web/lib/prisma-for-auth.ts`, typed in
+  `apps/web/auth.ts`).
+- Cross-cutting integrations (email, analytics) go through their
+  wrapper packages: `@working-theory/email`, `@working-theory/analytics`.
+  Never import `resend`, etc. directly. Auth has no wrapper package: it is
+  Better Auth, configured in `apps/web/auth.ts` and mounted at
+  `apps/web/app/api/auth/[...all]/route.ts`.
 
 ## What you can verify, what you can't
 

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

@@ -32,12 +32,20 @@ env-presence signal: it switches on the password method
 | `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 on its own. It mentions
+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).
+- `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`.

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
 
 \`\`\`
@@ -152,7 +160,7 @@ 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> |
 

package/templates/.claude/skills/add-page/references/page-types.md

@@ -1,17 +1,16 @@
-<!-- GENERATED — do not hand-edit. Regenerate with:
-       cd packages/create-ailk && pnpm page-types:build
-     Source: packages/schema/src/registry/entries.ts
-     Generator: packages/create-ailk/scripts/generate-page-types-reference.ts
+<!-- GENERATED — do not hand-edit. AI Launch Kit generates this file
+     from its page-type registry and ships it with the scaffold. The
+     source of record for this site's own page-type registry is `pageTypeRegistry` in the installed `@working-theory/schema` package.
 -->
 
 # Page-Type → schema.org Registry Reference
 
 The full page-type catalog the `add-page` skill reads at runtime to
 resolve a slug or page-purpose hint to a family, chassis, schema.org
-`@type`, and route convention. Generated from
-`packages/schema/src/registry/entries.ts` — every registered page type
-appears exactly once, list/detail pairs are shown together, and no row
-here can name a type the registry doesn't have.
+`@type`, and route convention. Generated from the page-type registry
+`@working-theory/schema` exports — every registered page type appears
+exactly once, list/detail pairs are shown together, and no row here
+can name a type the registry doesn't have.
 
 The skill resolves in this order:
 
@@ -30,8 +29,8 @@ levels). The level is the module's, never a claim about this site's key.
 `<slug>` in a route below is the page's own slug (e.g. `hello-world`);
 `<Type>` families using two-layer builders route supplementary schema
 through the `schema:` frontmatter override — see this skill's
-[Adding schema to an existing page](../SKILL.md#adding-schema-to-an-existing-page) section, or `packages/schema/README.md` for the full
-override contract.
+[Adding schema to an existing page](../SKILL.md#adding-schema-to-an-existing-page) section, or the installed `@working-theory/schema`
+package's README for the full override contract.
 
 ## Core