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

package/src/components/chat/entity-cards/.admin-content-card.md

@@ -1,28 +1,29 @@
-<!-- source-hash: 5014a5d76cff7f765951023b41048390 -->
-Reusable admin content card component that renders a cover image with edge-color fill, title, subtitle, summary, platform badges, meta info, and action buttons in a consistent card layout.
+<!-- source-hash: 90ecdb57b252e70aaadc1195c206d309 -->
+A reusable card component for displaying admin content items (articles, posts, resources) with a cover image, metadata, platform badges, and action slots.
 
 ## Key Components
 
 ### `AdminContentCard`
-Main exported component. Renders an `<article>` card with a 3:2 aspect-ratio cover image and a flexible content body.
+The primary exported component rendering a styled card with hover animations and dynamic image handling.
 
 ### `AdminContentCardProps`
 | Prop | Type | Description |
 |------|------|-------------|
 | `imageUrl` | `string \| null` | Primary cover image URL |
-| `placeholderUrl` | `string \| null` | Fallback image URL when `imageUrl` is missing or errors |
-| `title` | `string` | Required heading and image alt text |
-| `summary` | `string \| null` | Two-line clamped description |
+| `placeholderUrl` | `string \| null` | Fallback image URL when `imageUrl` is absent or fails |
+| `title` | `string` | Card heading and image alt text |
+| `summary` | `string \| null` | Optional description (2-line clamp) |
 | `subtitle` | `string \| null` | Secondary line (e.g. customer name) |
-| `platforms` | `PlatformInfo[]` | Renders `<PlatformBadge>` chips |
-| `badges` | `ReactNode` | Additional status badges after platform chips |
-| `meta` | `ReactNode` | Date, views, or other metadata row |
-| `actions` | `ReactNode` | Pinned-to-bottom action buttons |
-| `className` | `string` | Extra Tailwind classes |
+| `platforms` | `PlatformInfo[]` | Renders `PlatformBadge` entries |
+| `badges` | `ReactNode` | Additional status/info badges |
+| `meta` | `ReactNode` | Date, view count, or other metadata |
+| `actions` | `ReactNode` | Action buttons pinned to the card footer |
+| `className` | `string` | Additional CSS classes |
 
-### Internal Hooks
-- **`useImageEdgeColor`** — samples the edge color of `displayUrl` to use as the image container background, blending the cover image seamlessly.
-- **`useState / useEffect`** — tracks `imageError` and `imageLoaded` states; resets load state on URL change to replay the fade-in.
+**Image handling:**
+- Falls back from `imageUrl` → `placeholderUrl` → plain background on error
+- Shows a pulse skeleton while the image loads
+- Applies `useImageEdgeColor` to fill the 3:2 image container background with the image's edge color
 
 ## Usage Example
 
@@ -30,14 +31,20 @@ Main exported component. Renders an `<article>` card with a 3:2 aspect-ratio cov
 import { AdminContentCard } from './admin-content-card'
 
 <AdminContentCard
-  imageUrl="https://cdn.example.com/cover.png"
-  placeholderUrl="https://cdn.example.com/og-placeholder.png"
-  title="Quarterly Security Report"
+  imageUrl="https://cdn.example.com/post-cover.jpg"
+  placeholderUrl="https://cdn.example.com/og-placeholder.jpg"
+  title="Automating Patch Management with Flamingo"
   subtitle="Acme Corp"
-  summary="Overview of vulnerabilities patched in Q2 2025."
-  platforms={[{ id: 'azure', name: 'Azure', display_name: 'Microsoft Azure' }]}
-  badges={<span className="badge">Published</span>}
-  meta={<span>June 12, 2025 · 142 views</span>}
+  summary="A walkthrough of OpenFrame's patch automation workflows for MSPs."
+  platforms={[{ platform_id: 'ninja', name: 'NinjaRMM' }]}
+  badges={<span className="badge">Featured</span>}
+  meta={<span>Apr 2025 · 1.2k views</span>}
   actions={<button>Edit</button>}
 />
-```
+```
+
+## Notes
+
+- Uses ODS (OpenFrame Design System) tokens (`ods-border`, `ods-accent`, etc.) for theming
+- Image scaling on hover via `group-hover:scale-[1.03]` requires the parent to carry Tailwind's `group` class (applied internally on `<article>`)
+- View source: [`admin-content-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/admin-content-card.tsx)

package/src/components/chat/entity-cards/.blog-card.md

@@ -1,52 +1,63 @@
-<!-- source-hash: 84fe8c9e8dffcbf0ae0ec8ff163a67e2 -->
-Pure presentation component for rendering blog post cards in two density modes (`default` and `sm`), with no built-in click/navigation logic — callers supply the resolved `href` and wrap with their own anchor strategy.
+<!-- source-hash: c1cd88e3bedb3ff138c2d63ba69b758b -->
+Pure presentation component for rendering blog post cards in three density modes: full vertical (`default`), compact horizontal (`sm`), and portrait strip (`portrait`).
 
 ## Key Components
 
 ### `BlogCard`
-Main card component supporting two layouts:
-- **`default`**: Full vertical card with cover image, title, summary, author avatar, date, and view count
-- **`sm`**: Compact horizontal card (~80px tall) designed for chat-inline rendering, showing a thumbnail, title, category, and summary
+Main component that renders a `BlogPostSummary` in one of three layouts. All click/navigation logic is deferred to the caller via `href` and optional `target`/`rel` props.
+
+| Size | Layout | Use Case |
+|------|--------|----------|
+| `default` | Full vertical card with cover image, title, summary, author/date footer, and view count | Blog index grids |
+| `sm` | Compact horizontal (~80px) with thumbnail, title, category, summary | Chat inline rendering |
+| `portrait` | Delegates to `EntityPortraitCard` | Mixed-type content rails |
+
+**Image fallback chain:** `post.featured_image` → `placeholderUrl` (caller-resolved via `useOgPlaceholderUrl`) → `bg-ods-bg` slot background.
 
 ### `BlogCardSkeleton`
-Loading placeholder matching both `default` and `sm` density layouts using animated pulse styles.
+Loading placeholder mirroring the shape of each density. Accepts the same `size` prop.
+
+## Key Props
 
-### `BlogCardProps`
 | Prop | Type | Description |
-|---|---|---|
-| `post` | `BlogPostSummary` | Post data (title, image, author, etc.) |
-| `href` | `string` | Resolved detail URL from caller |
+|------|------|-------------|
+| `post` | `BlogPostSummary` | Post data |
+| `href` | `string` | Resolved detail URL (caller provides) |
 | `target` | `'_blank'` | Opens in new tab (set by chat dispatch) |
-| `placeholderUrl` | `string \| null` | Fallback image when `featured_image` is missing |
-| `size` | `'default' \| 'sm'` | Card density mode |
-| `hasEmbeddedVideo` | `boolean` | Surfaces a "Video" badge in compact mode |
-| `priority` | `boolean` | Passes LCP priority hint to the cover image |
-
-**Image fallback chain:** `post.featured_image` → `placeholderUrl` → `bg-ods-bg` background slot
+| `placeholderUrl` | `string \| null` | Fallback image when `featured_image` is absent |
+| `size` | `'default' \| 'sm' \| 'portrait'` | Card density |
+| `showTypeBadge` | `boolean` | Renders content-type chip in portrait mode |
+| `hasEmbeddedVideo` | `boolean` | Shows "Video" badge in `sm` mode |
+| `priority` | `boolean` | Passes Next.js `priority` to the cover `<Image>` |
 
 ## Usage Example
 
 ```typescript
-// Default full card — caller wraps with navigation anchor
+// Default vertical card (hub context)
+<NavLinkAnchor href={buildContentURL(post)}>
+  <BlogCard
+    post={post}
+    href={buildContentURL(post)}
+    placeholderUrl={useOgPlaceholderUrl(post.title)}
+    size="default"
+    priority={isAboveFold}
+  />
+</NavLinkAnchor>
+
+// Compact card for chat inline
 <BlogCard
-  post={blogPostSummary}
-  href={buildContentURL(post.slug)}
-  placeholderUrl={useOgPlaceholder(post)}
-  size="default"
-  priority={true}
-/>
-
-// Compact card for chat-inline rendering
-<BlogCard
-  post={blogPostSummary}
-  href={detailUrl}
+  post={post}
+  href={resolvedUrl}
   target="_blank"
   rel="noopener noreferrer"
   size="sm"
-  hasEmbeddedVideo={true}
-  placeholderUrl={staticFallbackUrl}
+  hasEmbeddedVideo={post.has_video}
 />
 
-// Skeleton while loading
-<BlogCardSkeleton size="sm" />
-```
+// Skeleton during load
+<BlogCardSkeleton size="default" />
+```
+
+> **No click logic lives here.** Callers wrap with `<NavLinkAnchor>` (hub) or `<NavLinkAnchorViaRuntime>` (lib) as appropriate.
+
+**Source:** [`blog-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/blog-card.tsx)

package/src/components/chat/entity-cards/.blog-image-placeholder.md

@@ -1,39 +1,41 @@
-<!-- source-hash: d68b2db5f05c474ec9bdb96a22e60341 -->
-Thin presentation component that renders a blog post cover image (or OG-generated placeholder) with graceful 404 recovery.
+<!-- source-hash: 97c4c0581bb8cb14e23dddcdae3af6f4 -->
+Renders a blog post cover image with graceful error handling — returns `null` when no URL is provided and silently hides broken images on load failure.
 
 ## Key Components
 
-### `BlogImagePlaceholder`
-A client-side React component that wraps a cover image in an HTML phrasing-content–safe `<span>`. Key behaviors:
+### `BlogImagePlaceholder` (exported function component)
 
-- Returns `null` when `imageUrl` is `null`, rendering nothing
-- Uses a plain `<img>` tag (bypasses `next/image`) to support query-string–based dynamic placeholder URLs
-- Hides the broken-image icon via `onError` when the URL 404s, letting the parent `bg-ods-bg` background show through cleanly
-- Wrapped in `<span className="block">` instead of `<div>` for HTML validity when rendered inside markdown `<p>` tags (e.g., compact `BlogCard` in the chat shell)
+| Prop | Type | Description |
+|---|---|---|
+| `imageUrl` | `string \| null` | Pre-resolved cover/OG image URL; component renders nothing if `null` |
+| `title` | `string` | Used in the `alt` attribute for accessibility |
+| `className` | `string?` | Optional additional CSS classes |
 
-### `BlogImagePlaceholderProps`
+**Notable implementation details:**
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `imageUrl` | `string \| null` | Pre-resolved cover/OG image URL; `null` renders nothing |
-| `title` | `string` | Used for the `alt` attribute |
-| `className` | `string` | Optional extra Tailwind classes |
+- Uses `<span className="block">` instead of `<div>` to satisfy HTML phrasing-content rules when rendered inside a markdown `<p>` element (e.g., chat shell's compact `BlogCard` fallback)
+- Bypasses `next/image` in favor of a plain `<img>` tag — appropriate here since the URL is a dynamically-generated placeholder with a query string where Next.js loader config adds no value
+- `onError` hides the broken image element, allowing the parent's `bg-ods-bg` background to show through cleanly
 
 ## Usage Example
 
 ```typescript
 import { BlogImagePlaceholder } from './blog-image-placeholder'
 
-// Typical usage in a BlogCard with a pre-resolved OG placeholder URL
+// With a resolved OG placeholder URL
 <BlogImagePlaceholder
-  imageUrl="https://og.flamingo.run/placeholder?title=My+Post&category=devops"
+  imageUrl="https://example.com/og-image.png?title=My+Post"
   title="My Post"
   className="rounded-lg"
 />
 
-// When imageUrl is null, renders nothing — safe to use unconditionally
+// Renders nothing when imageUrl is null
 <BlogImagePlaceholder
   imageUrl={null}
   title="Draft Post"
 />
-```
+```
+
+## Source
+
+[`blog-image-placeholder.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/blog-image-placeholder.tsx)

package/src/components/chat/entity-cards/.case-study-card.md

@@ -1,58 +1,49 @@
-<!-- source-hash: 02a29dbf8a78be028a2e952b979247a7 -->
-Pure presentation component for displaying MSP case studies in two density modes — `default` (vertical detail card) and `sm` (compact horizontal for chat-inline rendering).
+<!-- source-hash: d3c2c6a2b8511d1b5bb1d570d788eed4 -->
+Pure presentation component for rendering MSP case study cards in three density variants: `default` (vertical detail), `sm` (compact horizontal for chat-inline), and `portrait` (rail/strip layout via `EntityPortraitCard`).
 
 ## Key Components
 
 ### `CaseStudyCard`
-Main card component. Renders a linked, non-interactive card (no click logic — callers wrap with their own anchor and pass a resolved `href`). Supports:
-- **`default` size**: Full vertical layout with OG-ratio cover image (`1200×630`), title, and author/MSP attribution with avatar stack.
-- **`sm` size**: Compact horizontal layout for embedding in chat threads.
+The primary export. Renders a case study in one of three layouts based on the `size` prop. Contains no click logic — callers supply `href` directly and wrap with their own anchor. Image resolution follows the fallback chain: `study.featured_image` → `placeholderUrl` → `bg-ods-bg` background.
 
 ### `CaseStudyCardSkeleton`
-Loading placeholder that mirrors the exact layout and aspect ratios of `CaseStudyCard` for both size variants, using `animate-pulse`.
+Loading placeholder that mirrors the real card's layout zones for each density. The `default` and `portrait` variants share the same skeleton shape (media aspect ratio → 72px title zone → 60px person footer).
 
-### Image Fallback Chain
-```text
-study.featured_image → placeholderUrl (from useOgPlaceholder) → bg-ods-bg background
-```
-
-## Key Props (`CaseStudyCardProps`)
+### Props (`CaseStudyCardProps`)
 
 | Prop | Type | Description |
-|------|------|-------------|
+|---|---|---|
 | `study` | `CaseStudy` | Case study data object |
-| `href` | `string` | Resolved detail URL (caller-provided) |
-| `target` | `'_blank'` | Opens in new tab (set by chat dispatch) |
-| `placeholderUrl` | `string \| null` | OG fallback image when `featured_image` is missing |
-| `size` | `'default' \| 'sm'` | Card density mode |
+| `href` | `string` | Resolved detail URL (caller-supplied) |
+| `target` | `'_blank'` | Optional new-tab behavior |
+| `placeholderUrl` | `string \| null` | OG placeholder when `featured_image` is absent |
+| `size` | `'default' \| 'sm' \| 'portrait'` | Card density variant |
+| `showTypeBadge` | `boolean` | Portrait only — shows "Case Study" chip in mixed-type rails |
 
 ## Usage Example
 
 ```typescript
 import { CaseStudyCard, CaseStudyCardSkeleton } from './case-study-card'
-import { useOgPlaceholder } from '../hooks/use-og-placeholder'
+import { useOgPlaceholderUrl } from '../hooks/use-og-placeholder-url'
 
-function CaseStudyGrid({ studies }: { studies: CaseStudy[] }) {
-  const placeholderUrl = useOgPlaceholder(study.id)
+function CaseStudyRail({ studies, isLoading }) {
+  const placeholderUrl = useOgPlaceholderUrl({ aspect: 'wide' })
 
-  if (!studies) return <CaseStudyCardSkeleton size="default" />
+  if (isLoading) {
+    return <CaseStudyCardSkeleton size="portrait" />
+  }
 
-  return (
+  return studies.map((study) => (
     <CaseStudyCard
+      key={study.id}
       study={study}
       href={`/case-studies/${study.slug}`}
+      size="portrait"
+      showTypeBadge={false}
       placeholderUrl={placeholderUrl}
-      size="default"
     />
-  )
+  ))
 }
+```
 
-// Chat-inline compact variant
-<CaseStudyCard
-  study={study}
-  href={`/case-studies/${study.slug}`}
-  target="_blank"
-  rel="noopener noreferrer"
-  size="sm"
-/>
-```
+**Source:** [`case-study-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/case-study-card.tsx)

package/src/components/chat/entity-cards/.chat-ticket-item.md

@@ -1,40 +1,57 @@
-<!-- source-hash: 88aa76a71f078b18928be54e60fe0a71 -->
-A clickable ticket row component for chat interfaces, rendering ticket details (title, number, category, time), a status tag, an optional linked-work chip, and a chevron affordance.
+<!-- source-hash: ad593d628549abcee57e9fe3d784a504 -->
+A React client component that renders a single ticket row inside a chat/support panel, supporting interactive, loading skeleton, and linked-work states.
 
 ## Key Components
 
-### `ChatTicketItemData`
-Data interface for the ticket row:
-- `id`, `title`, `ticketNumber` — core identifiers
-- `status` — accepts any known format (`ACTIVE`, `active`, `ACTION_REQUIRED`, etc.)
-- `statusLabel?` — overrides the badge text while preserving status variant/icon (e.g. HubSpot pipeline stage labels)
-- `linkedTaskLabel?` — when set, renders a wrench-icon "linked work" chip indicating an in-flight delivery task
-- `category?`, `timeAgo?` — optional subtitle fields joined with `•`
+### Interfaces
 
-### `ChatTicketItemProps`
-Extends `ButtonHTMLAttributes` (omitting `onClick`) with a typed `onClick?: (ticketId: string) => void` callback.
+- **`ChatTicketItemData`** — Data model for a ticket row, including `id`, `title`, `ticketNumber`, `status`, `statusLabel`, `statusKind`, `statusColor`, `category`, `timeAgo`, and optional `linkedTaskLabel` (renders a wrench-icon chip when present).
+- **`ChatTicketItemProps`** — Props for the component; extends `HTMLButtonElement` attributes (excluding native `onClick`), accepting `ticket`, a typed `onClick(ticketId: string)` callback, and `isLoading`.
 
-### `ChatTicketItem`
-A `forwardRef` button component that:
-- Dims the title (`text-ods-text-secondary`) when the ticket is resolved
-- Builds a dot-separated subtitle from `ticketNumber`, `category`, and `timeAgo`
-- Renders `Tag` with `WrenchIcon` (hidden on `sm` screens) when `linkedTaskLabel` is present
-- Handles focus ring via `focus-visible` to prevent stray white borders after click in jsdom/Chromium
+### Component
+
+- **`ChatTicketItem`** — A `forwardRef` button component with three render states:
+  - **Loading** (`isLoading=true`): Renders an `aria-hidden` skeleton placeholder sized to match a real row.
+  - **No data** (`ticket` is `undefined`): Returns `null`.
+  - **Populated**: Renders the ticket title, a subtitle line joining `ticketNumber`, `category`, and `timeAgo` with bullet separators, an optional linked-work `Tag` chip (hidden on `sm` and below), a `TicketStatusTag`, and a chevron navigation indicator.
 
 ## Usage Example
 
 ```typescript
+import { ChatTicketItem } from './chat-ticket-item'
+
+// Loading state
+<ChatTicketItem isLoading />
+
+// Populated state
 <ChatTicketItem
   ticket={{
-    id: 'tkt-001',
-    title: 'Email not syncing after password reset',
+    id: 'TKT-001',
+    title: 'VPN not connecting after Windows update',
     ticketNumber: '#1042',
     status: 'ACTION_REQUIRED',
-    statusLabel: 'Waiting on contact',
-    category: 'Email',
+    category: 'Network',
     timeAgo: '2h ago',
     linkedTaskLabel: 'Waiting on version release',
   }}
   onClick={(ticketId) => router.push(`/tickets/${ticketId}`)}
 />
-```
+
+// With custom HubSpot pipeline stage label
+<ChatTicketItem
+  ticket={{
+    id: 'TKT-002',
+    title: 'Email sync issue',
+    ticketNumber: '#1043',
+    status: 'ACTIVE',
+    statusLabel: 'Waiting on contact',
+  }}
+  onClick={(id) => console.log('opened', id)}
+/>
+```
+
+## Notes
+
+- Status resolution delegates to `resolveStatusTagProps` and `resolveTicketStatus`, allowing any status string format (`ACTIVE`, `active`, `ACTION_REQUIRED`, etc.).
+- The linked-work chip (`linkedTaskLabel`) is hidden on small screens via `hidden sm:inline-flex` to prevent row crowding.
+- Focus styles explicitly suppress the post-click outline ring using `focus:outline-none focus:bg-ods-bg-hover` while preserving keyboard-nav visibility via `focus-visible:ring-2`.

package/src/components/chat/entity-cards/.customer-interview-card.md

@@ -1,53 +1,50 @@
-<!-- source-hash: 13f9305f5b11a7a8a688986630bbf7d1 -->
-Pure presentation component for displaying customer interview data in two density variants (`default` and `sm`), with no embedded click logic — navigation is handled entirely by the caller via `href`.
+<!-- source-hash: be03f9107f1ebb36349ea65aa7f3ebeb -->
+Pure presentation component for rendering customer interview content in three density modes: `default` (full card), `sm` (compact horizontal for chat-inline), and `portrait` (rail/strip layout).
 
 ## Key Components
 
+### `CustomerInterviewCardProps`
+| Prop | Type | Description |
+|---|---|---|
+| `interview` | `CustomerInterview` | Data model for the interview |
+| `href` | `string` | Resolved detail URL — no click logic inside the card |
+| `target` | `'_blank'` | Optional new-tab behavior |
+| `targetPlatform` | `string \| null` | Passed to `useEntityCardLink` for platform-aware link resolution |
+| `placeholderUrl` | `string \| null` | OG image fallback when `featured_image` is absent |
+| `size` | `'default' \| 'sm' \| 'portrait'` | Render density |
+| `showTypeBadge` | `boolean` | Portrait mode only — renders the "Customer Interview" chip (default: `true`) |
+
 ### `CustomerInterviewCard`
-Main card component rendering interview metadata, thumbnail, video indicator, and author/MSP attribution. Accepts an `href` prop for navigation and delegates all routing concerns to the caller.
+Main export. Delegates link resolution to `useEntityCardLink` and placeholder generation to `useEntityCardPlaceholder`. Branches render path by `size`:
+- **`default`** — Full card with 1200×630 aspect image, title, summary, and avatar footer with MSP icon overlay
+- **`sm`** — Compact horizontal layout with square thumbnail and video indicator icon
+- **`portrait`** — Delegates entirely to `EntityPortraitCard`
 
 ### `CustomerInterviewCardSkeleton`
-Animated loading placeholder that mirrors the layout of `CustomerInterviewCard` for both size variants, preventing layout shift during data fetching.
-
-### `CustomerInterviewCardProps`
-```typescript
-interface CustomerInterviewCardProps {
-  interview: CustomerInterview   // Core interview data
-  href: string                   // Resolved detail URL (caller-provided)
-  target?: '_blank'              // Opens in new tab when set
-  rel?: 'noopener noreferrer'
-  placeholderUrl?: string | null // Fallback OG image when featured_image is absent
-  size?: 'default' | 'sm'       // 'sm' = compact horizontal (chat-inline)
-  className?: string
-}
-```
+Loading placeholder matching each density's layout zones, with `animate-pulse` shimmer.
 
 ## Usage Example
 
 ```typescript
-// Default card — standalone page listing
+import { CustomerInterviewCard, CustomerInterviewCardSkeleton } from './customer-interview-card'
+
+// Default full card
 <CustomerInterviewCard
   interview={interviewData}
-  href={`/interviews/${interviewData.slug}`}
-  placeholderUrl="/assets/interview-placeholder.jpg"
+  href="/interviews/acme-corp-story"
+  size="default"
+  showTypeBadge={false}
 />
 
-// Compact variant — inline within chat/AI responses
+// Compact chat-inline variant
 <CustomerInterviewCard
   interview={interviewData}
-  href={`/interviews/${interviewData.slug}`}
+  href="/interviews/acme-corp-story"
   target="_blank"
   rel="noopener noreferrer"
   size="sm"
 />
 
-// Skeleton while fetching
-<CustomerInterviewCardSkeleton size="sm" />
-```
-
-## Size Variants
-
-| Variant | Layout | Use Case |
-|---------|--------|----------|
-| `default` | Vertical card with 1200×630 aspect image, summary, and author row | Grid/list pages |
-| `sm` | Compact horizontal row with thumbnail + text column | Chat-inline embeds (Mingo AI / Fae) |
+// Loading state
+<CustomerInterviewCardSkeleton size="default" />
+```

package/src/components/chat/entity-cards/.data-room-doc-card.md

@@ -1,47 +1,46 @@
-<!-- source-hash: f8069e3f963f307b16a2d6ae310496d9 -->
-Inline chat card component for rendering Data Room and OpenFrame-docs document references within the Flamingo/OpenFrame AI chat interface. Handles both `/data-room` and `/knowledge-base` route surfaces with a shared presentation layer.
+<!-- source-hash: 9352fa2f2f4a64170a613a49640d8f24 -->
+Presentational inline-chat card for Data Room and OpenFrame-docs document references. Renders `[card://data_room_doc:<id>]` and `[card://markdown:<id>]` markers with a shared UI surface — only the `baseRoute` differs between document sources.
 
 ## Key Components
 
 ### `DataRoomDocCard`
-Primary card component. Renders as an interactive `<a>` element when `anchorProps` is provided, or a static `<span>` when no link is available. Displays document title, source badge, file path, and a preview excerpt.
+Primary card component. Conditionally renders as an interactive `<a>` element (when `anchorProps` is provided) or a static `<span>` (non-interactive fallback). Displays document title, source badge, optional file path, and a two-line preview excerpt.
 
 ### `DataRoomDocCardSkeleton`
-Loading state placeholder matching the card's layout — used while document data is being fetched.
+Loading state placeholder that mirrors the card's layout with shimmer-style placeholder spans for title, badge, path, and preview lines.
 
-### `DataRoomDocCardAnchorProps`
-Prop bundle interface for pre-composed anchor attributes (`href`, `target`, `rel`, `onClick`). URL composition and routing decisions are handled by the consumer, not this component.
+### Types
 
-### `DataRoomDocCardProps`
-| Prop | Type | Notes |
-|------|------|-------|
-| `item` | `DataRoomDocCardItem` | Title, path, and preview text |
-| `badgeText` | `string` | Required. Consumer-resolved source label (e.g. "Data Room", "Knowledge Base") |
-| `anchorProps` | `DataRoomDocCardAnchorProps?` | When omitted, card renders non-interactive |
-| `className` | `string?` | Additional CSS classes |
+| Export | Description |
+|---|---|
+| `DataRoomDocCardProps` | Card props: `item`, `badgeText` (required), optional `anchorProps` and `className` |
+| `DataRoomDocCardAnchorProps` | Subset of `<a>` props: `href`, `target`, `rel`, `onClick` |
 
 ## Usage Example
 
 ```typescript
-// Interactive card (linked)
+import { DataRoomDocCard, DataRoomDocCardSkeleton } from './data-room-doc-card'
+
+// Interactive card — consumer resolves routing and badge label
 <DataRoomDocCard
-  item={{ title: 'Onboarding Guide', path: '/docs/onboarding.md', preview: 'Step-by-step...' }}
-  badgeText={getSourceLabel(item.sourceRepo)}  // consumer resolves label
+  item={{ title: 'Onboarding Guide', path: '/docs/onboarding.md', preview: 'Step-by-step setup...' }}
+  badgeText="Knowledge Base"
   anchorProps={{
-    href: '/data-room/docs/abc123',
+    href: '/knowledge-base/42',
     target: '_blank',
     rel: 'noopener noreferrer',
+    onClick: (e) => trackCardClick(e),
   }}
 />
 
-// Non-interactive card (no link resolved)
+// Static (no link available)
 <DataRoomDocCard
-  item={{ title: 'Policy Draft', path: null, preview: null }}
-  badgeText="Knowledge Base"
+  item={{ title: 'Restricted Doc', path: '/data-room/secret.pdf' }}
+  badgeText="Data Room"
 />
 
-// Skeleton while loading
+// Loading state
 <DataRoomDocCardSkeleton />
 ```
 
-> **Design note:** `badgeText` is required (no default) to prevent silent mislabeling — a document sourced from `openframe-docs` must never display "Data Room" due to its private/internal connotation. The consumer's `getSourceLabel()` resolver is the single source of truth for provenance labels.
+> **Design note:** `badgeText` is required (no default) to prevent silent mislabeling — a card from `openframe-docs` silently falling back to `"Data Room"` would falsely imply internal/private provenance to end-users. The consumer must explicitly resolve and pass the correct label.