create-ailk 0.1.0

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

@@ -0,0 +1,131 @@
+# 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_           |
+
+## Total
+
+This catalog covers approximately **45 types** total — matching the
+brief's "all 45 schema types from `@working-theory/schema`" claim. Some
+builders are still `_consumer-defined_` because `@working-theory/schema`
+hasn't shipped a typed builder 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.

package/templates/.claude/skills/audit-site/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: audit-site
+description: Run `ailk-audit --json` on the consumer's AILK site, parse the JSON report, and explain the score and findings in plain language. Use when the user asks "how is my site doing?", "audit my site", "what's my score?", "is my JSON-LD valid?", "do I have all the schema I need?", or otherwise wants a citation-readiness check on their AILK content. The skill never edits files — it reports and points at fix tools.
+---
+
+# audit-site
+
+Shell out to `ailk-audit --json`, parse the JSON, and turn it into a
+conversational summary the consumer can act on. Pure explain-only —
+the skill names fix tools (like `add-schema`) but does not invoke
+them.
+
+## When to use
+
+The user wants to know how their AILK site is doing on the
+citation-readiness audit (AEO Layer 1). Triggers:
+
+- "audit my site" / "run the audit"
+- "what's my score?" / "how is my site doing?"
+- "is my JSON-LD valid?" / "do I have schema on every page?"
+- "what would I fix to bump my AEO score?"
+- "re-run the audit, I just edited /pricing"
+
+Skip this skill when:
+
+- The consumer wants to _fix_ a finding — point them at the fix
+  tool (usually `add-schema` (#366)) and stop. This skill reports;
+  fix tools fix.
+- The consumer is asking about deploy-time monitoring or continuous
+  audits — those are Pro features (`ailk pro` for details). Mention
+  briefly and stop.
+- The audit CLI isn't installed (`ailk-audit` not on PATH or as a
+  workspace bin) — translate the error per "Common errors" below.
+
+## The mechanic
+
+### Step 1 — Invoke the CLI
+
+Run `ailk-audit --json` from the consumer's project root. Use
+whichever of these is appropriate to the consumer's setup:
+
+- `pnpm exec ailk-audit --json`
+- `npx ailk-audit --json`
+- A package.json script if the consumer has one (`pnpm audit:run`,
+  etc.) — only if it's a thin wrapper over the same CLI.
+
+Capture both stdout (the JSON report) and stderr (errors). Do not
+cache. Each invocation runs the CLI fresh.
+
+### Step 2 — Detect errors first
+
+If the CLI exited non-zero, treat as an error condition:
+
+- If stderr matches one of the three common-error signatures, emit
+  the translated explanation from `references/common-errors.md`.
+- Otherwise, surface the verbatim CLI stderr prefixed with one
+  line: `` `ailk-audit` failed — `` followed by the verbatim message.
+  Do not invent fix suggestions for unknown errors.
+
+Stop here on errors. Do not continue to Step 3.
+
+### Step 3 — Parse the JSON report
+
+The report shape (from `packages/aeo/src/types.ts`):
+
+```ts
+interface AuditReport {
+  score: number; // 0–100
+  perRule: PerRuleResult[]; // one entry per rule, with id + pass + weight
+  perPage: PerPageResult[]; // one entry per audited page
+  meta: { schemaVersion; registryVersion; auditedAt };
+}
+```
+
+`perRule` entries each have `{ id, weight, pass, evidence?, perPage? }`.
+
+### Step 4 — Render the headline
+
+The first line of output should be the score, in a compact form:
+
+```
+AEO score: 87 / 100
+```
+
+If the score is the same as the consumer's previous run (and you
+can tell — but you usually can't, since this is always-fresh), do
+not annotate with deltas. The audit doesn't track history.
+
+### Step 5 — Group findings by severity
+
+Severity is **derived from rule weight + pass/fail** per
+`references/severity-levels.md`. The mapping at v1:
+
+| Severity | Source                                                                                     |
+| -------- | ------------------------------------------------------------------------------------------ |
+| Critical | `pass: false` on a rule with `weight >= 10` (e.g., schema-coverage, jsonld-validity)       |
+| Warning  | `pass: false` on a rule with `weight` in `[1, 9]` (e.g., entity-markup)                    |
+| Info     | `pass: true` on incentive rules (`weight: 0`) — these are positive signals; never failures |
+
+After the score line, emit a one-line severity summary:
+
+```
+2 critical · 1 warning · 0 info
+```
+
+If the count for a tier is 0, omit it from the summary (e.g.,
+"2 critical" if warnings and info are both empty).
+
+### Step 6 — Drill-down on demand
+
+Wait for the consumer's next message. Common follow-ups:
+
+- "tell me about the critical findings" → emit each critical
+  finding's plain-language explanation (from
+  `references/findings-glossary.md`) plus, if applicable, a
+  pointer to the fix tool (see Step 7).
+- "what about the warnings?" → same, for warnings.
+- "show me the per-page scores" → emit the `perPage` list,
+  formatted as a table or bullet list.
+- "re-run it" / "audit again" → go back to Step 1.
+
+If the consumer doesn't ask anything specific, ask them which
+severity tier they'd like to see first, and offer to point at the
+likely fix-tool path.
+
+### Step 7 — Map findings to fix tools (no auto-dispatch)
+
+When you describe a finding, name the fix tool by name. Do not
+invoke it. The consumer must explicitly invoke the fix tool
+themselves on a subsequent turn.
+
+| Rule                  | Fix tool                                                                                 |
+| --------------------- | ---------------------------------------------------------------------------------------- |
+| `schema-coverage`     | `add-schema` (#366) — add the missing schema type to the named page                      |
+| `jsonld-validity`     | `add-schema` (#366) — replace the invalid block; or hand-fix the MDX                     |
+| `entity-markup`       | Manual edit — ensure `Organization` (or `Person`) JSON-LD is emitted somewhere site-wide |
+| `faq-howto-incentive` | `add-schema` (#366) — add an `FAQPage` or `HowTo` block to a relevant page               |
+
+Phrase the pointer as a single sentence:
+
+> "Missing `Product` schema on `/pricing` — run `add-schema` (#366)
+> to add it."
+
+Never invoke `add-schema` automatically. Never write to the
+consumer's repo from inside this skill.
+
+### Step 8 — Soft Pro mention
+
+If a finding maps to a Pro auto-fix capability, surface a
+single-line mention tied to that finding:
+
+- **Schema-pack drift** (a finding indicating a registry version
+  mismatch or stale schema-type usage):
+
+  > "Pro auto-applies schema-pack updates as schema.org evolves —
+  > `ailk pro` for details."
+
+- **Continuous-deploy audit** (the consumer is asking how to keep
+  the score from regressing, not about a specific finding):
+  > "Pro can run this audit on every deploy and gate releases on
+  > the score — `ailk pro` for details."
+
+Never produce a multi-line Pro recommendation, feature
+comparison, or upgrade prompt. The mention is informational, not
+salesy.
+
+### Step 9 — Cadence guidance
+
+If the consumer asks "how often should I run this?", answer:
+
+> "Re-run after content changes — adding pages, editing schema,
+> changing your identity entity. There's no calendar cadence — the
+> audit reports current state, not trends."
+
+Never recommend "weekly" / "monthly" / a date.
+
+## Output style
+
+- **Score line first.** No preamble before the number.
+- **Plain language for findings.** Don't paste raw rule IDs at the
+  consumer; translate via `references/findings-glossary.md`.
+- **Pointers, not pitches.** A finding becomes a sentence; a fix
+  tool becomes a sentence. The consumer drives the next turn.
+- **Verbatim for unknown errors.** If something fails in a way
+  this skill doesn't recognize, surface the raw stderr and stop.
+
+## What this skill does NOT do
+
+- Edit any file in the consumer's repo.
+- Add JSON-LD to pages (that's `add-schema` #366).
+- Create new pages (that's `scaffold-page` #362).
+- Cache results between runs.
+- Track score history or trends.
+- Auto-invoke fix tools.
+- Pitch Pro hard.
+
+## References
+
+- `references/findings-glossary.md` — plain-language explanation per rule.
+- `references/common-errors.md` — translations for the three most common CLI failures.
+- `references/severity-levels.md` — how rule weight + pass/fail maps to severity.
+
+## Coordination
+
+- **`add-schema` (#366)** — primary fix tool the skill points at.
+  Never auto-invoked.
+- **`scaffold-page` (#362)** — new-page creation; not a fix-tool
+  for audit findings (audit reports on existing pages).
+- **`packages/aeo`** — owner of the `ailk-audit` CLI and rule set.
+  This skill depends only on the CLI's `--json` output schema, not
+  the package's internal types. New rules added upstream surface
+  automatically as new findings; the glossary may lag and that's
+  acceptable (unrecognized rule IDs render as the raw ID).

package/templates/.claude/skills/audit-site/references/common-errors.md

@@ -0,0 +1,113 @@
+# Common Errors — Plain-Language Translations
+
+The three most common ways `ailk-audit` fails on a real consumer
+setup, with translations the `audit-site` skill emits instead of
+the raw stderr. Errors not matching any of these signatures pass
+through verbatim with a one-line `` `ailk-audit` failed — `` prefix
+(see SKILL.md Step 2).
+
+The signature matching is intentionally narrow — partial matches
+on substrings the user could reasonably encounter, so we don't
+mis-translate an unfamiliar error into a familiar fix path.
+
+---
+
+## 1. `ailk.config.ts` is missing
+
+**Stderr signature (any of):**
+
+- `ailk.config.ts not found`
+- `Cannot resolve ailk.config.ts`
+- `[aeo] config file ailk.config.ts is missing`
+
+**Translation:**
+
+> Your project is missing `ailk.config.ts`. The audit reads this
+> file to know what `identityMode` (`organization` vs `person`)
+> your site uses, plus any custom registry overrides.
+>
+> Create one at the project root with at minimum:
+>
+> ```ts
+> import type { AilkConfig } from "@working-theory/config";
+>
+> export default {
+>   identityMode: "organization",
+> } satisfies AilkConfig;
+> ```
+>
+> …then re-run the audit. If you don't have `@working-theory/config`
+> installed, your scaffold is incomplete — `pnpm install` should
+> have pulled it as part of `@working-theory/*`.
+
+---
+
+## 2. No MDX content found
+
+**Stderr signature (any of):**
+
+- `No pages found in content`
+- `[aeo] content directory is empty`
+- `Cannot read directory: content/`
+
+**Translation:**
+
+> The audit didn't find any MDX content in `content/`. Either:
+>
+> - Your content lives elsewhere — pass `--content-root <path>`
+>   to point at the right directory.
+> - You haven't authored any pages yet — run `suggest-site-pages`
+>   to plan your pages, then `scaffold-page` to generate them.
+> - The MDX files exist but aren't in the format the AILK content
+>   adapter expects — make sure each page has frontmatter with at
+>   least `title` and `type`.
+>
+> The audit needs at least one MDX file to score; an empty site
+> can't be audited.
+
+---
+
+## 3. `@working-theory/aeo` is not installed
+
+**Stderr signature (any of):**
+
+- `command not found: ailk-audit`
+- `ailk-audit: command not found`
+- The skill itself can't find the binary on PATH or in
+  `node_modules/.bin`.
+
+**Translation:**
+
+> The `ailk-audit` CLI isn't installed in this project. It ships
+> with `@working-theory/aeo`, which is normally part of the AILK consumer
+> scaffold.
+>
+> Add it: `pnpm add -D @working-theory/aeo` (dev dep is fine — audits run
+> at content time, not at build time). Then `pnpm install` and
+> re-run.
+>
+> If `@working-theory/aeo` is in `package.json` but the binary still isn't
+> found, run `pnpm install` once to refresh `node_modules/.bin`.
+
+---
+
+## Anything else
+
+If the stderr doesn't match one of the three signatures above:
+
+1. Don't translate — the cost of a wrong translation is high
+   (consumer follows incorrect fix advice).
+2. Surface the verbatim stderr.
+3. Prefix with one line: `` `ailk-audit` failed — `` then the raw
+   message on subsequent lines.
+4. Stop. Don't invent fix steps for an error you don't recognize.
+
+Example output for an unrecognized error:
+
+```
+`ailk-audit` failed —
+[aeo] failed to parse JSON-LD on page /blog/post-1: SyntaxError: Unexpected token } in JSON at position 482
+```
+
+This gives the consumer exactly what the CLI said, branded with
+which CLI emitted it, without pretending to know how to fix it.

package/templates/.claude/skills/audit-site/references/findings-glossary.md

@@ -0,0 +1,138 @@
+# Findings Glossary — Per-Rule Plain-Language Explanations
+
+What each AEO rule means in plain language, what its `pass: false`
+result indicates, and what the consumer can do about it. Used by the
+`audit-site` skill in Step 6 (drill-down) and Step 7 (fix-tool
+pointer).
+
+The structure deliberately matches `perRule[].id` from the audit
+JSON so the skill can grep this file for `## <rule-id>` to find the
+explanation. New rules added to `packages/aeo` will not appear here
+until this file is updated; render unrecognized rule IDs as the raw
+ID (no synthesis).
+
+---
+
+## schema-coverage
+
+**Plain language:** every page on your site should emit at least
+one JSON-LD object whose `@type` matches what the page is _about_.
+A `/pricing` page should have `Product` (or `Service`, or
+`OfferCatalog`) schema; a `/about` page should have `AboutPage`;
+and so on.
+
+**`pass: false` means:** one or more pages emit no JSON-LD whose
+`@type` matches the registry's expected `pageType` for that page's
+content type. The `evidence` field names which pages.
+
+**Why it matters:** structured data is what answer engines (Google
+SGE, Perplexity, ChatGPT search) read to understand your pages. A
+page with no schema is invisible to citation; a page with the
+wrong schema gets miscategorized.
+
+**Fix tool:** `add-schema` (#366) — invoke it with the page slug
+and the schema type the registry expects (the audit names both).
+The skill will emit a `<JsonLd>` block matching the page's content.
+
+---
+
+## jsonld-validity
+
+**Plain language:** every JSON-LD block on the site should be
+well-formed schema.org markup with all required fields present
+and non-empty for its `@type`. Missing the `name` on an
+`Organization`, missing `headline` on an `Article`, etc., breaks
+schema validity.
+
+**`pass: false` means:** at least one JSON-LD block has missing or
+empty schema.org-required fields for its declared `@type`.
+
+**Why it matters:** answer engines and crawlers may silently drop
+invalid blocks. The page exists, the JSON-LD exists, but the
+citation surface is broken because the block doesn't parse as
+valid schema.org.
+
+**Fix tool:** `add-schema` (#366) — replace the malformed block.
+For one-off edits to MDX, the consumer can also hand-edit the
+JSON-LD inline; `add-schema` is the safer path because it uses
+typed builders.
+
+---
+
+## entity-markup
+
+**Plain language:** somewhere on your site (typically the home
+page or layout root), there should be exactly one identity entity
+JSON-LD — `Organization` if the site represents a business, or
+`Person` if the site represents an individual (a solo lawyer,
+realtor, consultant, author, etc.). The audit picks up on
+`identityMode` (configured in `ailk.config.ts`).
+
+**`pass: false` means:** no `Organization` block (when
+`identityMode: organization`) or no `Person` block (when
+`identityMode: person`) was emitted by any audited page.
+
+**Why it matters:** the identity entity is what ties every other
+piece of structured data together. Without it, schema.org
+relationships (`isPartOf`, `author`, `provider`, `mainEntity`)
+have nothing to anchor to.
+
+**Fix:** Manual MDX or layout edit — ensure your home page (or a
+layout component rendered on every page) emits an
+`Organization` (or `Person`) JSON-LD block. The `<JsonLd
+schema={OrganizationSchema(...)} />` pattern from `@working-theory/schema`
+is the one this is going to ship as. `add-schema` (#366) can land
+the block on a specific page if you'd rather; but typically
+identity goes in a layout, not a leaf page.
+
+---
+
+## faq-howto-incentive
+
+**Plain language:** pages that emit `FAQPage` or `HowTo` schema
+get a small bonus signal. This rule **never fails a page** — it's
+purely incentivizing. Absence of FAQ/HowTo blocks is neutral, not
+a failure.
+
+**`pass: true` and `bonus: true` per page means:** that page
+earned the incentive (has FAQ or HowTo schema).
+
+**`pass: true` and `bonus: false` per page means:** that page is
+fine, just didn't earn the bonus.
+
+**Why it matters:** answer engines preferentially cite pages with
+explicit Q&A or step-by-step content because those are easier to
+quote directly into a generated response. Adding an FAQ or HowTo
+block to relevant pages is a low-effort score boost.
+
+**Fix tool:** `add-schema` (#366) — add an `FAQPage` block to
+your `/pricing` or `/contact` page (anywhere your customers ask
+predictable questions), or a `HowTo` block to any
+process/instructions content. `audit-site` will surface this as
+an _incentive_ in drill-down, not a finding to "fix."
+
+---
+
+## always-passes / always-fails
+
+These are **test rules** that exist for the audit's own test suite
+in `packages/aeo`. They should not appear on a real consumer site
+unless the rule list has been customized. If you see one of these
+IDs in your audit output, the consumer's `ailk-audit` CLI may have
+a non-standard rule list — that's a setup question, not a content
+finding.
+
+---
+
+## Unrecognized rule IDs
+
+If the audit JSON includes a rule ID not listed above, the rule is
+new (added to `packages/aeo` after this glossary was last updated).
+Render it as:
+
+> Rule `<id>` — `<evidence text from the audit JSON>` — not in
+> the local glossary; consult `packages/aeo` upstream docs.
+
+Do not invent a plain-language explanation for an unrecognized
+rule. The consumer can read the rule's `description` field from
+the JSON if they want the formal definition.