create-ailk 0.7.0 → 0.9.0

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

@@ -1,12 +1,13 @@
 # `RUNBOOK.md` Template
 
 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.
+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 all three named persistence-section headings
-are present after emit (per SKILL.md Step 6 validation). If any is
-missing, the skill has a bug.
+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
 
@@ -35,109 +36,65 @@ Before you click Deploy in Vercel:
       set in Vercel before deploy.
 - [ ] **Configure your custom domain** if you have one (Vercel
       Project → Settings → Domains). Vercel handles TLS automatically.
-- [ ] **Pick a leads-persistence backend** — see the three named
-      upgrade paths below. **Do not deploy without picking one** if
-      your site captures leads. AILK's default `leads.jsonl`
-      fallback does not persist on Vercel's ephemeral filesystem.
+- [ ] **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.
 
 ---
 
-## Operations — leads.jsonl persistence
+## Leads — where messages go
 
-> **Critical:** AILK's default lead-capture writes to
-> `apps/api/leads.jsonl`. On Vercel's ephemeral filesystem, this
-> file **does not persist** across cold starts. Leads captured
-> during one container's lifetime are lost when that container
-> shuts down.
+Where a contact-form message goes depends only on what you set on
+the **API** project:
 
-You **must** pick a persistence backend before going live or you
-will lose leads. Pick one of the three sections below based on
-your situation:
+| 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      |
 
-- Cheapest fix, drop-in, native Vercel — **Vercel KV**
-- One provider for db + auth + storage — **Supabase**
-- Already have Postgres elsewhere — **Postgres via `@working-theory/database`**
+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.
 
----
-
-## Persistence upgrade — Vercel KV
+### Email (default)
 
-**When to pick:** you want the cheapest fix, no new infra, and
-you're already on Vercel. Vercel KV is Redis-compatible key-value
-storage, native to the Vercel dashboard.
+**When to pick:** you want messages in your inbox with no database
+to run. This is the default for a new site.
 
 **Setup:**
 
-1. Vercel Dashboard → Storage → Create Database → KV.
-2. Connect to your project. Vercel auto-populates
-   `KV_REST_API_URL` and `KV_REST_API_TOKEN` in your project
-   environment.
-3. Pull updated env vars locally: `vercel env pull`.
-4. Switch the lead-capture writer in your code from JSONL to KV
-   (`@working-theory/api`'s lead-capture supports a KV adapter — see its
-   README for the wiring).
-5. Redeploy.
+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.
 
-**Trade-offs:** KV is fast and easy but has limits (storage
-ceilings, access patterns). For >10K leads/month or rich querying,
-graduate to Supabase or Postgres.
-
----
+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.
 
-## Persistence upgrade — Supabase
-
-**When to pick:** you want one provider for database, auth, and
-storage. You're not committed to NextAuth (Supabase has its own
-auth), or you're fine running NextAuth + Supabase auth in parallel.
-
-**Setup:**
+### Lead inbox (setup-database)
 
-1. Sign up at <https://supabase.com>.
-2. Create a project.
-3. Go to Settings → API. Copy:
-   - `Project URL` → `NEXT_PUBLIC_SUPABASE_URL`
-   - `anon public` key → `NEXT_PUBLIC_SUPABASE_ANON_KEY`
-   - `service_role` key → `SUPABASE_SERVICE_ROLE_KEY` (server-only)
-4. Set those three env vars in Vercel project settings.
-5. Run the AILK Supabase migration (see `@working-theory/database` Supabase
-   adapter README — the migration creates a `leads` table with the
-   AILK schema).
-6. Switch the lead-capture writer to use the Supabase adapter.
-7. Redeploy.
-
-**Trade-offs:** Supabase is generous on free tier, scales well, and
-its dashboard is excellent. The auth coexistence with NextAuth is
-the only design wrinkle — most consumers either use NextAuth alone
-(treating Supabase as just a Postgres host) or commit to Supabase
-auth and remove NextAuth.
-
----
-
-## Persistence upgrade — Postgres via `@working-theory/database`
-
-**When to pick:** you already have Postgres somewhere — Neon,
-Railway, RDS, self-hosted, anywhere. You don't need a new provider
-relationship.
-
-**Setup:**
+**When to pick:** you want every message kept, searchable, in a
+lead inbox you review signed in — and newsletter signups collected.
 
-1. Get a Postgres connection string from your provider. Format:
-   `postgres://user:password@host:5432/dbname`.
-2. Set `DATABASE_URL` in Vercel project settings.
-3. Install `@working-theory/database`: `pnpm add @working-theory/database`.
-4. Run the migration:
-   `pnpm --filter @working-theory/database run migrate:deploy` (or your
-   provider's equivalent).
-5. The `@working-theory/database` package exposes a Prisma client tied to the
-   AILK schema; switch the lead-capture writer to use it.
-6. Redeploy.
-
-**Trade-offs:** most flexible, most setup. You manage the database
-yourself (backups, connection pooling, scaling). For consumers who
-already have Postgres in their stack, this is the natural fit.
+**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.
 
 ---
 
@@ -204,9 +161,9 @@ You do **not** need to redeploy after:
 
 ## Troubleshooting
 
-- **"My leads disappeared"** → you skipped the leads-persistence
-  upgrade. Pick one of Vercel KV / Supabase / Postgres above and
-  migrate the writer.
+- **"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).
@@ -219,15 +176,14 @@ You do **not** need to redeploy after:
 
 ## Section headings the validation must find
 
-After emit, the skill must grep for these three headings (verbatim
-match). All three must be present:
+After emit, the skill must grep for these two headings (verbatim
+match). Both must be present:
 
-- `## Persistence upgrade — Vercel KV`
-- `## Persistence upgrade — Supabase`
-- `## Persistence upgrade — Postgres via `@working-theory/database\``
+- `### Email (default)`
+- `### Lead inbox (setup-database)`
 
-If any is missing, the template was edited in a way that broke the
-contract. Surface the failure to the consumer (not silent).
+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
 
@@ -235,8 +191,8 @@ If the consumer already has `RUNBOOK.md`, the skill (per SKILL.md
 Step 3) offers merge / overwrite / skip. Merge logic:
 
 1. Read the existing file.
-2. Check whether each of the three named persistence section
-   headings is already present.
+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:
    ```

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

@@ -0,0 +1,117 @@
+---
+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 (only an `add-page`-created route has one) | 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.