create-ailk 0.6.0 → 0.7.0

package/templates/.claude/skills/fill-page/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: fill-page
+description: Fill one existing page's section content from a category profile. Tier 1 writes realistic, labelled sample content for the category (a plumber's home page, say). Tier 2 asks the owner the profile's questions and writes the company's own first draft from their answers and `_site.mdx`. Use when the user says "fill this page", "fill the home page for a plumber", "write sample content for my services page", or "write my real copy from what I tell you". It never creates a page, never changes a page's section stack, and never edits `_site.mdx`.
+---
+
+# fill-page
+
+Replace one page's `{brace}` instructions with content, reading the
+content from a **category profile** (`profiles/<slug>.yaml` beside this
+file). A profile is the data for one business type: the schema.org
+subtype, the typical offerings, the proof buyers expect, the buyer's own
+words, and the questions to ask the owner.
+
+Two tiers:
+
+| Tier | Source                                                   | Result                                     | `placeholder` |
+| ---- | -------------------------------------------------------- | ------------------------------------------ | ------------- |
+| 1    | the profile                                              | realistic sample content for the category  | `true`        |
+| 2    | `_site.mdx` + the owner's answers (`content/_intake.yaml`) | the company's own first draft              | by the rule in Step 2.4 |
+
+`placeholder: true` in a page's frontmatter makes the site render a
+**PLACEHOLDER — REPLACE BEFORE LAUNCH** label at the top of the page.
+The label is for people. Structured data reaches agents without it, so
+tier-1 content must be safe to publish by itself (see the never-invent
+list).
+
+## Inputs
+
+- **The page file** — `content/<locale>/<Type>/<slug>.mdx`. It must
+  already exist; `add-page` creates pages.
+- **The page type** — the frontmatter `type`.
+- **The profile slug** — a file under `profiles/` (e.g. `plumbing`).
+  Ask if the user did not name one. If there is no profile for their
+  category, say so and stop.
+- **The tier** — 1 unless the user asks for their own copy.
+
+## What never changes
+
+- The page's **section stack**: every section's `id` and `type`, in
+  order. Never add, remove or reorder a section. The starter's manifest
+  records each page's sections, and a changed stack fails its check.
+- Each section's **layout options** that are already present:
+  `variant`, `columns`, `layout`, `initialOpen`, `size` and the like.
+  They are the site's locked look.
+- Link targets (`href`) that are already present, except a link to a
+  Service page, which follows that page's slug (Step 1.3).
+- `{/* … */}` comments in the MDX body.
+- `_site.mdx`. Identity strings (the company name) are read from it,
+  never written to it.
+
+## Never invent (tier 1)
+
+At tier 1, write none of these. Remove any you find in the page:
+
+- `price`, `priceCurrency`, `availability` or `stripe` — each feeds the
+  schema.org `Offer` an agent quotes as the company's price.
+- A person's name or another company's name.
+- A phone number, a street address, or a licence or registration number.
+- A town, a county, or a distance: the service area is a company fact.
+- Testimonials: `author` is the literal `Sample customer`; no `company`,
+  `rating` or `avatar`.
+- Statistics a reader would take as measured (a count of jobs, a years
+  figure). Use the profile's `proof[]` labels as words, not numbers.
+
+The company name is the one identity string tier 1 may write, and it
+comes from `_site.mdx` `siteIdentity.name`.
+
+## Step 0 — Read
+
+1. Read the profile: `profiles/<slug>.yaml`.
+2. Read `content/_site.mdx` for `siteIdentity.name`.
+3. Read the page file. Note its stack (`sections[].type` in order).
+4. For each section type in the stack, read its data schema: the
+   `<Type>SectionDataSchema` (or `<Type>DataSchema`) export in the
+   installed `@working-theory/validation`'s `schemas/page-sections`. Fill
+   only fields the schema declares. Every field a section renders from
+   copy gets content; a field the source page did not use stays unused.
+5. Find the route that renders this page type under `apps/web/app/[locale]/`
+   and read its `bodyMode`. When it is `"mdx-body"`, the MDX body is
+   rendered and must be filled too. Otherwise the body is a short note,
+   and you rewrite it as one plain sentence that names no braces.
+
+`references/section-sources.md` maps each section type to the profile
+fields and intake answers that fill it.
+
+## Step 1 — Tier 1: sample content
+
+1. **Sections.** For each section, in place, write every copy field from
+   the profile using `references/section-sources.md`:
+   - offerings → `items` entries (`title` = the offering `name`,
+     `description` = its `job`, `link.href` = `/services/<kebab name>`);
+   - vocabulary → headlines, eyebrows and FAQ questions (the buyer's own
+     words: the `problem` list for what went wrong, `outcome` for what
+     they get);
+   - proof → `stats` labels and `testimonials` quotes, under the
+     never-invent list.
+   Keep `id`, `type` and every layout option.
+2. **Frontmatter.** Rewrite `title` and `description` without braces.
+   Use the company name from `_site.mdx` where the page names the
+   company. On a page that carries `provider.name`, set it to the company
+   name. Drop `schema.areaServed`; set `schema.serviceType` to the
+   offering name. Remove every key the never-invent list names.
+3. **Service pages.** A `Service` page is one offering. The user names
+   the offering, or you take the first profile offering that no other
+   Service page carries yet. Set `title` and `schema.serviceType` to the
+   offering `name`, and `slug` and the file name to its name in kebab
+   case (`Drain clearing` → `drain-clearing`): rename the file, never
+   copy it. To give every offering a page, the user first adds one
+   Service page per offering (`add-page`, or a copy of an existing one),
+   then runs this skill on each.
+4. **Body.** When the route renders `mdx-body`, rewrite each paragraph
+   and list item under the page's existing headings in the category's
+   words. Keep the headings, keep the order, keep the comments. Drop
+   every `\{…\}` instruction. Under a price heading, say how the job is
+   priced (the offering's `pricing`: `quote`, `fixed`, `hourly`,
+   `subscription`) in words, with no figure.
+5. **Label.** Set `placeholder: true` in the frontmatter.
+6. **Check** (below).
+
+## Step 2 — Tier 2: the company's own draft
+
+1. **Ask.** Ask each `intake[]` question from the profile, in order, one
+   at a time. Record the answers in `content/_intake.yaml`:
+
+   ```yaml
+   answers:
+     offerings: [Drain clearing, Emergency call-out]
+     service_area: "…"
+     faq: null # unanswered
+   ```
+
+   A list answer stays a list. An unanswered or skipped question is
+   `null`. Offerings are named exactly as the profile names them.
+2. **Fill.** Fill the page as in Step 1, but from `_site.mdx` and the
+   answers first; the profile fills only what the answers leave open.
+   - A profile offering the owner does not offer appears on no page:
+     remove its `items` entries, and ask before deleting its Service
+     page (the one file this skill may delete).
+   - A price appears only when the owner gave one, with `priceCurrency`.
+   - The company name appears in each page's frontmatter (`title` or
+     `description`), and the service area in the home hero when given.
+   - A section whose sources have no answer keeps its tier-1 sample
+     content.
+3. **Never invent** still holds for everything the owner did not give.
+   Testimonials stay `Sample customer` unless the owner supplies a
+   customer's name with permission to publish it.
+4. **Label.** Set `placeholder: false` only when every section is filled
+   from company facts:
+   - every section type in the stack appears in the `fills` of at least
+     one intake item whose answer is not empty, and
+   - when the stack has a `hero` or `cta`, `_site.mdx` has
+     `siteIdentity.name`.
+
+   A page with no sections is judged on its body: a `Service` page is
+   cleared only when the `offerings` answer names its offering; any
+   other page with no sections keeps `placeholder: true`. In every other
+   case, keep `placeholder: true`.
+5. **Check** (below).
+
+## The check
+
+Run the site's own structured-data check. It reads every content page
+through the same frontmatter and section schemas the site renders with,
+and validates each page's JSON-LD:
+
+```bash
+pnpm --filter web test -- lib/__tests__/structured-data.test.tsx
+```
+
+Then search the filled file for a `{` or `}` in any frontmatter string or
+in the body outside `{/* … */}` comments. Fix everything either reports
+and run both again. Stop only when both are clean.
+
+## What this skill does not do
+
+- Tier 3 (the Messaging Canvas through the content pipeline).
+- Create a page — use `add-page`.
+- Edit `_site.mdx`, the nav or the page roster. A profile's `roster` and
+  `nav` entries are declared for a later step and are not applied here.
+- Write a price, a name or an address the owner did not give.

package/templates/.claude/skills/fill-page/profiles/plumbing.yaml

@@ -0,0 +1,80 @@
+# Category profile — Local Plumbing (#6640; starter-template contract § D).
+# Read by the `fill-page` skill: tier 1 fills a page with labelled sample
+# content from this file; tier 2 asks `intake[]` and fills from the answers.
+# Twin: templates/.claude/skills/fill-page/profiles/plumbing.yaml (byte-identical).
+slug: plumbing
+shape: local-business-service
+subtype: Plumber
+secondary: Person
+offerings:
+  - name: Drain clearing
+    job: Clears blocked sinks, showers, toilets and main drains, and says what caused the blockage.
+    pricing: quote
+  - name: Water heater installation
+    job: Removes the old tank or boiler and fits, tests and registers a new water heater.
+    pricing: fixed
+  - name: Emergency call-out
+    job: A plumber at the door the same day for a burst pipe, a flood or no water at all.
+    pricing: hourly
+  - name: Leak detection and repair
+    job: Finds the hidden leak behind a wall or under a floor and fixes it with the least damage.
+    pricing: quote
+proof:
+  - kind: credential
+    label: Licensed and insured
+  - kind: reviews
+    label: Reviews from local customers
+  - kind: response-time
+    label: Same-day response on emergency calls
+  - kind: guarantee
+    label: Workmanship guaranteed
+vocabulary:
+  problem:
+    - burst pipe
+    - blocked drain
+    - no hot water
+    - leaking tap
+    - low water pressure
+    - water stain on the ceiling
+  service:
+    - drain clearing
+    - water heater install
+    - emergency call-out
+    - leak repair
+    - pipe replacement
+  outcome:
+    - same-day fix
+    - hot water back on
+    - no water damage
+    - upfront quote
+    - tidy job, nothing left behind
+roster:
+  - op: add
+    route: /emergency
+    pageType: BookCall
+    reason: Emergency jobs book a call, not a form.
+  - op: drop
+    route: /pricing
+    reason: Most plumbing work is quote-priced, so a price table misleads.
+nav:
+  Services: Plumbing services
+content_posture: sample
+intake:
+  - id: offerings
+    ask: Which of these jobs do you take on, and is there one you do not list? (Drain clearing, water heater installation, emergency call-out, leak detection and repair.)
+    fills: [hero, items]
+  - id: service_area
+    ask: Which towns, postcodes or radius do you cover?
+    fills: [hero, cta]
+  - id: about
+    ask: How did the business start, who does the work, and what will you not take on?
+    fills: [content-block]
+  - id: proof
+    ask: What can a customer check — your licence, your insurance, your reviews, your response time, your guarantee?
+    fills: [stats, testimonials, social-proof]
+  - id: faq
+    ask: What do customers ask before they book, and what do you tell them?
+    fills: [faq]
+  - id: contact
+    ask: How should a customer reach you — phone, form or booking — and how fast do you reply?
+    fills: [cta]

package/templates/.claude/skills/fill-page/references/section-sources.md

@@ -0,0 +1,41 @@
+# Section sources
+
+Where each section's copy comes from. **Profile** is tier 1's source;
+**Intake** lists the `intake[]` answers that fill the section at tier 2
+(the same ids appear in each question's `fills`). Fields not named here
+are layout options: keep them as they are.
+
+| Section type    | Copy fields                                                                 | Profile (tier 1)                                                                                                 | Intake (tier 2)                          |
+| --------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `hero`          | `eyebrow`, `headline`, `subheadline`, `primaryCta.label`, `secondaryCta.label` | `vocabulary.problem` + `vocabulary.outcome` for the headline; the category name for the eyebrow                 | `offerings`, `service_area`              |
+| `items`         | `headline`, `description`, `items[].title`, `items[].description`, `items[].link` | one item per `offerings[]` entry: `title` = `name`, `description` = `job`, `link.href` = `/services/<kebab name>` | `offerings`                              |
+| `cta`           | `headline`, `description`, `primaryCta.label`, `secondaryCta.label`         | `vocabulary.outcome`                                                                                             | `service_area`, `contact`                |
+| `content-block` | `eyebrow`, `headline`, `body`                                               | `proof[].label` and `vocabulary.service`, with no names, places or numbers                                        | `about`                                  |
+| `faq`           | `headline`, `items[].question`, `items[].answer`                            | questions in `vocabulary.problem` words; answers from `offerings[].pricing` and `proof[]`                        | `faq`                                    |
+| `stats`         | `headline`, `items[].label`, `items[].value`                                | `proof[].label` as the label; a value only when it is not a measurement (e.g. `Same day`)                        | `proof`                                  |
+| `testimonials`  | `headline`, `items[].quote`, `items[].author`                               | quotes in `vocabulary.outcome` words; `author: Sample customer`; no `company`, `rating` or `avatar`              | `proof`                                  |
+| `social-proof`  | `headline`, labels                                                          | `proof[].label`                                                                                                  | `proof`                                  |
+
+A section type not in this table: fill its copy fields from the profile's
+`vocabulary` and leave its data otherwise as it was. At tier 2 no intake
+answer fills it, so a page carrying it keeps `placeholder: true`.
+
+## Frontmatter
+
+| Key                    | Tier 1                                             | Tier 2                                      |
+| ---------------------- | -------------------------------------------------- | ------------------------------------------- |
+| `title`, `description` | the category's words; the company name from `_site.mdx` where the page names the company | the company name and the owner's answers    |
+| `provider.name`        | `siteIdentity.name`                                | `siteIdentity.name`                         |
+| `schema.serviceType`   | the offering `name`                                | the offering `name`                         |
+| `schema.areaServed`    | removed                                            | the `service_area` answer                   |
+| `price`, `priceCurrency`, `availability`, `stripe` | removed                | only a price the owner gave, with its currency |
+| `placeholder`          | `true`                                             | by the rule in `SKILL.md` Step 2.4           |
+
+## Pricing words (Service bodies, FAQ answers)
+
+| `pricing`      | Say                                                                 |
+| -------------- | ------------------------------------------------------------------- |
+| `quote`        | priced after a look at the job; the quote is given before work starts |
+| `fixed`        | one fixed price for the job, agreed before work starts               |
+| `hourly`       | charged by the hour on site, with the call-out rate stated up front  |
+| `subscription` | a regular plan, billed on a schedule                                 |

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

@@ -1,9 +1,9 @@
 ---
-name: provision-config
+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. The RUNBOOK includes the three named persistence-upgrade paths for leads.jsonl (Vercel KV / Supabase / Postgres-via-`@working-theory/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
@@ -64,7 +64,7 @@ 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.
@@ -100,7 +100,7 @@ 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,
@@ -144,7 +144,7 @@ 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 6 — Emit `RUNBOOK.md`
@@ -168,7 +168,7 @@ runbook has these sections:
    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.
+   `add-auth` and need to register prod redirect URIs.
 
 After write, grep the RUNBOOK for the three named persistence
 section headings (Vercel KV, Supabase,
@@ -214,7 +214,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.
 
@@ -228,7 +228,7 @@ If any check fails, surface the failure to the consumer (not silent).
 
 ## Coordination
 
-- **`scaffold-auth` (#364)** — produces its own `RUNBOOK.md`
+- **`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.
 
@@ -177,7 +177,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/{provision-config → setup-deploy}/references/runbook-template.md

@@ -1,6 +1,6 @@
 # `RUNBOOK.md` Template
 
-The `provision-config` skill emits this runbook at the consumer's
+The `setup-deploy` 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.
 
@@ -13,12 +13,12 @@ missing, the skill has a bug.
 ```markdown
 # RUNBOOK — Production Operations
 
-This runbook is generated by the `provision-config` skill. It covers
+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 `provision-config`, new sections may be appended at
-the end under "## Added by provision-config." Existing sections are
+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.
 
 ---
@@ -40,7 +40,7 @@ Before you click Deploy in Vercel:
       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
+      `add-auth` and activated Google or GitHub. Each provider
       needs the prod callback URL added to its OAuth app settings.
 
 ---
@@ -160,9 +160,9 @@ Domains → Add → DNS records → wait for verification.
 
 ---
 
-## Production callbacks for OAuth (if you used `scaffold-auth`)
+## Production callbacks for OAuth (if you used `add-auth`)
 
-If you activated Google or GitHub OAuth via `scaffold-auth` (#364),
+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:
 
@@ -240,7 +240,7 @@ Step 3) offers merge / overwrite / skip. Merge logic:
 3. Headings already present → not modified.
 4. Headings missing → append at the end of the existing file under:
    ```
-   ## Added by provision-config
+   ## Added by setup-deploy
    ```
 
 The pre-deploy checklist, custom-domain, and OAuth-prod-callbacks

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.