create-ailk 0.6.1 → 0.7.0

package/templates/tools/lint-architecture.ts

@@ -0,0 +1,315 @@
+#!/usr/bin/env tsx
+/**
+ * Architecture Boundary Linter — enforces this site's `architecture.yaml`.
+ *
+ * `architecture.yaml` is generated by create-ailk from the selected module
+ * set; this file is what makes it more than prose. It walks `apps/` and
+ * `database/` for .ts/.tsx files and reports:
+ *
+ *   - apps do not import apps — any file under `apps/<a>/` (or `database/`)
+ *     importing `apps/<b>/`, by package name or by relative path, whether or
+ *     not architecture.yaml declares either app;
+ *   - `may_not_import_from` / `may_import_from` per declared app;
+ *   - the global and per-app `forbidden_patterns` (with `paths_excluded`);
+ *   - the `namespaces` boundaries inside `database/`, when declared:
+ *     cross-namespace relative imports and cross-namespace Prisma `@relation`
+ *     directives.
+ *
+ * An import target is checked only when it is a workspace present in this
+ * repo (`apps/*`, `database`); `@working-theory/*` libraries install from npm
+ * and are not source here.
+ *
+ * Usage:
+ *   pnpm architecture            # or: tsx tools/lint-architecture.ts
+ *
+ * Exit codes:
+ *   0 — no violations
+ *   1 — violations found (each names the file, the line and the rule)
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+import { parse as parseYaml } from "yaml";
+
+interface ForbiddenPattern {
+  pattern: string;
+  reason: string;
+  paths_excluded?: string[];
+}
+
+interface AppRule {
+  path: string;
+  may_import_from?: string[];
+  may_not_import_from?: string[];
+  forbidden_patterns?: ForbiddenPattern[];
+}
+
+interface ArchConfig {
+  apps?: Record<string, AppRule>;
+  forbidden_patterns?: ForbiddenPattern[];
+  namespaces?: { members?: Record<string, { path: string }> };
+}
+
+interface Violation {
+  file: string;
+  line: number;
+  rule: string;
+  reason: string;
+}
+
+const ROOT = resolve(dirname(process.argv[1] ?? "."), "..");
+const SKIP_DIRS = new Set([
+  "node_modules",
+  "dist",
+  ".next",
+  ".turbo",
+  ".source",
+  "coverage",
+  "generated",
+]);
+const IMPORT_RE =
+  /(?:^|[\n;])\s*(?:import\s+(?:type\s+)?|export\s+(?:type\s+)?(?=[*{]))[^;'"]*?\bfrom\s+['"]([^'"]+)['"]/g;
+const SIDE_EFFECT_IMPORT_RE = /(?:^|[\n;])\s*import\s+['"]([^'"]+)['"]/g;
+const DYNAMIC_IMPORT_RE = /\b(?:import|require)\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+function toPosix(p: string): string {
+  return p.split(sep).join("/");
+}
+
+function rel(abs: string): string {
+  return toPosix(relative(ROOT, abs));
+}
+
+function walk(dir: string, match: RegExp, out: string[] = []): string[] {
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    const p = join(dir, entry);
+    if (statSync(p).isDirectory()) walk(p, match, out);
+    else if (match.test(entry) && !entry.endsWith(".d.ts")) out.push(p);
+  }
+  return out;
+}
+
+/** Every workspace in this repo: `apps/<name>` for each app dir, plus `database`. */
+function workspacesOnDisk(): string[] {
+  const out: string[] = [];
+  const appsDir = join(ROOT, "apps");
+  if (existsSync(appsDir)) {
+    for (const entry of readdirSync(appsDir).sort()) {
+      if (statSync(join(appsDir, entry)).isDirectory()) out.push(`apps/${entry}`);
+    }
+  }
+  if (existsSync(join(ROOT, "database"))) out.push("database");
+  return out;
+}
+
+/** Package name → workspace, read from each workspace's own package.json. */
+function packageNames(workspaces: string[]): Map<string, string> {
+  const names = new Map<string, string>();
+  for (const ws of workspaces) {
+    const pkgPath = join(ROOT, ws, "package.json");
+    if (!existsSync(pkgPath)) continue;
+    const name = (JSON.parse(readFileSync(pkgPath, "utf8")) as { name?: unknown })
+      .name;
+    if (typeof name === "string") names.set(name, ws);
+  }
+  return names;
+}
+
+function workspaceOfPath(relPath: string, workspaces: string[]): string | null {
+  for (const ws of workspaces) {
+    if (relPath === ws || relPath.startsWith(`${ws}/`)) return ws;
+  }
+  return null;
+}
+
+function extractImports(content: string): { specifier: string; line: number }[] {
+  const lineOf = (offset: number) => content.slice(0, offset).split("\n").length;
+  const out: { specifier: string; line: number }[] = [];
+  for (const re of [IMPORT_RE, SIDE_EFFECT_IMPORT_RE, DYNAMIC_IMPORT_RE]) {
+    for (const m of content.matchAll(re)) {
+      // The newline/semicolon (and blank lines) the static regexes anchor on
+      // belong to earlier lines; count from the import keyword itself.
+      const lead = Math.max(0, m[0].search(/[^\s;]/));
+      if (m[1]) out.push({ specifier: m[1], line: lineOf((m.index ?? 0) + lead) });
+    }
+  }
+  return out;
+}
+
+function resolveTarget(
+  file: string,
+  specifier: string,
+  workspaces: string[],
+  names: Map<string, string>,
+): string | null {
+  if (specifier.startsWith(".")) {
+    return workspaceOfPath(rel(resolve(dirname(file), specifier)), workspaces);
+  }
+  for (const [name, ws] of names) {
+    if (specifier === name || specifier.startsWith(`${name}/`)) return ws;
+  }
+  return null;
+}
+
+function checkImport(
+  fileWs: string,
+  targetWs: string,
+  cfg: ArchConfig,
+): { rule: string; reason: string } | null {
+  if (targetWs.startsWith("apps/")) {
+    return fileWs.startsWith("apps/")
+      ? {
+          rule: `${fileWs} may not import ${targetWs} — apps do not import apps`,
+          reason:
+            "Apps talk over HTTP (web → api) and MCP (mcp → api); shared code belongs in a package.",
+        }
+      : {
+          rule: `${fileWs} may not import ${targetWs} — the data tier imports no app`,
+          reason: "database/ sits below every app; apps import it, never the reverse.",
+        };
+  }
+  const rule = fileWs.startsWith("apps/")
+    ? cfg.apps?.[fileWs.slice("apps/".length)]
+    : undefined;
+  if (!rule) return null;
+  if (rule.may_not_import_from?.includes(targetWs)) {
+    return {
+      rule: `${fileWs} may_not_import_from ${targetWs}`,
+      reason: "Forbidden by architecture.yaml",
+    };
+  }
+  if (rule.may_import_from?.length && !rule.may_import_from.includes(targetWs)) {
+    return {
+      rule: `${fileWs} may_import_from does not include ${targetWs}`,
+      reason: `Not on ${fileWs}'s allowlist in architecture.yaml`,
+    };
+  }
+  return null;
+}
+
+function isExcluded(relPath: string, globs: string[] | undefined): boolean {
+  return (globs ?? []).some((glob) =>
+    glob.endsWith("/**") ? relPath.startsWith(glob.slice(0, -2)) : relPath === glob,
+  );
+}
+
+function checkForbiddenPattern(
+  file: string,
+  content: string,
+  fp: ForbiddenPattern,
+): Violation[] {
+  if (isExcluded(rel(file), fp.paths_excluded)) return [];
+  const re = new RegExp(fp.pattern);
+  const out: Violation[] = [];
+  content.split("\n").forEach((text, i) => {
+    if (re.test(text)) {
+      out.push({ file, line: i + 1, rule: `forbidden_pattern: ${fp.pattern}`, reason: fp.reason });
+    }
+  });
+  return out;
+}
+
+/** Namespace boundaries inside database/ — imports and Prisma @relation. */
+function checkNamespaces(cfg: ArchConfig): Violation[] {
+  const members = Object.values(cfg.namespaces?.members ?? {}).map((m) => m.path);
+  if (members.length === 0) return [];
+  const nsOf = (relPath: string) => workspaceOfPath(relPath, members);
+  const dbDir = join(ROOT, "database");
+  const out: Violation[] = [];
+
+  for (const file of walk(dbDir, /\.tsx?$/)) {
+    const fromNs = nsOf(rel(file));
+    if (!fromNs) continue;
+    for (const imp of extractImports(readFileSync(file, "utf8"))) {
+      if (!imp.specifier.startsWith(".")) continue;
+      const toNs = nsOf(rel(resolve(dirname(file), imp.specifier)));
+      if (!toNs || toNs === fromNs) continue;
+      out.push({
+        file,
+        line: imp.line,
+        rule: `cross-namespace-import: ${fromNs} may not import ${toNs}`,
+        reason: "Cross-namespace data assembly routes through apps/api.",
+      });
+    }
+  }
+
+  const prismaFiles = walk(dbDir, /\.prisma$/);
+  const modelNs = new Map<string, string>();
+  for (const file of prismaFiles) {
+    const ns = nsOf(rel(file));
+    if (!ns) continue;
+    for (const m of readFileSync(file, "utf8").matchAll(/^\s*model\s+(\w+)\s*\{/gm)) {
+      if (m[1] && !modelNs.has(m[1])) modelNs.set(m[1], ns);
+    }
+  }
+  const relationLine = /^\s*\w+\s+(\w+)(\?|\[\])?\s+@relation\s*\(/;
+  for (const file of prismaFiles) {
+    const fromNs = nsOf(rel(file));
+    if (!fromNs) continue;
+    readFileSync(file, "utf8")
+      .split("\n")
+      .forEach((text, i) => {
+        const model = relationLine.exec(text)?.[1];
+        const toNs = model ? modelNs.get(model) : undefined;
+        if (!toNs || toNs === fromNs) return;
+        out.push({
+          file,
+          line: i + 1,
+          rule: `cross-namespace-prisma-relation: ${fromNs} may not relate to ${toNs}`,
+          reason: `@relation to model '${model}' crosses a namespace boundary.`,
+        });
+      });
+  }
+  return out;
+}
+
+function main(): void {
+  const yamlPath = join(ROOT, "architecture.yaml");
+  if (!existsSync(yamlPath)) {
+    console.error(`architecture: no architecture.yaml at ${ROOT}`);
+    process.exitCode = 1;
+    return;
+  }
+  const cfg = (parseYaml(readFileSync(yamlPath, "utf8")) ?? {}) as ArchConfig;
+  const workspaces = workspacesOnDisk();
+  const names = packageNames(workspaces);
+  const violations: Violation[] = [];
+
+  for (const ws of workspaces) {
+    for (const file of walk(join(ROOT, ws), /\.tsx?$/)) {
+      const content = readFileSync(file, "utf8");
+      for (const imp of extractImports(content)) {
+        const targetWs = resolveTarget(file, imp.specifier, workspaces, names);
+        if (!targetWs || targetWs === ws) continue;
+        const v = checkImport(ws, targetWs, cfg);
+        if (v) violations.push({ file, line: imp.line, ...v });
+      }
+      for (const fp of cfg.forbidden_patterns ?? []) {
+        violations.push(...checkForbiddenPattern(file, content, fp));
+      }
+      const app = ws.startsWith("apps/") ? cfg.apps?.[ws.slice("apps/".length)] : undefined;
+      for (const fp of app?.forbidden_patterns ?? []) {
+        violations.push(...checkForbiddenPattern(file, content, fp));
+      }
+    }
+  }
+  violations.push(...checkNamespaces(cfg));
+
+  if (violations.length === 0) {
+    console.log("architecture: OK");
+    return;
+  }
+  console.error(`architecture: ${violations.length} violation(s)`);
+  for (const v of violations) {
+    console.error(`  ${rel(v.file)}:${v.line}  ${v.rule}`);
+    console.error(`    ${v.reason}`);
+  }
+  // exitCode, not exit(): stderr to a pipe is asynchronous on macOS, and the
+  // hook reads this report through one.
+  process.exitCode = 1;
+}
+
+main();

package/templates/tools/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["*.ts"]
+}

package/versions.json

@@ -1,39 +1,39 @@
 {
-  "@working-theory/admin-ui": "0.26.0",
-  "@working-theory/aeo": "0.26.0",
-  "@working-theory/agent-context": "0.26.0",
+  "@working-theory/admin-ui": "0.27.0",
+  "@working-theory/aeo": "0.27.0",
+  "@working-theory/agent-context": "0.27.0",
   "@working-theory/agent-contract": "0.1.0",
   "@working-theory/agent-memory": "0.0.0",
   "@working-theory/ai": "0.1.0",
-  "@working-theory/analytics": "0.26.0",
-  "@working-theory/api-client": "0.26.0",
+  "@working-theory/analytics": "0.27.0",
+  "@working-theory/api-client": "0.27.0",
   "@working-theory/cda-filesystem": "0.0.0",
-  "@working-theory/cli": "0.26.0",
-  "@working-theory/common": "0.26.0",
+  "@working-theory/cli": "0.27.0",
+  "@working-theory/common": "0.27.0",
   "@working-theory/consent": "0.1.0",
-  "@working-theory/content-adapters": "0.26.0",
-  "@working-theory/content-projection": "0.26.0",
-  "@working-theory/email": "0.26.0",
+  "@working-theory/content-adapters": "0.27.0",
+  "@working-theory/content-projection": "0.27.0",
+  "@working-theory/email": "0.27.0",
   "@working-theory/env": "0.0.0",
-  "@working-theory/eslint-config": "0.26.0",
-  "@working-theory/fumadocs-schema": "0.26.0",
+  "@working-theory/eslint-config": "0.27.0",
+  "@working-theory/fumadocs-schema": "0.27.0",
   "@working-theory/ids": "0.8.0",
-  "@working-theory/jsonld": "0.26.0",
-  "@working-theory/license": "0.26.0",
-  "@working-theory/metadata": "0.26.0",
-  "@working-theory/observability": "0.26.0",
-  "@working-theory/page-renderer": "0.26.0",
-  "@working-theory/schema": "0.26.0",
-  "@working-theory/schema-pack-registry": "0.26.0",
-  "@working-theory/schema-validator": "0.26.0",
-  "@working-theory/sections-registry": "0.26.0",
-  "@working-theory/site-config": "0.26.0",
-  "@working-theory/stripe-client": "0.26.0",
-  "@working-theory/templates": "0.26.0",
-  "@working-theory/theme": "0.26.0",
-  "@working-theory/ui": "0.26.0",
-  "@working-theory/validation": "0.26.0",
-  "@working-theory/web-i18n": "0.26.0",
+  "@working-theory/jsonld": "0.27.0",
+  "@working-theory/license": "0.27.0",
+  "@working-theory/metadata": "0.27.0",
+  "@working-theory/observability": "0.27.0",
+  "@working-theory/page-renderer": "0.27.0",
+  "@working-theory/schema": "0.27.0",
+  "@working-theory/schema-pack-registry": "0.27.0",
+  "@working-theory/schema-validator": "0.27.0",
+  "@working-theory/sections-registry": "0.27.0",
+  "@working-theory/site-config": "0.27.0",
+  "@working-theory/stripe-client": "0.27.0",
+  "@working-theory/templates": "0.27.0",
+  "@working-theory/theme": "0.27.0",
+  "@working-theory/ui": "0.27.0",
+  "@working-theory/validation": "0.27.0",
+  "@working-theory/web-i18n": "0.27.0",
   "@working-theory/billing-client": "0.0.0",
   "@working-theory/branding": "0.0.0",
   "@working-theory/license-client": "0.0.0",
@@ -41,12 +41,12 @@
   "@working-theory/marketing-api-client": "0.0.0",
   "@working-theory/partner-session": "0.0.0",
   "@working-theory/preview-protocol": "0.0.0",
-  "@working-theory/ui-commerce": "0.23.3",
-  "@working-theory/ui-docs-blog": "0.23.3",
-  "@working-theory/ui-scheduling": "0.23.3",
-  "@working-theory/ui-signal-collectors": "0.24.1",
+  "@working-theory/ui-commerce": "0.23.4",
+  "@working-theory/ui-docs-blog": "0.23.4",
+  "@working-theory/ui-scheduling": "0.23.4",
+  "@working-theory/ui-signal-collectors": "0.24.2",
   "@working-theory/web": "0.0.0",
   "@working-theory/api": "1.0.0",
   "@working-theory/mcp": "0.0.0",
-  "@working-theory/database": "0.26.0"
+  "@working-theory/database": "0.27.0"
 }

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

@@ -1,277 +0,0 @@
----
-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 the general schema.org vocabulary
-it curates as **primary** or **supplementary**; the AILK page-type
-registry (60 keys, all builder-backed in `@working-theory/schema`) is
-listed separately in that file's "AILK page types" section and is
-treated as **primary** for conflict handling — a registry page type
-names what the whole page IS about, and replacing on same-type
-conflict is the usual intent:
-
-- **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 60 AILK page types in `@working-theory/schema` by
-name, plus a smaller general schema.org vocabulary for non-registry types.
-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
-> 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 60 registry-backed AILK page types
-  from `@working-theory/schema`, plus a smaller general schema.org
-  vocabulary 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.