create-ailk 0.8.0 → 0.10.0

package/templates/.claude/skills/check-site/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: check-site
-description: Run `ailk-audit --json` on the consumer's AILK site, parse the JSON report, and explain the score and findings in plain language. Use when the user asks "how is my site doing?", "audit my site", "what's my score?", "is my JSON-LD valid?", "do I have all the schema I need?", or otherwise wants a citation-readiness check on their AILK content. The skill never edits files — it reports and points at fix tools.
+description: Run `ailk-audit --format json` on the consumer's AILK site, parse the JSON report, and explain the score and findings in plain language. Use when the user asks "how is my site doing?", "audit my site", "what's my score?", "is my JSON-LD valid?", "do I have all the schema I need?", or otherwise wants a citation-readiness check on their AILK content. The skill never edits files — it reports and points at fix tools.
 ---
 
 # check-site
 
-Shell out to `ailk-audit --json`, parse the JSON, and turn it into a
+Shell out to `ailk-audit --format json`, parse the JSON, and turn it into a
 conversational summary the consumer can act on. Pure explain-only —
 the skill names fix tools (like the `schema:` frontmatter override)
 but does not invoke them.
@@ -27,22 +27,46 @@ Skip this skill when:
   tool (usually `add-page`'s `schema:` frontmatter override) and stop. This skill reports;
   fix tools fix.
 - The consumer is asking about deploy-time monitoring or continuous
-  audits — those are Pro features (`ailk pro` for details). Mention
-  briefly and stop.
-- The audit CLI isn't installed (`ailk-audit` not on PATH or as a
-  workspace bin) — translate the error per "Common errors" below.
+  audits — those are Pro features (the `upgrade-plan` skill explains
+  the levels). Mention briefly and stop.
+- The audit CLI isn't installed (`apps/api/node_modules/.bin/ailk-audit`
+  is missing) — translate the error per "Common errors" below.
 
 ## The mechanic
 
+### Step 0 — Read what this site can render
+
+Read `.ailk-site-manifest.json` at the site root, the site's roster of
+record:
+
+- `modules` — the modules this site has. Add any module the
+  `# Modules:` line of `architecture.yaml` names that `modules` does not:
+  `create-ailk add-module` records a module it adds there. With no
+  manifest, or none carrying `modules`, that line is the set.
+- `rows` — every route the site carries and the page type each renders.
+- `level` — present only when the scaffold derived it from the licence
+  key. It never decides what to suggest; `modules` does.
+
+A page type renders on this site only when its **Module** in
+`.claude/skills/add-page/references/page-types.md` is in that set.
+Step 7 suggests a page only of such a type.
+
 ### Step 1 — Invoke the CLI
 
-Run `ailk-audit --json` from the consumer's project root. Use
-whichever of these is appropriate to the consumer's setup:
+The `ailk-audit` CLI ships in `@working-theory/aeo`, which the scaffold
+installs as a dependency of `apps/api` — not of the site root — so pnpm
+links its bin at `apps/api/node_modules/.bin/ailk-audit`. Run it **from
+the site root**:
 
-- `pnpm exec ailk-audit --json`
-- `npx ailk-audit --json`
-- A package.json script if the consumer has one (`pnpm audit:run`,
-  etc.) — only if it's a thin wrapper over the same CLI.
+```bash
+apps/api/node_modules/.bin/ailk-audit --format json
+```
+
+The site root matters: the CLI reads `content/` (its `--content-root`
+default) and `project.yaml` relative to the directory it runs in. Do not
+run it through `pnpm --filter ./apps/api exec`, which runs it inside
+`apps/api` where neither exists. `--format json` is the flag that
+selects JSON; the CLI rejects any flag it does not know and exits 2.
 
 Capture both stdout (the JSON report) and stderr (errors). Do not
 cache. Each invocation runs the CLI fresh.
@@ -61,7 +85,9 @@ Stop here on errors. Do not continue to Step 3.
 
 ### Step 3 — Parse the JSON report
 
-The report shape (from `packages/aeo/src/types.ts`):
+The report is the `AuditReport` type `@working-theory/aeo` exports
+(its shipped `dist/types.d.ts`, under
+`apps/api/node_modules/@working-theory/aeo/`):
 
 ```ts
 interface AuditReport {
@@ -136,6 +162,12 @@ themselves on a subsequent turn.
 | `entity-markup`       | Manual edit — ensure `Organization` (or `Person`) JSON-LD is emitted somewhere site-wide |
 | `faq-howto-incentive` | `add-page`'s `schema:` frontmatter override — add an `FAQPage` or `HowTo` block to a relevant page |
 
+When a fix means adding a page, name only a page type this site can
+render (Step 0) — for `faq-howto-incentive`, a `FAQPage` or `HowTo`
+page, never one the site's modules do not render. When only a type the
+site cannot render would fix a finding, say which module renders it and
+which level carries it, and point at the `upgrade-plan` skill.
+
 Phrase the pointer as a single sentence:
 
 > "Missing `Product` schema on `/pricing` — add it via `add-page`'s
@@ -152,12 +184,12 @@ single-line mention tied to that finding:
   mismatch or stale schema-type usage):
 
   > "Pro auto-applies schema-pack updates as schema.org evolves —
-  > `ailk pro` for details."
+  > the `upgrade-plan` skill explains the levels."
 
 - **Continuous-deploy audit** (the consumer is asking how to keep
   the score from regressing, not about a specific finding):
   > "Pro can run this audit on every deploy and gate releases on
-  > the score — `ailk pro` for details."
+  > the score — the `upgrade-plan` skill explains the levels."
 
 Never produce a multi-line Pro recommendation, feature
 comparison, or upgrade prompt. The mention is informational, not
@@ -205,8 +237,9 @@ Never recommend "weekly" / "monthly" / a date.
   mechanism the skill points at. Never auto-invoked.
 - **`add-page`** — new-page creation; not a fix-tool
   for audit findings (audit reports on existing pages).
-- **`packages/aeo`** — owner of the `ailk-audit` CLI and rule set.
-  This skill depends only on the CLI's `--json` output schema, not
-  the package's internal types. New rules added upstream surface
+- **`@working-theory/aeo`** — owner of the `ailk-audit` CLI and rule
+  set, installed under `apps/api`. This skill depends only on the
+  CLI's `--format json` output schema, not the package's internal
+  types. New rules added upstream surface
   automatically as new findings; the glossary may lag and that's
   acceptable (unrecognized rule IDs render as the raw ID).

package/templates/.claude/skills/check-site/references/common-errors.md

@@ -73,21 +73,24 @@ mis-translate an unfamiliar error into a familiar fix path.
 
 - `command not found: ailk-audit`
 - `ailk-audit: command not found`
-- The skill itself can't find the binary on PATH or in
-  `node_modules/.bin`.
+- `apps/api/node_modules/.bin/ailk-audit: No such file or directory`
+- The skill itself can't find `apps/api/node_modules/.bin/ailk-audit`.
 
 **Translation:**
 
 > The `ailk-audit` CLI isn't installed in this project. It ships
-> with `@working-theory/aeo`, which is normally part of the AILK consumer
-> scaffold.
+> with `@working-theory/aeo`, which the AILK scaffold installs as a
+> dependency of `apps/api` — its bin lives at
+> `apps/api/node_modules/.bin/ailk-audit`, not at the site root.
 >
-> Add it: `pnpm add -D @working-theory/aeo` (dev dep is fine — audits run
-> at content time, not at build time). Then `pnpm install` and
-> re-run.
+> If `apps/api/package.json` lists `@working-theory/aeo`, run
+> `pnpm install` once from the site root to refresh
+> `apps/api/node_modules/.bin`, then re-run the audit from the site
+> root.
 >
-> If `@working-theory/aeo` is in `package.json` but the binary still isn't
-> found, run `pnpm install` once to refresh `node_modules/.bin`.
+> If it isn't listed, the scaffold's `apps/api` is incomplete — add
+> it there with `pnpm --filter ./apps/api add @working-theory/aeo`,
+> then re-run from the site root.
 
 ---
 

package/templates/.claude/skills/check-site/references/findings-glossary.md

@@ -7,7 +7,7 @@ pointer).
 
 The structure deliberately matches `perRule[].id` from the audit
 JSON so the skill can grep this file for `## <rule-id>` to find the
-explanation. New rules added to `packages/aeo` will not appear here
+explanation. New rules added to `@working-theory/aeo` will not appear here
 until this file is updated; render unrecognized rule IDs as the raw
 ID (no synthesis).
 
@@ -118,7 +118,7 @@ an _incentive_ in drill-down, not a finding to "fix."
 ## always-passes / always-fails
 
 These are **test rules** that exist for the audit's own test suite
-in `packages/aeo`. They should not appear on a real consumer site
+in `@working-theory/aeo`. They should not appear on a real consumer site
 unless the rule list has been customized. If you see one of these
 IDs in your audit output, the consumer's `ailk-audit` CLI may have
 a non-standard rule list — that's a setup question, not a content
@@ -129,11 +129,11 @@ finding.
 ## Unrecognized rule IDs
 
 If the audit JSON includes a rule ID not listed above, the rule is
-new (added to `packages/aeo` after this glossary was last updated).
+new (added to `@working-theory/aeo` after this glossary was last updated).
 Render it as:
 
 > Rule `<id>` — `<evidence text from the audit JSON>` — not in
-> the local glossary; consult `packages/aeo` upstream docs.
+> the local glossary; consult the `@working-theory/aeo` package docs.
 
 Do not invent a plain-language explanation for an unrecognized
 rule. The consumer can read the rule's `description` field from

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

@@ -20,7 +20,7 @@ The skill applies these rules in `SKILL.md` Step 5.
 
 A rule with `pass: false` AND `weight: 0` is **not possible** today
 (incentive rules are designed to never fail — see
-`faq-howto-incentive` in `packages/aeo`). If one ever appears,
+`faq-howto-incentive` in `@working-theory/aeo`). If one ever appears,
 treat it as Info (the rule's own design says failures are neutral).
 
 ---
@@ -39,7 +39,7 @@ severity-based. Reasons:
   The skill turns "weight 10 fail" into "Critical" because that's
   the language consumers can act on.
 - **Rule authors don't have to think about severity.** A new rule
-  added to `packages/aeo` gets a weight (its impact on the score)
+  added to `@working-theory/aeo` gets a weight (its impact on the score)
   and the skill maps that to a severity tier automatically. No
   coupling between rule authoring and consumer-facing UX.
 
@@ -105,7 +105,7 @@ for drill-down.
 
 ## Future rules
 
-When `packages/aeo` adds a new rule, this glossary may not name
+When `@working-theory/aeo` adds a new rule, this glossary may not name
 it. The severity mapping still works because it keys off `weight`
 and `pass` only — both fields are guaranteed by the
 `PerRuleResult` type. New critical-tier rules will surface as

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

@@ -67,15 +67,30 @@ 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
+1. Read `.ailk-site-manifest.json` at the site root, the site's roster
+   of record: `modules` (the modules this site has) and `rows` (every
+   route it carries). Add any module the `# Modules:` line of
+   `architecture.yaml` names that `modules` does not — `create-ailk
+   add-module` records a module it adds there; with no manifest, or none
+   carrying `modules`, that line is the set. `level`, when present, never
+   decides anything here.
+
+   The page's `type` must render on this site: its **Module** in
+   `../add-page/references/page-types.md` is in that set, or a row
+   already renders it (`rows[].pageType` — a Free starter's `/meet/<slug>`
+   `BookCall` placeholders). When it does not,
+   say which module renders the type and which level carries it, point at
+   the `upgrade-plan` skill, and stop. Never fill a page this site cannot
+   render.
+2. Read the profile: `profiles/<slug>.yaml`.
+3. Read `content/_site.mdx` for `siteIdentity.name`.
+4. Read the page file. Note its stack (`sections[].type` in order).
+5. 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]/`
+6. 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.
@@ -88,7 +103,9 @@ fields and intake answers that fill it.
 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>`);
+     `description` = its `job`, `link.href` = `/services/<kebab name>`
+     only when the manifest's `rows` carry `/services/[slug]`; otherwise
+     no `link`, so no entry points at a page the site does not have);
    - vocabulary → headlines, eyebrows and FAQ questions (the buyer's own
      words: the `problem` list for what went wrong, `outcome` for what
      they get);
@@ -176,5 +193,7 @@ and run both again. Stop only when both are clean.
 - 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.
+  `nav` entries are declared for a later step and are not applied here,
+  and a profile page type this site cannot render (Step 0) is never
+  suggested.
 - Write a price, a name or an address the owner did not give.

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

@@ -50,7 +50,7 @@ vocabulary:
     - tidy job, nothing left behind
 roster:
   - op: add
-    route: /emergency
+    route: /meet/emergency
     pageType: BookCall
     reason: Emergency jobs book a call, not a form.
   - op: drop

package/templates/.claude/skills/setup-deploy/SKILL.md

@@ -1,12 +1,13 @@
 ---
 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).
+description: Emit deploy configuration for an AILK consumer site — `vercel.json` and `RUNBOOK.md`, plus an env checklist read from the scaffold's own `.env.example`. 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).
 ---
 
 # 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
+Emit `vercel.json` and `RUNBOOK.md` at the consumer's project root,
+and bring the scaffold's own `.env.example` up to date with what the
+site's code reads, ready for a Vercel deploy. Vercel is the only valid
 `platform` value at v1. Other platforms (Netlify, Cloudflare, Render,
 Fly, self-host) reject with an explicit "not yet supported" message
 and emit nothing.
@@ -40,13 +41,16 @@ Skip this skill when:
   the consumer's project root.
 - For each artifact, ask the consumer how to handle conflicts
   (merge / overwrite / skip) before writing.
-- Emit the three artifacts at the consumer's project root, derived
-  from templates in `references/`.
+- Emit `vercel.json` and `RUNBOOK.md` at the consumer's project root,
+  derived from templates in `references/`.
+- Read the env contract from the scaffold's own `.env.example` — the
+  file every scaffold ships at its root — plus a `process.env` scan
+  of the site's code, and turn it into the env checklist (Step 5).
 - 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
-  two lead-destination headings).
+  `.env.example` declares every variable the `process.env` scan
+  found, confirm `RUNBOOK.md` has the two lead-destination headings).
 
 **Does not:**
 
@@ -84,23 +88,31 @@ consumer's project root. For each one, note:
 - **Missing** — will emit fresh.
 - **Present** — ask how to handle (Step 3).
 
+`.env.example` is the exception: every scaffold ships one, and it is
+the source this skill reads, not a file it writes from scratch. If
+it is missing, tell the consumer to restore it from git history and
+re-run — never write one from memory.
+
 ### Step 3 — Conflict handling per file
 
 For each existing artifact, show the consumer:
 
 1. The first ~10 lines of the existing file (preview).
 2. A summary of what the skill would emit (template name + key
-   fields).
+   fields; for `.env.example`, the variables Step 5 would add).
 3. Three options: **merge** (only for `RUNBOOK.md` and
    `.env.example` — see merge logic below), **overwrite**
-   (replace contents), **skip** (leave existing file untouched).
+   (replace contents; not offered for `.env.example`, which has no
+   other source), **skip** (leave existing file untouched).
 
 Wait for the consumer's choice per file. Do not blindly overwrite.
 
-**Merge logic — `.env.example`:** if a var listed in
-`references/env-vars-template.md` is **missing** from the existing
-file, append it (with comment) at the bottom under a "## Added by
-setup-deploy" section. Vars already present are not modified.
+**Merge logic — `.env.example`:** if a var the Step 5 `process.env`
+scan found is **missing** from every `.env.example` Step 5 reads —
+neither set (`NAME=`) nor listed commented (`# NAME=`) — append it
+(with comment) at the bottom of the root file
+under a `# ── Added by setup-deploy ──` heading. Lines already in
+the file are never modified; the consumer's comments and values win.
 
 **Merge logic — `RUNBOOK.md`:** if the "Leads — where messages go"
 section (with its two headings, `Email (default)` and
@@ -130,22 +142,43 @@ emitted file has these fields:
 After write, parse the JSON. If parse fails, the skill has a bug —
 report it to the consumer with the literal error.
 
-### Step 5 — Emit `.env.example`
-
-Use the template at `references/env-vars-template.md`. The emitted
-file lists every env var the consumer's site reads, grouped by
-concern (auth, content, payments, analytics, etc.) with placeholder
-values and inline comments.
+### Step 5 — Build the env checklist from `.env.example`
+
+The env contract is the scaffold's own `.env.example` at the project
+root, plus the per-app `apps/*/.env.example` files it points to. Read
+them; keep no second copy of them anywhere, including in this skill.
+
+1. **Read the declared names.** In each of those files, every
+   uncommented `NAME=value` line is a variable the scaffold sets (for
+   example `CONTENT_ADAPTER=mdx`); every commented `# NAME=` line is
+   an opt-in variable. The `# ── <Section> ──` heading above a line
+   is its group, and the comment above an entry says what it does
+   and whether production needs it. A name counts as declared when
+   any of the files declares it.
+2. **Scan the code.** Grep the site's source (`apps/`, `database/`,
+   and `packages/` if the scaffold has one) for `process.env.NAME`
+   and `process.env["NAME"]`. Skip `NODE_ENV`, variables the platform
+   sets itself (`VERCEL_*`, `CI`), and any name the files' comments
+   call deprecated — the code reads those only as a fallback, and the
+   checklist uses the name that replaced them.
+3. **Add what is missing.** A name the scan found that `.env.example`
+   does not declare goes at the bottom under
+   `# ── Added by setup-deploy ──`, commented out with an empty
+   placeholder and a one-line comment naming the file that reads it.
+   Do this only when the consumer chose **merge** in Step 3; on
+   **skip**, list those names in the checklist instead. Either way,
+   never silently omit a var the consumer's site reads.
+4. **Show the checklist.** List each section heading with its
+   variables, marking the ones the file sets, and quote the entry's
+   own comment for what production needs. Call out every value the
+   file sets that the consumer must change for their own site — for
+   example `AILK_PUBLIC_DOMAIN`, and `STEALTH`, which stays `true`
+   until launch. Use the names exactly as `.env.example` spells
+   them — do not restate a variable from memory.
 
 The skill **does not** read live `.env` files. Placeholder values
 only. No `sk_live_*`, no `pk_live_*`, no real Resend keys, no real
-NextAuth secrets.
-
-After write, count the declared vars and confirm the count matches
-the template's expected count. If a var the consumer's site uses
-(grep `process.env.X` from a quick scan) is missing from the
-template, add it under "## Added by setup-deploy" — never silently
-omit a var the consumer needs.
+auth secrets.
 
 ### Step 5a — Lead delivery
 
@@ -160,10 +193,10 @@ two questions:
 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.
+   domain). All three are needed — a key alone sends nothing.
+   `.env.example` already lists all three as commented entries; 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:
@@ -229,7 +262,9 @@ message.
 Before reporting "done":
 
 - `vercel.json` parses as JSON ✓
-- `.env.example` declares >= the count of vars in the template ✓
+- Every variable the `process.env` scan found is declared in an
+  `.env.example`, set or commented — or, when the consumer chose
+  **skip**, listed in the checklist ✓
 - `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
@@ -250,8 +285,9 @@ If any check fails, surface the failure to the consumer (not silent).
 ## References
 
 - `references/vercel-json-template.md` — minimal viable `vercel.json`.
-- `references/env-vars-template.md` — `.env.example` structure with
-  placeholder values per category.
+- The scaffold's own `.env.example` at the project root, and the
+  per-app `apps/*/.env.example` files — the env contract Step 5
+  reads. This skill keeps no copy of it.
 - `references/runbook-template.md` — `RUNBOOK.md` with the two lead
   destinations (Email (default), Lead inbox (setup-database)).
 
@@ -265,11 +301,12 @@ If any check fails, surface the failure to the consumer (not silent).
   RUNBOOK adds production callback URLs and merges with any
   existing runbook content (not blindly overwrites).
 - **`@working-theory/env`** — at v1 a placeholder package, not yet a Zod
-  schema. This skill derives `.env.example` from the template, not
-  from a runtime schema. When `@working-theory/env` ships its schema, this
-  skill should be revised to read from it.
-- **Stripe sandbox-only** — hard-floor enforced globally. Emitted
-  `.env.example` uses `sk_test_*` placeholders, never `sk_live_*`.
+  schema. This skill reads the env contract from the scaffold's
+  `.env.example`, not from a runtime schema. When `@working-theory/env`
+  ships its schema, this skill should be revised to read from it.
+- **Stripe sandbox-only** — hard-floor enforced globally. Nothing
+  this skill adds to `.env.example` carries a `sk_live_*` or
+  `pk_live_*` value.
 - **Cloudflare deferred** — neither CF Pages (deploy target) nor
   CF KV / D1 / R2 (data layer) is in v1. Will ship as a coherent
   follow-up PR.

package/templates/.claude/skills/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, 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.