create-ailk 0.1.0

package/templates/.claude/skills/suggest-site-pages/SKILL.md

@@ -0,0 +1,242 @@
+---
+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.

package/templates/.claude/skills/suggest-site-pages/references/categories.md

@@ -0,0 +1,287 @@
+# Site-page categories — v1 corpus
+
+The 10 business categories `suggest-site-pages` knows about, with the
+ordered page list and primary schema.org type for each page. Schemas
+are drawn from the 45 types `@working-theory/schema` builds; nothing in this
+file should reference a type the package can't generate.
+
+## How to read this file
+
+Each category section has:
+
+1. **Name and description** — what the category covers.
+2. **Entity tag** — `organization`, `person`, or `both`. Drives whether
+   `suggest-site-pages` asks the Person-vs-Organization disambiguation
+   question.
+3. **Page list** — ordered. The slug is what `scaffold-page` will use.
+4. **Primary schema per page** — the `Schema.orgType` to emit.
+
+When the entity tag is `both`, some pages (typically home, about,
+contact) carry an identity that flips between `Organization` and
+`Person` based on the consumer's answer. The page's _own_ schema type
+(`HomePage`, `AboutPage`, `ContactPage`) does not change; only the
+identity attached inside the JSON-LD does.
+
+---
+
+## SaaS
+
+Software-as-a-service products — anything where the value prop is
+"sign up and use the software." Includes vertical SaaS, horizontal
+tools, dev platforms, and self-serve B2B.
+
+- **Entity tag:** `organization`
+- **Pages:**
+
+| Slug       | Schema.orgType | Purpose                                            |
+| ---------- | -------------- | -------------------------------------------------- |
+| `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                                   |
+
+---
+
+## E-commerce
+
+Direct-to-consumer or B2B storefronts selling physical or digital
+goods. The catalog is the primary surface; everything else supports it.
+
+- **Entity tag:** `organization`
+- **Pages:**
+
+| Slug      | Schema.orgType | Purpose                                     |
+| --------- | -------------- | ------------------------------------------- |
+| `home`    | `HomePage`     | featured products and category entry points |
+| `shop`    | `ProductsList` | the full catalog                            |
+| `about`   | `AboutPage`    | brand story and what the company makes      |
+| `contact` | `ContactPage`  | customer-service entry point                |
+| `faq`     | `FAQPage`      | shipping, returns, sizing, common questions |
+| `privacy` | `PrivacyPage`  | privacy policy                              |
+| `terms`   | `TermsPage`    | terms of service                            |
+
+Per-product pages use `Product` and live under `shop/<product-slug>`.
+`scaffold-page` handles them one at a time once the user has the
+catalog page.
+
+---
+
+## Service business
+
+Restaurant, salon, contractor, gym, plumber, cleaner — anyone whose
+business is "show up and do the work." Owner is usually an entity
+(LLC / corp), occasionally a sole proprietor.
+
+- **Entity tag:** `both`
+- **Pages:**
+
+| Slug           | Schema.orgType     | Purpose                                             |
+| -------------- | ------------------ | --------------------------------------------------- |
+| `home`         | `HomePage`         | what the business does, where, and how to book      |
+| `services`     | `ServicesList`     | menu of services offered                            |
+| `about`        | `AboutPage`        | the operator's story and credentials                |
+| `contact`      | `ContactPage`      | hours, address, booking link                        |
+| `testimonials` | `TestimonialsList` | customer reviews and quotes                         |
+| `faq`          | `FAQPage`          | common questions about service, pricing, scheduling |
+| `privacy`      | `PrivacyPage`      | privacy policy                                      |
+| `terms`        | `TermsPage`        | terms of service                                    |
+
+Individual services go under `services/<service-slug>` with `Service`
+as the type. The home/about/contact pages anchor on `Organization` for
+a business entity, `Person` for a sole proprietor.
+
+---
+
+## Professional services
+
+Law firms, accounting firms, consulting shops, marketing agencies — fee-for-engagement
+expertise. Almost always firm-shaped at scale, but plenty of solo practitioners.
+
+- **Entity tag:** `both`
+- **Pages:**
+
+| Slug           | Schema.orgType    | Purpose                                           |
+| -------------- | ----------------- | ------------------------------------------------- |
+| `home`         | `HomePage`        | who the firm serves and what kinds of engagements |
+| `services`     | `ServicesList`    | practice areas or service lines                   |
+| `team`         | `TeamList`        | the people clients will work with                 |
+| `case-studies` | `CaseStudiesList` | engagement outcomes and references                |
+| `about`        | `AboutPage`       | firm history, philosophy, credentials             |
+| `contact`      | `ContactPage`     | how to reach out about an engagement              |
+| `blog`         | `BlogList`        | thought leadership and updates                    |
+| `privacy`      | `PrivacyPage`     | privacy policy                                    |
+| `terms`        | `TermsPage`       | terms of service                                  |
+
+For solo practitioners, drop the `team` page and anchor home/about/contact
+on `Person` instead of `Organization`.
+
+---
+
+## Marketplace
+
+Two-sided platforms — buyers on one side, sellers/providers on the
+other. Always organizational; an individual cannot be a marketplace.
+
+- **Entity tag:** `organization`
+- **Pages:**
+
+| Slug          | Schema.orgType | Purpose                                          |
+| ------------- | -------------- | ------------------------------------------------ |
+| `home`        | `HomePage`     | the value prop for both sides of the marketplace |
+| `for-buyers`  | `ServicesList` | what buyers get and how it works                 |
+| `for-sellers` | `ServicesList` | what sellers get and how to onboard              |
+| `browse`      | `ProductsList` | the searchable catalog of listings               |
+| `about`       | `AboutPage`    | who runs the platform and why                    |
+| `contact`     | `ContactPage`  | support entry point                              |
+| `faq`         | `FAQPage`      | trust, payments, dispute resolution              |
+| `privacy`     | `PrivacyPage`  | privacy policy                                   |
+| `terms`       | `TermsPage`    | terms of service                                 |
+
+---
+
+## Content / Blog
+
+Publications, personal blogs, newsletters with a website. The
+defining feature: posts are the primary surface, not products or
+services.
+
+- **Entity tag:** `both`
+- **Pages:**
+
+| Slug      | Schema.orgType | Purpose                                   |
+| --------- | -------------- | ----------------------------------------- |
+| `home`    | `HomePage`     | recent and featured posts                 |
+| `blog`    | `BlogList`     | the full archive                          |
+| `about`   | `AboutPage`    | who writes and why                        |
+| `contact` | `ContactPage`  | how to reach the author or editorial team |
+| `privacy` | `PrivacyPage`  | privacy policy                            |
+| `terms`   | `TermsPage`    | terms of service                          |
+
+Individual posts use `BlogPosting`. A "personal" blog (one writer,
+their name on the site) is `Person`; an editorial publication with a
+masthead is `Organization`. Phrases like "personal" or "my" in the
+description settle it as Person without asking.
+
+---
+
+## Course / Education
+
+Course providers, schools, online academies, individual instructors
+selling courses. Core surface is the course catalog.
+
+- **Entity tag:** `both`
+- **Pages:**
+
+| Slug           | Schema.orgType     | Purpose                                          |
+| -------------- | ------------------ | ------------------------------------------------ |
+| `home`         | `HomePage`         | who the courses are for and the headline outcome |
+| `courses`      | `CoursesList`      | catalog of available courses                     |
+| `about`        | `AboutPage`        | instructor or institution story                  |
+| `testimonials` | `TestimonialsList` | student outcomes and quotes                      |
+| `contact`      | `ContactPage`      | enrollment and support                           |
+| `faq`          | `FAQPage`          | format, prerequisites, certification             |
+| `privacy`      | `PrivacyPage`      | privacy policy                                   |
+| `terms`        | `TermsPage`        | terms of service                                 |
+
+Individual courses use `Course`. A solo instructor anchors on `Person`;
+a school anchors on `Organization`.
+
+---
+
+## Real estate
+
+Brokerages, individual agents, property-management firms. The
+disambiguation matters here: a solo agent's site looks different from
+a brokerage's.
+
+- **Entity tag:** `both`
+- **Pages:**
+
+| Slug           | Schema.orgType     | Purpose                                                 |
+| -------------- | ------------------ | ------------------------------------------------------- |
+| `home`         | `HomePage`         | what kinds of properties and which markets              |
+| `listings`     | `ProductsList`     | available properties (treat each property as a Product) |
+| `services`     | `ServicesList`     | buyer / seller / rental representation                  |
+| `about`        | `AboutPage`        | the agent's or brokerage's story and credentials        |
+| `team`         | `TeamList`         | the agents at the brokerage (skip for solo agents)      |
+| `testimonials` | `TestimonialsList` | client reviews                                          |
+| `contact`      | `ContactPage`      | how to reach out about a property                       |
+| `privacy`      | `PrivacyPage`      | privacy policy                                          |
+| `terms`        | `TermsPage`        | terms of service                                        |
+
+Words like "brokerage", "team", "our agents" → `Organization`. "Solo
+agent", "I represent" → `Person`. Drop the `team` page for solo
+agents.
+
+---
+
+## Healthcare / Medical
+
+Clinics, solo practitioners, group practices, dental offices,
+therapists, specialty practices. Privacy and credibility are
+load-bearing here.
+
+- **Entity tag:** `both`
+- **Pages:**
+
+| Slug       | Schema.orgType | Purpose                                                |
+| ---------- | -------------- | ------------------------------------------------------ |
+| `home`     | `HomePage`     | what care is offered and for whom                      |
+| `services` | `ServicesList` | conditions treated and procedures offered              |
+| `team`     | `TeamList`     | the providers (skip for solo practitioners)            |
+| `about`    | `AboutPage`    | practice philosophy, credentials, affiliations         |
+| `faq`      | `FAQPage`      | insurance, scheduling, what to expect                  |
+| `contact`  | `ContactPage`  | hours, address, intake form link                       |
+| `privacy`  | `PrivacyPage`  | privacy policy (HIPAA-relevant; flag this to the user) |
+| `terms`    | `TermsPage`    | terms of service                                       |
+
+Solo practitioner → `Person`; clinic or group practice → `Organization`.
+Drop `team` for solo practitioners.
+
+When emitting the privacy line, mention HIPAA: "Healthcare sites need
+a HIPAA-aware privacy policy. The default `PrivacyPage` is a starting
+point, not a finished policy."
+
+---
+
+## Nonprofit / Org
+
+Nonprofits, advocacy groups, professional associations, foundations.
+Always organizational by nature; even a one-person foundation
+operates as an entity.
+
+- **Entity tag:** `organization`
+- **Pages:**
+
+| Slug       | Schema.orgType | Purpose                                                       |
+| ---------- | -------------- | ------------------------------------------------------------- |
+| `home`     | `HomePage`     | mission and what the org does this year                       |
+| `programs` | `ServicesList` | programs the org runs                                         |
+| `about`    | `AboutPage`    | history, mission, governance                                  |
+| `team`     | `TeamList`     | staff and board                                               |
+| `partners` | `PartnersList` | funders, partners, supporting organizations                   |
+| `events`   | `EventsList`   | upcoming events and campaigns                                 |
+| `donate`   | `Service`      | donation entry point (treat the act of donating as a Service) |
+| `contact`  | `ContactPage`  | how to reach the org                                          |
+| `privacy`  | `PrivacyPage`  | privacy policy                                                |
+| `terms`    | `TermsPage`    | terms of service                                              |
+
+---
+
+## Schema-builder coverage
+
+Every `Schema.orgType` referenced above is a member of the
+`SchemaOrgType` union exported by `@working-theory/schema` and has a builder
+function. The v1 catalog uses 21 of the 45 supported types:
+
+`HomePage`, `AboutPage`, `ContactPage`, `PrivacyPage`, `TermsPage`,
+`Organization`, `Person`, `ServicesList`, `Service`, `ProductsList`,
+`Product`, `FAQPage`, `TestimonialsList`, `TeamList`, `PartnersList`,
+`EventsList`, `CoursesList`, `Course`, `BlogList`, `BlogPosting`,
+`CaseStudiesList`.
+
+The remaining 24 types are available to `scaffold-page` and `add-schema`
+for per-page use but don't drive category recommendations.