create-ailk 0.10.0 → 0.11.1

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

@@ -1,204 +0,0 @@
-# `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/setup-deploy/references/vercel-json-template.md

@@ -1,98 +0,0 @@
-# `vercel.json` Template
-
-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.
-
-## 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/update-page/SKILL.md

@@ -1,117 +0,0 @@
----
-name: update-page
-description: Rename a page on this AI Launch Kit site — change its URL (/meet to /schedule, /team to /people) and/or its title — safely, in one plan-then-confirm pass. Use this whenever the user wants to move, rename, re-slug or re-title an existing page, even if they don't say "rename" — "make /meet be /schedule", "the booking page should live at /book", "call the team page People", "I don't like this URL". It moves the content file(s), the page's own route folder if it has one, every exact internal link, the site-manifest row, and adds a permanent redirect from the old URL. It refuses pages whose URL is fixed by their type or shipped by the scaffold. Not for adding a page (add-page) or rewriting its words (fill-page).
----
-
-# update-page
-
-Move a page from `/old` to `/new` (and optionally give it a new title) without
-leaving a dead link, a stale manifest row, or a broken inbound URL behind. A
-bundled helper computes the whole change as a plan; you show the plan, the user
-confirms once, and only then does anything get written.
-
-## The one rule
-
-**Never run `apply` before the user has seen the plan and confirmed it.** The
-helper enforces this mechanically — `apply` requires the hash the plan printed,
-and refuses any other — but the order is yours to keep:
-plan → show the file list → wait for confirmation → apply with the plan hash.
-
-## Step 1 — Plan
-
-From the site root:
-
-```bash
-pnpm exec tsx .claude/skills/update-page/scripts/update-page.ts plan --from /meet --to /schedule
-```
-
-Add `--name "Book a time"` to also change the page's title (the `title:` in its
-content file; it sets the English file only and reports other languages as
-"title left as translated").
-
-The helper prints:
-
-- every file it would touch, tagged `move`, `modify`, `create` or `delete`;
-- `note:` lines a reader should know about (see below);
-- `hash: <sha256>` — the plan's fingerprint.
-
-It writes nothing. If it prints `refused: …` and exits 3, stop there and tell
-the user why (the reasons are below). Don't work around a refusal by hand.
-
-## Step 2 — Show the plan and wait
-
-Show the user the file list and the notes as printed. If they want to see the
-new contents, `plan --json` prints every change with its full new content.
-Then wait for one confirmation. A "yes" to the summary is enough; you don't
-need per-file approval.
-
-## Step 3 — Apply
-
-```bash
-pnpm exec tsx .claude/skills/update-page/scripts/update-page.ts apply --from /meet --to /schedule --confirm <hash>
-```
-
-Pass the same `--from`, `--to` and `--name` as the plan. The helper re-plans
-and compares hashes: if anything changed in between (a file was edited, a
-different rename was planned), it exits 1 and writes nothing — run `plan` again
-and confirm the new hash.
-
-## Step 4 — Check and report
-
-Run `pnpm build` from the site root. Then tell the user:
-
-- the new URL (with the locale, e.g. `/en/schedule`), and that `/meet` now
-  answers with a permanent redirect (HTTP 308) to it;
-- any `note:` lines that need their attention (below);
-- that the nav label text lives in `apps/web/messages/<locale>.json` if they
-  also want the menu wording changed — this skill only re-points the link.
-
-## What the plan changes
-
-| Surface | What happens |
-|---|---|
-| `content/<locale>/<Type>/old.mdx` (every locale) | Renamed to `new.mdx`; its `slug:` updated; `title:` updated when `--name` is given |
-| The page's own route folder, when a folder under `apps/web/app` serves `/old` and is not a route the scaffold ships (a page the catch-all route serves has none) | Moved to the sibling folder `new/`; the `getPage("old")` literal inside becomes `getPage("new")` |
-| Exact links to `/old` in `content/**` and `apps/web/lib/nav-config.ts` | Rewritten to `/new`. Exact means the whole path: `/meet` is rewritten, `/meet/book-a-call` and `/meeting` are not |
-| `.ailk-site-manifest.json` | The one row whose `route` is `/old` now reads `/new`; no other byte changes |
-| `apps/web/next.config.mjs` `redirects()` | Gains a managed block (`ailk:page-renames`) with `{ from: "/old", to: "/new" }`. Locale-prefixed forms are added for every non-default locale. A second rename collapses chains: renaming `/schedule` to `/book` later re-points the `/meet` row straight to `/book` |
-
-Links to `/old` in code files (`apps/web/app`, `lib`, `components`) are
-reported, not rewritten — the redirect covers them, and code edits are the
-owner's call.
-
-## The notes, and what to say about them
-
-- **"…belongs to the `<module>` module's routes…"** — the old or new URL is a
-  route a paid module (scheduling, docs-blog, …) would install if the site
-  adds it later. Tell the user: if they add that module, the redirect (for the
-  old URL) or the module's folder (for the new URL) will take over, and the
-  note says what to remove or rename first.
-- **"add-module `<module>` will keep these edited placeholder files…"** — the
-  rename edited seed pages that a module would normally replace; the module
-  will now list them for review instead. Nothing is lost.
-- **"add-module will no longer regenerate the nav…"** — the nav is now a
-  hand-edited file; later module installs report the nav change they wanted
-  rather than applying it.
-- **"the pages under /old … keep their URLs"** — detail pages like
-  `/meet/book-a-call` are fixed by their type and stay where they are.
-
-## When the helper refuses (exit 3)
-
-| Reason | What it means | What to offer instead |
-|---|---|---|
-| `routes must be one lowercase segment` | Only a top-level page moves (`/meet`, not `/meet/book-a-call`) | Detail pages are fixed by their type |
-| `no page at /old` | Nothing on the site is served there | Check the URL; `add-page` adds a page |
-| `/old is a code route with no page content to move` | A route folder exists but no content page backs it | A code change, not a rename |
-| `a <Type> page's URL is fixed by its type` | About, Contact, a Service, a booking page — their URL comes from the page type | Explain that these can't move; the title can still change in the content file |
-| `/old is served by a route the scaffold ships` | The route folder came with the scaffold (e.g. `/pricing`) | Same as above |
-| `/new already exists: …` | A route folder, another page, or a content locale directory owns `/new` | Pick another route |
-| `redirects() has been edited` | Someone hand-edited `redirects()` in `next.config.mjs`, so the helper won't touch it | Add the redirect line the message gives, by hand, or restore the generated method |
-
-## What this skill does not do
-
-- Add a page (`add-page`) or rewrite its words (`fill-page`).
-- Change the menu label text in `apps/web/messages/*.json` (it re-points the
-  link and reports the label key).
-- Edit route literals in code, or anything in `apps/api` / `apps/mcp`.
-- Move detail pages, hubs, or any page whose URL is fixed by its type.