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

package/src/components/.vendor-tag.md

@@ -1,49 +1,54 @@
-<!-- source-hash: 288686d02f75f571a8af9576a88762b3 -->
-A React component that renders categorized vendor tags with icons and styling for different software types and classifications.
+<!-- source-hash: f936efb725972b55ffa32204b6306bc7 -->
+A client-side React component that renders styled badge tags for categorizing vendors, tools, and platform capabilities within the OpenFrame design system.
 
 ## Key Components
 
-- **VendorTag**: Main component that displays a styled tag with icon and text based on vendor type
-- **VendorTagProps**: Interface defining props including type, text, styling options, and size variants
-- **getTagContent()**: Internal function that maps vendor types to their corresponding icons, colors, and display text
+### `VendorTagProps` Interface
 
-## Supported Tag Types
+| Prop | Type | Description |
+|---|---|---|
+| `type` | union (14 variants) | Determines icon, label, and color scheme |
+| `text` | `string` | Optional override for the default display label |
+| `className` | `string` | Additional CSS classes |
+| `size` | `'sm' \| 'md'` | Controls padding; defaults to `'md'` |
+| `hidden` | `boolean` | Applies `invisible` class when `true` |
+| `accentColor` | `string` | Inline color override for the icon box (open-source type only) |
 
-The component supports various vendor classifications:
-- **Licensing**: `open-source`, `commercial`, `free`, `freemium`, `paid`, `enterprise`
-- **Selection**: `ai`, `manual`, `openframe_selected`, `recommended`
-- **Generic**: `classification`, `placeholder`
+### `VendorTag` Function
 
-Each type has predefined styling, icons, and color schemes with support for custom accent colors and text overrides.
+Renders a pill-shaped tag with a small icon box and a label. The internal `getTagContent()` helper maps each `type` to its icon, default text, and text color using ODS design tokens (`ods-accent`, `ods-border`, `ods-text-primary`, etc.).
+
+**Supported types:**
+
+- **Licensing:** `open-source`, `commercial`, `free`, `freemium`, `paid`, `enterprise`
+- **Platform capability:** `api`, `data`, `k8s`, `secured`
+- **Selection state:** `ai`, `manual`, `openframe_selected`, `placeholder`
+- **Meta:** `recommended`, `classification` (sub-dispatches on `text` value)
 
 ## Usage Example
 
 ```typescript
-import { VendorTag } from './vendor-tag'
+import { VendorTag } from "./vendor-tag"
 
-// Basic open source tag
+// Basic licensing badge
 <VendorTag type="open-source" />
 
-// Custom commercial tag with accent color
-<VendorTag 
-  type="commercial" 
-  text="Enterprise Solution" 
-  accentColor="#ff6b35"
-  size="sm"
-/>
-
-// AI-selected tag with custom styling
-<VendorTag 
-  type="ai"
-  className="ml-2"
-  hidden={!showTags}
-/>
-
-// Classification tag with dynamic content
-<VendorTag 
-  type="classification"
-  text="openframe_selected"
-/>
+// Custom label with accent color override
+<VendorTag type="open-source" text="Apache 2.0" accentColor="#e07b39" />
+
+// Small AI-selection badge
+<VendorTag type="ai" size="sm" />
+
+// Platform capability tags
+<VendorTag type="k8s" />
+<VendorTag type="secured" text="SOC 2" />
+
+// Classification (text drives sub-type)
+<VendorTag type="classification" text="open_source" />
+<VendorTag type="classification" text="openframe_selected" />
+
+// Hidden (preserves layout space)
+<VendorTag type="recommended" hidden />
 ```
 
-The component uses Tailwind CSS classes with a dark theme design system (`ods-*` custom colors) and includes responsive sizing options.
+**Source:** [`vendor-tag.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/vendor-tag.tsx)

package/src/components/.why-it-matters.md

@@ -1,14 +1,13 @@
-<!-- source-hash: 0a0456d4a0a372cdfeb0bc7afca3a55f -->
-A Next.js client component that renders a numbered list section highlighting the key value propositions of the OpenFrame/Flamingo platform.
+<!-- source-hash: 8bdfd0b0bb8aed0edd883e829a021abf -->
+A client-side React section component that renders a numbered list of value propositions explaining the benefits of the OpenFrame/Flamingo platform.
 
 ## Key Components
 
 ### `WhyItMattersItem` (internal)
-A list item component rendering a numbered entry with title and description. Accepts:
-- `number` — display number string (e.g. `"1."`)
-- `title` — short benefit headline
-- `description` — supporting copy
-- `isLast?` — omits bottom border on the final item
+A list item component rendering a single value proposition with:
+- **Props:** `number` (display numeral), `title`, `description`, `isLast` (controls bottom border visibility)
+- Responsive layout: stacked on mobile (`flex-col`), side-by-side on desktop (`md:flex-row`)
+- Hover highlight via `hover:bg-ods-bg-hover`
 
 ### `WhyItMatters` (default export)
 The parent section component containing four hardcoded value propositions:
@@ -22,12 +21,17 @@ The parent section component containing four hardcoded value propositions:
 
 ## Usage Example
 
+```vue
+<!-- Drop into any page layout as a standalone section -->
+```
+
 ```typescript
 import WhyItMatters from '@/components/why-it-matters';
 
 export default function LandingPage() {
   return (
     <main>
+      {/* other sections */}
       <WhyItMatters />
     </main>
   );
@@ -36,7 +40,7 @@ export default function LandingPage() {
 
 ## Notes
 
-- Marked `"use client"` — requires a Next.js App Router client boundary.
-- Styled with Tailwind CSS using `ods-` design tokens (`ods-accent`, `ods-border`, `ods-text-primary`, `ods-card`).
-- Items hover to `#2A2A2A` with a smooth transition for subtle interactivity.
-- Layout is responsive: stacks vertically on mobile (`flex-col`), switches to row on `md+`.
+- Uses `"use client"` directive — requires a Next.js App Router client boundary
+- Styling relies on ODS design tokens (`ods-bg`, `ods-card`, `ods-border`, `ods-accent`, `ods-text-primary`) — ensure the ODS theme is configured in Tailwind
+- `SECTION_HEADING_CLASS` is imported from [`./layout/page-heading`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/layout/page-heading.ts) for consistent section heading typography
+- Content is currently static; extract `items` to props or a CMS if copy needs to vary per page

package/src/components/.yes-no-display.md

@@ -1,12 +1,28 @@
-<!-- source-hash: 7b9908b3b26a126e9c2fb26254d2a3dc -->
-A React component for displaying boolean values with appropriate icons and text, plus utility logic for evaluating feature values across different data types.
+<!-- source-hash: 5d8965c2105bee8651e70267abd0b3db -->
+A React client component for rendering boolean values as icon-accompanied Yes/No indicators, plus a utility function for evaluating feature flag values across multiple data types.
 
 ## Key Components
 
-- **YesNoDisplay**: Main React component that renders boolean values with check/X icons
-- **evaluateFeatureValue**: Utility function that determines boolean state from various data formats (boolean, text, number)
+### `YesNoDisplay` (Component)
 
-The component supports customizable yes/no text, custom text override, and flexible styling through className props.
+Renders a boolean state with an icon and label. Supports custom text override, configurable Yes/No labels, and optional CSS class extension.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `boolean` | — | The boolean state to display |
+| `yesText` | `string` | `"Yes"` | Label shown for truthy state |
+| `noText` | `string` | `"No"` | Label shown for falsy state |
+| `customText` | `string` | — | Overrides Yes/No logic; always renders with check icon |
+| `className` | `string` | `""` | Additional CSS classes |
+
+### `evaluateFeatureValue` (Utility)
+
+Normalizes raw feature values (`string | null | undefined`) to a `boolean` using type-aware rules:
+
+- **`boolean`** — matches `"true"`, `"1"`, `"yes"`, `"✓"`, `"✅"`
+- **`text`** — emoji-aware; treats any non-empty, non-negative string as truthy
+- **`number`** — parses float; truthy if `> 0`
+- Null-like sentinels (`"null"`, `"n/a"`, `"none"`, `"-"`) always return `false`
 
 ## Usage Example
 
@@ -14,31 +30,20 @@ The component supports customizable yes/no text, custom text override, and flexi
 import { YesNoDisplay, evaluateFeatureValue } from './yes-no-display'
 
 // Basic boolean display
-<YesNoDisplay value={true} />
-
-// Custom text labels
-<YesNoDisplay 
-  value={false} 
-  yesText="Active" 
-  noText="Inactive" 
-/>
-
-// Custom text override
-<YesNoDisplay 
-  value={true} 
-  customText="Premium Feature Available" 
-/>
-
-// Evaluate feature values
-const isEnabled = evaluateFeatureValue("✅", "text")  // true
-const isActive = evaluateFeatureValue("0", "number")  // false
-const hasFeature = evaluateFeatureValue("yes", "boolean")  // true
-
-// Use together
-<YesNoDisplay 
-  value={evaluateFeatureValue(featureData.value, featureData.type)}
-  className="my-2"
-/>
+<YesNoDisplay value={true} />                          // ✓ Yes
+<YesNoDisplay value={false} yesText="Enabled" noText="Disabled" />
+
+// Custom text (always shows check icon)
+<YesNoDisplay value={true} customText="Included in plan" />
+
+// Evaluate raw feature flag values before rendering
+const isEnabled = evaluateFeatureValue("✅", "text")   // true
+const hasCount  = evaluateFeatureValue("42", "number") // true
+const missing   = evaluateFeatureValue("n/a", "boolean") // false
+
+<YesNoDisplay value={isEnabled} />
 ```
 
-The `evaluateFeatureValue` function handles various input formats including emojis (✅/❌), text values ("yes"/"no"), numbers (>0 is true), and explicit null/empty states.
+## Source
+
+[`yes-no-display.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/yes-no-display.tsx)

package/src/components/authors/.author-detail-view.md

@@ -0,0 +1,50 @@
+<!-- source-hash: d20279dde85e1fcd84bfce0068c08fca -->
+A presentational component that renders a full author profile page body — identity header (avatar, name, job title, socials), bio, expertise badges, and a slot for the authored-content rail.
+
+## Key Components
+
+### `AuthorDetailViewProps`
+
+| Prop | Type | Description |
+|---|---|---|
+| `author` | `AuthorProfile` | Full author data object |
+| `proxyImageUrl` | `(url: string) => string` | Optional host-level avatar URL mapper; takes precedence over the ambient runtime proxy |
+| `children` | `React.ReactNode` | Authored-content rail slot (hub passes SSR-prefetched section; embedders pass API-backed section) |
+| `className` | `string` | Optional wrapper class override |
+
+### `AuthorDetailView`
+
+The exported component. Handles:
+
+- **Avatar proxying** — resolves through `proxyImageUrl` prop → `ChatRuntime.endpoints.imageProxyUrlPrefix` → raw URL (never throws without a provider)
+- **Identity header** — avatar (or initial fallback), name as `<p>` (host owns `<h1>`), subtitle (`jobTitle @ company`), and social icon row
+- **Bio** — formatted via `formatBioText`
+- **Expertise badges** — `StatusBadge` per `knowsAbout` entry
+- **Content slot** — renders `children` as-is beneath the profile
+
+## Usage Example
+
+```typescript
+// Hub usage — SSR content rail passed as children
+<AuthorDetailView author={authorProfile}>
+  <RelatedContentSection
+    authorSlug={authorProfile.slug}
+    initialItems={ssrItems}
+  />
+</AuthorDetailView>
+
+// Embed usage — custom proxy + API-backed content rail
+<AuthorDetailView
+  author={authorProfile}
+  proxyImageUrl={(url) => `/media-proxy?src=${encodeURIComponent(url)}`}
+>
+  <AuthoredContentSection
+    authorSlug={authorProfile.slug}
+    apiBaseUrl="https://api.example.com"
+  />
+</AuthorDetailView>
+```
+
+> **Embed contract:** `Image` renders through the embed shim (plain `<img>` outside Next.js hosts). The component is data-in, markup-out — no internal fetches.
+
+**Source:** [`author-detail-view.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/author-detail-view.tsx)

package/src/components/case-studies/.index.md

@@ -0,0 +1,26 @@
+<!-- source-hash: c59db722e44565f70c23008e3894c6d4 -->
+Barrel export file that re-exports the `ShareExperienceSection` component and its associated `ShareExperienceSectionProps` type from the `share-experience-section` module.
+
+## Key Components
+
+- **`ShareExperienceSection`** — The main component for rendering a "share experience" UI section.
+- **`ShareExperienceSectionProps`** — TypeScript type definition for the component's props.
+
+## Usage Example
+
+```typescript
+import {
+  ShareExperienceSection,
+  type ShareExperienceSectionProps,
+} from '@/components/share-experience-section'
+
+const props: ShareExperienceSectionProps = {
+  // component-specific props
+}
+
+export default function Page() {
+  return <ShareExperienceSection {...props} />
+}
+```
+
+> **Source:** [`index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts)

package/src/components/case-studies/.share-experience-section.md

@@ -0,0 +1,45 @@
+<!-- source-hash: aa11a1879c86772619c2a16ae6fa5a48 -->
+A client-side React section component that renders the "Share Your Experience" CTA block used on the Flamingo case-studies page, displaying review platform cards (G2, Capterra, TrustPilot, GetApp) alongside an embedded contact form.
+
+## Key Components
+
+- **`ShareExperienceSection`** — Main exported component; composes the heading, subtitle, "How it works" block, review platform benefit cards, and a `ContactForm` into a unified CTA section.
+- **`ShareExperienceSectionProps`** — Interface exposing overridable props: `title`, `subtitle`, `howItWorksTitle`, `howItWorksBody`, `contactFormProps`, and `className`.
+- **`DEFAULT_CONTACT_FORM_PROPS`** — Pre-configured `ContactForm` defaults (prefilled reason/message, hidden fields, outline button style) matching the hub's `/case-studies` behavior; caller-supplied `contactFormProps` take precedence via spread order.
+
+## Usage Example
+
+**Hub usage (auto-resolved context):**
+
+```typescript
+<ShareExperienceSection
+  contactFormProps={{
+    userId: currentUser.id,
+    rdtCid: rdtCid,
+    onSubmitSuccess: () => router.push('/case-studies/thank-you'),
+  }}
+/>
+```
+
+**Embed usage (brand-neutral override):**
+
+```typescript
+<ShareExperienceSection
+  title="Share Your Experience"
+  subtitle="Help other IT teams make better decisions."
+  howItWorksTitle="How it works?"
+  howItWorksBody="Submit your details and we'll be in touch."
+  contactFormProps={{
+    successRedirectUrl: '/thank-you',
+  }}
+  className="my-16"
+/>
+```
+
+**Minimal usage (all defaults):**
+
+```typescript
+<ShareExperienceSection />
+```
+
+The inner `ContactForm` submits through the ambient `EndpointsRuntime.contactUrl` proxy, so no per-call-site API wiring is required for embedded deployments behind a `/content` reverse proxy.

package/src/components/chat/.approval-batch-message.md

@@ -1,51 +1,66 @@
-<!-- source-hash: 0d9faa5f98d4a04ec4d4d1a8221ac7cd -->
-A React component that renders a batch of pending AI tool-call approvals, allowing users to approve or reject multiple tool executions at once, with expandable argument details and live execution status indicators.
+<!-- source-hash: 53c5e53d9aa5256ad542ac1abea08fb2 -->
+Renders an approval batch message UI component that displays pending AI tool calls requiring user approval, with support for both admin and client (end-user) variants, expandable tool call details, and real-time execution status tracking.
 
 ## Key Components
 
 ### `ApprovalBatchMessage` (default export)
-A `forwardRef` component that renders the full approval card. Accepts:
+The main `forwardRef` component rendering a bordered card containing one or more tool call rows, explanation bullets, and Approve/Reject action buttons.
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `data` | `ApprovalBatchSegment["data"]` | Tool calls, executions, and request ID |
-| `status` | `ApprovalBatchSegment["status"]` | `"pending"` \| `"approved"` \| `"rejected"` |
-| `onApprove` | `(requestId?) => void \| Promise<void>` | Called when user approves the batch |
-| `onReject` | `(requestId?) => void \| Promise<void>` | Called when user rejects the batch |
+**Key props:**
+- `data` — batch segment data including tool calls and approval request ID
+- `status` — `"pending"` | `"approved"` | `"rejected"` | `"cancelled"`
+- `onApprove` / `onReject` — async callbacks receiving the `requestId`
+- `variant` — `"admin"` (full preview, expandable args/results) or `"client"` (titles + actions only)
+- `maxBodyHeight` — constrains tool list height with internal scroll
+- `showExecutionStatus` — toggles per-tool execution spinner/check/cross icons
+- `showFooterActions` — hides Approve/Reject when host owns the action row
+- `resolvedByName` — name shown alongside the resolved status tag
+
+### `ApprovalStatusTag`
+Standalone badge for resolved batches. Renders a `Tag` component with icon for `approved`, `rejected`, or `cancelled` states; returns `null` while pending. Supports `inlineResolver` to embed `"by {name}"` inside the pill.
 
 ### `ToolCallRow` (internal)
-Renders a single collapsible tool call row showing the command text, filtered arguments via `ArgRow`, execution result via `ResultBlock`, and a live `ExecutionStatusIcon`.
+Admin-only collapsible row showing tool icon, command preview, execution status icon, and expandable arguments/result block.
 
 ### `ExecutionStatusIcon` (internal)
-Displays the per-tool execution state:
-- **Pending batch** → hidden
-- **Approved / executing** → `DotsLoaderIcon` (spinner)
-- **Done + success** → green `CheckCircleIcon`
-- **Done + failure** → red `XmarkCircleIcon`
-
-### Helper: `getArgEntries`
-Filters tool call arguments, excluding body-level keys (via `COMMAND_BODY_KEYS`) and null/empty values.
+Resolves the correct icon based on batch status and per-tool execution state: `DotsLoaderIcon` while queued/executing, `CheckCircleIcon` on success, `XmarkCircleIcon` on failure.
 
 ## Usage Example
 
 ```typescript
-import { ApprovalBatchMessage } from "./approval-batch-message"
+import { ApprovalBatchMessage } from "@openframe/ui"
 
+// Admin view — full command preview with execution tracking
 <ApprovalBatchMessage
-  data={{
-    approvalRequestId: "req_123",
-    toolCalls: [
-      {
-        toolExecutionRequestId: "exec_1",
-        toolType: "SHELL",
-        toolCallArguments: { command: "ls -la" },
-        toolExplanation: "List directory contents",
-      },
-    ],
-    executions: {},
+  data={batch.data}
+  status={batch.status}
+  variant="admin"
+  showExecutionStatus
+  maxBodyHeight={400}
+  resolvedByName="Jane Doe"
+  onApprove={async (requestId) => {
+    await approveRequest(requestId)
+  }}
+  onReject={async (requestId) => {
+    await rejectRequest(requestId)
   }}
-  status="pending"
-  onApprove={(id) => console.log("Approved:", id)}
-  onReject={(id) => console.log("Rejected:", id)}
+/>
+
+// Client (Fae end-user) view — titles + action buttons only
+<ApprovalBatchMessage
+  data={batch.data}
+  status={batch.status}
+  variant="client"
+  resolvedByName="Jane Doe"
+  onApprove={handleApprove}
+  onReject={handleReject}
+/>
+
+// Notification tile — host owns the action row
+<ApprovalBatchMessage
+  data={batch.data}
+  status={batch.status}
+  showFooterActions={false}
+  showExecutionStatus={false}
 />
 ```

package/src/components/chat/.approval-request-message.md

@@ -1,45 +1,56 @@
-<!-- source-hash: 8ff0735cc63d1ea7a83dab6aab9e0cc6 -->
-A React component that renders an AI approval request card with pending (Approve/Reject buttons) and resolved (status tag) states, used in Mingo AI's chat interface for human-in-the-loop action confirmation.
+<!-- source-hash: 3efe25cb3a6b4446309ff83a123a65c3 -->
+A React component that renders an individual approval request card in two variants — `admin` (technician-facing, shows raw command + structured fields) and `client` (Fae end-user-facing, shows only the human-readable explanation). Both variants switch between a pending state with Approve/Reject actions and a resolved state with a status tag.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `ApprovalRequestMessage` | `forwardRef` component | Main approval card with pending/resolved display states |
-| `ApprovalCardBody` | Internal component | Shared card body (command block + fields/explanation) |
-| `ApprovalFieldList` | Internal component | Stacked label/value `<dl>` rows for structured fields |
+| Export / Symbol | Description |
+|---|---|
+| `ApprovalRequestMessage` | Primary `forwardRef` component — the main export |
+| `ApprovalCardBody` | Internal shared body (command block + fields/explanation) rendered for the `admin` variant |
+| `ApprovalFieldList` | Internal `<dl>`-based renderer for structured `label/value` field pairs |
+
+**Props (`ApprovalRequestMessageProps`):**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `ApprovalRequestData` | — | Command, fields, explanation, requestId |
+| `status` | `'pending' \| 'approved' \| 'rejected' \| 'cancelled'` | `'pending'` | Controls action vs. resolved UI |
+| `variant` | `'admin' \| 'client'` | `'admin'` | Switches between technician and end-user layout |
+| `onApprove` | `(requestId) => Promise<void>` | — | Callback fired on Approve click |
+| `onReject` | `(requestId) => Promise<void>` | — | Callback fired on Reject click |
+| `resolvedByName` | `string` | — | Name shown in resolved status tag (client variant) |
+| `assistantType` | `string` | — | Accepted for prop parity with batch card; unused internally |
 
 ## Usage Example
 
 ```typescript
 import { ApprovalRequestMessage } from "./approval-request-message"
 
-// Pending state — shows Approve / Reject buttons
+// Admin (technician) view — shows command block and structured fields
 <ApprovalRequestMessage
+  variant="admin"
+  status="pending"
   data={{
-    requestId: "req_abc123",
-    command: "apt-get install nginx --yes",
-    explanation: "Installing nginx on the production web server.",
+    requestId: "req_123",
+    command: "net user jdoe /domain",
     fields: [
-      { label: "Host", value: "web-01.prod" },
-      { label: "Risk", value: "Low" },
+      { label: "Ticket", value: "#4821" },
+      { label: "Requested By", value: "John Doe" },
     ],
   }}
-  status="pending"
-  onApprove={async (id) => await approveAction(id)}
-  onReject={async (id) => await rejectAction(id)}
+  onApprove={async (id) => await approveRequest(id)}
+  onReject={async (id) => await rejectRequest(id)}
 />
 
-// Resolved state — shows Approved/Rejected tag
+// Client (Fae end-user) view — shows explanation only
 <ApprovalRequestMessage
-  data={{ requestId: "req_abc123", command: "apt-get install nginx --yes" }}
+  variant="client"
   status="approved"
+  data={{
+    requestId: "req_123",
+    command: "net user jdoe /domain",
+    explanation: "Your technician needs to look up your domain account.",
+  }}
+  resolvedByName="Alex T."
 />
-```
-
-## Behavior Notes
-
-- `status` defaults to `"pending"`; transitions to `"approved"` or `"rejected"` render a `<Tag>` with a `CheckCircle` or `XCircle` icon respectively
-- Both `handleApprove` and `handleReject` set `isProcessing = true` during the async callback, disabling both buttons to prevent double-submission
-- `fields` take rendering priority over `explanation` — if both are provided, only `fields` is shown
-- The command block is scrollable (`max-h-32 overflow-y-auto`) for long commands
+```

package/src/components/chat/.chat-archive-page.md

@@ -0,0 +1,56 @@
+<!-- source-hash: c499bb92cb1ddfd48e76787dd129e08f -->
+Renders the Chat Archive page UI, displaying date-grouped archived dialogs with conditional loading states, and supports both a standalone mode (with its own back/close header) and an embedded mode (headerless, for split layouts).
+
+## Key Components
+
+### `ChatArchivePage`
+Main exported component that orchestrates the archive view. Conditionally renders:
+- **Mobile header** (`ChatPanelHeaderMobile`) — back + close controls on small screens
+- **Desktop header** — fixed-height bar with `ChatHeaderIconButton` cells for back/close
+- **`MingoChatHistory`** — date-grouped dialog list when dialogs exist
+- **`MingoChatHistorySkeleton`** — grouped placeholder during first-load
+- **`ChatListEmptyState`** — archive-specific empty state with `BoxArchiveIcon`
+
+### Props Interfaces
+
+| Interface | Description |
+|---|---|
+| `ChatArchivePageStandaloneProps` | Requires `onBack` and `onClose`; renders its own header |
+| `ChatArchivePageEmbeddedProps` | Sets `embedded: true`; omits header and forbids `onBack`/`onClose` |
+| `ChatArchivePageBaseProps` | Shared: `dialogs`, `onSelectDialog`, `isLoading`, `isFetching`, `hasMore`, `onLoadMore` |
+
+## Usage Example
+
+```typescript
+// Standalone mode (default)
+<ChatArchivePage
+  dialogs={archivedDialogs}
+  onSelectDialog={(id) => openDialog(id)}
+  onBack={() => setView('list')}
+  onClose={() => setPanelOpen(false)}
+  isLoading={isLoadingArchive}
+  isFetching={isFetchingArchive}
+  hasMore={hasNextPage}
+  onLoadMore={fetchNextPage}
+/>
+
+// Embedded mode (split layout — host provides header)
+<ChatArchivePage
+  embedded
+  dialogs={archivedDialogs}
+  onSelectDialog={(id) => openDialog(id)}
+  isLoading={isLoadingArchive}
+/>
+```
+
+## Loading State Precedence
+
+```mermaid
+graph TD
+    A{dialogs.length > 0?} -->|Yes| B[MingoChatHistory]
+    A -->|No| C{isLoading?}
+    C -->|Yes| D[MingoChatHistorySkeleton]
+    C -->|No| E{isFetching?}
+    E -->|Yes| F[null - suppress flash]
+    E -->|No| G[ChatListEmptyState]
+```