create-ailk 0.1.0

package/templates/.claude/skills/provision-config/references/runbook-template.md

@@ -0,0 +1,248 @@
+# `RUNBOOK.md` Template
+
+The `provision-config` skill emits this runbook at the consumer's
+project root. It documents pre-deploy steps, the **critical**
+leads-persistence caveat, and the three named upgrade paths.
+
+The skill must verify all three named persistence-section headings
+are present after emit (per SKILL.md Step 6 validation). If any is
+missing, the skill has a bug.
+
+## Template
+
+```markdown
+# RUNBOOK — Production Operations
+
+This runbook is generated by the `provision-config` skill. It covers
+what to do before and after deploying to Vercel, plus the
+operational caveats AILK ships with.
+
+If you re-run `provision-config`, new sections may be appended at
+the end under "## Added by provision-config." Existing sections are
+not modified by the skill.
+
+---
+
+## Pre-deploy checklist
+
+Before you click Deploy in Vercel:
+
+- [ ] **Add a Vercel project** pointed at this repo
+      (`vercel link` from the CLI, or the dashboard).
+- [ ] **Set environment variables** in Vercel's project dashboard
+      (Settings → Environment Variables). Use `.env.example` as the
+      contract — every variable listed there should have a value
+      set in Vercel before deploy.
+- [ ] **Configure your custom domain** if you have one (Vercel
+      Project → Settings → Domains). Vercel handles TLS automatically.
+- [ ] **Pick a leads-persistence backend** — see the three named
+      upgrade paths below. **Do not deploy without picking one** if
+      your site captures leads. AILK's default `leads.jsonl`
+      fallback does not persist on Vercel's ephemeral filesystem.
+- [ ] **Register production OAuth callbacks** if you used
+      `scaffold-auth` and activated Google or GitHub. Each provider
+      needs the prod callback URL added to its OAuth app settings.
+
+---
+
+## Operations — leads.jsonl persistence
+
+> **Critical:** AILK's default lead-capture writes to
+> `apps/api/leads.jsonl`. On Vercel's ephemeral filesystem, this
+> file **does not persist** across cold starts. Leads captured
+> during one container's lifetime are lost when that container
+> shuts down.
+
+You **must** pick a persistence backend before going live or you
+will lose leads. Pick one of the three sections below based on
+your situation:
+
+- Cheapest fix, drop-in, native Vercel — **Vercel KV**
+- One provider for db + auth + storage — **Supabase**
+- Already have Postgres elsewhere — **Postgres via `@working-theory/database`**
+
+---
+
+## Persistence upgrade — Vercel KV
+
+**When to pick:** you want the cheapest fix, no new infra, and
+you're already on Vercel. Vercel KV is Redis-compatible key-value
+storage, native to the Vercel dashboard.
+
+**Setup:**
+
+1. Vercel Dashboard → Storage → Create Database → KV.
+2. Connect to your project. Vercel auto-populates
+   `KV_REST_API_URL` and `KV_REST_API_TOKEN` in your project
+   environment.
+3. Pull updated env vars locally: `vercel env pull`.
+4. Switch the lead-capture writer in your code from JSONL to KV
+   (`@working-theory/api`'s lead-capture supports a KV adapter — see its
+   README for the wiring).
+5. Redeploy.
+
+**Trade-offs:** KV is fast and easy but has limits (storage
+ceilings, access patterns). For >10K leads/month or rich querying,
+graduate to Supabase or Postgres.
+
+---
+
+## Persistence upgrade — Supabase
+
+**When to pick:** you want one provider for database, auth, and
+storage. You're not committed to NextAuth (Supabase has its own
+auth), or you're fine running NextAuth + Supabase auth in parallel.
+
+**Setup:**
+
+1. Sign up at <https://supabase.com>.
+2. Create a project.
+3. Go to Settings → API. Copy:
+   - `Project URL` → `NEXT_PUBLIC_SUPABASE_URL`
+   - `anon public` key → `NEXT_PUBLIC_SUPABASE_ANON_KEY`
+   - `service_role` key → `SUPABASE_SERVICE_ROLE_KEY` (server-only)
+4. Set those three env vars in Vercel project settings.
+5. Run the AILK Supabase migration (see `@working-theory/database` Supabase
+   adapter README — the migration creates a `leads` table with the
+   AILK schema).
+6. Switch the lead-capture writer to use the Supabase adapter.
+7. Redeploy.
+
+**Trade-offs:** Supabase is generous on free tier, scales well, and
+its dashboard is excellent. The auth coexistence with NextAuth is
+the only design wrinkle — most consumers either use NextAuth alone
+(treating Supabase as just a Postgres host) or commit to Supabase
+auth and remove NextAuth.
+
+---
+
+## Persistence upgrade — Postgres via `@working-theory/database`
+
+**When to pick:** you already have Postgres somewhere — Neon,
+Railway, RDS, self-hosted, anywhere. You don't need a new provider
+relationship.
+
+**Setup:**
+
+1. Get a Postgres connection string from your provider. Format:
+   `postgres://user:password@host:5432/dbname`.
+2. Set `DATABASE_URL` in Vercel project settings.
+3. Install `@working-theory/database`: `pnpm add @working-theory/database`.
+4. Run the migration:
+   `pnpm --filter @working-theory/database run migrate:deploy` (or your
+   provider's equivalent).
+5. The `@working-theory/database` package exposes a Prisma client tied to the
+   AILK schema; switch the lead-capture writer to use it.
+6. Redeploy.
+
+**Trade-offs:** most flexible, most setup. You manage the database
+yourself (backups, connection pooling, scaling). For consumers who
+already have Postgres in their stack, this is the natural fit.
+
+---
+
+## Custom domain + DNS
+
+Vercel handles TLS automatically once a domain is added to your
+project. Two paths:
+
+- **Vercel-managed DNS** — let Vercel handle nameservers. Easiest;
+  Vercel Dashboard → Project → Settings → Domains → Add → "Manage
+  DNS Records."
+- **External DNS** — add an A record (or CNAME for subdomains)
+  pointing at Vercel's IP, then add the domain to your project.
+  Vercel docs walk through it.
+
+For email-sending domains (Resend, magic-link), you'll also need
+to verify the sending domain in Resend's dashboard before
+production magic-link emails will deliver. Resend Dashboard →
+Domains → Add → DNS records → wait for verification.
+
+---
+
+## Production callbacks for OAuth (if you used `scaffold-auth`)
+
+If you activated Google or GitHub OAuth via `scaffold-auth` (#364),
+those activations used dev callback URLs (`localhost:3000`). For
+production, add the prod callback URLs to each OAuth app:
+
+### Google
+
+1. Open the Google Cloud Console OAuth client you created
+   (<https://console.cloud.google.com/apis/credentials>).
+2. Under **Authorized redirect URIs**, add:
+   `https://<your-prod-domain>/api/auth/callback/google`
+3. Save.
+
+### GitHub
+
+1. Open the GitHub OAuth App you created
+   (<https://github.com/settings/developers>).
+2. Edit either:
+   - The same app's **Authorization callback URL** to add a second
+     line for prod (GitHub allows multiple).
+   - Or create a separate OAuth App for production.
+3. Update the env vars in Vercel if you created a separate app.
+
+---
+
+## When to redeploy
+
+- After changing any `NEXT_PUBLIC_*` env var (those bake at build
+  time).
+- After running database migrations (data shape changed).
+- After updating `vercel.json` (deploy config changed).
+
+You do **not** need to redeploy after:
+
+- Adding a non-`NEXT_PUBLIC_*` env var in Vercel's dashboard
+  (server-side reads pick it up on next request).
+- Editing MDX content in `content/` and pushing — Vercel rebuilds
+  on push.
+
+---
+
+## Troubleshooting
+
+- **"My leads disappeared"** → you skipped the leads-persistence
+  upgrade. Pick one of Vercel KV / Supabase / Postgres above and
+  migrate the writer.
+- **"OAuth login redirects to localhost in production"** → you
+  haven't added the production callback URL to the OAuth app
+  (see above).
+- **"Magic-link emails aren't arriving in production"** → your
+  Resend sender domain isn't verified yet (Resend Dashboard →
+  Domains).
+
+---
+```
+
+## Section headings the validation must find
+
+After emit, the skill must grep for these three headings (verbatim
+match). All three must be present:
+
+- `## Persistence upgrade — Vercel KV`
+- `## Persistence upgrade — Supabase`
+- `## Persistence upgrade — Postgres via `@working-theory/database\``
+
+If any is missing, the template was edited in a way that broke the
+contract. Surface the failure to the consumer (not silent).
+
+## Merge logic
+
+If the consumer already has `RUNBOOK.md`, the skill (per SKILL.md
+Step 3) offers merge / overwrite / skip. Merge logic:
+
+1. Read the existing file.
+2. Check whether each of the three named persistence section
+   headings is already present.
+3. Headings already present → not modified.
+4. Headings missing → append at the end of the existing file under:
+   ```
+   ## Added by provision-config
+   ```
+
+The pre-deploy checklist, custom-domain, and OAuth-prod-callbacks
+sections are also appended if missing. Sections that are already
+present (even with different content) are not modified.

package/templates/.claude/skills/provision-config/references/vercel-json-template.md

@@ -0,0 +1,98 @@
+# `vercel.json` Template
+
+The minimal viable Vercel config the `provision-config` skill emits.
+Customization beyond this template is the consumer's responsibility —
+the skill's job is to ship the consumer with a working baseline.
+
+## Template
+
+```json
+{
+  "version": 2,
+  "framework": "nextjs",
+  "buildCommand": "pnpm build",
+  "installCommand": "pnpm install --frozen-lockfile",
+  "env": {}
+}
+```
+
+## Field-by-field
+
+### `version: 2`
+
+Required. Vercel config schema version. Always `2` at v1.
+
+### `framework: "nextjs"`
+
+The skill assumes the consumer's `apps/web` is a Next.js app (the
+AILK scaffold default). Other valid values exist in Vercel's docs
+but the skill emits `nextjs` only. Consumers on bespoke setups can
+overwrite the file post-emission.
+
+### `buildCommand`
+
+The default `pnpm build` works for single-app deploys (the AILK
+scaffold's `apps/web` is the deploy target). For monorepo deploys
+where the consumer wants Vercel to build the whole tree, suggest
+the consumer change this to:
+
+```
+cd ../.. && pnpm install --frozen-lockfile && pnpm --filter ./apps/web build
+```
+
+The skill does NOT auto-detect monorepo vs single-app — the consumer
+edits the field if their setup deviates. Surface the alternative as
+a comment in the chat after emit, not in the JSON file (JSON has
+no comments).
+
+### `installCommand`
+
+Default `pnpm install --frozen-lockfile`. Match the consumer's
+package manager:
+
+- pnpm — `pnpm install --frozen-lockfile`
+- npm — `npm ci`
+- yarn — `yarn install --frozen-lockfile`
+
+The skill detects the package manager by checking for `pnpm-lock.yaml`,
+`package-lock.json`, or `yarn.lock` at the project root. Default
+to pnpm if none is found (AILK scaffold ships pnpm).
+
+### `env: {}`
+
+Empty by default. Vercel's project-level env-var dashboard is the
+canonical place to set production values — `.env.example` is the
+contract, the dashboard is the values.
+
+If the consumer specifically asks for build-time env-var defaults
+(e.g., `NODE_ENV: "production"`), the skill can populate the field.
+But the default is empty.
+
+## What this template intentionally omits
+
+- **`routes`** — Next.js App Router handles routing; `vercel.json`
+  routing is for non-Next.js apps. AILK is Next.js.
+- **`outputDirectory`** — Vercel auto-detects `.next` for Next.js.
+- **`functions`** — per-function config is rarely needed for AILK's
+  shape. Consumers who need it (long-running cron, large payload
+  tolerances) edit post-emission.
+- **`regions`** — Vercel's default multi-region routing is fine for
+  AILK at v1. Consumers with strict latency requirements add this
+  themselves.
+- **`crons`** — AILK doesn't ship scheduled jobs. Consumer-added
+  crons go in post-emit edits.
+
+The template is small on purpose. A 100-line `vercel.json` carries a
+maintenance cost the consumer didn't ask for. Five fields is enough
+to deploy.
+
+## Validation after emit
+
+After writing, the skill must:
+
+1. Parse the file as JSON. If it fails to parse, the skill has a bug
+   (the template is hand-authored JSON; a parse failure means the
+   template was edited in a way that broke it).
+2. Confirm the field count matches the template (5 fields). Extra
+   fields are fine if the consumer's existing file had more (in
+   merge mode, but `vercel.json` doesn't merge — see SKILL.md Step 3).

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

@@ -0,0 +1,261 @@
+---
+name: scaffold-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.
+---
+
+# scaffold-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.
+
+## 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:
+
+- "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"
+- "add OAuth"
+
+Skip this skill when:
+
+- The user wants a `/login` or `/account` _page_ — those are pages, not
+  auth wiring. Use `scaffold-page` (#362) 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 is in production and needs production callback URLs. v1
+  ships dev-mode callbacks (`http://localhost:3000`) only —
+  production callback setup is deferred to `provision-config` (#367)
+  or a future deploy skill. Note this and stop.
+
+## 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_.
+- 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.
+- 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.
+- 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.
+- 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.
+
+## The mechanic
+
+### 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`):
+
+```
+Which auth providers do you want to activate?
+
+  [ ] magic-link  (passwordless email login via Resend)
+  [ ] Google OAuth
+  [ ] 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
+will be skipped automatically.
+```
+
+If `.env.local` already has any of these activated, mark them:
+
+```
+  [x] magic-link  (already activated — AUTH_EMAIL_SERVER + AUTH_EMAIL_FROM are set)
+  [ ] Google OAuth
+  [ ] GitHub OAuth
+```
+
+Wait for the consumer to pick a subset. Then, for each picked
+provider, run the matching sub-flow.
+
+### Step 2 — Run per-provider sub-flows
+
+#### magic-link 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>."_
+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
+   common to use `onboarding@resend.dev` (Resend's shared dev
+   sender). Mention that.
+4. Construct `AUTH_EMAIL_SERVER` as
+   `smtp://resend:<API_KEY>@smtp.resend.com:465`.
+5. Write to `.env.local`:
+   ```
+   AUTH_EMAIL_SERVER=smtp://resend:re_...@smtp.resend.com:465
+   AUTH_EMAIL_FROM=onboarding@resend.dev
+   ```
+
+#### Google OAuth 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).
+   - Application type: **Web application**.
+   - Name: anything (e.g., "AILK dev").
+   - **Authorized redirect URIs** — add exactly:
+     `http://localhost:3000/api/auth/callback/google`
+   - Click **Create**. Copy the **Client ID** and **Client secret**
+     from the dialog.
+2. Wait for the consumer to paste both values.
+3. Write to `.env.local`:
+   ```
+   GOOGLE_CLIENT_ID=...
+   GOOGLE_CLIENT_SECRET=...
+   ```
+
+#### GitHub OAuth sub-flow
+
+1. Tell the consumer the steps in chat AND queue the same content for
+   the runbook. Steps:
+   - Go to <https://github.com/settings/developers>.
+   - Click **New OAuth App**.
+   - Application name: anything (e.g., "AILK dev").
+   - Homepage URL: `http://localhost:3000`
+   - **Authorization callback URL** — add exactly:
+     `http://localhost:3000/api/auth/callback/github`
+   - Click **Register application**. Generate a new client secret.
+     Copy the **Client ID** and **Client secret**.
+2. Wait for the consumer to paste both values.
+3. Write to `.env.local`:
+   ```
+   GITHUB_CLIENT_ID=...
+   GITHUB_CLIENT_SECRET=...
+   ```
+
+### Step 3 — Write the RUNBOOK
+
+After all picked providers are activated, write
+`RUNBOOK.md` (or merge into existing) at the consumer's repo root.
+The runbook captures the OAuth-app-creation steps and Resend setup
+the consumer just walked through, so they can hand it to a teammate
+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
+duplicate — add only the new sections beneath any existing content.
+
+### Step 4 — Detect the database adapter mode
+
+Before printing the closing summary, check the consumer's setup:
+
+- 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.
+
+State the mode 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."
+
+or
+
+> "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`."
+
+### Step 5 — Closing summary
+
+Print:
+
+- Which providers are now active (subset picked this session +
+  already-activated providers).
+- The database adapter mode (Prisma or JWT).
+- 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 `provision-config` (#367) for production callback URL
+  setup when the consumer is ready to deploy.
+
+## 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
+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.
+
+If the consumer wants to _change_ a previously-activated provider's
+secrets (e.g., rotated their Google Client Secret), they should pick
+that provider in the menu and the sub-flow will overwrite the
+existing values in `.env.local`. Confirm before overwriting.
+
+## Customization preservation
+
+If `auth.config.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.
+
+## 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`
+- A site with zero auth env vars boots cleanly with no active
+  providers (`apps/web/lib/auth-env.ts` 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).
+
+## Coordination
+
+- **`scaffold-page` (#362)** — `/login` or `/account` pages. This skill
+  emits no pages.
+- **`provision-config` (#367)** — 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.

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

@@ -0,0 +1,91 @@
+# Auth Env-Var Contract
+
+Source of truth for which env vars activate which auth provider on
+an AILK consumer site. Read by the `scaffold-auth` skill before
+asking the consumer to paste secrets.
+
+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.
+
+## Provider activation table
+
+| Provider ID | Required env vars                            | Source                       |
+| ----------- | -------------------------------------------- | ---------------------------- |
+| `email`     | `AUTH_EMAIL_SERVER` + `AUTH_EMAIL_FROM`      | Magic-link (Resend at v1)    |
+| `google`    | `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET`  | Google OAuth                 |
+| `github`    | `GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET`  | GitHub OAuth                 |
+
+## 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
+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 (`provision-config` (#367) or future deploy skill).
+
+## Env-var formats — what valid values look like
+
+### `AUTH_EMAIL_SERVER` (magic-link via Resend)
+
+```
+smtp://resend:<RESEND_API_KEY>@smtp.resend.com:465
+```
+
+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)
+
+A verified sender address on the consumer's Resend account. For
+development, `onboarding@resend.dev` works without verification.
+
+### `GOOGLE_CLIENT_ID` / `GITHUB_CLIENT_ID`
+
+Public identifiers issued by Google / GitHub. Typically:
+
+- Google: ends in `.apps.googleusercontent.com`
+- GitHub: 20-character hex string
+
+Either can be safely committed to a public template; production
+secrets stay in `.env.local`.
+
+### `GOOGLE_CLIENT_SECRET` / `GITHUB_CLIENT_SECRET`
+
+Sensitive values. Treat as passwords. Never commit. The skill writes
+these only to `.env.local` (which is in the consumer scaffold's
+`.gitignore` by default).
+
+## Detection of "already activated"
+
+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
+their first sign-in attempt; the fix is to re-run the skill and
+overwrite.
+
+## Where these vars are read
+
+- `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.
+
+The skill never modifies any of those files. All activation is
+env-var-driven.