@sdaia-ds/mcp 0.0.0-stage → 3.1.1

package/knowledge/ai/prompt-context.md

@@ -0,0 +1,72 @@
+# Prompt Context
+
+## Metadata
+- Component: Prompt Context
+- Slug: `prompt-context`
+- Category: AI
+- Install: `npx sdaia-ui@latest add prompt-context`
+- Import: `import { PromptContext } from '@/components/ui/PromptContext'`
+- Installed files: `PromptContext.tsx`, `PromptContext.types.ts`, `PromptContext.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/prompt-context
+
+> **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 prompt-context`. It copies the source into your components folder (`components/ui/PromptContext/`, under `src/` when the project has one); import it as `@/components/ui/PromptContext`. 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 context chip. - `brand`   — raised surface + brand-tinted icon tile (default) - `neutral` — subtle surface + muted icon tile - `outline` — transparent surface + outlined icon tile |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the layout. Omit to inherit from the closest `dir` ancestor. |
+| `labels?` | `Partial<PromptContextLabels>` | — | Override any built-in string (e.g. the remove button's aria-label). |
+| `icon?` | `string` | fileAttachmentStroke | Leading icon — a `@platformscode/icons` data URL. |
+| `filename` | `ReactNode` | — | File name / context title (truncates on overflow). |
+| `tokens?` | `ReactNode` | — | Token-count label (e.g. `14.8k tokens`). |
+| `fileType?` | `ReactNode` | — | File-type badge label (e.g. `CSV`). |
+| `showType?` | `boolean` | true | Show the file-type badge. |
+| `status?` | `ReactNode` | — | Status badge label (e.g. `Loaded`). |
+| `showStatus?` | `boolean` | true | Show the status badge. |
+| `statusColor?` | `BadgeColor` | 'primary' | Status badge colour. |
+| `showRemove?` | `boolean` | true | Show the remove action. |
+| `removeIcon?` | `string` | cancel01Stroke | Remove icon — a `@platformscode/icons` data URL. |
+| `removeLabel?` | `string` | 'Remove' | Accessible label for the remove button. Wins over `labels.remove`. |
+| `onRemove?` | `MouseEventHandler<HTMLButtonElement>` | — | Click handler for the remove button. |
+| `as?` | `ElementType` | 'div' | Override the rendered root element. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`, `title`.
+
+## Options (allowed values)
+- `variant`: `'brand'` \| `'neutral'` \| `'outline'` — Visual style of the chip — mirrors the Figma `Style` property.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the layout. 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-muted)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-bg-subtle)`
+- `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-l)`
+- `var(--ds-radius-m)`
+- `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 prompt-context` (after `npx sdaia-ui@latest init`), then import `{ PromptContext }` from `@/components/ui/PromptContext`.
+- 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/prompt-suggestion.md

@@ -0,0 +1,68 @@
+# Prompt Suggestion
+
+## Metadata
+- Component: Prompt Suggestion
+- Slug: `prompt-suggestion`
+- Category: AI
+- Install: `npx sdaia-ui@latest add prompt-suggestion`
+- Import: `import { PromptSuggestion } from '@/components/ui/PromptSuggestion'`
+- Installed files: `PromptSuggestion.tsx`, `PromptSuggestion.types.ts`, `PromptSuggestion.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/prompt-suggestion
+
+> **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 prompt-suggestion`. It copies the source into your components folder (`components/ui/PromptSuggestion/`, under `src/` when the project has one); import it as `@/components/ui/PromptSuggestion`. 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 suggestion card. - `brand`   — raised surface, neutral border that turns brand-green on hover, soft-tinted icon disc + soft category chip (default) - `neutral` — subtle surface, black icon disc, neutral category chip - `outline` — transparent surface, outlined icon disc + outlined chip |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the layout (icon trails the text). |
+| `title` | `ReactNode` | — | Primary line — the suggested prompt title. |
+| `description?` | `ReactNode` | — | Secondary line — a short description of the prompt. |
+| `category?` | `ReactNode` | — | Category label rendered inside the DS Chip. |
+| `meta?` | `ReactNode` | — | Token-cost meta text shown after the category (e.g. `~2.1k tokens`). |
+| `icon?` | `string` | sparklesStroke | Leading icon — a `@platformscode/icons` data URL rendered through `DgaIcon`. |
+| `showIcon?` | `boolean` | true | Show the leading icon disc. |
+| `as?` | `ElementType` | 'button' | Override the rendered root element (e.g. `'a'`, `'div'`). |
+
+Also accepts standard `<button>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `prefix`.
+
+## 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 layout (icon 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-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-subtle)`
+- `var(--ds-color-button-bg-black-default)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-icon-oncolor)`
+- `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-radius-l)`
+- `var(--ds-radius-xl)`
+- `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 prompt-suggestion` (after `npx sdaia-ui@latest init`), then import `{ PromptSuggestion }` from `@/components/ui/PromptSuggestion`.
+- 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/prompt-template.md

@@ -0,0 +1,71 @@
+# Prompt Template
+
+## Metadata
+- Component: Prompt Template
+- Slug: `prompt-template`
+- Category: AI
+- Install: `npx sdaia-ui@latest add prompt-template`
+- Import: `import { PromptTemplate } from '@/components/ui/PromptTemplate'`
+- Installed files: `PromptTemplate.tsx`, `PromptTemplate.types.ts`, `PromptTemplate.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/prompt-template
+
+> **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 prompt-template`. It copies the source into your components folder (`components/ui/PromptTemplate/`, under `src/` when the project has one); import it as `@/components/ui/PromptTemplate`. 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 template card. - `brand`   — raised surface + soft (green) category chip (default) - `neutral` — subtle surface + neutral category chip - `outline` — transparent surface + outlined category chip |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the layout. Omit to inherit from the closest `dir` ancestor. |
+| `labels?` | `Partial<PromptTemplateLabels>` | — | Override any built-in string (e.g. the action button label). |
+| `category?` | `ReactNode` | — | Category label rendered in the DS Chip. |
+| `showChip?` | `boolean` | true | Show the category chip. |
+| `difficulty?` | `ReactNode` | — | Difficulty label rendered in the DS Badge (gold). |
+| `showBadge?` | `boolean` | true | Show the difficulty badge. |
+| `owner?` | `ReactNode` | — | Owner / scope label (e.g. `Global Template`). |
+| `ownerIcon?` | `string` | user02Stroke | Owner icon — a `@platformscode/icons` data URL. |
+| `title` | `ReactNode` | — | Title — the template name. |
+| `description?` | `ReactNode` | — | Short description of what the template does. |
+| `stat?` | `ReactNode` | — | Primary stat (e.g. `Saves ~2 hrs`). |
+| `statMeta?` | `ReactNode` | — | Secondary stat after the separator dot (e.g. `1.2k uses`). |
+| `statIcon?` | `string` | timeHalfPassStroke | Stat icon — a `@platformscode/icons` data URL. |
+| `showStat?` | `boolean` | true | Show the stat row. |
+| `actionLabel?` | `ReactNode` | 'Inject Template' | Action button label. Wins over `labels.action`; pass `null` to hide the button. |
+| `actionIcon?` | `string` | arrowRight02Stroke | Action button leading icon — a `@platformscode/icons` data URL. |
+| `onAction?` | `MouseEventHandler<HTMLButtonElement>` | — | Click handler for the action button. |
+| `showAction?` | `boolean` | true | Render the action button. |
+| `as?` | `ElementType` | 'div' | Override the rendered root element. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `children`.
+
+## 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 layout. 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-raised)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-subtle)`
+- `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-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add prompt-template` (after `npx sdaia-ui@latest init`), then import `{ PromptTemplate }` from `@/components/ui/PromptTemplate`.
+- 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/prompt-variable.md

@@ -0,0 +1,61 @@
+# Prompt Variable
+
+## Metadata
+- Component: Prompt Variable
+- Slug: `prompt-variable`
+- Category: AI
+- Install: `npx sdaia-ui@latest add prompt-variable`
+- Import: `import { PromptVariable } from '@/components/ui/PromptVariable'`
+- Installed files: `PromptVariable.tsx`, `PromptVariable.types.ts`, `PromptVariable.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/prompt-variable
+
+> **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 prompt-variable`. It copies the source into your components folder (`components/ui/PromptVariable/`, under `src/` when the project has one); import it as `@/components/ui/PromptVariable`. 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 variable card. - `brand`   — raised surface (default) - `neutral` — subtle surface - `outline` — transparent surface |
+| `locked?` | `boolean` | false | Locked state — the value input is read-only/disabled and the state badge + marker switch to the neutral "Locked" treatment. Mirrors the Figma `State`. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the layout. Omit to inherit from the closest `dir` ancestor. |
+| `labels?` | `Partial<PromptVariableLabels>` | — | Override any built-in string (state badge text, the input's fallback name). |
+| `label?` | `ReactNode` | — | Variable label (e.g. `Variable: Language_Target`). It also names the value input (`aria-labelledby`); without it the input is named by `labels.value`. |
+| `showState?` | `boolean` | true | Show the state badge (Editable / Locked). |
+| `stateLabel?` | `ReactNode` | — | Override the state badge text. Wins over `labels.editable` / `labels.locked`. |
+| `showType?` | `boolean` | true | Show the type badge. |
+| `type?` | `ReactNode` | — | Type badge label (e.g. `string`). |
+| `helper?` | `ReactNode` | — | Helper text after the type badge (e.g. `Used in 3 places`). |
+| `placeholder?` | `string` | — | Placeholder for the value input. |
+
+Also accepts standard `<input>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `size`, `prefix`, `dir`, `type`.
+
+## 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 layout. 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-raised)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-subtle)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-icon-warning)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-l)`
+- `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 prompt-variable` (after `npx sdaia-ui@latest init`), then import `{ PromptVariable }` from `@/components/ui/PromptVariable`.
+- 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/reasoning-trace.md

@@ -0,0 +1,106 @@
+# Reasoning Trace
+
+## Metadata
+- Component: Reasoning Trace (composite pattern — not a single component)
+- Slug: `reasoning-trace`
+- Category: AI
+- Install: `npx sdaia-ui@latest add reasoning-disclosure reasoning-node thinking-step`
+- Import: per primitive, e.g. `import { ReasoningNode } from '@/components/ui/ReasoningNode'`
+- Docs: https://ds.nacew.com/components/reasoning-trace
+
+> **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 run the composite install 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 `reasoning-trace` slug.** "Reasoning Trace" is a documentation pattern that composes three installable primitives — `ReasoningNode`, `ReasoningDisclosure`, and `ThinkingStep` — into an auditable chain of how an answer was reached.
+
+## Description
+A vertical, auditable chain that explains *how* an AI reached an answer: a sequence of reasoning steps, each with a lifecycle state, an optional rationale, and an expandable evidence summary. Compose `ReasoningNode` rows for the step-by-step chain, `ThinkingStep` cards for lighter "what the model is considering" notes, and a `ReasoningDisclosure` for the collapsible verified-evidence summary at the end.
+
+## Composed components
+
+| Component | Slug | Purpose |
+| --- | --- | --- |
+| `ReasoningNode` | `reasoning-node` | One step in the chain — title, rationale, and a lifecycle status pill. |
+| `ReasoningDisclosure` | `reasoning-disclosure` | Collapsible summary box of `label → value` evidence rows. |
+| `ThinkingStep` | `thinking-step` | Lightweight step card — title, optional trailing element, description. |
+
+### `ReasoningNode` props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant?` | `'neutral' \| 'brand' \| 'outline'` | `'neutral'` | Visual style of the outer card. |
+| `state?` | `'active' \| 'complete' \| 'pending'` | `'active'` | Lifecycle — sets the semantic tint (active → info, complete → success, pending → warning), status icon, and default label. |
+| `dir?` | `'ltr' \| 'rtl'` | `'ltr'` | Layout direction (mirrors for RTL). |
+| `icon?` | `ReactNode` | `<ReasoningHeadIcon />` | Leading glyph inside the 36px tile. |
+| `title?` | `ReactNode` | `'Reasoning node'` | Header title (the reasoning step). |
+| `statusLabel?` | `ReactNode` | state name | Status pill label (`Active` / `Complete` / `Pending`). |
+| `rationale?` | `ReactNode` | — | Rationale paragraph shown in the tinted summary box. |
+| `as?` | `ElementType` | `'div'` | Override the rendered root element. |
+
+### `ReasoningDisclosure` props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant?` | `'neutral' \| 'brand' \| 'outline'` | `'neutral'` | Visual style. |
+| `dir?` | `'ltr' \| 'rtl'` | `'ltr'` | Layout direction. |
+| `expanded?` | `boolean` | — | Controlled expanded state. |
+| `defaultExpanded?` | `boolean` | `false` | Initial expanded state when uncontrolled. |
+| `onExpandedChange?` | `(expanded: boolean) => void` | — | Called when the user toggles open/closed. |
+| `icon?` | `ReactNode` | `<ReasoningHeadIcon />` | Leading glyph inside the 36px tile. |
+| `title?` | `ReactNode` | `'Reasoning summary'` | Header title. |
+| `subtitle?` | `ReactNode` | `'3 verified points · auditable'` | Header subtitle. |
+| `items?` | `ReasoningDisclosureItem[]` | — | `label → value` rows shown when expanded. |
+| `expandLabel?` | `string` | `'Expand reasoning summary'` | Accessible label when collapsed. |
+| `collapseLabel?` | `string` | `'Collapse reasoning summary'` | Accessible label when expanded. |
+| `as?` | `ElementType` | `'div'` | Override the rendered root element. |
+
+`ReasoningDisclosureItem` = `{ label: ReactNode; value: ReactNode; key?: string \| number }`.
+
+### `ThinkingStep` props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant?` | `'neutral' \| 'brand' \| 'outline'` | `'neutral'` | Visual style of the card. |
+| `dir?` | `'ltr' \| 'rtl'` | `'ltr'` | Layout direction. |
+| `icon?` | `ReactNode` | `<ReasoningHeadIcon />` | Leading glyph inside the 40px tile. |
+| `title?` | `ReactNode` | `'Thinking step'` | Step title (semibold). |
+| `titleTrailing?` | `ReactNode` | — | Optional trailing element on the title row (e.g. a timestamp or badge). |
+| `description?` | `ReactNode` | — | Supporting description line. |
+| `as?` | `ElementType` | `'div'` | Override the rendered root element. |
+
+All three also accept standard `<div>` HTML attributes (`className`, `style`, `aria-*`, …) except `title`.
+
+## Options (allowed values)
+- `ReasoningNode` `state` — `'active'` \| `'complete'` \| `'pending'`
+- `variant` (all three) — `'neutral'` \| `'brand'` \| `'outline'`
+
+## Usage example
+```tsx
+import { ReasoningNode } from '@/components/ui/ReasoningNode';
+
+const NODES = [
+  { state: 'complete' as const, title: 'Current rule applies',          rationale: 'Supported by 3 primary sources with matching effective dates.' },
+  { state: 'active'   as const, title: 'Comparing policy applicability', rationale: 'Checking entity type, jurisdiction, effective date, and exceptions.' },
+  { state: 'pending'  as const, title: 'Amendment date needs confirmation', rationale: 'One source conflicts with the official publication timeline.' },
+];
+
+<div className="flex flex-col gap-spacing-md">
+  {NODES.map((node) => (
+    <ReasoningNode key={node.title} {...node} />
+  ))}
+</div>
+```
+
+## Accessibility
+- `ReasoningDisclosure` is a disclosure widget — keep the toggle keyboard-operable and provide `expandLabel` / `collapseLabel`.
+- Don't rely on the status tint alone; the `statusLabel` text carries the state meaning.
+- For full color-contrast and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- Surfaces/borders via `color-bg-raised`, `color-border-muted`, `brand-neutral-*`.
+- State tints resolve from semantic `color-*` tokens by `state`; spacing/radius via `spacing-*` / `radius-*`. Never hardcode colours.
+
+## AI usage guidance
+When generating UI:
+- Install the three primitives with the composite command above, then import each `{ ReasoningNode }` / `{ ReasoningDisclosure }` / `{ ThinkingStep }` from `@/components/ui/<Name>`. There is no `reasoning-trace` install slug.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Build the chain from `ReasoningNode` rows (one per step) and close it with a `ReasoningDisclosure` evidence summary; use `ThinkingStep` for lighter narration. Use only the documented `state` / `variant` values.
+- Pass any custom `icon` as a node from `@platformscode/icons` via `DgaIcon` — 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/source-explorer.md

@@ -0,0 +1,117 @@
+# Source Explorer
+
+## Metadata
+- Component: Source Explorer
+- Slug: `source-explorer`
+- Category: AI
+- Install: `npx sdaia-ui@latest add source-explorer`
+- Import: `import { SourceExplorer } from '@/components/ui/SourceExplorer'`
+- Installed files: `SourceExplorer.tsx`, `SourceExplorer.types.ts`, `SourceExplorer.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/source-explorer
+
+> **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 source-explorer`. It copies the source into your components folder (`components/ui/SourceExplorer/`, under `src/` when the project has one); import it as `@/components/ui/SourceExplorer`. 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 |
+| --- | --- | --- | --- |
+| `layout?` | `'side-panel' \| 'inline' \| 'modal'` | 'side-panel' | Layout — mirrors the Figma `Variant` property. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the layout. |
+| `labels?` | `Partial<SourceExplorerLabels>` | — | Overrides for every built-in visible or accessible string (see ). Unset keys keep the English defaults. The per-string props (`title`, `searchPlaceholder`, `primaryActionLabel`) win over the matching keys. |
+| `title?` | `ReactNode` | 'Sources' | Header title. Wins over `labels.title`. |
+| `headerIcon?` | `string` | globe02Stroke | Header icon (inline variant) — a `@platformscode/icons` data URL. |
+| `count?` | `number` | — | Count shown in the header pill. |
+| `verified?` | `boolean` | false | Show the header "Verified" badge. |
+| `subtitle?` | `ReactNode` | — | Header subtitle (side-panel: "8 sources used · 6 verified"; modal: description). |
+| `filters?` | `string[]` | — | Filter-tab labels (side-panel). |
+| `activeFilter?` | `string` | — | Active filter label. |
+| `onFilterChange?` | `(filter: string) => void` | — | Filter change handler. |
+| `searchPlaceholder?` | `string` | 'Search sources, types, domains…' | Search placeholder (modal). Wins over `labels.searchPlaceholder`. |
+| `sources?` | `SourceExplorerItem[]` | [] | The source rows. |
+| `moreCount?` | `number` | — | Number of extra chips collapsed into "+N more" (inline). |
+| `primaryActionLabel?` | `ReactNode` | 'View all sources' | Inline primary button label. Wins over `labels.viewAllSources`; pass `null` to hide the button. |
+| `onPrimaryAction?` | `MouseEventHandler<HTMLButtonElement>` | — | Inline primary button handler. |
+| `detail?` | `SourceExplorerDetail` | — | Featured detail panel (side-panel / modal). |
+| `metadata?` | `SourceExplorerMetaRow[]` | — | Metadata rows (side-panel / modal). |
+| `footerNote?` | `ReactNode` | — | Footer note (modal: "4 of 8 shown"). |
+| `searchValue?` | `string` | — | Search field value (modal). When `onSearchChange` is set the field is editable. |
+| `onSearchChange?` | `(value: string) => void` | — | Search field change handler (modal) — makes the search input live. |
+| `onSelectSource?` | `(item: SourceExplorerItem) => void` | — | Select a source — makes each row clickable (and the row "view" action). |
+| `onCopySource?` | `(item: SourceExplorerItem) => void` | — | Row "copy" action. |
+| `rowMenu?` | `SourceMenuAction[]` | — | Row overflow-menu actions. When provided, the row "⋮" button renders the DS Dropdown menu with these items instead of the single `onMoreSource` action. |
+| `onMoreSource?` | `(item: SourceExplorerItem) => void` | — | Row "more" action — used when `rowMenu` is not provided. |
+| `onOpenSource?` | `MouseEventHandler<HTMLButtonElement>` | — | "Open source" action (detail panel + modal footer). |
+| `onCopyCitation?` | `MouseEventHandler<HTMLButtonElement>` | — | "Copy citation" / "Copy citations" action (detail panel + modal footer). |
+| `onViewMetadata?` | `MouseEventHandler<HTMLButtonElement>` | — | "View metadata" action (detail panel). |
+| `onSort?` | `MouseEventHandler<HTMLButtonElement>` | — | Header sort icon button. |
+| `onFilter?` | `MouseEventHandler<HTMLButtonElement>` | — | Header filter icon button. |
+| `onClose?` | `MouseEventHandler<HTMLButtonElement>` | — | Close handler — renders the header close (×) button on side-panel / modal. |
+| `as?` | `ElementType` | 'div' | Override the rendered root element. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`, `title`, `style`.
+
+## Options (allowed values)
+- `layout`: `'side-panel'` \| `'inline'` \| `'modal'` — Figma `Variant` property — the three layouts (set with the `layout` prop).
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the layout.
+
+## Deprecated props
+Do not use in new code:
+- `variant` — Root surface style (`neutral` / `brand` / `outline`) — mirrors the Figma
+`Style` property.
+- `style` — Root surface style.
+
+## 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-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-strong)`
+- `var(--ds-color-bg-success-subtle)`
+- `var(--ds-color-bg-warning-strong)`
+- `var(--ds-color-bg-warning-subtle)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-default-strong)`
+- `var(--ds-color-border-subtle)`
+- `var(--ds-color-form-field-border-default)`
+- `var(--ds-color-icon-brand)`
+- `var(--ds-color-icon-danger)`
+- `var(--ds-color-icon-info)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-icon-success)`
+- `var(--ds-color-icon-warning)`
+- `var(--ds-color-primitive-radius-radius-12)`
+- `var(--ds-color-primitive-radius-radius-16)`
+- `var(--ds-color-primitive-radius-radius-2)`
+- `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-brand)`
+- `var(--ds-color-text-danger)`
+- `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-color-text-warning)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- …and 7 more
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add source-explorer` (after `npx sdaia-ui@latest init`), then import `{ SourceExplorer }` from `@/components/ui/SourceExplorer`.
+- 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/source-group.md

@@ -0,0 +1,59 @@
+# Source Group
+
+## Metadata
+- Component: Source Group
+- Slug: `source-group`
+- Category: AI
+- Install: `npx sdaia-ui@latest add source-group`
+- Import: `import { SourceGroup } from '@/components/ui/SourceGroup'`
+- Installed files: `SourceGroup.tsx`, `SourceGroup.types.ts`, `SourceGroup.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/sourcegroup
+
+> **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 source-group`. It copies the source into your components folder (`components/ui/SourceGroup/`, under `src/` when the project has one); import it as `@/components/ui/SourceGroup`. 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 group container. - `brand`   — raised surface, default border (default) - `neutral` — subtle surface, subtle border - `outline` — transparent surface, default border |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the header and citation row. |
+| `title` | `ReactNode` | — | Header title (e.g. `Grounding Context Logs (3 Citations)`). |
+| `icon?` | `string` | databaseStroke | Header icon — a `@platformscode/icons` data URL rendered through `DgaIcon`. |
+| `showIcon?` | `boolean` | true | Show the leading header icon. |
+| `verification?` | `ReactNode` | — | Verification badge label (e.g. `Strict Verification`). The badge renders only when this is set — there is no built-in default copy. |
+| `showVerification?` | `boolean` | true | Show the trailing verification badge (when `verification` is set). |
+| `items` | `SourceGroupItem[]` | — | Citation rows rendered in the group body. |
+| `autoNumber?` | `boolean` | true | Auto-number items 1..n when an item omits its own `number`. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`.
+
+## Options (allowed values)
+- `variant`: `'brand'` \| `'neutral'` \| `'outline'` — Visual style of the group container — mirrors the Figma `Style` property.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. `rtl` mirrors the header and citation row.
+
+## 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-bg-default)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-default-strong)`
+- `var(--ds-color-border-subtle)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-text-default)`
+- `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 source-group` (after `npx sdaia-ui@latest init`), then import `{ SourceGroup }` from `@/components/ui/SourceGroup`.
+- 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/source-reference.md

@@ -0,0 +1,70 @@
+# Source Reference
+
+## Metadata
+- Component: Source Reference
+- Slug: `source-reference`
+- Category: AI
+- Install: `npx sdaia-ui@latest add source-reference`
+- Import: `import { SourceReference } from '@/components/ui/SourceReference'`
+- Installed files: `SourceReference.tsx`, `SourceReference.types.ts`, `SourceReference.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/source-reference
+
+> **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 source-reference`. It copies the source into your components folder (`components/ui/SourceReference/`, under `src/` when the project has one); import it as `@/components/ui/SourceReference`. 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 source card. - `brand`   — raised surface + transparent (subtle) leading button (default) - `neutral` — subtle surface + solid black leading button - `outline` — transparent surface + outlined leading button |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. `rtl` mirrors the layout. |
+| `title` | `ReactNode` | — | Source title — the linked document/page name. |
+| `url?` | `ReactNode` | — | Source URL shown under the title. |
+| `showUrl?` | `boolean` | true | Show the URL line. |
+| `icon?` | `string` | tick02Stroke | Leading icon-only button glyph — a `@platformscode/icons` data URL. |
+| `showButton?` | `boolean` | true | Show the leading icon-only button. |
+| `onButtonClick?` | `MouseEventHandler<HTMLButtonElement>` | — | Click handler for the leading icon-only button. |
+| `buttonLabel?` | `string` | 'Cited source' | Accessible label for the leading icon-only button. Wins over `labels.button`. |
+| `selectable?` | `boolean` | true | Whether the leading button is a selection toggle (filled when selected, outlined when not). On by default so a source can be selected/unselected. Set `false` for a purely decorative "cited" indicator styled by `variant`. |
+| `selected?` | `boolean` | — | Controlled selected state of the leading toggle. When set, the component is controlled — drive it with `onSelectedChange`. Sources can be selected and unselected independently. |
+| `defaultSelected?` | `boolean` | false | Uncontrolled initial selected state (ignored when `selected` is set). |
+| `onSelectedChange?` | `(selected: boolean) => void` | — | Fired with the next value whenever the user toggles the leading selection control. |
+| `openIcon?` | `string` | linkSquare02Stroke | Trailing "open" affordance glyph — a `@platformscode/icons` data URL. |
+| `showOpen?` | `boolean` | true | Show the trailing "open" affordance. |
+| `href?` | `string` | — | When set, the "open" affordance becomes a link to the source. |
+| `target?` | `HTMLAttributeAnchorTarget` | '_blank' | Anchor target when `href` is set. |
+| `rel?` | `string` | 'noopener noreferrer' for `_blank` | Anchor rel when `href` is set. |
+| `onOpen?` | `MouseEventHandler<HTMLAnchorElement \| HTMLButtonElement>` | — | Click handler for the "open" affordance (used when there is no `href`). |
+| `openLabel?` | `string` | 'Open source' | Accessible label for the "open" affordance. Wins over `labels.open`. |
+| `labels?` | `Partial<SourceReferenceLabels>` | — | Overrides for every built-in accessible string (see ). Unset keys keep the English defaults. |
+| `as?` | `ElementType` | 'div' | Override the rendered root element. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `children`.
+
+## 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 layout.
+
+## 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-raised)`
+- `var(--ds-color-bg-subtle)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-subtle)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-l)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add source-reference` (after `npx sdaia-ui@latest init`), then import `{ SourceReference }` from `@/components/ui/SourceReference`.
+- 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.