create-ailk 0.1.0

package/templates/.claude/skills/audit-site/references/severity-levels.md

@@ -0,0 +1,114 @@
+# Severity Levels — Score Banding + Severity Mapping
+
+The AEO audit JSON does **not** include explicit severity fields.
+Severity is **derived** by the `audit-site` skill from each rule's
+`weight` and `pass`. This file is the source of truth for that
+mapping.
+
+The skill applies these rules in `SKILL.md` Step 5.
+
+---
+
+## Severity tiers
+
+| Tier     | Source signal                                   | Meaning                                                                 |
+| -------- | ----------------------------------------------- | ----------------------------------------------------------------------- |
+| Critical | `pass: false` AND `weight >= 10`                | Rule that materially affects citation readiness; failure is blocking.   |
+| Warning  | `pass: false` AND `weight` in `[1, 9]`          | Rule that nudges citation quality; failure is fixable, not blocking.    |
+| Info     | `pass: true` AND `weight: 0` (incentive rules)  | Positive signal earned. Bonus, not a finding.                           |
+| Neutral  | `pass: true` AND `weight: 0` AND `bonus: false` | Page is fine but didn't earn the incentive. Don't surface unless asked. |
+
+A rule with `pass: false` AND `weight: 0` is **not possible** today
+(incentive rules are designed to never fail — see
+`faq-howto-incentive` in `packages/aeo`). If one ever appears,
+treat it as Info (the rule's own design says failures are neutral).
+
+---
+
+## Why weight thresholds, not explicit severity
+
+The AEO type system intentionally keeps rules weight-based, not
+severity-based. Reasons:
+
+- **Score arithmetic stays simple.** `passing-weight / total-weight`
+  is the score; introducing severity as a separate axis would force
+  every rule to choose two attributes (weight AND severity) when
+  one is enough.
+- **The skill is the right place for the translation.** Consumers
+  don't care about weights — they care about "should I fix this?".
+  The skill turns "weight 10 fail" into "Critical" because that's
+  the language consumers can act on.
+- **Rule authors don't have to think about severity.** A new rule
+  added to `packages/aeo` gets a weight (its impact on the score)
+  and the skill maps that to a severity tier automatically. No
+  coupling between rule authoring and consumer-facing UX.
+
+---
+
+## Score banding (optional)
+
+When the consumer asks "is this a good score?", you can map the
+numeric score to a band. This is optional — Step 4 always emits
+the raw score first.
+
+| Score  | Band              | Hint                                                             |
+| ------ | ----------------- | ---------------------------------------------------------------- |
+| 90–100 | Excellent         | All critical rules pass; site is well-instrumented for citation. |
+| 75–89  | Good              | Probably a critical or warning fixable on a couple of pages.     |
+| 50–74  | Needs work        | Multiple critical rules failing; address those first.            |
+| 0–49   | Foundational gaps | Site likely has no schema or invalid schema across most pages.   |
+
+Hint sentences are suggestions; adapt phrasing to the consumer's
+context. Don't quote the band tag verbatim if a more natural
+phrasing fits the conversation ("you're at 87 — couple of fixes
+away from clean").
+
+---
+
+## Severity counting for the summary line
+
+Step 5 of SKILL.md asks for a summary like:
+
+```
+2 critical · 1 warning · 0 info
+```
+
+Counts are computed as:
+
+- **Critical count** = count of `perRule[]` entries where
+  `pass === false && weight >= 10`.
+- **Warning count** = count of `perRule[]` entries where
+  `pass === false && weight >= 1 && weight < 10`.
+- **Info count** = count of `perRule[]` entries where
+  `pass === true && weight === 0` (i.e., earned incentives).
+
+Some rules surface per-page failures (`perRule[].perPage[]`).
+Those are deeper-level findings the skill can drill into in Step 6;
+they don't change the rule-level severity counts. A `schema-coverage`
+rule with `pass: false` and 5 failing pages is **one** critical
+finding (the rule failed), with 5 page-specific evidence entries
+for drill-down.
+
+---
+
+## What this skill does NOT classify as severity
+
+- **`bonus: true` per page** is not a finding; it's a positive
+  signal. Surface it on drill-down ("These pages earned the FAQ
+  bonus: …") but don't include it in the severity summary.
+- **Schema-version mismatch** (a `meta.schemaVersion` from the
+  audit that doesn't match the consumer's `@working-theory/schema`) is not a
+  rule failure — it's a setup-drift signal. Surface only if the
+  consumer asks why the score might be inconsistent across runs.
+
+---
+
+## Future rules
+
+When `packages/aeo` adds a new rule, this glossary may not name
+it. The severity mapping still works because it keys off `weight`
+and `pass` only — both fields are guaranteed by the
+`PerRuleResult` type. New critical-tier rules will surface as
+`Critical` automatically; new warnings as `Warning`. The findings
+glossary may lag in offering plain-language explanations until
+this template is updated.

package/templates/.claude/skills/provision-config/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: provision-config
+description: Emit deploy configuration for an AILK consumer site — `vercel.json`, `.env.example`, and `RUNBOOK.md`. Vercel-only at v1; other platforms reject with a clear "not yet supported" message. Use when the user asks "set up Vercel", "provision deploy config", "what env vars do I need for production?", "I'm ready to ship to Vercel", or otherwise asks about pre-deploy file setup. The RUNBOOK includes the three named persistence-upgrade paths for leads.jsonl (Vercel KV / Supabase / Postgres-via-`@working-theory/database`).
+---
+
+# provision-config
+
+Emit `vercel.json`, `.env.example`, and `RUNBOOK.md` at the consumer's
+project root, ready for a Vercel deploy. Vercel is the only valid
+`platform` value at v1. Other platforms (Netlify, Cloudflare, Render,
+Fly, self-host) reject with an explicit "not yet supported" message
+and emit nothing.
+
+## When to use
+
+The consumer is preparing to deploy their AILK site for the first
+time, or wants to verify their deploy config is complete. Triggers:
+
+- "provision Vercel config" / "set up Vercel"
+- "what env vars do I need to deploy?"
+- "I'm ready to ship — what files do I need?"
+- "regenerate `vercel.json`" / "refresh `.env.example`"
+
+Skip this skill when:
+
+- The consumer is on a non-Vercel platform — emit the rejection
+  message (see Step 1) and stop.
+- The consumer asks about runtime environment values
+  (`process.env.X` debugging) — that's an app-level concern, not a
+  config-emission concern.
+- The consumer is asking about Stripe live-mode setup — that's
+  hard-floor blocked across AILK; sandbox-only at v1. Mention and stop.
+
+## What this skill does (and does not do)
+
+**Does:**
+
+- Validate the `platform` parameter — only `vercel` is accepted at v1.
+- Detect existing `vercel.json`, `.env.example`, and `RUNBOOK.md` at
+  the consumer's project root.
+- For each artifact, ask the consumer how to handle conflicts
+  (merge / overwrite / skip) before writing.
+- Emit the three artifacts at the consumer's project root, derived
+  from templates in `references/`.
+- Validate the emitted output (parse `vercel.json` as JSON, check
+  `.env.example` covers required vars, confirm `RUNBOOK.md` has the
+  three named persistence-upgrade headings).
+
+**Does not:**
+
+- Call any Vercel API. The consumer runs `vercel deploy` themselves.
+- Read or write live secrets. `.env.example` uses placeholder values
+  only.
+- Configure Cloudflare anything (deploy target, KV, D1, R2). CF is
+  deferred entirely as a coherent follow-up unit.
+- Emit Netlify / Render / Fly / self-host config. v1 is Vercel only.
+- Modify the consumer's actual `.env.local` or any other file
+  containing real secrets.
+
+## The mechanic
+
+### Step 1 — Validate the platform parameter
+
+Default platform is `vercel`. If the consumer asks for any other
+platform, respond:
+
+> "`provision-config` is Vercel-only at v1. Netlify / Cloudflare /
+> Render / Fly / self-host support are tracked at the upstream repo —
+> file an issue at <https://github.com/tailwind-ai/ai-launch-kit/issues>
+> if your platform is missing.
+>
+> Cloudflare is deferred entirely (deploy target + KV/D1/R2 data
+> layer) as a coherent follow-up. CF requires different default
+> persistence per platform because Workers lack the Node `fs` API
+> the JSONL fallback depends on."
+
+Then stop. Do not emit any files.
+
+### Step 2 — Detect existing artifacts
+
+Look for `vercel.json`, `.env.example`, and `RUNBOOK.md` at the
+consumer's project root. For each one, note:
+
+- **Missing** — will emit fresh.
+- **Present** — ask how to handle (Step 3).
+
+### Step 3 — Conflict handling per file
+
+For each existing artifact, show the consumer:
+
+1. The first ~10 lines of the existing file (preview).
+2. A summary of what the skill would emit (template name + key
+   fields).
+3. Three options: **merge** (only for `RUNBOOK.md` and
+   `.env.example` — see merge logic below), **overwrite**
+   (replace contents), **skip** (leave existing file untouched).
+
+Wait for the consumer's choice per file. Do not blindly overwrite.
+
+**Merge logic — `.env.example`:** if a var listed in
+`references/env-vars-template.md` is **missing** from the existing
+file, append it (with comment) at the bottom under a "## Added by
+provision-config" section. Vars already present are not modified.
+
+**Merge logic — `RUNBOOK.md`:** if any of the three named
+persistence sections (Vercel KV, Supabase,
+Postgres-via-`@working-theory/database`) is missing from the existing file,
+append it at the end. Existing sections are not modified.
+
+**Merge logic — `vercel.json`:** **not supported.** `vercel.json` is
+either overwritten or skipped — no field-level merge. Reason: the
+file is small and consumers are likely to have customized it
+intentionally; merging risks subtle config drift.
+
+### Step 4 — Emit `vercel.json`
+
+Use the template at `references/vercel-json-template.md`. The
+emitted file has these fields:
+
+- `version: 2` — Vercel config schema version.
+- `framework: "nextjs"` — Vercel auto-detects `apps/web` as Next.js.
+- `buildCommand` — pnpm-aware build (typically
+  `cd ../.. && pnpm install --frozen-lockfile && pnpm --filter ./apps/web build`
+  for monorepo deploys, or `pnpm build` for single-app deploys).
+- `installCommand` — match the consumer's package manager.
+- `env` — env-var passthrough; AILK ships an empty `env: {}` and
+  expects Vercel's project-level env-var dashboard to handle real
+  values.
+
+After write, parse the JSON. If parse fails, the skill has a bug —
+report it to the consumer with the literal error.
+
+### Step 5 — Emit `.env.example`
+
+Use the template at `references/env-vars-template.md`. The emitted
+file lists every env var the consumer's site reads, grouped by
+concern (auth, content, payments, analytics, etc.) with placeholder
+values and inline comments.
+
+The skill **does not** read live `.env` files. Placeholder values
+only. No `sk_live_*`, no `pk_live_*`, no real Resend keys, no real
+NextAuth secrets.
+
+After write, count the declared vars and confirm the count matches
+the template's expected count. If a var the consumer's site uses
+(grep `process.env.X` from a quick scan) is missing from the
+template, add it under "## Added by provision-config" — never silently
+omit a var the consumer needs.
+
+### Step 6 — Emit `RUNBOOK.md`
+
+Use the template at `references/runbook-template.md`. The emitted
+runbook has these sections:
+
+1. **Pre-deploy checklist** — what to set in Vercel's project
+   dashboard before clicking Deploy.
+2. **Operations — leads.jsonl persistence** — the **critical**
+   section. AILK's lead-capture writes JSONL to
+   `apps/api/leads.jsonl`, which **does not persist** on Vercel's
+   ephemeral filesystem. Consumer must pick a persistence backend
+   before going live or leads disappear on cold-start.
+3. **Persistence upgrade — Vercel KV** — drop-in, no new infra,
+   cheapest fix. When to pick.
+4. **Persistence upgrade — Supabase** — Postgres + auth + storage
+   in one provider. When to pick.
+5. **Persistence upgrade — Postgres via `@working-theory/database`** — for
+   consumers who already have Postgres elsewhere (Neon, Railway,
+   RDS). When to pick.
+6. **Custom domain + DNS** — pointer at Vercel's domain docs.
+7. **Production callbacks for OAuth** — for consumers who used
+   `scaffold-auth` (#364) and need to register prod redirect URIs.
+
+After write, grep the RUNBOOK for the three named persistence
+section headings (Vercel KV, Supabase,
+Postgres-via-`@working-theory/database`). All three must be present. If any
+is missing, the skill has a bug — flag with the literal error.
+
+### Step 7 — Closing summary
+
+Print:
+
+- Which artifacts were emitted vs skipped (per consumer's Step 3
+  choices).
+- A pointer to `RUNBOOK.md`'s leads-persistence section (the
+  highest-stakes operational caveat).
+- A reminder that Vercel project-level env-vars need to be set in
+  the Vercel dashboard before deploy — `.env.example` is the
+  contract, not the values.
+- The next step: `vercel deploy` (or `git push` if the consumer is
+  using Vercel's GitHub integration).
+
+## Re-invocation
+
+The skill is idempotent. Re-running on a project with all three
+artifacts present asks the consumer how to handle each conflict
+(per Step 3). A consumer who picks **skip** for all three gets a
+no-op run with a "all artifacts already present, nothing to do"
+message.
+
+## Validation
+
+Before reporting "done":
+
+- `vercel.json` parses as JSON ✓
+- `.env.example` declares >= the count of vars in the template ✓
+- `RUNBOOK.md` contains all three named persistence section
+  headings ✓
+
+If any check fails, surface the failure to the consumer (not silent).
+
+## What this skill does NOT validate
+
+- That the consumer's Vercel project actually deploys. That's
+  `vercel deploy`'s job.
+- That env-var values in the consumer's Vercel dashboard are
+  correct or live. The skill never reads dashboard state.
+- That OAuth callback URLs in `scaffold-auth`'s RUNBOOK are
+  registered in production OAuth apps. That's the consumer's job
+  pre-launch.
+
+## References
+
+- `references/vercel-json-template.md` — minimal viable `vercel.json`.
+- `references/env-vars-template.md` — `.env.example` structure with
+  placeholder values per category.
+- `references/runbook-template.md` — `RUNBOOK.md` with the three
+  named persistence-upgrade sections.
+
+## Coordination
+
+- **`scaffold-auth` (#364)** — produces its own `RUNBOOK.md`
+  sections for OAuth setup (dev callback URLs). This skill's
+  RUNBOOK adds production callback URLs and merges with any
+  existing runbook content (not blindly overwrites).
+- **`@working-theory/env`** — at v1 a placeholder package, not yet a Zod
+  schema. This skill derives `.env.example` from the template, not
+  from a runtime schema. When `@working-theory/env` ships its schema, this
+  skill should be revised to read from it.
+- **Stripe sandbox-only** — hard-floor enforced globally. Emitted
+  `.env.example` uses `sk_test_*` placeholders, never `sk_live_*`.
+- **Cloudflare deferred** — neither CF Pages (deploy target) nor
+  CF KV / D1 / R2 (data layer) is in v1. Will ship as a coherent
+  follow-up PR.

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

@@ -0,0 +1,184 @@
+# `.env.example` Template
+
+The structure the `provision-config` skill emits at the consumer's
+project root. Placeholder values only — the skill never echoes a
+real secret.
+
+When `@working-theory/env` ships a Zod schema (currently a placeholder
+package), this template should be revised to derive from that
+schema instead. Until then, this file is the source of truth for
+what env vars an AILK consumer site reads.
+
+## Template
+
+```bash
+# AI Launch Kit — environment template
+# Copy this file to `.env.local` (gitignored) and fill in values.
+# Production values live in your deploy platform's dashboard
+# (Vercel project settings → Environment Variables).
+
+# ── Marketing / canonical domain ─────────────────────────────────
+# Your site's canonical public domain (no protocol).
+AILK_PUBLIC_DOMAIN=your-domain.com
+
+# ── Content backend ──────────────────────────────────────────────
+# AILK's MDX adapter is the default. Other adapters ship as
+# additive PRs later.
+CONTENT_BACKEND=mdx
+# Override the content directory. Default is <repo-root>/content.
+# AILK_CONTENT_ROOT=
+
+# ── Database (optional in standalone mode) ───────────────────────
+# Required only if you've installed @working-theory/database for persistent
+# leads, sessions, or other data. See RUNBOOK.md § "Persistence
+# upgrade — Postgres via @working-theory/database" for setup.
+# DATABASE_URL=postgres://user:pass@host:5432/db
+
+# ── Auth — required env vars ─────────────────────────────────────
+# Set to "1" to require sign-in for protected routes; default is
+# auth-disabled / public.
+# AILK_AUTH_REQUIRED=1
+#
+# NextAuth secret — production must be set; generate with:
+#   openssl rand -base64 32
+# Local dev (next dev) auto-generates a session-only secret.
+# NEXTAUTH_SECRET=
+#
+# Production base URL for callback construction. Local dev defaults
+# to http://localhost:3000 if unset.
+# NEXTAUTH_URL=https://your-domain.com
+
+# ── Auth — magic-link (Resend) ───────────────────────────────────
+# Activated when both AUTH_EMAIL_SERVER and AUTH_EMAIL_FROM are set.
+# Get a Resend API key at https://resend.com/api-keys.
+# AUTH_EMAIL_SERVER=smtp://resend:re_yourkeyhere@smtp.resend.com:465
+# AUTH_EMAIL_FROM=onboarding@resend.dev
+
+# ── Auth — Google OAuth ──────────────────────────────────────────
+# Activated when both GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET set.
+# Set up at https://console.cloud.google.com/apis/credentials.
+# Production callback: https://your-domain.com/api/auth/callback/google
+# GOOGLE_CLIENT_ID=
+# GOOGLE_CLIENT_SECRET=
+
+# ── Auth — GitHub OAuth ──────────────────────────────────────────
+# Activated when both GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET set.
+# Set up at https://github.com/settings/developers.
+# Production callback: https://your-domain.com/api/auth/callback/github
+# GITHUB_CLIENT_ID=
+# GITHUB_CLIENT_SECRET=
+
+# ── Stripe (sandbox keys only — sk_test_* / pk_test_*) ───────────
+# AILK is sandbox-only at v1. Live keys (sk_live_*, pk_live_*) are
+# hook-blocked from appearing in source.
+# Get test keys at https://dashboard.stripe.com/test/apikeys.
+# STRIPE_SECRET_KEY=sk_test_...
+# NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
+# Webhook signing secret — see Stripe Dashboard → Developers →
+# Webhooks → <endpoint> → Signing secret. Format: whsec_*.
+# STRIPE_WEBHOOK_SECRET=
+
+# ── Email provider (Resend) ──────────────────────────────────────
+# Used by transactional senders outside auth (e.g., contact form).
+# Same Resend account as magic-link if both are configured.
+# RESEND_API_KEY=
+
+# ── Analytics — all off by default ───────────────────────────────
+# Each provider is independent. Set the env var(s) to enable.
+#
+# Vercel Analytics — built-in dashboard for Vercel deploys.
+# Requires Vercel hosting. Set to "true" to enable. Requires redeploy
+# after change (NEXT_PUBLIC_* values bake at build time).
+# NEXT_PUBLIC_VERCEL_ANALYTICS_ENABLED=
+#
+# Google Analytics 4 — gtag.js measurement. Requires consent in EU/UK/CA.
+# Get the measurement ID from analytics.google.com → Admin → Data Streams.
+# Format: G-XXXXXXXXXX. Requires redeploy after change.
+# NEXT_PUBLIC_GA_MEASUREMENT_ID=
+#
+# GA4 Measurement Protocol — server-side analytics secret.
+# Required alongside NEXT_PUBLIC_GA_MEASUREMENT_ID for server-side
+# lead/purchase events.
+# GA_API_SECRET=
+#
+# Google Search Console — verification meta tag. No script, no consent.
+# Get the token from search.google.com/search-console → Settings →
+# Ownership verification → HTML tag. Paste only the content="..." value.
+# GOOGLE_SITE_VERIFICATION=
+
+# ── Persistent leads (optional) ──────────────────────────────────
+# By default, leads.jsonl is written to apps/api/leads.jsonl. On
+# Vercel's ephemeral filesystem this does NOT persist across cold
+# starts. See RUNBOOK.md § "Persistence upgrade" for the three
+# named upgrade paths.
+#
+# Vercel KV (drop-in):
+# KV_REST_API_URL=
+# KV_REST_API_TOKEN=
+#
+# Supabase (Postgres + auth + storage):
+# NEXT_PUBLIC_SUPABASE_URL=
+# NEXT_PUBLIC_SUPABASE_ANON_KEY=
+# SUPABASE_SERVICE_ROLE_KEY=
+```
+
+## Categories the skill emits
+
+The template above groups vars into seven categories. Every emitted
+`.env.example` should hit each category at least with its header
+comment, even if the consumer hasn't activated any vars in that
+category — the comment block tells future-them what's available.
+
+Categories:
+
+1. Marketing / canonical domain
+2. Content backend
+3. Database (optional)
+4. Auth — required + per-provider
+5. Stripe (sandbox-only)
+6. Email + Analytics
+7. Persistent leads (optional)
+
+## What the skill never includes
+
+- Real secret values. All values are placeholders or commented
+  examples.
+- Live Stripe keys. Sandbox-only at AILK v1.
+- Live Vercel deploy tokens. The Vercel CLI handles deploy auth via
+  `vercel login`.
+- Database connection strings with embedded passwords. Comments
+  show shape only.
+
+## Counting vars for validation
+
+The skill's Step 5 validation counts the declared (uncommented) vars
+the template emits and confirms the count is non-zero. Empty
+`.env.example` is a bug. Currently declared vars in the template:
+
+- `AILK_PUBLIC_DOMAIN`
+- `CONTENT_BACKEND`
+
+(All other entries are commented optional vars.) The skill should
+not require the consumer to set every commented var — they're
+opt-in. The two declared entries are the minimum the AILK scaffold
+needs to boot, even on a static-content-only site.
+
+## Merge logic
+
+If the consumer already has `.env.example`, the skill (per SKILL.md
+Step 3) offers merge / overwrite / skip. Merge logic:
+
+1. Read the existing file.
+2. For each line in this template that's not a comment-only line,
+   check whether the var name already appears anywhere in the
+   existing file (commented or uncommented).
+3. Vars **already present** are not modified — the consumer's
+   existing comments and value choices win.
+4. Vars **missing** are appended at the end of the existing file
+   under a new section:
+   ```
+   # ── Added by provision-config ────────────────────────────────
+   ```
+
+This avoids duplicating vars while still surfacing additions the
+template gained since the consumer's last run.