@sdaia-ds/mcp 0.0.0-stage → 3.1.0

package/knowledge/ai/ai-states.md

@@ -0,0 +1,107 @@
+# AI States
+
+## Metadata
+- Component: AI States (composite pattern — not a single component)
+- Slug: `ai-states`
+- Category: AI
+- Install: `npx sdaia-ui@latest add ai-state-row ai-reasoning-state ai-research-state ai-tool-state ai-generation-state ai-artifact-state ai-context-state ai-memory-state ai-model-state ai-multi-agent-state`
+- Import: per family member, e.g. `import { AiReasoningState } from '@/components/ui/AiReasoningState'`
+- Docs: https://ds.nacew.com/components/ai-states
+
+> **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 add only the state components you need from the list above. It copies the source into your components folder (`components/ui/<Name>/`, under `src/` when the project has one); import each part as `@/components/ui/<Name>`. 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.
+
+> **There is no `ai-states` slug to install.** "AI States" is a documentation grouping for a family of single-line status rows that all share one shape (`AiStateRow`). Install the specific members you need — the docs site's `add ai-states` command does not exist in the registry.
+
+## Description
+A family of compact, single-line status rows that communicate what an AI/agent system is doing right now (thinking, searching, running a tool, streaming, managing context/memory, switching model, coordinating agents). Every member renders the same `AiStateRow` shell — a leading icon, a primary label, and an intent-coloured trailing hint — and differs only in its `state` union, which picks the default intent colour, icon, label, and hint.
+
+## Composed components
+Each is installable on its own; pick the ones your flow needs.
+
+| Component | Slug | Purpose |
+| --- | --- | --- |
+| `AiStateRow` | `ai-state-row` | Base row primitive — use directly for a fully custom state. |
+| `AiReasoningState` | `ai-reasoning-state` | Model reasoning / thinking status. |
+| `AiResearchState` | `ai-research-state` | Source search, reading, and ranking status. |
+| `AiToolState` | `ai-tool-state` | Tool invocation lifecycle (waiting → running → result). |
+| `AiGenerationState` | `ai-generation-state` | Output streaming / pause / regenerate status. |
+| `AiArtifactState` | `ai-artifact-state` | Artifact generation lifecycle. |
+| `AiContextState` | `ai-context-state` | Context-window health (full, truncated, lost…). |
+| `AiMemoryState` | `ai-memory-state` | Memory read/write/conflict status. |
+| `AiModelState` | `ai-model-state` | Model switching / fallback / availability. |
+| `AiMultiAgentState` | `ai-multi-agent-state` | Multi-agent coordination + handoff status. |
+
+## Props
+The semantic members (`AiReasoningState`, `AiToolState`, …) share one prop shape:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `state` | *(per-component union — see Options)* | — | Which state to display. Drives the intent colour, default icon, label, and hint. |
+| `dir?` | `'ltr' \| 'rtl'` | `'ltr'` | Layout direction (mirrors for RTL). |
+| `label?` | `ReactNode` | — | Override the default label for the state. |
+| `hint?` | `ReactNode` | — | Override the default trailing hint for the state. |
+| `icon?` | `string` | — | Override the leading icon — a `@platformscode/icons` data URL. |
+| `onHintClick?` | `() => void` | — | When set, the hint becomes an interactive action (e.g. `View chain`, `Authorize`). |
+| `hintLabel?` | `string` | hint text | Accessible label for the hint action. |
+
+The base `AiStateRow` takes the same fields but requires `intent` and `icon` explicitly:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `intent` | `'brand' \| 'success' \| 'warning' \| 'danger' \| 'info' \| 'neutral'` | — | Semantic intent — drives border, icon, and hint colour. |
+| `icon` | `string` | — | Leading icon (`@platformscode/icons` data URL). |
+| `label` | `ReactNode` | — | Primary label (always default text colour). |
+| `hint?` | `ReactNode` | — | Intent-coloured trailing status text or action label. |
+| `onHintClick?` | `() => void` | — | Makes the hint an interactive button. |
+| `hintLabel?` | `string` | hint text | Accessible label for the hint button. |
+| `dir?` | `'ltr' \| 'rtl'` | `'ltr'` | Layout direction. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `aria-*`, …) except `title`.
+
+## Options (allowed `state` values)
+- `AiReasoningState` — `'deep-thinking'` \| `'reasoning-hidden'` \| `'reasoning-available'` \| `'reasoning-unavailable'`
+- `AiResearchState` — `'searching-sources'` \| `'reading-sources'` \| `'ranking-sources'` \| `'source-failed'` \| `'no-sources-found'`
+- `AiToolState` — `'tool-waiting'` \| `'tool-running'` \| `'permission-needed'` \| `'tool-failed'` \| `'tool-timed-out'`
+- `AiGenerationState` — `'streaming'` \| `'paused'` \| `'interrupted'` \| `'continued'` \| `'regenerating'` \| `'comparing-versions'`
+- `AiArtifactState` — `'generating-artifact'` \| `'artifact-ready'` \| `'artifact-failed'` \| `'artifact-updated'`
+- `AiContextState` — `'context-full'` \| `'context-truncated'` \| `'context-lost'` \| `'context-imported'` \| `'context-invalid'`
+- `AiMemoryState` — `'memory-used'` \| `'memory-updated'` \| `'memory-conflict'` \| `'memory-permission-required'`
+- `AiModelState` — `'model-switching'` \| `'model-fallback'` \| `'model-overloaded'` \| `'model-unavailable'`
+- `AiMultiAgentState` — `'agent-started'` \| `'agent-waiting'` \| `'agent-handoff'` \| `'agent-conflict'` \| `'agent-complete'`
+- `AiStateRow` `intent` — `'brand'` \| `'success'` \| `'warning'` \| `'danger'` \| `'info'` \| `'neutral'`
+
+## Usage example
+```tsx
+import { AiReasoningState } from '@/components/ui/AiReasoningState';
+import { AiResearchState } from '@/components/ui/AiResearchState';
+import { AiToolState } from '@/components/ui/AiToolState';
+import { AiGenerationState } from '@/components/ui/AiGenerationState';
+
+// Stack the live status of the current turn — each row defaults its own
+// icon, colour, label, and hint from `state`.
+<div className="flex flex-col gap-spacing-md">
+  <AiReasoningState state="deep-thinking" />
+  <AiResearchState state="searching-sources" />
+  <AiToolState state="tool-running" />
+  <AiGenerationState state="streaming" />
+</div>
+```
+
+## Accessibility
+- Keep keyboard focus visible and any interactive `hint` (`onHintClick`) keyboard-operable; give it a clear `hintLabel`.
+- Convey status with text, not colour alone — the label/hint already carry meaning; intent colour is supplementary.
+- For full color-contrast and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- Intent colours resolve from semantic tokens (`color-text-*`, `color-border-*`, `brand-*`) per `intent`/`state`.
+- Spacing/radius via `spacing-*` / `radius-*` tokens; never hardcode colours.
+
+## AI usage guidance
+When generating UI:
+- Install only the state members you use (see Install), then import each `{ AiXState }` from `@/components/ui/AiXState`. NEVER `add ai-states` — that slug does not exist.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Drive each row with the documented `state` value; only override `label`/`hint`/`icon` for custom copy. Use only the listed `state` options.
+- For a one-off status not covered by a family member, use `AiStateRow` directly with an explicit `intent` + `icon`.
+- Pass any custom `icon` as a `@platformscode/icons` data URL — see `get_foundations` (`icon-usage`). Never emoji, Lucide, or random icons.
+- Pick one theme per screen via `.theme-dark`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/ai/ai-status-indicator.md

@@ -0,0 +1,81 @@
+# AI Status Indicator
+
+## Metadata
+- Component: AI Status Indicator
+- Slug: `ai-status-indicator`
+- Category: AI
+- Install: `npx sdaia-ui@latest add ai-status-indicator`
+- Import: `import { AiStatusIndicator } from '@/components/ui/AiStatusIndicator'`
+- Installed files: `AiStatusIndicator.tsx`, `AiStatusIndicator.types.ts`, `AiStatusIndicator.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/ai-status-indicator
+
+> **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-status-indicator`. It copies the source into your components folder (`components/ui/AiStatusIndicator/`, under `src/` when the project has one); import it as `@/components/ui/AiStatusIndicator`. 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 |
+| --- | --- | --- | --- |
+| `state?` | `'thinking' \| 'tool-running' \| 'tool-success' \| 'tool-error' \| 'source' \| 'model' \| 'agent' \| 'memory'` | 'thinking' | Which AI/agent state to display — drives the icon, intent colour and default copy. |
+| `variant?` | `'brand' \| 'neutral' \| 'outline'` | 'brand' | Visual style of the chip. - `brand`   — tinted semantic fill + border (default) - `neutral` — neutral fill + border, semantic icon only - `outline` — transparent fill, semantic border |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. Inherits from the document when unset. `rtl` mirrors the layout and, when `labels` has no entry for the state, uses the built-in Arabic copy. |
+| `showIcon?` | `boolean` | true | Show the leading status icon. |
+| `animated?` | `boolean` | true | Animate the live statuses — a text shimmer on `thinking` and a spinning icon on `tool-running`. Settled statuses stay static. Collapses under `prefers-reduced-motion`. |
+| `labels?` | `Partial<AiStatusIndicatorLabels>` | — | Translatable label per state (see ). |
+| `label?` | `ReactNode` | — | Override the label for the current state (wins over `labels`). |
+| `children?` | `ReactNode` | — | Alias for . |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`.
+
+## Options (allowed values)
+- `state`: `'thinking'` \| `'tool-running'` \| `'tool-success'` \| `'tool-error'` \| `'source'` \| `'model'` \| `'agent'` \| `'memory'` — Canonical name for  — the indicator's `state` values.
+- `variant`: `'brand'` \| `'neutral'` \| `'outline'` — Visual style of the chip (Figma "Style" property) — a type, not a state.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. Inherits from the document when unset. `rtl` mirrors the
+layout and, when `labels` has no entry for the state, uses the built-in
+Arabic copy.
+
+## Deprecated props
+Do not use in new code:
+- `status`
+- `appearance`
+
+## 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-muted)`
+- `var(--ds-color-bg-danger-muted)`
+- `var(--ds-color-bg-info-muted)`
+- `var(--ds-color-bg-muted)`
+- `var(--ds-color-bg-success-muted)`
+- `var(--ds-color-bg-warning-muted)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-danger-strong)`
+- `var(--ds-color-border-info-strong)`
+- `var(--ds-color-border-subtle)`
+- `var(--ds-color-border-success-strong)`
+- `var(--ds-color-border-warning-strong)`
+- `var(--ds-color-icon-brand)`
+- `var(--ds-color-icon-danger)`
+- `var(--ds-color-icon-info)`
+- `var(--ds-color-icon-success)`
+- `var(--ds-color-icon-warning)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-color-text-danger)`
+- `var(--ds-color-text-info)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-color-text-success)`
+- `var(--ds-color-text-warning)`
+- `var(--ds-radius-full)`
+- `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-status-indicator` (after `npx sdaia-ui@latest init`), then import `{ AiStatusIndicator }` from `@/components/ui/AiStatusIndicator`.
+- 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-suggested-prompts.md

@@ -0,0 +1,62 @@
+# AI Suggested Prompts
+
+## Metadata
+- Component: AI Suggested Prompts
+- Slug: `ai-suggested-prompts`
+- Category: AI
+- Install: `npx sdaia-ui@latest add ai-suggested-prompts`
+- Import: `import { AiSuggestedPrompts } from '@/components/ui/AiSuggestedPrompts'`
+- Installed files: `AiSuggestedPrompts.tsx`, `AiSuggestedPrompts.types.ts`, `AiSuggestedPrompts.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/ai-suggested-prompts
+
+> **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-suggested-prompts`. It copies the source into your components folder (`components/ui/AiSuggestedPrompts/`, under `src/` when the project has one); import it as `@/components/ui/AiSuggestedPrompts`. 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 |
+| --- | --- | --- | --- |
+| `items` | `AiSuggestedPromptItem[]` | — | The suggested-prompt entry points to render. |
+| `type?` | `'starter-cards' \| 'follow-up-chips'` | 'starter-cards' | Layout type — mirrors the Figma `Type` property. - `starter-cards`   — icon disc + title + description cards (default) - `follow-up-chips` — compact pill chips with a single label |
+| `variant?` | `'neutral' \| 'brand' \| 'outline'` | 'neutral' | Visual style — mirrors the Figma `Style` property. - `neutral` — white surface, neutral border (default) - `brand`   — brand-subtle surface, brand-green border - `outline` — transparent surface, neutral border |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the row flow and text alignment. |
+| `icon?` | `string` | sparklesStroke | Leading icon for every starter card (a `@platformscode/icons` data URL rendered through `DgaIcon`). Overridable per item via `item.icon`. |
+| `showIcon?` | `boolean` | true | Show the leading icon disc on starter cards. |
+| `onSelect?` | `(item: AiSuggestedPromptItem, index: number) => void` | — | Fired when any entry is activated. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `onSelect`.
+
+## Options (allowed values)
+- `type`: `'starter-cards'` \| `'follow-up-chips'` — Layout type — mirrors the Figma `Type` property.
+- `variant`: `'neutral'` \| `'brand'` \| `'outline'` — Visual style — mirrors the Figma `Style` property.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the row flow and text alignment.
+
+## Accessibility
+- 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-control-border)`
+- `var(--ds-color-icon-brand)`
+- `var(--ds-color-primitive-radius-radius-12)`
+- `var(--ds-color-primitive-radius-radius-8)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-full)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-sm)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add ai-suggested-prompts` (after `npx sdaia-ui@latest init`), then import `{ AiSuggestedPrompts }` from `@/components/ui/AiSuggestedPrompts`.
+- 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-thinking-indicator.md

@@ -0,0 +1,94 @@
+# AI Thinking Indicator
+
+## Metadata
+- Component: AI Thinking Indicator
+- Slug: `ai-thinking-indicator`
+- Category: AI
+- Install: `npx sdaia-ui@latest add ai-thinking-indicator`
+- Import: `import { AiThinkingIndicator } from '@/components/ui/AiThinkingIndicator'`
+- Installed files: `AiThinkingIndicator.tsx`, `AiThinkingIndicator.types.ts`, `AiThinkingIndicator.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/ai-thinking-indicator
+
+> **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-thinking-indicator`. It copies the source into your components folder (`components/ui/AiThinkingIndicator/`, under `src/` when the project has one); import it as `@/components/ui/AiThinkingIndicator`. 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?` | `'dots' \| 'activity' \| 'reasoning'` | 'dots' | Which cue to render. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the layout. Inherits from the document when unset. |
+| `icon?` | `string` | sparklesStroke | Leading AI avatar glyph (a `DgaIcon` data URL from `@platformscode/icons`). |
+| `showAvatar?` | `boolean` | true | Show the leading AI avatar badge (brand circle + sparkle). |
+| `animated?` | `boolean` | true | Animate the working cues — bouncing thinking dots, a shimmering activity label and shimmering live-reasoning copy. Disable for a static snapshot; all collapse under `prefers-reduced-motion`. |
+| `labels?` | `Partial<AiThinkingIndicatorLabels>` | — | Translatable built-in strings (see ). |
+| `label?` | `ReactNode` | — | Activity label shown in the `activity` type (e.g. "Searching the web…"). Falls back to `labels.thinking` ('Thinking…') when unset. |
+| `collapsedLabel?` | `ReactNode` | — | Label for the collapsed reasoning toggle (wins over `labels.showReasoning`). |
+| `title?` | `ReactNode` | — | Title shown in the expanded reasoning panel header (wins over `labels.reasoning`). |
+| `children?` | `ReactNode` | — | Reasoning body content rendered inside the expanded panel. Nothing is rendered in the body when unset. |
+| `open?` | `boolean` | — | Controlled open state of the reasoning disclosure. |
+| `defaultOpen?` | `boolean` | false | Initial open state of the reasoning disclosure when uncontrolled. |
+| `onOpenChange?` | `(open: boolean) => void` | — | Called when the reasoning disclosure is toggled. |
+| `thinkingLabel?` | `string` | — | Status text announced by the wordless `dots` type (wins over `labels.thinking`). |
+| `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 (a type) — mirrors the Figma `Style` property.
+- `neutral` — quiet surface (raised / subtle) with a default border (default)
+- `brand`   — brand-tinted surface with a brand border
+- `outline` — minimal surface (default / transparent) with a default border
+- `type`: `'dots'` \| `'activity'` \| `'reasoning'` — Structural type — mirrors the Figma `State` property, which describes a
+variation of the cue rather than a condition (so it is a type here):
+- `dots`      — three pulsing dots (model is thinking, no copy yet)
+- `activity`  — sparkle + short activity label (e.g. "Searching the web…")
+- `reasoning` — a reasoning disclosure; collapsed shows a "Show reasoning"
+  toggle, expanded (via ) reveals the
+  reasoning panel. The Figma `Reasoning-Open` variant is this type with the
+  disclosure open.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the layout. Inherits from the document when unset.
+
+## Deprecated props
+Do not use in new code:
+- `style`
+- `state`
+- `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-default)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-muted)`
+- `var(--ds-color-icon-brand)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-icon-oncolor)`
+- `var(--ds-color-primitive-radius-radius-10)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add ai-thinking-indicator` (after `npx sdaia-ui@latest init`), then import `{ AiThinkingIndicator }` from `@/components/ui/AiThinkingIndicator`.
+- 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/artifact-viewer.md

@@ -0,0 +1,105 @@
+# Artifact Viewer
+
+## Metadata
+- Component: Artifact Viewer
+- Slug: `artifact-viewer`
+- Category: AI
+- Install: `npx sdaia-ui@latest add artifact-viewer`
+- Import: `import { ArtifactViewer } from '@/components/ui/ArtifactViewer'`
+- Installed files: `ArtifactViewer.tsx`, `ArtifactViewer.types.ts`, `ArtifactViewer.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/artifact-viewer
+
+> **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 artifact-viewer`. It copies the source into your components folder (`components/ui/ArtifactViewer/`, under `src/` when the project has one); import it as `@/components/ui/ArtifactViewer`. 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 |
+| --- | --- | --- | --- |
+| `mode?` | `'inline' \| 'fullscreen'` | 'inline' | Layout mode. `inline` is the compact card; `fullscreen` is the 2-pane viewer. |
+| `type?` | `'code' \| 'file' \| 'document' \| 'image'` | 'code' | Artifact kind — drives the tile accent, default icon and preview rendering. |
+| `variant?` | `'neutral' \| 'brand' \| 'outline'` | 'neutral' | Visual style of the card surface. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the header, sidebar and action order. |
+| `title` | `ReactNode` | — | Artifact name / filename (header title). |
+| `subtitle?` | `ReactNode` | — | Secondary line — e.g. `TypeScript · 1.2 KB`. |
+| `icon?` | `string` | — | Override the tile icon (a `@platformscode/icons` data URL). Defaults per `type`. |
+| `status?` | `ReactNode` | — | Status chip label (e.g. `Ready`). No default — the chip renders only when set. |
+| `statusState?` | `'success' \| 'warning' \| 'danger' \| 'info' \| 'neutral'` | 'success' | Status chip colour intent. |
+| `showStatus?` | `boolean` | true | Show the status chip. |
+| `version?` | `ReactNode` | — | Version label shown as a chip in the fullscreen top bar (e.g. `v2`). |
+| `code?` | `string` | — | Code body for `type="code"` (rendered in the dark code panel). Nothing renders when omitted. |
+| `imageSrc?` | `string` | — | Image source for `type="image"` — when omitted a placeholder is shown. |
+| `imageCaption?` | `ReactNode` | — | Caption under the image placeholder / image. |
+| `documentHeading?` | `ReactNode` | — | Heading for `type="document"`. |
+| `documentBody?` | `ReactNode` | — | Custom body for `type="document"` — overrides the default skeleton lines. |
+| `preview?` | `ReactNode` | — | Fully override the preview region for any type. |
+| `meta?` | `ArtifactViewerMetaRow[]` | — | Metadata rows. No default — the list renders only when rows are passed. |
+| `detailsHeading?` | `ReactNode` | 'Details' | Heading above the details sidebar (fullscreen). Same as `labels.details`. |
+| `prompt?` | `ReactNode` | — | Prompt line shown in the inline card. |
+| `showPrompt?` | `boolean` | true | Show the prompt row (inline only). |
+| `onOpen?` | `() => void` | — | Action handlers — the matching buttons render with the `labels` copy. |
+| `onCopy?` | `() => void` | — | — |
+| `onDownload?` | `() => void` | — | — |
+| `onRegenerate?` | `() => void` | — | — |
+| `onMore?` | `() => void` | — | — |
+| `onExpand?` | `() => void` | — | Inline header expand control (→ fullscreen). |
+| `onClose?` | `() => void` | — | Fullscreen top-bar close control. |
+| `actions?` | `ReactNode` | — | Override the inline actions row entirely. |
+| `headerActions?` | `ReactNode` | — | Override the fullscreen top-bar trailing action buttons. |
+| `labels?` | `Partial<ArtifactViewerLabels>` | — | Localised copy for the action buttons, icon-button names and details heading. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `prefix`.
+
+## Options (allowed values)
+- `mode`: `'inline'` \| `'fullscreen'` — Layout mode — mirrors the Figma `Variant` property.
+- `type`: `'code'` \| `'file'` \| `'document'` \| `'image'` — Artifact kind — mirrors the Figma `Type` property. Sets the tile accent, icon and preview.
+- `variant`: `'neutral'` \| `'brand'` \| `'outline'` — Visual style of the card — mirrors the Figma `Style` property.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the header, sidebar and action order.
+- `statusState`: `'success'` \| `'warning'` \| `'danger'` \| `'info'` \| `'neutral'` — Colour intent of the status chip.
+
+## 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-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-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-info)`
+- `var(--ds-color-icon-success)`
+- `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-6)`
+- `var(--ds-color-primitive-radius-radius-8)`
+- `var(--ds-color-primitive-radius-radius-9999)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+- `var(--ds-text-leading-line-heights-text-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add artifact-viewer` (after `npx sdaia-ui@latest init`), then import `{ ArtifactViewer }` from `@/components/ui/ArtifactViewer`.
+- 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/citation.md

@@ -0,0 +1,61 @@
+# Citation
+
+## Metadata
+- Component: Citation
+- Slug: `citation`
+- Category: AI
+- Install: `npx sdaia-ui@latest add citation`
+- Import: `import { Citation } from '@/components/ui/Citation'`
+- Installed files: `Citation.tsx`, `Citation.types.ts`, `Citation.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/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 citation`. It copies the source into your components folder (`components/ui/Citation/`, under `src/` when the project has one); import it as `@/components/ui/Citation`. 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 citation badge. - `brand`   — raised surface, success-green index badge (default) - `neutral` — subtle surface, neutral index badge - `outline` — transparent surface, info-blue index badge |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the layout (index trails the text). |
+| `source` | `ReactNode` | — | Source name — the cited document/source (e.g. `knowledge_base_v3`). |
+| `index?` | `ReactNode` | — | Citation index shown in the leading badge (e.g. `1`). |
+| `showIndex?` | `boolean` | true | Show the leading index badge. |
+| `type?` | `ReactNode` | — | Source type shown in the trailing badge (e.g. `Vector File`). |
+| `showType?` | `boolean` | true | Show the trailing type badge (and its divider). |
+| `as?` | `ElementType` | 'span' | Override the rendered root element (e.g. `'a'`, `'button'`). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`.
+
+## Options (allowed values)
+- `variant`: `'brand'` \| `'neutral'` \| `'outline'` — Visual style of the citation — mirrors the Figma `Style` property.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the layout (index trails the text).
+
+## Accessibility
+- 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-info-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-default-strong)`
+- `var(--ds-color-border-info-strong)`
+- `var(--ds-color-border-subtle)`
+- `var(--ds-color-text-brand)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-info)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add citation` (after `npx sdaia-ui@latest init`), then import `{ Citation }` from `@/components/ui/Citation`.
+- 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/context-manager.md

@@ -0,0 +1,111 @@
+# Context Manager
+
+## Metadata
+- Component: Context Manager
+- Slug: `context-manager`
+- Category: AI
+- Install: `npx sdaia-ui@latest add context-manager`
+- Import: `import { ContextManager } from '@/components/ui/ContextManager'`
+- Installed files: `ContextManager.tsx`, `ContextManager.types.ts`, `ContextManager.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/context-manager
+
+> **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 context-manager`. It copies the source into your components folder (`components/ui/ContextManager/`, under `src/` when the project has one); import it as `@/components/ui/ContextManager`. 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?` | `'panel' \| 'inline' \| 'modal'` | 'panel' | Structural layout. |
+| `surface?` | `'neutral' \| 'brand' \| 'outline'` | 'neutral' | Outer surface treatment. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction for RTL support. Omit to inherit from the closest `dir` ancestor. |
+| `labels?` | `Partial<ContextManagerLabels>` | — | Override any built-in string (titles, status words, aria-labels, buttons). |
+| `title?` | `ReactNode` | `labels.title` (panel/inline) · `labels.modalTitle` (modal) | Title text. |
+| `headerStatus?` | `ReactNode` | — | Panel: status badge shown next to the title (e.g. "Active"). |
+| `subtitle?` | `ReactNode` | — | Panel: subtitle line · Modal: description line under the title. |
+| `count?` | `number` | — | Inline: total-count shown in the muted pill after the title. |
+| `activeCount?` | `number` | — | Inline: number shown in the green "{n} active" badge. |
+| `activeLabel?` | `string` | 'active' | Inline: word after `activeCount` in the badge. Wins over `labels.active`. |
+| `tabs?` | `ContextTab[]` | — | — |
+| `activeTabId?` | `string` | — | Controlled active tab id. |
+| `onTabChange?` | `(id: string) => void` | — | — |
+| `items?` | `ContextItem[]` | [] | — |
+| `onToggleItem?` | `(id: string, on: boolean) => void` | — | Fired when a row toggle changes. |
+| `detail?` | `ContextDetail \| null` | — | Right-column detail for the selected item. Pass `null` to hide it. |
+| `moreCount?` | `number` | — | Inline: "+{n} more" pill appended after the chips. |
+| `onRemoveItem?` | `(id: string) => void` | — | Inline: fired when a chip's dismiss "×" is activated. |
+| `searchPlaceholder?` | `string` | — | Modal search placeholder. Wins over `labels.searchPlaceholder`. |
+| `searchValue?` | `string` | — | Modal search value (controlled). |
+| `onSearchChange?` | `(value: string) => void` | — | — |
+| `footerSummary?` | `ReactNode` | — | Modal footer summary text (e.g. "4 of 12 shown"). |
+| `warning?` | `ReactNode` | — | Panel footer warning text. Omit to hide the warning bar. |
+| `addLabel?` | `string` | — | — |
+| `manageLabel?` | `string` | — | — |
+| `previewLabel?` | `string` | — | — |
+| `openSourceLabel?` | `string` | — | — |
+| `removeLabel?` | `string` | — | — |
+| `cancelLabel?` | `string` | — | — |
+| `saveLabel?` | `string` | — | — |
+| `onAddContext?` | `() => void` | — | — |
+| `onManage?` | `() => void` | — | — |
+| `onSearch?` | `() => void` | — | — |
+| `onFilter?` | `() => void` | — | — |
+| `onSort?` | `() => void` | — | — |
+| `onClose?` | `() => void` | — | — |
+| `onCancel?` | `() => void` | — | — |
+| `onSave?` | `() => void` | — | — |
+| `onPreview?` | `() => void` | — | — |
+| `onOpenSource?` | `() => void` | — | — |
+| `onRemove?` | `() => void` | — | — |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`.
+
+## Options (allowed values)
+- `variant`: `'panel'` \| `'inline'` \| `'modal'` — Structural layout of the manager.
+- `panel`  — full two-column panel: header, tabs, list + detail, footer warning.
+- `inline` — compact in-conversation strip: header, dismissible chips, actions.
+- `modal`  — centred dialog: header, search, list, footer actions.
+
+Mirrors the Figma `Variant` property (Panel / Inline / Modal).
+- `surface`: `'neutral'` \| `'brand'` \| `'outline'` — Outer surface treatment — mirrors the Figma `Style` property.
+- `neutral` — solid raised surface, hairline border.
+- `brand`   — brand-tinted surface, brand border.
+- `outline` — transparent surface, neutral border.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction for RTL support. Omit to inherit from the closest `dir` ancestor.
+
+## 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-info-subtle)`
+- `var(--ds-color-bg-muted)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-bg-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-button-bg-neutral-default)`
+- `var(--ds-color-icon-brand)`
+- `var(--ds-color-icon-info)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-icon-warning)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-color-text-warning)`
+- `var(--ds-radius-full)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add context-manager` (after `npx sdaia-ui@latest init`), then import `{ ContextManager }` from `@/components/ui/ContextManager`.
+- 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.