create-ailk 0.6.1 → 0.7.0

package/templates/.claude/skills/add-schema/references/conflict-handling.md

@@ -1,200 +0,0 @@
-# Conflict Handling — Replace / Append / Ask
-
-When `add-schema` is asked to attach a schema to a page that
-already has JSON-LD, the resolution depends on (a) whether the
-incoming type is **primary** or **supplementary** per
-`references/schema-types.md`, and (b) what's already there.
-
-This file is the decision tree the skill applies in Steps 4–5 of
-the SKILL.md mechanic.
-
-## The decision tree
-
-```
-                ┌─────────────────────────────────┐
-                │  New schema — type T, page P    │
-                └─────────────────┬───────────────┘
-                                  ▼
-              ┌────────────────────────────────────┐
-              │ Existing JSON-LD on page P?        │
-              └─┬─────────────────┬────────────────┘
-                │                 │
-              No│              Yes│
-                ▼                 ▼
-         ┌──────────┐      ┌─────────────────────────────┐
-         │ APPEND   │      │ Existing schema parseable?  │
-         │ (first   │      │ (canonical <JsonLd>         │
-         │  attach) │      │  pattern only)              │
-         └──────────┘      └──┬──────────────┬───────────┘
-                              │              │
-                            No│           Yes│
-                              ▼              ▼
-                    ┌────────────┐    ┌──────────────────────┐
-                    │ ASK        │    │ Same @type as T?     │
-                    │ (consumer  │    └──┬────────────────┬──┘
-                    │  decides:  │       │                │
-                    │  alongside │     Yes│              No│
-                    │  /         │       ▼                ▼
-                    │  migrate / │  ┌─────────────┐  ┌──────────────────┐
-                    │  cancel)   │  │ T is        │  │ APPEND           │
-                    └────────────┘  │ primary?    │  │ (different types │
-                                    └─┬───────┬───┘  │  always stack)   │
-                                      │       │     └──────────────────┘
-                                    Yes│     No│
-                                      ▼       ▼
-                              ┌──────────┐ ┌──────────┐
-                              │ REPLACE  │ │ APPEND   │
-                              │ (after   │ │ (supp.   │
-                              │ confirm) │ │ stacks)  │
-                              └──────────┘ └──────────┘
-```
-
-## Case-by-case
-
-### Case 1 — No existing JSON-LD
-
-**Action:** APPEND (first attachment).
-
-Add the import line + `<JsonLd>` JSX element. Confirm via Step 7
-diff before write. This is the simplest path.
-
-### Case 2 — Existing JSON-LD, same `@type`, primary type
-
-**Action:** REPLACE (after confirming).
-
-Example: page has `<JsonLd schema={buildProduct(oldProduct)}/>`,
-consumer asks to add `Product` schema. The new `Product` replaces
-the old one — locating the existing JSX, swapping the
-`schema={…}` expression.
-
-Confirmation message:
-
-> "`Product` schema is already attached to `/<slug>`. I'll replace
-> it with the new one. The old expression
-> `buildProduct(oldProduct)` becomes
-> `buildProduct(newProduct)` — confirm or cancel."
-
-### Case 3 — Existing JSON-LD, same `@type`, supplementary type
-
-**Action:** APPEND (supplementary stacks).
-
-This is rare but valid. Example: page has `<JsonLd
-schema={buildReview(review1)}/>`, consumer asks to add another
-`Review`. Reviews can stack — append a second `<JsonLd>` element
-rather than replacing.
-
-If unsure whether the consumer meant replace or append, ask:
-
-> "There's already a `Review` schema on this page. I can:
->
-> - Add a second `Review` (stack — both visible in
->   structured data).
-> - Replace the existing one (only the new review is visible).
->
-> Which?"
-
-### Case 4 — Existing JSON-LD, different `@type`
-
-**Action:** APPEND.
-
-Example: page has `<JsonLd schema={buildOrganization(...)}/>`,
-consumer asks to add `FAQPage`. Different types always stack — add
-a new `<JsonLd>` element next to the existing one.
-
-This is the most common case for supplementary types
-(`FAQPage`, `HowTo`, `BreadcrumbList`, `Review`,
-`AggregateRating`).
-
-### Case 5 — Existing JSON-LD is non-canonical
-
-**Action:** ASK.
-
-Triggers when the existing structured data:
-
-- Uses a raw `<script type="application/ld+json">` block.
-- Uses a hand-coded JSON literal (no builder import).
-- Uses `metadata.other` in `generateMetadata`.
-- Has `<JsonLd>` JSX with a `schema` prop that doesn't match a
-  recognized builder call.
-
-The skill must not silently rewrite. Ask:
-
-> "I see existing structured data on this page that wasn't
-> created by the canonical `<JsonLd schema={builder(...)}/>`
-> pattern. I can:
->
-> - **Add alongside** — leave the existing data, add my new
->   schema as a separate `<JsonLd>` element.
-> - **Migrate to canonical** — replace the existing structured
->   data with the canonical pattern, then add my new schema.
-> - **Cancel** — leave the file alone.
->
-> Which?"
-
-Wait for choice. The "migrate to canonical" path is the deepest —
-it requires parsing the existing JSON-LD object literal,
-inferring the builder, and rewriting. Don't attempt unless the
-consumer explicitly chooses migrate.
-
-### Case 6 — Existing JSON-LD is malformed / unparseable
-
-**Action:** ASK with a stronger refuse-default.
-
-Triggers when the file's JSON-LD block can't be parsed at all (broken
-JSX, malformed JSON literal, syntax error). The default is **don't
-touch the existing data**:
-
-> "There's existing JSON-LD on this page that doesn't parse
-> cleanly. I shouldn't rewrite it without you seeing what's
-> there. I can:
->
-> - **Add alongside** — append my new schema as a separate
->   `<JsonLd>` element. Existing broken data stays as-is (you
->   fix it later).
-> - **Cancel** — open the file yourself, fix the existing
->   block, then re-run this skill.
->
-> Recommended: cancel and fix the existing data first."
-
-## Identity-on-non-home-page edge case
-
-If the consumer asks to attach `Organization`, `Person`, or
-another identity type (per `references/schema-types.md`) to a
-**non-home** page, surface a flag:
-
-> "`Organization` is typically a site-wide identity emitted in
-> the layout (so it appears on every page). Adding it to one
-> page means only that page surfaces the entity. Continue, or
-> add it to your layout instead?"
-
-Wait for the consumer's choice. If they continue, proceed
-through the normal decision tree. If they want to add to the
-layout, point at `apps/web/app/layout.tsx` and stop —
-modifying the layout is outside this skill's lane.
-
-## Validation after write
-
-Regardless of replace / append, after the write the file must
-still parse:
-
-- For `.tsx`: TS parse check (parse only, not full type-check).
-- For `.mdx`: MDX parse check.
-
-If parse fails, revert the write and surface the literal parse
-error per SKILL.md Step 8.
-
-## Why this complexity exists
-
-Type-aware conflict handling is what separates `add-schema` from
-"just append every time." The two cases that drive the
-complexity:
-
-- A consumer iterating on `Product` schema (Case 2) expects
-  replacement, not stacking — duplicate `Product` schemas hurt
-  citation more than help.
-- A consumer adding `FAQPage` to a `Product` page (Case 4) wants
-  both — `Product` is the page's identity, `FAQPage` adds
-  question/answer dimensions. Stacking is correct.
-
-The decision tree above codifies the difference once so the
-skill applies it consistently.

package/templates/.claude/skills/add-schema/references/file-finding.md

@@ -1,123 +0,0 @@
-# File-Finding — Slug → File Resolution
-
-The `add-schema` skill resolves a slug like `/pricing` to one or
-more files in the consumer's repo. This file is the source of
-truth for the resolution logic the skill applies in Step 2.
-
-## The two locations to scan
-
-A slug can map to either (or both) of:
-
-1. **App Router route file.**
-   - Primary: `apps/web/app/<slug>/page.tsx` (monorepo layout, the
-     AILK default).
-   - Fallback: `app/<slug>/page.tsx` (standalone Next.js app at
-     repo root).
-   - Slug supports nested paths: `/products/widget` →
-     `app/products/widget/page.tsx`.
-   - The `[slug]` dynamic-route convention is also valid: `/blog/foo`
-     can map to `app/blog/[slug]/page.tsx`. The skill recognizes
-     both static and dynamic route files; for dynamic routes, it
-     modifies the route handler itself (not the dynamic instance).
-
-2. **MDX content file.**
-   - Scan: `content/**/<slug>.mdx`.
-   - The frontmatter `slug:` field is **authoritative** when
-     present. Filename match is a fallback.
-   - Multi-type content folders: a slug can live in
-     `content/Product/widget.mdx` or
-     `content/BlogPosting/widget.mdx`. The frontmatter `type:`
-     field disambiguates.
-
-## Match outcomes
-
-### Zero matches
-
-Refuse with a clear pointer:
-
-> "No page exists at `/<slug>`. Use `scaffold-page` (#362) to
-> create one first; come back here once it exists to add
-> additional schema."
-
-Do not write anything.
-
-### One match
-
-Proceed. Show the consumer which file you'll modify in Step 7's
-diff so they can confirm the path before any write.
-
-### Multiple matches
-
-List and ask. Common multi-match shapes:
-
-- **Route + MDX coexistence.** Many AILK pages have both a
-  `apps/web/app/<slug>/page.tsx` (renderer) and a
-  `content/<Type>/<slug>.mdx` (data). The route renders the MDX —
-  schema can attach in either:
-  - Attaching in the route puts JSON-LD in JSX.
-  - Attaching in the MDX puts JSON-LD inline in content.
-  - The canonical AILK pattern emits via the route (the route
-    imports `<JsonLd schema={builder(page)}/>` and reads frontmatter
-    via the content adapter). When in doubt, modify the route.
-
-- **Multiple MDX files for the same slug.** Rare; usually means
-  the consumer has organized content by `type/` and the same slug
-  appears in different type folders. List all matches with their
-  `type:` frontmatter and ask which one the consumer means.
-
-- **Static + dynamic route ambiguity.** If both `app/<slug>/page.tsx`
-  and `app/<slug>/[child]/page.tsx` exist, only the static
-  `<slug>/page.tsx` is the target — the dynamic file handles
-  child routes, not the index.
-
-Ask the consumer plainly:
-
-> "Found multiple files for `/<slug>`:
->
-> - `apps/web/app/<slug>/page.tsx` — App Router route
-> - `content/Product/<slug>.mdx` — MDX content
->
-> Where should I attach the schema? (Recommended: route, since
-> JSON-LD belongs in the rendered output.)"
-
-Wait for the consumer's choice.
-
-## What the skill does NOT touch
-
-- **Layout files.** `apps/web/app/layout.tsx` is the right place
-  for site-wide identity schema (`Organization` / `Person`). If
-  the consumer asks to add identity schema to a leaf page, the
-  skill flags this and asks (per `references/schema-types.md`).
-- **`globals.css`, `metadata.ts`, `route.ts`** — these aren't
-  where JSON-LD lives. The skill scans only `page.tsx` and
-  `*.mdx` for slug-pattern matches.
-- **`packages/schema/`** — read-only at v1 (per the issue scope).
-  The skill imports from `@working-theory/schema` but never modifies it.
-
-## Edge case — non-MDX content backend
-
-If the consumer's project uses a non-MDX adapter (Sanity, Payload,
-or any other), the MDX scan returns nothing. The skill still tries
-the App Router route file. If the route exists, attaching schema
-there works regardless of where the page's content data lives.
-
-If the consumer wants schema attached **to content** (not the
-route) and they're on a non-MDX backend, this skill at v1 says:
-
-> "Your content backend isn't MDX. JSON-LD attachment in
-> non-MDX backends ships in a future PR. For now, attach the
-> schema to the route file (`app/<slug>/page.tsx`) — that's
-> rendered server-side and works regardless of content adapter."
-
-## Validation after resolution
-
-Before any write, the skill confirms the resolved file is one of:
-
-- `.tsx` (App Router page) — must contain `export default
-function … Page()`.
-- `.mdx` (content file) — must have frontmatter delimiters
-  (`---`).
-
-If the file at the resolved path doesn't match one of those
-shapes, the skill surfaces the mismatch and stops. Don't write to
-a file you can't recognize.

package/templates/.claude/skills/add-schema/references/schema-types.md

@@ -1,234 +0,0 @@
-# Schema Types — Primary / Supplementary Catalog
-
-The schema.org types `add-schema` recognizes, each tagged
-**primary** (typically one per page) or **supplementary** (stacks
-freely). The skill reads this file to decide replace-vs-append in
-Step 6 of the mechanic.
-
-This catalog mirrors `@working-theory/schema`'s exports. When new builders
-ship in `@working-theory/schema`, this file updates in a follow-up PR. Until
-then, unrecognized types fall through to the "ask the consumer"
-path in SKILL.md.
-
-## Primary types (one per page; replace on conflict)
-
-These name what the page **is about**. Replacing on same-type
-conflict is the usual intent — adding a new `Product` schema
-generally means swapping the existing one.
-
-| `@type`             | Builder            | Aliases                       | Typical page              |
-| ------------------- | ------------------ | ----------------------------- | ------------------------- |
-| `HomePage`          | `buildHomePage`    | "home"                        | `/`                       |
-| `AboutPage`         | `buildAboutPage`   | "about"                       | `/about`                  |
-| `ContactPage`       | `buildContactPage` | "contact"                     | `/contact`                |
-| `PrivacyPage`       | `buildPrivacyPage` | "privacy"                     | `/privacy`                |
-| `TermsPage`         | `buildTermsPage`   | "terms"                       | `/terms`                  |
-| `Product`           | `buildProduct`     | "product"                     | Per-item product page     |
-| `Service`           | `buildService`     | "service", "service offering" | `/pricing`, `/services/*` |
-| `Article`           | `buildArticle`     | "article"                     | Editorial piece           |
-| `BlogPosting`       | `buildBlogPosting` | "blog post", "post"           | `/blog/<slug>`            |
-| `NewsArticle`       | `buildNewsArticle` | "news article"                | News piece                |
-| `Course`            | `buildCourse`      | "course"                      | `/courses/<slug>`         |
-| `Event`             | `buildEvent`       | "event"                       | Event landing             |
-| `JobPosting`        | `buildJobPosting`  | "job", "career"               | `/jobs/<slug>`            |
-| `Recipe`            | `buildRecipe`      | "recipe"                      | Per-recipe page           |
-| `Book`              | `buildBook`        | "book"                        | Book detail page          |
-| `Movie`             | `buildMovie`       | "movie", "film"               | Movie detail              |
-| `MusicAlbum`        | `buildMusicAlbum`  | "album"                       | Album page                |
-| `RealEstateListing` | _consumer-defined_ | "listing", "property"         | `/listings/<slug>`        |
-
-## Supplementary types (stack freely; always append)
-
-These add **dimensions** to a page that already has a primary
-type. Multiple of these can coexist on one page — never replace,
-always append.
-
-| `@type`           | Builder               | Aliases                       | Use                                   |
-| ----------------- | --------------------- | ----------------------------- | ------------------------------------- |
-| `FAQPage`         | _consumer-defined_    | "faq", "FAQ"                  | Q&A block on any page                 |
-| `HowTo`           | _consumer-defined_    | "how-to", "howto", "tutorial" | Step-by-step instructions             |
-| `BreadcrumbList`  | `buildBreadcrumbList` | "breadcrumbs"                 | Site navigation context               |
-| `Review`          | _consumer-defined_    | "review"                      | Single review (within Product, etc.)  |
-| `AggregateRating` | _consumer-defined_    | "rating", "ratings", "stars"  | Aggregate of reviews                  |
-| `VideoObject`     | _consumer-defined_    | "video"                       | Embedded video metadata               |
-| `ImageObject`     | _consumer-defined_    | "image"                       | Image with structured metadata        |
-| `AudioObject`     | _consumer-defined_    | "audio", "podcast"            | Audio embed metadata                  |
-| `Offer`           | _consumer-defined_    | "offer"                       | Pricing offer (under Product/Service) |
-| `OfferCatalog`    | _consumer-defined_    | "catalog", "offer catalog"    | Multi-offer container                 |
-| `MonetaryAmount`  | _consumer-defined_    | "monetary amount", "amount"   | Used inside Service / Offer           |
-
-## Identity types (one site-wide; emit on home or in layout)
-
-These are **the site's identity**. Typically one per site (not per
-page) and lives in the home page or a layout component. The skill
-treats them as **primary** for the conflict logic but flags the
-consumer if they're trying to add one to a non-home page.
-
-| `@type`         | Builder             | Aliases                          | Use                       |
-| --------------- | ------------------- | -------------------------------- | ------------------------- |
-| `Organization`  | `buildOrganization` | "org", "organization", "company" | Business identity         |
-| `Person`        | `buildPerson`       | "person", "individual"           | Solo individual identity  |
-| `LocalBusiness` | _consumer-defined_  | "local business"                 | Brick-and-mortar business |
-| `Restaurant`    | _consumer-defined_  | "restaurant"                     | Restaurant subtype        |
-| `Store`         | _consumer-defined_  | "store"                          | Retail subtype            |
-
-When adding `Organization` or `Person` to a non-home page, the
-skill should ask:
-
-> "`Organization` is typically a site-wide identity emitted in
-> the layout (so it appears on every page). Adding it to one
-> page means only that page surfaces the entity. Continue, or
-> add it to your layout instead?"
-
-## Specialty types
-
-Less-frequently-used but in the catalog. The skill recognizes
-these by name; conflict handling defaults to **supplementary**
-(append).
-
-| `@type`                             | Builder            | Aliases                          |
-| ----------------------------------- | ------------------ | -------------------------------- |
-| `MedicalCondition`                  | _consumer-defined_ | "medical condition"              |
-| `MedicalProcedure`                  | _consumer-defined_ | "medical procedure", "procedure" |
-| `Drug`                              | _consumer-defined_ | "drug", "medication"             |
-| `LearningResource`                  | _consumer-defined_ | "lesson", "learning resource"    |
-| `EducationalOccupationalCredential` | _consumer-defined_ | "credential", "certification"    |
-| `SoftwareApplication`               | _consumer-defined_ | "app", "software"                |
-| `MobileApplication`                 | _consumer-defined_ | "mobile app"                     |
-| `WebApplication`                    | _consumer-defined_ | "web app"                        |
-| `Dataset`                           | _consumer-defined_ | "dataset"                        |
-| `ScholarlyArticle`                  | _consumer-defined_ | "scholarly article", "paper"     |
-| `LegislativeBuilding`               | _consumer-defined_ | _rare, government use_           |
-
-## AILK page types (registry-backed — 60 keys, one builder each)
-
-Every key below is an entry in `@working-theory/schema`'s page-type registry
-(`packages/schema/src/registry/entries.ts`) and has a real, exported builder
-reachable via `buildJsonLd({ type: '<Key>', ... })` — this is the complete
-list of scaffoldable AILK page types, as opposed to the smaller general
-schema.org vocabulary tables above (some of which is still
-`_consumer-defined_`, i.e. not yet builder-backed). Several keys share one
-`@type` (e.g. `PrivacyPage` / `TermsPage` / `LandingPage` / `ThankYouPage` all
-emit `WebPage`) — the registry has 60 entries but only 24 distinct `@type`
-values. Re-derive with `pnpm page-type-counts`
-(`scripts/component/page-type-counts.ts` in the `ai-launch-kit-internal`
-source repo) before hand-editing this table.
-
-### Core (15)
-
-| Key | `@type` |
-| --- | --- |
-| `HomePage` | `HomePage` |
-| `AboutPage` | `AboutPage` |
-| `ContactPage` | `ContactPage` |
-| `PrivacyPage` | `WebPage` |
-| `TermsPage` | `WebPage` |
-| `LandingPage` | `WebPage` |
-| `ThankYouPage` | `WebPage` |
-| `BookCall` | `WebPage` |
-| `NewsletterSignup` | `WebPage` |
-| `DemoRequest` | `WebPage` |
-| `TrialSignup` | `WebPage` |
-| `Waitlist` | `WebPage` |
-| `Assessment` | `WebApplication` |
-| `Calculator` | `WebApplication` |
-| `CampaignLP` | `WebPage` |
-
-### Identity (4)
-
-`Organization` / `Person` / `BreadcrumbList` / `ContactPoint` — see the
-[Identity types](#identity-types-one-site-wide-emit-on-home-or-in-layout)
-table above; all four are registry-backed.
-
-### Canonical-List (17)
-
-| Key | `@type` |
-| --- | --- |
-| `ServicesList` | `CollectionPage` |
-| `ProductsList` | `CollectionPage` |
-| `ProjectsList` | `CollectionPage` |
-| `FAQPage` | `FAQPage` |
-| `CareersList` | `CollectionPage` |
-| `UseCasesList` | `CollectionPage` |
-| `TestimonialsList` | `CollectionPage` |
-| `ClientsList` | `CollectionPage` |
-| `DownloadsList` | `CollectionPage` |
-| `EventsList` | `CollectionPage` |
-| `CoursesList` | `CollectionPage` |
-| `TeamList` | `CollectionPage` |
-| `PartnersList` | `CollectionPage` |
-| `IntegrationsList` | `CollectionPage` |
-| `GlossaryList` | `CollectionPage` |
-| `LocationsList` | `CollectionPage` |
-| `DocsList` | `CollectionPage` |
-
-### Canonical-Detail (14)
-
-| Key | `@type` |
-| --- | --- |
-| `Service` | `Service` |
-| `Product` | `Product` |
-| `Project` | `CreativeWork` |
-| `Event` | `Event` |
-| `Course` | `Course` |
-| `TeamMember` | `ProfilePage` |
-| `Partner` | `AboutPage` |
-| `Integration` | `WebPage` |
-| `JobPosting` | `JobPosting` |
-| `SoftwareProduct` | `WebPage` |
-| `Location` | `Place` |
-| `ServiceAreaPage` | `WebPage` |
-| `UseCase` | `WebPage` |
-| `Pricing` | `WebPage` |
-
-### Editorial-List (3)
-
-| Key | `@type` |
-| --- | --- |
-| `BlogList` | `Blog` |
-| `ResourcesHub` | `CollectionPage` |
-| `CaseStudiesList` | `CollectionPage` |
-
-### Editorial-Detail (7)
-
-| Key | `@type` |
-| --- | --- |
-| `BlogPosting` | `BlogPosting` |
-| `CaseStudy` | `Article` |
-| `HowTo` | `HowTo` |
-| `Whitepaper` | `Article` |
-| `ResourceDetail` | `Article` |
-| `TechArticle` | `TechArticle` |
-| `DocsDetail` | `TechArticle` |
-
-## Total
-
-**Two distinct counts, not one.** The AILK page-type registry — the types
-`add-schema` can scaffold with a real builder — has **60 keys** (24 distinct
-`@type` values; see the family tables above). The general schema.org
-vocabulary tables earlier in this file are a separate, smaller, hand-curated
-list the skill also recognizes by name for non-registry types; several of
-those are still `_consumer-defined_` because `@working-theory/schema` hasn't
-shipped a typed builder for them yet — for those, the skill emits the JSON-LD
-as an inline literal with a comment noting the upstream issue.
-
-## When `@working-theory/schema` doesn't yet export the builder
-
-Some entries above say `_consumer-defined_` for the builder
-column. The skill's behavior in that case:
-
-1. Surface the gap:
-
-   > "`@working-theory/schema` doesn't export `build<Type>` yet. I can:
-   >
-   > - Emit the JSON-LD as an inline object literal (less
-   >   type-safe but works).
-   > - Skip — you author it manually using the canonical
-   >   `<JsonLd schema={...}/>` pattern.
-   >
-   > Which?"
-
-2. Wait for the consumer's choice. Don't fabricate a builder.
-
-This matches `scaffold-page` (#362)'s behavior — both skills handle
-the missing-builder case the same way.