@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/chat/.nav-link-anchor-via-runtime.md

@@ -1,40 +1,51 @@
-<!-- source-hash: 7bb7ab52d16e8c26a26fa5ab1feba948 -->
-A client-side `<a>` wrapper used within the chat tree to handle link navigation by reading the active `ChatRuntime` and routing clicks through the shared `handleChatNavClick` utility.
+<!-- source-hash: 83b227b8e0df5ad60d3358b3d5e15409 -->
+A client-side `<a>` wrapper that routes chat-rendered links (markdown bodies, source chips, inline references) through the active `ChatRuntime`, applying consistent new-tab logic and panel-close behavior.
 
 ## Key Components
 
 ### `NavLinkAnchorViaRuntimeProps`
+
 | Prop | Type | Description |
-|------|------|-------------|
-| `href` | `string` | Raw href to resolve |
-| `path` | `string \| null` | Optional internal path hint |
-| `targetPlatform` | `string \| null` | Platform target override |
+|---|---|---|
+| `href` | `string` | Raw link URL |
+| `path` | `string \| null` | Optional internal path override |
+| `targetPlatform` | `string \| null` | Platform hint for new-tab resolution |
 | `className` | `string` | Optional CSS class |
-| `children` | `ReactNode` | Optional child content |
+| `children` | `ReactNode` | Link content (optional — empty anchors are valid) |
 
 ### `NavLinkAnchorViaRuntime`
-The main exported component. Orchestrates four responsibilities:
-1. **Resolves `href`** via `resolveHrefForRuntime` (runtime-aware URL normalization)
-2. **Decides new-tab vs. same-tab** via `computeIsNewTab` (embed-mode short-circuit → `runtime.navigation.decideNewTab` → lib fallback)
-3. **Sets `target`/`rel`** attributes via `newTabAnchorAttrs`
-4. **Closes the chat panel** on same-tab navigation via `ChatPanelContext.closeChat`
 
-> **⚠️ Chat-tree only:** Uses `useRequiredChatRuntime`, which **throws** when mounted outside a `<ChatRuntimeContext.Provider>`. This is intentional — no silent fallback. For surfaces outside the chat tree (header chrome, marketing pages), use the hub's `useNavLink`-based anchor instead.
+Primary export. Resolves the final href and new-tab decision at runtime, then delegates click handling to shared utilities:
+
+- **`resolveHrefForRuntime`** — adapts the raw `href` for the active runtime context
+- **`computeIsNewTab`** — applies embed-mode short-circuit → `runtime.navigation.decideNewTab` → lib fallback chain
+- **`newTabAnchorAttrs`** — produces correct `target` / `rel` attributes
+- **`handleChatNavClick`** — unified click handler shared with source chips and inline cards
+- **`useChatPanel`** — closes the chat panel on same-tab navigation; leaves it open for new-tab clicks
+
+> **Chat-only contract:** Uses `useRequiredChatRuntime`, which **throws** if mounted outside a `<ChatRuntimeContext.Provider>`. This is intentional — silent fallback when the runtime is absent is never acceptable.
 
 ## Usage Example
 
 ```typescript
-// Used in markdown-rendered chat bodies or source-chip drill-ins
-<NavLinkAnchorViaRuntime
-  href="https://example.com/docs/setup"
-  path="/docs/setup"
-  targetPlatform="web"
-  className="chat-link"
->
-  View Setup Guide
-</NavLinkAnchorViaRuntime>
+// Inside a chat markdown renderer or source chip
+import { NavLinkAnchorViaRuntime } from './nav-link-anchor-via-runtime'
+
+function ChatMarkdownLink({ href, children }) {
+  return (
+    <NavLinkAnchorViaRuntime
+      href={href}
+      targetPlatform="web"
+      className="chat-link"
+    >
+      {children}
+    </NavLinkAnchorViaRuntime>
+  )
+}
 ```
 
-At runtime:
-- **Same-tab click** → navigates and calls `panel.closeChat()` to dismiss the chat panel
-- **New-tab click** → opens in a new tab, leaving the chat panel open
+> For links **outside** the chat tree (header chrome, marketing pages), use the hub's own `useNavLink`-based anchor instead — this component will throw in those contexts by design.
+
+## Source
+
+[`nav-link-anchor-via-runtime.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/nav-link-anchor-via-runtime.tsx)

package/src/components/chat/.quick-action-chip.md

@@ -0,0 +1,60 @@
+<!-- source-hash: aaf3eec1cf53779f0b01f4e804331724 -->
+Renders a compact, themed quick-action chip button with icon resolution, loading skeleton, and support for agent-branded accents, lozenges, and selection states.
+
+## Key Components
+
+### Types & Utilities
+
+- **`QuickActionAccent`** — Union type for icon tint: `'pink'` | `'cyan'` | any CSS color string
+- **`QuickActionIconSpec`** — Extends `EntityIconValue` with `accent` and `size`; declarative icon descriptor resolved by `<EntityIcon>`
+- **`QuickActionThemeSpec`** — Caller-supplied chip theme with `accent` and optional `lozenge`
+- **`QuickActionChipLozenge`** — Leading category/status affix rendered inside the chip label
+- **`getAgentAccent(slug)`** — Maps built-in agent slugs (`'fae'`, `'mingo'`) to brand accent tokens
+- **`accentFromIdentityIcon(icon)`** — Extracts `icon_props.color` from an admin-configured identity
+- **`isQuickActionIconSpec(icon)`** — Type guard distinguishing a spec object from a `ReactNode`
+- **`renderQuickActionIcon(icon)`** — Resolves a chip `icon` prop to a renderable node via `<EntityIcon>`
+
+### Components
+
+- **`QuickActionChipButton`** — Primary chip component with full theming, icon, lozenge, selection, and interactivity support
+- **`QuickActionChipSkeleton`** — Loading placeholder that mirrors the real chip's exact dimensions using pulse bars
+
+## Usage Example
+
+```typescript
+import {
+  QuickActionChipButton,
+  QuickActionChipSkeleton,
+  getAgentAccent,
+  accentFromIdentityIcon,
+} from './quick-action-chip'
+
+// Basic chip with a built-in agent accent
+<QuickActionChipButton
+  label="Summarize Ticket"
+  icon={{ name: 'mingo', size: 16 }}
+  theme={{ accent: getAgentAccent('mingo') ?? 'cyan' }}
+  onSelect={() => console.log('selected')}
+/>
+
+// Chip with admin-configured icon color and a category lozenge
+<QuickActionChipButton
+  label="Patch Servers"
+  icon={{ name: 'server', accent: accentFromIdentityIcon(agentRow.icon) }}
+  lozenge={{ label: 'SEC', className: 'text-ods-warning' }}
+  selected
+  selectedAccent="cyan"
+  size="large"
+/>
+
+// Loading state — matches loaded chip dimensions 1:1
+<QuickActionChipSkeleton labelCh={12} icon lozenge size="large" />
+```
+
+## Notes
+
+- Theme accent fills only when the icon spec carries no `accent` of its own — per-action config always wins.
+- Named brand tokens (`pink`, `cyan`) apply a `text-ods-flamingo-*` class; arbitrary CSS colors are passed as an explicit `color` prop to `<EntityIcon>`.
+- Set `interactive={false}` for decorative chips (marquee strips, table cells) to suppress focus and keyboard handling.
+
+**Source:** [`quick-action-chip.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/quick-action-chip.tsx)

package/src/components/chat/.quick-action-marquee.md

@@ -0,0 +1,53 @@
+<!-- source-hash: 5a021d0d9bef82d15123c47324bd44ae -->
+Single-row horizontally-scrolling strip of quick-action chips, a thin preset wrapper around `QuickActionWall` that enforces a `flex-nowrap` single-axis layout with optional endless marquee animation.
+
+## Key Components
+
+### `QuickActionMarquee` (component)
+
+The primary export. Converts `QuickActionMarqueeItem[]` into `QuickActionChip[]` via `useMemo` and delegates rendering to `QuickActionWall` with `axis="x"` and `flex-nowrap` content layout.
+
+**Props (`QuickActionMarqueeProps`):**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `ReadonlyArray<QuickActionMarqueeItem>` | — | Chip data |
+| `mode` | `'animated' \| 'plain'` | `'animated'` | Endless scroll or static row |
+| `direction` | `'left' \| 'right'` | `'left'` | Scroll travel direction |
+| `speed` | `number` | `40` | Scroll speed in px/s |
+| `pauseOnHover` | `boolean` | `true` | Pause scroll on hover |
+| `onSelect` | `(item) => void` | — | Makes chips interactive buttons; omit for decorative tags |
+| `minChips` | `number` | `12` | Minimum chip count for loop overflow (~2600px+) |
+| `sync` | `MarqueeSyncController` | — | Pixel-locks sibling marquee strips under one position driver |
+| `className` | `string` | — | Root element class override |
+
+### `QuickActionMarqueeItem` (interface)
+
+Data shape for each chip: `id` (stable key), `label`, and optional `icon` (React node or `QuickActionIconSpec`).
+
+## Usage Example
+
+```typescript
+import { QuickActionMarquee } from './quick-action-marquee'
+
+const SUGGESTIONS: QuickActionMarqueeItem[] = [
+  { id: 'restart', label: 'Restart service', icon: <RefreshIcon /> },
+  { id: 'logs',    label: 'View logs' },
+  { id: 'deploy',  label: 'Deploy patch' },
+]
+
+// Animated, interactive strip
+<QuickActionMarquee
+  items={SUGGESTIONS}
+  speed={50}
+  onSelect={(item) => console.log('Selected:', item.label)}
+/>
+
+// Static decorative row (no motion, no cloning)
+<QuickActionMarquee
+  items={SUGGESTIONS}
+  mode="plain"
+/>
+```
+
+> **Motion safety:** the underlying `QuickActionWall` engine always respects `prefers-reduced-motion`. In `plain` mode, `minChips` padding is disabled since no looping occurs.

package/src/components/chat/.quick-action-wall.md

@@ -0,0 +1,68 @@
+<!-- source-hash: 604eb79e10ef142d8c69457a1482cc62 -->
+Animated, multi-row "brick wall" of quick-action chips built on `MarqueeWall`, supporting skeleton loading, adaptive padding, interleaved chip streams, and per-agent row caps.
+
+## Key Components
+
+### Exports
+
+| Export | Type | Description |
+|---|---|---|
+| `QuickActionWall` | Component | Primary wall component rendering themed chips on a scrolling/static marquee |
+| `QuickActionWallProps` | Interface | Full prop surface for the wall |
+| `WALL_SKELETON_LABEL_CH` | `number[]` | Cycled skeleton chip widths (in `ch`) shared across surfaces |
+| `interleave<T>` | Function | Deterministic index-alternating merge of two chip arrays |
+
+### Internal Constants
+
+| Constant | Purpose |
+|---|---|
+| `DEFAULT_MIN_CHIPS_PER_ROW` | Fallback pad target (14 chips) before geometry is measured |
+| `ADAPTIVE_PAD_MARGIN` | Extra repeat buffer added after measured overflow count |
+| `AGENT_MAX_ROWS` | Brick-stack cap (2 rows) for `fae`/`mingo` agent walls |
+
+## Usage Example
+
+```typescript
+import { QuickActionWall, interleave } from './quick-action-wall'
+
+// Basic animated wall
+<QuickActionWall
+  chips={myChips}
+  theme={{ accent: '#6366f1' }}
+  mode="animated"
+  rows={3}
+  agentSlug="mingo"
+  fade={['left', 'right']}
+  fadeColor="#ffffff"
+  pauseOnHover
+/>
+
+// Interleaved IT + SEC chip stream (deck slide 3 / mixed wall)
+const blended = interleave(itChips, secChips)
+<QuickActionWall
+  chips={blended}
+  lozenges
+  rows={2}
+  speed={50}
+  dragScroll
+/>
+
+// Skeleton loading state
+<QuickActionWall
+  chips={[]}
+  loading
+  skeletonCount={24}
+  rows={2}
+/>
+```
+
+## Behavior Notes
+
+- **Adaptive padding**: measures container + narrowest chip via `ResizeObserver`; pads rows to `ceil(width / chipWidth) + 2` so the marquee loop always engages
+- **Brick mode**: `rows` splits chips evenly across stacked single-row marquees; each row pads independently
+- **Agent cap**: `agentSlug="fae"` or `"mingo"` clamps brick rows to 2 regardless of `rows`
+- **Accessibility**: clone copies are `aria-hidden` with focus suppressed; interactive chips remain clickable in clones
+
+## Source
+
+[`quick-action-wall.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/quick-action-wall.tsx)

package/src/components/chat/.remark-mention-chips.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 74dbdc2ffb35df002f0f95977836c9b4 -->
+Remark plugin that transforms inline `@marker:id` mention tokens in markdown text nodes into synthetic `link` mdast nodes using the `mention://` scheme, enabling downstream rendering as interactive chip components.
+
+## Key Components
+
+### `MENTION_REGEX`
+Compiled regex matching `@<marker>:<id>` tokens with boundary detection. Captures an optional leading boundary character (`lead`), the marker (lowercase letters), and the id (alphanumeric plus `_.+/=-`, but not trailing `.` or `-`).
+
+### `remarkMentionChips`
+A [unified](https://github.com/unifiedjs/unified) `Plugin<[], Root>` that visits every `text` leaf in the mdast tree. For each match it:
+1. Emits any preceding text as a `Text` node
+2. Replaces the token with a `Link` node (`url: mention://<marker>:<id>`, children: raw token as fallback text)
+3. Returns `[SKIP, index + parts.length]` to advance past the injected nodes without re-visiting them
+
+## Usage Example
+
+```typescript
+import { unified } from 'unified'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import { remarkMentionChips } from './remark-mention-chips'
+
+const processor = unified()
+  .use(remarkParse)
+  .use(remarkMentionChips)
+  .use(remarkRehype)
+
+// Input markdown:  "Check @device:64f0a1 and @kb:5 for details."
+// Produces a link node: { type: 'link', url: 'mention://device:64f0a1', ... }
+// The downstream <a> override detects the mention:// scheme and renders a chip.
+const file = await processor.process('Check @device:64f0a1 and @kb:5 for details.')
+```
+
+## Notes
+
+- Handles boundary safety: `user@host:1234` is **not** matched because `@` is preceded by a word character
+- Parenthesised mentions like `(@device:64f0a1)` work correctly — the `(` is re-emitted as text
+- Unresolved mentions (no matching `contextItems` entry) fall back to the raw `@marker:id` literal
+- Companion to `remark-card-links`, which handles assistant-side `[card://type:id]` markers
+
+**Source:** [`remark-mention-chips.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/remark-mention-chips.ts)

package/src/components/chat/.slash-command-suggestions.md

@@ -1,47 +1,41 @@
-<!-- source-hash: b3b4c24e822f3ccb1b39897c02cee900 -->
-Renders an accessible autocomplete dropdown for slash commands, mapping each command to a `MingoOnboardingCard` row with unified icon resolution, keyboard/mouse highlight sync, and optional inline action buttons.
+<!-- source-hash: d1a2b6cd443ffee1f14fb1fbefe456e3 -->
+Renders an autocomplete dropdown for slash-command suggestions, displaying each command as a styled card with icon, label, description, and optional action buttons.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `SlashCommandSuggestions` | `React.FC` | Main dropdown component; returns `null` when `commands` is empty |
-| `SlashCommandSuggestionsProps` | `interface` | Props contract covering command list, highlight state, and action callbacks |
+**`SlashCommandSuggestions`** — Primary export. Renders a `role="menu"` container populated with `MingoOnboardingCard` rows, one per command. Returns `null` when `commands` is empty.
 
-**Icon resolution priority (highest → lowest):**
-1. `cmd.iconName` → `resolveOnboardingIcon` (v2 registry)
-2. `cmd.primarySourceId` → consumer `resolveSourceIcon` (legacy fallback)
-3. `FileIcon` (default inside `resolveOnboardingIcon`)
+**`SlashCommandSuggestionsProps`** — Interface defining:
+- `commands` — Filtered `SlashCommandSummary[]` to display
+- `highlightedIdx` — Keyboard/hover cursor position
+- `onHover` / `onSelect` — Sync callbacks for mouse and keyboard navigation
+- `onAction` — Optional handler for inline action buttons (browse, search, find, etc.)
+- `resolveSourceIcon` — Legacy fallback icon resolver for commands without `iconName`
+- `className` — Positioning override (e.g. `absolute bottom-full`)
+
+**Icon resolution priority:**
+1. `cmd.iconName` → `resolveIcon` (v2 registry, production path)
+2. `cmd.primarySourceId` → `resolveSourceIcon` (legacy fallback)
+3. `FileIcon` (default inside `resolveIcon`)
+
+**Display label priority:** `cmd.label` → `legacyMeta.label` → `cmd.id`
 
 ## Usage Example
 
 ```typescript
-import { SlashCommandSuggestions } from './slash-command-suggestions'
-import type { SlashCommandSummary } from './types'
-
-function ChatInput() {
-  const [commands, setCommands] = useState<SlashCommandSummary[]>([])
-  const [highlightedIdx, setHighlightedIdx] = useState(0)
-
-  return (
-    <div className="relative">
-      <SlashCommandSuggestions
-        commands={commands}
-        highlightedIdx={highlightedIdx}
-        onHover={(idx) => setHighlightedIdx(idx)}
-        onSelect={(cmd) => setValue(`/${cmd.id} `)}
-        onAction={(cmd, actionId) => dispatch({ cmd, actionId })}
-        className="absolute bottom-full"
-      />
-      <input ... />
-    </div>
-  )
-}
+<SlashCommandSuggestions
+  commands={filteredCommands}
+  highlightedIdx={activeIdx}
+  onHover={(idx) => setActiveIdx(idx)}
+  onSelect={(cmd) => prefillInput(`/${cmd.id} `)}
+  onAction={(cmd, actionId) => dispatch({ cmd, actionId })}
+  resolveSourceIcon={(sourceId) => legacyIconMap[sourceId]}
+  className="absolute bottom-full"
+/>
 ```
 
-## Accessibility Notes
+## Notes
 
-- Outer container: `role="menu"` with `aria-label`
-- Each row: `role="menuitem"` + `aria-current` on the highlighted item
-- `Enter`/`Space` activate the focused row; arrow-key navigation is delegated to the parent input
-- Action buttons call `stopPropagation` to prevent double-firing the row's `onSelect`
+- Uses `role="menu"` with `role="menuitem"` rows (not `listbox`/`option`) to allow interactive action buttons inside each row per ARIA 1.2
+- `aria-current` marks the highlighted row; action button clicks call `stopPropagation` to prevent double-firing `onSelect`
+- Mirrors the empty-state onboarding card design via shared `MingoOnboardingCard` component

package/src/components/chat/.source-action-button.md

@@ -1,48 +1,51 @@
-<!-- source-hash: 770809a15a2a56eec700f22e576bdc99 -->
-Unified "Ask / Display" action button rendered across source chips, inline cards, and search-result list rows. Replaces three divergent ad-hoc implementations with a single `Button`-backed primitive that keeps DOM shape, accessibility attributes, and hover behavior in one place.
+<!-- source-hash: 2b46a61a06e35d0d30a9cba0a4b9531a -->
+Renders a unified "Ask" or "Display" action button for chat-adjacent surfaces (source chips, inline cards, search result rows), replacing three divergent implementations with a single density-aware primitive.
 
 ## Key Components
 
-### `SourceActionButton`
-The sole export. Returns `null` when either `chatRef` or `onDiscuss` is absent, making the guard declarative at the call site.
+### Types
 
-### `SourceActionDensity`
-Union type `'inline' | 'card' | 'list-row'` that selects the visual variant via the `DENSITY_STYLES` map.
+- **`SourceActionDensity`** — Union type `'inline' | 'card' | 'list-row'` controlling visual layout variant
+- **`SourceActionButtonProps`** — Component props including `chatRef`, `onDiscuss`, `density`, `label`, and `className`
 
-### `DENSITY_STYLES`
-Internal record keyed by `SourceActionDensity`. Each entry carries `size`, `showLabel`, `iconSize`, and `className`. Adding a fourth surface requires one new entry here — no changes to the render path.
+### Constants
 
-### Icon selection
-Label-driven: `'Display'` renders `FileText` (verbatim-content semantics); any other label renders `MessageSquare` (conversational semantics).
+- **`DENSITY_STYLES`** — Static map from `SourceActionDensity` to per-variant sizing, icon dimensions, label visibility, and Tailwind class strings. Adding a new surface requires only a new entry here.
+
+### Component
+
+- **`SourceActionButton`** — Returns `null` when `chatRef` or `onDiscuss` is absent (safe to render unconditionally). Selects `MessageSquare` or `FileText` icon based on whether `label` is `'Display'`. Delegates to the UI-Kit `<Button variant="transparent">` for consistent DOM structure and accessibility.
 
 ## Usage Example
 
 ```typescript
-// Inline chip — icon only, small footprint
+import { SourceActionButton } from './source-action-button'
+import type { ChatRef } from './chat-ref.types'
+
+const ref: ChatRef = { id: 'doc-42', title: 'Q4 Report' }
+
+// Compact icon-only button beside a source chip
 <SourceActionButton
-  chatRef={{ id: 'row-42', title: 'Ticket #42' }}
-  onDiscuss={(ref) => openChat(ref)}
+  chatRef={ref}
+  onDiscuss={(r) => openChat(r)}
   density="inline"
 />
 
-// Card — shows "Ask" label beside icon
+// Labelled button inside an inline card
 <SourceActionButton
-  chatRef={row}
-  onDiscuss={handleDiscuss}
+  chatRef={ref}
+  onDiscuss={(r) => openChat(r)}
   density="card"
+  label="Ask"
 />
 
-// List row with custom label
+// Labelled button with display semantics in a list row
 <SourceActionButton
-  chatRef={row}
-  onDiscuss={handleDiscuss}
+  chatRef={ref}
+  onDiscuss={(r) => openViewer(r)}
   density="list-row"
   label="Display"
 />
+```
 
-// Hidden — chatRef is null, renders nothing
-<SourceActionButton
-  chatRef={null}
-  onDiscuss={handleDiscuss}
-/>
-```
+**Visibility rules:** the component renders `null` (no DOM node) when either `chatRef` or `onDiscuss` is `undefined`/`null`, so call sites need no conditional wrapping.

package/src/components/chat/.tool-call-blocks.md

@@ -1,45 +1,33 @@
-<!-- source-hash: c2806ae4c954c7e6f9d20b3fe6ddb5f6 -->
-Reusable React components for rendering tool call arguments and results in the Flamingo/OpenFrame AI chat interface, handling both inline and block display formats.
+<!-- source-hash: 33bf00d3b65113d65665605ce5e4d951 -->
+Reusable React components for rendering tool call arguments, results, and command bodies within AI message interfaces (Mingo AI / Fae client cards).
 
 ## Key Components
 
-### `ArgRow`
-Renders a single tool argument as either an inline `key: value` pair (for short values) or a labeled scrollable `<pre>` block (for long JSON, scripts, or multiline content). Shared across `ApprovalBatchMessage` and `ToolExecutionDisplay` for consistent rendering.
+| Export | Props | Description |
+|---|---|---|
+| `ArgRow` | `argKey: string`, `value: unknown` | Renders a single tool argument as either an inline `key: value` pair or a labeled scrollable `<pre>` block for long/complex values |
+| `ResultBlock` | `result: string \| undefined \| null`, `className?: string` | Renders tool execution output inline for short single-line results or as a scrollable code block for JSON/multiline output |
+| `CommandBlock` | `command: string`, `className?: string` | Renders a raw command or script body as an unlabeled code block; used by Fae client cards in expanded state |
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `argKey` | `string` | The argument name/key |
-| `value` | `unknown` | The argument value (any type) |
+All three components share a common `CODE_PRE_CLASS` constant that applies ODS design tokens (`text-code`, `bg-ods-bg`, `border-ods-border`) for consistent monospace display with a 64-line max-height scroll container.
 
-### `ResultBlock`
-Renders a tool execution result as either inline text or a scrollable code block, depending on length and content type. Returns `null` when result is empty.
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `result` | `string \| undefined \| null` | The tool execution output |
-| `className` | `string?` | Optional additional CSS classes |
+Rendering mode (`"inline"` vs block) is determined by `formatToolArgValue` and `formatToolResult` helpers from `./utils/tool-call-helpers`.
 
 ## Usage Example
 
 ```typescript
-import { ArgRow, ResultBlock } from "./tool-call-blocks"
+import { ArgRow, ResultBlock, CommandBlock } from "./tool-call-blocks"
 
-// Rendering tool arguments
-<ArgRow argKey="script" value={`console.log("hello")`} />
-<ArgRow argKey="timeout" value={30} />
+// Short string → inline; long JSON → scrollable <pre>
+<ArgRow argKey="query" value={{ filter: "status=open", limit: 50 }} />
 
-// Rendering tool result
+// Multiline output → scrollable block
 <ResultBlock result={toolOutput} className="mt-2" />
-```
 
-## Display Logic
+// Expanded Fae card — show raw command in code block body
+<CommandBlock command="Get-Service | Where-Object { $_.Status -eq 'Running' }" />
+```
 
-Both components delegate format decisions to `formatToolArgValue` and `formatToolResult` helpers, which return a `kind` of `"inline"` or `"block"`:
+## Source
 
-```mermaid
-graph TD
-    A["Raw Value/Result"] --> B["Format Helper"]
-    B --> C{"kind?"}
-    C -->|inline| D["Inline span"]
-    C -->|block| E["Scrollable pre/code"]
-```
+[`tool-call-blocks.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/tool-call-blocks.tsx)

package/src/components/chat/.tool-execution-display.md

@@ -1,53 +1,48 @@
-<!-- source-hash: 51e80592b1ae4e56c89af6c06ba53a04 -->
-Renders a collapsible card UI for displaying AI tool call execution state — including tool arguments, execution status (running/success/failure), and result output.
+<!-- source-hash: 6622fc68fe4ae722eeab2de7945c1691 -->
+Renders an AI tool execution status card showing tool name, arguments, status icon, and collapsible result output — with separate display modes for admin users (expandable accordion with full details) and end-client Fae users (static, non-expandable summary row).
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `ToolExecutionDisplay` | `forwardRef<HTMLDivElement>` | Main component displaying tool call lifecycle in a collapsible card |
+- **`ToolExecutionDisplay`** — Primary `forwardRef` component that renders the tool execution card
+- **`useCollapsible`** — Hook managing animated expand/collapse of the detail body panel
+- **`ArgRow`** — Renders individual argument key/value pairs in the expanded body
+- **`ResultBlock`** — Displays the tool's result string when execution is complete
+- **`renderStatusIcon`** — Internal helper returning `DotsLoaderIcon` (executing), `CheckCircleIcon` (success), or `XmarkCircleIcon` (failure)
 
-### Internal Helpers
+## Props (`ToolExecutionDisplayProps`)
 
-- **`renderStatusIcon`** — Returns `DotsLoaderIcon` (executing), `CheckCircleIcon` (success), or `XmarkCircleIcon` (failure) based on message state
-- **`argEntries`** — Filters `message.parameters` to exclude `COMMAND_BODY_KEYS`, nulls, undefined, and empty strings
-- **`previewText`** — Memoized title derived from `getToolCallTitle` using tool args, title, and function name
-- **`useCollapsible`** — Hook providing animated expand/collapse container styles
-- **`hasBody`** — Guards rendering of the collapsible body section
+| Prop | Description |
+|---|---|
+| `message` | Tool execution message with `type`, `parameters`, `result`, `success`, `toolTitle`, `toolExplanation` |
+| `assistantType` | `"mingo"` or `"fae"` — controls tool icon visibility |
+| `variant` | `"admin"` (default) or `"client"` — controls expandability and visible fields |
+| `className` | Additional CSS classes |
 
-### Props (`ToolExecutionDisplayProps`)
+## Variant Behaviour
 
-| Prop | Description |
-|------|-------------|
-| `message` | Tool execution message with `type`, `parameters`, `result`, `success`, `toolTitle`, `toolFunction`, `integratedToolType` |
-| `className` | Optional CSS class override |
+- **`variant="admin"`** — Expandable accordion showing tool icon, concise `toolTitle`, all args (command body first), and result output
+- **`variant="client"`** — Static row showing only `toolExplanation` and status icon; command body, raw args, and result are hidden
 
 ## Usage Example
 
 ```typescript
 import { ToolExecutionDisplay } from "./tool-execution-display"
 
-// Executing state
-<ToolExecutionDisplay
-  message={{
-    type: "EXECUTING_TOOL",
-    toolTitle: "Query Database",
-    toolFunction: "run_query",
-    parameters: { query: "SELECT * FROM tickets LIMIT 10" },
-    integratedToolType: "OPENFRAME",
-  }}
-/>
-
-// Completed with result
 <ToolExecutionDisplay
+  assistantType="mingo"
+  variant="admin"
   message={{
     type: "EXECUTED_TOOL",
-    toolTitle: "Query Database",
-    toolFunction: "run_query",
-    parameters: { query: "SELECT * FROM tickets LIMIT 10" },
-    result: "Returned 10 rows",
+    toolTitle: "Run PowerShell Script",
+    toolExplanation: "Restarting the print spooler service",
+    integratedToolType: "POWERSHELL",
+    parameters: { script: "Restart-Service Spooler" },
+    result: "Service restarted successfully.",
     success: true,
-    integratedToolType: "OPENFRAME",
   }}
 />
-```
+```
+
+## Source
+
+[`tool-execution-display.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/tool-execution-display.tsx)