@kitn.ai/ui 0.21.0 → 0.22.0

package/frameworks/react/index.tsx

@@ -203,7 +203,7 @@ export interface ButtonProps extends WebComponentProps {
   icon?: string;
   /** Trailing icon, after the label (e.g. `"chevron-down"` for a menu affordance). */
   iconTrailing?: string;
-  /** Accessible name. REQUIRED for icon-only buttons (no visible text); ignored when you slot visible text, which already names the button. */
+  /** Accessible name. REQUIRED for icon-only buttons (no visible text); ignored when you slot visible text, which already names the button. An `aria-label` on top of visible text REPLACES that name rather than adding to it, so a button reading "Save" that answers to "Submit" is unusable by speech input (WCAG 2.5.3, Label in Name). The visible text wins. An `icon` / `icon-sm` size hides the slot, which makes the button icon-only whatever you slotted, so `label` is what names it there. */
   label?: string;
   /** Disable the button (non-interactive, dimmed). */
   disabled?: boolean;
@@ -353,6 +353,8 @@ export interface ChatProps extends WebComponentProps {
   kindIcons?: Record<string, string>;
   /** Whether each message's action bar is always visible (`'always'`, default) or only revealed on hover of that message row (`'hover'`). */
   actionsReveal?: "always" | "hover";
+  /** Which attachment media types the user may stage, in HTML `accept` syntax: `<kai-chat accept="image/*,application/pdf">`. A plain string, so unlike `messages` it DOES work as an attribute. Omitted means no filter. MEDIA TYPES ONLY -- exact (`image/png`) or subtype wildcard (`text/*`). HTML allows a file extension here and this does not: `accept=".py"` THROWS with the entry named, rather than silently resolving to a picker that accepts nothing. It can only NARROW what the kit can already encode: `accept="image/*"` resolves to the four image formats both APIs take, not to every image type the OS offers. Pass the SAME string to `toOpenAIMessages(msgs, { accept })` and the picker and the wire cannot disagree -- both resolve it through `resolveMediaPolicy` against one declaration. That declaration is readable as `encodableMediaTypes()` from `@kitn.ai/ui/wire`, if you would rather build your own picker than use this prop. */
+  accept?: string;
   /** 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>`. */
   messages?: { id: string; role: "user" | "assistant"; parts: ({ type: "text"; text: string; raw?: { source: string; payload: unknown } } | { type: "reasoning"; text: string; label?: string; index?: number; streamId?: string; signature?: string; raw?: { source: string; payload: unknown } } | { type: "tool"; tool: { type: string; kind?: "command" | "file-change" | "search" | "fetch" | "mcp" | "image" | "generic"; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; rawInput?: string; output?: Record<string, unknown>; toolCallId?: string; errorText?: string; raw?: { source: string; payload: unknown } }; raw?: { source: string; payload: unknown } } | { type: "card"; envelope: { type: string; id: string; data: unknown; title?: string; resolution?: { kind: "action"; action: string; payload?: unknown; at?: string } | { kind: "submit"; data: unknown; at?: string } | { kind: "dismissed"; at?: string } | { kind: "expired"; reason?: string; at?: string } }; raw?: { source: string; payload: unknown } } | { type: "source"; source: { id?: string; url?: string; title?: string; snippet?: string; index?: number }; raw?: { source: string; payload: unknown } } | { type: "file"; attachment: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }; raw?: { source: string; payload: unknown } })[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: string; tooltip?: string })[]; avatar?: { src?: string; fallback?: string; alt?: string }; feedback?: "like" | "dislike" }[];
   /** 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. */
@@ -361,6 +363,8 @@ export interface ChatProps extends WebComponentProps {
   cardSchemas?: Record<string, object>;
   /** The staged attachments changed (file added or removed). Carries the full current list so a consumer can react in real time. */
   onAttachmentsChange?: (event: CustomEvent<{ attachments: { id: string; type: "file" | "source-document"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[] }>) => void;
+  /** 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. */
+  onAttachmentsRejected?: (event: CustomEvent<{ rejected: { filename: string; mediaType: string; reason: "filtered" | "unsupported" }[] }>) => void;
   /** 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. */
   onMessageAction?: (event: CustomEvent<{ messageId: string; action: string; state?: undefined | "on" | "off" }>) => void;
   /** The header model switcher changed. */
@@ -379,8 +383,8 @@ export interface ChatProps extends WebComponentProps {
 
 export const Chat = /*#__PURE__*/ createWebComponent<ChatProps>(
   'kai-chat',
-  ["theme","search","value","placeholder","loading","suggestions","suggestionMode","persistSuggestions","proseSize","codeTheme","codeHighlight","chatTitle","models","currentModel","context","scrollButton","headerStart","headerEnd","headerFull","sidebar","empty","composer","composerActions","footer","voice","triggers","kindIcons","actionsReveal","messages","cardTypes","cardSchemas"],
-  { onAttachmentsChange: 'kai-attachments-change', onMessageAction: 'kai-message-action', onModelChange: 'kai-model-change', onSearch: 'kai-search', onSubmit: 'kai-submit', onSuggestionClick: 'kai-suggestion-click', onValueChange: 'kai-value-change', onVoice: 'kai-voice' },
+  ["theme","search","value","placeholder","loading","suggestions","suggestionMode","persistSuggestions","proseSize","codeTheme","codeHighlight","chatTitle","models","currentModel","context","scrollButton","headerStart","headerEnd","headerFull","sidebar","empty","composer","composerActions","footer","voice","triggers","kindIcons","actionsReveal","accept","messages","cardTypes","cardSchemas"],
+  { onAttachmentsChange: 'kai-attachments-change', onAttachmentsRejected: 'kai-attachments-rejected', onMessageAction: 'kai-message-action', onModelChange: 'kai-model-change', onSearch: 'kai-search', onSubmit: 'kai-submit', onSuggestionClick: 'kai-suggestion-click', onValueChange: 'kai-value-change', onVoice: 'kai-voice' },
   () => import('@kitn.ai/ui/elements/chat'),
 );
 
@@ -973,11 +977,11 @@ export interface MenuProps extends WebComponentProps {
   placement?: string;
   /** Built-in trigger: leading icon (a named icon like `"plus"`, an image URL/data-URI, or text). Use this instead of slotting `slot="trigger"` for the common case; a slotted trigger overrides it. */
   triggerIcon?: string;
-  /** Built-in trigger: a text label (e.g. `"High"`). */
+  /** Built-in trigger: a text label (e.g. `"High"`). This is the trigger's VISIBLE text, so it is also its accessible name, and `label` does not override it: an accessible name that does not contain the visible text is unreachable by speech input, which is what WCAG 2.5.3 (Label in Name) exists for. A slotted `slot="trigger"` replaces this built-in trigger entirely and is named differently; see `label`. */
   triggerLabel?: string;
   /** Built-in trigger: a trailing icon (e.g. `"chevron-down"` for a select look). */
   triggerIconTrailing?: string;
-  /** Accessible name for an icon-only trigger (no visible label). */
+  /** Accessible name for a trigger with no visible label. Ignored when `triggerLabel` is set, which is already the visible name. It DOES name a slotted `slot="trigger"`, and that is a difference in what the two slots MEAN, not a limitation. `<kai-button>`'s slot IS the button's label, so text slotted there is the name and `label` steps aside. This slot is VISUAL content, a `+` or an `<svg>`, with the name supplied separately: decoration beside a name, never a second name competing with one. So `label` names the trigger here by design. Slotting a real WORD rather than a glyph makes that word a visible label, and an accessible name has to contain the visible text. Then either drop `label` or make it contain the word you slotted. */
   label?: string;
   /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute, the menu still self-manages on click/keyboard). Set `el.open = true`, or `<kai-menu open>`; listen for `kai-open-change`. */
   open?: boolean;

package/llms-full.txt

@@ -449,7 +449,7 @@ _No events._
 | `size` | `size` | `undefined \| "sm" \| "md" \| "lg" \| "icon" \| "icon-sm"` | Size token. `icon` / `icon-sm` are square (for icon-only buttons); `sm` / `md` / `lg` size text buttons. Defaults to `md`. |
 | `icon` | `icon` | `undefined \| string` | Leading icon: a named icon (e.g. `"mic"`, `"plus"`), an image URL/data-URI, or plain text. Renders before any slotted label. |
 | `iconTrailing` | `icon-trailing` | `undefined \| string` | Trailing icon, after the label (e.g. `"chevron-down"` for a menu affordance). |
-| `label` | `label` | `undefined \| string` | Accessible name. REQUIRED for icon-only buttons (no visible text); ignored when you slot visible text, which already names the button. |
+| `label` | `label` | `undefined \| string` | Accessible name. REQUIRED for icon-only buttons (no visible text); ignored when you slot visible text, which already names the button. An `aria-label` on top of visible text REPLACES that name rather than adding to it, so a button reading "Save" that answers to "Submit" is unusable by speech input (WCAG 2.5.3, Label in Name). The visible text wins. An `icon` / `icon-sm` size hides the slot, which makes the button icon-only whatever you slotted, so `label` is what names it there. |
 | `disabled` | `disabled` | `undefined \| false \| true` | Disable the button (non-interactive, dimmed). |
 | `full` | `full` | `undefined \| false \| true` | Stretch the button to the full width of its container (a block button), e.g. a card CTA or a stacked action. Attribute: `full`. |
 | `align` | `align` | `undefined \| "start" \| "center" \| "end"` | Justify the button's content: `start`, `center` (default), or `end`. Combine with `full` for a full-width, left-aligned button. |
@@ -629,6 +629,7 @@ _No events._
 | `triggers` | — | `undefined \| { char: string; kind: string; items?: undefined \| { id: string; label: string; icon?: undefined \| string; description?: undefined \| string; group?: undefined \| string; kind?: undefined \| string; promptText?: undefined \| string; data?: undefined \| Record<string, unknown> }[] }[]` | Rich entity triggers. Each `{ char, kind, items }` opens a caret-anchored menu that inserts an atomic pill (`/` skills, `@` agents/plugins). Set as a JS property; forwarded to the input. |
 | `kindIcons` | — | `undefined \| Record<string, string>` | Default icon per entity kind (kind → image src) for pills/menu items. |
 | `actionsReveal` | `actions-reveal` | `undefined \| "always" \| "hover"` | Whether each message's action bar is always visible (`'always'`, default) or only revealed on hover of that message row (`'hover'`). |
+| `accept` | `accept` | `undefined \| string` | Which attachment media types the user may stage, in HTML `accept` syntax: `<kai-chat accept="image/*,application/pdf">`. A plain string, so unlike `messages` it DOES work as an attribute. Omitted means no filter. MEDIA TYPES ONLY -- exact (`image/png`) or subtype wildcard (`text/*`). HTML allows a file extension here and this does not: `accept=".py"` THROWS with the entry named, rather than silently resolving to a picker that accepts nothing. It can only NARROW what the kit can already encode: `accept="image/*"` resolves to the four image formats both APIs take, not to every image type the OS offers. Pass the SAME string to `toOpenAIMessages(msgs, { accept })` and the picker and the wire cannot disagree -- both resolve it through `resolveMediaPolicy` against one declaration. That declaration is readable as `encodableMediaTypes()` from `@kitn.ai/ui/wire`, if you would rather build your own picker than use this prop. |
 | `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. |
@@ -638,6 +639,7 @@ _No events._
 | Event | `detail` type | Description |
 |---|---|---|
 | `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-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-search` | `CustomEvent<Record<string, never>>` | The Search button was clicked. |
@@ -951,6 +953,13 @@ _No events._
 |---|---|---|
 | `kai-threshold-change` | `CustomEvent<{ level: "ok" \| "warn" \| "danger" }>` | Fires when the computed severity level changes (ok → warn → danger or back). `detail.level` is `'ok'`, `'warn'`, or `'danger'`. |
 
+**Styleable parts** (restyle from outside via `kai-context::part(name)`):
+
+| Part | Description |
+|---|---|
+| `::part(track)` | The usage meter track inside the hover-card breakdown. Carries `role="progressbar"` and is in the DOM only while the card is open. Restyle its height, radius, or background from outside. — `kai-context::part(track) { height: 0.5rem }` |
+| `::part(fill)` | The used-tokens portion of that meter. Its width follows `usedTokens / maxTokens`; its default color is the severity hue picked by `warnThreshold` / `dangerThreshold`, so recoloring it from outside replaces that signal. — `kai-context::part(fill) { background: var(--color-tool-blue) }` |
+
 ---
 
 ### `kai-conversations` / `Conversations`
@@ -1450,9 +1459,9 @@ _No events._
 | `items` | — | `undefined \| { id?: undefined \| string; label?: undefined \| string; icon?: undefined \| string; shortcut?: undefined \| string; checked?: undefined \| false \| true; radioGroup?: undefined \| string; disabled?: undefined \| false \| true; separator?: undefined \| false \| true; heading?: undefined \| false \| true; items?: undefined \| Record<string, unknown>[] }[]` | Tree of menu items. Set as a JS property, not an HTML attribute. |
 | `placement` | `placement` | `undefined \| string` | Optional placement hint (unused by the underlying Dropdown which always positions bottom-start, kept for future extension). |
 | `triggerIcon` | `trigger-icon` | `undefined \| string` | Built-in trigger: leading icon (a named icon like `"plus"`, an image URL/data-URI, or text). Use this instead of slotting `slot="trigger"` for the common case; a slotted trigger overrides it. |
-| `triggerLabel` | `trigger-label` | `undefined \| string` | Built-in trigger: a text label (e.g. `"High"`). |
+| `triggerLabel` | `trigger-label` | `undefined \| string` | Built-in trigger: a text label (e.g. `"High"`). This is the trigger's VISIBLE text, so it is also its accessible name, and `label` does not override it: an accessible name that does not contain the visible text is unreachable by speech input, which is what WCAG 2.5.3 (Label in Name) exists for. A slotted `slot="trigger"` replaces this built-in trigger entirely and is named differently; see `label`. |
 | `triggerIconTrailing` | `trigger-icon-trailing` | `undefined \| string` | Built-in trigger: a trailing icon (e.g. `"chevron-down"` for a select look). |
-| `label` | `label` | `undefined \| string` | Accessible name for an icon-only trigger (no visible label). |
+| `label` | `label` | `undefined \| string` | Accessible name for a trigger with no visible label. Ignored when `triggerLabel` is set, which is already the visible name. It DOES name a slotted `slot="trigger"`, and that is a difference in what the two slots MEAN, not a limitation. `<kai-button>`'s slot IS the button's label, so text slotted there is the name and `label` steps aside. This slot is VISUAL content, a `+` or an `<svg>`, with the name supplied separately: decoration beside a name, never a second name competing with one. So `label` names the trigger here by design. Slotting a real WORD rather than a glyph makes that word a visible label, and an accessible name has to contain the visible text. Then either drop `label` or make it contain the word you slotted. |
 | `open` | `open` | `undefined \| false \| true` | Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute, the menu still self-manages on click/keyboard). Set `el.open = true`, or `<kai-menu open>`; listen for `kai-open-change`. |
 | `defaultOpen` | `default-open` | `undefined \| false \| true` | Initial open state on mount (uncontrolled seed). |
 | `disabled` | `disabled` | `undefined \| false \| true` | Disable the trigger: click/keyboard and `show()` no longer open the menu. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitn.ai/ui",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "nx": {
     "name": "ui",
     "targets": {
@@ -177,6 +177,7 @@
     "verify:ssr:imports": "node scripts/verify-ssr-imports.mjs",
     "verify:ssr:render": "node scripts/verify-ssr-render.mjs",
     "verify:pack": "node scripts/verify-pack-weight.mjs",
+    "verify:starters": "node scripts/verify-starters.mjs",
     "test": "vitest run",
     "test:react": "vitest run --config vitest.react.config.ts",
     "test:storybook": "vitest run --project=storybook",

package/src/agent-tooling/archetypes.ts

@@ -55,6 +55,34 @@ export const archetypes: Archetype[] = [
     defaultPlacement: 'full-page',
     docsSlug: 'examples/voice-assistant',
   },
+  /**
+   * THE PRESET THAT EXISTS TO MAKE A CAPABILITY REACHABLE, not to name a product
+   * shape someone asked for.
+   *
+   * `kai-file-upload` and `kai-attachments` were registered elements that NO
+   * preset composed, and `listCapabilityGroups` derives its answer from this
+   * table — so the attachments capability reached neither `listSurfaceProbes`
+   * nor `verify:scaffold`, and `renderSurface` had no branch that emitted either
+   * tag. A caller could pass them in `components` (the axis takes any list) and
+   * get two bare `<kai-file-upload></kai-file-upload>` / `<kai-attachments>`
+   * siblings with nothing wired to them: on screen, inert, silent.
+   *
+   * The pair is ONE capability for the same reason `kai-artifact` +
+   * `kai-resizable` are: a dropzone with no list is a black hole, and a list
+   * with no dropzone can never fill. `hasAttachments` in scaffold.ts requires
+   * both for exactly that reason.
+   *
+   * The components match the create-kai spec's own feature table
+   * (`attachments` -> `kai-file-upload`, `kai-attachments`), so the CLI's
+   * multi-select and this preset name the same surface rather than two.
+   */
+  {
+    id: 'attachments',
+    title: 'File attachments',
+    components: ['kai-chat', 'kai-file-upload', 'kai-attachments'],
+    defaultPlacement: 'full-page',
+    docsSlug: 'examples/attachments',
+  },
 ];
 
 /** The component every surface composes around, so never a capability by itself. */
@@ -71,9 +99,10 @@ export interface CapabilityGroup {
  * The distinct capabilities the presets know about, DERIVED from them.
  *
  * A capability is one preset's components minus `kai-chat`, deduped across the
- * catalog. Today that is four: `sources`, `tool+reasoning`, `artifact+resizable`,
- * `voice-input` — and the six presets collapse onto them because `drop-in-chat`
- * and `support-widget` both add nothing (they differ only in `defaultPlacement`).
+ * catalog. Today that is five: `sources`, `tool+reasoning`, `artifact+resizable`,
+ * `voice-input`, `file-upload+attachments` — and the seven presets collapse onto
+ * them because `drop-in-chat` and `support-widget` both add nothing (they differ
+ * only in `defaultPlacement`).
  *
  * Derived rather than listed for the reason the verify script's other axes are:
  * a hand-written list would have to be edited by the same hand that adds a
@@ -83,9 +112,11 @@ export interface CapabilityGroup {
  *
  * The grouping is real and not an artifact of the derivation: `kai-tool` and
  * `kai-reasoning` are one capability because a tool panel with no reasoning
- * disclosure is not a surface anyone asks for, and `kai-artifact` /
+ * disclosure is not a surface anyone asks for, `kai-artifact` /
  * `kai-resizable` are one because `isWorkspace` only fires when BOTH are present
- * — split them and the renderer emits a bare artifact with no pane to put it in.
+ * — split them and the renderer emits a bare artifact with no pane to put it in
+ * — and `kai-file-upload` / `kai-attachments` are one because `hasAttachments`
+ * fires the same way, for the same kind of reason.
  */
 export function listCapabilityGroups(): CapabilityGroup[] {
   const seen = new Map<string, CapabilityGroup>();
@@ -109,14 +140,14 @@ export interface SurfaceProbe {
  * The surface axis for `verify:scaffold`: each capability ALONE, plus none, plus
  * ALL of them.
  *
- * WHY THESE AND NOT THE PRESETS. The presets are six cells covering five distinct
- * components lists (`support-widget` repeats `drop-in-chat`'s, and the matrix
- * holds `placement` at one value, so that pair compiled the same types twice).
- * More importantly they cover no combination at all — every preset is exactly one
- * capability — so the surfaces the multi-select makes reachable, which is most of
- * them, had nothing compiling them.
+ * WHY THESE AND NOT THE PRESETS. The presets are seven cells covering six
+ * distinct components lists (`support-widget` repeats `drop-in-chat`'s, and the
+ * matrix holds `placement` at one value, so that pair compiled the same types
+ * twice). More importantly they cover no combination at all — every preset is
+ * exactly one capability — so the surfaces the multi-select makes reachable,
+ * which is most of them, had nothing compiling them.
  *
- * WHY NOT THE POWER SET. 2^4 x 11 integrations x 8 frameworks is 1408 cells to
+ * WHY NOT THE POWER SET. 2^5 x 11 integrations x 8 frameworks is 2816 cells to
  * exercise no new branch. The renderers compose capabilities INDEPENDENTLY: each
  * companion tag is emitted on its own terms, and the one multi-component
  * predicate (`isWorkspace`) reads components from within a single group. So

package/src/agent-tooling/integrations/anthropic.ts

@@ -35,10 +35,19 @@ const anthropic: Integration = {
   // No per-framework templates: the handler below is web-standard, so the
   // scaffolder wraps it in whatever the target framework routes with.
   routeTemplates: {},
-  webRoute: `/** One Anthropic content block. Open union on the wire; these are the four the
+  webRoute: `/** Where an image or document's bytes come from. Anthropic takes both forms
+ *  for both block types, which is why this route has no gap where the
+ *  OpenAI-shaped one does: a chat-completions \`file\` part is base64-only. */
+type AnthropicSource =
+  | { type: 'base64'; media_type: string; data: string }
+  | { type: 'url'; url: string };
+
+/** One Anthropic content block. Open union on the wire; these are the ones the
  *  scaffold's own thread can produce. */
 type AnthropicBlock =
   | { type: 'text'; text: string }
+  | { type: 'image'; source: AnthropicSource }
+  | { type: 'document'; source: AnthropicSource }
   | { type: 'tool_use'; id: string; name: string; input: unknown }
   | { type: 'tool_result'; tool_use_id: string; content: string };
 
@@ -121,12 +130,24 @@ function toAnthropicBody(messages: ChatRequestBody['messages']): {
     switch (message.role) {
       case 'system': {
         // TOP-LEVEL, not a message. Several system turns concatenate.
-        const text = message.content ?? '';
+        const text = wireText(message.content);
         system = system === undefined ? text : \`\${system}\\n\\n\${text}\`;
         break;
       }
       case 'user': {
-        if (message.content) pushUser([{ type: 'text', text: message.content }]);
+        // Attachments ride HERE, as image and document blocks beside the text,
+        // in the order the thread authored them.
+        const blocks = wireParts(message.content).map((part): AnthropicBlock => {
+          if (part.kind === 'text') return { type: 'text', text: part.text };
+          const source: AnthropicSource =
+            part.source.type === 'data'
+              ? { type: 'base64', media_type: part.mediaType, data: part.source.data }
+              : { type: 'url', url: part.source.url };
+          // \`image/png\` and the bare top-level \`image\` both mean an image; a URL
+          // source reports only the segment because the wire carries no more.
+          return part.mediaType.startsWith('image') ? { type: 'image', source } : { type: 'document', source };
+        });
+        if (blocks.length > 0) pushUser(blocks);
         break;
       }
       case 'tool': {
@@ -135,14 +156,15 @@ function toAnthropicBody(messages: ChatRequestBody['messages']): {
           {
             type: 'tool_result',
             tool_use_id: message.tool_call_id ?? '',
-            content: message.content ?? '',
+            content: wireText(message.content),
           },
         ]);
         break;
       }
       case 'assistant': {
         const content: AnthropicBlock[] = [];
-        if (message.content) content.push({ type: 'text', text: message.content });
+        const text = wireText(message.content);
+        if (text) content.push({ type: 'text', text });
         for (const call of message.tool_calls ?? []) {
           content.push({
             type: 'tool_use',
@@ -407,6 +429,8 @@ async function chatHandler(request: Request): Promise<Response> {
   // header is NOT `Authorization`, which is why the schema's detector matches
   // both spellings.
   keyExposure: 'needs-proxy',
+  // A remote HTTPS endpoint and a key. Nothing to install, nothing to start.
+  outOfBand: 'none',
 };
 
 export default anthropic;

package/src/agent-tooling/integrations/cloudflare.ts

@@ -167,6 +167,11 @@ export default {
   // the `env.AI` binding and holds no token in code at all, but a binding is a
   // Worker capability, not a browser one. Either way a server is required.
   keyExposure: 'needs-proxy',
+  // Workers AI is a remote HTTPS endpoint (the REST route) or a platform binding
+  // (the worker route) — either way there is nothing on the developer's machine
+  // to install or run. `wrangler` is a devDependency of a Worker app, not an
+  // out-of-band prerequisite of this integration.
+  outOfBand: 'none',
 };
 
 export default cloudflare;

package/src/agent-tooling/integrations/langgraph.ts

@@ -109,6 +109,19 @@ async function chatHandler(request: Request): Promise<Response> {
   // No key appears in the route: `new ChatOpenAI(...)` reads OPENAI_API_KEY from
   // the environment itself. Same invisible-key shape as vercel-ai-sdk.
   keyExposure: 'needs-proxy',
+  // 'none', and this is the entry most likely to be "corrected" to something
+  // else, so the reason is here rather than assumed. The create-kai spec lists
+  // LangGraph under "Bring a server or runtime". That is WRONG for this route:
+  // the graph is built and compiled IN PROCESS above (`createReactAgent` over a
+  // `new ChatOpenAI(...)`), so there is no LangGraph server, no port and no
+  // second process — the four packages in `deps` are the whole install and
+  // `runNote` asks for a key and nothing else.
+  //
+  // LangGraph Platform / `langgraph dev` IS a server, and an integration that
+  // talked to one over HTTP would be 'local-server'. That is a different route
+  // than the one above, and if it is ever added it must be added as its own
+  // catalog entry rather than by changing this line.
+  outOfBand: 'none',
 };
 
 export default langgraph;

package/src/agent-tooling/integrations/mastra.ts

@@ -35,17 +35,43 @@ async function chatHandler(request: Request): Promise<Response> {
   // is never null. A 'tool' wire message is OUR client-side tool bookkeeping;
   // this agent owns its tools server-side (forwardsFromClient is empty), so it
   // has no schema for that shape and the entry is dropped rather than guessed.
-  type MastraMessage = { role: 'system'; content: string } | { role: 'user'; content: string } | { role: 'assistant'; content: string };
+  //
+  // Only the USER role takes content parts: a system prompt is text by
+  // definition, and an assistant turn here is replayed history, not a new
+  // upload. \`data\` uses the bare base64-or-URL shorthand, which every AI SDK
+  // major Mastra accepts understands.
+  type MastraFilePart = { type: 'file'; data: string | URL; mediaType: string; filename?: string };
+  type MastraUserContent = string | Array<{ type: 'text'; text: string } | MastraFilePart>;
+  type MastraMessage = { role: 'system'; content: string } | { role: 'user'; content: MastraUserContent } | { role: 'assistant'; content: string };
   const mastraMessages: MastraMessage[] = [];
   for (const m of messages) {
-    const content = m.content ?? '';
     // Each branch constructs a literal with ONE fixed role, not m.role (which is
     // still typed as the 4-way union): a union-VALUED field on a single object
     // does not structurally match a union of role-discriminated objects, so
     // widening back to m.role here would reintroduce the original TS2345.
-    if (m.role === 'system') mastraMessages.push({ role: 'system', content });
-    else if (m.role === 'user') mastraMessages.push({ role: 'user', content });
-    else if (m.role === 'assistant') mastraMessages.push({ role: 'assistant', content });
+    if (m.role === 'system') mastraMessages.push({ role: 'system', content: wireText(m.content) });
+    else if (m.role === 'assistant') mastraMessages.push({ role: 'assistant', content: wireText(m.content) });
+    else if (m.role === 'user') {
+      const parts = wireParts(m.content);
+      // Plain string unless the turn actually carries an attachment.
+      if (parts.every((p) => p.kind === 'text')) {
+        mastraMessages.push({ role: 'user', content: wireText(m.content) });
+      } else {
+        mastraMessages.push({
+          role: 'user',
+          content: parts.map((p) =>
+            p.kind === 'text'
+              ? { type: 'text' as const, text: p.text }
+              : {
+                  type: 'file' as const,
+                  mediaType: p.mediaType,
+                  ...(p.filename === undefined ? {} : { filename: p.filename }),
+                  data: p.source.type === 'data' ? p.source.data : new URL(p.source.url),
+                },
+          ),
+        });
+      }
+    }
   }
 
   let agentStream: Awaited<ReturnType<ReturnType<typeof mastra.getAgent>['stream']>>;
@@ -130,6 +156,21 @@ async function chatHandler(request: Request): Promise<Response> {
   // no key leaks. The conservative direction is the cheap one: a needless server
   // hop costs a process, the other error costs the endpoint.
   keyExposure: 'needs-proxy',
+  // THE JUDGEMENT CALL FOR THIS FIELD, exactly as keyExposure above is, and for
+  // a related reason: no automatic check can decide it. MASTRA_URL is a base URL
+  // for a server this integration does not ship and cannot start; the route's
+  // only mention of loopback is inside a `throw new Error(...)` string, which
+  // LOOPBACK_FETCH deliberately does not match (a net that fired on prose would
+  // be right here by accident and wrong elsewhere). So 'none' would parse
+  // cleanly.
+  //
+  // It is 'local-server' on what the integration actually requires: a Mastra
+  // server has to be reachable at MASTRA_URL before the first message works,
+  // `mastra dev` is how a developer gets one (port 4111), and `@mastra/client-js`
+  // is a CLIENT for it, not the server itself. Printing "start your Mastra
+  // server" costs a line; omitting it produces a scaffold that fetches a URL
+  // nothing answers.
+  outOfBand: 'local-server',
 };
 
 export default mastra;

package/src/agent-tooling/integrations/mock.ts

@@ -64,6 +64,10 @@ const mock: Integration = {
   // the one place where "declares nothing" genuinely means safe — which is
   // precisely why it still has to SAY so rather than be left blank.
   keyExposure: 'frontend-safe',
+  // Nothing at all, and here that is the literal truth rather than a shorthand:
+  // there is no route, no upstream and no process. This is the "No backend"
+  // group of create-kai's gateway prompt all by itself.
+  outOfBand: 'none',
 };
 
 export default mock;

package/src/agent-tooling/integrations/ollama.ts

@@ -79,6 +79,13 @@ const ollama: Integration = {
   // the browser-direct path (set OLLAMA_ORIGINS to allow the page origin), which
   // is the path this value unlocks.
   keyExposure: 'frontend-safe',
+  // The route fetches http://localhost:11434, so Ollama must ALREADY be running:
+  // `ollama serve`, then `ollama pull <model>` for the model the route pins.
+  // Nothing in package.json installs or starts it — `deps.npm` is empty because
+  // the route is bare `fetch`, which is exactly why this cannot be inferred from
+  // the dependency list. The schema's LOOPBACK_FETCH net catches this one
+  // independently, so a later edit to 'none' fails at the catalog boundary.
+  outOfBand: 'local-server',
 };
 
 export default ollama;

package/src/agent-tooling/integrations/openai.ts

@@ -82,6 +82,8 @@ const openai: Integration = {
   // The route reads OPENAI_API_KEY and puts it in an `Authorization: Bearer`
   // header. A static bundle carrying that is a published key.
   keyExposure: 'needs-proxy',
+  // A remote HTTPS endpoint and a key. Nothing to install, nothing to start.
+  outOfBand: 'none',
 };
 
 export default openai;

package/src/agent-tooling/integrations/openrouter.ts

@@ -69,6 +69,8 @@ const openrouter: Integration = {
   deps: { npm: [], pip: [] },
   // The route reads OPENROUTER_API_KEY into an `Authorization: Bearer` header.
   keyExposure: 'needs-proxy',
+  // A remote HTTPS endpoint and a key. Nothing to install, nothing to start.
+  outOfBand: 'none',
 };
 
 export default openrouter;

package/src/agent-tooling/integrations/pi.ts

@@ -23,7 +23,25 @@ app.use(express.json());
 // POST /api/chat: bridge a Pi RPC session to the browser as SSE.
 app.post('/api/chat', (req, res) => {
   const { messages } = req.body as { messages: OpenAIWireMessage[] };
-  const prompt = messages.at(-1)?.content ?? '';
+  const last = messages.at(-1)?.content;
+  // \`content\` is a plain string until the turn carries an attachment, at which
+  // point it is an ARRAY of content parts. Pi's RPC mode takes a TEXT prompt and
+  // has no channel for a file, so an attachment is REFUSED here. Passing the
+  // array straight through would JSON.stringify an object graph into the prompt
+  // — no type error, no crash, just a model reading serialised noise.
+  if (Array.isArray(last) && last.some((part) => part.type !== 'text')) {
+    res.status(400).json({
+      error: {
+        message:
+          'This Pi bridge forwards a text prompt only and has no channel for an attachment. Extract the file content into the message text, or send it through a tool.',
+      },
+    });
+    return;
+  }
+  const prompt =
+    typeof last === 'string'
+      ? last
+      : (last ?? []).map((part) => (part.type === 'text' ? part.text : '')).join('');
 
   // Headers before the first frame: without text/event-stream the browser
   // buffers the body and readOpenAIStream never sees a frame.
@@ -91,6 +109,13 @@ app.listen(3001, () => console.log('chat api: http://localhost:3001/api/chat'));
   // is exposed. "No key" is not the same fact as "safe in the browser", and
   // collapsing the two is exactly how this flag would be got wrong.
   keyExposure: 'needs-proxy',
+  // Not 'local-server': nothing is listening in advance. The bridge spawns
+  // `pi --mode rpc` per request, so what the developer supplies is an EXECUTABLE
+  // on PATH ("Pi must be installed locally and available on PATH as 'pi'"), and
+  // "start the server first" would be the wrong instruction to print. Pi is not
+  // in `deps` for the same reason — the route reaches it with spawn(), not an
+  // import. The schema's SPAWNS_PROCESS net catches this one independently.
+  outOfBand: 'local-binary',
 };
 
 export default pi;

package/src/agent-tooling/integrations/pydantic-ai.ts

@@ -10,7 +10,7 @@ const pydanticAi: Integration = {
   routeTemplates: {
     fastapi: `# main.py
 import json
-from fastapi import FastAPI
+from fastapi import FastAPI, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel
@@ -23,15 +23,41 @@ app.add_middleware(
     CORSMiddleware, allow_origins=['*'], allow_methods=['*'], allow_headers=['*']
 )
 
+class ContentPart(BaseModel):
+    type: str
+    text: str | None = None
+
 class Message(BaseModel):
     role: str
-    content: str
+    # A plain string until the turn carries an attachment, at which point the
+    # wire sends an ARRAY of content parts. Declaring this \`str\` alone made a
+    # message with a file a 422 that named pydantic rather than the cause.
+    content: str | list[ContentPart] | None = None
 
 class ChatRequest(BaseModel):
     messages: list[Message]
 
+def prompt_text(message: Message) -> str:
+    """The text of a turn, refusing what this route cannot carry.
+
+    agent.run_stream() takes a TEXT prompt, so an image or a document has no
+    channel here. Dropping it would send the model a turn that silently lost the
+    user's file; a 400 that names the reason is the honest failure.
+    """
+    if message.content is None:
+        return ''
+    if isinstance(message.content, str):
+        return message.content
+    if any(part.type != 'text' for part in message.content):
+        raise HTTPException(
+            status_code=400,
+            detail='This route forwards a text prompt only and has no channel for an attachment. '
+            'Extract the file content into the message text, or send it through a tool.',
+        )
+    return ''.join(part.text or '' for part in message.content)
+
 async def openai_sse(messages: list[Message]):
-    prompt = messages[-1].content if messages else ''
+    prompt = prompt_text(messages[-1]) if messages else ''
     async with agent.run_stream(prompt) as result:
         async for delta in result.stream_text(delta=True):
             chunk = {'choices': [{'delta': {'content': delta}}]}
@@ -69,6 +95,14 @@ async def chat(req: ChatRequest):
   // 'frontend-safe' — the flag asks where the SECRET lives, and it lives in the
   // python process. The FastAPI service IS the server hop.
   keyExposure: 'needs-proxy',
+  // The emitted backend is a FastAPI service: a python interpreter, the four
+  // `deps.pip` packages, and `uvicorn main:app` on its own port — none of which a
+  // node toolchain provides or starts. It also needs OPENAI_API_KEY, so this is
+  // the entry that proves the groups are not mutually exclusive: a runtime
+  // prerequisite and a key at once. The prompt should lead with the runtime,
+  // because a key is useless until the service runs. The schema's `language ===
+  // 'python'` net catches this one independently.
+  outOfBand: 'language-runtime',
 };
 
 export default pydanticAi;