create-ailk 0.1.0

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

@@ -0,0 +1,270 @@
+---
+name: add-schema
+description: Add or replace schema.org JSON-LD on an existing page in an AILK consumer site. Use when the user says "add Product schema to /pricing", "add FAQ to /contact", "put Service schema on this page", or otherwise wants schema attached to a page that already exists. Does NOT scaffold new pages — that's `scaffold-page` (#362). Type-aware conflict handling: replaces existing schema of the same `@type`, appends supplementary schema, asks on ambiguity.
+---
+
+# add-schema
+
+Inject schema.org JSON-LD into an existing page without re-scaffolding
+the route. Pairs with `scaffold-page` (#362) — that skill creates new
+pages, this one modifies existing ones. Both share the same `<JsonLd>`
+attachment pattern from `@working-theory/jsonld`.
+
+## When to use
+
+The consumer wants to add or update structured data on an existing
+page. Triggers:
+
+- "add Product schema to /pricing"
+- "add FAQ to /contact" / "add an FAQ section schema to about"
+- "put Service schema on this page"
+- "swap out the Product schema on /pricing for a new one"
+
+Skip this skill when:
+
+- The consumer wants a **new page** — that's `scaffold-page` (#362).
+  This skill refuses on no-match and points at #362 explicitly.
+- The consumer wants to **audit** schema coverage / validity —
+  that's `audit-site` (#365). Never invoked from here.
+- The schema type isn't in `references/schema-types.md`. Ask the
+  consumer rather than guessing.
+
+## What this skill does
+
+1. Parse the consumer's input: extract the **schema type** (Product,
+   FAQ, Service, etc.) and the **target slug** (`/pricing`,
+   `/contact`).
+2. **Resolve the file.** Slug-pattern lookup against:
+   - App Router: `apps/web/app/<slug>/page.tsx` (or
+     `app/<slug>/page.tsx` depending on consumer layout).
+   - MDX content: `content/<Type>/<slug>.mdx` for any of the page
+     types in `@working-theory/schema`.
+3. **Refuse on zero matches.** Point at `scaffold-page` (#362).
+4. **Ask on multiple matches.** List route vs MDX (or multiple
+   MDX matches) and ask which to modify.
+5. **Detect existing `<JsonLd>` attachments** in the resolved file.
+   Use `references/conflict-handling.md` to decide:
+   - Same `@type` already present → **replace** (after confirming).
+   - Different `@type` (supplementary) already present → **append**.
+   - Existing JSON-LD is malformed / unparseable → **ask** for
+     clarification before writing.
+6. **Show the diff** in a single confirmation step. After approval,
+   write.
+7. **Validate** the modified file still parses cleanly (TS or MDX
+   syntax check). Surface failures with the literal parse error.
+
+## What this skill does NOT do
+
+- Create new pages. Refuses + points at `scaffold-page` (#362).
+- Validate schema.org rich-results against Google's Rich Results
+  Test or schema.org's own validator. The typed builder from
+  `@working-theory/schema` is the type-correctness contract; rich-results
+  validation is `audit-site` (#365)'s lane.
+- Modify `packages/schema/` (read-only at v1). If a builder is
+  missing, surface and stop.
+- Use a `<script>` tag, `metadata.other`, or hand-coded JSON
+  literals. The canonical attachment is always
+  `<JsonLd schema={builder(...)} />` from `@working-theory/jsonld` +
+  `@working-theory/schema`. This matches `scaffold-page` (#362) — the two
+  skills share one attachment pattern.
+- Auto-invoke other skills.
+
+## The mechanic
+
+### Step 1 — Parse the input
+
+Extract two things:
+
+- **Schema type.** Match the consumer's words to a `@type` from
+  `references/schema-types.md`. "Product" → `Product`, "FAQ" →
+  `FAQPage`, "how-to" → `HowTo`, "Service" → `Service`. If
+  ambiguous (e.g., "review" could be `Review` or
+  `AggregateRating`), ask.
+- **Target slug.** From phrases like "/pricing", "to /contact", "on
+  the about page". Drop the leading `/`. If the consumer says
+  "this page" without specifying, ask which page.
+
+### Step 2 — File resolution
+
+Look in two places:
+
+1. **App Router route:** `apps/web/app/<slug>/page.tsx` (also try
+   `app/<slug>/page.tsx` for non-monorepo layouts).
+2. **MDX content:** scan `content/**/<slug>.mdx`. The frontmatter
+   `slug:` field is authoritative; filename is a fallback.
+
+**Zero matches** — refuse:
+
+> "I don't see a page at `/<slug>`. To **create** the page first,
+> run `scaffold-page` (#362). Once it exists, come back here to add
+> additional schema."
+
+Stop. No writes.
+
+**One match** — proceed to Step 3.
+
+**Multiple matches** — list and ask:
+
+> "Found multiple files for `/<slug>`:
+>
+> - `apps/web/app/<slug>/page.tsx` (App Router route)
+> - `content/Product/<slug>.mdx` (MDX content)
+>
+> Which one should I modify?"
+
+Wait for the consumer's choice.
+
+### Step 3 — Detect existing attachments
+
+In the resolved file, look for `<JsonLd schema={...} />` JSX
+elements. The canonical pattern emits one of these per attached
+schema. Two states matter:
+
+- **Same `@type` already present.** Example: consumer wants to add
+  `Product` schema to `/pricing`, and the file already has
+  `<JsonLd schema={buildProduct(...)} />`. This is a **replace**
+  case (Step 4).
+- **Different `@type` already present.** Example: file has
+  `<JsonLd schema={buildOrganization(...)} />` and consumer wants
+  to add `FAQPage`. This is an **append** case (Step 5).
+
+If existing JSON-LD is **malformed or unrecognized** (raw `<script
+type="application/ld+json">` block, hand-coded literal not
+matching a builder, malformed JSX), do 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 my new schema alongside (no conflict — different
+>   attachment style).
+> - Replace what's there with the canonical pattern + my new
+>   schema (clean migration).
+> - Cancel — leave the file alone.
+>
+> Which?"
+
+### Step 4 — Conflict handling: replace (same `@type`)
+
+When the same `@type` is already attached, the default is
+**replace**. Confirm:
+
+> "`<Type>` schema is already attached to `/<slug>`. I'll replace
+> it with the new one — confirm or cancel."
+
+After approval, locate the existing `<JsonLd>` JSX, swap the
+`schema={...}` expression. Keep surrounding code (imports, other
+JSX, exports) untouched.
+
+### Step 5 — Conflict handling: append (different `@type`)
+
+When the new schema is a different `@type` from existing
+attachments, the default is **append**. Show the diff:
+
+> "Your page already has `<Organization>` schema. I'll add an
+> `<FAQPage>` block next to it — confirm or cancel."
+
+After approval, add a new `<JsonLd schema={buildFAQPage(...)} />`
+JSX element next to the existing one(s). Add the import for the
+new builder if not already imported.
+
+### Step 6 — Type-aware classification
+
+`references/schema-types.md` tags each of the 45 schema.org types
+in `@working-theory/schema` as **primary** or **supplementary**:
+
+- **Primary** types are typically one-per-page: `HomePage`,
+  `AboutPage`, `BlogPosting`, `Product`, `Service`. A page rarely
+  has two `Product` schemas.
+- **Supplementary** types stack naturally: `FAQPage`, `HowTo`,
+  `BreadcrumbList`, `Review`, `AggregateRating`. A single product
+  page might have `Product` + `FAQPage` + `Review` + `BreadcrumbList`.
+
+Default behavior:
+
+- Adding a **primary** type → if same type already present, replace.
+- Adding a **supplementary** type → always append; never replace
+  (you'd lose information).
+
+The classification is read-only at v1 — the skill knows the table,
+but does not write to `packages/schema/`. Future PR may move
+classification into the package.
+
+### Step 7 — Show the diff + confirm
+
+Single confirmation message:
+
+> "Adding `<Type>` schema to `<filepath>`:
+>
+> ```diff
+> + import { buildType } from "@working-theory/schema";
+>   ...
+> + <JsonLd schema={buildType({ ... })} />
+> ```
+>
+> Confirm to write, or tell me what to adjust."
+
+Wait for approval. Do not write per-step.
+
+### Step 8 — Write + validate
+
+Write the modified file atomically. After write, validate the file
+still parses:
+
+- For `.tsx` routes: run a TS parse check on the modified file
+  (parse only — full type-check is the consumer's `pnpm
+type-check` job).
+- For `.mdx` content: run an MDX parse check.
+
+If parse fails, surface the literal error and revert the write:
+
+> "After writing, the file no longer parses cleanly:
+>
+> ```
+> <verbatim parse error>
+> ```
+>
+> I've reverted the change. Try a different approach, or hand-edit
+> the file."
+
+If parse succeeds, print a closing summary:
+
+> "Added `<Type>` schema to `<filepath>`. Run `pnpm dev` to verify
+> the page renders, or `audit-site` (#365) to check
+> citation-readiness."
+
+## Type-by-name recognition
+
+The skill recognizes all 45 schema types in `@working-theory/schema` by name.
+Common aliases (e.g., "FAQ" → `FAQPage`, "how-to" → `HowTo`,
+"review" → `Review`) are handled in `references/schema-types.md`.
+If the consumer asks for a type not in the catalog, surface and
+ask:
+
+> "I don't see `<requested type>` in the v1 schema catalog. The 45
+> recognized types are listed in `references/schema-types.md` —
+> closest matches are `<X>` and `<Y>`. Use one of those, or hand-
+> author the JSON-LD inline if you need a less-common type."
+
+## References
+
+- `references/schema-types.md` — the 45 schema.org types from
+  `@working-theory/schema`, each tagged primary or supplementary, with
+  human-friendly aliases.
+- `references/file-finding.md` — slug-to-file resolution rules
+  (App Router + MDX).
+- `references/conflict-handling.md` — full decision tree for
+  replace / append / ask.
+
+## Coordination
+
+- **`scaffold-page` (#362)** — creates new pages. This skill
+  modifies existing ones. Same `<JsonLd>` attachment pattern.
+- **`audit-site` (#365)** — citation-readiness check. Never
+  invoked from inside this skill; the audit reports, this fix
+  tool fixes.
+- **`@working-theory/jsonld` (#389)** — the React component for JSON-LD
+  rendering. Single source of truth for the attachment pattern.
+- **`@working-theory/schema`** — typed builders + `JsonLdObject` output.
+  Read-only at v1; `references/schema-types.md` is the skill's
+  copy of the catalog.

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

@@ -0,0 +1,200 @@
+# 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

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