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

package/src/components/chat/.index.md

@@ -1,42 +1,47 @@
-<!-- source-hash: 4f91f1efeb0b18cbf93d3b4ed385c331 -->
-Central barrel export for the `chat` UI package — re-exports every public component, hook, utility, type, and constant from the chat feature module, making the entire surface area available via a single import path.
+<!-- source-hash: 81dec73c1b378eb59ab6833dce65f1b7 -->
+Public barrel index for the `chat` UI component library. Aggregates and re-exports all chat-related components, hooks, utilities, types, and entity cards for downstream consumption as a single import surface.
 
 ## Key Components
 
-| Export | Description |
-|--------|-------------|
-| `EmbeddableChat` | Top-level chat orchestrator; mount once at the app root inside a `ChatRuntimeContext.Provider` |
-| `ChatRef` | Type for imperative chat handle refs |
-| `remarkCardLinks` | Remark plugin for rendering card-style links in chat messages |
-| `NavLinkAnchorViaRuntime` | Runtime-aware navigation anchor component |
-| `SourceActionButton` | Action button with configurable density for source references |
-| `ChatAttachmentAddButton` / `ChatAttachmentChipStrip` | Attachment UI with MIME type constants and upload concurrency limits |
-| `entity-cards` | Suite of 12+ refactored entity card components |
-| `hooks` | All chat-related React hooks |
-| `utils` | Chat utility functions |
-| `types` | Shared chat types and constants |
+| Export Group | Description |
+|---|---|
+| **Core Chat UI** | `ChatContainer`, `ChatInput`, `ChatComposer`, `ChatMessageEnhanced`, `ChatMessageList`, `ChatMessageRow` |
+| **AI Interaction** | `ThinkingDisplay`, `ToolExecutionDisplay`, `ToolCallBlocks`, `ApprovalRequestMessage`, `ApprovalBatchMessage` |
+| **Mingo / Guide** | `MingoOnboardingCard`, `MingoWelcome`, `GuideWelcome`, `GuideModeTooltip`, `MingoChatHistory`, `MingoHistoryRail` |
+| **Context & Memory** | `ChatContextPicker`, `ChatContextMemoryBar`, `ContextItemsList`, `ContextCompactionDisplay` |
+| **Quick Actions** | `QuickActionChip`, `QuickActionMarquee`, `QuickActionWall` |
+| **Attachments** | `ChatAttachmentAddButton`, `ChatAttachmentChipStrip`, `CHAT_ATTACHMENT_MIME_TYPES` |
+| **Entity Cards** | Full set of entity cards and supporting primitives via `./entity-cards` |
+| **Remark Plugins** | `remarkCardLinks`, `remarkMentionChips` |
+| **Orchestrator** | `EmbeddableChat` — root-level chat orchestrator, portable across host apps |
+| **Primitives** | `hooks`, `utils`, `types`, `ChatRef` |
 
 ## Usage Example
 
 ```typescript
-// Import anything from the chat package via this single entry point
+// Single import surface — no deep path imports needed
 import {
   EmbeddableChat,
+  ChatContainer,
+  ChatInput,
+  MingoWelcome,
+  QuickActionChip,
   ChatAttachmentAddButton,
   CHAT_ATTACHMENT_MIME_TYPES,
+  remarkCardLinks,
   type ChatRef,
   type EmbeddableChatProps,
-} from '@flamingo/chat'
-
-function AppRoot() {
-  const chatRef = useRef<ChatRef>(null)
+  type StagedAttachment,
+} from '@openframe/chat'
 
+// Mount the full chat orchestrator at your app root
+function App() {
   return (
     <ChatRuntimeContext.Provider value={runtime}>
-      <EmbeddableChat ref={chatRef} />
+      <EmbeddableChat userId="usr_123" tenantId="msp_456" />
     </ChatRuntimeContext.Provider>
   )
 }
 ```
 
-> **Note:** This file is marked `'use client'` — all exports are React Client Components or client-safe utilities, intended for browser rendering in Next.js App Router environments.
+> **Note:** This module is marked `'use client'` — all exports are React Client Components intended for browser rendering only. Mount `EmbeddableChat` once at the root after providing a `ChatRuntimeContext.Provider`.

package/src/components/chat/.mingo-chat-history.md

@@ -0,0 +1,63 @@
+<!-- source-hash: 5f18f183bb0da99f376729304439764e -->
+Renders a scrollable, date-grouped list of Mingo AI chat dialogs with support for row actions, unread badges, owner avatars, infinite scroll, skeleton loading states, and empty state handling.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `MingoChatHistoryProps` | Primary props interface for the list component |
+| `MingoChatHistory` *(default export implied)* | Root scrollable dialog list with grouped sections |
+| `MingoChatHistoryRow` | Individual dialog row with title, unread badge, avatar, and actions menu |
+| `MingoChatHistorySkeleton` | Animated pulse placeholder shown during initial page load |
+| `groupDialogs` | Pure utility that buckets dialogs into **Today / Yesterday / Older** groups |
+| `DialogGroup` | Internal type representing a labeled group of `DialogItem` entries |
+
+## Usage Example
+
+```typescript
+import {
+  MingoChatHistory,
+  MingoChatHistorySkeleton,
+} from '@openframe/oss-lib'
+import type { DialogItem } from '@openframe/oss-lib'
+
+const dialogs: DialogItem[] = [
+  {
+    id: 'abc-123',
+    title: 'Network outage triage',
+    timestamp: new Date(),
+    unreadMessagesCount: 3,
+    owner: { name: 'Ada Lovelace', avatarUrl: 'https://cdn.example.com/ada.png' },
+  },
+]
+
+// Show skeleton while loading the first page
+if (isLoading) return <MingoChatHistorySkeleton />
+
+// Render the list once data arrives
+return (
+  <MingoChatHistory
+    dialogs={dialogs}
+    activeDialogId="abc-123"
+    searchQuery={query}
+    hasMore={hasNextPage}
+    isLoadingMore={isFetchingNextPage}
+    onSelectDialog={(id) => router.push(`/chat/${id}`)}
+    onRequestRename={(dialog) => openRenameModal(dialog)}
+    onRequestArchive={(dialog) => openArchiveModal(dialog)}
+    onLoadMore={fetchNextPage}
+  />
+)
+```
+
+## Behavior Notes
+
+- **Date grouping** is computed client-side from `dialog.timestamp` (accepts both `string` and `Date`); dialogs without a timestamp fall into **Older**.
+- **Infinite scroll** is driven by an Intersection Observer on a bottom sentinel; `onLoadMore` fires automatically when it enters the viewport.
+- **Search** is server-side — the list renders whatever `dialogs` the host provides and uses `searchQuery` only to render the correct empty-state message.
+- **Active row** renders an amber accent bar and yellow title text per the ODS design spec.
+- The `⋯` actions menu is desktop-only (hidden on touch via `max-md:hidden`) and stays visible while the Radix dropdown is open via controlled `menuOpen` state.
+
+## Source
+
+[`mingo-chat-history.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/mingo-chat-history.tsx)

package/src/components/chat/.mingo-chat-modals.md

@@ -0,0 +1,44 @@
+<!-- source-hash: 84980ba72f1825d869b36d8a7a15c4e7 -->
+Provides three chat management modals — Rename, Archive, and Unarchive — plus a composite `ChatDialogModals` component that renders all three together, driven by target dialog state.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `RenameChatModal` | Modal with a controlled text input to rename a chat; seeds from `initialName` on open, fires `onSave` with the trimmed value |
+| `ArchiveChatModal` | Destructive confirmation modal to hide a chat from the current list |
+| `UnarchiveChatModal` | Confirmation modal to restore an archived chat back to the current list |
+| `ChatDialogModals` | Composite wrapper rendering all three modals; pairs with `useChatDialogManager` which produces the expected prop shape |
+
+## Usage Example
+
+```typescript
+// Standalone modal usage
+<RenameChatModal
+  isOpen={isOpen}
+  initialName="Support Session"
+  onClose={() => setIsOpen(false)}
+  onSave={(newName) => updateChatName(chatId, newName)}
+/>
+
+// Composite usage with useChatDialogManager
+const dialogManager = useChatDialogManager()
+
+<ChatDialogModals
+  renameTarget={dialogManager.renameTarget}
+  setRenameTarget={dialogManager.setRenameTarget}
+  onConfirmRename={(name) => renameChat(name)}
+  archiveTarget={dialogManager.archiveTarget}
+  setArchiveTarget={dialogManager.setArchiveTarget}
+  onConfirmArchive={() => archiveChat()}
+  restoreTarget={dialogManager.restoreTarget}
+  setRestoreTarget={dialogManager.setRestoreTarget}
+  onConfirmRestore={() => restoreChat()}
+/>
+```
+
+## Notes
+
+- All modals are capped at `600px` width on `md+` breakpoints via `ModalV2`.
+- `RenameChatModal` re-seeds the input via `useEffect` whenever `isOpen` or `initialName` changes, safely handling different chats sharing the same modal instance.
+- Button styles (`cancelBtn`, `saveBtn`, `dangerBtn`) follow the Figma `button-full` spec: full-width, DM Sans Bold 18px, `rounded-md`.

package/src/components/chat/.mingo-history-rail.md

@@ -0,0 +1,63 @@
+<!-- source-hash: 91ed9862c8dd8b9c0d7182ce412e2488 -->
+Persistent left-rail component for the wide (split) Mingo layout that displays the chat history list alongside the active conversation panel.
+
+## Key Components
+
+### `MingoHistoryRail` (default export)
+
+The root component renders a vertical flex column containing three logical zones:
+
+- **"Start New Chat" button** — always pinned at top when `onNewChat` is provided
+- **Scope selector** (`TabSelector`) — toggles between "My Chats" / "All Chats" when both `scope` and `onScopeChange` are provided; hidden on load error
+- **Content area** — renders one of four mutually exclusive states:
+  - `loadError` → error message with optional retry button
+  - `isLoadingHistory` → `MingoChatHistorySkeleton`
+  - Dialogs present or active search → `MingoChatHistory`
+  - Empty, no search → `ChatListEmptyState`
+
+### `MingoHistoryScope`
+
+```typescript
+export type MingoHistoryScope = 'my' | 'all'
+```
+
+Union type controlling whether the rail lists only the current user's dialogs (`'my'`) or all tenant-admin dialogs (`'all'`).
+
+### `MingoHistoryRailProps`
+
+Full prop interface. Key props:
+
+| Prop | Type | Description |
+|---|---|---|
+| `dialogs` | `ReadonlyArray<DialogItem>` | Pre-sorted (newest-first) dialog list |
+| `activeDialogId` | `string` | Highlights the currently open chat |
+| `scope` / `onScopeChange` | `MingoHistoryScope` / handler | Opt-in ownership filter; host owns state |
+| `isLoadingHistory` | `boolean` | Shows skeleton on first page load |
+| `loadError` | `boolean` | Triggers error + retry UI |
+| `hasMore` / `onLoadMore` | `boolean` / handler | Cursor-based pagination |
+
+## Usage Example
+
+```typescript
+<MingoHistoryRail
+  dialogs={dialogs}
+  activeDialogId={activeId}
+  onSelectDialog={(id) => setActiveId(id)}
+  onNewChat={() => setActiveId(undefined)}
+  onRequestRename={(dialog) => openRenameModal(dialog)}
+  onRequestArchive={(dialog) => openArchiveModal(dialog)}
+  scope={scope}
+  onScopeChange={setScope}
+  searchQuery={searchQuery}
+  hasMore={hasMore}
+  isLoadingMore={isFetchingMore}
+  onLoadMore={fetchNextPage}
+  isLoadingHistory={isLoading}
+  loadError={isError}
+  onRetry={refetch}
+/>
+```
+
+## Source
+
+[`mingo-history-rail.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/mingo-history-rail.tsx)

package/src/components/chat/.mingo-info-card.md

@@ -0,0 +1,59 @@
+<!-- source-hash: 511a5004fe6fe4628e28098d4d2873fa -->
+A React component that renders an inline-safe information card designed for use inside chat message paragraphs, using only phrasing-content elements (`<span>`, `<a>`, `<button>`, `<img>`) to remain valid within `<p>` tags.
+
+## Key Components
+
+### Exports
+
+- **`MingoInfoCard`** — Primary card component rendering title, optional description, leading media, status pill, and overflow menu
+- **`CardMedia`** *(internal)* — 40px leading media slot supporting avatar images (with initials fallback) or icon glyphs
+- **`MingoInfoCardProps`** — Full prop interface for the card
+- **`MingoInfoCardStatus`** — Shape for the status pill (`label` + `variant`)
+- **`MingoInfoCardAnchorProps`** — Anchor-prop bundle (`href`, `target`, `rel`, `onClick`) for navigation mode
+
+### Content Region Modes
+
+| Condition | Rendered as |
+|---|---|
+| `anchorProps` supplied | `<a>` (takes precedence) |
+| `onClick` supplied | `<button type="button">` |
+| Neither | `<span>` (static) |
+
+## Usage Example
+
+```typescript
+import { MingoInfoCard } from '@openframe/ui'
+
+// Static card with avatar and status pill
+<MingoInfoCard
+  imageSrc="https://cdn.example.com/avatar.png"
+  imageAlt="Jane Doe"
+  title="Jane Doe"
+  description="Senior Technician"
+  status={{ label: 'Online', variant: 'success' }}
+/>
+
+// Navigable card with icon and overflow menu
+<MingoInfoCard
+  icon={<ServerIcon size={24} />}
+  title="Prod Server"
+  description="192.168.1.1"
+  anchorProps={{ href: '/devices/42', target: '_blank' }}
+  menuGroups={[
+    {
+      items: [
+        { label: 'View details', onClick: handleView },
+        { label: 'Restart', onClick: handleRestart },
+      ],
+    },
+  ]}
+/>
+```
+
+## Notes
+
+- The `imageSrc` avatar gracefully degrades to initials (via `getFirstLastInitials`) on image load failure
+- The `⋯` menu button is always a sibling of the content anchor — never nested — preserving valid HTML
+- Status pill reuses `tagVariants` for colour consistency without introducing block-level `<div>` elements
+
+**Source:** [`mingo-info-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/mingo-info-card.tsx)

package/src/components/chat/.mingo-onboarding-card.md

@@ -1,24 +1,24 @@
-<!-- source-hash: 86ac59c4c1438a33b694f4b3fbba9291 -->
-A chat empty-state onboarding card component that renders a single slash-command or feature row, supporting optional action buttons, icons, and interactive/non-interactive modes.
+<!-- source-hash: 5c7bea0689601e74e88dd84bfa270626 -->
+A React client component that renders a single onboarding/slash-command row card for the Mingo AI chat empty-state list. Supports optional icons, slash-command labels, descriptions, and inline action buttons, rendering as either an interactive `<button>` or a static `<div>` depending on props.
 
 ## Key Components
 
 ### Interfaces
 
 - **`MingoOnboardingCardAction`** — Defines a single action button with `id`, `label`, and `onClick` handler
-- **`MingoOnboardingCardProps`** — Full card configuration including `icon`, `title`, `slashCommand`, `description`, `actions`, `onClick`, and `className`
+- **`MingoOnboardingCardProps`** — Full prop surface for the card: `icon`, `title`, `slashCommand`, `description`, `actions`, `onClick`, `className`
 
 ### Component
 
-- **`MingoOnboardingCard`** — Root component that conditionally renders as a `<button>` (when `onClick` is set and no `actions`) or a `<div>` (when `actions` are present or no `onClick`)
+- **`MingoOnboardingCard`** — Main export. Conditionally renders as a `<button>` (when `onClick` is set and `actions` is empty) or a `<div>` (when `actions` are present or no `onClick` is provided). Action buttons use `e.stopPropagation()` to prevent card-level click conflicts.
 
-### Behavior Logic
+## Rendering Behavior
 
-| Condition | Rendered Element |
-|-----------|-----------------|
+| Condition | Root element |
+|---|---|
+| `actions` provided (non-empty) | `<div>` (non-interactive) |
 | `onClick` set, no `actions` | `<button>` with hover/focus styles |
-| `actions` present | `<div>` with per-action `<button>` chips |
-| Neither | Static `<div>` |
+| Neither | `<div>` |
 
 ## Usage Example
 
@@ -28,35 +28,29 @@ import {
   MingoOnboardingCardAction,
 } from './mingo-onboarding-card'
 
-// Static card with slash command
+// Static card with description
 <MingoOnboardingCard
   icon={<SearchIcon />}
-  title="Search Knowledge Base"
+  title="Search tickets"
   slashCommand="/search"
-  description="Find articles, runbooks, and past tickets"
+  description="Find tickets by keyword or ID"
+  onClick={() => console.log('card clicked')}
 />
 
-// Interactive card (renders as <button>)
-<MingoOnboardingCard
-  icon={<RoadmapIcon />}
-  title="View Roadmap"
-  slashCommand="/roadmap"
-  onClick={() => router.push('/roadmap')}
-/>
-
-// Card with action chips (renders as <div>)
+// Card with inline action buttons (renders as non-interactive div)
 const actions: MingoOnboardingCardAction[] = [
-  { id: 'recent', label: 'Recent', onClick: () => fetchRecent() },
-  { id: 'search', label: 'Search', onClick: (e) => { e.stopPropagation(); openSearch() } },
+  { id: 'recent', label: 'Recent', onClick: (e) => handleRecent(e) },
+  { id: 'search', label: 'Search', onClick: (e) => handleSearch(e) },
 ]
 
 <MingoOnboardingCard
   icon={<TicketIcon />}
-  title="Tickets"
-  slashCommand="/tickets"
-  description="Browse and manage open tickets"
+  title="Roadmap"
+  slashCommand="/roadmap"
   actions={actions}
 />
 ```
 
-> **Note:** Stack multiple cards inside a `rounded-md` container — the `last:border-b-0` rule automatically removes the bottom divider from the final card, keeping the visual frame clean.
+> Cards are designed to be stacked in a `rounded-md` container. The `border-b` divider on each card and `last:border-b-0` keep the visual frame clean without a trailing border.
+
+**Source:** [`mingo-onboarding-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/mingo-onboarding-card.tsx)

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

@@ -0,0 +1,60 @@
+<!-- source-hash: 9eec10a801d679d0ee1d460966bca7a5 -->
+Mingo's chat empty-state screen, rendering a greeting, feature grid, optional "New to OpenFrame?" promo notification, and quick-action chips for new and returning users.
+
+## Key Components
+
+### Exported Types
+
+- **`MingoWelcomePromo`** — Config object (`title`, `description`) for the one-time "New to OpenFrame?" notification card. Pass `null` to suppress.
+- **`MingoQuickAction`** — Descriptor for an extra quick-action chip: `id`, `label`, optional `icon`, `variant` (`'primary'` | `'outline'`), `onClick`, and a `prompt` string previewed on hover.
+- **`MingoWelcomeProps`** — Full props surface for `MingoWelcome`.
+
+### Main Export
+
+- **`MingoWelcome`** — Primary empty-state component. Handles three distinct states:
+  - **New user** — Greeting, feature grid, optional promo notification, and quick-action chips.
+  - **Returning user** — Replaces greeting/grid with `dialogHistory` content; chips remain pinned.
+  - **Loading / Error** — Renders `MingoChatHistorySkeleton` or a retry block while history resolves.
+
+### Key Behaviors
+
+- **Promo persistence** — Dismissal stored in `localStorage` or `sessionStorage` (SSR-safe; hydrated after mount).
+- **Scroll-fade affordances** — Uses `useScrollFade` to show 48 px edge gradients when content overflows the scrollable greeting/grid region.
+- **Pinned region gating** — The promo and chips are suppressed while `isLoadingHistory` or `loadError` is active (avoids misleadingly showing the new-user layout).
+
+## Usage Example
+
+```typescript
+import {
+  MingoWelcome,
+  MingoWelcomeProps,
+  MingoQuickAction,
+} from '@openframe-oss-lib/components/mingo/mingo-welcome'
+
+const quickActions: MingoQuickAction[] = [
+  {
+    id: 'run-diagnostic',
+    label: 'Run Diagnostic',
+    variant: 'outline',
+    prompt: 'Run a full system diagnostic and summarize the results.',
+    onClick: () => console.log('diagnostic triggered'),
+  },
+]
+
+export function MingoChatPanel() {
+  return (
+    <MingoWelcome
+      subtitle="What can I help you with today?"
+      quickActions={quickActions}
+      onQuickActionHover={(action) => previewPrompt(action.prompt ?? action.label)}
+      onQuickActionHoverEnd={() => clearPreview()}
+      onStartGuideChat={() => switchToGuideMode()}
+      hasExistingChats={false}
+      isLoadingHistory={false}
+      promoStorage="local"
+    />
+  )
+}
+```
+
+**Source:** [`mingo-welcome.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/mingo-welcome.tsx)

package/src/components/chat/.model-display.md

@@ -1,46 +1,54 @@
-<!-- source-hash: 75472e90962007832fb7ea753283d69c -->
-Renders an inline pill showing the AI provider icon, model name, and token usage against the context window. When per-call token breakdown data is available, a hover card expands to show input/output splits across the answer model and any auxiliary Haiku sub-agents (rewriter, classifier, summarizer), plus an optional prompt-cache hit rate.
+<!-- source-hash: 5ec42a1329af78781e4ae04ac5e8abe8 -->
+Renders an inline pill showing the AI model provider icon, model name, and token usage, with an optional hover card that breaks down token consumption across sub-models (rewriter, classifier, summarizer).
 
 ## Key Components
 
-| Export / Function | Description |
-|---|---|
-| `ModelDisplay` | Primary `forwardRef` component rendering the inline token pill and optional hover card breakdown |
-| `BreakdownRow` | Internal helper rendering a single `label / X in / Y out` row in the hover card |
-| `getProviderIcon` | Maps provider string (`anthropic`, `openai`, `google`, etc.) to the corresponding grey logo icon |
-| `formatTokenCount` | Formats raw token integers to human-readable strings (`1.2K`, `200M`, etc.) |
-| `hasAnyBreakdownRow` | Guards hover card rendering — returns `true` only when at least one Haiku sub-agent row exists |
+| Export | Type | Description |
+|--------|------|-------------|
+| `ModelDisplay` | `React.forwardRef` component | Primary display pill with provider icon, model name, token counter, and hover breakdown card |
+| `ModelDisplaySkeleton` | `React.forwardRef` component | Loading placeholder that mirrors `ModelDisplay` layout to prevent layout shift |
+| `BreakdownRow` | Internal component | Single row in the hover card showing input/output token counts for one model call |
+| `getProviderIcon` | Helper function | Maps provider string (`anthropic`, `openai`, `google`, etc.) to the matching grey logo icon |
+| `formatTokenCount` | Helper function | Formats raw token integers to human-readable strings (`1.2K`, `200M`) |
 
 ## Usage Example
 
 ```typescript
-import { ModelDisplay } from './model-display';
-
-// Minimal — inline pill only (no hover card)
+// Basic pill — shows provider icon + name only
 <ModelDisplay
   provider="anthropic"
   modelName="claude-opus-4-5"
   displayName="Claude Opus"
-  usedTokens={12_400}
-  contextWindow={200_000}
 />
 
-// With full breakdown — activates hover card on mouse-over
+// With token usage counter (renders once contextWindow is known)
+<ModelDisplay
+  provider="openai"
+  modelName="gpt-4o"
+  usedTokens={12340}
+  contextWindow={128000}
+  inputTokens={10000}
+  outputTokens={2340}
+/>
+
+// With sub-model breakdown (enables hover card)
 <ModelDisplay
   provider="anthropic"
   modelName="claude-opus-4-5"
-  displayName="Claude Opus"
-  usedTokens={18_750}
-  contextWindow={200_000}
-  inputTokens={15_200}
-  outputTokens={3_550}
-  hitRatePct={34}
+  usedTokens={15000}
+  contextWindow={200000}
+  inputTokens={12000}
+  outputTokens={3000}
+  hitRatePct={42}
   breakdown={{
-    haikuRewriter:   { input: 420,  output: 80  },
-    haikuClassifier: { input: 310,  output: 45  },
-    haikuSummarizer: { input: 1100, output: 200 },
+    haikuRewriter:   { input: 500,  output: 200 },
+    haikuClassifier: { input: 300,  output: 100 },
+    haikuSummarizer: { input: 1200, output: 400 },
   }}
 />
+
+// Skeleton during loading — opt-in token tail placeholder
+<ModelDisplaySkeleton showTokens />
 ```
 
-> **Note:** The `usedTokens` / `contextWindow` tail renders as soon as `contextWindow` is available, intentionally showing `—/200K tokens used` before the first usage frame arrives so users can see model capacity without waiting for streaming to begin.
+The hover card only mounts when at least one `breakdown` sub-model row (`haikuRewriter`, `haikuClassifier`, `haikuSummarizer`) is present, avoiding unnecessary accessibility chrome on surfaces that don't capture cross-call usage.

package/src/components/chat/.msp-organization-card-skeleton.md

@@ -0,0 +1,44 @@
+<!-- source-hash: c9249823535d22722e2d0a1620a2ff31 -->
+Loading placeholder that mirrors the layout of `MspOrganizationCard` — preserving dimensions during data fetch to prevent layout shift on the welcome screen.
+
+## Key Components
+
+### `MspOrganizationCardSkeleton`
+
+A shimmer placeholder component that replicates the visual structure of `MspOrganizationCard` with three skeleton blocks:
+
+- **Logo placeholder** — 48×48px square (left)
+- **Text placeholders** — title line (60% width) and website line (40% width) stacked vertically
+- **Action button placeholder** — 48×48px square (right)
+
+### `MspOrganizationCardSkeletonProps`
+
+| Prop | Type | Description |
+|---|---|---|
+| `className` | `string` (optional) | Appended to the root element for layout overrides |
+
+## Usage Example
+
+```typescript
+import { MspOrganizationCardSkeleton } from './msp-organization-card-skeleton'
+
+// Show while tenant data is loading
+function WelcomeScreen() {
+  const { data, isLoading } = useTenantInfo()
+
+  if (isLoading) {
+    return <MspOrganizationCardSkeleton />
+  }
+
+  return <MspOrganizationCard {...data} />
+}
+
+// With a custom class override
+<MspOrganizationCardSkeleton className="my-4 max-w-sm" />
+```
+
+## Notes
+
+- Rendered as a client component (`'use client'`)
+- Uses the same container dimensions and spacing tokens (`--spacing-system-m`) as `MspOrganizationCard`, ensuring a seamless swap once data resolves
+- Source: [`msp-organization-card-skeleton.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/msp-organization-card-skeleton.tsx)

package/src/components/chat/.msp-organization-card.md

@@ -0,0 +1,51 @@
+<!-- source-hash: d24890257e6931aa4965bfc927c49767 -->
+Renders a horizontal card identifying the MSP organization managing a user's IT, designed for AI Assistant welcome screens.
+
+## Key Components
+
+**`MspOrganizationCard`** — Primary export. Composes a square org logo (`SquareAvatar`), a title/website text block, and an optional external-link button into a styled card matching Figma spec `openframe — fae-chat` (node 1:5540).
+
+**`MspOrganizationCardProps`** — Interface defining all accepted props:
+
+| Prop | Type | Description |
+|---|---|---|
+| `name` | `string` | Organization name; used in default title and avatar fallback |
+| `website` | `string?` | Displayed beneath the title |
+| `logoUrl` | `string?` | Logo URL; falls back to initials when absent |
+| `title` | `React.ReactNode?` | Overrides the default "Your IT is managed by {name}" title |
+| `href` | `string?` | Renders trailing action as `<a target="_blank">` |
+| `onOpenWebsite` | `() => void?` | Click handler when `href` is not provided |
+| `className` | `string?` | Appended to the root element |
+
+**Trailing action priority:** `href` (anchor) → `onOpenWebsite` (button) → hidden.
+
+## Usage Example
+
+```typescript
+// With a direct link (renders as anchor)
+<MspOrganizationCard
+  name="TechFlow IT"
+  website="www.techflow.com"
+  logoUrl="https://cdn.example.com/techflow-logo.png"
+  href="https://www.techflow.com"
+/>
+
+// With a click handler
+<MspOrganizationCard
+  name="TechFlow IT"
+  website="www.techflow.com"
+  onOpenWebsite={() => router.push('/org-info')}
+/>
+
+// Custom title, no action button
+<MspOrganizationCard
+  name="TechFlow IT"
+  title={<strong>Supported by TechFlow IT</strong>}
+/>
+```
+
+## Notes
+
+- Uses an inset `ring-1` instead of `border` to preserve the 80px frame height matching Figma's inside-aligned stroke.
+- Styles are driven by ODS design tokens (`--spacing-system-m`, `ods-bg`, `ods-border`, `ods-text-primary`).
+- Source: [`msp-organization-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/msp-organization-card.tsx)