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

package/src/components/chat/entity-cards/.dispatch.md

@@ -1,39 +1,56 @@
-<!-- source-hash: 32d71d29579661580177180e5a23c34d -->
-Renders the correct compact card component for a given `ChatRef` by dispatching on document type, handling fetch/skeleton states, and wiring navigation props for the chat shell.
+<!-- source-hash: 662d570ca898ee06d2fcb44e45351ac9 -->
+Dispatches canonical chat card types to their corresponding React components, serving as the lib-portable rendering layer for inline entity cards within the chat shell.
 
 ## Key Components
 
-### Types
-- **`ChatCardDispatchExtras`** — Host-supplied builders for hub-specific derived props (program configs, product-release prop builder, OG placeholder URL generator)
-- **`ChatCardRenderOptions`** — Per-render options including `baseRoute`, `chipBasePlatform`, `extras`, and the pre-computed `isNewTab` flag
+### Types & Interfaces
 
-### Internal Card Wrappers
-- **`GitHubChatCard`** — Renders a compact `GitHubActivityCard` from a `ChatRef`
-- **`HubspotTicketChatCard`** — Extracts ticket metadata (status, priority, customer) from `chatRef.metadata` and renders `HubspotTicketCard`
-- **`SlackChatCard`** — Maps channel name from metadata and renders `SlackMessageCard`
-- **`DataRoomDocChatCard`** — Renders `DataRoomDocCard` with provenance badge resolved via `getSourceLabel`; intentionally falls back to `"Document"` (never `"Data room"`) to avoid false sensitivity labeling
-- **`GenericFinancialChatCard`** — Renders `GenericEntityCard` with badge, color scheme, optional facts list, and subtitle
-- **`ChatInlineVideoPill`** — Inline pill span for video references (non-block contexts)
+- **`ChatCardDispatchExtras`** — Host-supplied builder functions for hub-dependent card props (program configs, product-release props, OG placeholder URLs)
+- **`ChatCardRenderOptions`** — Per-card render options including `baseRoute`, `isNewTab`, `extras`, and `discuss` action
+- **`CardDiscussAction`** — Action descriptor for the "Ask Mingo"/"Display" affordance in card menus
 
-### Utilities Used
-- `buildAnchorProps` / `computeIsNewTab` / `newTabAnchorAttrs` — Anchor attribute construction
-- `resolveHrefForRuntime` / `handleChatNavClick` — Runtime-aware navigation
-- `resolveSourceRowCTA` / `resolveSourceIcon` / `getSourceLabel` — Source chip metadata
+### Internal Components
+
+- **`GitHubChatCard`** — Renders GitHub activity cards (commits, PRs, PR reviews) using `MingoInfoCard` with kind-specific icons and review state color variants
+- **`githubKindIcon(kind)`** — Maps `GitHubActivityKind` to the appropriate icon component
+- **`reviewStateToVariant(state)`** — Converts PR review state to a `MingoInfoCardStatus` variant (`success`, `error`, `warning`, `grey`)
+
+### Public Entry Points
+
+- **`renderChatInlineEntityCard(ref, opts)`** — Top-level dispatch function; hoists video refs to block cards, otherwise renders compact inline cards
+- **`ChatCardLoader`** — Fetch + skeleton + render component for fetch-mode entries
+
+### Registry
+
+- **`CHAT_CARD_REGISTRY`** — Central map of document types to their card component and skeleton, enabling O(1) dispatch without nested conditionals
 
 ## Usage Example
 
 ```typescript
-// In the chat shell — dispatch a compact inline card
+// Rendering an inline entity card from chat context
+import { renderChatInlineEntityCard } from './dispatch'
+
 const card = renderChatInlineEntityCard(chatRef, {
-  isNewTab: computeIsNewTab(chatRef.url, runtime.source),
-  baseRoute: '/app',
-  chipBasePlatform: 'hub',
+  isNewTab: false,
+  baseRoute: '/hub',
   extras: {
-    programConfigs: { podcast: myPodcastConfig },
-    buildProductReleaseCardProps: (release) => ({ iconUrl: release.icon }),
-    buildOgPlaceholderUrl: (title) => `/og?title=${encodeURIComponent(title)}`,
+    buildOgPlaceholderUrl: (title) => `/api/og?title=${encodeURIComponent(title)}`,
+    buildProductReleaseCardProps: (release) => ({ /* hub-derived props */ }),
+    programConfigs: {
+      podcast: podcastConfig,
+      webinar: webinarConfig,
+    },
   },
 })
 ```
 
-> **Adding a new card type:** Implement the `size='sm'` branch in `./<card>.tsx`, then register one entry in the `CHAT_CARD_REGISTRY` switch inside this file.
+## Adding a New Card Type
+
+1. Implement a `size='sm'` branch + skeleton in `./<card>.tsx` (pure presentation, accepts `href` + `targetPlatform`)
+2. Add one entry to `CHAT_CARD_REGISTRY`
+
+## Related Files
+
+- [`chat-ref.types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/types/chat-ref.types.ts) — `ChatRef` shape
+- [`nav-click-handler.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/utils/nav-click-handler.ts) — `handleChatNavClick`
+- [`product-release-card-defaults.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/cards/product-release-card-defaults.ts) — Fallback prop builder

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

@@ -1,51 +1,54 @@
-<!-- source-hash: 7fa68fe7633e75913b75cba411a322f1 -->
-Renders author and publication metadata as a bordered grid card, matching the visual contract of the release detail page. Supports 1–4 cells with responsive dividers.
+<!-- source-hash: 5bff6cdc476cf1a4ab5b1da3aac188eb -->
+Renders author and publication metadata as a bordered grid card, matching the visual layout used on release detail pages. Supports 1–4 cells with responsive column sizing.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `EntityAuthorCard` | Component | Convenience composer rendering a "Published + Author" grid. Primary public API. |
-| `EntityMetadataValueCell` | Component | Single cell with a large uppercase value (`text-h4`) and a small secondary label. |
-| `EntityMetadataAuthorCell` | Component | Single cell with `SquareAvatar`, name, and role/job-title label. |
-| `EMPTY_AUTHOR_PLACEHOLDER` | Constant | Fallback author shape (`"—"` / `"Unknown"`) used when `renderEmptyAuthor` is `true`. |
-| `EntityAuthorCardProps` | Interface | Full props contract for `EntityAuthorCard`. |
+### `EntityAuthorCard` (default export)
+Main composer component. Renders a bordered grid with optional extra cells, a publication date cell, and an author cell. Returns `null` when `author` is empty unless `renderEmptyAuthor` is set.
+
+### `EntityMetadataValueCell`
+Standalone value cell: large `text-h4` label (uppercase by default) above a secondary `DM_Sans` 14px descriptor. Used for Type, Status, Date, or custom `extraCells`.
+
+### `EntityMetadataAuthorCell`
+Avatar + name + role label cell. Wraps the name in a link only when both `authorHref` and a real (non-placeholder) name are present — prevents linking placeholder text like "Unknown Author".
+
+### `EMPTY_AUTHOR_PLACEHOLDER`
+Exported constant (`full_name: '—'`, `job_title: 'Unknown'`) used by catalog grids that require a fixed skeleton shape when no author is available.
+
+### `EntityAuthorCardProps`
+Full prop interface. Key props:
+
+| Prop | Type | Description |
+|---|---|---|
+| `author` | `EntityAuthor \| null` | Author data |
+| `publishedAt` | `string \| Date \| null` | Triggers 2-cell (Published + Author) layout |
+| `extraCells` | `Array<{value, label, uppercase?}>` | Prepended value cells (e.g. Section, Step) |
+| `authorHref` | `string` | Link URL for author name |
+| `renderEmptyAuthor` | `boolean` | Force render with placeholder when author is absent |
 
 ## Usage Example
 
 ```typescript
-// Basic: author only (single-cell)
+// Two-cell: Published + Author
 <EntityAuthorCard
-  author={{ full_name: 'Ada Lovelace', avatar_url: '/ada.jpg', job_title: 'Engineer' }}
-/>
-
-// With publication date (2-cell grid)
-<EntityAuthorCard
-  author={{ full_name: 'Ada Lovelace', avatar_url: null, job_title: null }}
+  author={{ full_name: 'Jane Doe', avatar_url: '/avatar.jpg', job_title: 'Engineer' }}
   publishedAt="2024-06-01"
-  publishedLabel="Released"
-  roleLabel="Contributor"
+  authorHref="/authors/jane-doe"
 />
 
-// Extra cells before the date (4-cell grid)
+// Four-cell: Section + Step + Published + Author
 <EntityAuthorCard
-  author={author}
-  publishedAt={guide.publishedAt}
+  author={guide.author}
+  publishedAt={guide.published_at}
   extraCells={[
-    { value: 'Onboarding', label: 'Section' },
-    { value: '3',          label: 'Step'    },
+    { value: 'Setup', label: 'Section' },
+    { value: '3', label: 'Step' },
   ]}
-/>
-
-// Skeleton-safe: render even when author is absent
-<EntityAuthorCard
-  author={null}
   renderEmptyAuthor
 />
-```
 
-## Behavior Notes
+// Author-only (no date), placeholder fallback
+<EntityAuthorCard author={null} renderEmptyAuthor />
+```
 
-- Returns `null` when `author.full_name` is empty **unless** `renderEmptyAuthor` is set — keeps catalog grids skeleton-aligned.
-- Grid columns (`md:grid-cols-1` → `md:grid-cols-4`) are computed at render time so Tailwind JIT picks up the literal class strings at build.
-- Invalid date strings from `formatDate` are silently suppressed — the Published cell is hidden rather than showing `"Invalid Date"`.
+**Source:** [`entity-author-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/entity-author-card.tsx)

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

@@ -0,0 +1,47 @@
+<!-- source-hash: 04c12d798410d197c90950258dda5c3e -->
+Shared portrait-density card anatomy used by all entity card types (`size="portrait"`), encoding media zone, title zone, and footer zone layout exactly once to prevent per-card drift.
+
+## Key Components
+
+### Interfaces
+
+- **`EntityPortraitPerson`** — Author/person data: `name`, optional `avatarUrl`, `subtitle`, and `iconOverlayUrl` (small round overlay on avatar bottom-right, e.g. MSP company icon)
+- **`EntityPortraitCardProps`** — Full card props: `href`, `typeLabel` (content-type chip), `imageUrl`, `placeholderUrl`, `title`, `titleClassName` (typography override per entity), `person`, and `className`
+
+### Component
+
+- **`EntityPortraitCard`** — Renders three fixed anatomical zones inside a hover-styled `Card`:
+  - **Media zone** (`aspect-[1200/630]`): Wide covers fill `object-cover`; non-wide covers (e.g. square podcast art) render `object-contain` on an edge-sampled background color via `useImageEdgeColor`
+  - **Title zone** (`h-[72px]`): Optional `StatusBadge` eyebrow chip + 2- or 3-line clamped title with per-entity `titleClassName`
+  - **Footer zone** (`h-[60px]`): Avatar (or initial fallback) + name + subtitle, with optional `iconOverlayUrl` overlay
+
+### Constants
+
+- **`MIN_WIDE_RATIO`** (`1.3`) — Aspect ratio threshold distinguishing wide OG-style covers from square/portrait artwork
+
+## Usage Example
+
+```typescript
+import { EntityPortraitCard } from './entity-portrait-card'
+
+<EntityPortraitCard
+  href="/case-studies/acme-corp"
+  typeLabel="Case Study"
+  imageUrl="https://cdn.example.com/covers/acme-1200x630.jpg"
+  placeholderUrl="https://cdn.example.com/og-fallback.jpg"
+  imageAlt="Acme Corp case study cover"
+  title="How Acme Corp reduced IT tickets by 60%"
+  person={{
+    name: "Jane Smith",
+    avatarUrl: "https://cdn.example.com/avatars/jane.jpg",
+    subtitle: "IT Director, Acme Corp",
+    iconOverlayUrl: "https://cdn.example.com/logos/acme-icon.png",
+  }}
+/>
+```
+
+## Notes
+
+- The `typeLabel` prop should be omitted on single-type rails (all cards are the same content type) and passed only on mixed-type rails
+- Cover image resolution follows the shared `useCoverImageFallback` chain: real image → `placeholderUrl` → hidden
+- The footer zone renders an empty fixed-height box even when `person` is `null`, preserving baseline alignment across a rail

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

@@ -1,13 +1,13 @@
-<!-- source-hash: 775503f0a371e047d64f92c3ad355efe -->
-A pure-presentation React component that renders a compact, reusable entity card for chat contexts that don't require a bespoke component. Supports optional linking, status badges, key-value facts, and a skeleton loading state.
+<!-- source-hash: bb992ce717c9d3fc2ce3e4ae967ccebd -->
+A pure-presentation React component that renders a compact, reusable entity/document card for chat interfaces, supporting optional links, status badges, key-value facts, and a loading skeleton state.
 
 ## Key Components
 
 ### `GenericEntityCard`
-Main card component. Renders as an `<a>` tag (clickable) or `<span>` (static) depending on whether a URL or `anchorProps` is provided. Displays an `ExternalLink` icon when a URL is present.
+Main card component. Renders as an `<a>` (with `anchorProps` or derived `href`) or a static `<span>` when no URL is available. Displays title, optional badge, subtitle, preview text, fact rows, and a formatted date.
 
 ### `GenericEntityCardSkeleton`
-Animated placeholder component that mirrors the layout of `GenericEntityCard` for use during loading states.
+Shimmer/placeholder version of the card for loading states, matching the layout of the full card.
 
 ### Interfaces
 
@@ -15,48 +15,49 @@ Animated placeholder component that mirrors the layout of `GenericEntityCard` fo
 |---|---|
 | `GenericEntityCardItem` | Data shape for the card content |
 | `GenericEntityCardAnchorProps` | Pre-composed anchor element props (href, target, rel, onClick) |
-| `GenericEntityCardProps` | Combined props for the card (item + anchorProps + className) |
+| `GenericEntityCardProps` | Combined props for `GenericEntityCard` |
 
 ### `GenericEntityCardItem` Fields
 
 | Field | Type | Description |
 |---|---|---|
+| `id` | `string` | Unique identifier |
 | `title` | `string` | Primary heading |
-| `preview` | `string \| null` | Truncated body text (2-line clamp) |
-| `subtitle` | `string \| null` | Monospace secondary label |
-| `badge` | `{ text, scheme? }` | Status badge with color scheme |
-| `facts` | `Array<{ label, value }>` | Inline key-value metadata pairs |
-| `dateUpdated` | `string \| number \| null` | Formatted UTC timestamp |
-| `url` | `string \| null` | Optional navigation target |
+| `preview` | `string \| null` | 2-line clamped body text |
+| `url` | `string \| null` | Link target (sanitized via `safeHref`) |
+| `subtitle` | `string \| null` | Monospace secondary line |
+| `badge` | `{ text, scheme? } \| null` | Status badge with color scheme |
+| `facts` | `Array<{ label, value }>` | Inline key-value pairs |
+| `dateUpdated` | `string \| number \| null` | Formatted as local UTC date |
 
 ## Usage Example
 
 ```typescript
 import { GenericEntityCard, GenericEntityCardSkeleton } from './generic-entity-card'
 
-// Basic card with URL
+// With external link controlled by parent
 <GenericEntityCard
   item={{
     id: 'ticket-42',
-    title: 'Printer offline on Floor 2',
-    subtitle: 'TKT-0042',
-    preview: 'User reports printer is unreachable since 9am.',
+    title: 'Printer offline – HQ Floor 2',
+    subtitle: 'TKT-00042',
     badge: { text: 'Open', scheme: 'warning' },
+    preview: 'User reports printer is not responding since 09:00.',
     facts: [{ label: 'Priority', value: 'High' }],
-    dateUpdated: '2024-06-01T10:00:00Z',
-    url: 'https://app.example.com/tickets/42',
+    url: 'https://psa.example.com/tickets/42',
+    dateUpdated: '2024-06-01T09:00:00Z',
   }}
-/>
-
-// Custom anchor props (e.g. SPA router navigation)
-<GenericEntityCard
-  item={item}
   anchorProps={{
-    href: '/tickets/42',
-    onClick: (e) => { e.preventDefault(); router.push('/tickets/42') },
+    href: 'https://psa.example.com/tickets/42',
+    target: '_blank',
+    rel: 'noopener noreferrer',
   }}
 />
 
 // Loading state
 <GenericEntityCardSkeleton />
-```
+```
+
+## Source
+
+[`generic-entity-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/generic-entity-card.tsx)

package/src/components/chat/entity-cards/.github-activity-card.md

@@ -1,51 +1,50 @@
-<!-- source-hash: c0769109de52014dbb4d350262e4d01d -->
-A pure-presentation React component that renders GitHub activity items (commits, pull requests, and PR reviews) in two layout variants: a list row and a compact inline card.
+<!-- source-hash: 76bf0c6e541cd02e03174f0063150c97 -->
+A pure-presentation React component that renders GitHub activity (commits, pull requests, and PR reviews) as a unified visual card in two layout variants: a horizontal `row` for list views and a `compact` inline card for chat markers.
 
 ## Key Components
 
-### Exports
+### `GitHubActivityCard`
+Main export. Renders a `GitHubActivityItem` in either `"row"` or `"compact"` variant. Accepts an optional `anchorProps` bundle from the caller (e.g., a `useNavLink` hook) to control navigation without internal routing logic.
 
-| Name | Type | Description |
-|------|------|-------------|
-| `GitHubActivityCard` | Component | Main card renderer supporting `row` and `compact` variants |
-| `GitHubActivityCardSkeleton` | Component | Animated loading placeholder matching both variants |
-| `GitHubActivityCardAnchorProps` | Interface | Pre-composed `<a>` prop bundle passed from caller navigation hooks |
-| `GitHubActivityCardProps` | Interface | Full props shape for `GitHubActivityCard` |
+### `GitHubActivityCardSkeleton`
+Loading placeholder matching the layout of `GitHubActivityCard` for both variants.
 
-### Internal Helpers
+### Exported Utilities
 
-| Name | Description |
-|------|-------------|
-| `parseRepoFromUrl` | Extracts `owner/repo` string from a GitHub URL |
-| `kindIcon` | Returns the appropriate Lucide/GitHub icon for `commit`, `pull_request`, or `pr_review` |
-| `kindLabel` | Maps `GitHubActivityKind` to a short display string |
-| `formatActivityId` | Shortens commit SHAs to 7 chars; prefixes PR/review IDs with `#` |
-| `parseGithubTitle` | Parses bracket-prefixed tags (e.g. `[Review:APPROVED]`) from titles without regex backtracking |
-| `ReviewStateBadge` | Renders a color-coded badge for PR review states (`APPROVED`, `CHANGES_REQUESTED`, etc.) |
+| Function | Description |
+|---|---|
+| `kindLabel(kind)` | Maps `GitHubActivityKind` → `"Commit"` / `"PR"` / `"Review"` |
+| `formatActivityId(id, kind)` | Shortens a SHA to 7 chars or prefixes PR/review IDs with `#` |
+| `parseGithubTitle(title, kind)` | Strips bracket prefix tags (e.g., `[Review:APPROVED]`), returns display text and `PrReviewState` |
+| `reviewStateLabel(state)` | Maps `PrReviewState` → human label (`"Approved"`, `"Changes"`, etc.) |
 
 ## Usage Example
 
 ```typescript
-import { GitHubActivityCard, GitHubActivityCardSkeleton } from './github-activity-card'
-
-// Compact inline card (default) with external link
-<GitHubActivityCard
-  item={{
-    kind: 'pull_request',
-    id: '42',
-    title: 'Fix memory leak in worker pool',
-    url: 'https://github.com/org/repo/pull/42',
-    dateUpdated: '2024-11-01T10:00:00Z',
-  }}
-/>
-
-// Row variant for activity lists, with caller-composed navigation
+import { GitHubActivityCard } from './github-activity-card'
+import type { GitHubActivityItem } from '../types/entities/github-activity'
+
+const item: GitHubActivityItem = {
+  kind: 'pull_request',
+  id: '42',
+  title: 'Fix auth token refresh',
+  repo: 'flamingo-stack/openframe-oss-lib',
+  url: 'https://github.com/flamingo-stack/openframe-oss-lib/pull/42',
+  dateUpdated: '2024-11-01T12:00:00Z',
+}
+
+// Compact card (chat inline)
+<GitHubActivityCard item={item} variant="compact" />
+
+// Row with caller-controlled navigation
 <GitHubActivityCard
+  item={item}
   variant="row"
-  item={activityItem}
   anchorProps={{
-    href: '/activity/commit/abc1234',
-    onClick: (e) => handleNavigation(e),
+    href: item.url,
+    target: '_blank',
+    rel: 'noopener noreferrer',
+    onClick: (e) => handleNav(e),
   }}
 />
 
@@ -53,9 +52,4 @@ import { GitHubActivityCard, GitHubActivityCardSkeleton } from './github-activit
 <GitHubActivityCardSkeleton variant="row" />
 ```
 
-## Variants
-
-| Variant | Use Case |
-|---------|----------|
-| `compact` | Chat inline markers (`[card://github_commit:<sha>]`) |
-| `row` | Activity list rows in employee detail views |
+**Source:** [`github-activity-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/github-activity-card.tsx)

package/src/components/chat/entity-cards/.hubspot-ticket-card.md

@@ -1,53 +1,47 @@
-<!-- source-hash: 526a5a2e2cd1e53b04aca51a563fe490 -->
-Pure presentation component that renders HubSpot ticket data as a compact card or inline row, with a matching skeleton loader for loading states.
+<!-- source-hash: fa39082d0ecd56100a736a21747fae80 -->
+Unified presentation component for rendering HubSpot ticket data as a card or inline row, with no internal navigation logic — link behavior is fully delegated to the caller via `anchorProps`.
 
 ## Key Components
 
 ### `HubspotTicketCard`
-Main card component supporting two layout variants:
-- **`compact`** (default) — Full card with title, priority/status badges, customer email, description preview, meta row (company + date), and optional external link icon
-- **`row`** — Slim inline layout for use in lists/tables: title, preview snippet, status badge, and date
-
-Accepts an `anchorProps` bundle for caller-controlled navigation (e.g. from a runtime hook), falling back to a plain `<a>` using `item.url`, or a static `<span>` if no URL is available.
+Primary export. Renders a `HubspotTicketItem` in one of two layouts:
+- **`compact`** (default): Full card with title, priority/status badges, customer email, preview text, company, and date. Links via `anchorProps`, a derived `href`, or renders as a static `<span>` if no URL is available.
+- **`row`**: Minimal inline layout — title, preview snippet, status badge, and date — suited for list or table rows.
 
 ### `HubspotTicketCardSkeleton`
-Animated pulse placeholder matching the `compact` and `row` layouts, used during data fetching.
+Loading placeholder matching the `compact` or `row` layout with animated pulse shimmer blocks.
+
+### Helper functions
 
-### Helper Functions
 | Function | Purpose |
 |---|---|
-| `formatToken` | Normalizes `snake_case` enum strings to `Title case` |
-| `priorityScheme` | Maps `URGENT/HIGH/MEDIUM/LOW` → badge color scheme |
-| `statusScheme` | Maps `CLOSED/OPEN/...` → badge color scheme |
+| `formatToken` | Normalizes `SNAKE_CASE` enum strings to `Title case` for display |
+| `priorityScheme` | Maps `URGENT / HIGH / MEDIUM / …` to badge color variants |
+| `statusScheme` | Maps `CLOSED / OPEN / …` to badge color variants |
 
-## Interfaces
+### Interfaces
 
-```typescript
-interface HubspotTicketCardProps {
-  item: HubspotTicketItem      // Ticket data shape
-  variant?: 'row' | 'compact' // Layout mode (default: 'compact')
-  className?: string
-  anchorProps?: HubspotTicketCardAnchorProps // Caller-controlled <a> props
-}
-```
+- **`HubspotTicketCardAnchorProps`** — `href`, optional `target`, `rel`, and `onClick` passed through to the rendered `<a>`.
+- **`HubspotTicketCardProps`** — `item`, `variant`, `className`, `anchorProps`.
 
 ## Usage Example
 
 ```typescript
-// Compact card with caller-supplied navigation
+// Compact card driven by caller-composed anchor props
 <HubspotTicketCard
-  item={ticket}
+  item={ticketItem}
+  variant="compact"
   anchorProps={{
-    href: buildTicketHref(ticket.id),
+    href: ticketItem.url,
     target: '_blank',
     rel: 'noopener noreferrer',
-    onClick: (e) => handleTicketClick(e, ticket.id),
+    onClick: (e) => handleTicketClick(e, ticketItem.id),
   }}
 />
 
-// Inline row variant (e.g. inside a list)
-<HubspotTicketCard item={ticket} variant="row" />
+// Inline row variant (e.g. inside a search result list)
+<HubspotTicketCard item={ticketItem} variant="row" />
 
-// Loading state
+// Skeleton while data loads
 <HubspotTicketCardSkeleton variant="compact" />
 ```

package/src/components/chat/entity-cards/.index.md

@@ -1,66 +1,55 @@
-<!-- source-hash: 153106e38c4d90f80e36ec34a77c2d0d -->
-Barrel export file that consolidates all chat-surface entity card components under a single import path, enabling consumers to access any presentation card without knowing its subdirectory location.
+<!-- source-hash: 791f7cf08b31a1737cab8b5f7f5f9512 -->
+Barrel file that consolidates all chat-surface entity card components, primitives, and utilities into a single import path for consumers.
 
 ## Key Components
 
 ### Supporting Primitives
-- **`EntityAuthorCard`** — Renders author metadata with `EMPTY_AUTHOR_PLACEHOLDER` fallback
-- **`BlogImagePlaceholder`** — Placeholder image for blog content
+- **`EntityAuthorCard`** — Author display card with metadata cells (`EntityMetadataValueCell`, `EntityMetadataAuthorCell`)
+- **`EntityPortraitCard`** — Portrait-style entity card with person data
+- **`BlogImagePlaceholder`** — Placeholder component for blog cover images
+- **`useCoverImageFallback` / `hideOnError`** — Hook and utility for cover image error handling
 - **`AdminContentCard`** — Admin-facing content card
+- **`WhatIShippedCard`** — Shipped-item card with skeleton loader
 
-### Flat Cards
-- **`BlockCard`** — Generic block-level card
-- **`ChatTicketItem`** — Ticket representation within chat surfaces
-- **`ChatVideoEntityCard`** — Video entity display in chat
+### Chat Surface Cards
+- **`BlockCard`**, **`ChatTicketItem`**, **`ChatVideoEntityCard`** — Flat inline chat cards
+- **`ProductReleaseCard`** — Release card with size variants and prop builders (`defaultBuildProductReleaseCardProps`, `buildProductReleaseCardProps`)
+- **`BlogCard`**, **`CaseStudyCard`**, **`CustomerInterviewCard`**, **`InvestorUpdateCard`** — Content-type cards with skeleton loaders
+- **`OnboardingGuideCard`**, **`RoadmapCard`**, **`GitHubActivityCard`**, **`SlackMessageCard`** — Operational entity cards
+- **`HubspotTicketCard`**, **`DataRoomDocCard`**, **`ProgramCard`**, **`CampaignCardAdmin`**, **`GenericEntityCard`** — Integration and generic cards
 
-### Pure-Presentation Cards (with Skeleton variants)
-| Card | Skeleton | Notes |
-|------|----------|-------|
-| `BlogCard` | `BlogCardSkeleton` | — |
-| `CaseStudyCard` | `CaseStudyCardSkeleton` | — |
-| `CustomerInterviewCard` | `CustomerInterviewCardSkeleton` | — |
-| `InvestorUpdateCard` | `InvestorUpdateCardSkeleton` | — |
-| `OnboardingGuideCard` | `OnboardingGuideCardSkeleton` | — |
-| `RoadmapCard` | `RoadmapCardSkeleton` | Includes `VoteType` + `RoadmapVoteButton` |
-| `GitHubActivityCard` | `GitHubActivityCardSkeleton` | — |
-| `SlackMessageCard` | `SlackMessageCardSkeleton` | — |
-| `HubspotTicketCard` | `HubspotTicketCardSkeleton` | — |
-| `DataRoomDocCard` | `DataRoomDocCardSkeleton` | — |
-| `ProgramCard` | `ProgramCardSkeleton` | — |
-| `CampaignCardAdmin` | `CampaignCardAdminSkeleton` | — |
-| `GenericEntityCard` | `GenericEntityCardSkeleton` | Fallback catch-all |
+### Dispatch System
+- **`renderChatInlineEntityCard`** — Function that resolves and renders the correct card for a given entity type
+- **`ChatCardLoader`** — Component wrapper driven by `CHAT_CARD_REGISTRY` in `dispatch.tsx`
 
-### Dispatch Layer
-- **`renderChatInlineEntityCard`** — Renders the correct card given an entity type
-- **`ChatCardLoader`** — Async card loader; new card types registered in `./dispatch.tsx` via `CHAT_CARD_REGISTRY`
+### Utilities
+- **`programItemToStripProfile`** — Adapter converting program items to strip profile format
+- **`TaskTypeIcon`**, **`RoadmapVoteButton`** — Shared UI primitives used across card types
 
 ## Usage Example
 
 ```typescript
-// Single import replaces per-directory imports
 import {
   BlogCard,
   BlogCardSkeleton,
-  RoadmapCard,
+  ProductReleaseCard,
+  buildProductReleaseCardProps,
   ChatCardLoader,
   renderChatInlineEntityCard,
   type BlogCardProps,
-  type ChatCardRenderOptions,
-} from '@/components/entity-cards'
+} from '@openframe/lib/entity-cards'
 
-// Pure-presentation: consumer owns the anchor
-function MyFeed({ post }: { post: BlogCardProps }) {
-  return (
-    <NavLinkAnchor href={post.href}>
-      <BlogCard {...post} />
-    </NavLinkAnchor>
-  )
-}
+// Render a blog card — consumer provides the anchor wrapper
+const props: BlogCardProps = { href: '/blog/my-post', title: 'Hello', coverUrl: '...' }
+;<NavLinkAnchor href={props.href}>
+  <BlogCard {...props} />
+</NavLinkAnchor>
 
-// Dynamic dispatch — resolves card type at runtime
-function ChatEntity({ entity, options }: { entity: unknown; options: ChatCardRenderOptions }) {
-  return renderChatInlineEntityCard(entity, options)
-}
+// Dispatch a card by entity type in a chat surface
+renderChatInlineEntityCard({ type: 'blog', entity: blogEntity }, options)
+
+// Build rich product release card props
+const cardProps = buildProductReleaseCardProps(release, { size: 'lg' })
 ```
 
-> **Design contract:** All cards in this directory are **pure presentation** — they accept a pre-resolved `href` and entity data as props and contain no internal navigation logic. Click handling belongs to the consumer (`NavLinkAnchor` or `NavLinkAnchorViaRuntime`).
+> **Design contract:** All cards in this directory are pure-presentation components — they accept a pre-resolved `href` and entity data as props and contain no internal navigation logic. Consumers are responsible for wrapping cards with their own anchor components (`NavLinkAnchor` or `NavLinkAnchorViaRuntime`).