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

package/src/components/chat/.chat-ticket-list.md

@@ -1,39 +1,54 @@
-<!-- source-hash: 6e8a04ae19bb53e1b3779c86e3a511c1 -->
-Scrollable list component that renders a collection of `ChatTicketItem` cards with dynamic edge-fade masking based on scroll position.
+<!-- source-hash: 9b003d4a0319d2d06cb32bc530f883ab -->
+Scrollable list component that renders a collection of chat ticket items with scroll-fade shadow overlays, loading skeleton states, and empty-state handling.
 
 ## Key Components
 
-- **`ChatTicketList`** — `forwardRef` component that wraps a scrollable ticket list with fade-in/out gradient masks at the top and bottom edges to indicate overflow content
-- **`getMask(top, bottom)`** — Pure utility that computes a CSS `linear-gradient` mask string based on whether the scroll container has hidden content above or below
-- **`updateFade`** — Scroll handler that compares `scrollTop`, `scrollHeight`, and `clientHeight` to toggle `fadeTop`/`fadeBottom` state, also triggered via `useLayoutEffect` when the ticket count changes
+| Export | Type | Description |
+|---|---|---|
+| `ChatTicketList` | `React.forwardRef` component | Main list container with scroll-fade behavior |
+| `ChatTicketListProps` | Interface | Props extending `HTMLAttributes<HTMLDivElement>` |
+| `ChatTicketItemData` | Re-exported type | Ticket data shape from `chat-ticket-item` |
 
-## Props
+### Props
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `tickets` | `ChatTicketItemData[]` | Array of ticket data to render |
-| `onTicketClick` | `(ticketId: string) => void` | Optional click handler passed to each item |
-| `className` | `string` | Additional CSS classes |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `tickets` | `ChatTicketItemData[]` | — | Array of ticket data to render |
+| `onTicketClick` | `(ticketId: string) => void` | — | Click handler passed to each item |
+| `isLoading` | `boolean` | `false` | Renders skeleton placeholders instead of tickets |
+| `skeletonCount` | `number` | `5` | Number of skeleton rows during loading |
+
+### Behavior
+
+- Uses `useScrollFade` to track scroll position and conditionally apply top/bottom fade overlays via `ScrollFadeOverlay`
+- Border radius on the list container dynamically toggles based on whether top/bottom fades are active
+- Returns `null` when `tickets` is empty (no empty state UI)
 
 ## Usage Example
 
 ```typescript
 import { ChatTicketList } from './chat-ticket-list'
+import type { ChatTicketItemData } from './chat-ticket-list'
 
-const tickets = [
-  { id: 'TKT-001', title: 'VPN not connecting', status: 'open' },
+const tickets: ChatTicketItemData[] = [
+  { id: 'TKT-001', title: 'Cannot connect to VPN', status: 'open' },
   { id: 'TKT-002', title: 'Printer offline', status: 'pending' },
 ]
 
-function ChatSidebar() {
-  return (
-    <ChatTicketList
-      tickets={tickets}
-      onTicketClick={(id) => console.log('Selected ticket:', id)}
-      className="max-h-96"
-    />
-  )
-}
+// Normal render
+<ChatTicketList
+  tickets={tickets}
+  onTicketClick={(id) => router.push(`/tickets/${id}`)}
+/>
+
+// Loading state
+<ChatTicketList
+  tickets={[]}
+  isLoading
+  skeletonCount={3}
+/>
 ```
 
-> Returns `null` when `tickets` is empty. Border radius and top/bottom borders are conditionally removed at scroll edges to visually blend with the fade mask.
+## Source
+
+[`chat-ticket-list.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chat-ticket-list.tsx)

package/src/components/chat/.chat-typing-indicator.md

@@ -1,34 +1,52 @@
-<!-- source-hash: fe8d4775d6a56401707002b9d3c2df21 -->
-A React component that displays an animated typing indicator with three pulsing dots, commonly used in chat interfaces to show when an assistant or user is typing a response.
+<!-- source-hash: de0eae2f35b8c3403f32c0ec87aeb062 -->
+A React component that renders an animated three-dot typing indicator for chat interfaces, with configurable size, optional label text, and customizable dot styling.
 
 ## Key Components
 
-- **ChatTypingIndicator** - Main component that renders animated dots with optional text
-- **dotSizeClasses** - Responsive sizing options (sm, md, lg) for the pulsing dots
-- **containerSizeClasses** - Container height classes that match the dot sizes
-- **dotAnimation** - CSS keyframe animation for the pulsing effect
+### `ChatTypingIndicator`
+
+A `forwardRef` component accepting `ChatTypingIndicatorProps`:
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Controls dot and container dimensions |
+| `showText` | `boolean` | `false` | Toggles "Assistant is typing" label |
+| `dotClassName` | `string` | `undefined` | Overrides default dot color (`bg-ods-text-primary`) |
+| `className` | `string` | `undefined` | Additional classes for the root element |
+
+**Animation:** Uses an injected `dotPulse` keyframe (`scale` + `opacity` pulse over 1.4s) with staggered delays — `0ms`, `200ms`, `400ms` — across the three dots.
+
+**Size variants:**
+
+| Size | Dot | Container height |
+|---|---|---|
+| `sm` | `w-1 h-1` | `h-4` |
+| `md` | `w-1.5 h-1.5` | `h-6` |
+| `lg` | `w-2 h-2` | `h-8` |
 
 ## Usage Example
 
 ```typescript
-import { ChatTypingIndicator } from './chat-typing-indicator'
+import { ChatTypingIndicator } from "./chat-typing-indicator"
 
-// Basic usage
+// Default medium indicator
 <ChatTypingIndicator />
 
-// With text and custom size
-<ChatTypingIndicator 
-  size="lg" 
-  showText={true} 
-  className="my-4"
-/>
+// Large with label
+<ChatTypingIndicator size="lg" showText />
 
-// Custom dot styling
-<ChatTypingIndicator 
-  size="md"
+// Custom dot color
+<ChatTypingIndicator
+  size="sm"
   dotClassName="bg-blue-500"
-  showText={true}
 />
+
+// Inside a chat message bubble
+<div className="chat-bubble">
+  <ChatTypingIndicator showText dotClassName="bg-ods-brand-primary" />
+</div>
 ```
 
-The component features three dots that pulse in sequence with staggered animation delays (0ms, 200ms, 400ms), creating a smooth wave effect. It supports three sizes (sm, md, lg), optional "Assistant is typing" text, and custom styling through className props. The animation uses CSS-in-JS with `dangerouslySetInnerHTML` to inject the keyframe animation directly into the component.
+> **Note:** The component injects a `<style>` tag via `dangerouslySetInnerHTML` to define the `dotPulse` keyframe. Ensure your CSP allows inline styles if applicable.
+
+**Source:** [`chat-typing-indicator.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chat-typing-indicator.tsx)

package/src/components/chat/.context-compaction-display.md

@@ -1,11 +1,19 @@
-<!-- source-hash: 4f36d6b4b32c3b253b88e445f6e633a8 -->
-A display component that shows context compaction status in a styled card, indicating either an in-progress summarization or a completed one.
+<!-- source-hash: 4ea3d14913c5982b17e29bcfa31d3441 -->
+A React component that displays the status of context compaction (summarization) for AI chat interfaces, showing either an in-progress or completed state.
 
 ## Key Components
 
-- **`ContextCompactionDisplay`** — A forwarded-ref `div` component that renders a status banner with a label and icon based on the `status` prop
-- **`status`** — Accepts `'started'` (in-progress) or any other value (completed), driving both the label text and icon displayed
-- **Icons** — Uses `DotsLoaderIcon` for in-progress state and `CheckCircleIcon` for completed state
+**`ContextCompactionDisplay`** — A `forwardRef` component that renders a styled status banner indicating whether context summarization is in progress or has completed.
+
+| Status | Label | Icon |
+|---|---|---|
+| `started` | "Context limit reached. Summarizing earlier messages." | `DotsLoaderIcon` (animated) |
+| *(any other)* | "Earlier context summarized." | `CheckCircleIcon` (success) |
+
+**Props** (`ContextCompactionDisplayProps`):
+- `status` — Controls which state is displayed (`'started'` or completed)
+- `className` — Optional class overrides merged via `cn()`
+- Forwards all other `HTMLDivElement` props and the `ref`
 
 ## Usage Example
 
@@ -14,23 +22,19 @@ import { ContextCompactionDisplay } from "./context-compaction-display"
 
 // In-progress state
 <ContextCompactionDisplay status="started" />
-// Renders: "Context limit reached. Summarizing earlier messages." + spinner
 
 // Completed state
 <ContextCompactionDisplay status="completed" />
-// Renders: "Earlier context summarized." + check icon
 
 // With custom className
 <ContextCompactionDisplay
-  status="done"
-  className="my-2 w-full"
+  status="started"
+  className="mt-2 mx-4"
 />
 ```
 
-## Props
+## Notes
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `status` | `string` | `'started'` shows loader; any other value shows check icon |
-| `className` | `string` | Optional additional CSS classes |
-| `ref` | `React.Ref<HTMLDivElement>` | Forwarded ref to the root `div` |
+- Styled with ODS design tokens (`bg-ods-card`, `border-ods-border`, `text-ods-text-secondary`, `text-ods-success`) — ensure your project includes the OpenFrame Design System token definitions.
+- The `displayName` is explicitly set to `"ContextCompactionDisplay"` for better React DevTools visibility.
+- Source: [`context-compaction-display.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/context-compaction-display.tsx)

package/src/components/chat/.context-items-list.md

@@ -0,0 +1,57 @@
+<!-- source-hash: 849d337b5d84f9474942d4af95de653f -->
+Shared building blocks for the **items level** of the entity-context picker (Figma 31:29102). Provides row chrome, skeleton placeholders, a scrollable list with scroll-driven pagination, and an error boundary — consumed by `ChatContextPickerConfig.renderItems` in the host application.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `CONTEXT_ROW_CLASS` | `string` | Tailwind classes for a standard menu row |
+| `CONTEXT_ICON_CLASS` | `string` | Responsive 16px→24px icon wrapper |
+| `CONTEXT_LABEL_CLASS` | `string` | Truncating h4 label slot |
+| `CONTEXT_BACK_CLASS` | `string` | Back-navigation row classes |
+| `CONTEXT_STATE_CLASS` | `string` | Empty/error state prose classes |
+| `ContextMenuRow` | Component | Icon + label + optional trailing slot button primitive |
+| `ContextItemsSkeleton` | Component | Suspense / load-more placeholder rows |
+| `ContextItemsList` | Component | Scrollable `role="listbox"` with selection state, limit enforcement, and scroll-driven pagination |
+| `ContextErrorBoundary` | Class Component | Catches failed host fetches; auto-resets on `resetKey` change |
+
+## Usage Example
+
+```typescript
+import {
+  ContextItemsList,
+  ContextErrorBoundary,
+  ContextItemsSkeleton,
+} from './context-items-list'
+
+function MyPickerItems({ query }: { query: string }) {
+  const { items, hasMore, fetchNextPage, isFetchingNextPage } = useMyItems(query)
+
+  return (
+    <ContextErrorBoundary
+      resetKey={`device:${query}`}
+      fallback={(retry) => (
+        <button onClick={retry}>Failed to load — retry</button>
+      )}
+    >
+      <React.Suspense fallback={<ContextItemsSkeleton count={5} />}>
+        <ContextItemsList
+          items={items}
+          selectedKeys={selectedKeys}
+          onToggle={handleToggle}
+          atLimit={selectedKeys.size >= 5}
+          hasMore={hasMore}
+          onLoadMore={fetchNextPage}
+          loadingMore={isFetchingNextPage}
+          emptyLabel="No devices found"
+        />
+      </React.Suspense>
+    </ContextErrorBoundary>
+  )
+}
+```
+
+**Notes:**
+- `ContextErrorBoundary.resetKey` should encode both the entity type and current search query so errors clear automatically on navigation or new searches. Pair the `retry` callback with your data library's cache-reset (e.g. react-query's `queryClient.resetQueries`) to ensure the fetch actually re-runs.
+- The list caps height at `min(340px, 45vh)` to stay inside bottom-anchored popovers on short viewports.
+- Source: [`context-items-list.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/context-items-list.tsx)

package/src/components/chat/.embeddable-chat.md

@@ -1,81 +1,72 @@
-<!-- source-hash: c87e4b417e41397ff1753b0ea0848f78 -->
-Portable, lib-safe port of the hub's `<GlobalAskAI>` chat panel component, decoupled from all hub-only imports by routing navigation, identity, and transport decisions through a `useRequiredChatRuntime()` context hook.
+<!-- source-hash: 6d1785ee322c618d61267609c25a54fb -->
+Portable, library-safe chat panel component that strips all hub-specific dependencies and routes navigation, identity, and transport decisions through a unified `useRequiredChatRuntime()` hook, enabling embedding in any host application.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `EmbeddableChat` | Component | Main embeddable chat panel with controlled/uncontrolled open state |
-| `EmbeddableChatProps` | Interface | Full prop surface for the component |
-| `dispatchSlashCommandAction` | Function | Maps slash-command action IDs (`browse`, `search`, `find`, `display`) to `ChatInputRef` mutations |
-| `resolveChipIcon` | Function | Resolves a `ChatSource` to a Lucide icon via the icon registry |
-| `SKELETON_ROW_VARIANTS` | Constant | Deterministic width palette for loading skeleton rows |
-| `FALLBACK_TOP_RETRIEVED` | Constant | Number of fallback source chips shown when the model cites no sources (default: `3`) |
-
-## Usage Example
+### `EmbeddableChat` (default export)
+The primary component rendering a full-featured AI chat panel with:
+- **Controlled/uncontrolled open state** via `open`, `defaultOpen`, and `onOpenChange` props
+- **Dual-mode support** — Guide (SSE/RAG) and Mingo (NATS/agent) modes with an in-panel toggle
+- **Injected Mingo state** via `mingoState` for host-managed transport (survives panel unmounting)
+- **Preview/marketing mode** via `previewMode` — renders a non-interactive visual mock
 
+### `EmbeddableChatProps`
 ```typescript
-// Host wires the runtime once at root
-<HubRuntimeProvider source="hub" user={currentUser}>
-  <EmbeddableChat
-    emptyStateGreeting="How can I help you today?"
-    suggestedQueries={['How do I reset a password?', 'Show open tickets']}
-    enabledRagTableIds={enabledTableIds}
-    modes={{
-      guide: { tableIdForDocumentType },
-      mingo: { agentId: 'mingo-agent' },
-    }}
-    defaultActiveMode="guide"
-    extras={{ buildProgramProps, buildProductReleaseProps }}
-  />
-</HubRuntimeProvider>
-
-// Controlled open state
-<EmbeddableChat
-  open={isOpen}
-  onOpenChange={setIsOpen}
-  showInternalTrigger={false}
-/>
+interface EmbeddableChatProps {
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  defaultOpen?: boolean
+  showInternalTrigger?: boolean
+  previewMode?: boolean
+  modes?: UseUnifiedChatModes         // Guide + Mingo transport config
+  mingoState?: UnifiedChatState       // Host-injected Mingo state
+  mingoDialogCapabilities?: { ... }   // Rename/archive/restore capabilities
+  extras?: ChatCardDispatchExtras     // Entity card builder overrides
+  enabledRagTableIds?: ReadonlyArray<string> | null
+  suggestedQueries?: ReadonlyArray<string> | null
+  baseRoute?: string
+  chipBasePlatform?: string
+}
 ```
 
-## Runtime Substitutions
+### Key Runtime Dependencies
+- **`useRequiredChatRuntime()`** — provides `user`, `source`, and navigation context (replaces hub's `useAuth`, `currentPlatform`, `useNavLink`)
+- **`useUnifiedChat()`** — orchestrates Guide/Mingo mode switching and transport adapters
+- **`useSseChatAdapter()`** — SSE transport for Guide mode (replaces `useDocChat`)
+- **`NavLinkAnchorViaRuntime`** — runtime-aware link rendering (replaces hub's `NavLinkAnchor`)
 
-| Hub Original | Lib Replacement |
-|---|---|
-| `useAuth()` | `useRequiredChatRuntime().user` |
-| `currentPlatform()` | `useRequiredChatRuntime().source` |
-| `useNavLink` / `NavLinkAnchor` | `handleChatNavClick` + `NavLinkAnchorViaRuntime` |
-| `useDocChat(source)` | `useSseChatAdapter()` (source from runtime) |
-## Agent mode (OpenFrame AI agents — Fae / Mingo)
-
-Reuse the SAME `<EmbeddableChat>` to render a global OpenFrame AI agent. No new
-component, no agent-specific render path — an "agent mode" just OVERRIDES the
-empty-state URL so the chat fetches the agent's display config (greeting +
-suggested prompts + source chips) from the public `/api/ai-agents/[slug]`
-endpoint, which is byte-compatible with the `EmptyStateConfig` wire shape
-(`{ greeting, suggestedQueries, enabledRagTableIds }`).
+## Usage Example
 
-- Pass `activeAgentSlug` (e.g. `"fae"`) to `<EmbeddableChat>`. **Works in BOTH
-  regular (host) and embedded modes** — there is no navigation-mode gate.
+```typescript
+import { EmbeddableChat } from '@openframe/lib'
+import { HubRuntimeProvider } from './hub-runtime-provider'
 
-```tsx
-<EmbeddableChat activeAgentSlug="fae" />
+function App() {
+  return (
+    <HubRuntimeProvider>
+      <EmbeddableChat
+        showInternalTrigger
+        modes={{
+          guide: { tableIdForDocumentType: (type) => myTableMap[type] ?? null },
+          mingo: { natsConfig: myNatsConfig, fetchDialogs: fetchDialogs }
+        }}
+        enabledRagTableIds={['kb_articles', 'tickets']}
+        suggestedQueries={['How do I reset a password?', 'Show open tickets']}
+        extras={{ buildProgramCardProps: myBuilder }}
+      />
+    </HubRuntimeProvider>
+  )
+}
 ```
 
-**Default routes, fully overridable.** Agent mode works with ZERO endpoint
-wiring — the component falls back to a built-in default route. Resolution order
-for the agent display-config route (highest → lowest precedence):
+## Drawer Behavior
 
-1. `aiAgentConfigUrl` prop on `<EmbeddableChat>` (per-mount override)
-2. `runtime.endpoints.aiAgentConfigUrl(slug)` (shared runtime override)
-3. built-in default `` (slug) => `/api/ai-agents/${encodeURIComponent(slug)}` ``
+| Constant | Value | Description |
+|---|---|---|
+| `DRAWER_DEFAULT_WIDTH_RATIO` | `0.5` | 50% of viewport width on desktop |
+| `DRAWER_WIDTH_KEY` | `mingo-chat-width-v3` | `localStorage` key for persisted width |
+| `DRAWER_DEFAULT_WIDTH_PX` | `750` | SSR fallback before viewport is known |
 
-Same-origin embedders need nothing; cross-origin embedders behind a proxy set
-`runtime.endpoints.aiAgentConfigUrl` (or the prop) to their absolute proxied
-path. Every other chat route (`chatStreamUrl`, `commandsUrl`, …) comes from
-`runtime.endpoints` and is likewise overridable.
+## Source
 
-DISPLAY-ONLY this phase: retrieval still resolves server-side from the platform
-(the chat route derives `source` from the deployment, not the client) — the
-agent customizes the greeting + suggested-prompt chips, not the corpus. In mingo
-mode, `mingoWelcome` still owns its own welcome surface.
+[`embeddable-chat.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/embeddable-chat.tsx) · [OpenFrame OSS Lib](https://github.com/flamingo-stack/openframe-oss-lib) · Community: [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)

package/src/components/chat/.error-message-display.md

@@ -1,39 +1,57 @@
-<!-- source-hash: 00278694728343420131f5468336720f -->
-A React component that displays error messages with an expandable details section, designed for user-friendly error communication in the Flamingo platform.
+<!-- source-hash: ef8653f94f0fdc48eb37fc59aa16aeb7 -->
+Collapsible error/warning/info message component that displays a title with an optional expandable details section, supporting three severity types with distinct icon tinting.
 
 ## Key Components
 
-- **ErrorMessageDisplay**: A forwardRef component that renders error messages with:
-  - Alert icon and styled error container
-  - Expandable/collapsible details section
-  - Accessibility features (ARIA labels, keyboard navigation)
-  - Custom styling using CSS variables and Tailwind classes
+### `ErrorMessageDisplay`
+A `forwardRef` component that renders an alert card with:
+- **`title`** — Always-visible summary text (truncated when collapsed)
+- **`details`** — Optional expandable body text; when omitted, the card is non-interactive
+- **`type`** — Severity level controlling icon color: `"error"` (default) | `"warning"` | `"info"`
+- **`className`** — Additional CSS classes merged via `cn`
+
+### `iconTint`
+Internal map from `type` to ODS color tokens:
+| Type | Token |
+|---|---|
+| `error` | `text-ods-error` |
+| `warning` | `text-ods-warning` |
+| `info` | `text-ods-text-secondary` |
+
+### Internal Hooks & Sub-components
+- **`useCollapsible`** — Provides animated `containerStyle` and `innerRef` for smooth height transitions
+- **`ExpandChevron`** — Chevron icon that rotates based on `expanded` state
+- **`AlertCircleIcon`** — 16px alert icon tinted by severity type
 
 ## Usage Example
 
 ```typescript
 import { ErrorMessageDisplay } from "./error-message-display"
 
-// Basic error message
-<ErrorMessageDisplay 
+// Simple non-interactive error
+<ErrorMessageDisplay
+  type="error"
   title="Authentication failed"
 />
 
-// Error with expandable details
-<ErrorMessageDisplay 
-  title="Connection timeout"
-  details="The server failed to respond within 30 seconds. Please check your network connection and try again."
-  className="mb-4"
+// Expandable warning with details
+<ErrorMessageDisplay
+  type="warning"
+  title="Rate limit approaching"
+  details="You have used 90% of your API quota. Requests may be throttled after midnight UTC."
 />
 
-// With ref for programmatic access
-const errorRef = useRef<HTMLDivElement>(null)
-
-<ErrorMessageDisplay 
-  ref={errorRef}
-  title="Validation error"
-  details="Email format is invalid. Please enter a valid email address."
+// Info message with custom class
+<ErrorMessageDisplay
+  type="info"
+  title="Scheduled maintenance window"
+  details="The service will be unavailable from 02:00–04:00 UTC on Saturday."
+  className="mt-4"
 />
 ```
 
-The component features a red error theme with white text, an AlertCircle icon from Lucide React, and smooth expand/collapse animations. When details are provided, users can click the chevron button to toggle the detailed error information.
+## Accessibility
+
+- `aria-expanded` is set on the toggle button only when `details` is present
+- `aria-label` dynamically switches between `"Expand details"` / `"Collapse details"`
+- Button is `disabled` when no details exist, preventing keyboard interaction

package/src/components/chat/.guide-mode-banner.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 2df823f019c629ff7f91356377ab1d22 -->
+A full-bleed accent banner component that indicates when a chat session is running in Guide Mode, displaying a compass icon, label, and optional help tooltip.
+
+## Key Components
+
+### `GuideModeBanner`
+
+The primary exported component. Renders a fixed-height (`h-8`) yellow accent strip intended to appear below a chat header.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `React.ReactNode` | `'Guide Mode Chat'` | Banner label text (rendered uppercase via `text-h5` style) |
+| `tooltip` | `React.ReactNode \| null` | Default explanation string | Help icon tooltip copy; pass `null` to hide the help icon entirely |
+| `className` | `string` | — | Additional CSS classes merged via `cn()` |
+
+**Visual structure:**
+- **Leading:** `CompassIcon` (16px)
+- **Center:** Truncated label paragraph
+- **Trailing:** `QuestionCircleIcon` button with a `TooltipProvider` (hidden when `tooltip` is `null`)
+
+## Usage Example
+
+```typescript
+// Default — shows all three elements with built-in copy
+<GuideModeBanner />
+
+// Custom label only
+<GuideModeBanner label="Exploration Mode" />
+
+// Hide the help icon entirely
+<GuideModeBanner tooltip={null} />
+
+// Fully custom
+<GuideModeBanner
+  label="Read-Only Session"
+  tooltip="This session cannot modify any devices or run scripts."
+  className="opacity-90"
+/>
+```
+
+> **Note:** This component is a Client Component (`'use client'`). It maps to Figma node `7532:328222` and uses ODS design tokens (`bg-ods-accent`, `text-ods-text-on-accent`) for theming. The tooltip uses `delayDuration={0}` for immediate display.

package/src/components/chat/.guide-welcome.md

@@ -0,0 +1,43 @@
+<!-- source-hash: e233b47b6ba8c30b077620a42a9735ba -->
+Guide-mode chat empty state component that renders a centered greeting (icon, title, optional subtitle) and a pinned quick-action chip wall above the composer, sharing a single scrollable region with scroll-fade affordances.
+
+## Key Components
+
+### `GuideQuickAction`
+Interface for individual quick-action chips, supporting labels, prompt text, icon resolution (glyph name or URL), and accent tints (`'fae'` → pink, `'mingo'` → cyan).
+
+### `GuideWelcomeProps`
+Full props interface for the `GuideWelcome` component, including identity icon override, subtitle loading state, quick-action callbacks, and agent slug for row-cap behavior in `QuickActionWall`.
+
+### `GuideWelcome`
+Primary export. Renders:
+- **Scroll region** — greeting (icon + title + subtitle/skeleton) and `children` (slash-command onboarding list) share one `overflow-y-auto` container with `ScrollFadeOverlay` top/bottom edge fades.
+- **Identity icon** — uses `<EntityIcon>` when `icon.name` or `icon.url` is set; falls back to the default `<MingoIcon>` with cyan accents.
+- **Subtitle** — renders admin copy when present, a `<Skeleton>` while `subtitleLoading` is true, or nothing by default.
+- **Quick-action wall** — pinned below the scroll region via `<QuickActionWall>` in BRICK marquee mode (up to 4 rows, hover-pause, drag-scroll, left/right edge fades).
+
+## Usage Example
+
+```typescript
+import { GuideWelcome, type GuideQuickAction } from './guide-welcome'
+
+const actions: GuideQuickAction[] = [
+  { id: '1', label: 'Reset a password', iconName: 'key', accent: 'cyan' },
+  { id: '2', label: 'Check device health', prompt: 'Run a full device health check', accent: 'cyan' },
+]
+
+<GuideWelcome
+  title="IT Support Assistant"
+  subtitle="Ask me anything about your devices or accounts."
+  icon={{ name: 'robot' }}
+  quickActions={actions}
+  onQuickAction={(action) => sendPrompt(action.prompt ?? action.label)}
+  onQuickActionHover={(action) => previewInComposer(action.prompt ?? action.label)}
+  onQuickActionHoverEnd={() => restoreComposer()}
+  agentSlug="mingo"
+>
+  <SlashCommandList />
+</GuideWelcome>
+```
+
+**Source:** [`guide-welcome.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/guide-welcome.tsx)