@kitn.ai/ui 0.20.1 → 0.22.0

package/src/agent-tooling/mcp/manifest.ts

@@ -2,16 +2,48 @@
  * manifest.ts — reads dist/custom-elements.json (a Custom Elements Manifest)
  * and exposes helpers for the component_reference tool.
  *
- * Resolution strategy (dual-context):
+ * Resolution strategy (dual-context) — each context is an EXACT location, never a
+ * search. See `resolveManifestPath` for why that distinction is the whole point:
  *  1. Bundled bin: dist/mcp.es.js lives in dist/, so custom-elements.json is
- *     a sibling → try ./custom-elements.json relative to import.meta.url.
- *  2. Vitest (source): manifest.ts lives in src/agent-tooling/mcp/, so we walk
- *     up parent directories looking for <dir>/dist/custom-elements.json.
+ *     a sibling → ./custom-elements.json relative to import.meta.url.
+ *  2. Vitest (source): manifest.ts lives at <package>/src/agent-tooling/mcp/, so
+ *     the manifest is <package>/dist/custom-elements.json and nowhere else.
+ *
+ * It also answers "which of these 80 elements has anything to do with cards", for
+ * the card contract component_reference serves. That question lives HERE rather than
+ * in reference.ts because half of it is a question about the element manifest — the
+ * kit's own `type -> tag` map, crossed against the tag list this module already owns
+ * — and because both halves of the answer must come off one place. See
+ * `cardTagForType` for the rule and for what happens when an eighth card type lands.
  */
 
 import { readFileSync, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { join, dirname } from 'node:path';
+import { join, dirname, resolve } from 'node:path';
+// The package's own public entry, by the same specifier the scaffolder tells a
+// consumer's route to use. That is now a CHOICE, and this comment used to say the
+// opposite: the barrel re-exports src/schemas/registry.ts, which type-IMPORTED
+// `CardComponentMap` from src/primitives/card-registry.TSX, and pulling a .tsx into
+// this pass would mean giving tsconfig.mcp.json `jsx` + `jsxImportSource` + the DOM
+// lib, dragging the whole Solid component tree into a Node-only project — measured
+// as 0 errors -> 1364. Those two types moved to the DOM-free
+// src/primitives/card-component-types.ts, so a relative import of the barrel would
+// typecheck here today. It stays on the public specifier anyway, because emitting
+// and consuming the same string is the point of this module. The built entry
+// resolves to dist/schemas/index.d.ts, whose own reference to card-registry is a
+// .d.ts that skipLibCheck skips, so the Node/no-DOM guarantee survives intact.
+//
+// `BUILTIN_CARD_TAGS` is the authoritative `CardEnvelope.type -> kai-* tag` map and
+// arrives here as DATA, not a type. It is authored in src/primitives/card-tags.ts,
+// which holds that map ALONE — no Solid below it — so it is readable from source by a
+// Node/no-DOM project rather than only through this built entry. Before that split it
+// shared a module with `BUILTIN_CARD_COMPONENTS` and this module re-derived it by
+// convention instead; see `cardTagForType`.
+//
+// This costs a build before typecheck and before the unit suite. That is not a new
+// dependency: resolveManifestPath() below already requires dist/custom-elements.json,
+// and CI already runs `nx build ui` ahead of both.
+import { BUILTIN_CARD_TAGS, cardSchemaNames } from '@kitn.ai/ui/schemas';
 
 // ── CEM types ────────────────────────────────────────────────────────────────
 
@@ -81,32 +113,95 @@ interface CustomElementsManifest {
 }
 
 // ── Manifest resolution ───────────────────────────────────────────────────────
+//
+// THE MANIFEST IS THIS PACKAGE'S OWN BUILD ARTIFACT, SO IT IS ADDRESSED, NOT SEARCHED
+// FOR. This used to walk up ten parent directories taking the first
+// `<dir>/dist/custom-elements.json` it found, and that is a categorically weaker
+// thing than it looks: "a custom-elements.json exists somewhere above me" and "THIS
+// package's custom-elements.json exists" are different facts, and a walk-up cannot
+// tell them apart. It reports success for both.
+//
+// It was not hypothetical. Measured from an agent git worktree at
+// `<repo>/.claude/worktrees/<agent>/packages/ui/src/agent-tooling/mcp`, the loop
+// climbed past the worktree's own (unbuilt) `packages/ui/dist`, out of the worktree
+// entirely, and bound on iteration 8 to `<repo>/dist/custom-elements.json` — a
+// leftover from the pre-monorepo layout, six weeks stale, 78 tags, and zero elements
+// declaring `cardSchemas`. The consequence is this repo's dominant failure mode in
+// its purest form: on an unbuilt tree the MCP manifest tests did not error, they
+// PASSED, 16 of 17, against an artifact from a tree nobody was working in. Two
+// checkouts could disagree about what they had tested and nothing said so.
+//
+// So the rule here is now: a missing manifest is a HARD FAILURE that names the path
+// it expected. Never a fallback, never a wider search. If this throws, the answer is
+// to build — not to let it find someone else's build.
+
+const PACKAGE_NAME = '@kitn.ai/ui';
+const MANIFEST_FILE = 'custom-elements.json';
+
+/**
+ * `<package>/src/agent-tooling/mcp` -> `<package>`. A fixed, exact hop, and it is
+ * CHECKED below rather than trusted: if this module is ever moved to a different
+ * depth the derived root stops being this package and resolution throws, instead of
+ * silently addressing whatever directory happens to sit three levels up.
+ */
+const SOURCE_TO_PACKAGE_ROOT = ['..', '..', '..'] as const;
+
+/** Is `root` the root of THIS package — not merely *a* directory holding a dist/? */
+function isThisPackage(root: string): boolean {
+  const manifest = join(root, 'package.json');
+  if (!existsSync(manifest)) return false;
+  try {
+    return (JSON.parse(readFileSync(manifest, 'utf-8')) as { name?: string }).name === PACKAGE_NAME;
+  } catch {
+    return false;
+  }
+}
 
-function resolveManifestPath(): string {
-  const thisFile = fileURLToPath(import.meta.url);
-  const thisDir = dirname(thisFile);
+/**
+ * Absolute path to this package's Custom Elements Manifest, or a throw naming what
+ * it looked for.
+ *
+ * `fromDir` exists for the tests and defaults to this module's own directory. It is
+ * the only way to write the check that matters: the guarantee is not "a manifest was
+ * found", it is "THIS package's manifest was found", and the two only come apart
+ * when there is a decoy above the origin. manifest.test.ts builds exactly that tree.
+ */
+export function resolveManifestPath(
+  fromDir: string = dirname(fileURLToPath(import.meta.url)),
+): string {
+  // 1. Bundled bin: dist/mcp.es.js and dist/custom-elements.json are siblings.
+  //    Unambiguous by construction — a sibling cannot be another checkout's artifact.
+  const sibling = join(fromDir, MANIFEST_FILE);
+  if (existsSync(sibling)) return sibling;
+
+  // 2. Source (vitest, tsx): one exact location, derived and then verified.
+  const packageRoot = resolve(fromDir, ...SOURCE_TO_PACKAGE_ROOT);
+  const expected = join(packageRoot, 'dist', MANIFEST_FILE);
 
-  // 1. Bundled bin: sibling in the same directory
-  const sibling = join(thisDir, 'custom-elements.json');
-  if (existsSync(sibling)) {
-    return sibling;
+  if (!isThisPackage(packageRoot)) {
+    throw new Error(
+      `[${PACKAGE_NAME}] Cannot locate the Custom Elements Manifest: ${packageRoot} is not ` +
+        `the ${PACKAGE_NAME} package root, so ${expected} would not be this package's ` +
+        `manifest even if it existed.\n` +
+        `Resolved from: ${fromDir}\n` +
+        `This module must live at <package>/src/agent-tooling/mcp/ (or be bundled beside ` +
+        `${MANIFEST_FILE} in dist/). Resolution deliberately does NOT search parent ` +
+        `directories — finding some other checkout's manifest is worse than failing.`,
+    );
   }
 
-  // 2. Source/Vitest: walk up parent directories looking for dist/custom-elements.json
-  let dir = thisDir;
-  for (let i = 0; i < 10; i++) {
-    const candidate = join(dir, 'dist', 'custom-elements.json');
-    if (existsSync(candidate)) {
-      return candidate;
-    }
-    const parent = dirname(dir);
-    if (parent === dir) break; // reached filesystem root
-    dir = parent;
+  if (!existsSync(expected)) {
+    throw new Error(
+      `[${PACKAGE_NAME}] Missing build artifact: ${expected}\n` +
+        `Resolved from: ${fromDir}\n` +
+        `The Custom Elements Manifest is generated by the build. Run \`nx build ui\` ` +
+        `(or \`npm run build:api\` in packages/ui) and try again.\n` +
+        `Resolution deliberately does NOT search parent directories: binding to a ` +
+        `neighbouring checkout's manifest would make this succeed against stale data.`,
+    );
   }
 
-  throw new Error(
-    `Could not find custom-elements.json. Searched from: ${thisDir}`,
-  );
+  return expected;
 }
 
 // ── Parsed manifest (module-level cache) ─────────────────────────────────────
@@ -140,3 +235,89 @@ export function listElements(): string[] {
     .map((d) => d.tagName!)
     .sort();
 }
+
+// ── Which elements have anything to do with cards ────────────────────────────
+//
+// Two different populations, and conflating them would be the "attaches card
+// material to everything" failure:
+//
+//   CARD-BACKED   kai-confirm, kai-choice, …  — one element per CardEnvelope.type.
+//                 These get a schema and a generated tool definition.
+//   CARD HOST     kai-chat, kai-message, …    — the elements that RENDER a thread of
+//                 cards and therefore carry the `cardTypes` / `cardSchemas` props.
+//                 These get the wiring note, not a schema.
+//
+// Neither list is written down here. The host list is derived from the manifest; the
+// card-backed one is the kit's own map, read rather than guessed at. Either way an
+// eighth card type is covered the day it lands rather than the day someone remembers
+// this file.
+
+/** Cached derivations. Same lifetime as the parsed manifest above. */
+let _cardTags: Map<string, string> | undefined;
+let _cardHosts: string[] | undefined;
+
+/**
+ * `CardEnvelope.type` -> the `kai-*` element that renders it.
+ *
+ * THE MAP IS IMPORTED, NOT INFERRED. `BUILTIN_CARD_TAGS` is the same object
+ * `<kai-cards>` dispatches on in the browser, reached here through
+ * `@kitn.ai/ui/schemas`. This function used to RE-DERIVE it by convention — the tag
+ * is `kai-<t>` when that element exists, else the single element whose tag starts
+ * `kai-<t>-` — which was correct against all 80 tags on this tree, `link` ->
+ * `kai-link-preview` included, and was still a second copy of a fact the repo already
+ * held. The eighth card type is the one that would have broken it: any type whose tag
+ * is neither `kai-<t>` nor the sole `kai-<t>-*` had to be noticed by a human, and a
+ * future `kai-form-field` would have made `form` ambiguous on its own. A lookup has
+ * neither failure mode.
+ *
+ * WHY IT IS STILL CROSSED AGAINST THE MANIFEST. The map is authoritative for the
+ * ASSOCIATION; only the manifest knows what actually got registered. A tag in the map
+ * with no element behind it (a rename that missed this file) would otherwise have
+ * `component_reference` send a harness to an element that does not exist. Entries with
+ * no registered element are dropped, so the answer is a real tag or nothing.
+ *
+ * WHEN IT BREAKS, IT BREAKS LOUDLY. reference.test.ts asserts every member of
+ * `cardSchemaNames` resolves AND that what it resolves to is in `listElements()`, so a
+ * card type missing from the map, or pointed at a tag nobody registered, fails a test
+ * instead of silently losing its schema in the reference.
+ */
+export function cardTagForType(type: string): string | undefined {
+  if (!_cardTags) {
+    const present = new Set(listElements());
+    _cardTags = new Map(Object.entries(BUILTIN_CARD_TAGS).filter(([, tag]) => present.has(tag)));
+  }
+  return _cardTags.get(type);
+}
+
+/** The inverse: which card type does this element render, if any. */
+export function cardTypeForTag(tag: string): string | undefined {
+  for (const name of cardSchemaNames) {
+    if (cardTagForType(name) === tag) return name;
+  }
+  return undefined;
+}
+
+/**
+ * The elements that host a thread of cards, derived from the manifest: an element is
+ * a card host exactly when it declares the `cardSchemas` prop.
+ *
+ * That prop is the one that carries a developer's own card schemas into the browser
+ * validator, so "declares it" and "hosts cards" are the same fact rather than two
+ * facts that can disagree. Today it selects kai-chat / kai-message / kai-thread /
+ * kai-workspace; an element that grows the prop tomorrow joins without an edit here.
+ */
+export function cardHostTags(): string[] {
+  if (!_cardHosts) {
+    _cardHosts = getDeclarations()
+      .filter(
+        (d) =>
+          d.tagName !== undefined &&
+          (d.members ?? []).some(
+            (m) => m.kind === 'field' && m.privacy === 'public' && m.name === 'cardSchemas',
+          ),
+      )
+      .map((d) => d.tagName!)
+      .sort();
+  }
+  return _cardHosts;
+}

package/src/agent-tooling/mcp/tools/debug.ts

@@ -39,7 +39,7 @@ const RULES: Rule[] = [
       '```js\n' +
       "// ✅ Works — set messages in JavaScript as a property\n" +
       "const chat = document.querySelector('kai-chat');\n" +
-      "chat.messages = [{ id: '1', role: 'assistant', content: 'Hello!' }];\n" +
+      "chat.messages = [{ id: '1', role: 'assistant', parts: [{ type: 'text', text: 'Hello!' }] }];\n" +
       '```\n\n' +
       '```html\n' +
       '<!-- ❌ Fails — messages cannot be an HTML attribute -->\n' +
@@ -55,7 +55,7 @@ const RULES: Rule[] = [
     title: 'In-place mutation does not trigger a re-render',
     cause:
       'Mutating an existing message object or array in place (e.g. `chat.messages.push(…)` ' +
-      'or `chat.messages[i].content = …`) does not trigger a re-render. ' +
+      'or `chat.messages[i].parts = […]`) does not trigger a re-render. ' +
       'The element only reacts when it detects a new array/object reference.',
     fix:
       'Assign a NEW array (and a new object) on every change — never mutate in place.\n\n' +
@@ -63,17 +63,23 @@ const RULES: Rule[] = [
       '// ✅ Triggers re-render — new array + new object reference\n' +
       'chat.messages = [\n' +
       '  ...chat.messages,\n' +
-      "  { id: crypto.randomUUID(), role: 'user', content: userText },\n" +
+      "  { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: userText }] },\n" +
       '];\n\n' +
-      '// ✅ During streaming — replace with a new array + new object on every chunk\n' +
+      '// ✅ During streaming: new array + new object per chunk, and FOLD the delta\n' +
+      "//    onto the trailing text part so reasoning/tool/card parts survive.\n" +
+      "import { appendTextPart } from '@kitn.ai/ui/state';\n" +
       'chat.messages = chat.messages.map((m) =>\n' +
-      '  m.id === assistantId ? { ...m, content: accumulated } : m\n' +
+      '  m.id === assistantId ? { ...m, parts: appendTextPart(m.parts, delta) } : m\n' +
       ');\n\n' +
       '// ❌ Does NOT trigger re-render\n' +
       'chat.messages.push(newMsg);\n' +
-      'chat.messages[i].content = accumulated;\n' +
+      'chat.messages[i].parts = appendTextPart(chat.messages[i].parts, delta);\n\n' +
+      '// ❌ Re-renders, but DROPS the reasoning/tool/card parts already on the message\n' +
+      'chat.messages = chat.messages.map((m) =>\n' +
+      "  m.id === assistantId ? { ...m, parts: [{ type: 'text', text: accumulated }] } : m\n" +
+      ');\n' +
       '```\n\n' +
-      'The ergonomic path: helpers in `@kitn.ai/ui/state` (`appendMessage`, `updateMessage`, `appendContent`) ' +
+      'The ergonomic path: helpers in `@kitn.ai/ui/state` (`appendMessage`, `updateMessage`, `appendText`) ' +
       'and `createAssistantStream` handle the new-reference contract for you. ' +
       '`useKaiChat` (React) and `createKaiChat` (Solid) own state entirely so mutation is never an option.\n\n' +
       '// setMessages((m) => appendMessage(m, msg)) // new array, no footgun',

package/src/agent-tooling/mcp/tools/reference.ts

@@ -1,6 +1,16 @@
 import { z } from 'zod';
+import {
+  KAI_TOOL_PREFIX,
+  cardSchemaNames,
+  cardSchemas,
+  cardTools,
+  isCardSchemaName,
+  toolNameForCardType,
+} from '@kitn.ai/ui/schemas';
+import type { CardSchemaName, ToolProvider } from '@kitn.ai/ui/schemas';
 import type { Tool } from './types';
-import { getElement, listElements } from '../manifest';
+import { cardHostTags, cardTagForType, cardTypeForTag, getElement, listElements } from '../manifest';
+import type { CemMember } from '../manifest';
 
 /**
  * component_reference — look up AI/UI (kai-*) web components, their props,
@@ -10,6 +20,10 @@ import { getElement, listElements } from '../manifest';
  * Backed by manifest.ts which resolves the CEM in both the bundled bin
  * (dist/mcp.es.js sibling) and the Vitest source context (walks up to find
  * dist/custom-elements.json in the repo root).
+ *
+ * For a card-backed element it also serves the card's JSON Schema and a tool
+ * definition GENERATED by `cardTools()`. See `renderCardContract` for why not one
+ * byte of that is written here as a literal.
  */
 
 /** Types that warrant the JS-property contract note. */
@@ -19,7 +33,199 @@ function isJsOnlyType(typeText: string | undefined): boolean {
   return typeText ? JS_ONLY_TYPE_PATTERNS.test(typeText) : false;
 }
 
-function formatReference(tag: string): string {
+// ─────────────────────────────────────────────────────────────────────────────
+// The imperative half of the interaction surface
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A CEM member of `kind: 'method'`.
+ *
+ * `CemMember` in manifest.ts types what EVERY member carries. `parameters` and
+ * `return` exist only on methods, and gen-element-api.mjs writes the AUTHORED
+ * parameter list into a single `parameters[0].name` rather than splitting it, so
+ * the signature is rebuilt from those two fields rather than read off one.
+ */
+interface CemMethodMember extends CemMember {
+  kind: 'method';
+  parameters?: { name: string }[];
+  return?: { type?: { text?: string } };
+}
+
+function isPublicMethod(member: CemMember): member is CemMethodMember {
+  return member.kind === 'method' && member.privacy === 'public';
+}
+
+/** `maximize(index: number): void` — the call as a consumer types it. */
+function methodSignature(method: CemMethodMember): string {
+  return `${method.name}(${method.parameters?.[0]?.name ?? ''}): ${method.return?.type?.text ?? 'void'}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The card contract
+// ─────────────────────────────────────────────────────────────────────────────
+
+const PROVIDERS = ['openai', 'anthropic', 'jsonschema'] as const;
+
+/**
+ * What a caller gets when they do not name a provider.
+ *
+ * NOT a coin-flip between the two wire formats, and deliberately not "serve all
+ * three". The three envelopes are not interchangeable in a way a reader can patch
+ * up: OpenAI nests the schema at `function.parameters`, Anthropic puts it flat at
+ * `input_schema`. Handing over one of those unasked means a harness on the other
+ * provider pastes it in and gets a 400 it will blame on the kit.
+ *
+ * `jsonschema` is the only one of the three that is not a wire envelope at all —
+ * `{ name, description, schema }` cannot be mistaken for either provider's shape, so
+ * a caller who reads it as one is corrected by the field names before they ship it.
+ * It is also directly usable, not a booby prize: `tool({ inputSchema: jsonSchema(
+ * def.schema) })` is exactly what the Vercel AI SDK wants, and of the nine
+ * integrations this MCP scaffolds, exactly one (openrouter) posts a raw OpenAI-wire
+ * tools array; the rest go through an SDK or an agent framework that takes the bare
+ * schema.
+ *
+ * Serving all three was the other candidate and it loses on cost for no gain in
+ * safety: measured on this tree, one card's pretty-printed definition runs
+ * 1.7-5.3 KB, so three of them plus the schema turns a single `kai-artifact` lookup
+ * into roughly 20 KB of context. The response names all three modes and the exact
+ * call that produces each, so a caller who does know their provider is one re-ask
+ * away and still never invents an envelope.
+ */
+const DEFAULT_PROVIDER: ToolProvider = 'jsonschema';
+
+function isProvider(value: string): value is ToolProvider {
+  return (PROVIDERS as readonly string[]).includes(value);
+}
+
+/** Stable fence info strings, so a reader (and reference.test.ts) can lift the blocks back out exactly. */
+const TOOL_FENCE = 'kai-tool-definition';
+const SCHEMA_FENCE = 'kai-card-schema';
+
+function fence(info: string, value: unknown): string[] {
+  return ['```json ' + info, JSON.stringify(value, null, 2), '```'];
+}
+
+/**
+ * Render a card type as it would be written in JS source.
+ *
+ * The seven built-ins are all bare identifiers, but a card type is whatever string a
+ * developer put in `CardEnvelope.type` — `pricing-table` is legal and reaches this
+ * code the day an eighth built-in is hyphenated. Emitting `{ pricing-table: … }` as a
+ * copy-paste sample would be a syntax error, so the quoting is decided, not assumed.
+ */
+const BARE_IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+function asKey(cardType: string): string {
+  return BARE_IDENTIFIER.test(cardType) ? cardType : JSON.stringify(cardType);
+}
+
+function asMember(cardType: string): string {
+  return BARE_IDENTIFIER.test(cardType) ? `.${cardType}` : `[${JSON.stringify(cardType)}]`;
+}
+
+/**
+ * The loop, in the four facts a harness cannot infer from a prop table.
+ *
+ * Shared by the card-backed and the card-host sections because they are the same
+ * contract seen from the two ends, and a second copy would be the drift this whole
+ * task exists to remove, one level up from the tool definition.
+ *
+ * `example` is the card the caller actually asked about, so the illustration is about
+ * their card rather than a fixed one they then have to translate.
+ */
+function loopWiring(example: string): string[] {
+  return [
+    '',
+    '#### Wiring the loop',
+    `- **Tool names are \`${KAI_TOOL_PREFIX}<card type>\`.** \`${toolNameForCardType(example)}\` produces \`{ type: "${example}" }\`. ` +
+      'Use `isCardTool(name)` to split card calls from your own tools; never match the prefix by hand.',
+    '- **`tool_call_id` becomes `CardEnvelope.id`, unchanged.** That is what makes a revision UPSERT: ' +
+      'a model that re-sends the same tool call id replaces the card in place instead of rendering a second copy of it. ' +
+      'Generating your own id breaks that silently.',
+    '- **`cardFromToolCall(name, input, { id: call.id })`** turns the call into a renderable envelope, ' +
+      'or returns `null` when it is one of your own tools so the loop falls through to it. It never throws.',
+    '- **Everything above is one import:** `import { cardTools, cardFromToolCall, isCardTool } from \'@kitn.ai/ui/schemas\'`. ' +
+      `The raw documents also ship as JSON (\`@kitn.ai/ui/schemas/${example}.schema.json\`) for a Python or Go backend.`,
+  ];
+}
+
+/** The card-backed section: schema + a GENERATED tool definition. */
+function renderCardContract(tag: string, cardType: CardSchemaName, provider: ToolProvider): string[] {
+  const schema = cardSchemas[cardType];
+
+  // GENERATED, NEVER RESTATED.
+  //
+  // This calls the same `cardTools` a consumer's route calls, on the same schema, so
+  // the definition served here cannot diverge from the one they ship — not when a
+  // schema gains a field, not when the projection changes what it strips. A literal
+  // typed into this file would read identically today and rot on the first schema
+  // change, which is exactly the hand-copy drift this tool exists to remove.
+  // reference.test.ts asserts byte-equality against BOTH `cardTools({ [type]: schema },
+  // …)` and the matching entry of the whole-registry `cardTools({ provider })`, so a
+  // hand-edit here fails a test rather than shipping.
+  const [def] = cardTools({ [cardType]: schema }, { provider });
+
+  const lines: string[] = [
+    '',
+    '### Card contract',
+    `\`<${tag}>\` renders \`CardEnvelope.type: "${cardType}"\`. A model does not emit an envelope; ` +
+      `it calls the tool \`${toolNameForCardType(cardType)}\`, and the kit turns that call back into one.`,
+  ];
+
+  lines.push(
+    '',
+    `#### Tool definition — provider \`${provider}\``,
+    `Generated by \`cardTools({ ${asKey(cardType)}: cardSchemas${asMember(cardType)} }, { provider: '${provider}' })\`. ` +
+      'Copy it; do not retype it, and do not hand-maintain a second copy — regenerate instead.',
+    `Ask again with \`provider\` set to \`openai\`, \`anthropic\` or \`jsonschema\` for the other envelopes. ` +
+      'They are NOT interchangeable: OpenAI nests the schema at `function.parameters`, Anthropic puts it flat at `input_schema`.',
+    ...fence(TOOL_FENCE, def),
+  );
+
+  lines.push(
+    '',
+    '#### Card data JSON Schema',
+    `\`import { cardSchemas } from '@kitn.ai/ui/schemas'\` → \`cardSchemas${asMember(cardType)}\`. ` +
+      `Raw document: \`@kitn.ai/ui/schemas/${cardType}.schema.json\`.`,
+    'This is the authored contract, and it is what `registry.validate()` checks arriving data against. ' +
+      'The tool definition above carries the same document with `$schema`, `$id` and `x-kai-*` stripped — ' +
+      'that projection is `cardTools`\' job, so do not put a raw schema on the wire yourself.',
+    ...fence(SCHEMA_FENCE, schema),
+  );
+
+  lines.push(...loopWiring(cardType));
+  return lines;
+}
+
+/** The card-host section: no schema of its own, but this is where the props live. */
+function renderCardHost(tag: string): string[] {
+  const rows = cardSchemaNames.map((type) => {
+    const cardTag = cardTagForType(type);
+    return `- \`${type}\` → \`<${cardTag ?? '(no element)'}>\`, tool \`${toolNameForCardType(type)}\``;
+  });
+
+  return [
+    '',
+    '### Card contract',
+    `\`<${tag}>\` renders generative-UI cards inside the thread. It is a HOST: it draws whatever ` +
+      'envelopes arrive, and carries the two props that say what a card may be.',
+    '',
+    '- **`cardTypes`** — `Record<envelope type, custom element tag>`. What DRAWS a card. ' +
+      `Merged over the built-ins, so your entry overrides ours and the other ${cardSchemaNames.length - 1} still render.`,
+    '- **`cardSchemas`** — `Record<envelope type, JSON Schema>`. What a VALID card looks like. ' +
+      `This is the prop that carries YOUR OWN card schemas into the browser validator; the ${cardSchemaNames.length} built-ins are already known. ` +
+      'Both are objects, so both are JS properties (`el.cardSchemas = …`), never HTML attributes.',
+    '',
+    'Write both once with `createCardRegistry({ use, custom })` from `@kitn.ai/ui/schemas` and thread it to both ends: ' +
+      '`el.cardTypes = cards.tags` / `el.cardSchemas = cards.validationSchemas` on the client, `cardTools(cards, { provider })` on the route.',
+    '',
+    'Built-in card types (ask `component_reference` for one of these tags to get its schema and tool definition):',
+    ...rows,
+    ...loopWiring(cardSchemaNames[0]),
+  ];
+}
+
+function formatReference(tag: string, provider: ToolProvider): string {
   const el = getElement(tag);
 
   if (!el) {
@@ -50,6 +256,17 @@ function formatReference(tag: string): string {
       'and read `event.detail` for the payload.',
   );
 
+  // ── Card contract ─────────────────────────────────────────────────────────
+  // Attached to the two populations manifest.ts derives, and to nothing else. A
+  // reference that hangs card material off all 80 elements is worse than one that
+  // hangs it off none: it teaches a harness that every element takes a tool call.
+  const cardType = cardTypeForTag(tag);
+  if (cardType !== undefined && isCardSchemaName(cardType)) {
+    lines.push(...renderCardContract(tag, cardType, provider));
+  } else if (cardHostTags().includes(tag)) {
+    lines.push(...renderCardHost(tag));
+  }
+
   // ── Public JS properties ───────────────────────────────────────────────────
   const publicFields = (el.members ?? []).filter(
     (m) => m.kind === 'field' && m.privacy === 'public',
@@ -93,6 +310,25 @@ function formatReference(tag: string): string {
     }
   }
 
+  // ── Methods ───────────────────────────────────────────────────────────────
+  // The input half of the interaction surface. These were in the manifest and in
+  // the shipped types and rendered in NO reference, so the only way to find one
+  // was to read the kit's source.
+  const methods = (el.members ?? []).filter(isPublicMethod);
+  if (methods.length > 0) {
+    lines.push(
+      '',
+      '### Methods (call these on the element instance)',
+      `Get the element (\`const el = document.querySelector('${tag}')\`), then call it. ` +
+        'Methods drive the element from your code; the events above report back what the ' +
+        'user did. Both are public API.',
+    );
+    for (const method of methods) {
+      const desc = method.description?.trim() ?? '';
+      lines.push(`- **${methodSignature(method)}**${desc ? ` — ${desc}` : ''}`);
+    }
+  }
+
   // ── CSS custom properties ─────────────────────────────────────────────────
   const cssProps = el.cssProperties ?? [];
   if (cssProps.length > 0) {
@@ -142,21 +378,64 @@ function formatReference(tag: string): string {
 export const reference: Tool = {
   name: 'component_reference',
   description:
-    'Look up AI/UI (kai-*) web components: their tags, props, events, and usage examples.',
-  inputSchema: z.object({ name: z.string().optional() }),
+    'Look up AI/UI (kai-*) web components: their tags, props, events, imperative methods, and usage examples. ' +
+    'For a card-backed element it also returns the card\'s JSON Schema and a ready-to-send ' +
+    'tool definition generated from it — pass `provider` to get that provider\'s envelope.',
+  inputSchema: z.object({
+    name: z.string().optional(),
+    provider: z
+      .enum(PROVIDERS)
+      .optional()
+      .describe(
+        'Which tool-definition envelope to project for a card-backed element. ' +
+          `Defaults to "${DEFAULT_PROVIDER}", the provider-neutral { name, description, schema } form.`,
+      ),
+  }),
   handler: async (args: Record<string, unknown>) => {
     const name = typeof args.name === 'string' ? args.name.trim() : undefined;
 
+    // Validated HERE, not left to the zod schema above. server.ts advertises
+    // `inputSchema` over the protocol but hands `request.params.arguments` straight
+    // to this handler without parsing it, so an unrecognised provider would reach
+    // `cardTools`, which treats anything that is not "openai"/"anthropic" as the
+    // jsonschema branch. A caller asking for "gemini" would then get a definition in
+    // a shape they did not ask for, with nothing saying so. Refusing is the only
+    // answer that cannot be mistaken for an answer.
+    const rawProvider = args.provider;
+    if (rawProvider !== undefined && (typeof rawProvider !== 'string' || !isProvider(rawProvider))) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text:
+              `Unknown provider: ${JSON.stringify(rawProvider)}\n\n` +
+              `Valid providers are ${PROVIDERS.map((p) => `"${p}"`).join(', ')}. ` +
+              `Omit it to get "${DEFAULT_PROVIDER}", the provider-neutral { name, description, schema } form ` +
+              'that the Vercel AI SDK and most agent frameworks take directly.\n' +
+              'No tool definition was returned, because guessing which envelope you meant would hand you ' +
+              'a shape your provider rejects with nothing saying why.',
+          },
+        ],
+      };
+    }
+    const provider: ToolProvider = rawProvider ?? DEFAULT_PROVIDER;
+
     let text: string;
 
     if (!name || name === 'list') {
       const tags = listElements();
+      const cardRows = cardSchemaNames
+        .map((t) => cardTagForType(t))
+        .filter((t): t is string => t !== undefined);
       text =
         `AI/UI elements (${tags.length} total):\n\n` +
         tags.map((t) => `  ${t}`).join('\n') +
-        '\n\nCall component_reference with a specific name (e.g. { name: "kai-chat" }) for full API details.';
+        '\n\nCall component_reference with a specific name (e.g. { name: "kai-chat" }) for full API details.' +
+        `\n\nCard-backed elements — ask for one of these to get its JSON Schema and a generated ` +
+        `\`${KAI_TOOL_PREFIX}*\` tool definition:\n  ${cardRows.join(', ')}` +
+        `\nThe elements that HOST them (and carry the \`cardTypes\` / \`cardSchemas\` props): ${cardHostTags().join(', ')}`;
     } else {
-      text = formatReference(name);
+      text = formatReference(name, provider);
     }
 
     return { content: [{ type: 'text' as const, text }] };