@flamingo-stack/openframe-frontend-core 0.0.212 → 0.0.213-snapshot.20260528174436

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

@@ -0,0 +1,47 @@
+<!-- source-hash: ff394dac0474471ce2eebef4dbdbb49b -->
+A pure-presentation compact card component for displaying marketing campaigns inline in chat interfaces. Renders a 3-row layout with icon, title, metadata, and description — with optional anchor wrapping for navigation.
+
+## Key Components
+
+### Interfaces
+
+| Interface | Purpose |
+|-----------|---------|
+| `CampaignCardItem` | Minimal campaign data shape (id, name, description, start_date, goals) |
+| `CampaignCardAdminAnchorProps` | Anchor element props bundle (href, target, rel, onClick) |
+| `CampaignCardAdminProps` | Main component props (campaign, className, anchorProps) |
+
+### Exports
+
+- **`CampaignCardAdmin`** — Primary compact card. Renders as a clickable `<a>` when `anchorProps` is provided, otherwise falls back to a static `<span>`. Displays campaign name, start date, goal count, and description.
+- **`CampaignCardAdminSkeleton`** — Loading placeholder matching the card's 3-row layout using shimmer blocks.
+
+## Usage Example
+
+```typescript
+// With navigation link
+<CampaignCardAdmin
+  campaign={{
+    id: 'camp_123',
+    name: 'Q3 Product Launch',
+    description: 'Multi-channel awareness campaign',
+    start_date: '2024-07-01',
+    goals: [{ id: 1 }, { id: 2 }],
+  }}
+  anchorProps={{
+    href: '/campaigns/camp_123',
+    target: '_blank',
+    rel: 'noopener noreferrer',
+  }}
+/>
+
+// Static (no navigation)
+<CampaignCardAdmin
+  campaign={{ id: 'camp_123', name: 'Q3 Launch' }}
+/>
+
+// Loading state
+<CampaignCardAdminSkeleton className="my-2" />
+```
+
+> **Note:** This is the chat-inline compact variant only. The full-size admin card (with delete/manage actions) is managed by the hub, not this component.

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

@@ -0,0 +1,58 @@
+<!-- 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).
+
+## 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.
+
+### `CaseStudyCardSkeleton`
+Loading placeholder that mirrors the exact layout and aspect ratios of `CaseStudyCard` for both size variants, using `animate-pulse`.
+
+### Image Fallback Chain
+```text
+study.featured_image → placeholderUrl (from useOgPlaceholder) → bg-ods-bg background
+```
+
+## Key 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 |
+
+## Usage Example
+
+```typescript
+import { CaseStudyCard, CaseStudyCardSkeleton } from './case-study-card'
+import { useOgPlaceholder } from '../hooks/use-og-placeholder'
+
+function CaseStudyGrid({ studies }: { studies: CaseStudy[] }) {
+  const placeholderUrl = useOgPlaceholder(study.id)
+
+  if (!studies) return <CaseStudyCardSkeleton size="default" />
+
+  return (
+    <CaseStudyCard
+      study={study}
+      href={`/case-studies/${study.slug}`}
+      placeholderUrl={placeholderUrl}
+      size="default"
+    />
+  )
+}
+
+// Chat-inline compact variant
+<CaseStudyCard
+  study={study}
+  href={`/case-studies/${study.slug}`}
+  target="_blank"
+  rel="noopener noreferrer"
+  size="sm"
+/>
+```

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

@@ -0,0 +1,40 @@
+<!-- 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.
+
+## 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 `•`
+
+### `ChatTicketItemProps`
+Extends `ButtonHTMLAttributes` (omitting `onClick`) with a typed `onClick?: (ticketId: string) => void` callback.
+
+### `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
+
+## Usage Example
+
+```typescript
+<ChatTicketItem
+  ticket={{
+    id: 'tkt-001',
+    title: 'Email not syncing after password reset',
+    ticketNumber: '#1042',
+    status: 'ACTION_REQUIRED',
+    statusLabel: 'Waiting on contact',
+    category: 'Email',
+    timeAgo: '2h ago',
+    linkedTaskLabel: 'Waiting on version release',
+  }}
+  onClick={(ticketId) => router.push(`/tickets/${ticketId}`)}
+/>
+```

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

@@ -0,0 +1,43 @@
+<!-- source-hash: 4a819f268fa72ed0c9baa868c023b47f -->
+Renders a stripped-chrome video player card for entity references within the chat interface, delegating entirely to `<EntityVideoSection>` to maintain visual parity with detail pages.
+
+## Key Components
+
+### `ChatVideoEntityCardProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `chatRef` | `ChatRef` | Entity reference containing `metadata` fields for video URL routing |
+
+### `ChatVideoEntityCard`
+Main export. Extracts video-related fields from `chatRef.metadata` and passes them directly to `<EntityVideoSection>`. Intentionally omits `videoSummary`, `videoBites`, and header chrome (title, date, Ask button) to preserve chat panel density — those affordances are handled by the host's inline pill.
+
+### `readString(value)`
+Internal guard that returns `null` for any non-string or empty-string value, preventing invalid URLs from reaching the player.
+
+## Metadata Fields Read
+
+| Field | Passed As |
+|-------|-----------|
+| `metadata.videoUrl` | `mainVideoUrl` |
+| `metadata.youtubeUrl` | `youtubeUrl` |
+| `metadata.videoPoster` | `mainVideoPoster` |
+| `metadata.highlightVideoUrl` | `highlightVideoUrl` |
+| `metadata.highlightVideoPoster` | `highlightVideoThumbnail` |
+
+## Usage Example
+
+```typescript
+// Host dispatch — only routed here when at least one video URL is present
+<ChatVideoEntityCard
+  chatRef={{
+    title: "Q3 Investor Update",
+    metadata: {
+      youtubeUrl: "https://www.youtube.com/watch?v=abc123",
+      highlightVideoUrl: "https://stream.mux.com/highlight.m3u8",
+      highlightVideoPoster: "https://cdn.example.com/poster.jpg",
+    },
+  }}
+/>
+```
+
+> **Activation contract:** The host must only render this card when at least one of `metadata.videoUrl`, `youtubeUrl`, or `highlightVideoUrl` is a non-empty string. URL sanitization is handled inside `<Video>` — no additional validation is required at the call site.

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

@@ -0,0 +1,53 @@
+<!-- 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`.
+
+## Key Components
+
+### `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.
+
+### `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
+}
+```
+
+## Usage Example
+
+```typescript
+// Default card — standalone page listing
+<CustomerInterviewCard
+  interview={interviewData}
+  href={`/interviews/${interviewData.slug}`}
+  placeholderUrl="/assets/interview-placeholder.jpg"
+/>
+
+// Compact variant — inline within chat/AI responses
+<CustomerInterviewCard
+  interview={interviewData}
+  href={`/interviews/${interviewData.slug}`}
+  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) |

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

@@ -0,0 +1,47 @@
+<!-- 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.
+
+## 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.
+
+### `DataRoomDocCardSkeleton`
+Loading state placeholder matching the card's layout — used while document data is being fetched.
+
+### `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.
+
+### `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 |
+
+## Usage Example
+
+```typescript
+// Interactive card (linked)
+<DataRoomDocCard
+  item={{ title: 'Onboarding Guide', path: '/docs/onboarding.md', preview: 'Step-by-step...' }}
+  badgeText={getSourceLabel(item.sourceRepo)}  // consumer resolves label
+  anchorProps={{
+    href: '/data-room/docs/abc123',
+    target: '_blank',
+    rel: 'noopener noreferrer',
+  }}
+/>
+
+// Non-interactive card (no link resolved)
+<DataRoomDocCard
+  item={{ title: 'Policy Draft', path: null, preview: null }}
+  badgeText="Knowledge Base"
+/>
+
+// Skeleton while loading
+<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.

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

@@ -0,0 +1,39 @@
+<!-- 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.
+
+## 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
+
+### 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)
+
+### Utilities Used
+- `buildAnchorProps` / `computeIsNewTab` / `newTabAnchorAttrs` — Anchor attribute construction
+- `resolveHrefForRuntime` / `handleChatNavClick` — Runtime-aware navigation
+- `resolveSourceRowCTA` / `resolveSourceIcon` / `getSourceLabel` — Source chip metadata
+
+## Usage Example
+
+```typescript
+// In the chat shell — dispatch a compact inline card
+const card = renderChatInlineEntityCard(chatRef, {
+  isNewTab: computeIsNewTab(chatRef.url, runtime.source),
+  baseRoute: '/app',
+  chipBasePlatform: 'hub',
+  extras: {
+    programConfigs: { podcast: myPodcastConfig },
+    buildProductReleaseCardProps: (release) => ({ iconUrl: release.icon }),
+    buildOgPlaceholderUrl: (title) => `/og?title=${encodeURIComponent(title)}`,
+  },
+})
+```
+
+> **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.

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

@@ -0,0 +1,51 @@
+<!-- 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.
+
+## 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`. |
+
+## Usage Example
+
+```typescript
+// Basic: author only (single-cell)
+<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 }}
+  publishedAt="2024-06-01"
+  publishedLabel="Released"
+  roleLabel="Contributor"
+/>
+
+// Extra cells before the date (4-cell grid)
+<EntityAuthorCard
+  author={author}
+  publishedAt={guide.publishedAt}
+  extraCells={[
+    { value: 'Onboarding', label: 'Section' },
+    { value: '3',          label: 'Step'    },
+  ]}
+/>
+
+// Skeleton-safe: render even when author is absent
+<EntityAuthorCard
+  author={null}
+  renderEmptyAuthor
+/>
+```
+
+## Behavior Notes
+
+- 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"`.

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

@@ -0,0 +1,62 @@
+<!-- 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.
+
+## 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.
+
+### `GenericEntityCardSkeleton`
+Animated placeholder component that mirrors the layout of `GenericEntityCard` for use during loading states.
+
+### Interfaces
+
+| Interface | Purpose |
+|---|---|
+| `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) |
+
+### `GenericEntityCardItem` Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `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 |
+
+## Usage Example
+
+```typescript
+import { GenericEntityCard, GenericEntityCardSkeleton } from './generic-entity-card'
+
+// Basic card with URL
+<GenericEntityCard
+  item={{
+    id: 'ticket-42',
+    title: 'Printer offline on Floor 2',
+    subtitle: 'TKT-0042',
+    preview: 'User reports printer is unreachable since 9am.',
+    badge: { text: 'Open', scheme: 'warning' },
+    facts: [{ label: 'Priority', value: 'High' }],
+    dateUpdated: '2024-06-01T10:00:00Z',
+    url: 'https://app.example.com/tickets/42',
+  }}
+/>
+
+// Custom anchor props (e.g. SPA router navigation)
+<GenericEntityCard
+  item={item}
+  anchorProps={{
+    href: '/tickets/42',
+    onClick: (e) => { e.preventDefault(); router.push('/tickets/42') },
+  }}
+/>
+
+// Loading state
+<GenericEntityCardSkeleton />
+```

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

@@ -0,0 +1,61 @@
+<!-- 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.
+
+## Key Components
+
+### Exports
+
+| 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` |
+
+### Internal Helpers
+
+| 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.) |
+
+## 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
+<GitHubActivityCard
+  variant="row"
+  item={activityItem}
+  anchorProps={{
+    href: '/activity/commit/abc1234',
+    onClick: (e) => handleNavigation(e),
+  }}
+/>
+
+// Loading state
+<GitHubActivityCardSkeleton variant="row" />
+```
+
+## Variants
+
+| Variant | Use Case |
+|---------|----------|
+| `compact` | Chat inline markers (`[card://github_commit:<sha>]`) |
+| `row` | Activity list rows in employee detail views |

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

@@ -0,0 +1,53 @@
+<!-- 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.
+
+## 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.
+
+### `HubspotTicketCardSkeleton`
+Animated pulse placeholder matching the `compact` and `row` layouts, used during data fetching.
+
+### 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 |
+
+## Interfaces
+
+```typescript
+interface HubspotTicketCardProps {
+  item: HubspotTicketItem      // Ticket data shape
+  variant?: 'row' | 'compact' // Layout mode (default: 'compact')
+  className?: string
+  anchorProps?: HubspotTicketCardAnchorProps // Caller-controlled <a> props
+}
+```
+
+## Usage Example
+
+```typescript
+// Compact card with caller-supplied navigation
+<HubspotTicketCard
+  item={ticket}
+  anchorProps={{
+    href: buildTicketHref(ticket.id),
+    target: '_blank',
+    rel: 'noopener noreferrer',
+    onClick: (e) => handleTicketClick(e, ticket.id),
+  }}
+/>
+
+// Inline row variant (e.g. inside a list)
+<HubspotTicketCard item={ticket} variant="row" />
+
+// Loading state
+<HubspotTicketCardSkeleton variant="compact" />
+```

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

@@ -0,0 +1,66 @@
+<!-- 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.
+
+## Key Components
+
+### Supporting Primitives
+- **`EntityAuthorCard`** — Renders author metadata with `EMPTY_AUTHOR_PLACEHOLDER` fallback
+- **`BlogImagePlaceholder`** — Placeholder image for blog content
+- **`AdminContentCard`** — Admin-facing content card
+
+### Flat Cards
+- **`BlockCard`** — Generic block-level card
+- **`ChatTicketItem`** — Ticket representation within chat surfaces
+- **`ChatVideoEntityCard`** — Video entity display in chat
+
+### 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 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`
+
+## Usage Example
+
+```typescript
+// Single import replaces per-directory imports
+import {
+  BlogCard,
+  BlogCardSkeleton,
+  RoadmapCard,
+  ChatCardLoader,
+  renderChatInlineEntityCard,
+  type BlogCardProps,
+  type ChatCardRenderOptions,
+} from '@/components/entity-cards'
+
+// Pure-presentation: consumer owns the anchor
+function MyFeed({ post }: { post: BlogCardProps }) {
+  return (
+    <NavLinkAnchor href={post.href}>
+      <BlogCard {...post} />
+    </NavLinkAnchor>
+  )
+}
+
+// Dynamic dispatch — resolves card type at runtime
+function ChatEntity({ entity, options }: { entity: unknown; options: ChatCardRenderOptions }) {
+  return renderChatInlineEntityCard(entity, options)
+}
+```
+
+> **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`).