create-ailk 0.1.0

package/templates/.claude/skills/scaffold-commerce/templates/marketplace-cta-route.tsx.tmpl

@@ -0,0 +1,72 @@
+// Emitted by `scaffold-commerce` (link path). Owns its own
+// <MarketplaceCTA> component definition — not imported from
+// @working-theory/ui — so you can edit the styling, add tracking, change
+// the icon layout, etc., without forking a shared package.
+//
+// The skill substitutes:
+//   {{HREF}}   — storefront URL (e.g., https://amazon.com/my-shop)
+//   {{LABEL}}  — button text (e.g., "Buy on Amazon")
+//   {{ICON}}   — optional iconSrc prop binding (e.g., iconSrc="/logos/amazon.svg")
+//                or empty when the consumer chose text-only
+
+import type { ReactNode } from "react";
+
+interface MarketplaceCTAProps {
+  href: string;
+  label: ReactNode;
+  iconSrc?: string;
+  className?: string;
+}
+
+/**
+ * MarketplaceCTA — outbound link to an external storefront.
+ *
+ * Renders a single anchor styled as a button. Optional iconSrc renders
+ * a small <img> next to the label; omitting it produces a clean
+ * text-only button. Customize freely — this component is yours, not
+ * a shared dep.
+ */
+function MarketplaceCTA({
+  href,
+  label,
+  iconSrc,
+  className,
+}: MarketplaceCTAProps) {
+  const baseClasses =
+    "inline-flex items-center gap-2 rounded-md border border-current px-4 py-2 text-sm font-medium hover:bg-current/5 transition-colors";
+  const finalClassName = className
+    ? `${baseClasses} ${className}`
+    : baseClasses;
+
+  return (
+    <a
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      className={finalClassName}
+    >
+      {iconSrc ? (
+        <img src={iconSrc} alt="" aria-hidden="true" className="h-5 w-5" />
+      ) : null}
+      <span>{label}</span>
+    </a>
+  );
+}
+
+export default function BuyPage() {
+  return (
+    <main className="mx-auto max-w-2xl px-6 py-12">
+      <h1 className="text-3xl font-semibold">Get yours</h1>
+      <p className="mt-3 text-muted-foreground">
+        Available at our store on the marketplace below.
+      </p>
+      <div className="mt-8">
+        <MarketplaceCTA
+          href="{{HREF}}"
+          label="{{LABEL}}"
+          {{ICON}}
+        />
+      </div>
+    </main>
+  );
+}

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

@@ -0,0 +1,243 @@
+---
+name: scaffold-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 chains a row from `suggest-site-pages` output (e.g., "scaffold 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 `add-schema` (#366).
+---
+
+# scaffold-page
+
+Generate a new page in one pass. Three artifacts emit together:
+
+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)
+
+Single confirm-before-write — no per-file or per-step prompts.
+
+## When to use
+
+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 row chained from `suggest-site-pages` output:
+  `home — Organization — anchor with hero, value prop, CTA`
+- "scaffold that one" referring to a specific row from prior chat output
+
+Skip this skill when:
+
+- The consumer wants to **add schema to an existing page** — that's
+  `add-schema` (#366). This skill refuses on existing routes and
+  points at #366 explicitly.
+- The consumer wants to **plan their pages** — that's
+  `suggest-site-pages` (#361). Output of #361 is this skill's chained
+  input contract.
+- 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 — chained format
+   (`<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 → Service,
+   etc.). Confirms the choice before writing.
+3. Detects existing routes and refuses if `app/<slug>/page.tsx`
+   already exists, pointing at `add-schema` (#366).
+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 `add-schema` (#366) for additional
+   schema, pointer at `audit-site` (#365) for citation-readiness check.
+
+## What this skill does NOT do
+
+- Modify an existing route. Refuses + points at `add-schema` (#366).
+- 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:
+
+**Chained shape** (from `suggest-site-pages` output):
+
+```
+home — Organization — anchor with hero, value prop, CTA
+about — AboutPage — company story and team
+pricing — Service — public price tiers and feature comparison
+```
+
+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:
+
+> "scaffold-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 schema** to an
+> existing page, run `add-schema` (#366) 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 `add-schema` (#366) for adding supplementary schema
+  (FAQPage, HowTo, Product, etc.) to this page later.
+- Pointer at `audit-site` (#365) for citation-readiness check after
+  adding pages.
+
+## Cross-skill chaining
+
+Output of `suggest-site-pages` (#361) is this skill's input contract.
+The consumer can paste any row of #361's output verbatim and this
+skill scaffolds it. Example end-to-end:
+
+1. Consumer asks `suggest-site-pages` for a SaaS page list.
+2. Output includes: `pricing — Service — public price tiers and feature comparison`
+3. Consumer says: "scaffold that pricing one"
+4. This skill resolves the row, emits route + MDX + JSON-LD, all in
+   one confirm-before-write pass.
+5. Consumer continues with the next row, or moves on.
+
+## 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.
+
+The mapping covers the canonical AILK page types:
+
+- Identity — `home → HomePage`, `about → AboutPage`
+- Conversion — `pricing → Service`, `contact → ContactPage`
+- Trust — `privacy → PrivacyPage`, `terms → TermsPage`
+- Editorial — `blog → Blog`, `blog/<slug> → BlogPosting`
+- Catalog — `products → ItemList`, `products/<slug> → Product`
+- Q&A — `faq → FAQPage`, `how-to/<slug> → HowTo`
+
+The full list is in `references/page-types.md`. New types added to
+`@working-theory/schema` should be added to that file in a follow-up PR; the
+skill renders unrecognized types as a "missing from page-types.md"
+prompt to ask the consumer rather than guessing.
+
+## Coordination
+
+- **`suggest-site-pages` (#361)** — output is this skill's chained
+  input. The two skills' references corpora (`categories.md` and
+  `page-types.md`) must agree on schema-type names.
+- **`add-schema` (#366)** — modifies existing pages. The
+  `<JsonLd schema={build<Type>(...)} />` attachment pattern is
+  shared with this skill (canonical pattern landed in #389 /
+  `@working-theory/jsonld`).
+- **`audit-site` (#365)** — citation-readiness check. Runs after
+  pages exist; not invoked from inside this skill.
+- **`@working-theory/jsonld`** (#389) — 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.
+- **`@working-theory/content-adapters`** (MDX) — the content backend. v1 is
+  MDX-only; other adapters are deferred.

package/templates/.claude/skills/scaffold-page/references/page-types.md

@@ -0,0 +1,169 @@
+# Page-Type → schema.org Mapping
+
+The lookup table the `scaffold-page` skill reads at runtime to
+resolve a slug or page-purpose hint to a primary schema.org `@type`
+plus the matching `@working-theory/schema` builder name.
+
+The skill resolves in this order:
+
+1. **Exact slug match** — `pricing` → `Service`.
+2. **Slug-prefix match** — `blog/<anything>` → `BlogPosting`.
+3. **Free-text hint match** — "company story" / "team" → `AboutPage`.
+4. **Ask** — if nothing matches, ask the consumer rather than
+   guessing.
+
+This file's table must agree with the entries
+`suggest-site-pages` (#361) emits in `categories.md`. When new types
+land in `@working-theory/schema`, both files update in the same follow-up PR.
+
+## Identity / surface pages
+
+| Slug    | Primary `@type` | Builder          | When to pick                                                          |
+| ------- | --------------- | ---------------- | --------------------------------------------------------------------- |
+| `home`  | `HomePage`      | `buildHomePage`  | The site's root landing page. Anchors hero, value prop, primary CTAs. |
+| `about` | `AboutPage`     | `buildAboutPage` | Company story / team / founders. Trust + narrative.                   |
+
+## Conversion pages
+
+| Slug      | Primary `@type` | Builder            | When to pick                                                                                                                       |
+| --------- | --------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `pricing` | `Service`       | `buildService`     | Public price tiers and feature comparison. (Or `Product` if the consumer sells discrete physical/digital products with SKUs.)      |
+| `contact` | `ContactPage`   | `buildContactPage` | Sales / support entry point. Form, address, hours.                                                                                 |
+| `book`    | `Reservation`   | _consumer-defined_ | Service businesses with appointment booking (salon, contractor, restaurant table). Requires consumer to wire the reservation flow. |
+
+## Trust pages
+
+| Slug      | Primary `@type` | Builder            | When to pick      |
+| --------- | --------------- | ------------------ | ----------------- |
+| `privacy` | `PrivacyPage`   | `buildPrivacyPage` | Privacy policy.   |
+| `terms`   | `TermsPage`     | `buildTermsPage`   | Terms of service. |
+
+## Editorial / blog
+
+| Slug          | Primary `@type` | Builder            | When to pick                                                                                                        |
+| ------------- | --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `blog`        | `Blog`          | _consumer-defined_ | Blog index page. Lists posts.                                                                                       |
+| `blog/<slug>` | `BlogPosting`   | _consumer-defined_ | Individual blog post. The skill's chained input handles the per-post case naturally — ask `scaffold-page` per post. |
+
+> Builder availability for editorial types depends on `@working-theory/schema`
+> exports at the consumer's installed version. If
+> `buildBlogPosting` is missing, fall back to manually authoring
+> the JSON-LD via `<JsonLd schema={{...}} />`.
+
+## Catalog / commerce
+
+| Slug              | Primary `@type` | Builder            | When to pick                                          |
+| ----------------- | --------------- | ------------------ | ----------------------------------------------------- |
+| `products`        | `ItemList`      | _consumer-defined_ | Product index. Lists products.                        |
+| `products/<slug>` | `Product`       | _consumer-defined_ | Individual product page.                              |
+| `services`        | `ServicesList`  | _consumer-defined_ | Service index for service-business consumer profiles. |
+| `services/<slug>` | `Service`       | `buildService`     | Individual service page.                              |
+
+> For commerce wiring (Stripe products + lookup_keys), use
+> `scaffold-commerce` (#363). This skill emits the page; commerce
+> wires it.
+
+## Q&A / how-to
+
+| Slug            | Primary `@type` | Builder            | When to pick                     |
+| --------------- | --------------- | ------------------ | -------------------------------- |
+| `faq`           | `FAQPage`       | _consumer-defined_ | Frequently-asked-questions page. |
+| `how-to/<slug>` | `HowTo`         | _consumer-defined_ | Step-by-step instructions page.  |
+
+## Real estate / listings
+
+| Slug              | Primary `@type`     | Builder            | When to pick                  |
+| ----------------- | ------------------- | ------------------ | ----------------------------- |
+| `listings`        | `ItemList`          | _consumer-defined_ | Property index.               |
+| `listings/<slug>` | `RealEstateListing` | _consumer-defined_ | Individual listing.           |
+| `agent`           | `RealEstateAgent`   | _consumer-defined_ | Solo realtor / agent profile. |
+
+## Healthcare / medical
+
+| Slug              | Primary `@type`                | Builder            | When to pick                                      |
+| ----------------- | ------------------------------ | ------------------ | ------------------------------------------------- |
+| `practice`        | `MedicalBusiness`              | _consumer-defined_ | Practice / clinic landing.                        |
+| `provider`        | `Physician` / `Dentist` / etc. | _consumer-defined_ | Solo provider profile. Type depends on specialty. |
+| `services/<slug>` | `MedicalProcedure`             | _consumer-defined_ | Procedure / treatment page.                       |
+
+## Course / education
+
+| Slug             | Primary `@type`    | Builder            | When to pick          |
+| ---------------- | ------------------ | ------------------ | --------------------- |
+| `courses`        | `ItemList`         | _consumer-defined_ | Course catalog.       |
+| `courses/<slug>` | `Course`           | _consumer-defined_ | Individual course.    |
+| `lesson/<slug>`  | `LearningResource` | _consumer-defined_ | Free / sample lesson. |
+
+## Nonprofit / org
+
+| Slug              | Primary `@type` | Builder            | When to pick                     |
+| ----------------- | --------------- | ------------------ | -------------------------------- |
+| `mission`         | `AboutPage`     | `buildAboutPage`   | Mission statement / what we do.  |
+| `donate`          | `DonateAction`  | _consumer-defined_ | Donation page.                   |
+| `programs/<slug>` | `Program`       | _consumer-defined_ | Individual program / initiative. |
+
+## Identity entity (Organization vs Person)
+
+The site's **identity entity** is emitted on `home` (or in a layout
+component). Two flavors:
+
+| Site profile       | Identity `@type` | Builder             |
+| ------------------ | ---------------- | ------------------- |
+| Business / company | `Organization`   | `buildOrganization` |
+| Solo individual    | `Person`         | `buildPerson`       |
+
+For categories that admit both (real estate, healthcare,
+professional services, course/education), `suggest-site-pages`
+(#361) disambiguates Person vs Organization based on the consumer's
+free-text. This skill receives the resolved type as part of the
+chained input or asks if free-text is ambiguous.
+
+## When a slug doesn't match anything above
+
+Don't guess. Ask the consumer:
+
+> "I don't have a default schema.org type mapped for `/<slug>`. Two
+> options:
+>
+> - Tell me which schema.org `@type` to use (e.g., `WebPage`,
+>   `Article`, `Event`).
+> - Skip JSON-LD on this page; I emit a vanilla route + MDX stub
+>   and you wire schema later via `add-schema` (#366).
+>
+> Which?"
+
+## Generic fallbacks
+
+For pages that don't match a specific category, two safe fallbacks:
+
+- `WebPage` — the most generic schema.org `@type`. Always valid, low
+  citation value.
+- `Article` — for editorial / longform content that isn't a blog
+  post specifically.
+
+The `WebPage` fallback is the implicit default if the consumer
+explicitly says "no schema" — emit the route + MDX without an
+emitted `<JsonLd>` block; consumer can add later via #366.
+
+## When `@working-theory/schema` doesn't yet export the builder
+
+Some types in this table say `_consumer-defined_` for the builder
+column. That means `@working-theory/schema` doesn't export a typed builder
+for that type yet. The skill's behavior:
+
+1. Surface the gap to the consumer:
+
+   > "`@working-theory/schema` doesn't export `build<Type>` yet. I can:
+   >
+   > - Emit the route with an inline JSON-LD object literal (less
+   >   type-safe but works).
+   > - Skip JSON-LD on this page; you wire it via `add-schema`
+   >   (#366) once the builder ships upstream.
+   > - File an upstream issue requesting the builder.
+   >
+   > Which?"
+
+2. Wait for the consumer's choice. Don't fabricate a builder.
+
+The fallback to inline literals is documented in `add-schema`
+(#366) too — both skills handle this case the same way.

package/templates/.claude/skills/scaffold-page/templates/content.mdx.tmpl

@@ -0,0 +1,28 @@
+---
+type: {{TYPE}}
+slug: {{SLUG}}
+title: {{TITLE}}
+description: {{DESCRIPTION}}
+---
+
+# {{TITLE}}
+
+{{DESCRIPTION}}
+
+<!--
+  This is the MDX content stub emitted by `scaffold-page`.
+  The frontmatter is the source of truth for JSON-LD — the
+  `{{BUILDER}}(page)` call in `app/{{SLUG}}/page.tsx` reads it.
+
+  Edit this file freely:
+   - Add sections, prose, components imported from your project.
+   - Update `description` (it's used both as the meta description
+     and as input to the JSON-LD builder).
+   - Don't change `type` unless you also update the route's import
+     to match a different `@working-theory/schema` builder.
+
+  When you're happy with the page, run `audit-site` (#365) to see
+  how it scores on citation-readiness. Use `add-schema` (#366) to
+  add supplementary schema (FAQPage, HowTo, etc.) without
+  re-scaffolding.
+-->

package/templates/.claude/skills/scaffold-page/templates/route.tsx.tmpl

@@ -0,0 +1,28 @@
+// Emitted by `scaffold-page` at `app/{{SLUG}}/page.tsx`. Substitutions:
+//   {{SLUG}}     — page slug (e.g., "pricing")
+//   {{TYPE}}     — schema.org @type (e.g., "Service")
+//   {{BUILDER}}  — typed builder name (e.g., "buildService")
+//   {{TITLE}}    — page title (e.g., "Pricing")
+import { notFound } from "next/navigation";
+
+import { JsonLd } from "@working-theory/jsonld";
+import { {{BUILDER}} } from "@working-theory/schema";
+import { mdxAdapter } from "@/lib/content";
+
+export default async function {{TYPE}}Page() {
+  const page = await mdxAdapter.getPage("{{SLUG}}");
+  if (!page) return notFound();
+
+  const schema = {{BUILDER}}(page);
+
+  return (
+    <main className="mx-auto max-w-3xl px-6 py-12">
+      <JsonLd schema={schema} />
+      <article className="prose dark:prose-invert">
+        <h1>{page.title}</h1>
+        {page.description ? <p className="lead">{page.description}</p> : null}
+        {/* Render MDX body via your project's MDX renderer of choice. */}
+      </article>
+    </main>
+  );
+}