@kitn.ai/ui 0.27.0 → 0.28.0

package/llms-full.txt

@@ -1520,7 +1520,7 @@ _No events._
 | `cards` | — | `undefined \| { type: string; id: string; data: unknown; title?: undefined \| string; resolution?: undefined \| { kind: "action"; action: string; payload?: unknown; at?: undefined \| string } \| { kind: "submit"; data: unknown; at?: undefined \| string } \| { kind: "dismissed"; at?: undefined \| string } \| { kind: "expired"; reason?: undefined \| string; at?: undefined \| string } }[]` | The stream of card envelopes to render. Set as a JS PROPERTY: `el.cards = [...]`. |
 | `types` | — | `undefined \| Record<string, string>` | Optional type→tag overrides/additions (merged over the built-ins). Property: `el.types`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. |
 | `schemas` | — | `undefined \| Record<string, object>` | JSON Schemas for the card types this app renders, keyed by envelope type. The companion of `types`, which says what DRAWS a card while this says what a VALID one looks like. An OBJECT, so it is a JS property only: `el.schemas = { 'pricing-table': pricingSchema }`, never an attribute. `createCardRegistry(...).validationSchemas` is exactly this shape. Without it the kit validates its own seven built-ins and leaves your own card type, the one your app actually cares about, as the only unchecked thing on screen. A schema here WINS over a built-in of the same name, matching `mergeCardTags`, where your entry is spread over ours. Typed `Record<string, object>` rather than `Record<string, JsonSchema>` deliberately: an imported `.json` schema widens `"type"` to `string`, and an authored one carries `$schema`/`title`/`description`/`additionalProperties`, so the tighter type would reject both of the normal ways to supply one. See `CardSchemaMap` in components/card-renderer.tsx. |
-| `policy` | — | `undefined \| { onSubmit?: undefined \| ((cardId: string, data: unknown) => void); onAction?: undefined \| ((cardId: string, action: string, payload?: unknown) => void); onSendPrompt?: undefined \| ((text: string, opts: { mode: "compose" \| "send"; context?: unknown; }) => void); onOpen?: undefined \| ((url: string, target: "tab" \| "artifact") => void); onState?: undefined \| ((cardId: string, patch: unknown) => void); onDismiss?: undefined \| ((cardId: string) => void); onReopen?: undefined \| ((cardId: string) => void); onError?: undefined \| ((cardId: string, message: string) => void); maxSendPromptMode?: undefined \| "compose" \| "send" }` | Optional CardPolicy handling child events. Property: `el.policy`. |
+| `policy` | — | `undefined \| { onSubmit?: undefined \| ((cardId: string, data: unknown) => void); onAction?: undefined \| ((cardId: string, action: string, payload?: unknown) => void); onSendPrompt?: undefined \| ((text: string, opts: { mode: "compose" \| "send"; context?: unknown }) => void); onOpen?: undefined \| ((url: string, target: "tab" \| "artifact") => void); onState?: undefined \| ((cardId: string, patch: unknown) => void); onDismiss?: undefined \| ((cardId: string) => void); onReopen?: undefined \| ((cardId: string) => void); onError?: undefined \| ((cardId: string, message: string) => void); maxSendPromptMode?: undefined \| "compose" \| "send" }` | Optional CardPolicy handling child events. Property: `el.policy`. |
 | `validateCards` | `validate-cards` | `undefined \| false \| true` | Validate each envelope's `data` against the schema for its type before rendering it, using a built-in's own schema or yours from `schemas`. Default `true`; set `validate-cards="false"` (or `el.validateCards = false`) to opt out. A hard failure (wrong type, a missing required field) renders a diagnostic naming the field instead of the card; a soft failure (bounds) renders the card unchanged. Both emit a contract `error` event. On in production too: a model emitting a bad shape is a production failure mode, so stripping the check there would hide it from exactly the person who needs to see it. |
 
 **Events** (non-bubbling `CustomEvent`s — listen directly on the element):
@@ -1614,6 +1614,9 @@ _No events._
 | `messages` | — | `undefined \| { id: string; role: "user" \| "assistant"; parts: ({ type: "text"; text: string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "reasoning"; text: string; label?: undefined \| string; index?: undefined \| number; streamId?: undefined \| string; signature?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "tool"; tool: { type: string; kind?: undefined \| "command" \| "file-change" \| "search" \| "fetch" \| "mcp" \| "image" \| "generic"; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; rawInput?: undefined \| string; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "card"; envelope: { type: string; id: string; data: unknown; title?: undefined \| string; resolution?: undefined \| { kind: "action"; action: string; payload?: unknown; at?: undefined \| string } \| { kind: "submit"; data: unknown; at?: undefined \| string } \| { kind: "dismissed"; at?: undefined \| string } \| { kind: "expired"; reason?: undefined \| string; at?: undefined \| string } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "source"; source: { id?: undefined \| string; url?: undefined \| string; title?: undefined \| string; snippet?: undefined \| string; index?: undefined \| number }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "file"; attachment: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }; raw?: undefined \| { source: string; payload: unknown } })[]; actions?: undefined \| ("copy" \| "like" \| "dislike" \| "regenerate" \| "edit" \| { id: string; label: string; icon?: undefined \| string; tooltip?: undefined \| string })[]; avatar?: undefined \| { src?: undefined \| string; fallback?: undefined \| string; alt?: undefined \| string }; feedback?: undefined \| "like" \| "dislike" }[]` | The full message thread to render, newest last. Each entry carries its role, ordered `parts`, and optional actions/avatar/feedback. Set as a JS property (`el.messages = [...]`); a NEW array reference per streaming chunk re-renders (mutating in place does not). Omit for an empty thread. Re-declared here (rather than inherited from `ChatThreadProps`) because the ELEMENT registers a `[]` default and renders the empty state without it, while the SolidJS `<ChatThread>` component still requires it. The facade hands it a validated array either way. Matches `<kai-thread>`. |
 | `cardTypes` | — | `undefined \| Record<string, string>` | Optional card type -> custom-element tag overrides/additions for `card` parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. |
 | `cardSchemas` | — | `undefined \| Record<string, object>` | JSON Schemas for the card types this app renders, keyed by envelope type. The companion of `cardTypes`, which says what DRAWS a card while this says what a VALID one looks like. An OBJECT, so it is a JS property only: `el.cardSchemas = { 'pricing-table': pricingSchema }`, never an attribute. `createCardRegistry(...).validationSchemas` is exactly this shape. Without it the kit validates its own seven built-ins and leaves your own card type, the one your app actually cares about, as the only unchecked thing on screen. A schema here WINS over a built-in of the same name. Typed `Record<string, object>` rather than `Record<string, JsonSchema>` deliberately: an imported `.json` schema widens `"type"` to `string`, and an authored one carries `$schema`/`title`/`description`/`additionalProperties`, so the tighter type would reject both of the normal ways to supply one. |
+| `conversations` | `conversations` | `undefined \| false \| true` | Turns on the prior-conversations list (a list-toggle button in the header, plus a second list view sharing the panel, C-1). Attribute- settable like every other boolean flag on this element: `<kai-chat conversations>`. Requires `store`. A row select, "new conversation," or the visitor's mount-time auto-restore all deliver their messages the same way: listen for `kai-conversation-load` and set `el.messages` from `event.detail.messages` (a fresh array): this element does not update `messages` for you. Set with no `store`, the underlying `ChatThread` decides loudly (one console.error) and stays visually off; this facade always supplies its own internal load handler (the `kai-conversation-load` dispatch below), so the second ChatThread guard, missing `onConversationLoad`, never trips here, even for a consumer who never listens for the event. Default false. |
+| `store` | — | `undefined \| { list: () => Promise<{ id: string; title: string; groupId?: undefined \| string; scope?: undefined \| { type: "document" \| "collection"; documentId?: undefined \| string; filters?: undefined \| { tags?: undefined \| string[]; authors?: undefined \| string[]; contentType?: undefined \| "transcript" \| "markdown"; dateRange?: undefined \| { from: string; to: string } } }; messageCount: number; lastMessageAt?: undefined \| string; updatedAt: string; trailing?: undefined \| string; lastReadAt?: undefined \| string }[]>; load: (id: string) => Promise<{ id: string; role: "user" \| "assistant"; parts: ({ type: "text"; text: string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "reasoning"; text: string; label?: undefined \| string; index?: undefined \| number; streamId?: undefined \| string; signature?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "tool"; tool: { type: string; kind?: undefined \| "command" \| "file-change" \| "search" \| "fetch" \| "mcp" \| "image" \| "generic"; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; rawInput?: undefined \| string; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "card"; envelope: { type: string; id: string; data: unknown; title?: undefined \| string; resolution?: undefined \| { kind: "action"; action: string; payload?: unknown; at?: undefined \| string } \| { kind: "submit"; data: unknown; at?: undefined \| string } \| { kind: "dismissed"; at?: undefined \| string } \| { kind: "expired"; reason?: undefined \| string; at?: undefined \| string } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "source"; source: { id?: undefined \| string; url?: undefined \| string; title?: undefined \| string; snippet?: undefined \| string; index?: undefined \| number }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "file"; attachment: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }; raw?: undefined \| { source: string; payload: unknown } })[]; actions?: undefined \| ("copy" \| "like" \| "dislike" \| "regenerate" \| "edit" \| { id: string; label: string; icon?: undefined \| string; tooltip?: undefined \| string })[]; avatar?: undefined \| { src?: undefined \| string; fallback?: undefined \| string; alt?: undefined \| string }; feedback?: undefined \| "like" \| "dislike" }[]>; save: (id: string, messages: { id: string; role: "user" \| "assistant"; parts: ({ type: "text"; text: string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "reasoning"; text: string; label?: undefined \| string; index?: undefined \| number; streamId?: undefined \| string; signature?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "tool"; tool: { type: string; kind?: undefined \| "command" \| "file-change" \| "search" \| "fetch" \| "mcp" \| "image" \| "generic"; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; rawInput?: undefined \| string; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "card"; envelope: { type: string; id: string; data: unknown; title?: undefined \| string; resolution?: undefined \| { kind: "action"; action: string; payload?: unknown; at?: undefined \| string } \| { kind: "submit"; data: unknown; at?: undefined \| string } \| { kind: "dismissed"; at?: undefined \| string } \| { kind: "expired"; reason?: undefined \| string; at?: undefined \| string } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "source"; source: { id?: undefined \| string; url?: undefined \| string; title?: undefined \| string; snippet?: undefined \| string; index?: undefined \| number }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "file"; attachment: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }; raw?: undefined \| { source: string; payload: unknown } })[]; actions?: undefined \| ("copy" \| "like" \| "dislike" \| "regenerate" \| "edit" \| { id: string; label: string; icon?: undefined \| string; tooltip?: undefined \| string })[]; avatar?: undefined \| { src?: undefined \| string; fallback?: undefined \| string; alt?: undefined \| string }; feedback?: undefined \| "like" \| "dislike" }[]) => Promise<void>; markRead?: undefined \| ((id: string) => Promise<void>) }` | The adapter this thread persists conversations through: an object of three functions (`list`/`load`/`save`; `ConversationStore`, exported from `@kitn.ai/ui`'s `primitives/conversation-store`). A JS PROPERTY ONLY: `el.store = myAdapter`. It can never be an attribute, since a function-bearing object has no HTML string form, the same reasoning that keeps `messages`/`cardSchemas` property-only (the kai- contract: array/object props are JS properties, never attributes). Two built-ins ship: `localStorageStore(name, userId?)` and `fetchStore(url, userId?)`. |
+| `home` | — | `undefined \| { greeting?: undefined \| { title?: undefined \| string; subtitle?: undefined \| string }; recentConversation?: undefined \| false \| true; newConversation?: undefined \| { label?: undefined \| string }; links?: undefined \| { label: string; href?: undefined \| string; description?: undefined \| string; icon?: undefined \| string }[] }` | Turns on the widget home screen (Intercom-pattern): the panel boots into a `home` view, with a greeting, most-recent-conversation card, a "new conversation" CTA, and host-defined links, plus a Home/Messages tab bar for switching back to the thread. An OBJECT, so it is a JS property only: `el.home = { greeting: { title: 'Hey' }, links: [...] }`, never an attribute (the kai- contract: array/object props are JS properties). A `links` entry with no `href` fires `kai-home-link` with that entry when tapped, rather than navigating; one WITH `href` opens it directly (only when the URL passes the kit's own scheme allowlist). Omit for the no-home widget (chat view only, unchanged). |
 
 **Events** (non-bubbling `CustomEvent`s — listen directly on the element):
 
@@ -1621,6 +1624,8 @@ _No events._
 |---|---|---|
 | `kai-attachments-change` | `CustomEvent<{ attachments: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[] }>` | The staged attachments changed (file added or removed). Carries the full current list so a consumer can react in real time. |
 | `kai-attachments-rejected` | `CustomEvent<{ rejected: { filename: string; mediaType: string; reason: "filtered" \| "unsupported" }[] }>` | One or more picked files were refused because `accept` excluded them. The element renders NO message of its own: it reports the facts (name, media type, whether the kit could have sent it) and what the user should see is the application's call. Only ever fires when `accept` is set. |
+| `kai-conversation-load` | `CustomEvent<{ id: string \| undefined; messages: { id: string; role: "user" \| "assistant"; parts: ({ type: "text"; text: string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "reasoning"; text: string; label?: undefined \| string; index?: undefined \| number; streamId?: undefined \| string; signature?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "tool"; tool: { type: string; kind?: undefined \| "command" \| "file-change" \| "search" \| "fetch" \| "mcp" \| "image" \| "generic"; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; rawInput?: undefined \| string; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "card"; envelope: { type: string; id: string; data: unknown; title?: undefined \| string; resolution?: undefined \| { kind: "action"; action: string; payload?: unknown; at?: undefined \| string } \| { kind: "submit"; data: unknown; at?: undefined \| string } \| { kind: "dismissed"; at?: undefined \| string } \| { kind: "expired"; reason?: undefined \| string; at?: undefined \| string } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "source"; source: { id?: undefined \| string; url?: undefined \| string; title?: undefined \| string; snippet?: undefined \| string; index?: undefined \| number }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "file"; attachment: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }; raw?: undefined \| { source: string; payload: unknown } })[]; actions?: undefined \| ("copy" \| "like" \| "dislike" \| "regenerate" \| "edit" \| { id: string; label: string; icon?: undefined \| string; tooltip?: undefined \| string })[]; avatar?: undefined \| { src?: undefined \| string; fallback?: undefined \| string; alt?: undefined \| string }; feedback?: undefined \| "like" \| "dislike" }[] }>` | A conversation's history loaded: a row tap in the list, "new conversation," or the visitor's own mount-time auto-restore of their most recent thread (only fires when `conversations` is on and a `store` is set). `detail.id` is that conversation's id, `undefined` for the "new conversation" case (no id exists until the first message mints one, C-6). Set `el.messages = event.detail.messages` (already a fresh array) to actually render it, since this element does not do that for you; `messages` stays your own state like everywhere else on this element. |
+| `kai-home-link` | `CustomEvent<{ entry: { label: string; href?: undefined \| string; description?: undefined \| string; icon?: undefined \| string } }>` | A `home.links` entry with no `href` was activated (tapped/clicked/Enter). Meaningful only when `home` is set. |
 | `kai-message-action` | `CustomEvent<{ messageId: string; action: string; state?: undefined \| "on" \| "off" }>` | An action button on a message was clicked. `action` is the built-in name or custom id. `state` is present only for the toggleable feedback votes: `'on'` when a like/dislike is set, `'off'` when re-tapped to clear. |
 | `kai-model-change` | `CustomEvent<{ modelId: string }>` | The header model switcher changed. |
 | `kai-submit` | `CustomEvent<{ value: string; attachments: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[] }>` | User submitted a message. |
@@ -2055,7 +2060,7 @@ _No events._
 |---|---|---|---|
 | `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
 | `groups` | — | `undefined \| { id: string; userId?: undefined \| string; teamId?: undefined \| string; name: string; sortOrder: number; createdAt: string }[]` | The list's section headers (`{ id, name, sortOrder, createdAt }`), rendered in array order. A group carries no conversations of its own; it is matched against `conversations` by id, so the two props are complementary rather than alternatives. Omit for an ungrouped list. Set as a JS property. |
-| `conversations` | — | `undefined \| { id: string; title: string; groupId?: undefined \| string; scope?: undefined \| { type: "document" \| "collection"; documentId?: undefined \| string; filters?: undefined \| { tags?: undefined \| string[]; authors?: undefined \| string[]; contentType?: undefined \| "transcript" \| "markdown"; dateRange?: undefined \| { from: string; to: string } } }; messageCount: number; lastMessageAt?: undefined \| string; updatedAt: string; trailing?: undefined \| string }[]` | Every conversation the list renders, flat. Each one is filed under the group whose `id` equals its `groupId`; one with no `groupId`, or with a `groupId` matching no entry in `groups`, falls into a trailing "Ungrouped" section, so nothing you pass in is ever dropped. There is no recency bucketing. Set as a JS property. Omit to supply them as `<kai-conversation>` light-DOM children instead, or for the empty state. A search query that matches nothing shows a visible "No conversations match your search" state, distinct from the zero-conversations empty state. Slotted `<kai-conversation-item>` children switch the list into item mode instead: your own rows win and this array is not rendered. |
+| `conversations` | — | `undefined \| { id: string; title: string; groupId?: undefined \| string; scope?: undefined \| { type: "document" \| "collection"; documentId?: undefined \| string; filters?: undefined \| { tags?: undefined \| string[]; authors?: undefined \| string[]; contentType?: undefined \| "transcript" \| "markdown"; dateRange?: undefined \| { from: string; to: string } } }; messageCount: number; lastMessageAt?: undefined \| string; updatedAt: string; trailing?: undefined \| string; lastReadAt?: undefined \| string }[]` | Every conversation the list renders, flat. Each one is filed under the group whose `id` equals its `groupId`; one with no `groupId`, or with a `groupId` matching no entry in `groups`, falls into a trailing "Ungrouped" section, so nothing you pass in is ever dropped. There is no recency bucketing. Set as a JS property. Omit to supply them as `<kai-conversation>` light-DOM children instead, or for the empty state. A search query that matches nothing shows a visible "No conversations match your search" state, distinct from the zero-conversations empty state. Slotted `<kai-conversation-item>` children switch the list into item mode instead: your own rows win and this array is not rendered. |
 | `activeId` | `active-id` | `undefined \| string` | The id of the currently-open conversation, highlighted in the list. |
 | `collapsed` | `collapsed` | `undefined \| false \| true` | Controlled collapsed state. Set as a JS property (`el.collapsed = true`) to drive the rail from your app, updating it in response to `kai-collapse-toggle`. Omit for uncontrolled (the element manages it). Collapsed shrinks the rail to a floating reopen button. |
 | `defaultCollapsed` | `default-collapsed` | `undefined \| false \| true` | Initial collapsed state when uncontrolled (default false). Use the `default-collapsed` attribute to start collapsed in plain HTML. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitn.ai/ui",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "nx": {
     "name": "ui",
     "targets": {

package/src/agent-tooling/README.md

@@ -0,0 +1,192 @@
+# `agent-tooling/`
+
+The kit's machine-facing front door: everything that makes AI coding agents
+and CLIs fluent building with `@kitn.ai/ui`. It is packaging and tooling on
+top of the library, not part of it — `grep -rn "agent-tooling"
+packages/ui/src/components packages/ui/src/elements` returns no imports (only
+a code comment and a test's `UNSCANNED_DIRS` entry mention the directory by
+name). Nothing a consumer's chat UI renders depends on anything in here.
+
+## The four parts
+
+```
+                 ┌─────────────────────────┐
+                 │   kai MCP server (mcp/)  │
+                 │  construct · scaffold ·  │
+                 │  reference · theme ·     │
+                 │  debug                   │
+                 └───────┬─────────┬────────┘
+                         consumes  consumes
+                          │         │
+                          ▼         ▼
+              ┌────────────────┐ ┌──────────────────┐
+              │ construct/      │ │ catalog/          │
+              │ (schema→codegen │ │ (invariants,      │
+              │  →cli engine)   │ │  surfaces,        │
+              └────────▲────────┘ │  fabrications, …) │
+                       │          └───────────────────┘
+                  standalone,
+                  no MCP involved
+                       │
+              ┌────────┴────────┐
+              │ bin/mcp.js CLI   │
+              │ validate/dev/    │
+              │ compile/eject    │
+              └──────────────────┘
+```
+
+- **`mcp/`** — the `kai` MCP server. The tools in `mcp/tools/`:
+  - `construct.ts` — turn-by-turn authoring of a construct JSON file (one
+    JSON file → one web component); stateless, the harness owns the file.
+  - `scaffold.ts` — generates a full chat integration (framework + backend
+    route + integration wiring) from `agent-tooling/registry.ts` and
+    `agent-tooling/archetypes.ts` (backed by `agent-tooling/integrations/`).
+  - `reference.ts` — component/element/card lookup for an agent deciding what
+    to use.
+  - `theme.ts` — produces a `--kai-*` CSS token override block from a brand
+    color or description, resolved against the kit's own `theme.css`.
+  - `debug.ts` — diagnoses common `kai-*` integration failures from a
+    symptom/snippet, sourced from `apps/docs/src/content/docs/guides/for-ai-agents.mdx`.
+- **`construct/`** — the construct engine: a declarative JSON format compiled
+  to a self-registering web component. Pipeline is `schema.ts` (Zod, single
+  source of truth) → `codegen.ts` (the one generation path — `kai dev`,
+  `kai compile`, and `kai eject` all call the same `generateProject`) →
+  `cli.ts` (the `validate | eject | dev | compile` subcommands). Fixtures
+  live in `construct/fixtures/` (`demo-widget`, `ops-console`,
+  `owner-widget`). The published JSON Schema artifact is
+  `construct/construct.v1.schema.json`, mirrored byte-identical at
+  `apps/docs/public/schemas/construct/v1.json`; both are guarded against
+  drift from the Zod source by `construct/schema-artifact.test.ts` (asserts
+  the checked-in artifact equals `z.toJSONSchema(ConstructSchema)` right now)
+  and regenerated by `scripts/gen-construct-schema.mjs` via `build:api`.
+- **`catalog/`** — Zod-typed reference data, mostly independent of the
+  construct engine, each file feeding a specific consumer:
+  - `catalog-types.ts` — the shared Zod types (`SurfaceArchetype`,
+    `DeliveryTarget`, `WireReader`, `Backend`, …) the rest of the catalog is
+    built from.
+  - `invariants.ts` — the composition invariants an agent must hold, each
+    with an `enforcedBy` path and a `lint` script name; feeds
+    `invariants.test.ts` and the acceptance harness.
+  - `surfaces.ts` — the sorted inventory of product-shaped surfaces vs.
+    ingredients vs. corpus; feeds `surfaces.test.ts` and `derived.json`.
+  - `fabrications.ts` — tags agents have invented while working from an
+    acceptance pack (and what they should have used instead); renders the
+    pack's `FABRICATED.md`, checked against `derived.json` in both directions
+    by `fabrications.test.ts`.
+  - `scenarios.ts` — the acceptance deck (spec §6): prompts + what each
+    needs, written before the catalog it measures.
+  - `labs-titles.ts` — parses the real `Labs/…` story titles registered by
+    story files (TypeScript AST, not a regex), used to keep the catalog's
+    story inventory honest.
+  - `derived.json` — generated inventory of elements/props read by
+    `catalog-types.ts`, `fabrications.ts`, and `surfaces.ts` (and their
+    tests) rather than by anything outside the catalog.
+  - `catalog/README.md` — the catalog's own deeper documentation.
+
+How they relate: the MCP's `construct` and `scaffold` tools **consume** the
+construct engine and the catalogs — they don't reimplement authoring logic,
+they call into `construct/schema.ts` / `construct/codegen.ts` and read the
+registry/catalog data. The construct CLI (`bin/mcp.js validate|dev|compile|eject`,
+built from `construct/cli-entry.ts` → `dist/construct-cli.es.js`) runs the
+engine standalone, with no MCP server involved at all.
+
+## Usage
+
+- **`npx @kitn.ai/ui mcp`** starts the MCP server (the historical default
+  subcommand). For wiring it into a multi-harness setup, see the docs site's
+  agents guide: `apps/docs/src/content/docs/guides/for-ai-agents.mdx`.
+- **CLI form**, no MCP: `node bin/mcp.js validate|dev|compile|eject <construct.json>`
+  (`bin/mcp.js` dispatches `dev`/`compile`/`eject`/`validate` to the construct
+  CLI and anything else, including `mcp` or no argument, to the MCP server;
+  an unrecognized subcommand is a loud error, not a silent fallthrough).
+  `eject` writes a real Solid project you own; `dev` gives a live-reload
+  preview; `compile` emits one self-registering `.js`.
+- **Acceptance harness** (`packages/ui/scripts/acceptance-*.mjs`:
+  `acceptance-pack.mjs`, `acceptance-run.mjs`, `acceptance-eval.mjs`,
+  `acceptance-gate-compiles.mjs`) — builds and grades a coding agent's
+  from-scratch attempt at using the catalog with no kit source, per the
+  scenarios in `catalog/scenarios.ts`; this is how the catalog's own claims
+  get checked against a real agent rather than asserted.
+
+## Worked example
+
+`construct/fixtures/owner-widget.construct.json`, field by field:
+
+- `"$schema"` — points at the published schema URL for editor validation.
+- `"name": "acme-support"` — the construct's name; also the emitted custom
+  element's tag basis.
+- `"layout": "widget"` — a floating launcher widget, not full-screen or docked.
+- `"provider": { "mode": "mock" }` — no backend; canned responses (vs.
+  `mode: "endpoint"`, the consumer's own chat route).
+- `"userId": "user_123"` — the identity value threaded through for
+  history/persistence.
+- `"header": { "title": "Acme Support" }` — the chat header's title text.
+- `"theme": { "unreadColor": "#38BDF8" }` — one branded token override.
+- `"empty": { "title": ..., "description": ... }` — the empty-state copy
+  shown before the first message.
+- `"widget": { "position": "top-start", "defaultOpen": true }` — widget-layout
+  placement and initial open state.
+- `"capabilities.attachments.accept"` — allowed MIME patterns for uploads.
+- `"capabilities.history.persistence": "local"` — history persisted in the
+  browser, not the consumer's backend.
+- `"capabilities.starters"` — suggested first prompts.
+- `"capabilities.reasoningOpen": true` — reasoning panels start expanded.
+- `"capabilities.conversations": true` — enables the conversations sidebar.
+
+`codegen.ts` turns this into a small, deterministic (no dates, no randomness,
+fixed key order) Solid project: pure Solid interior composing
+`@kitn.ai/ui/solid` components, provider glue built on `@kitn.ai/ui/state` +
+`@kitn.ai/ui/wire` (never a hand-rolled SSE reader), and one
+`defineWebComponent` facade carrying the tag, theme default, and slots. The
+facade injects the kit's compiled CSS into the shadow root, so the generated
+project needs no Tailwind and no CSS build step. `kai dev`, `kai compile`,
+and `kai eject` all go through this same generation path — the preview is
+the artifact, there is no separate interpreter to drift from it.
+
+## Rules that bind changes here
+
+- **Vocabulary never logic** — the construct format has no handlers and no
+  expressions; it describes, it doesn't script. `schema.ts` is `.strict()`
+  everywhere, so an unknown key is a loud rejection.
+- **Widen, never restructure `schema.ts`** — it's the single source of truth;
+  never hand-edit the generated JSON Schema artifacts or restate an enum
+  elsewhere, read it off `ConstructSchema.shape` or the generated artifact.
+- **Derive, don't type** — the published schema artifact is generated from
+  Zod (`scripts/gen-construct-schema.mjs`, run by `build:api`) and pinned by
+  `construct/schema-artifact.test.ts`; `verify:construct`'s layout and
+  capability axes are read off that same drift-guarded artifact rather than
+  hand-listed, so adding a layout or capability to the Zod schema moves what
+  the gate covers on its own.
+- **`verify:construct`** (`scripts/verify-construct.mjs`) drives the real CLI
+  end to end against this checkout's own packed tarball — eject, install,
+  compile under the emitted tsconfig, build, and bundle inside a real
+  consumer app — for every layout/capability combination the schema
+  currently declares. No unit test in this tree leaves the process; this is
+  the one that does.
+- **`verify:scaffold`** (`scripts/verify-scaffold-compiles.mjs`) compiles the
+  scaffolder's emitted front ends and backend routes under `tsc --strict`
+  across the integration × surface × framework axes derived from the
+  registry, plus structural checks (e.g. the Solid emit branches on every
+  `MessagePart` variant).
+- **`verify:generated`** (`scripts/verify-generated-sync.mjs`) re-runs
+  `build:api` and fails if any derived artifact in the tree (including
+  catalog/manifest files this directory reads) differs from what the
+  generator produces right now — catches drift `nx build ui`'s NX cache can
+  hide.
+- **The schema-artifact test pair** (`construct/schema-artifact.test.ts`)
+  catches a `schema.ts` edit that shipped without a regen, in the unit suite
+  itself rather than only in CI's `verify:generated`.
+
+## Where deeper docs live
+
+- Repo root [`CLAUDE.md`](../../../../CLAUDE.md)'s **Map** section for how
+  this directory sits relative to `primitives/`, `ui/`, `components/`, and
+  `elements/`.
+- [`.claude/README.md`](../../../../.claude/README.md) for the project-local
+  skills/agents that exercise this tooling (notably `/consumer-regression`).
+- The docs site's agents guide,
+  `apps/docs/src/content/docs/guides/for-ai-agents.mdx` — the rules
+  `debug.ts` and the MCP's contract enforcement are sourced from.
+- `docs/superpowers/specs/2026-08-25-construct-engine-design.md` — the
+  construct engine's design spec (decisions ledger, format rules, success
+  criteria).

package/src/agent-tooling/catalog/invariants.ts

@@ -142,9 +142,9 @@ export const invariants: TInvariant[] = [
     ],
     examples: [
       {
-        wrong: 'chat.conversations = rows;',
+        wrong: 'chat.conversationRows = rows;',
         right: 'conversations.conversations = rows;',
-        note: 'kai-chat has no conversations prop — the sidebar is its own element. One element never holds the whole app state.',
+        note: "kai-chat's own `conversations` prop is a boolean flag (turns the built-in list panel on); it has no `conversationRows`-shaped data prop, and the sidebar is its own element. One element never holds the whole app state.",
       },
       {
         wrong: "chat.addEventListener('kai-conversation-select', (e) => load(e.detail.id));",

package/src/agent-tooling/construct/cli.ts

@@ -25,6 +25,20 @@ const USAGE = `usage: kai <command>
   kai compile <construct.json> [outDir]  one self-registering .js (Task 6)
 `;
 
+/** H-3, decide loudly: `home.recentConversation` renders nothing without
+ *  `capabilities.conversations` to draw the card from — never fatal (the
+ *  schema explicitly does NOT require conversations for `home`, see
+ *  schema.ts's own doc on `home`), just a non-blocking heads-up at validate
+ *  time, the same idiom `validate`'s success line already uses (io.log, not
+ *  a bare console call). Extracted so it can be unit-tested without going
+ *  through the CLI's stdout wiring. */
+export function homeRecentConversationWarning(construct: Construct): string | null {
+  if (construct.home?.recentConversation && !construct.capabilities?.conversations) {
+    return 'warning: home.recentConversation is set but capabilities.conversations is not — the recent-conversation card will render nothing without it.';
+  }
+  return null;
+}
+
 export function loadConstruct(path: string, io: CliIo): Construct | null {
   const abs = resolve(path);
   let raw: string;
@@ -66,6 +80,8 @@ export async function runCli(argv: string[], io: CliIo = defaultIo): Promise<num
       const construct = loadConstruct(rest[0] ?? '', io);
       if (!construct) return 1;
       io.log(`valid construct: <${construct.name}> (layout: ${construct.layout}, provider: ${construct.provider.mode})`);
+      const warning = homeRecentConversationWarning(construct);
+      if (warning) io.log(warning);
       return 0;
     }
     case 'eject': {