create-ailk 0.8.0 → 0.9.0

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

@@ -1,257 +1,260 @@
 ---
 name: add-page
-description: Generate a new page on an AILK consumer site — App Router route + MDX content stub + typed JSON-LD attachment — in a single confirm-before-write pass. Use when the user says "scaffold me a /pricing page", "add an about page", "create a /contact route", or hands over a structured triple (e.g., "add home — Organization — anchor with hero, value prop, CTA"). Both invocation shapes flow through the same pipeline. MDX-only at v1; refuses on existing routes and points at the `schema:` frontmatter override for adding structured data to a page that already exists.
+description: Add a new page to this AI Launch Kit site — a new service, a new "who it's for" page, a new booking page, a comparison against a competitor, a stand-alone landing page, or a whole route the site doesn't carry yet like /pricing — with its content file, its structured data and its nav link, in one confirm-before-write pass. Use this whenever the user wants a page that doesn't exist yet, even if they don't say "page" — "add a service for kitchen remodels", "I need a /pricing page", "make a page for dentists", "add a comparison with Acme", "we need a booking page for on-site estimates", "add a landing page for the spring offer", or a structured triple like "pricing — Pricing — plans and FAQ". Not for changing a page that already exists (fill-page writes content; update-page renames).
 ---
 
 # add-page
 
-Generate a new page in one pass. Three artifacts emit together:
+Add a page this site can actually serve, at the path its routes really use,
+with a nav link, and nothing else. One plan, one confirmation, then write.
 
-1. **App Router route** at `app/<slug>/page.tsx`
-2. **MDX content stub** at `content/<Type>/<slug>.mdx`
-3. **JSON-LD attachment** via `<JsonLd schema={build<Type>(page)} />` from
-   `@working-theory/jsonld` (component) and `@working-theory/schema` (typed builder)
+The single most important fact about this site: **almost every page type
+already has its route.** Routes live in `apps/web/app/[locale]/…` and render
+whatever content file sits in `content/en/<Type>/`. So adding a page is
+usually **adding one content file**, not writing route code. Route code is
+only ever added by the `create-ailk add-route` command, never by hand — a
+hand-written route drifts from the template the site is built from and
+breaks the next `create-ailk` upgrade.
 
-Single confirm-before-write — no per-file or per-step prompts.
+## Step 1 — Read what this site can serve
 
-## When to use
+Run, from the site's root:
 
-The consumer wants a new page on their AILK site. Triggers:
-
-- "scaffold me a /pricing page" / "create a /contact route"
-- "add an about page" / "I need a /privacy page"
-- A structured triple: `home — Organization — anchor with hero, value prop, CTA`
-- "add that one" referring to a specific row from prior chat output
-
-Skip this skill when:
-
-- The consumer wants to **add supplementary schema to an existing
-  page** — that's the `schema:` frontmatter override (see
-  [Adding schema to an existing page](#adding-schema-to-an-existing-page)
-  below), not a separate skill. This skill refuses on existing routes
-  and points there.
-- The consumer's content backend is **not MDX**. v1 is MDX-only —
-  other adapters (Sanity, Payload, additional adapters) are additive
-  future PRs. Refuse with a clear message.
-
-## What this skill does
-
-1. Parses the consumer's input — structured triple
-   (`<slug> — <Schema.orgType> — <purpose>`) OR free-text.
-2. Resolves the **primary schema.org type** for the page using
-   `references/page-types.md` (about → AboutPage, pricing → Pricing,
-   etc.). Confirms the choice before writing.
-3. Detects existing routes and refuses if `app/<slug>/page.tsx`
-   already exists, pointing at the `schema:` frontmatter override.
-4. Detects content adapter — only MDX is supported at v1; refuses
-   on any other adapter with a clear message.
-5. Emits three files via `templates/route.tsx.tmpl` and
-   `templates/content.mdx.tmpl` (instantiated per page) plus a
-   typed builder import from `@working-theory/schema`.
-6. Shows the consumer a **single diff** of all three files and waits
-   for one confirmation. After approval, writes all files.
-7. Closing summary: pointer at the `schema:` frontmatter override for
-   additional schema, pointer at `check-site` for citation-readiness check.
-
-## What this skill does NOT do
-
-- Modify an existing route. Refuses + points at the `schema:`
-  frontmatter override.
-- Run `pnpm dev` or rebuild content. The consumer does that.
-- Detect content-adapter type beyond "is it MDX?". v1 ships MDX
-  only; other adapters are out of scope.
-- Use `<script type="application/ld+json">` blocks or
-  `generateMetadata.other`. The canonical attachment is always
-  `<JsonLd>` from `@working-theory/jsonld`.
-- Hand-code JSON-LD object literals. The typed builder from
-  `@working-theory/schema` is the source of truth (e.g. `buildOrganization(...)`,
-  `buildHomePage(...)`).
-
-## The mechanic
-
-### Step 1 — Parse the input
-
-The consumer's request can arrive in either shape:
-
-**Structured triple:**
-
-```
-home — Organization — anchor with hero, value prop, CTA
-about — AboutPage — company story and team
-pricing — Pricing — public price tiers and feature comparison
+```bash
+node .claude/skills/add-page/scripts/site-pages.mjs
 ```
 
-Three em-dash-separated fields: `<slug>` `<Schema.orgType>` `<purpose>`.
-
-**Free-text shape:**
-
-```
-"scaffold me a /pricing page"
-"add an about page"
-"create a /contact route for sales"
-```
-
-Both shapes resolve to the same internal triple: `(slug, type, purpose)`.
-
-For free-text:
-
-- Extract the slug from the URL-shaped fragment ("/pricing" → "pricing"; "an about page" → "about").
-- Resolve the `type` from `references/page-types.md` (the slug is the lookup key).
-- The `purpose` is whatever description the consumer gave — used as MDX `description` frontmatter.
-
-If you can't resolve a slug → type from the references file, **ask the consumer** rather than guessing. Don't fabricate types.
-
-### Step 2 — Detect MDX adapter
-
-Quick check: does the consumer's project have an MDX content
-backend?
-
-- Look for `content/` directory at the project root.
-- Look for `apps/web/source.config.ts` or `next.config.ts` that
-  references `@working-theory/content-adapters` MDX adapter.
-
-If neither exists, refuse:
-
-> "add-page only supports the MDX content backend at v1. Your
-> project doesn't appear to have one — file an issue at the upstream
-> repo if you'd like Sanity / Payload / additional adapter support."
-
-Stop. No writes.
-
-### Step 3 — Detect existing route
-
-Check for `apps/web/app/<slug>/page.tsx` (or `app/<slug>/page.tsx`
-depending on the consumer's structure).
-
-If it exists, refuse:
-
-> "A route at `/<slug>` already exists. To **add structured data** to
-> an existing page, use the `schema:` frontmatter override (see this
-> skill's [Adding schema to an existing page](#adding-schema-to-an-existing-page)
-> section) instead. To **replace** the page entirely, delete the
-> existing files first and re-run this skill."
-
-Stop. No writes.
-
-### Step 4 — Instantiate the templates
-
-Use `templates/route.tsx.tmpl` and `templates/content.mdx.tmpl` as
-sources. Substitute:
-
-| Placeholder       | Source                                             |
-| ----------------- | -------------------------------------------------- |
-| `{{SLUG}}`        | from Step 1 (e.g., `pricing`)                      |
-| `{{TYPE}}`        | from Step 1 (e.g., `Service`)                      |
-| `{{TYPE_KEBAB}}`  | type lowercased + kebab (e.g., `service`)          |
-| `{{TYPE_CAMEL}}`  | type camelCased for builder name (e.g., `service`) |
-| `{{BUILDER}}`     | builder function name (e.g., `buildService`)       |
-| `{{TITLE}}`       | derived from slug, title-cased (e.g., "Pricing")   |
-| `{{DESCRIPTION}}` | the `purpose` field from input                     |
-
-Builder name resolution: every type in `references/page-types.md`
-maps to a `build<Type>` export from `@working-theory/schema`. Verify the
-builder exists in the consumer's installed `@working-theory/schema` (check
-`node_modules/@working-theory/schema/dist/index.d.ts` or its README) before
-emitting the import. If the builder is missing, surface a clear
-"`@working-theory/schema` doesn't export `build<Type>` yet — file an issue
-upstream" message and stop.
-
-### Step 5 — Show the diff
-
-Present all three files (route + MDX + import path) in one
-combined diff message. Single confirmation question:
-
-> "I'll create:
->
-> - `app/<slug>/page.tsx` (App Router route, ~30 lines)
-> - `content/<Type>/<slug>.mdx` (content stub with frontmatter)
->
-> The route imports `<JsonLd>` from `@working-theory/jsonld` and `build<Type>` from
-> `@working-theory/schema`. JSON-LD is rendered server-side from the MDX
-> frontmatter via the typed builder.
->
-> Confirm to write all three files, or tell me what to change."
-
-Wait for the consumer's confirmation. Do not write per-step.
-
-### Step 6 — Write all three files
-
-After confirmation, write the route file and MDX stub atomically.
-The third "file" is the import line inside the route — already
-included in the route template.
-
-### Step 7 — Closing summary
-
-Print:
-
-- The two paths written.
-- Reminder: `pnpm dev` to see the page, `pnpm build` to confirm it
-  compiles.
-- Pointer at the `schema:` frontmatter override for adding
-  supplementary schema (FAQPage-shaped Q&A, a `Review`, a richer
-  `mainEntity`, etc.) to this page later.
-- Pointer at `check-site` for citation-readiness check after
-  adding pages.
-
-## Adding schema to an existing page
-
-There is no separate skill for this — a page's MDX frontmatter
-already carries an escape hatch. `page.schema` is a
-`Record<string, unknown>`, opaque to the typed builder, that the
-builder merges on top of its derived fields after deriving them
-(frontmatter wins on conflict). Use it to add structured sub-entities,
-enrich a page with additional fields, or override any derived field
-— without re-scaffolding the route.
+It prints the site's shape, design and level (from `.ailk-site-manifest.json`),
+then one row per page type this site renders: its route, whether it takes new
+pages (a route with a `[slug]` does; a fixed route like `/about` is one page),
+and the pages already written. Add `--json` if you want to parse it.
+
+Treat this output as the truth about the site. `references/page-types.md`
+lists every page type AI Launch Kit knows — the vocabulary — but many of them
+are not on this site. Never offer a page type the script doesn't list unless
+you are also going to add its route (Step 3, case D).
+
+Then read `.ailk-site-manifest.json` at the site root yourself, 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 already has (`route`) and the page type
+  each renders (`pageType`).
+- `level` — present only when the scaffold derived it from the licence key.
+  It never decides what to offer; `modules` does.
+
+A page type renders on this site only when the **Module** column of
+`references/page-types.md` names a module in that set. Never offer,
+suggest or write any other page type: a type whose Module the site lacks is
+case E, never case D.
+
+## Step 2 — Work out which page type the user wants
+
+The user may give a structured triple (`<slug> — <Type> — <purpose>`) or plain
+words. Resolve plain words to a type with `references/page-types.md`: an exact
+slug match first (`pricing` → `Pricing`), then a prefix (`services/…` →
+`Service`), then the purpose ("company story" → `AboutPage`). If two types
+fit, or none does, ask — a wrong type gives the page the wrong structured
+data, which is what search and answer engines read.
+
+Also settle the slug: lowercase, hyphenated, from the user's words
+(`kitchen-remodels`, not `kitchen_remodels` or `KitchenRemodels`).
+
+## Step 3 — Decide which case this is
+
+Check case C first: if the page the user describes already exists (the type is on a fixed route and its one page is in the "existing" column, or the slug is taken), stop there — nothing else in this skill applies.
+
+| Case | When | What you'll write |
+|---|---|---|
+| **A. New page on an existing route** | The type is listed and takes new pages (`Service`, `UseCase`, `PortfolioItem`, `BookCall`, `ThankYouPage`, …) | One content file: `content/en/<Type>/<slug>.mdx`. Plus a nav link if the page belongs in the nav. |
+| **B. Stand-alone landing page** | A one-off page at `/<slug>` that isn't any specific type (an offer, a campaign) | One content file: `content/en/LandingPage/<slug>.mdx`. The site's catch-all route serves it. |
+| **C. The page already exists** | A fixed-route type already has its page (`/about`, `/contact`, `/faq`), or `<slug>` is taken | Nothing. Say so. To change its words, use `fill-page`; to rename it or move its URL, use `update-page`. |
+| **D. The route isn't on this site** | The type exists in `page-types.md` but not in the script's output (e.g. `/pricing` on a person-service site) | First the route: `pnpm create ailk@latest add-route <route-id>` (run in the site root). `<route-id>` is the route family's name as `pnpm create ailk@latest --help` lists it under `--surfaces` — usually the first path segment (`pricing`, `alternatives`, `careers`). Then continue as case A (or case C for a fixed route — `add-route` seeds its page). |
+| **E. Needs a module the site doesn't have** | The type's **Module** in `page-types.md` is not in the site's modules (Step 1), or `add-route` refuses, naming a module (e.g. docs, blog, scheduling-backed booking) | Nothing yet. Tell the user which module renders it and which level carries it (the **Level** column), and point at the `upgrade-plan` skill. Don't try to recreate the module's routes by hand. |
+
+Why case B uses `LandingPage` rather than a new route: a route directory is
+template code the site inherits and upgrades; a content file is the owner's.
+Keeping one-off pages as content keeps upgrades clean.
+
+Comparison pages (`/vs/<competitor>`, listed on `/alternatives`) are case A on
+the `alternatives` route family, or case D when the site doesn't carry it yet
+(`add-route alternatives`). The `/alternatives` hub lists every comparison
+automatically — never hand-list them on the hub's page.
+
+Reports and flow landing pages are content on routes the **signal-collectors
+module** owns — see "Reports" and "Flow landing pages" below.
+
+## Step 4 — Draft the content file
+
+Copy the shape of a page the site already has **of the same type** — pick one
+from the "existing" column (e.g. `content/en/Service/first-engagement.mdx`).
+Its frontmatter is exactly what that type's route and structured-data builder
+expect, so matching it is how the new page renders and emits valid JSON-LD.
+Keep the same keys and section structure; replace the words.
+
+- Pick the page to copy with care: if the only page of this type is an odd one
+  (a hub slug, a stub), start from `templates/content.mdx.tmpl` instead and
+  borrow the section shapes from `content/en/HomePage/home.mdx`.
+- Set `slug` to the new slug and write a real `title` and `description` from
+  what the user said. `description` becomes the meta description and feeds the
+  structured data, so make it a true one-sentence summary.
+- Use the site's own name from `content/_site.mdx` wherever the page names
+  the business (a comparison's "us" side, a CTA) — don't leave `{Your Name}`
+  when the answer is on disk.
+- A time-limited offer carries its end date in structured data
+  (`schema: { offers: { validThrough: "2027-05-31" } }`) and says it in the
+  copy, so the page doesn't keep advertising an expired deal.
+- Where you don't have the owner's facts (prices, names, results), write
+  clearly-marked placeholder copy — never invent facts about their business.
+  Offer `fill-page` afterwards to write it properly.
+- If no page of this type exists yet, start from `templates/content.mdx.tmpl`
+  (or `templates/comparison-page.mdx.tmpl` for a comparison) and fill in the
+  `type` from `page-types.md`. Reports and flow landing pages have their own
+  templates — see their sections below.
+- Extra structured data (an `Offer`, a `Review`, an `author`) goes in the
+  frontmatter `schema:` block — see "Adding schema to a page" below. Don't
+  hand-write JSON-LD anywhere.
+
+## Step 5 — Link the page from its hub and the nav
+
+**The hub page.** Detail types sit under a list page: `Service` under
+`ServicesList` (`/services`), `UseCase` under `UseCasesList` (`/for`),
+`PortfolioItem` under `PortfolioList` (`/portfolio`). Open the hub's content
+file. If it lists its entries by hand (an `items` section with one entry per
+page, each with an `href`), add an entry for the new page in the same shape —
+otherwise visitors can't find it. The comparisons hub (`/alternatives`) and the
+reports hub (`/reports`) are the exceptions: they list their pages automatically.
+
+**The nav.**
+
+The site nav is `apps/web/lib/nav-config.ts`; its labels are keys in the
+`nav` section of `apps/web/messages/<locale>.json` (one file per language
+under `apps/web/messages/`).
+
+- A detail page under a list (a new service, a new persona) usually belongs in
+  that list's flyout or group in `nav-config.ts`. A stand-alone landing page
+  usually doesn't belong in the nav at all — ask if unsure. If it isn't in the
+  nav or a hub, tell the user how visitors will reach it (a link from the home
+  page, an email, an ad), because nothing on the site points to it yet.
+- Name a new `labelKey` after the page in camelCase (`kitchenRemodels`), not
+  after its position (`service4`), so it still makes sense after reordering.
+- A flyout may list the same links twice — once in `features` (the compact
+  view) and once in `groups` (the grouped view). Add the link to both.
+- To add a link: add an entry with the new `labelKey` and the locale-free path
+  (`/services/kitchen-remodels`, not `/en/…`), and add that key with its label
+  to **every** messages file (a site with one language has one file). A key
+  missing from one language breaks that language's nav.
+- Know the trade-off and tell the user once: `create-ailk` regenerates the nav
+  when a route or module is added, but only while `nav-config.ts` is exactly as
+  generated. Once hand-edited, later `add-route`/`add-module` runs leave it
+  alone and print the change they wanted instead.
+
+## Step 6 — Show the plan, confirm once, write
+
+Show every file you will create or change — the content file in full, and the
+exact lines added to the hub page, `nav-config.ts` and each messages file — plus any
+`add-route` command you'll run first. Wait for one confirmation. Then run the
+command (if any) and write the files. Don't write anything before the user
+confirms, and don't touch any other file.
+
+## Step 7 — Check it
+
+Run `pnpm build` from the site root. Then tell the user:
+
+- the new page's URL (with the locale, e.g. `/en/services/kitchen-remodels`)
+- that `fill-page` can write its real copy, and `check-site` can score it
+  for search and answer-engine readiness.
+
+If the build fails, the usual cause is frontmatter that doesn't match the
+type — compare the new file with the page you copied in Step 4.
+
+## Reports
+
+`ReportPage` (the `/reports/<slug>` report reader) is a hub-and-spoke family
+listed on the `/reports` hub (`ReportsList`). Its routes are
+**module-owned code** (the signal-collectors module's own
+`app/[locale]/reports/[slug]/page.tsx` and `app/[locale]/reports/page.tsx`),
+so this skill writes report **content only**, never report route code
+(spec 6892 D5).
+
+When the resolved type is `ReportPage` — a structured triple naming it, or
+free text like "add a report on Q3 results" — do this instead of Steps 3–4:
+
+1. Refuse when `app/[locale]/reports/[slug]/page.tsx` is absent, naming the
+   `signal-collectors` module: "This site has no report reader yet — run
+   `create-ailk add-module signal-collectors` first."
+2. Write `content/en/ReportPage/<slug>.mdx` from
+   `templates/report-page.mdx.tmpl` (substituting `{{SLUG}}`, `{{TITLE}}`,
+   `{{DESCRIPTION}}`, `{{DATE_PUBLISHED}}` — an ISO date — and
+   `{{DATE_LABEL}}` — the display string, e.g. "March 2025"). Refuse only
+   when that file already exists.
+3. When `content/en/ReportsList/reports.mdx` is absent, write it from
+   `templates/reports-list.mdx.tmpl` (substituting `{{TITLE}}`/`{{DESCRIPTION}}`
+   for the hub's own copy).
+
+The hub's own card list is **generated at request time** from whichever
+`ReportPage` seeds exist (`app/[locale]/reports/page.tsx` injects them) —
+never hand-list reports on the hub's MDX. Steps 5–7 apply as usual.
+
+## Flow landing pages
+
+A flow landing page is a single, standalone `LandingPage` whose CTA opens a
+named flow at `/flows/<slug>/start` — the referral-request shape (spec 6892
+D3). It belongs to no hub, but like the report family its route is
+**module-owned code** (the signal-collectors module's own
+`app/[locale]/flows/[slug]/start/page.tsx`), so this skill writes content
+only.
+
+When the consumer asks for a flow landing page — "add a referral page",
+"add a landing page for the intake flow" — given a flow slug:
+
+1. Refuse when `app/[locale]/flows/[slug]/start/page.tsx` is absent, naming
+   the `signal-collectors` module: "This site has no flow engine yet — run
+   `create-ailk add-module signal-collectors` first."
+2. Refuse when `content/en/LandingPage/<slug>.mdx` already exists — this
+   is a single standalone page, not a family member with its own detail
+   route.
+3. Write `content/en/LandingPage/<slug>.mdx` from
+   `templates/flow-landing-page.mdx.tmpl`, substituting `{{SLUG}}`,
+   `{{TITLE}}`, `{{DESCRIPTION}}` as usual and `{{FLOW_SLUG}}` — the flow's
+   own slug, which may differ from the page's `{{SLUG}}`.
+
+This skill writes no flow definition (`database/flows/<slug>.flow.json`) —
+that is a separate artifact, seeded through the flow engine, not through a
+page.
+
+## Adding schema to a page
+
+Every page's frontmatter has an escape hatch, `schema:`, that the page's
+structured-data builder merges on top of what it derives (frontmatter wins).
+Use it to add sub-entities or enrich fields, on a new page or an existing one:
 
 ```yaml
-# in an existing page's MDX frontmatter
 ---
-type: BlogPosting
-slug: hello-world
-title: Hello, World
-description: First post.
+type: Service
+slug: kitchen-remodels
+title: Kitchen remodels
+description: Full kitchen remodels, from design to final inspection.
 schema:
-  author:
-    "@type": Person
-    name: Jane Doe
+  offers:
+    "@type": Offer
+    priceCurrency: USD
+    price: "15000"
 ---
 ```
 
-Where an override key lands depends on the builder's shape — a
-two-layer builder (a `WebPage`-family envelope wrapping a described
-`mainEntity`, e.g. `BlogPosting`, `Service`, `Product`, `JobPosting`)
-routes most keys to the entity and a known few to the envelope; every
-other builder shallow-merges `page.schema` onto the top level. The
-full routing table is `packages/schema/README.md` § `schema` field
-override — read it before guiding a consumer through a non-obvious
-placement (e.g. `mainEntity` object merges, `@type` retyping).
-
-This is also how a page picks up a **supplementary** schema type that
-has no builder of its own — an `Offer`, a `Review`, an `AggregateRating`
-— since those are expressed as plain objects inside `schema:`, not as
-a distinct AILK page type.
-
-## What lives in `references/page-types.md`
-
-The type-to-schema mapping is data, not logic. Read the references
-file at runtime — don't try to remember the table. It is generated
-from `packages/schema/src/registry/entries.ts` by
-`packages/create-ailk/scripts/generate-page-types-reference.ts` —
-never hand-edit it; regenerate it instead (`pnpm page-types:build` from
-`packages/create-ailk`) whenever a registry key changes.
-
-The mapping covers every registered AILK page type — family, chassis,
-schema.org `@type`, and the route convention — with list/detail pairs
-(e.g. `ServicesList` / `Service`) shown together.
-
-## Coordination
-
-- **`check-site`** — citation-readiness check. Runs after
-  pages exist; not invoked from inside this skill.
-- **`@working-theory/jsonld`** — the React component for JSON-LD
-  rendering. Single source of truth for the attachment pattern.
-- **`@working-theory/schema`** — typed builders (`buildHomePage`,
-  `buildAboutPage`, etc.). The skill's emit imports from here, and its
-  README documents the `schema` frontmatter override in full.
-- **`@working-theory/content-adapters`** (MDX) — the content backend. v1 is
-  MDX-only; other adapters are deferred.
+On types that wrap a described entity in a page (`Service`, `Product`,
+`BlogPosting`, `JobPosting`), most keys land on the entity; on others they
+merge at the top level. This is also how a page gets a supplementary type
+with no page type of its own — `Offer`, `Review`, `AggregateRating`.
+
+## What this skill does not do
+
+- Write or copy route code by hand — `create-ailk add-route` does that.
+- Change an existing page's words (`fill-page`), name or URL (`update-page`).
+- Add a module or change the site's level (`upgrade-plan` explains; the
+  owner decides).
+- Edit `_site.mdx`, the design, or another page's content.