create-ailk 0.6.1 → 0.7.0

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

@@ -1,169 +0,0 @@
-# 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/suggest-site-pages/SKILL.md

@@ -1,242 +0,0 @@
----
-name: suggest-site-pages
-description: Recommend a starter set of website pages — each tagged with the schema.org type to use — from a free-text business description. Use when the user is opening a new AI Launch Kit project, asks "what pages should this site have?", "help me plan my pages", "what should I build first" for a website, or describes a business in plain language and wants a page plan back. The output is shaped so each line can be passed straight to the `scaffold-page` skill.
----
-
-# suggest-site-pages
-
-Turn a free-text business description into an ordered list of pages, with the
-right schema.org type per page, that the user can build with `scaffold-page`.
-
-## When to use
-
-The user is in a fresh `pnpm create ailk` project (or any AI Launch Kit
-project that has no pages yet) and needs a plan for what to build. They
-describe their business — "I'm building a SaaS for accountants", "I'm
-opening a pizza restaurant", "I'm launching my law firm" — and want a
-page list back, not a generic site-builder questionnaire.
-
-Skip this skill when:
-
-- The user already has a page list and just wants one more page added
-  (use `scaffold-page` directly).
-- The user is asking about page _content_, not page _structure_ (answer
-  conversationally; this skill is about which pages exist, not what
-  goes inside them).
-- The user wants schema added to an _existing_ page (use `add-schema`).
-
-## What you produce
-
-An ordered list, one line per page, in this exact format:
-
-```
-<slug> — <Schema.orgType> — <one-sentence purpose>
-```
-
-Example for a SaaS for accountants:
-
-```
-home — HomePage — top-of-funnel landing with the headline value prop
-about — AboutPage — company story and team
-pricing — Product — public price tiers and feature comparison
-features — ServicesList — what the product does, broken into capabilities
-contact — ContactPage — sales and support entry point
-privacy — PrivacyPage — privacy policy
-terms — TermsPage — terms of service
-```
-
-Each line is a copy-paste plan: the user (or you, on their next turn)
-can hand any line to `scaffold-page` and the chain works because the
-schema type is the input contract `scaffold-page` expects.
-
-## The mechanic
-
-### Step 1 — Identify the category
-
-Match the user's description to one of the **10 v1 categories**:
-
-1. SaaS
-2. E-commerce
-3. Service business (restaurant / salon / contractor / gym)
-4. Professional services (law / accounting / consulting / agency)
-5. Marketplace
-6. Content / Blog
-7. Course / Education
-8. Real estate
-9. Healthcare / Medical
-10. Nonprofit / Org
-
-The full corpus — each category's entity tag, page list, and schemas —
-lives in `references/categories.md`. **Read that file** before producing
-the page list. Don't try to remember it.
-
-If the description doesn't match any of the 10, do **not** invent a
-category. Say:
-
-> "That's not in the v1 catalog. The closest matches are **\<X\>** and
-> **\<Y\>**. Would you like to use one of those, or describe your business
-> differently?"
-
-The two closest matches come from `references/categories.md` — pick
-whichever categories share the most surface area with the user's
-description (e.g., "research consortium" → Professional services and
-Nonprofit / Org).
-
-### Step 2 — Disambiguate Person vs Organization (when needed)
-
-Each category in `references/categories.md` carries an **entity tag**:
-`organization`, `person`, or `both`. The tag drives the next step.
-
-- **`organization`** — skip the question. Marketplaces are always
-  organizations, SaaS is always an organization. Proceed to Step 3.
-- **`person`** — skip the question. A "personal poetry blog" is always
-  a Person. Proceed to Step 3.
-- **`both`** — the consumer could be either. This is where the
-  disambiguation matters: a solo lawyer's home page anchors on `Person`,
-  a law firm's anchors on `Organization`, and the page recommendations
-  shift accordingly.
-
-For `both`-tagged categories, first check whether the user's free-text
-**already settles it**. Phrases like:
-
-- "my brokerage", "our firm", "the company", "we're a clinic" → Organization
-- "I'm a solo \<role\>", "as an independent \<role\>", "my personal", "I'm a freelance" → Person
-
-If the description settles it, **infer and confirm** rather than ask blind:
-
-> "Got it — sounds like you're operating as an individual. I'll plan
-> the pages around a Person identity. Does that match?"
-
-If it's genuinely ambiguous, **ask once**:
-
-> "Are you operating as an individual practitioner or as a business
-> entity (firm / company / organization)? It changes which schemas
-> anchor your home, about, and contact pages."
-
-Then proceed to Step 3 with the answer.
-
-### Step 3 — Emit the page list
-
-Look up the category in `references/categories.md`. Use:
-
-- The **page list** for that category, in the listed order.
-- The **primary schema.org type** for each page, adjusted for the
-  Person-vs-Organization choice from Step 2 where the corpus calls it
-  out (typically the home, about, and contact pages).
-
-Format every line as `<slug> — <Schema.orgType> — <one-sentence purpose>`.
-The slugs come from the corpus; don't invent new ones. The one-sentence
-purpose can be lifted from the corpus or rephrased — keep it short.
-
-After the list, add one line:
-
-> "Pass any of these to `scaffold-page` to generate the page."
-
-## Person vs Organization — how it actually maps
-
-The Person/Organization choice cascades into the **identity attached to
-the page**, not into a different per-page type. `HomePage`, `AboutPage`,
-and `ContactPage` are entity-agnostic; only the `Organization` vs
-`Person` identity inside the JSON-LD changes.
-
-`@working-theory/schema` does **not** ship narrower types like `Attorney`,
-`Physician`, `RealEstateAgent`, `LegalService`, `MedicalBusiness`, or
-`EducationalOrganization` at v1. If the user mentions a category whose
-"natural" schema is one of those, fall back to the closest type from
-the supported catalog — typically `ServicesList` / `Service` for
-service-shaped categories. The corpus already does this for you.
-
-## Invocation contract
-
-This skill is **conversational only**. It is not a CLI command, not an
-MCP tool. The user invokes it by talking to Claude in plain language.
-
-## The `references/` convention
-
-This skill establishes a pattern: **`SKILL.md` holds the mechanic; the
-knowledge corpus lives in `references/<corpus>.md`**.
-
-- `SKILL.md` describes how to invoke the skill, the steps to run, the
-  output format, and pointers into the corpus. It stays short — under
-  500 lines is the budget — so the whole skill is auditable in under
-  ten minutes.
-- `references/<corpus>.md` holds the data the skill operates on. For
-  this skill, that's `references/categories.md`: 10 categories, each
-  with entity tag, page list, and primary schema per page. Editing the
-  corpus is a single-file change; the mechanic stays untouched.
-
-Other OSS skills that need a knowledge corpus (`add-schema` for
-primary/supplementary tagging, `provision-config` for persistence
-options) should adopt the same shape.
-
-## Worked examples
-
-**Example 1 — SaaS (unambiguous Organization)**
-
-User: "I'm building a SaaS for dental practices to manage appointments."
-
-You:
-
-1. Category → SaaS
-2. Entity tag → `organization`. No question.
-3. Read `references/categories.md` § SaaS, emit:
-
-```
-home — HomePage — top-of-funnel landing with the headline value prop
-about — AboutPage — company story and team
-pricing — Product — public price tiers and feature comparison
-features — ServicesList — what the product does, broken into capabilities
-contact — ContactPage — sales and support entry point
-privacy — PrivacyPage — privacy policy
-terms — TermsPage — terms of service
-
-Pass any of these to scaffold-page to generate the page.
-```
-
-**Example 2 — Law firm (ambiguous, asks)**
-
-User: "What pages should I have for my law firm?"
-
-You: "Are you operating as an individual lawyer or as a law firm
-entity? It changes which schemas anchor your home, about, and contact
-pages."
-
-User: "It's a firm with five attorneys."
-
-You: read `references/categories.md` § Professional services, render
-the list with `Organization` as the home/about/contact identity.
-
-**Example 3 — Real estate (free-text settles it)**
-
-User: "What pages should I have for a real estate brokerage?"
-
-You: "Got it — 'brokerage' tells me you're operating as an organization,
-not a solo agent. I'll plan around an Organization identity. Does that
-match?" Then proceed.
-
-**Example 4 — Personal blog (unambiguous Person)**
-
-User: "What pages should I have for my personal poetry blog?"
-
-You:
-
-1. Category → Content / Blog
-2. Entity tag → `person` (the corpus tags personal blogs as Person). No
-   question.
-3. Render the blog page list with `Person` as the home/about identity.
-
-**Example 5 — Out of catalog**
-
-User: "What pages should I have for a quantum-computing research
-consortium?"
-
-You: "That's not in the v1 catalog. The closest matches are
-**Professional services** and **Nonprofit / Org**. Would you like to use
-one of those, or describe your business differently?"
-
-## When the user pushes back
-
-The corpus is opinionated, not authoritative. If the user disputes a
-schema choice, explain why the corpus tagged it that way, then offer
-to override — `scaffold-page` accepts any type from the supported
-catalog. Don't argue.