create-ailk 0.6.1 → 0.8.0

package/templates/.claude/skills/{provision-config → setup-deploy}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-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`).
+name: setup-deploy
+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. Asks where leads should go — the email key (`RESEND_API_KEY` + the two notification addresses) or a database (`setup-database`) — and warns when neither is set. The RUNBOOK documents the two lead destinations: Email (default) and Lead inbox (setup-database).
 ---
 
-# provision-config
+# setup-deploy
 
 Emit `vercel.json`, `.env.example`, and `RUNBOOK.md` at the consumer's
 project root, ready for a Vercel deploy. Vercel is the only valid
@@ -42,9 +42,11 @@ Skip this skill when:
   (merge / overwrite / skip) before writing.
 - Emit the three artifacts at the consumer's project root, derived
   from templates in `references/`.
+- Ask where leads go (Step 5a) — the email key, or a database via
+  `setup-database` — and warn, verbatim, when neither is set.
 - 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).
+  two lead-destination headings).
 
 **Does not:**
 
@@ -64,15 +66,13 @@ Skip this skill when:
 Default platform is `vercel`. If the consumer asks for any other
 platform, respond:
 
-> "`provision-config` is Vercel-only at v1. Netlify / Cloudflare /
+> "`setup-deploy` 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/working-theory-labs/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."
+> layer) as a coherent follow-up."
 
 Then stop. Do not emit any files.
 
@@ -100,11 +100,11 @@ 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.
+setup-deploy" 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,
+**Merge logic — `RUNBOOK.md`:** if the "Leads — where messages go"
+section (with its two headings, `Email (default)` and
+`Lead inbox (setup-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
@@ -144,9 +144,37 @@ 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
+template, add it under "## Added by setup-deploy" — never silently
 omit a var the consumer needs.
 
+### Step 5a — Lead delivery
+
+Where a contact-form message goes is decided by the API project's
+environment (RUNBOOK § "Leads — where messages go"). Ask the consumer
+two questions:
+
+1. **Will this site use a database?** If yes, point them to the
+   `setup-database` skill — it provisions Postgres, sets
+   `DATABASE_URL`, runs migrations and verifies a test lead reaches
+   the inbox. Do not collect a connection string here.
+2. **What email should messages go to?** Ask for
+   `RESEND_API_KEY`, `AILK_LEAD_NOTIFICATION_TO` (their address) and
+   `AILK_LEAD_NOTIFICATION_FROM` (a sender on their Resend-verified
+   domain). All three are needed — a key alone sends nothing. Write
+   **placeholders only** into `.env.example`; tell the consumer to set
+   the real values in the **API** project's dashboard. Never write a
+   key into a file.
+
+If the consumer provides neither a database nor all three email
+values, print this, verbatim:
+
+> ⚠ No lead destination is set. In production your contact page will show
+> your contact email instead of the form, and no messages will be collected.
+> Run setup-database, or set RESEND_API_KEY, AILK_LEAD_NOTIFICATION_TO and
+> AILK_LEAD_NOTIFICATION_FROM on the API project.
+
+Then continue — the warning does not stop the deploy config.
+
 ### Step 6 — Emit `RUNBOOK.md`
 
 Use the template at `references/runbook-template.md`. The emitted
@@ -154,26 +182,24 @@ 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.
+2. **Leads — where messages go** — the two lead destinations, in
+   plain words:
+   - **Email (default)** — no database; each message is emailed to
+     the owner (`RESEND_API_KEY`, `AILK_LEAD_NOTIFICATION_TO`,
+     `AILK_LEAD_NOTIFICATION_FROM` on the API project).
+   - **Lead inbox (setup-database)** — `DATABASE_URL` set; messages
+     land in `/leads` and newsletter signups are collected.
+   With neither, production `/contact` shows the site's contact email
+   instead of the form. On a non-Vercel host, the API process needs
+   `NODE_ENV=production`.
+3. **Custom domain + DNS** — pointer at Vercel's domain docs.
+4. **Production callbacks for OAuth** — for consumers who used
+   `add-auth` and need to register prod redirect URIs.
+
+After write, grep the RUNBOOK for the two lead-destination headings
+(`Email (default)`, `Lead inbox (setup-database)`). Both must be
+present. If either is missing, the skill has a bug — flag with the
+literal error.
 
 ### Step 7 — Closing summary
 
@@ -181,8 +207,9 @@ 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).
+- Where leads will go (email, the lead inbox, or — with the Step 5a
+  warning repeated — nowhere), with a pointer to `RUNBOOK.md`'s
+  "Leads — where messages go" section.
 - 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.
@@ -203,8 +230,10 @@ 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 ✓
+- `RUNBOOK.md` contains both lead-destination headings
+  (`Email (default)`, `Lead inbox (setup-database)`) ✓
+- Step 5a ran: the consumer chose a lead destination, or saw the
+  no-destination warning ✓
 
 If any check fails, surface the failure to the consumer (not silent).
 
@@ -214,7 +243,7 @@ If any check fails, surface the failure to the consumer (not silent).
   `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
+- That OAuth callback URLs in `add-auth`'s RUNBOOK are
   registered in production OAuth apps. That's the consumer's job
   pre-launch.
 
@@ -223,12 +252,15 @@ If any check fails, surface the failure to the consumer (not silent).
 - `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.
+- `references/runbook-template.md` — `RUNBOOK.md` with the two lead
+  destinations (Email (default), Lead inbox (setup-database)).
 
 ## Coordination
 
-- **`scaffold-auth` (#364)** — produces its own `RUNBOOK.md`
+- **`setup-database`** — takes a site from no database to a working
+  lead inbox. Step 5a hands off to it; this skill never collects a
+  connection string.
+- **`add-auth`** — 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).

package/templates/.claude/skills/{provision-config → setup-deploy}/references/env-vars-template.md

@@ -1,6 +1,6 @@
 # `.env.example` Template
 
-The structure the `provision-config` skill emits at the consumer's
+The structure the `setup-deploy` skill emits at the consumer's
 project root. Placeholder values only — the skill never echoes a
 real secret.
 
@@ -28,11 +28,23 @@ 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.
+# ── Lead delivery ────────────────────────────────────────────────
+# Where contact-form messages go (RUNBOOK.md § "Leads — where
+# messages go"). Set these on the API project.
+#
+# Lead inbox — set by the `setup-database` skill. With it, messages
+# land in /leads and newsletter signups are collected.
 # DATABASE_URL=postgres://user:pass@host:5432/db
+# DATABASE_URL_NON_POOLED=postgres://user:pass@host:5432/db
+#
+# Email (default) — with no database, each message is emailed to you.
+# All three are required; a key alone sends nothing.
+# RESEND_API_KEY=
+# AILK_LEAD_NOTIFICATION_TO=you@your-domain.com
+# AILK_LEAD_NOTIFICATION_FROM=leads@your-domain.com
+#
+# With neither, /contact shows your contact email (content/_site.mdx
+# `contactEmail`) instead of the form in production.
 
 # ── Auth — required env vars ─────────────────────────────────────
 # Set to "1" to require sign-in for protected routes; default is
@@ -78,11 +90,6 @@ CONTENT_BACKEND=mdx
 # 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.
 #
@@ -105,26 +112,11 @@ CONTENT_BACKEND=mdx
 # 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
+The template above groups vars into six 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.
@@ -133,11 +125,10 @@ Categories:
 
 1. Marketing / canonical domain
 2. Content backend
-3. Database (optional)
+3. Lead delivery (database or email)
 4. Auth — required + per-provider
 5. Stripe (sandbox-only)
-6. Email + Analytics
-7. Persistent leads (optional)
+6. Analytics
 
 ## What the skill never includes
 
@@ -177,7 +168,7 @@ Step 3) offers merge / overwrite / skip. Merge logic:
 4. Vars **missing** are appended at the end of the existing file
    under a new section:
    ```
-   # ── Added by provision-config ────────────────────────────────
+   # ── Added by setup-deploy ────────────────────────────────
    ```
 
 This avoids duplicating vars while still surfacing additions the

package/templates/.claude/skills/setup-deploy/references/runbook-template.md

@@ -0,0 +1,204 @@
+# `RUNBOOK.md` Template
+
+The `setup-deploy` skill emits this runbook at the consumer's
+project root. It documents pre-deploy steps and where the site's
+leads go — the two lead destinations, **Email (default)** and
+**Lead inbox (setup-database)**.
+
+The skill must verify both lead-destination headings are present
+after emit (per SKILL.md Step 6 validation). If either is missing,
+the skill has a bug.
+
+## Template
+
+```markdown
+# RUNBOOK — Production Operations
+
+This runbook is generated by the `setup-deploy` skill. It covers
+what to do before and after deploying to Vercel, plus the
+operational caveats AILK ships with.
+
+If you re-run `setup-deploy`, new sections may be appended at
+the end under "## Added by setup-deploy." 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 where leads go** — see "Leads — where messages go"
+      below. With neither an email key nor a database, your contact
+      page shows your contact email instead of the form in
+      production, and no messages are collected.
+- [ ] **On a host other than Vercel**, set `NODE_ENV=production` on
+      the API process — that is how it knows it is in production.
+- [ ] **Register production OAuth callbacks** if you used
+      `add-auth` and activated Google or GitHub. Each provider
+      needs the prod callback URL added to its OAuth app settings.
+
+---
+
+## Leads — where messages go
+
+Where a contact-form message goes depends only on what you set on
+the **API** project:
+
+| You set                                   | A message…                                   |
+| ----------------------------------------- | -------------------------------------------- |
+| `DATABASE_URL`                            | lands in your lead inbox at `/leads`         |
+| the three email variables, no database    | is emailed to you                            |
+| neither (production)                      | is not collected — `/contact` shows your contact email instead of the form |
+| neither (`pnpm dev`)                      | is written to a local file, for testing      |
+
+A newsletter signup needs the database: without one, `/newsletter`
+offers no signup form. A visitor is never told a message was sent
+when it reached nobody.
+
+### Email (default)
+
+**When to pick:** you want messages in your inbox with no database
+to run. This is the default for a new site.
+
+**Setup:**
+
+1. Create an API key at <https://resend.com/api-keys> and verify the
+   domain you will send from (Resend Dashboard → Domains).
+2. On the **API** project in Vercel (Settings → Environment
+   Variables), set:
+   - `RESEND_API_KEY` — the key.
+   - `AILK_LEAD_NOTIFICATION_TO` — the address messages go to (yours).
+   - `AILK_LEAD_NOTIFICATION_FROM` — a sender on your verified domain.
+3. Redeploy the API.
+
+All three are required: a key without both addresses sends nothing.
+If Resend refuses a message, the visitor is told it could not be
+sent, so they can try again or email you directly.
+
+### Lead inbox (setup-database)
+
+**When to pick:** you want every message kept, searchable, in a
+lead inbox you review signed in — and newsletter signups collected.
+
+**Setup:** run the `setup-database` skill ("set up the database"). It
+walks you through provisioning Postgres, setting `DATABASE_URL`,
+running migrations, pinning you as the owner
+(`AILK_OPERATOR_EMAIL`), and sending one test message that must
+appear in `/leads` before it reports done. If the email variables
+are also set, you still get an email for each new lead.
+
+---
+
+## 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 `add-auth`)
+
+If you activated Google or GitHub OAuth via `add-auth`,
+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 contact page shows an email address instead of the form"**
+  → the API has no lead destination. Set the three email variables,
+  or run `setup-database` (see "Leads — where messages go").
+- **"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 two headings (verbatim
+match). Both must be present:
+
+- `### Email (default)`
+- `### Lead inbox (setup-database)`
+
+If either 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 the "Leads — where messages go" section and its two
+   lead-destination headings are already present.
+3. Headings already present → not modified.
+4. Headings missing → append at the end of the existing file under:
+   ```
+   ## Added by setup-deploy
+   ```
+
+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 → setup-deploy}/references/vercel-json-template.md

@@ -1,6 +1,6 @@
 # `vercel.json` Template
 
-The minimal viable Vercel config the `provision-config` skill emits.
+The minimal viable Vercel config the `setup-deploy` skill emits.
 Customization beyond this template is the consumer's responsibility —
 the skill's job is to ship the consumer with a working baseline.
 

package/templates/.claude/skills/upgrade-plan/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: upgrade-plan
+description: Explain the AI Launch Kit options — Free, Pro, Pro Plus, Agency and the commerce add-on's three rungs (Commerce, SaaS, SaaS with Usage) — side by side, with the prices the public pricing page publishes right now, read this site's own modules and shape, and recommend exactly one option with a reason. Use when the user asks "what does Pro get me?", "should I upgrade?", "compare plans", "which plan do I need?", "how much is commerce?", or types /upgrade-plan. The skill reads and explains only — it never buys, never installs, and never states a price from memory.
+---
+
+# upgrade-plan
+
+Answer "what does a paid level get me, and which one should I buy?" from two
+live sources: the public pricing page (for prices) and this repository (for
+what the site actually uses). A bundled helper does the reading and the
+choosing; this skill runs it and explains the result in plain words.
+
+## When to use
+
+- "what does Pro get me?" / "what's in Pro Plus?"
+- "should I upgrade?" / "which plan do I need?"
+- "compare the plans" / "how does Agency work?"
+- "can I sell things on my site?" / "how much is the commerce add-on?"
+- `/upgrade-plan`
+
+Skip this skill when the user wants to actually buy or install something —
+this skill explains and recommends; the purchase happens on the pricing
+page, and installing a module is a separate step (see "What happens next").
+
+## The mechanic
+
+### Step 1 — Map the user's stated need (optional)
+
+If the user said what they want to do, map it to one `--need` value:
+
+| The user says…                                    | `--need`       |
+| ------------------------------------------------- | -------------- |
+| "I build sites for clients"                        | `agency`       |
+| "I want to sell / take payments"                   | `sell`         |
+| "my product bills its own customers on plans"      | `saas`         |
+| "I bill my customers by usage / credits"           | `usage`        |
+| "I need docs or a blog"                            | `docs`         |
+| "I need booking / scheduling"                      | `scheduling`   |
+| "I need organizations / teams / many workspaces"   | `multi-tenant` |
+
+If the need maps to none of these, omit `--need`, and tell the user which
+need you could not map — the recommendation then comes from the site alone.
+
+### Step 2 — Run the helper
+
+From the project root:
+
+```bash
+pnpm exec tsx .claude/skills/upgrade-plan/scripts/upgrade-plan.ts [--need <value>]
+```
+
+It prints one JSON object:
+
+- `pricing.status` — `ok` (the page published prices), `unpublished` (the
+  page loaded but carries no machine-readable offers) or `unreachable`
+  (network error, timeout or error status). `pricing.url` is the link to give
+  the user.
+- `options[]` — the seven options, always all seven, each with `adds`,
+  `requires`, and `prices[]` (empty, with `status: "not published on the
+  pricing page"`, when the page does not price it).
+- `alsoPublished[]` — other offers on the pricing page that are none of the
+  seven (for example a one-off service), with their published price.
+- `site` — this site's `modules`, `template`, `shape`, `design`, whether it
+  already prices something (`sellsSomething`), whether commerce is installed,
+  and whether `AILK_LICENSE_KEY` is set in this shell (`licenseKeySet` —
+  presence only, never the value).
+- `recommendation` — one `option`, its `reason`, and its `link`.
+
+Exit status 0 in all three pricing states. Exit 2 is a usage error — re-run
+without the argument it names.
+
+### Step 3 — Explain it
+
+Answer in this order, in plain words:
+
+1. **Your site.** State the shape and the modules from `site`, the template
+   and design when recorded, whether it already prices anything, and whether
+   a licence key is set in this shell. A `null` field is "not recorded —
+   scaffolded without `--template`"; never guess a shape. If the key is not
+   set, say "not set in this shell" (a key kept only in `.env` reads that way).
+2. **The options, side by side.** A table of all seven options: name, what it
+   adds, what it requires, and its price exactly as `prices[]` gives it
+   (figure, currency and unit text). An option with no price reads
+   "not published on the pricing page — see https://ailaunchkit.ai/pricing".
+   Then list `alsoPublished` under "Also on the pricing page".
+3. **The recommendation.** Exactly one option — `recommendation.option` —
+   with its reason, naming the module or need that decided it. Do not offer a
+   second recommendation; you may say what would change it (for example "if
+   you add multi-tenant later, that moves you to Pro Plus").
+4. **What happens next.** Link `recommendation.link`. After purchase the
+   licence key arrives by email; set it as `AILK_LICENSE_KEY` in your
+   environment. To install the module(s): run
+   `pnpm dlx create-ailk@latest --help`, and name `add-module` only if that
+   output lists it. Otherwise say: re-run `create-ailk` with
+   `--modules <module>` and the key set, into a new directory, and move your
+   content across.
+
+## Hard rules
+
+- **Never state a price that is not in the helper's output for this run.**
+  Not from memory, not from an earlier run, not from another page, not as an
+  estimate or a range. A price appears in your answer only if it appears in
+  this run's `options[].prices` or `alsoPublished`.
+- **Unreachable means no prices.** When `pricing.status` is `unreachable`,
+  say the pricing page could not be reached, give no price for any option,
+  and link https://ailaunchkit.ai/pricing. Still show the site and the
+  recommendation — neither depends on a price.
+- **Unpublished means no prices.** When `pricing.status` is `unpublished`,
+  say the pricing page does not publish machine-readable prices yet and link
+  https://ailaunchkit.ai/pricing.
+- **Read-only.** Write no file and install nothing. The only outside command
+  besides the helper is the `--help` probe in step 3.
+- **Never print the licence key.** Report only whether it is set.
+
+## References
+
+- `references/options.md` — the seven options in plain words.

package/templates/.claude/skills/upgrade-plan/references/options.md

@@ -0,0 +1,24 @@
+# The options
+
+What each option adds and what it requires, in plain words. Names and
+structure only — prices come from https://ailaunchkit.ai/pricing at run time,
+never from this file.
+
+Source: the AI Launch Kit product vocabulary (Commerce; Packaging and
+delivery). Levels are Free, Pro and Pro Plus; Agency is an agreement, not a
+level; Commerce, SaaS and SaaS with Usage are the three rungs of the one
+commerce add-on, bought on top of a level.
+
+| Option              | What it adds                                                                                                                         | Requires                                  |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
+| **Free**            | The open-source base: the website, its API and MCP server, and the marketing module. Every site is agent-discoverable at this level. | Nothing — no licence key                  |
+| **Pro**             | The paid modules for one site — docs and blog, scheduling, signal collectors, the Admin app — kept current.                    | A licence key for the site                |
+| **Pro Plus**        | Everything in Pro, plus the multi-tenant module: organizations, workspaces and members.                                              | A licence key for the site                |
+| **Agency**          | A reseller agreement for building sites for clients. Not a bigger level.                                                             | Each client site is licensed Pro or Pro Plus |
+| **Commerce**        | Checkout, payment links, hosted invoices, subscriptions and the customer portal, through your own Stripe account.                    | Any paid level (Pro or Pro Plus)          |
+| **SaaS**            | Commerce plus plans, trials, coupons and entitlements mapped to feature flags — for a product that bills its tenants.                | Pro Plus                                  |
+| **SaaS with Usage** | SaaS plus usage metering, prepaid credits, overage and spend limits.                                                                  | Pro Plus                                  |
+
+Payment always happens on a Stripe-hosted page; the site never renders a card
+form. Paid bookings (deposits, no-show holds) belong to the scheduling module,
+not to Commerce.