@tmorrow/cre8-wc 2.3.0 → 2.3.2

package/a2ui/catalog.compact.json

@@ -1,7 +1,7 @@
 {
   "contractVersion": 1,
-  "sourceCatalog": "https://cre8.dev/a2ui/catalogs/cre8-wc/2.2.2",
-  "libraryVersion": "2.2.2",
+  "sourceCatalog": "https://cre8.dev/a2ui/catalogs/cre8-wc/2.3.1",
+  "libraryVersion": "2.3.1",
   "componentCount": 86,
   "components": [
     {
@@ -1662,7 +1662,7 @@
     },
     {
       "name": "cre8-progress-steps",
-      "category": "Other",
+      "category": "Feedback",
       "props": {
         "steps": {
           "type": "array"

package/a2ui/catalog.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cre8.dev/a2ui/catalogs/cre8-wc/2.2.2",
+  "$id": "https://cre8.dev/a2ui/catalogs/cre8-wc/2.3.1",
   "title": "cre8-wc A2UI Catalog",
   "description": "cre8 Web Components is a library of presentational UI web components to be consumed by # web applications.",
   "x-native-events": [
@@ -54,7 +54,7 @@
   "x-a2ui": {
     "catalogId": "cre8-wc",
     "library": "@tmorrow/cre8-wc",
-    "libraryVersion": "2.2.2",
+    "libraryVersion": "2.3.1",
     "tagPrefix": "cre8",
     "framework": "Lit 3.3.1"
   },
@@ -167,6 +167,9 @@
         {
           "$ref": "#/$defs/components/cre8-progress-meter"
         },
+        {
+          "$ref": "#/$defs/components/cre8-progress-steps"
+        },
         {
           "$ref": "#/$defs/components/cre8-progress-steps-item"
         },
@@ -317,9 +320,6 @@
         {
           "$ref": "#/$defs/components/cre8-utility-nav-item"
         },
-        {
-          "$ref": "#/$defs/components/cre8-progress-steps"
-        },
         {
           "$ref": "#/$defs/components/cre8-heading"
         },
@@ -3291,6 +3291,74 @@
         },
         "additionalProperties": false
       },
+      "cre8-progress-steps": {
+        "type": "object",
+        "title": "cre8-progress-steps",
+        "x-category": "Feedback",
+        "description": "The Progress Steps component is used to display where a user is in a multistep process.\nIt clearly indicates the total number of steps, which steps are complete and incomplete,\nand which step you’re currently on. They help users estimate how long a task will take and can be\nused to track status on orders.\n\nThe Progress Steps component should be used as a parent component for `cre8-progress-steps-item` components.\nThese Components serve a contextual purpose and don't provide any functionality.\n\n# How to Use\n\nProgress Steps is used when there is ample horizontal space and two to six steps. It displays each step by name\nand number to help users understand exactly where they are in a process. It is the preferred option for desktop.\nProgress Steps should change to Compact Steps on mobile web to conserve space.\n\nProgress Steps can also be used to track order status. It provides a quick visual of how an order is progressing\nwith options to alert users of any problems along the way. When used for order status, Progress Steps should\nchange to Vertical Steps on mobile web to conserve space while allowing alerts and messages to remain visible.",
+        "required": [
+          "component"
+        ],
+        "properties": {
+          "component": {
+            "const": "cre8-progress-steps",
+            "description": "Component tag name"
+          },
+          "props": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "steps": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "name": {
+                      "type": "string"
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "state": {
+                      "type": "string",
+                      "enum": [
+                        "error",
+                        "warning",
+                        "complete",
+                        "current"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "name"
+                  ],
+                  "additionalProperties": false
+                },
+                "description": "Steps for a data-driven progress indicator. Note that the visible label is\neach item's `name` prop rather than its content — `cre8-progress-steps-item`\ndoes not render children, which is easy to get wrong by hand.",
+                "x-kind": "attribute"
+              }
+            }
+          },
+          "children": {
+            "type": "array",
+            "description": "The Progress Steps Item components that represent the steps in the multistep process.",
+            "items": {
+              "$ref": "#/$defs/Child"
+            }
+          },
+          "events": {
+            "type": "object",
+            "description": "Event bindings. Each key is an event name; the value names the handler to emit.",
+            "propertyNames": {
+              "$ref": "#/$defs/NativeEventName"
+            },
+            "additionalProperties": {
+              "$ref": "#/$defs/EventBinding"
+            }
+          }
+        },
+        "additionalProperties": false
+      },
       "cre8-progress-steps-item": {
         "type": "object",
         "title": "cre8-progress-steps-item",
@@ -7402,74 +7470,6 @@
         },
         "additionalProperties": false
       },
-      "cre8-progress-steps": {
-        "type": "object",
-        "title": "cre8-progress-steps",
-        "x-category": "Other",
-        "description": "The Progress Steps component is used to display where a user is in a multistep process.\nIt clearly indicates the total number of steps, which steps are complete and incomplete,\nand which step you’re currently on. They help users estimate how long a task will take and can be\nused to track status on orders.\n\nThe Progress Steps component should be used as a parent component for `cre8-progress-steps-item` components.\nThese Components serve a contextual purpose and don't provide any functionality.\n\n# How to Use\n\nProgress Steps is used when there is ample horizontal space and two to six steps. It displays each step by name\nand number to help users understand exactly where they are in a process. It is the preferred option for desktop.\nProgress Steps should change to Compact Steps on mobile web to conserve space.\n\nProgress Steps can also be used to track order status. It provides a quick visual of how an order is progressing\nwith options to alert users of any problems along the way. When used for order status, Progress Steps should\nchange to Vertical Steps on mobile web to conserve space while allowing alerts and messages to remain visible.",
-        "required": [
-          "component"
-        ],
-        "properties": {
-          "component": {
-            "const": "cre8-progress-steps",
-            "description": "Component tag name"
-          },
-          "props": {
-            "type": "object",
-            "additionalProperties": false,
-            "properties": {
-              "steps": {
-                "type": "array",
-                "items": {
-                  "type": "object",
-                  "properties": {
-                    "name": {
-                      "type": "string"
-                    },
-                    "message": {
-                      "type": "string"
-                    },
-                    "state": {
-                      "type": "string",
-                      "enum": [
-                        "error",
-                        "warning",
-                        "complete",
-                        "current"
-                      ]
-                    }
-                  },
-                  "required": [
-                    "name"
-                  ],
-                  "additionalProperties": false
-                },
-                "description": "Steps for a data-driven progress indicator. Note that the visible label is\neach item's `name` prop rather than its content — `cre8-progress-steps-item`\ndoes not render children, which is easy to get wrong by hand.",
-                "x-kind": "attribute"
-              }
-            }
-          },
-          "children": {
-            "type": "array",
-            "description": "The Progress Steps Item components that represent the steps in the multistep process.",
-            "items": {
-              "$ref": "#/$defs/Child"
-            }
-          },
-          "events": {
-            "type": "object",
-            "description": "Event bindings. Each key is an event name; the value names the handler to emit.",
-            "propertyNames": {
-              "$ref": "#/$defs/NativeEventName"
-            },
-            "additionalProperties": {
-              "$ref": "#/$defs/EventBinding"
-            }
-          }
-        },
-        "additionalProperties": false
-      },
       "cre8-heading": {
         "type": "object",
         "title": "cre8-heading",

package/a2ui/check-deploy-drift.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * Deployment-drift check for the knowledge graph.
+ *
+ * Generation keeps catalog-kg.json honest with the library it was built from.
+ * It does nothing about a copy of that file that was deployed and then left
+ * behind — which is how the Claude plugin served 1.0.27 (via the unscoped
+ * `cre8-mcp` package) while the checkout was on 2.3.x. This script compares the local graph against every other place
+ * one is served from and exits non-zero if any of them differ.
+ *
+ * Targets, each optional:
+ *   --url <base>         a running cre8-mcp API (a Vercel deployment, a local
+ *                        dev server).
+ *                        Fetches <base>/a2ui/runtime/catalog-kg.json.
+ *                        Repeatable. Also read from CRE8_MCP_URLS (comma-separated).
+ *   --file <path>        another checkout or bundle's catalog-kg.json
+ *                        (a plugin's vendored copy, an npm tarball). Repeatable.
+ *   --npm [<version>]    the published @tmorrow/cre8-wc package (latest by
+ *                        default) — what anyone installing the connector gets.
+ *   --plugin <.mcp.json> a Claude plugin's server config. Resolves the npm
+ *                        package its `npx` line runs, then checks the
+ *                        @tmorrow/cre8-wc that package depends on. This is
+ *                        the surface that drifted furthest: the plugin ran
+ *                        the unscoped `cre8-mcp` (0.5.0, Feb 2026), which
+ *                        bundles its own 1.0.27 manifest and depends on no
+ *                        design-system package at all.
+ *
+ *   pnpm --filter @tmorrow/cre8-wc check:deploy-drift -- --npm --plugin .claude/marketplaces/tmorrow_ai/cre8/.mcp.json
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const localPath = resolve(__dirname, 'catalog-kg.json');
+
+const args = process.argv.slice(2);
+const urls = (process.env.CRE8_MCP_URLS ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+const files = [];
+const plugins = [];
+let npm = null;
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--url') urls.push(args[++i]);
+    else if (args[i] === '--file') files.push(args[++i]);
+    else if (args[i] === '--plugin') plugins.push(args[++i]);
+    else if (args[i] === '--npm') npm = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : 'latest';
+    else { console.error(`unknown argument ${args[i]}`); process.exit(2); }
+}
+if (!urls.length && !files.length && !npm && !plugins.length) {
+    console.error('nothing to compare against: pass --url, --file or --npm (or set CRE8_MCP_URLS)');
+    process.exit(2);
+}
+
+const fingerprint = (kg) => ({
+    library_version: kg.meta?.library_version ?? null,
+    components: kg.nodes?.filter((n) => n.type === 'component').length ?? 0,
+    categories: kg.nodes?.filter((n) => n.type === 'category').length ?? 0,
+    contains_edges: kg.meta?.contains_edges ?? kg.edges?.filter((e) => e.rel === 'CONTAINS').length ?? 0,
+    patterns: kg.nodes?.filter((n) => n.type === 'pattern').length ?? 0,
+    sha256: createHash('sha256').update(JSON.stringify({ nodes: kg.nodes, edges: kg.edges })).digest('hex').slice(0, 12),
+});
+
+const local = fingerprint(JSON.parse(readFileSync(localPath, 'utf8')));
+const targets = [];
+
+for (const url of urls) {
+    const endpoint = `${url.replace(/\/$/, '')}/a2ui/runtime/catalog-kg.json`;
+    try {
+        const res = await fetch(endpoint);
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        targets.push({ name: endpoint, fp: fingerprint(await res.json()) });
+    } catch (err) {
+        targets.push({ name: endpoint, error: err?.message ?? String(err) });
+    }
+}
+for (const file of files) {
+    try {
+        targets.push({ name: file, fp: fingerprint(JSON.parse(readFileSync(resolve(file), 'utf8'))) });
+    } catch (err) {
+        targets.push({ name: file, error: err?.message ?? String(err) });
+    }
+}
+/** The catalog-kg.json inside a published @tmorrow/cre8-wc, or an error. */
+function fromNpm(spec) {
+    const dir = mkdtempSync(join(tmpdir(), 'cre8-kg-'));
+    try {
+        const tgz = execSync(`npm pack ${spec} --pack-destination ${dir} --silent`, { encoding: 'utf8' }).trim().split('\n').pop();
+        execSync(`tar -xzf ${join(dir, tgz)} -C ${dir} package/a2ui/catalog-kg.json`);
+        return { fp: fingerprint(JSON.parse(readFileSync(join(dir, 'package', 'a2ui', 'catalog-kg.json'), 'utf8'))) };
+    } catch (err) {
+        return { error: `no catalog-kg.json in the published package (${err?.message?.split('\n')[0] ?? err})` };
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+if (npm) {
+    const name = `@tmorrow/cre8-wc@${npm}`;
+    targets.push({ name, ...fromNpm(name) });
+}
+
+for (const file of plugins) {
+    let label = file;
+    try {
+        const cfg = JSON.parse(readFileSync(resolve(file), 'utf8'));
+        const servers = Object.values(cfg.mcpServers ?? {});
+        const server = servers.find((s) => s.command === 'npx') ?? servers[0];
+        const pkg = (server?.args ?? []).find((a) => !a.startsWith('-'));
+        if (!pkg) throw new Error('no npx package in mcpServers');
+        label = `plugin → ${pkg}`;
+        const view = JSON.parse(execSync(`npm view ${pkg} version dependencies --json`, { encoding: 'utf8' }));
+        const wcRange = view.dependencies?.['@tmorrow/cre8-wc'];
+        if (!wcRange) {
+            targets.push({ name: `${label}@${view.version}`, error: 'does not depend on @tmorrow/cre8-wc — it bundles its own catalog and can never be graph-backed' });
+            continue;
+        }
+        const wcVersion = JSON.parse(execSync(`npm view "@tmorrow/cre8-wc@${wcRange}" version --json`, { encoding: 'utf8' }));
+        const resolved = Array.isArray(wcVersion) ? wcVersion.at(-1) : wcVersion;
+        targets.push({ name: `${label}@${view.version} (wc ${resolved})`, ...fromNpm(`@tmorrow/cre8-wc@${resolved}`) });
+    } catch (err) {
+        targets.push({ name: label, error: err?.message?.split('\n')[0] ?? String(err) });
+    }
+}
+
+const keys = Object.keys(local);
+const pad = (s, n) => String(s).padEnd(n);
+console.log(pad('', 34) + keys.map((k) => pad(k, 17)).join(''));
+console.log(pad('local checkout', 34) + keys.map((k) => pad(local[k], 17)).join(''));
+let drifted = 0;
+for (const t of targets) {
+    if (t.error) {
+        drifted++;
+        console.log(`${pad(t.name.slice(0, 33), 34)}DRIFTED: ${t.error}`);
+        continue;
+    }
+    const same = t.fp.sha256 === local.sha256;
+    if (!same) drifted++;
+    console.log(pad(t.name.slice(0, 33), 34) + keys.map((k) => pad(t.fp[k] === local[k] ? t.fp[k] : `${t.fp[k]} !!`, 17)).join(''));
+}
+if (drifted) {
+    console.error(`\n${drifted} deployment(s) do not serve the graph this checkout builds. Redeploy them with the library.`);
+    process.exit(1);
+}
+console.log('\nall deployments serve the same knowledge graph as this checkout');

package/a2ui/generate-catalog-kg.mjs

@@ -1,31 +1,61 @@
 /**
- * Generates catalog-kg.json - the knowledge-graph projection of the a2ui
- * catalog that cre8-mcp's KG-backed handlers serve.
+ * Generates catalog-kg.json — the knowledge graph cre8-mcp serves.
  *
- * Deterministic: same catalog.json in, same graph out. Runs after
- * generate-catalog.mjs (which derives catalog.json from mcp-manifest.json),
- * so `build:a2ui` keeps manifest -> catalog -> catalog-kg aligned.
+ * This is the single source of truth for everything cre8-mcp says about
+ * *relationships* between components. The catalog (catalog.json) says what
+ * each component accepts; this graph says what goes where, and why it is
+ * believed. Every tool that answers a structural question — get_composition,
+ * get_content_model, get_patterns, list_components — reads this file, and so
+ * does the eval oracle (evals/cre8-a2ui-vs-mcp/oracle/build_oracle.py). One
+ * regeneration refreshes all of them; nothing downstream re-derives.
  *
- * Graph shape (consumed by packages/cre8-mcp/src/handlers.ts and
- * surface-routes.ts):
- *   nodes: category (cat:<Name>), component (<tag>), slot (slot:<tag>:<name>),
- *          enum_prop (prop:<tag>:<prop>)
- *   edges: BELONGS_TO, HAS_SLOT, HAS_ENUM_PROP
+ * Deterministic: same inputs in, same graph out. Runs after
+ * generate-catalog.mjs, so `build:a2ui` keeps manifest -> catalog -> kg aligned.
+ *
+ * Nodes
+ *   category   cat:<Name>
+ *   component  <tag>            props, slots, accepts_children, category,
+ *                               exemplar (smallest authored A2UI subtree)
+ *   slot       slot:<tag>:<name>
+ *   enum_prop  prop:<tag>:<prop>
+ *   pattern    pattern:<slug>    name, description, spec (authored A2UI, validated)
+ *
+ * Edges
+ *   BELONGS_TO     component -> category
+ *   HAS_SLOT       component -> slot
+ *   HAS_ENUM_PROP  component -> enum_prop
+ *   CONTAINS       parent -> child   { slot, count, evidence:[{kind,file}] }
+ *                  Only ever from observed artifacts (stories, component
+ *                  render templates, a2ui examples, a2ui patterns) — never
+ *                  from the naming rule. See kg-sources.mjs for the readers.
+ *   USED_IN_PATTERN component -> pattern
+ *   IN_FAMILY      component <-> component sharing a name prefix. Undirected
+ *                  on purpose: cre8-tag-list contains cre8-tag, and the names
+ *                  do not say so.
+ *   EXTENDS        component -> base class (from graphify: Cre8FormElement …)
+ *   IMPORTS        component -> component, module-level (from graphify)
  */
 import { readFileSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
+import { newContainment, scanComponentsDir, scanExamples, scanGraphify, scanPatterns } from './kg-sources.mjs';
+import { registerCatalog, validateSpec } from './index.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const catalogPath = resolve(__dirname, 'catalog.json');
 const pkgPath = resolve(__dirname, '..', 'package.json');
 const outPath = resolve(__dirname, 'catalog-kg.json');
+const componentsDir = resolve(__dirname, '..', 'components');
+const examplesDir = resolve(__dirname, 'examples');
+const patternsDir = resolve(__dirname, 'patterns');
+const graphifyPath = process.env.CRE8_GRAPHIFY ?? resolve(__dirname, '..', '..', '..', 'graphify-out', 'graph.json');
 
 const catalog = JSON.parse(readFileSync(catalogPath, 'utf8'));
 const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
 
 const components = catalog.$defs?.components ?? {};
+const knownTags = new Set(Object.keys(components));
 
 /** Collapses whitespace/newlines and truncates with an ellipsis. */
 const summarize = (text, max) => {
@@ -34,21 +64,38 @@ const summarize = (text, max) => {
     return flat.length > max ? `${flat.slice(0, max)}…` : flat;
 };
 
+// ─── evidence ───────────────────────────────────────────────────────────────
+
+const stories = newContainment();
+const sources = newContainment();
+const scanned = scanComponentsDir(componentsDir, { stories, sources });
+const examples = scanExamples(examplesDir);
+const patternSet = scanPatterns(patternsDir);
+const graphify = scanGraphify(graphifyPath, knownTags);
+
 const nodes = [];
 const edges = [];
 
-// Category nodes, alphabetical. Components without x-category land in Other.
+// ─── categories ─────────────────────────────────────────────────────────────
+
+// A component's category comes from the manifest's x-category. A component
+// with none is not silently filed under "Other" any more: it is reported at
+// the end and the build fails, because "Other" is exactly the kind of
+// hand-maintained metadata this graph exists to stop drifting.
+const uncategorized = [];
 const categories = new Set();
-for (const def of Object.values(components)) {
-    categories.add(def['x-category'] || 'Other');
+for (const [tag, def] of Object.entries(components)) {
+    if (!def['x-category'] || def['x-category'] === 'Other') uncategorized.push(tag);
+    else categories.add(def['x-category']);
 }
 for (const label of [...categories].sort()) {
     nodes.push({ id: `cat:${label}`, type: 'category', label });
 }
 
-// Component, slot, and enum-prop nodes in catalog order.
+// ─── components, slots, enum props ──────────────────────────────────────────
+
 for (const [tag, def] of Object.entries(components)) {
-    const category = def['x-category'] || 'Other';
+    const category = def['x-category'] ?? null;
     const propDefs = def.properties?.props?.properties ?? {};
     const slotNames = Object.keys(def.properties?.slots?.properties ?? {});
     const slotDescriptions = def['x-slot-descriptions'] ?? {};
@@ -64,6 +111,7 @@ for (const [tag, def] of Object.entries(components)) {
         };
     }
 
+    const ex = examples.exemplar.get(tag);
     nodes.push({
         id: tag,
         type: 'component',
@@ -72,8 +120,10 @@ for (const [tag, def] of Object.entries(components)) {
         props,
         slots: slotNames,
         accepts_children: Boolean(def.properties?.children),
+        extends: graphify.extends.get(tag) ?? null,
+        exemplar: ex ? { source: ex.source, path: ex.path, spec: ex.spec } : null,
     });
-    edges.push({ from: tag, to: `cat:${category}`, rel: 'BELONGS_TO' });
+    if (category) edges.push({ from: tag, to: `cat:${category}`, rel: 'BELONGS_TO' });
 
     for (const slotName of slotNames) {
         const id = `slot:${tag}:${slotName}`;
@@ -102,14 +152,125 @@ for (const [tag, def] of Object.entries(components)) {
     }
 }
 
+// ─── CONTAINS: merged evidence ──────────────────────────────────────────────
+
+/**
+ * HTML and A2UI name the same position differently: unslotted markup is
+ * `children` in HTML, but for a component whose content model is slots the
+ * spec calls it `slots.default`. The graph speaks A2UI, because that is what
+ * the tools emit and validate — so the catalog's content model for the parent
+ * decides, and a story's unslotted child lands in `default` on a slotted
+ * component and in `children` (null) on a children component.
+ */
+const a2uiSlot = (parent, slot) => {
+    const def = components[parent];
+    const takesChildren = Boolean(def?.properties?.children);
+    const slotNames = Object.keys(def?.properties?.slots?.properties ?? {});
+    if (slot == null) return takesChildren || !slotNames.includes('default') ? null : 'default';
+    if (slot === 'default' && takesChildren) return null;
+    return slot;
+};
+
+/** key "parent|slot|child" -> { count, evidence: Map<kind, Set<file>> } */
+const contains = new Map();
+const merge = (kind, containment) => {
+    for (const [parent, bySlot] of containment) {
+        if (!knownTags.has(parent)) continue;
+        for (const [rawSlot, byChild] of bySlot) {
+            const slot = a2uiSlot(parent, rawSlot);
+            for (const [child, rec] of byChild) {
+                if (!knownTags.has(child)) continue; // cre8-icon-legacy and friends are not in the catalog
+                const key = `${parent}|${slot ?? ''}|${child}`;
+                const e = contains.get(key) ?? { parent, slot, child, count: 0, evidence: new Map() };
+                e.count += rec.count;
+                const files = e.evidence.get(kind) ?? new Set();
+                for (const f of rec.files) files.add(f);
+                e.evidence.set(kind, files);
+                contains.set(key, e);
+            }
+        }
+    }
+};
+merge('source', sources);
+merge('story', stories);
+merge('example', examples.containment);
+merge('pattern', patternSet.containment);
+
+const containsEdges = [...contains.values()]
+    .sort((a, b) => a.parent.localeCompare(b.parent) || (a.slot ?? '').localeCompare(b.slot ?? '') || a.child.localeCompare(b.child))
+    .map((e) => ({
+        from: e.parent,
+        to: e.child,
+        rel: 'CONTAINS',
+        slot: e.slot,
+        count: e.count,
+        evidence: [...e.evidence].flatMap(([kind, files]) => [...files].sort().map((file) => ({ kind, file }))),
+    }));
+edges.push(...containsEdges);
+
+// ─── patterns ───────────────────────────────────────────────────────────────
+
+// A pattern is an authored spec, so it is held to the same bar as anything an
+// agent would emit: it must validate against the catalog it ships with.
+const registered = registerCatalog(catalog);
+const invalidPatterns = [];
+for (const p of patternSet.patterns) {
+    try {
+        validateSpec(p.spec, registered);
+    } catch (err) {
+        invalidPatterns.push(`${p.source}: ${err?.message ?? err}`);
+        continue;
+    }
+    nodes.push({
+        id: `pattern:${p.slug}`,
+        type: 'pattern',
+        name: p.name,
+        description: p.description,
+        source: p.source,
+        spec: p.spec,
+        components: p.components,
+    });
+    for (const tag of p.components) edges.push({ from: tag, to: `pattern:${p.slug}`, rel: 'USED_IN_PATTERN' });
+}
+
+// ─── IN_FAMILY ──────────────────────────────────────────────────────────────
+
+const tags = [...knownTags].sort();
+for (const a of tags) {
+    for (const b of tags) {
+        if (a < b && (b.startsWith(`${a}-`) || a.startsWith(`${b}-`))) {
+            edges.push({ from: a, to: b, rel: 'IN_FAMILY' });
+        }
+    }
+}
+
+// ─── EXTENDS / IMPORTS ──────────────────────────────────────────────────────
+
+for (const [tag, base] of [...graphify.extends].sort()) {
+    edges.push({ from: tag, to: `class:${base}`, rel: 'EXTENDS' });
+}
+for (const [from, set] of [...graphify.imports].sort()) {
+    for (const to of [...set].sort()) edges.push({ from, to, rel: 'IMPORTS' });
+}
+
+// ─── write ──────────────────────────────────────────────────────────────────
+
 const kg = {
     meta: {
-        generated_from: 'catalog.json',
+        generated_from: ['catalog.json', 'components/*/*.stories.ts', 'components/*/*.ts', 'a2ui/examples/*.json', 'a2ui/patterns/*.json', graphify.found ? 'graphify-out/graph.json' : null].filter(Boolean),
         catalog_id: 'cre8-wc',
         library: pkg.name,
         library_version: pkg.version,
+        graphify_commit: graphify.commit,
+        evidence: {
+            story_files: scanned.storyFiles,
+            source_files: scanned.sourceFiles,
+            example_files: examples.files,
+            pattern_files: patternSet.patterns.map((p) => p.source.replace('a2ui/patterns/', '')),
+        },
         total_nodes: nodes.length,
         total_edges: edges.length,
+        contains_edges: containsEdges.length,
     },
     nodes,
     edges,
@@ -118,5 +279,20 @@ const kg = {
 writeFileSync(outPath, `${JSON.stringify(kg, null, 2)}\n`, 'utf8');
 console.log(
     `catalog-kg.json: ${nodes.length} nodes, ${edges.length} edges `
-  + `(${Object.keys(components).length} components, ${categories.size} categories)`,
+  + `(${knownTags.size} components, ${categories.size} categories, `
+  + `${containsEdges.length} CONTAINS from ${scanned.storyFiles} stories + ${scanned.sourceFiles} sources + ${examples.files.length} examples + ${patternSet.patterns.length} patterns`
+  + `${graphify.found ? `, graphify@${(graphify.commit ?? '').slice(0, 7)}` : ', no graphify graph'})`,
 );
+
+if (invalidPatterns.length) {
+    console.error(`\ncatalog-kg: ${invalidPatterns.length} pattern(s) do not validate against the catalog:\n  ${invalidPatterns.join('\n  ')}`);
+    process.exit(1);
+}
+
+if (uncategorized.length) {
+    console.error(
+        `\ncatalog-kg: ${uncategorized.length} component(s) have no category: ${uncategorized.join(', ')}\n`
+      + 'Add them to CATEGORY_MAP in scripts/generate-mcp-manifest.ts — "Other" is not a category.',
+    );
+    process.exit(1);
+}