@sdaia-ds/mcp 0.0.0-stage → 3.1.0

package/knowledge/ai/thinking-panel.md

@@ -0,0 +1,77 @@
+# Thinking Panel
+
+## Metadata
+- Component: Thinking Panel
+- Slug: `thinking-panel`
+- Category: AI
+- Install: `npx sdaia-ui@latest add thinking-panel`
+- Import: `import { ThinkingPanel } from '@/components/ui/ThinkingPanel'`
+- Installed files: `ThinkingPanel.tsx`, `ThinkingPanel.types.ts`, `ThinkingPanel.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/thinking-panel
+
+> **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 thinking-panel`. It copies the source into your components folder (`components/ui/ThinkingPanel/`, under `src/` when the project has one); import it as `@/components/ui/ThinkingPanel`. 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. - `brand`   — raised surface, brand-green accent (default) - `neutral` — subtle surface, neutral accent - `outline` — transparent surface, default accent |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the layout. Inherits from the document when unset. |
+| `animated?` | `boolean` | true | Animate the live trace — bouncing thinking dots (collapsed), a pulsing pipeline badge + spinning header icon (expanded) and a staggered rise-in of the timeline items. Collapses under `prefers-reduced-motion`. |
+| `state?` | `'hidden' \| 'collapsed' \| 'expanded'` | — | Controlled panel state. |
+| `defaultState?` | `'hidden' \| 'collapsed' \| 'expanded'` | 'collapsed' | Initial state when uncontrolled. |
+| `onStateChange?` | `(state: ThinkingPanelState) => void` | — | Called when the user toggles between collapsed and expanded. |
+| `runningLabel?` | `ReactNode` | — | Running label shown next to the thinking dots, inside a polite live region (wins over `labels.running`, default 'Thinking…'). |
+| `count?` | `ReactNode` | — | Activity count badge text (e.g. `4 activities executed`). |
+| `showCount?` | `boolean` | true | Show the activity count badge. |
+| `expandLabel?` | `ReactNode` | — | Expand button label (wins over `labels.expand`, default 'Expand'). |
+| `title?` | `ReactNode` | — | Expanded header title (wins over `labels.title`, default 'Reasoning trace'). |
+| `headerIcon?` | `string` | recordStroke | Header icon — a `@platformscode/icons` data URL. |
+| `pipelineLabel?` | `ReactNode` | — | Active-pipeline badge text (e.g. `Active Pipeline`). The badge is not rendered when unset. |
+| `showPipeline?` | `boolean` | true | Show the active-pipeline badge (when `pipelineLabel` is set). |
+| `items?` | `TraceItemProps[]` | — | Timeline entries — rendered as rail-less Trace Items along the panel rail. The timeline is a polite live region, so entries streamed in later are announced. |
+| `children?` | `ReactNode` | — | Custom timeline content — overrides `items` when provided. |
+| `hiddenLabel?` | `ReactNode` | — | Placeholder text for the hidden state (wins over `labels.hidden`, default 'No active trace'). |
+| `labels?` | `Partial<ThinkingPanelLabels>` | — | Translatable built-in strings (see ). |
+| `as?` | `ElementType` | 'div' | Override the rendered root element. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`.
+
+## Options (allowed values)
+- `variant`: `'brand'` \| `'neutral'` \| `'outline'` — Visual style of the panel — mirrors the Figma `Style` property.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the layout. Inherits from the document when unset.
+- `state`: `'hidden'` \| `'collapsed'` \| `'expanded'` — Panel state — mirrors the Figma `State` property.
+- `defaultState`: `'hidden'` \| `'collapsed'` \| `'expanded'` — Panel state — mirrors the Figma `State` property.
+
+## 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-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-default)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-l)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add thinking-panel` (after `npx sdaia-ui@latest init`), then import `{ ThinkingPanel }` from `@/components/ui/ThinkingPanel`.
+- 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/tool-activity-feed.md

@@ -0,0 +1,67 @@
+# Tool Activity Feed
+
+## Metadata
+- Component: Tool Activity Feed
+- Slug: `tool-activity-feed`
+- Category: AI
+- Install: `npx sdaia-ui@latest add tool-activity-feed`
+- Import: `import { ToolActivityFeed } from '@/components/ui/ToolActivityFeed'`
+- Installed files: `ToolActivityFeed.tsx`, `ToolActivityFeed.types.ts`, `ToolActivityFeed.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/tool-activity-feed
+
+> **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 tool-activity-feed`. It copies the source into your components folder (`components/ui/ToolActivityFeed/`, under `src/` when the project has one); import it as `@/components/ui/ToolActivityFeed`. 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 feed card. - `brand`   — raised surface, default border (default) - `neutral` — subtle surface, subtle border - `outline` — transparent surface, default border |
+| `state?` | `'live' \| 'completed'` | 'live' | Feed lifecycle state. - `live`      — pulsing status dot + warning count, live rows - `completed` — success tick + neutral count, compact result rows Applies to every row unless a row sets its own `state`. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the header and rows. Inherits from the document when unset. |
+| `title` | `ReactNode` | — | Header title (e.g. `Agent Processing Feed` / `Pipeline History Logs`). |
+| `count?` | `ReactNode` | — | Header count/summary badge (e.g. `3 Jobs Active` / `All tasks complete`). |
+| `showCount?` | `boolean` | true | Show the header count badge. |
+| `headerIcon?` | `ReactNode` | — | Override the header leading icon. Defaults to a pulsing dot (`live`) or a success tick (`completed`). |
+| `items` | `ToolActivityFeedItem[]` | — | Feed rows, rendered as composed `FeedItem`s. |
+| `showMetrics?` | `boolean` | true | Show each row's metric badge (completed rows). |
+| `labels?` | `Partial<ToolActivityFeedLabels>` | — | Translatable built-in strings (see ). |
+| `as?` | `ElementType` | 'div' | Override the rendered root element. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`.
+
+## Options (allowed values)
+- `variant`: `'brand'` \| `'neutral'` \| `'outline'` — Visual style of the feed card — mirrors the Figma `Style` property.
+- `state`: `'live'` \| `'completed'` — Lifecycle state of the feed (drives the header + default row state).
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the header and rows. 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-default)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-bg-warning-subtle)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-default-strong)`
+- `var(--ds-color-border-subtle)`
+- `var(--ds-color-border-warning-strong)`
+- `var(--ds-color-icon-success)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-warning)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-l)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add tool-activity-feed` (after `npx sdaia-ui@latest init`), then import `{ ToolActivityFeed }` from `@/components/ui/ToolActivityFeed`.
+- 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/tool-call-card.md

@@ -0,0 +1,66 @@
+# Tool Call
+
+## Metadata
+- Component: Tool Call
+- Slug: `tool-call-card`
+- Category: AI
+- Install: `npx sdaia-ui@latest add tool-call-card`
+- Import: `import { ToolCallCard } from '@/components/ui/ToolCallCard'`
+- Installed files: `ToolCallCard.tsx`, `ToolCallCard.types.ts`, `ToolCallCard.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/tool-call-card
+
+> **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 tool-call-card`. It copies the source into your components folder (`components/ui/ToolCallCard/`, under `src/` when the project has one); import it as `@/components/ui/ToolCallCard`. 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'` | 'neutral' | Visual style of the card. - `brand`   — brand-tinted surface + brand border - `neutral` — subtle surface + subtle border (default) - `outline` — transparent surface + default border |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the header and panels. Inherits from the document when unset. |
+| `name` | `ReactNode` | — | Tool name, e.g. `search_web`. |
+| `subtitle?` | `ReactNode` | — | Subtitle under the name, e.g. `Search tools server · MCP`. |
+| `icon?` | `string` | wrench02Stroke | Tool icon — a `@platformscode/icons` data URL rendered through `DgaIcon`. |
+| `showIcon?` | `boolean` | true | Show the leading tool-icon tile. |
+| `headerEnd?` | `ReactNode` | — | Optional trailing header content (e.g. a status badge or control). |
+| `animated?` | `boolean` | true | Fade the response panel in when it appears (streamed tool output). Collapses under `prefers-reduced-motion`. |
+| `request?` | `ToolCallPanel` | — | The request panel (labelled `Arguments` by default). |
+| `response?` | `ToolCallPanel` | — | The response panel (labelled `Response` by default). |
+| `labels?` | `Partial<ToolCallCardLabels>` | — | Translatable built-in strings (see ). |
+| `as?` | `ElementType` | 'div' | Override the rendered root element. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`.
+
+## Options (allowed values)
+- `variant`: `'brand'` \| `'neutral'` \| `'outline'` — Visual style of the card — mirrors the Figma `Style` property.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the header and panels. 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-info-subtle)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-subtle)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-primitive-radius-radius-12)`
+- `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 tool-call-card` (after `npx sdaia-ui@latest init`), then import `{ ToolCallCard }` from `@/components/ui/ToolCallCard`.
+- 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/tool-status-row.md

@@ -0,0 +1,72 @@
+# Tool Status Row
+
+## Metadata
+- Component: Tool Status Row
+- Slug: `tool-status-row`
+- Category: AI
+- Install: `npx sdaia-ui@latest add tool-status-row`
+- Import: `import { ToolStatusRow } from '@/components/ui/ToolStatusRow'`
+- Installed files: `ToolStatusRow.tsx`, `ToolStatusRow.types.ts`, `ToolStatusRow.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/tool-status-row
+
+> **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 tool-status-row`. It copies the source into your components folder (`components/ui/ToolStatusRow/`, under `src/` when the project has one); import it as `@/components/ui/ToolStatusRow`. 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'` | 'neutral' | Visual style of the card and the status pill. - `brand`   — brand-tinted surface + brand-style pill - `neutral` — raised surface + neutral pill (default) - `outline` — transparent surface + outline pill |
+| `state?` | `'queued' \| 'running' \| 'success' \| 'failed'` | 'queued' | Lifecycle state. - `queued`  — clock icon, "Thinking…" pill, muted progress - `running` — refresh icon, "Running tool" pill, info-blue progress - `success` — tick icon, "Tool complete" pill, full success-green progress - `failed`  — alert icon, "Tool failed" pill, danger-red progress |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the row and progress fill. Inherits from the document when unset. |
+| `name` | `ReactNode` | — | Tool name, e.g. `search_web`. |
+| `subtitle?` | `ReactNode` | — | Subtitle under the name, e.g. `Search server · attempt 1 of 3`. |
+| `icon?` | `string` | — | Override the leading icon — a `@platformscode/icons` data URL rendered through `DgaIcon`. Defaults to the icon for the given . |
+| `showIcon?` | `boolean` | true | Show the leading icon tile. |
+| `animated?` | `boolean` | true | Animate the live states — the leading icon spins while `running` and the status pill animates its live statuses (see ). Collapses under `prefers-reduced-motion`. |
+| `statusLabel?` | `ReactNode` | — | Override the status pill label (wins over `labels[state]`). |
+| `showStatus?` | `boolean` | true | Show the trailing status pill. |
+| `progress?` | `number` | — | Progress value (0–100). When unset: `queued` shows 0, `success` 100, and `running` / `failed` show an indeterminate bar (no `aria-valuenow`). |
+| `showProgress?` | `boolean` | true | Show the progress bar. |
+| `labels?` | `Partial<ToolStatusRowLabels>` | — | Translatable built-in strings (see ). |
+| `as?` | `ElementType` | 'div' | Override the rendered root element. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`.
+
+## Options (allowed values)
+- `variant`: `'brand'` \| `'neutral'` \| `'outline'` — Visual style of the card — mirrors the Figma `Style` property.
+- `state`: `'queued'` \| `'running'` \| `'success'` \| `'failed'` — Lifecycle state of the tool — drives the leading icon, the status pill
+(composed ) and the progress bar colour/value.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the row and progress fill. 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-icon-default)`
+- `var(--ds-color-primitive-radius-radius-12)`
+- `var(--ds-color-text-danger)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-info)`
+- `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-xs)`
+- `var(--ds-spacing-xxs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add tool-status-row` (after `npx sdaia-ui@latest init`), then import `{ ToolStatusRow }` from `@/components/ui/ToolStatusRow`.
+- 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/tool-timeline-item.md

@@ -0,0 +1,71 @@
+# Tool Timeline Item
+
+## Metadata
+- Component: Tool Timeline Item
+- Slug: `tool-timeline-item`
+- Category: AI
+- Install: `npx sdaia-ui@latest add tool-timeline-item`
+- Import: `import { ToolTimelineItem } from '@/components/ui/ToolTimelineItem'`
+- Installed files: `ToolTimelineItem.tsx`, `ToolTimelineItem.types.ts`, `ToolTimelineItem.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/tool-timeline-item
+
+> **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 tool-timeline-item`. It copies the source into your components folder (`components/ui/ToolTimelineItem/`, under `src/` when the project has one); import it as `@/components/ui/ToolTimelineItem`. 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'` | 'neutral' | Visual style of the card. - `brand`   — brand-tinted surface + brand border - `neutral` — raised surface + default border (default) - `outline` — transparent surface + default border |
+| `state?` | `'started' \| 'running' \| 'completed'` | 'started' | Lifecycle milestone. - `started`   — neutral clock icon, muted title, subtle line - `running`   — outlined refresh icon, info-blue title, info-blue line - `completed` — solid green tick, success-green title, success-green line |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the rail and content. Inherits from the document when unset. |
+| `title` | `ReactNode` | — | Milestone title, e.g. `Request accepted`. |
+| `description?` | `ReactNode` | — | Supporting description under the title. |
+| `timestamp?` | `ReactNode` | — | Trailing timestamp, e.g. `14:02:11`. |
+| `icon?` | `string` | — | Override the status icon — a `@platformscode/icons` data URL rendered through `DgaIcon`. Defaults to the icon for the given . |
+| `showConnector?` | `boolean` | true | Show the trailing connector line below the status icon. |
+| `labels?` | `Partial<ToolTimelineItemLabels>` | — | Translatable built-in strings (see ). |
+| `as?` | `ElementType` | 'div' | Override the rendered root element. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`.
+
+## Options (allowed values)
+- `variant`: `'brand'` \| `'neutral'` \| `'outline'` — Visual style of the card — mirrors the Figma `Style` property.
+- `state`: `'started'` \| `'running'` \| `'completed'` — Lifecycle milestone of the timeline item — drives the status icon, the title
+colour, and the connector-line colour.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the rail and content. 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-raised)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-info-subtle)`
+- `var(--ds-color-border-subtle)`
+- `var(--ds-color-border-success-subtle)`
+- `var(--ds-color-button-bg-primary-default)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-icon-oncolor)`
+- `var(--ds-color-primitive-radius-radius-12)`
+- `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-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add tool-timeline-item` (after `npx sdaia-ui@latest init`), then import `{ ToolTimelineItem }` from `@/components/ui/ToolTimelineItem`.
+- 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/voice-session.md

@@ -0,0 +1,93 @@
+# Voice Session
+
+## Metadata
+- Component: Voice Session
+- Slug: `voice-session`
+- Category: AI
+- Install: `npx sdaia-ui@latest add voice-session`
+- Import: `import { VoiceSession } from '@/components/ui/VoiceSession'`
+- Installed files: `VoiceSession.tsx`, `VoiceSession.types.ts`, `VoiceSession.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/voice-session
+
+> **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 voice-session`. It copies the source into your components folder (`components/ui/VoiceSession/`, under `src/` when the project has one); import it as `@/components/ui/VoiceSession`. 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'` | 'neutral' | Visual style of the card. - `brand`   — brand-tinted surface + brand border - `neutral` — default (white) surface + subtle border (default) - `outline` — transparent surface + default border |
+| `state?` | `'idle' \| 'listening' \| 'processing' \| 'speaking'` | 'listening' | Session lifecycle state. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the header, bubbles and controls. |
+| `title?` | `ReactNode` | labels.title ('Voice session') | Header title. |
+| `model?` | `ReactNode` | — | Model chip text. No default — the chip renders only when set. |
+| `language?` | `ReactNode` | — | Language chip text. No default — the chip renders only when set. |
+| `timer?` | `ReactNode` | — | Session timer, top-right. No default — renders only when set. |
+| `statusLabel?` | `ReactNode` | per state from `labels` ('Listening…' / 'Processing…' / 'Speaking…') | Status pill label override. |
+| `stageTitle?` | `ReactNode` | per state from `labels` | Stage title override. |
+| `stageHint?` | `ReactNode` | `labels.stageHintIdle` while idle; otherwise none | Stage hint/subtitle. |
+| `speaker?` | `ReactNode` | — | Transcript bubble — speaker name. No default. |
+| `speakerMeta?` | `ReactNode` | — | Transcript bubble — meta (e.g. `recognizing…`, `0:12`). No default. |
+| `transcript?` | `ReactNode` | — | Transcript bubble — the spoken text. No default; the bubble renders only when `speaker`, `speakerMeta` or `transcript` is set. |
+| `audioCurrentTime?` | `string` | — | Speaking only — audio player current time. The player renders only when an audio prop is set. |
+| `audioDuration?` | `string` | — | Speaking only — audio player total duration. |
+| `audioProgress?` | `number` | — | Speaking only — audio progress (0–100). |
+| `showControls?` | `boolean` | true | Show the trailing control row. |
+| `onPrimaryControl?` | `() => void` | — | Primary control click (mic in listening/processing, regenerate in speaking). |
+| `onToggleCaptions?` | `() => void` | — | Captions control click. |
+| `onSettings?` | `() => void` | — | Settings control click. |
+| `onEndSession?` | `() => void` | — | End-session control click. |
+| `as?` | `ElementType` | 'div' | Override the rendered root element. |
+| `labels?` | `Partial<VoiceSessionLabels>` | — | Localised copy for the title, status/stage text and control names. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`.
+
+## Options (allowed values)
+- `variant`: `'brand'` \| `'neutral'` \| `'outline'` — Visual style of the card — mirrors the Figma `Style` property.
+- `state`: `'idle'` \| `'listening'` \| `'processing'` \| `'speaking'` — Voice-session lifecycle — mirrors the Figma `State` property. Drives the
+status pill, stage media, accent colour and body:
+- `idle`       — static (muted) orb, no status pill, "tap to start" prompt, no bubble
+- `listening`  — pulse-ring orb, info-blue accent, live-speech bubble + waveform
+- `processing` — muted waveform, warning-amber accent, the user's request bubble
+- `speaking`   — active waveform, brand-green accent, the assistant bubble + audio player
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the header, bubbles and controls.
+
+## 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)`
+- `var(--ds-color-bg-brand-subtle)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-info-subtle)`
+- `var(--ds-color-bg-muted)`
+- `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-default)`
+- `var(--ds-color-icon-oncolor)`
+- `var(--ds-color-primitive-radius-radius-10)`
+- `var(--ds-color-primitive-radius-radius-12)`
+- `var(--ds-color-primitive-radius-radius-16)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-info)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-color-text-warning)`
+- `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)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add voice-session` (after `npx sdaia-ui@latest init`), then import `{ VoiceSession }` from `@/components/ui/VoiceSession`.
+- 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/feedback/alert.md

@@ -0,0 +1,106 @@
+# Alerts
+
+## Metadata
+- Component: Alerts
+- Slug: `alert`
+- Category: Feedback
+- Install: `npx sdaia-ui@latest add alert`
+- Import: `import { Alert } from '@/components/ui/Alert'`
+- Installed files: `Alert.tsx`, `Alert.types.ts`, `Alert.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/alerts
+
+> **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 alert`. It copies the source into your components folder (`components/ui/Alert/`, under `src/` when the project has one); import it as `@/components/ui/Alert`. 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' \| 'outline' \| 'solid'` | 'standard' | Structural type of the alert |
+| `variant?` | `'neutral' \| 'info' \| 'error' \| 'warning' \| 'success'` | 'info' | Intent of the alert. |
+| `surface?` | `'solid' \| 'glass'` | 'solid' | Surface material — `glass` swaps the container for the shared liquid-glass skin. |
+| `title?` | `string` | — | Title text displayed as the header |
+| `description?` | `string` | — | Description text displayed below the title |
+| `closable?` | `boolean` | false | Shows a close (X) button |
+| `onClose?` | `() => void` | — | Callback when the close button is clicked |
+| `leadingIcon?` | `ReactNode \| boolean` | — | Leading icon — true for default icon, false to hide, or ReactNode for custom |
+| `actions?` | `ReactNode` | — | Action buttons slot (rendered after text, before close button) |
+| `iconTop?` | `boolean` | false | Stack icon above text (for mobile/tablet layouts) |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the alert. Inherits from the document when omitted. |
+| `labels?` | `Partial<AlertLabels>` | — | Override built-in strings (English defaults) to localize the alert. |
+| `children?` | `ReactNode` | — | — |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`, `title`.
+
+## Options (allowed values)
+- `type`: `'standard'` \| `'outline'` \| `'solid'` — Structural type of the alert
+- `variant`: `'neutral'` \| `'info'` \| `'error'` \| `'warning'` \| `'success'` — Intent of the alert (neutral / info / error / warning / success). A
+variation of the design, not an interaction condition, so it is modelled as
+`variant`.
+- `surface`: `'solid'` \| `'glass'` — Surface material of the alert.
+- `solid` — the opaque per-type surface (default)
+- `glass` — the shared liquid-glass material (`.glass-surface`): translucent
+  background + backdrop blur + beveled shadow. Variant colours still drive the
+  icon and text (via the `standard` treatment, so copy stays readable on the
+  translucent surface). Orthogonal to `type`/`variant`.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the alert. Inherits from the document when omitted.
+
+## Deprecated props
+Do not use in new code:
+- `state`
+- `icon`
+
+## 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-alpha-black-10)`
+- `var(--ds-color-alpha-black-20)`
+- `var(--ds-color-bg-danger-muted)`
+- `var(--ds-color-bg-danger-strong)`
+- `var(--ds-color-bg-danger-subtle)`
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-emphasis-high)`
+- `var(--ds-color-bg-info-muted)`
+- `var(--ds-color-bg-info-strong)`
+- `var(--ds-color-bg-info-subtle)`
+- `var(--ds-color-bg-muted)`
+- `var(--ds-color-bg-success-muted)`
+- `var(--ds-color-bg-success-strong)`
+- `var(--ds-color-bg-success-subtle)`
+- `var(--ds-color-bg-warning-muted)`
+- `var(--ds-color-bg-warning-strong)`
+- `var(--ds-color-bg-warning-subtle)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-focus)`
+- `var(--ds-color-button-bg-neutral-hovered)`
+- `var(--ds-color-button-bg-neutral-pressed)`
+- `var(--ds-color-icon-danger)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-icon-info)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-icon-oncolor)`
+- `var(--ds-color-icon-success)`
+- `var(--ds-color-icon-warning)`
+- `var(--ds-color-text-danger)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-info)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-color-text-success)`
+- `var(--ds-color-text-warning)`
+- `var(--ds-icon-3xl)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-figma-xs)`
+- …and 20 more
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add alert` (after `npx sdaia-ui@latest init`), then import `{ Alert }` from `@/components/ui/Alert`.
+- 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.