@sdaia-ds/mcp 0.0.0-stage → 3.1.0

package/knowledge/ai/agent-handoff.md

@@ -0,0 +1,65 @@
+# Agent Handoff
+
+## Metadata
+- Component: Agent Handoff
+- Slug: `agent-handoff`
+- Category: AI
+- Install: `npx sdaia-ui@latest add agent-handoff`
+- Import: `import { AgentHandoff } from '@/components/ui/AgentHandoff'`
+- Installed files: `AgentHandoff.tsx`, `AgentHandoff.types.ts`, `AgentHandoff.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/agent-handoff
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add agent-handoff`. It copies the source into your components folder (`components/ui/AgentHandoff/`, under `src/` when the project has one); import it as `@/components/ui/AgentHandoff`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant?` | `'brand' \| 'neutral' \| 'outline'` | 'brand' | Visual style of the handoff container. - `brand`   — brand-tinted surface + brand border (default) - `neutral` — subtle surface + subtle border - `outline` — transparent surface + default border |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the flow (destination on the start side). Inherits from the document when unset. |
+| `source` | `AgentHandoffAgent` | — | The agent delegating the task. |
+| `destination` | `AgentHandoffAgent` | — | The agent receiving the task. |
+| `label?` | `ReactNode` | labels.connector ('Delegating Task') | Connector pill text describing the handoff. Wins over `labels.connector`; pass `null` to hide the pill. |
+| `showLabel?` | `boolean` | true | Show the connector label pill. |
+| `arrowIcon?` | `string` | arrowRight02Stroke | Connector arrow icon — points from source to destination and flips in RTL. |
+| `labels?` | `Partial<AgentHandoffLabels>` | — | Translatable built-in strings (see ). |
+| `as?` | `ElementType` | 'div' | Override the rendered root element. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`.
+
+## Options (allowed values)
+- `variant`: `'brand'` \| `'neutral'` \| `'outline'` — Visual style of the handoff — mirrors the Figma `Style` property.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the flow (destination on the start side).
+Inherits from the document when unset.
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-brand-subtle)`
+- `var(--ds-color-bg-muted)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-subtle)`
+- `var(--ds-color-icon-brand)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-l)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add agent-handoff` (after `npx sdaia-ui@latest init`), then import `{ AgentHandoff }` from `@/components/ui/AgentHandoff`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pass icons via `<DgaIcon data={…} className="size-icon-sm" />` from `@platformscode/icons` only — see `get_foundations` (`icon-usage`). Never emoji, Lucide, or random icons (e.g. `pizza01Stroke` for dark mode).
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/ai/ai-citation.md

@@ -0,0 +1,78 @@
+# AI Citation
+
+## Metadata
+- Component: AI Citation
+- Slug: `ai-citation`
+- Category: AI
+- Install: `npx sdaia-ui@latest add ai-citation`
+- Import: `import { AiCitation } from '@/components/ui/AiCitation'`
+- Installed files: `AiCitation.tsx`, `AiCitation.types.ts`, `AiCitation.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/ai-citation
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add ai-citation`. It copies the source into your components folder (`components/ui/AiCitation/`, under `src/` when the project has one); import it as `@/components/ui/AiCitation`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant?` | `'neutral' \| 'brand' \| 'outline'` | 'neutral' | Visual style — mirrors the Figma `Style` property. |
+| `type?` | `'inline-chip' \| 'sources-panel'` | 'inline-chip' | Structural layout — mirrors the Figma `Type` property. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the layout via logical alignment. |
+| `text?` | `ReactNode` | — | The cited text fragment shown before the chip (e.g. `…reducing dependence on oil`). Omit to render the chip on its own so it can be dropped inline after any run of text. (`inline-chip` only.) |
+| `index?` | `ReactNode` | — | The citation number shown inside the chip. Omit to render the link glyph alone — there is no built-in sample number. (`inline-chip` only.) |
+| `href?` | `string` | — | When set, the chip renders as an anchor to this URL. (`inline-chip` only.) |
+| `target?` | `string` | — | Anchor target — defaults to `_blank` when `href` is set. |
+| `rel?` | `string` | — | Anchor rel — defaults to `noopener noreferrer` for `_blank`. |
+| `onChipClick?` | `MouseEventHandler<HTMLElement>` | — | When set (and no `href`), the chip renders as a button. (`inline-chip` only.) |
+| `chipLabel?` | `string` | `View citation <index>` | Accessible label for an interactive chip. Wins over `labels.chip`. |
+| `label?` | `ReactNode` | 'Sources' (`sources-panel` only.) | Panel header label. Wins over `labels.sources`. |
+| `count?` | `number` | — | Header count badge. Defaults to the number of `sources`. |
+| `hideCount?` | `boolean` | false | Hide the header count badge. |
+| `sources?` | `AiCitationSource[]` | [] | The source rows. (`sources-panel` only.) |
+| `autoNumber?` | `boolean` | true | Auto-number rows by position when a row omits `number`. |
+| `labels?` | `Partial<AiCitationLabels>` | — | Overrides for every built-in visible or accessible string (see ). Unset keys keep the English defaults. |
+| `as?` | `ElementType` | 'span' (inline) / 'div' (panel) | Override the rendered root element. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`, `title`.
+
+## Options (allowed values)
+- `variant`: `'neutral'` \| `'brand'` \| `'outline'` — Figma `Style` property — the visual treatment of the citation.
+- `type`: `'inline-chip'` \| `'sources-panel'` — Figma `Type` property — the two structural layouts.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the layout via logical alignment.
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-)`
+- `var(--ds-color-bg-brand-subtle)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-muted)`
+- `var(--ds-color-icon-brand)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-primitive-radius-radius-)`
+- `var(--ds-color-primitive-radius-radius-12)`
+- `var(--ds-color-primitive-radius-radius-6)`
+- `var(--ds-color-primitive-radius-radius-9999)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add ai-citation` (after `npx sdaia-ui@latest init`), then import `{ AiCitation }` from `@/components/ui/AiCitation`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/ai/ai-code-block.md

@@ -0,0 +1,86 @@
+# AI Code Block
+
+## Metadata
+- Component: AI Code Block
+- Slug: `ai-code-block`
+- Category: AI
+- Install: `npx sdaia-ui@latest add ai-code-block`
+- Import: `import { AiCodeBlock } from '@/components/ui/AiCodeBlock'`
+- Installed files: `AiCodeBlock.tsx`, `AiCodeBlock.types.ts`, `AiCodeBlock.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/ai-code-block
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add ai-code-block`. It copies the source into your components folder (`components/ui/AiCodeBlock/`, under `src/` when the project has one); import it as `@/components/ui/AiCodeBlock`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant?` | `'neutral' \| 'brand' \| 'outline'` | 'neutral' | Visual style. |
+| `fileName?` | `ReactNode` | — | Filename / label shown in the header (e.g. `response.ts`). |
+| `code?` | `string` | — | Raw code string. Rendered line-by-line as plain on-color text when no are supplied, and used as the copy-to-clipboard payload. |
+| `lines?` | `ReactNode[]` | — | Pre-highlighted code, one entry per line. Strings render as plain on-color text; pass JSX (token-coloured spans) for syntax highlighting. Overrides the plain rendering of . When `lines` contain JSX, also pass so the copy action yields the correct plain text. |
+| `showCopy?` | `boolean` | true | Show the header copy button. |
+| `copyLabel?` | `string` | 'Copy code' | Accessible label for the copy button (idle state). Same as `labels.copy`. |
+| `copiedLabel?` | `string` | 'Copied' | Accessible label announced after a successful copy. Same as `labels.copied`. |
+| `onCopy?` | `(code: string) => void \| Promise<void>` | — | Called when the copy button is pressed, with the resolved copy text. When provided it replaces the default `navigator.clipboard.writeText` behaviour. |
+| `collapsible?` | `boolean` | false | Enable the collapsible behaviour. When collapsed, only the first lines are shown above a "Show N more lines" footer that expands the block. |
+| `collapsed?` | `boolean` | — | Controlled collapsed state. |
+| `defaultCollapsed?` | `boolean` | false | Initial collapsed state when uncontrolled. |
+| `onCollapsedChange?` | `(collapsed: boolean) => void` | — | Called when the collapsed state changes (expansion). |
+| `collapsedVisibleLines?` | `number` | 2 | Number of lines kept visible while collapsed. |
+| `hiddenLineCount?` | `number` | — | Override the hidden-line count shown in the footer label. Defaults to `totalLines - collapsedVisibleLines`. |
+| `showMoreLabel?` | `ReactNode \| ((hiddenLineCount: number) => ReactNode)` | (n) => `Show ${n} more line(s)` | Footer label. Either a node, or a builder receiving the hidden-line count. Same as `labels.showMore`. |
+| `labels?` | `Partial<AiCodeBlockLabels>` | — | Localised copy for the copy action, its confirmation and the footer. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the chrome; the code stays LTR. |
+| `as?` | `ElementType` | 'div' | Render the root as a different element. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `style`, `title`, `children`, `onCopy`.
+
+## Options (allowed values)
+- `variant`: `'neutral'` \| `'brand'` \| `'outline'` — Visual style — mirrors the Figma `Style` property.
+- `neutral` — subtle-filled header + default (grey) border (default)
+- `brand`   — subtle-filled header + brand (green) border
+- `outline` — transparent header + default (grey) border
+
+The dark code surface is identical across all three styles; only the chrome
+(border + header fill) changes.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the chrome; the code stays LTR.
+
+## Deprecated props
+Do not use in new code:
+- `rtl` — Deprecated boolean form of . Prefer `dir`.
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-brand-neutral-800)`
+- `var(--ds-color-)`
+- `var(--ds-color-bg-brand)`
+- `var(--ds-color-bg-brand-muted)`
+- `var(--ds-color-bg-muted)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-chart-gold)`
+- `var(--ds-color-chart-green)`
+- `var(--ds-color-primitive-public-lavender-300)`
+- `var(--ds-color-primitive-radius-radius-12)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-color-text-on-color-subtle)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-radius-xs)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xxs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add ai-code-block` (after `npx sdaia-ui@latest init`), then import `{ AiCodeBlock }` from `@/components/ui/AiCodeBlock`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/ai/ai-disclaimer.md

@@ -0,0 +1,84 @@
+# AI Disclaimer
+
+## Metadata
+- Component: AI Disclaimer
+- Slug: `ai-disclaimer`
+- Category: AI
+- Install: `npx sdaia-ui@latest add ai-disclaimer`
+- Import: `import { AiDisclaimer } from '@/components/ui/AiDisclaimer'`
+- Installed files: `AiDisclaimer.tsx`, `AiDisclaimer.types.ts`, `AiDisclaimer.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/ai-disclaimer
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add ai-disclaimer`. It copies the source into your components folder (`components/ui/AiDisclaimer/`, under `src/` when the project has one); import it as `@/components/ui/AiDisclaimer`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant?` | `'neutral' \| 'brand' \| 'outline'` | 'neutral' | Visual style. |
+| `type?` | `'footer' \| 'banner' \| 'model-chip'` | 'banner' | Structural type. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the layout. |
+| `icon?` | `string` | — | Leading glyph (a `DgaIcon` data URL from `@platformscode/icons`). Defaults to `alert02Stroke` for the `footer` type and `sparklesStroke` for the `banner` / `model-chip` types. |
+| `text?` | `ReactNode` | 'AI can make mistakes. Verify important information.' | Disclaimer line shown in the `footer` type. Same as `labels.text`. |
+| `title?` | `ReactNode` | 'You’re chatting with an AI assistant' | Banner heading (`banner` type). Same as `labels.title`. |
+| `description?` | `ReactNode` | 'Responses may be inaccurate. Please don’t share sensitive personal information.' | Banner supporting copy (`banner` type). Same as `labels.description`. |
+| `modelName?` | `ReactNode` | — | Assistant name shown in the `model-chip` type. No default — nothing is rendered when omitted. |
+| `modelVersion?` | `ReactNode` | — | Model / version shown after the separator dot in the `model-chip` type. No default — the dot and version are omitted when unset. |
+| `labels?` | `Partial<AiDisclaimerLabels>` | — | Localised built-in copy for the `footer` and `banner` types. |
+| `as?` | `ElementType` | 'div' | Render the root as a different element. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `style`.
+
+## Options (allowed values)
+- `variant`: `'neutral'` \| `'brand'` \| `'outline'` — Visual style — mirrors the Figma `Style` property.
+- `neutral` — quiet surfaces (banner tinted, chip subtle bg + default border) (default)
+- `brand`   — brand-tinted surfaces (banner tinted, chip brand bg + brand border)
+- `outline` — minimal surfaces (banner transparent, chip transparent + default border)
+
+The `footer` type is identical across all three styles (it has no surface).
+- `type`: `'footer'` \| `'banner'` \| `'model-chip'` — Structural type — mirrors the Figma `Type` property.
+- `footer`     — a quiet, centered single-line note (e.g. "AI can make mistakes…")
+- `banner`     — a card with a brand AI avatar, a title and a description
+- `model-chip` — a compact pill naming the assistant + model/version
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the layout.
+
+## Deprecated props
+Do not use in new code:
+- `style` — Visual style (collides with React's `style` attribute).
+- `rtl` — Deprecated boolean form of . Prefer `dir`.
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-)`
+- `var(--ds-color-bg-brand)`
+- `var(--ds-color-bg-brand-subtle)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-icon-brand)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-icon-oncolor)`
+- `var(--ds-color-primitive-radius-radius-12)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-full)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+- `var(--ds-text-leading-line-heights-text-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add ai-disclaimer` (after `npx sdaia-ui@latest init`), then import `{ AiDisclaimer }` from `@/components/ui/AiDisclaimer`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pass icons via `<DgaIcon data={…} className="size-icon-sm" />` from `@platformscode/icons` only — see `get_foundations` (`icon-usage`). Never emoji, Lucide, or random icons (e.g. `pizza01Stroke` for dark mode).
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/ai/ai-message-bubble.md

@@ -0,0 +1,81 @@
+# AI Message Bubble
+
+## Metadata
+- Component: AI Message Bubble
+- Slug: `ai-message-bubble`
+- Category: AI
+- Install: `npx sdaia-ui@latest add ai-message-bubble`
+- Import: `import { AiMessageBubble } from '@/components/ui/AiMessageBubble'`
+- Installed files: `AiMessageBubble.tsx`, `AiMessageBubble.types.ts`, `AiMessageBubble.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/ai-message-bubble
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add ai-message-bubble`. It copies the source into your components folder (`components/ui/AiMessageBubble/`, under `src/` when the project has one); import it as `@/components/ui/AiMessageBubble`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type?` | `'user' \| 'ai'` | 'ai' (or derived from a legacy `state`) | Who is speaking. |
+| `state?` | `'default' \| 'streaming' \| 'error' \| 'user' \| 'ai'` | 'default' | Bubble condition — `default`, `streaming` (live caret) or `error` (danger bubble + Retry). Legacy values `'user'` / `'ai'` are accepted and mean `type="user" \| "ai"` with `state="default"`. |
+| `variant?` | `'neutral' \| 'brand' \| 'outline'` | 'neutral' | Assistant bubble surface — Figma `Style`. Ignored for `user`/`error`. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. |
+| `children?` | `ReactNode` | — | Message content. For `error`, defaults to `labels.errorMessage`. |
+| `maxWidth?` | `number \| string` | 520px | Max bubble width (CSS length or px number). The bubble is fluid below it. |
+| `avatar?` | `ReactNode` | — | Override the avatar node entirely. |
+| `avatarIcon?` | `string` | sparklesStroke | Avatar glyph (`@platformscode/icons` data URL). |
+| `showAvatar?` | `boolean` | true | Show the assistant avatar. |
+| `retryLabel?` | `ReactNode` | 'Retry' | Retry button label. Same as `labels.retry`. |
+| `onRetry?` | `MouseEventHandler<HTMLButtonElement>` | — | Fired when the Retry button is pressed. |
+| `showRetry?` | `boolean` | true | Show the Retry action. |
+| `retryIcon?` | `string` | refreshStroke | Retry glyph (`@platformscode/icons` data URL). |
+| `labels?` | `Partial<AiMessageBubbleLabels>` | — | Localised copy for the error message, Retry and the streaming announcement. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `type`: `'user'` \| `'ai'` — Who is speaking — Figma `State` User / AI.
+- `state`: `'default'` \| `'streaming'` \| `'error'` \| `'user'` \| `'ai'` — Bubble condition. `'default'` / `'streaming'` / `'error'` are the states.
+
+`'user'` and `'ai'` are still accepted for backwards compatibility (they were
+the original single `state` axis) and map to `type` + `state="default"`.
+Prefer `type="user" | "ai"` for those.
+- `variant`: `'neutral'` \| `'brand'` \| `'outline'` — Figma `Style` — the assistant bubble surface treatment.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-)`
+- `var(--ds-color-bg-brand)`
+- `var(--ds-color-bg-brand-subtle)`
+- `var(--ds-color-bg-danger-subtle)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-danger-subtle)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-icon-oncolor)`
+- `var(--ds-color-text-danger)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-text-leading-line-heights-text-md)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add ai-message-bubble` (after `npx sdaia-ui@latest init`), then import `{ AiMessageBubble }` from `@/components/ui/AiMessageBubble`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pass icons via `<DgaIcon data={…} className="size-icon-sm" />` from `@platformscode/icons` only — see `get_foundations` (`icon-usage`). Never emoji, Lucide, or random icons (e.g. `pizza01Stroke` for dark mode).
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/ai/ai-message.md

@@ -0,0 +1,118 @@
+# AI Message
+
+## Metadata
+- Component: AI Message
+- Slug: `ai-message`
+- Category: AI
+- Install: `npx sdaia-ui@latest add ai-message`
+- Import: `import { AiMessage } from '@/components/ui/AiMessage'`
+- Installed files: `AiMessage.tsx`, `AiMessage.types.ts`, `AiMessage.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/ai-message
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add ai-message`. It copies the source into your components folder (`components/ui/AiMessage/`, under `src/` when the project has one); import it as `@/components/ui/AiMessage`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type?` | `'standard' \| 'reasoning' \| 'research' \| 'code' \| 'image-generation' \| 'multi-tool'` | 'standard' | Body composition (block order). |
+| `variant?` | `'neutral' \| 'brand' \| 'outline'` | 'neutral' | Card surface treatment. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. |
+| `name?` | `ReactNode` | — | Assistant name. No default — renders only when set. |
+| `avatar?` | `ReactNode` | — | Override the avatar node entirely. |
+| `avatarIcon?` | `string` | sparklesStroke | Avatar glyph (`@platformscode/icons` data URL). |
+| `model?` | `ReactNode` | — | Model pill label. No default — renders only when set. |
+| `showModel?` | `boolean` | true | — |
+| `modelIcon?` | `string` | sparklesStroke | Model pill glyph. |
+| `status?` | `AiStatus` | — | AI status shown in the header pill. No default — the pill renders only when set. |
+| `statusLabel?` | `ReactNode` | — | Override the status label. |
+| `statusAppearance?` | `AiStatusAppearance` | 'neutral' | Status pill appearance. |
+| `showStatus?` | `boolean` | true | — |
+| `timestamp?` | `ReactNode` | — | Trailing timestamp. No default — renders only when set. |
+| `showTimestamp?` | `boolean` | true | — |
+| `chips?` | `AiMessageChip[]` | — | Header metadata chips (e.g. Research / Multi-tool). |
+| `showDivider?` | `boolean` | true | Show the divider under the header. |
+| `title?` | `ReactNode` | — | — |
+| `body?` | `ReactNode` | — | — |
+| `bullets?` | `ReactNode[]` | — | Bulleted list items (brand-coloured bullets). |
+| `link?` | `AiMessageLink \| ReactNode` | — | Inline call-to-action link. |
+| `citationsLabel?` | `ReactNode` | labels.citations ('Cited sources') | Label preceding the cited-source chips. |
+| `citations?` | `ReactNode[]` | — | Bare numbered citation chips, e.g. `[1, 2, 3, 4]`. |
+| `sources?` | `AiMessageSource[]` | — | Cited-source cards. |
+| `viewAll?` | `AiMessageAction` | — | "View all N sources" action. |
+| `reasoning?` | `AiMessageReasoning` | — | — |
+| `createdFileChip?` | `AiMessageChip` | — | The "Created file: …" brand chip above the artifact. |
+| `artifact?` | `Partial<ArtifactViewerProps>` | — | Props forwarded to the composed DS `ArtifactViewer` (Code / Multi-tool). The artifact renders only when this is set with a `title`. |
+| `codeActions?` | `AiMessageAction[]` | — | Secondary chip-button row under the code artifact (Copy / Apply / Run again / Explain). |
+| `toolResults?` | `AiMessageToolResult[]` | — | Tool-result rows — the Code-execution result and the Multi-tool timeline. |
+| `image?` | `AiMessageImage` | — | — |
+| `actions?` | `AiMessageAction[]` | — | Footer action bar. Defaults to Copy / Regenerate / Share / Save / Like / More (copy from `labels`). |
+| `showActions?` | `boolean` | true | — |
+| `labels?` | `Partial<AiMessageLabels>` | — | Localised copy for actions, feedback, toggles and status badges. |
+| `children?` | `ReactNode` | — | Custom body — replaces the `type`-driven body entirely (header + footer stay). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `style`.
+
+## Options (allowed values)
+- `type`: `'standard'` \| `'reasoning'` \| `'research'` \| `'code'` \| `'image-generation'` \| `'multi-tool'` — Figma `Type` — selects the body composition.
+- `variant`: `'neutral'` \| `'brand'` \| `'outline'` — Figma `Style` — the root card surface treatment.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction.
+
+## Deprecated props
+Do not use in new code:
+- `style` — Card surface treatment (collides with React's `style` attribute).
+- `rtl`
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-)`
+- `var(--ds-color-bg-brand-subtle)`
+- `var(--ds-color-bg-danger-subtle)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-info-subtle)`
+- `var(--ds-color-bg-muted)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-bg-success-subtle)`
+- `var(--ds-color-bg-warning-subtle)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-subtle)`
+- `var(--ds-color-icon-brand)`
+- `var(--ds-color-icon-danger)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-icon-default-400)`
+- `var(--ds-color-icon-info)`
+- `var(--ds-color-icon-success)`
+- `var(--ds-color-icon-warning)`
+- `var(--ds-color-primitive-radius-radius-10)`
+- `var(--ds-color-primitive-radius-radius-12)`
+- `var(--ds-color-primitive-radius-radius-16)`
+- `var(--ds-color-primitive-radius-radius-8)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-info)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-color-text-success)`
+- `var(--ds-radius-full)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+- `var(--ds-text-leading-line-heights-text-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add ai-message` (after `npx sdaia-ui@latest init`), then import `{ AiMessage }` from `@/components/ui/AiMessage`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pass icons via `<DgaIcon data={…} className="size-icon-sm" />` from `@platformscode/icons` only — see `get_foundations` (`icon-usage`). Never emoji, Lucide, or random icons (e.g. `pizza01Stroke` for dark mode).
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/ai/ai-prompt-input.md

@@ -0,0 +1,93 @@
+# AI Prompt Input
+
+## Metadata
+- Component: AI Prompt Input
+- Slug: `ai-prompt-input`
+- Category: AI
+- Install: `npx sdaia-ui@latest add ai-prompt-input`
+- Import: `import { AiPromptInput } from '@/components/ui/AiPromptInput'`
+- Installed files: `AiPromptInput.tsx`, `AiPromptInput.types.ts`, `AiPromptInput.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/ai-prompt-input
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add ai-prompt-input`. It copies the source into your components folder (`components/ui/AiPromptInput/`, under `src/` when the project has one); import it as `@/components/ui/AiPromptInput`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant?` | `'neutral' \| 'brand' \| 'outline'` | 'neutral' | Field surface treatment — Figma `Style`. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. Omit to inherit from the closest `dir` ancestor. |
+| `labels?` | `Partial<AiPromptInputLabels>` | — | Override any built-in string (placeholder, aria-labels, counter, error). |
+| `limit?` | `number` | 1000 | Character-counter denominator and error threshold. This is **not** a hard input cap (the native `maxLength` is intentionally omitted) so the field can exceed the limit and surface the error state. |
+| `showCounter?` | `boolean` | — | Show the "{count} / {limit}" counter. Defaults to auto — visible while the field is focused or holds any value (mirrors the Figma Default vs Focused frames). Pass `true`/`false` to force it. |
+| `error?` | `boolean` | — | Force the error state. Otherwise derived from `value.length > limit`. |
+| `errorMessage?` | `ReactNode` | `labels.limitExceeded(limit)` | Error helper text under the field. |
+| `streaming?` | `boolean` | false | Streaming — replaces the send button with a stop button. |
+| `disabled?` | `boolean` | false | Disable the whole field (textarea + every action). |
+| `showAttach?` | `boolean` | true | Show the attachment button. |
+| `showRecord?` | `boolean` | true | Show the voice / record button. |
+| `onAttach?` | `MouseEventHandler<HTMLButtonElement>` | — | — |
+| `onRecord?` | `MouseEventHandler<HTMLButtonElement>` | — | — |
+| `attachIcon?` | `string` | attachmentSquareStroke | Attachment glyph (`@platformscode/icons` data URL). |
+| `recordIcon?` | `string` | recordStroke | Voice glyph (`@platformscode/icons` data URL). |
+| `attachLabel?` | `string` | — | Localised aria-label for the attachment button. Prefer `labels.attach`. |
+| `recordLabel?` | `string` | — | Localised aria-label for the voice button. Prefer `labels.record`. |
+| `onSend?` | `(value: string) => void` | — | Fired when send is pressed (or Enter when `submitOnEnter`). Receives the current value. |
+| `onStop?` | `MouseEventHandler<HTMLButtonElement>` | — | Fired when the stop button is pressed during streaming. |
+| `sendDisabled?` | `boolean` | false | Disable only the send button. |
+| `sendIcon?` | `string` | navigation03Stroke | Send glyph (`@platformscode/icons` data URL). |
+| `stopIcon?` | `string` | recordStroke | Stop glyph during streaming (`@platformscode/icons` data URL). |
+| `sendLabel?` | `string` | — | Localised aria-label for the send button. Prefer `labels.send`. |
+| `stopLabel?` | `string` | — | Localised aria-label for the stop button. Prefer `labels.stop`. |
+| `submitOnEnter?` | `boolean` | false | Submit on Enter (Shift+Enter inserts a newline). |
+| `className?` | `string` | — | Class applied to the root wrapper. |
+
+Also accepts standard `<textarea>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `style`, `maxLength`, `children`.
+
+## Options (allowed values)
+- `variant`: `'neutral'` \| `'brand'` \| `'outline'` — Figma `Style` — the field surface treatment.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. Omit to inherit from the closest `dir` ancestor.
+
+## Deprecated props
+Do not use in new code:
+- `style`
+- `rtl`
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-)`
+- `var(--ds-color-bg-brand-subtle)`
+- `var(--ds-color-bg-danger-strong)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-control-border)`
+- `var(--ds-color-form-field-bg-default)`
+- `var(--ds-color-form-field-border-danger)`
+- `var(--ds-color-form-field-border-default)`
+- `var(--ds-color-form-field-text-filled)`
+- `var(--ds-color-form-field-text-helper)`
+- `var(--ds-color-form-field-text-placeholder)`
+- `var(--ds-color-primitive-radius-radius-16)`
+- `var(--ds-color-text-danger)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-text-leading-line-heights-text-md)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add ai-prompt-input` (after `npx sdaia-ui@latest init`), then import `{ AiPromptInput }` from `@/components/ui/AiPromptInput`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pass icons via `<DgaIcon data={…} className="size-icon-sm" />` from `@platformscode/icons` only — see `get_foundations` (`icon-usage`). Never emoji, Lucide, or random icons (e.g. `pizza01Stroke` for dark mode).
+- Express the disabled state with the `disabled` prop, not custom styling.
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.