@flamingo-stack/openframe-frontend-core 0.0.438-snapshot.20260716203356 → 0.0.438

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

@@ -168,17 +168,17 @@ export function GuideWelcome({
                 cornerColor="var(--ods-flamingo-cyan-base)"
               />
             )}
-            <div className="flex w-full flex-col gap-[var(--spacing-system-l)]">
-              <p className="text-h2 text-ods-text-primary">{title}</p>
+            <div className="flex w-full flex-col gap-1">
+              <p className="text-h4 text-ods-text-primary">{title}</p>
               {/* Sub-line: while the greeting is still being fetched show a
                   one-line skeleton; once settled, render the greeting (admin
                   copy / host override) or nothing — no built-in default, so by
                   default the empty state shows the title alone. */}
               {subtitle ? (
-                <p className="text-h4 text-ods-text-secondary">{subtitle}</p>
+                <p className="text-h6 text-ods-text-secondary">{subtitle}</p>
               ) : subtitleLoading ? (
                 <div className="flex w-full justify-center">
-                  <Skeleton className="h-5 w-3/4 max-w-80 rounded-sm" />
+                  <Skeleton className="h-4 w-3/4 max-w-80 rounded-sm" />
                 </div>
               ) : null}
             </div>

package/src/components/chat/hooks/use-chat-dialog-manager.ts

@@ -1,6 +1,6 @@
 'use client'
 
-import { useCallback, useMemo, useRef, useState } from 'react'
+import { useCallback, useMemo, useState } from 'react'
 import type { DialogItem } from '../types/component.types'
 import type {
   FetchDialogsParams,
@@ -84,68 +84,28 @@ export function useChatDialogManager({
   const [archivedDialogs, setArchivedDialogs] = useState<DialogItem[]>([])
   const [archivedCursor, setArchivedCursor] = useState<string | null>(null)
   const [archivedLoading, setArchivedLoading] = useState(false)
-  // A fetch is in flight, tracked SEPARATELY from the delayed skeleton
-  // (`archivedLoading`). Set synchronously so the empty state stays suppressed
-  // during the 120ms skeleton delay — otherwise an uncached first open flashes
-  // "No archived chats" before the skeleton/data appears.
-  const [archivedPending, setArchivedPending] = useState(false)
-  // Monotonic request id — a background page-1 refresh and a pagination fetch
-  // can overlap (the retained list stays interactive while page 1 revalidates).
-  // Only the LATEST request may mutate the list / cursor / loading flags, so a
-  // slow earlier response can't clobber newer rows, append stale ones, or clear
-  // the shared loading flag while another request is still in flight.
-  const archivedRequestIdRef = useRef(0)
   const loadArchivedPage = useCallback(
     async (cursor?: string): Promise<void> => {
       if (!fetchArchivedDialogs) return
-      const requestId = ++archivedRequestIdRef.current
-      const isCurrent = () => archivedRequestIdRef.current === requestId
-      // Only a first-page load drives the full-view skeleton, and only if it's
-      // actually slow: a 120ms delay means a cached/fast fetch (the host caches
-      // page 1) resolves first and never flashes a skeleton. Pagination
-      // (`cursor`) keeps the current list visible.
-      const isInitial = !cursor
-      setArchivedPending(true)
-      let skeletonTimer: ReturnType<typeof setTimeout> | undefined
-      if (isInitial) {
-        // Delay the full-view skeleton so a cached/fast page-1 fetch never
-        // flashes it (and skip it if a newer request already superseded us).
-        skeletonTimer = setTimeout(() => {
-          if (isCurrent()) setArchivedLoading(true)
-        }, 120)
-      } else {
-        // Pagination shows its "load more" indicator immediately (the list
-        // stays visible), so no delay here.
-        setArchivedLoading(true)
-      }
+      setArchivedLoading(true)
       try {
         const result = await fetchArchivedDialogs({ cursor, limit: 20 })
-        // A newer request superseded this one — drop the response so overlapping
-        // refresh / pagination can't append stale rows or clobber newer results.
-        if (!isCurrent()) return
         setArchivedCursor(result.nextCursor)
         setArchivedDialogs((prev) =>
           cursor ? [...prev, ...result.dialogs] : result.dialogs,
         )
       } catch (err) {
-        if (!isCurrent()) return
         console.error('[useChatDialogManager] fetchArchivedDialogs failed:', err)
       } finally {
-        if (skeletonTimer) clearTimeout(skeletonTimer)
-        // Only the latest request owns the shared loading / pending flags.
-        if (isCurrent()) {
-          setArchivedLoading(false)
-          setArchivedPending(false)
-        }
+        setArchivedLoading(false)
       }
     },
     [fetchArchivedDialogs],
   )
   const openArchive = useCallback(() => {
     setArchiveOpen(true)
-    // Don't clear the list — keep any already-loaded page visible and refresh
-    // page 1 in the background (stale-while-revalidate), so reopening the
-    // archive within a session doesn't blank out to a skeleton.
+    setArchivedDialogs([])
+    setArchivedCursor(null)
     void loadArchivedPage()
   }, [loadArchivedPage])
   const closeArchive = useCallback(() => setArchiveOpen(false), [])
@@ -223,18 +183,6 @@ export function useChatDialogManager({
     if (wasArchived) setArchiveOpen(true)
   }, [isViewingArchived, selectDialog, clearMessages])
 
-  // "Start New Chat" reset — clears the open conversation and ALWAYS lands on
-  // the new-chat welcome. Unlike `handleBack`, it never reopens the archive
-  // (backing out of an archived chat returns to the archive; starting a NEW
-  // chat must not), so the archive is force-closed here regardless of state.
-  const resetToNewChat = useCallback(() => {
-    setViewingArchivedId(null)
-    setOpeningDialogId(null)
-    selectDialog(null)
-    clearMessages()
-    setArchiveOpen(false)
-  }, [selectDialog, clearMessages])
-
   // Active-conversation dialog — resolved from the active list, or the
   // archived list when an archived chat is open (archived dialogs aren't in
   // `dialogs`, so the header title and ⋯ / restore actions need this).
@@ -254,7 +202,6 @@ export function useChatDialogManager({
     archivedDialogs,
     archivedCursor,
     archivedLoading,
-    archivedPending,
     openArchive,
     closeArchive,
     loadArchivedPage,
@@ -265,7 +212,6 @@ export function useChatDialogManager({
     // archived conversation
     isViewingArchived,
     handleBack,
-    resetToNewChat,
     activeDialog,
     // action modals
     renameTarget,

package/src/components/chat/index.ts

@@ -31,10 +31,8 @@ export * from './msp-organization-card'
 export * from './msp-organization-card-skeleton'
 export * from './guide-mode-banner'
 export * from './mingo-chat-history'
-export * from './mingo-history-rail'
 export * from './mingo-chat-modals'
 export * from './chat-header-icon-button'
-export * from './chat-header-search-field'
 export * from './chat-panel-header'
 export * from './chat-composer'
 export * from './chat-context-picker'

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

@@ -2,11 +2,12 @@
 
 import * as React from 'react'
 import { cn } from '../../utils/cn'
+import { useDebounce } from '../../hooks/ui/use-debounce'
 import { ActionsMenuDropdown, type ActionsMenuItem } from '../ui/actions-menu'
 import { Button } from '../ui/button'
+import { Input } from '../ui/input'
 import { ScrollFadeOverlay, useScrollFade } from '../ui/scroll-fade'
-import { Ellipsis01Icon, SearchXmarkIcon } from '../icons-v2-generated'
-import { ChatListEmptyState } from './chat-list-empty-state'
+import { Ellipsis01Icon, SearchIcon } from '../icons-v2-generated'
 import type { DialogItem } from './types/component.types'
 
 // =============================================================================
@@ -26,10 +27,12 @@ export interface MingoChatHistoryProps {
   /** Request archive — enables the row "Archive chat" action. The host opens
    *  the Archive confirmation modal. */
   onRequestArchive?: (dialog: DialogItem) => void
-  /** Current server-side search term. Drives the "No chats found" empty state;
-   *  the search INPUT lives in the panel header, not in this list. The host
-   *  owns the term and refetches server-side — the list does no filtering. */
+  /** Seed value for the search input. The host owns the search term and refetches
+   *  the dialog list server-side; the list itself does no filtering. */
   searchQuery?: string
+  /** Emit the (debounced) search term — enables the dialog search bar above the
+   *  list. Omit to hide the search bar entirely. */
+  onSearchChange?: (query: string) => void
   /** Whether more dialogs remain (cursor pagination). */
   hasMore?: boolean
   /** True while the next page is loading. */
@@ -131,21 +134,11 @@ function MingoChatHistoryRow({
   return (
     <div
       className={cn(
-        'group/row relative flex h-12 items-center border-b border-ods-border last:border-b-0 transition-colors',
-        // Active (selected) dialog — Figma 259:91610: an open-yellow-secondary
-        // fill, a 4px open-yellow accent bar down the leading edge, and yellow
-        // title text. Inactive rows keep the dark surface with a hover tint.
-        isActive
-          ? 'bg-ods-open-yellow-secondary'
-          : 'bg-ods-bg hover:bg-ods-bg-hover',
+        'group/row flex h-12 items-center bg-ods-bg border-b border-ods-border last:border-b-0',
+        'transition-colors hover:bg-ods-bg-hover',
+        isActive && 'bg-ods-bg-hover',
       )}
     >
-      {isActive ? (
-        <span
-          aria-hidden
-          className="pointer-events-none absolute inset-y-0 left-0 w-1 bg-ods-open-yellow"
-        />
-      ) : null}
       <div
         role="button"
         tabIndex={0}
@@ -156,7 +149,7 @@ function MingoChatHistoryRow({
             onSelect?.(dialog.id)
           }
         }}
-        className="flex min-w-0 flex-1 items-center gap-[var(--spacing-system-xsf)] p-[var(--spacing-system-s)] cursor-pointer focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ods-accent"
+        className="flex min-w-0 flex-1 items-center gap-[var(--spacing-system-xsf)] p-[var(--spacing-system-s)] cursor-pointer focus:outline-none focus-visible:bg-ods-bg-hover"
       >
         {unread > 0 ? (
           <span className="flex h-8 min-w-8 shrink-0 items-center justify-center rounded-md bg-ods-accent px-[var(--spacing-system-xsf)] text-h5 text-ods-text-on-accent">
@@ -164,10 +157,7 @@ function MingoChatHistoryRow({
           </span>
         ) : null}
         <span
-          className={cn(
-            'min-w-0 flex-1 truncate text-h4',
-            isActive ? 'text-ods-open-yellow' : 'text-ods-text-primary',
-          )}
+          className="min-w-0 flex-1 truncate text-h4 text-ods-text-primary"
           title={title}
         >
           {title}
@@ -232,39 +222,61 @@ function MingoChatHistoryRow({
  */
 export function MingoChatHistorySkeleton({
   className,
+  searchable = false,
 }: {
   className?: string
+  /** Render a search-bar placeholder above the groups — match the real list,
+   *  which shows the search bar only when search is wired. */
+  searchable?: boolean
 }) {
-  // Mirror the real grouped list exactly: a small group label, then a bordered
-  // rounded container of `h-12` rows, each with a single title bar of varying
-  // width (no unread-badge squares — the real rows currently never show one, so
-  // a badge placeholder would mis-promise the layout). `bg-ods-border` matches
-  // the kit's canonical `Skeleton` placeholder colour; `bg-ods-bg` rows read a
-  // touch darker than the `bg-ods-card` panel so the bars stay legible.
-  const groups: ReadonlyArray<ReadonlyArray<string>> = [
-    ['w-3/5', 'w-4/5', 'w-2/5', 'w-3/4'],
-    ['w-1/2', 'w-2/3'],
+  // Mirror the real grouped list: a group label, then a bordered container of
+  // `h-12` rows. `withBadge` adds the leading unread-badge square on the first
+  // N rows; `widths` varies the title-bar length so the placeholder reads like
+  // a list of differing-length chat titles, not identical bars. `bg-ods-border`
+  // (not `bg-ods-bg-secondary`) so the placeholders are actually visible on the
+  // dark surface.
+  const groups: ReadonlyArray<{ withBadge: number; widths: ReadonlyArray<string> }> = [
+    { withBadge: 2, widths: ['w-3/5', 'w-4/5', 'w-2/5', 'w-3/4'] },
+    { withBadge: 0, widths: ['w-1/2', 'w-3/5', 'w-2/3'] },
   ]
   return (
     <div
       aria-hidden
       // `overflow-hidden` clips the placeholder rows to the flex-1 box (the real
-      // list scrolls; the skeleton just needs to stay within bounds).
+      // list scrolls; the skeleton just needs to stay within bounds). Without it
+      // the rows bleed past their allotment and render under the pinned composer
+      // — which has no surface of its own — so the input appears to overlap them.
       className={cn(
         'flex flex-1 min-h-0 flex-col gap-[var(--spacing-system-m)] overflow-hidden',
         className,
       )}
     >
-      {groups.map((widths, g) => (
+      {/* Search-bar placeholder — mirrors the real `Input` (border, rounded,
+          h-11/12) with a leading icon + text bar so the loading state matches
+          the searchable layout. */}
+      {searchable && (
+        <div className="flex h-11 md:h-12 shrink-0 items-center gap-2 rounded-[6px] border border-ods-border bg-ods-card px-3">
+          <div className="size-4 md:size-6 shrink-0 animate-pulse rounded bg-ods-border" />
+          <div className="h-4 w-32 animate-pulse rounded bg-ods-border" />
+        </div>
+      )}
+      {groups.map((group, g) => (
         <div key={g} className="flex shrink-0 flex-col gap-[var(--spacing-system-xxs)]">
-          {/* Group label (Today / Older). */}
+          {/* Group label (Today / Yesterday). */}
           <div className="h-3 w-16 animate-pulse rounded bg-ods-border" />
           <div className="overflow-hidden rounded-md border border-ods-border">
-            {widths.map((w, i) => (
+            {group.widths.map((w, i) => (
               <div
                 key={i}
-                className="flex h-12 items-center bg-ods-bg border-b border-ods-border px-[var(--spacing-system-s)] last:border-b-0"
+                // Match the real row surface: `bg-ods-bg` (#161616) sits darker
+                // than the `bg-ods-card` (#212121) panel, which is what makes
+                // the `bg-ods-border` (#3a3a3a) placeholders read clearly. On
+                // the bare card they'd be muddy (too close in value).
+                className="flex h-12 items-center gap-[var(--spacing-system-xsf)] bg-ods-bg border-b border-ods-border px-[var(--spacing-system-s)] last:border-b-0"
               >
+                {i < group.withBadge && (
+                  <div className="h-8 w-8 shrink-0 animate-pulse rounded-md bg-ods-border" />
+                )}
                 <div className={cn('h-4 animate-pulse rounded bg-ods-border', w)} />
               </div>
             ))}
@@ -275,6 +287,46 @@ export function MingoChatHistorySkeleton({
   )
 }
 
+// =============================================================================
+// Search bar
+// =============================================================================
+
+/**
+ * Dialog search field. Holds its own input text for snappy typing and emits 
+ * the DEBOUNCED term via `onSearchChange` — the host owns the search state 
+ * and refetches the dialog list server-side, so the list never
+ * filters locally. `initialValue` only seeds the field on mount.
+ */
+function DialogSearchBar({
+  initialValue,
+  onSearchChange,
+}: {
+  initialValue?: string
+  onSearchChange: (query: string) => void
+}) {
+  const [value, setValue] = React.useState(initialValue ?? '')
+  const debounced = useDebounce(value, 300)
+  const lastEmitted = React.useRef(initialValue ?? '')
+
+  React.useEffect(() => {
+    if (debounced === lastEmitted.current) return
+    lastEmitted.current = debounced
+    onSearchChange(debounced)
+  }, [debounced, onSearchChange])
+
+  return (
+    <Input
+      type="text"
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+      placeholder="Search for Chats"
+      aria-label="Search chats"
+      startAdornment={<SearchIcon />}
+      className="shrink-0"
+    />
+  )
+}
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -297,6 +349,7 @@ export function MingoChatHistory({
   onRequestRename,
   onRequestArchive,
   searchQuery,
+  onSearchChange,
   hasMore = false,
   isLoadingMore = false,
   onLoadMore,
@@ -335,8 +388,13 @@ export function MingoChatHistory({
 
   return (
     <div className={cn('relative flex flex-1 min-h-0 flex-col gap-[var(--spacing-system-m)]', className)}>
-      {/* Scroll region — the search INPUT now lives in the panel header
-          (Figma 116:51217), so the list is just the grouped rows + fades. */}
+      {/* Pinned search bar — stays put while the grouped list scrolls below. */}
+      {onSearchChange ? (
+        <DialogSearchBar initialValue={searchQuery} onSearchChange={onSearchChange} />
+      ) : null}
+
+      {/* Scroll region — `relative` so the fades anchor here (below the search
+          bar), not over it. */}
       <div className="relative flex flex-1 min-h-0 flex-col">
         <div
           ref={scrollRef}
@@ -344,13 +402,9 @@ export function MingoChatHistory({
           className="flex flex-1 min-h-0 flex-col gap-[var(--spacing-system-m)] overflow-y-auto"
         >
           {noSearchResults ? (
-            // No search matches — same centred glyph + title + caption layout as
-            // the other chat-list empty states (Figma 113:60939).
-            <ChatListEmptyState
-              icon={<SearchXmarkIcon size={24} />}
-              title="No Chats Found"
-              description="Try a different search term"
-            />
+            <p className="py-[var(--spacing-system-m)] text-center text-h5 text-ods-text-secondary">
+              No chats found
+            </p>
           ) : (
             groups.map((group) => (
               <div

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

@@ -10,6 +10,10 @@ import { Button } from '../ui/button'
 import { ScrollFadeOverlay, useScrollFade } from '../ui/scroll-fade'
 import { XmarkIcon } from '../icons-v2-generated/signs-and-symbols/xmark-icon'
 import {
+  Rocket01Icon,
+  BracketCurlyIcon,
+  SearchIcon,
+  LayersIcon,
   CompassIcon,
   Arrow01DownIcon,
   AlertCircleIcon,
@@ -20,6 +24,17 @@ import {
 // Types
 // =============================================================================
 
+/** A single capability cell in the 2-up feature grid. */
+export interface MingoFeatureCard {
+  /** Stable React key. */
+  id: string
+  /** Leading 16×16 icon (monochrome `ods-text-secondary`). */
+  icon?: React.ReactNode
+  /** Caption text. Line breaks (`\n`) are honoured (`whitespace-pre-line`)
+   *  so the two-line wrap stays fixed regardless of panel width. */
+  text: React.ReactNode
+}
+
 /** "New to OpenFrame?" one-time notification config. `null` hides the card. */
 export interface MingoWelcomePromo {
   title: React.ReactNode
@@ -42,10 +57,14 @@ export interface MingoQuickAction {
 }
 
 export interface MingoWelcomeProps {
-  /** Greeting heading. Defaults to `Hey, I'm Mingo`. */
+  /** First name woven into the greeting. Empty/undefined → no-name variant. */
+  userName?: string
+  /** Greeting heading. Defaults to `Hey{, name}, I'm Mingo`. */
   title?: React.ReactNode
   /** Greeting sub-line under the heading. */
   subtitle?: React.ReactNode
+  /** 2-up capability grid. Defaults to the four OpenFrame highlights. */
+  featureCards?: ReadonlyArray<MingoFeatureCard>
   /** One-time "New to OpenFrame?" notification below the grid. `null` hides
    *  it; omitting falls back to the OpenFrame default (only rendered when
    *  `onStartGuideChat` is wired, i.e. Guide mode exists to advertise). */
@@ -83,6 +102,10 @@ export interface MingoWelcomeProps {
   loadError?: boolean
   /** Retry handler for the `loadError` state. */
   onRetry?: () => void
+  /** Whether the dialog history has a search bar — when true, the loading
+   *  skeleton includes a search-bar placeholder so it matches the loaded
+   *  layout. Ignored once `dialogHistory` is provided. */
+  historySearchable?: boolean
   /** When provided, renders the "Start Guide Chat" chip (the only wired
    *  action — switches the host chat to Guide mode) and enables the default
    *  promo notification. When omitted, both are suppressed. */
@@ -98,6 +121,29 @@ export interface MingoWelcomeProps {
 const DEFAULT_SUBTITLE =
   'Ready to help with your technical tasks. What can I do for you?'
 
+const DEFAULT_FEATURE_CARDS: ReadonlyArray<MingoFeatureCard> = [
+  {
+    id: 'answers',
+    icon: <Rocket01Icon size={16} />,
+    text: 'Get instant answers about\ndevices, tickets, and clients',
+  },
+  {
+    id: 'scripts',
+    icon: <BracketCurlyIcon size={16} />,
+    text: 'Run scripts and queries\nthrough natural language',
+  },
+  {
+    id: 'summarize',
+    icon: <SearchIcon size={16} />,
+    text: 'Summarize long ticket\nthreads or activity history',
+  },
+  {
+    id: 'delegate',
+    icon: <LayersIcon size={16} />,
+    text: 'Delegate tasks, let Mingo\nwork in the background',
+  },
+]
+
 const DEFAULT_PROMO: MingoWelcomePromo = {
   title: 'New to OpenFrame?',
   description: 'Start a Guide Chat to learn how it works and how to set it up.',
@@ -110,12 +156,13 @@ const DEFAULT_PROMO_STORAGE_KEY = 'mingo-welcome:promo-dismissed'
 // =============================================================================
 
 /**
- * MingoWelcome — Figma node `113:69208`.
+ * MingoWelcome — Figma node `7532:222444`.
  *
  * Default (Mingo-mode) chat empty state: a vertically-centred greeting that
- * grows to fill available height, then a pinned stack of an optional one-time
- * "New to OpenFrame?" notification and a quick-action chip row. The Guide-mode
- * empty state keeps the slash-command onboarding list.
+ * grows to fill available height, then a pinned stack of a 2-up capability
+ * grid, an optional one-time "New to OpenFrame?" notification, and a
+ * quick-action chip row. The Guide-mode empty state keeps the slash-command
+ * onboarding list.
  *
  * Content is configurable (props) with OpenFrame defaults so the kit stays
  * platform-agnostic. The "Start Guide Chat" chip is the only wired action —
@@ -124,8 +171,10 @@ const DEFAULT_PROMO_STORAGE_KEY = 'mingo-welcome:promo-dismissed'
  * storage so it shows only until the user closes it once.
  */
 export function MingoWelcome({
+  userName,
   title,
   subtitle = DEFAULT_SUBTITLE,
+  featureCards = DEFAULT_FEATURE_CARDS,
   promo,
   promoStorageKey = DEFAULT_PROMO_STORAGE_KEY,
   promoStorage = 'local',
@@ -137,12 +186,12 @@ export function MingoWelcome({
   isLoadingHistory = false,
   loadError = false,
   onRetry,
+  historySearchable = false,
   onStartGuideChat,
   className,
 }: MingoWelcomeProps) {
-  // Greeting never weaves the user's name in — always the plain "Hey, I'm
-  // Mingo" (design node 113:69208). A host `title` override still wins.
-  const heading = title ?? "Hey, I'm Mingo"
+  const heading =
+    title ?? (userName ? `Hey ${userName}, I'm Mingo` : "Hey, I'm Mingo")
 
   // `promo` omitted → fall back to the OpenFrame default, but only when guide
   // mode exists to advertise (otherwise the notification points nowhere).
@@ -187,6 +236,10 @@ export function MingoWelcome({
   // only while content is hidden in that direction).
   const { scrollRef, fadeTop, fadeBottom, update: updateScrollFade } = useScrollFade<HTMLDivElement>()
 
+  const cellCount = featureCards.length
+  // Last row's first index — used to drop the bottom divider on the final row.
+  const lastRowStart = cellCount - ((cellCount % 2) || 2)
+
   // While we don't yet know whether the user is new or returning (first page
   // loading, or it errored with nothing cached), suppress the pinned region —
   // the "New to OpenFrame?" promo + quick-action chips. Showing them over the
@@ -231,7 +284,7 @@ export function MingoWelcome({
           )}
         </div>
       ) : isLoadingHistory ? (
-        <MingoChatHistorySkeleton />
+        <MingoChatHistorySkeleton searchable={historySearchable} />
       ) : (
       <>
       {/* Scrollable region — only the greeting + grid scroll; the notification
@@ -256,18 +309,46 @@ export function MingoWelcome({
           eyesColor="var(--ods-flamingo-cyan-base)"
           cornerColor="var(--ods-flamingo-cyan-base)"
         />
-        <div className="flex w-full flex-col gap-[var(--spacing-system-l)]">
-          <p className="text-h2 text-ods-text-primary">{heading}</p>
-          <p className="text-h4 text-ods-text-secondary">{subtitle}</p>
+        <div className="flex w-full flex-col gap-1">
+          <p className="text-h4 text-ods-text-primary">{heading}</p>
+          <p className="text-h6 text-ods-text-secondary">{subtitle}</p>
         </div>
       </div>
+
+      {/* 2-up capability grid. `shrink-0` keeps every cell at its natural
+          height so the bottom row is never clipped (the root scrolls instead).
+          Cells share the lighter `ods-card` surface; 1px `ods-border` dividers
+          (right on the left column, bottom on every row but the last) draw the
+          inner cross. Captions use explicit `\n` breaks (`whitespace-pre-line`)
+          so the two-line wrap is fixed and never reflows with panel width. */}
+      {cellCount > 0 && (
+        <div className="grid shrink-0 grid-cols-2 overflow-hidden rounded-md border border-ods-border bg-ods-card">
+          {featureCards.map((card, i) => (
+            <div
+              key={card.id}
+              className={cn(
+                'flex flex-col items-center justify-center gap-[var(--spacing-system-m)] p-[var(--spacing-system-m)] text-center',
+                i % 2 === 0 && 'border-r border-ods-border',
+                i < lastRowStart && 'border-b border-ods-border',
+              )}
+            >
+              {card.icon ? (
+                <span className="flex size-4 shrink-0 items-center justify-center text-ods-text-primary">
+                  {card.icon}
+                </span>
+              ) : null}
+              <p className="text-h4 text-ods-text-secondary whitespace-pre-line">
+                {card.text}
+              </p>
+            </div>
+          ))}
+        </div>
+      )}
       </div>
 
-      {/* Edge scroll-fades — visible only when content is hidden beyond them.
-          Fade into the panel's dark `ods-bg` surface (the default color), matching
-          the black Mingo welcome background (node 113:69208). */}
-      <ScrollFadeOverlay edge="top" visible={fadeTop} className="h-12" />
-      <ScrollFadeOverlay edge="bottom" visible={fadeBottom} className="h-12" />
+      {/* Edge scroll-fades — visible only when content is hidden beyond them. */}
+      <ScrollFadeOverlay edge="top" visible={fadeTop} color="var(--color-bg-card)" className="h-12" />
+      <ScrollFadeOverlay edge="bottom" visible={fadeBottom} color="var(--color-bg-card)" className="h-12" />
       </div>
       </>
       ))}

package/src/stories/MingoWelcome.stories.tsx

@@ -26,13 +26,14 @@ const meta: Meta<typeof MingoWelcome> = {
     docs: {
       description: {
         component:
-          'Figma node `113:69208`. Default (Mingo-mode) chat empty state — a vertically-centred greeting, an optional "New to OpenFrame?" Guide-chat promo, and a quick-action chip row. Content is configurable with OpenFrame defaults; the only wired action is "Start Guide Chat" (`onStartGuideChat`).',
+          'Figma node `7532:222444`. Default (Mingo-mode) chat empty state — a vertically-centred greeting, a 2-up capability grid, an optional "New to OpenFrame?" Guide-chat promo, and a quick-action chip row. Content is configurable with OpenFrame defaults; the only wired action is "Start Guide Chat" (`onStartGuideChat`).',
       },
     },
   },
   argTypes: {
     title: { control: false },
     subtitle: { control: false },
+    featureCards: { control: false },
     promo: { control: false },
     quickActions: { control: false },
     onStartGuideChat: { control: false },
@@ -60,6 +61,14 @@ export const Default: Story = {
   },
 }
 
+/** Greeting personalised with a first name. */
+export const WithUserName: Story = {
+  args: {
+    userName: 'Grace',
+    onStartGuideChat: () => console.log('switch to guide mode'),
+  },
+}
+
 /** Guide mode not configured → the promo card and "Start Guide Chat" chip are
  *  suppressed (no dead-end CTA). */
 export const WithoutGuide: Story = {
@@ -91,7 +100,7 @@ export const ReturningUser: Story = {
   },
 }
 
-/** Wide panel (e.g. in-layout / desktop). */
+/** Wide panel (e.g. in-layout / desktop) — the grid columns read roomy. */
 export const Wide: Story = {
   args: {
     onStartGuideChat: () => console.log('switch to guide mode'),