create-ailk 0.10.0 → 0.11.0

package/templates/.claude/skills/add-page/scripts/site-pages.mjs

@@ -1,87 +0,0 @@
-#!/usr/bin/env node
-// site-pages.mjs — report what THIS site can serve, read from the site itself.
-//
-// Usage: node .claude/skills/add-page/scripts/site-pages.mjs [--json] [<site-root>]
-//
-// It scans apps/web/app/[locale]/**/page.tsx for the page type each route
-// renders (the `type: "X"` literal in renderPage / renderPageMetadata, or a
-// getMdxSource("X", …) call), then pairs each type with its content folder and
-// the pages already written there. It also echoes .ailk-site-manifest.json's
-// shape, design and (when recorded) level. Read-only: it never writes.
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join, relative, sep } from "node:path";
-
-const args = process.argv.slice(2);
-const asJson = args.includes("--json");
-const root = args.find((a) => !a.startsWith("--")) ?? process.cwd();
-const appRoot = join(root, "apps/web/app/[locale]");
-if (!existsSync(appRoot)) {
-  console.error(`site-pages: ${appRoot} not found — run from the site's root.`);
-  process.exit(2);
-}
-
-// Types whose content lives outside content/<locale>/<Type>.
-const CONTENT_OVERRIDES = {
-  BlogPosting: "apps/web/content/en/blog",
-  BlogList: "apps/web/content/en/blog",
-  DocsDetail: "apps/web/content/en/docs",
-  DocsList: "apps/web/content/en/docs",
-};
-
-function walk(dir, out = []) {
-  for (const name of readdirSync(dir)) {
-    const abs = join(dir, name);
-    if (name === "__tests__" || name === "node_modules") continue;
-    if (statSync(abs).isDirectory()) walk(abs, out);
-    else if (name === "page.tsx") out.push(abs);
-  }
-  return out;
-}
-
-const routes = [];
-for (const file of walk(appRoot)) {
-  const src = readFileSync(file, "utf8");
-  const types = new Set();
-  for (const m of src.matchAll(/type:\s*"([A-Z][A-Za-z]+)"/g)) types.add(m[1]);
-  for (const m of src.matchAll(/getMdxSource\(\s*"([A-Z][A-Za-z]+)"/g)) types.add(m[1]);
-  const dir = relative(appRoot, file).split(sep).slice(0, -1);
-  // Route groups like (auth) do not appear in the URL.
-  const path = "/" + dir.filter((s) => !/^\(.*\)$/.test(s)).join("/");
-  const dynamic = dir.some((s) => s.startsWith("["));
-  routes.push({ route: path === "/" ? "/" : path, file: relative(root, file), types: [...types], dynamic });
-}
-
-const byType = {};
-for (const r of routes) {
-  for (const t of r.types) {
-    const entry = (byType[t] ??= { type: t, routes: [], contentDir: CONTENT_OVERRIDES[t] ?? `content/en/${t}`, pages: [] });
-    entry.routes.push(r.route);
-  }
-}
-for (const e of Object.values(byType)) {
-  const abs = join(root, e.contentDir);
-  if (existsSync(abs)) {
-    e.pages = readdirSync(abs).filter((f) => /\.mdx?$/.test(f)).map((f) => f.replace(/\.mdx?$/, ""));
-  }
-  // A type served by a dynamic route takes new pages; a static-only type is one page.
-  e.takesNewPages = routes.some((r) => r.dynamic && r.types.includes(e.type));
-}
-
-let manifest = null;
-const manifestPath = join(root, ".ailk-site-manifest.json");
-if (existsSync(manifestPath)) {
-  const m = JSON.parse(readFileSync(manifestPath, "utf8"));
-  manifest = { shape: m.shape ?? null, design: m.design ?? null, level: m.level ?? null, modules: m.modules ?? m.requires ?? null };
-}
-
-const result = { manifest, types: Object.values(byType).sort((a, b) => a.type.localeCompare(b.type)) };
-if (asJson) {
-  console.log(JSON.stringify(result, null, 2));
-} else {
-  if (manifest) console.log(`shape: ${manifest.shape}  design: ${manifest.design}  level: ${manifest.level ?? "(not recorded)"}`);
-  console.log("");
-  console.log("type".padEnd(22) + "route(s)".padEnd(34) + "new pages?".padEnd(12) + "existing");
-  for (const e of result.types) {
-    console.log(e.type.padEnd(22) + e.routes.join(" ").padEnd(34) + (e.takesNewPages ? "yes" : "no").padEnd(12) + (e.pages.join(", ") || "—"));
-  }
-}

package/templates/.claude/skills/add-page/templates/comparison-page.mdx.tmpl

@@ -1,99 +0,0 @@
----
-type: ComparisonPage
-slug: {{SLUG}}
-placeholder: true
-title: {{TITLE}}
-description: {{DESCRIPTION}}
-sections:
-  [
-    {
-      "id": "hero",
-      "type": "hero",
-      "data":
-        {
-          "eyebrow": "Comparisons",
-          "headline": "{{TITLE}}",
-          "subheadline": "{{DESCRIPTION}}",
-          "primaryCta": { "label": "{Primary CTA}", "href": "/contact" },
-        },
-    },
-    {
-      "id": "decision-split",
-      "type": "decision-split",
-      "data":
-        {
-          "headline": "{Which one fits you}",
-          "panels":
-            [
-              {
-                "title": "{{TITLE}}",
-                "checklist":
-                  [
-                    "{Reason 1 to choose us}",
-                    "{Reason 2 to choose us}",
-                    "{Reason 3 to choose us}",
-                  ],
-              },
-              {
-                "title": "{The alternative}",
-                "glyph": "cross",
-                "checklist":
-                  [
-                    "{Reason 1 to choose them instead}",
-                    "{Reason 2 to choose them instead}",
-                  ],
-              },
-            ],
-        },
-    },
-    {
-      "id": "comparison-table",
-      "type": "comparison-table",
-      "data":
-        {
-          "headline": "{How they compare}",
-          "columns":
-            [
-              { "key": "us", "name": "{{TITLE}}", "highlighted": true },
-              { "key": "them", "name": "{The alternative}" },
-            ],
-          "groups":
-            [
-              {
-                "groupName": "{Core features}",
-                "rows":
-                  [
-                    {
-                      "featureName": "{Feature 1}",
-                      "values": { "us": true, "them": false },
-                    },
-                    {
-                      "featureName": "{Feature 2}",
-                      "values": { "us": true, "them": true },
-                    },
-                  ],
-              },
-            ],
-        },
-    },
-    {
-      "id": "cta",
-      "type": "cta",
-      "data":
-        {
-          "variant": "box",
-          "headline": "{Ready to switch?}",
-          "description": "{One sentence on what happens next}",
-          "primaryCta": { "label": "{Primary CTA}", "href": "/contact" },
-          "secondaryCta":
-            {
-              "label": "See all alternatives",
-              "href": "/alternatives",
-              "variant": "outline",
-            },
-        },
-    },
-  ]
----
-
-{/* Rendered from frontmatter `sections[]` by the /vs/<slug> route (D10 — the generic detail chassis: hero, decision-split, comparison-table, cta; no dedicated comparison section). Listed automatically by the /alternatives hub. Placeholder copy — replace every {brace} with your own words before you launch. */}

package/templates/.claude/skills/add-page/templates/content.mdx.tmpl

@@ -1,18 +0,0 @@
----
-type: {{TYPE}}
-slug: {{SLUG}}
-title: {{TITLE}}
-description: {{DESCRIPTION}}
----
-
-{/*
-  Written by the add-page skill, used only when this site had no other page of
-  this type to copy. The frontmatter drives the page's route and its JSON-LD:
-  keep `type` as it is, and make `description` a true one-sentence summary.
-  Run `fill-page` to write the real copy, then `check-site` to score it.
-  Extra structured data goes in a `schema:` block — see the add-page skill.
-*/}
-
-# {{TITLE}}
-
-{{DESCRIPTION}}

package/templates/.claude/skills/add-page/templates/flow-landing-page.mdx.tmpl

@@ -1,43 +0,0 @@
----
-type: LandingPage
-slug: {{SLUG}}
-placeholder: true
-title: {{TITLE}}
-description: {{DESCRIPTION}}
-sections:
-  [
-    {
-      "id": "hero",
-      "type": "hero",
-      "data":
-        {
-          "variant": "centered",
-          "eyebrow": "{{TITLE}}",
-          "headline": "{{TITLE}}",
-          "subheadline": "{{DESCRIPTION}}",
-          "primaryCta":
-            { "label": "{Get started →}", "href": "/flows/{{FLOW_SLUG}}/start" },
-          "ctaSize": "xl",
-        },
-    },
-    {
-      "id": "request",
-      "type": "cta",
-      "data":
-        {
-          "variant": "minimal",
-          "headline": "{Ready?}",
-          "primaryCta":
-            { "label": "{Get started →}", "href": "/flows/{{FLOW_SLUG}}/start" },
-        },
-    },
-  ]
----
-
-{/* This page's CTA opens the `{{FLOW_SLUG}}` flow at
-    /flows/{{FLOW_SLUG}}/start — a signal-collectors module route, not a page
-    this seed owns. The flow definition itself
-    (`database/flows/{{FLOW_SLUG}}.flow.json`) is a separate artifact this
-    skill does not write; seed it via the flow engine before this page's CTA
-    resolves. Placeholder copy — replace every {brace} with your own words
-    before you launch. */}

package/templates/.claude/skills/add-page/templates/report-page.mdx.tmpl

@@ -1,52 +0,0 @@
----
-type: ReportPage
-slug: {{SLUG}}
-placeholder: true
-title: {{TITLE}}
-description: {{DESCRIPTION}}
-schema:
-  datePublished: "{{DATE_PUBLISHED}}"
-  author:
-    "@type": Organization
-    name: "{Your Company}"
-sections:
-  [
-    {
-      "id": "header",
-      "type": "report-header",
-      "data":
-        {
-          "title": "{{TITLE}}",
-          "eyebrow": "{{DATE_LABEL}}",
-          "backHref": "/reports",
-          "backLabel": "All reports",
-          "tone": "on-dark",
-        },
-    },
-    {
-      "id": "document",
-      "type": "document-viewer",
-      "data":
-        {
-          "src": "/reports/sample-report.pdf",
-          "geometry": "16:9",
-          "pages": 8,
-          "downloadFilename": "{{SLUG}}.pdf",
-          "outline":
-            [
-              { "id": "opening", "label": "Opening", "startPage": 1 },
-              { "id": "findings", "label": "Findings", "startPage": 3 },
-              { "id": "outlook", "label": "Outlook", "startPage": 6 },
-            ],
-        },
-    },
-  ]
----
-
-{/* A PLACEHOLDER report. Its bytes are the signal-collectors module's own
-    sample PDF (apps/web/public/reports/sample-report.pdf), shared by every
-    sample report so the site ships no binary of its own. Point `src` at your
-    real document and set `pages` to its real page count. Rendered by the
-    signal-collectors module's own /reports/<slug> route (`app/[locale]/reports/[slug]/page.tsx`)
-    and listed automatically by the /reports hub (ReportsList) — never
-    hand-list a report there. */}

package/templates/.claude/skills/add-page/templates/reports-list.mdx.tmpl

@@ -1,38 +0,0 @@
----
-type: ReportsList
-slug: reports
-placeholder: true
-title: {{TITLE}}
-description: {{DESCRIPTION}}
-sections:
-  [
-    {
-      "id": "hero",
-      "type": "hero",
-      "data":
-        {
-          "variant": "centered",
-          "eyebrow": "Reports",
-          "headline": "{{TITLE}}",
-          "subheadline": "{{DESCRIPTION}}",
-        },
-    },
-    {
-      "id": "closing",
-      "type": "cta",
-      "data":
-        {
-          "variant": "minimal",
-          "headline": "{Want the next one as it lands?}",
-          "primaryCta": { "label": "{Contact me →}", "href": "/contact" },
-        },
-    },
-  ]
----
-
-{/* Rendered from frontmatter `sections[]` by the /reports route
-    (`app/[locale]/reports/page.tsx`). Its card list is GENERATED, not
-    authored here (spec 6892 D2): the route appends one `reports-list`
-    section listing every ReportPage seed, so this seed carries only its own
-    hero and closing cta. Placeholder copy — replace every {brace} with your
-    own words before you launch. */}

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

@@ -1,245 +0,0 @@
----
-name: check-site
-description: Run `ailk-audit --format 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.
----
-
-# check-site
-
-Shell out to `ailk-audit --format 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 the `schema:` frontmatter override)
-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-page`'s `schema:` frontmatter override) and stop. This skill reports;
-  fix tools fix.
-- The consumer is asking about deploy-time monitoring or continuous
-  audits — those are Pro features (the `upgrade-plan` skill explains
-  the levels). Mention briefly and stop.
-- The audit CLI isn't installed (`apps/api/node_modules/.bin/ailk-audit`
-  is missing) — translate the error per "Common errors" below.
-
-## The mechanic
-
-### Step 0 — Read what this site can render
-
-Read `.ailk-site-manifest.json` at the site root, the site's roster of
-record:
-
-- `modules` — the modules this site has. Add any module the
-  `# Modules:` line of `architecture.yaml` names that `modules` does not:
-  `create-ailk add-module` records a module it adds there. With no
-  manifest, or none carrying `modules`, that line is the set.
-- `rows` — every route the site carries and the page type each renders.
-- `level` — present only when the scaffold derived it from the licence
-  key. It never decides what to suggest; `modules` does.
-
-A page type renders on this site only when its **Module** in
-`.claude/skills/add-page/references/page-types.md` is in that set.
-Step 7 suggests a page only of such a type.
-
-### Step 1 — Invoke the CLI
-
-The `ailk-audit` CLI ships in `@working-theory/aeo`, which the scaffold
-installs as a dependency of `apps/api` — not of the site root — so pnpm
-links its bin at `apps/api/node_modules/.bin/ailk-audit`. Run it **from
-the site root**:
-
-```bash
-apps/api/node_modules/.bin/ailk-audit --format json
-```
-
-The site root matters: the CLI reads `content/` (its `--content-root`
-default) and `project.yaml` relative to the directory it runs in. Do not
-run it through `pnpm --filter ./apps/api exec`, which runs it inside
-`apps/api` where neither exists. `--format json` is the flag that
-selects JSON; the CLI rejects any flag it does not know and exits 2.
-
-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 is the `AuditReport` type `@working-theory/aeo` exports
-(its shipped `dist/types.d.ts`, under
-`apps/api/node_modules/@working-theory/aeo/`):
-
-```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-page`'s `schema:` frontmatter override — add the missing schema type to the named page |
-| `jsonld-validity`     | `add-page`'s `schema:` frontmatter override — 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-page`'s `schema:` frontmatter override — add an `FAQPage` or `HowTo` block to a relevant page |
-
-When a fix means adding a page, name only a page type this site can
-render (Step 0) — for `faq-howto-incentive`, a `FAQPage` or `HowTo`
-page, never one the site's modules do not render. When only a type the
-site cannot render would fix a finding, say which module renders it and
-which level carries it, and point at the `upgrade-plan` skill.
-
-Phrase the pointer as a single sentence:
-
-> "Missing `Product` schema on `/pricing` — add it via `add-page`'s
-> `schema:` frontmatter override."
-
-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 —
-  > the `upgrade-plan` skill explains the levels."
-
-- **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 — the `upgrade-plan` skill explains the levels."
-
-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 the `schema:` frontmatter override, documented in `add-page`).
-- Create new pages (that's `add-page`).
-- 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-page`'s `schema:` frontmatter override** — primary fix
-  mechanism the skill points at. Never auto-invoked.
-- **`add-page`** — new-page creation; not a fix-tool
-  for audit findings (audit reports on existing pages).
-- **`@working-theory/aeo`** — owner of the `ailk-audit` CLI and rule
-  set, installed under `apps/api`. This skill depends only on the
-  CLI's `--format 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).