@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214

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`).

package/src/components/chat/entity-cards/.investor-update-card.md

@@ -0,0 +1,47 @@
+<!-- source-hash: 756619c21c965403499e06eb7fef94fa -->
+Pure presentation component for rendering investor update cards in two density modes (`default` and `sm`), with no internal click logic — callers supply the resolved `href`.
+
+## Key Components
+
+### `InvestorUpdateCard`
+Main card component. Renders differently based on the `size` prop:
+- **`default`** — delegates to `AdminContentCard` with image, title, summary, badges, and period meta
+- **`sm`** — compact horizontal layout using shared `COMPACT_CARD_*` utility classes
+
+### `InvestorUpdateCardSkeleton`
+Loading placeholder matching the visual footprint of each density mode. Uses `animate-pulse` for the default size.
+
+### `InvestorUpdateCardProps`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `update` | `InvestorUpdate` | Entity data |
+| `href` | `string` | Resolved detail URL (caller-supplied) |
+| `target` | `'_blank'` | Optional new-tab behavior |
+| `placeholderUrl` | `string \| null` | OG fallback when `featured_image` is absent |
+| `size` | `'default' \| 'sm'` | Card density (defaults to `'default'`) |
+
+## Usage Example
+
+```typescript
+// Default density — full card
+<InvestorUpdateCard
+  update={investorUpdate}
+  href={`/investor-updates/${investorUpdate.slug}`}
+  placeholderUrl="/images/update-placeholder.png"
+/>
+
+// Compact horizontal — e.g. inside a chat dispatch or sidebar list
+<InvestorUpdateCard
+  update={investorUpdate}
+  href={`/investor-updates/${investorUpdate.slug}`}
+  target="_blank"
+  rel="noopener noreferrer"
+  size="sm"
+/>
+
+// Skeleton while data loads
+<InvestorUpdateCardSkeleton size="sm" />
+```
+
+> **Design note:** The component intentionally owns zero click/navigation logic. Tab behavior (`target="_blank"`) is resolved externally (e.g. via `computeIsNewTab`) and passed in, keeping the component fully declarative.

package/src/components/chat/entity-cards/.onboarding-guide-card.md

@@ -0,0 +1,58 @@
+<!-- source-hash: ecac941a52e178236e11d54fe42337ec -->
+Pure presentation component that renders an onboarding guide card in three layout variants — `catalog`, `default`, and `sm` — plus matching skeleton states for loading UI.
+
+## Key Components
+
+### `OnboardingGuideCard`
+Main card component. Stateless and click-logic-free; the caller wraps with navigation and provides the resolved `href`.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `guide` | `OnboardingGuide` | Guide entity data |
+| `href` | `string` | Detail URL resolved by caller |
+| `target` | `'_blank'` | Optional new-tab behavior |
+| `size` | `'catalog' \| 'default' \| 'sm'` | Layout variant (default: `'default'`) |
+| `placeholderUrl` | `string \| null` | OG fallback image for catalog/sm |
+| `className` | `string` | Additional CSS classes |
+
+### `OnboardingGuideCardSkeleton`
+Loading placeholder that mirrors each layout variant's structure with animated pulse states.
+
+### `HORIZONTAL_SIZE_TOKENS`
+Internal token map for spacing/typography in the `default` variant.
+
+## Variants
+
+| Variant | Layout | Use Case |
+|---------|--------|----------|
+| `catalog` | Hero image + author grid | Public catalog page |
+| `default` | Horizontal step-numbered | "More in section" rail |
+| `sm` | Compact horizontal | Chat-inline rendering |
+
+## Usage Example
+
+```typescript
+import { OnboardingGuideCard, OnboardingGuideCardSkeleton } from './onboarding-guide-card'
+
+// Loading state
+if (isLoading) {
+  return <OnboardingGuideCardSkeleton size="catalog" />
+}
+
+// Catalog variant (public listing)
+<OnboardingGuideCard
+  guide={guide}
+  href={`/guides/${guide.slug}`}
+  size="catalog"
+  placeholderUrl={ogImageUrl}
+/>
+
+// Chat inline (sm variant, new tab)
+<OnboardingGuideCard
+  guide={guide}
+  href={`/guides/${guide.slug}`}
+  size="sm"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+```

package/src/components/chat/entity-cards/.product-release-card-defaults.md

@@ -0,0 +1,31 @@
+<!-- source-hash: 192500e77aad1a0a4024a9e7d8dfcfec -->
+Provides the lib-side default implementation of `buildProductReleaseCardProps` for chat dispatch, satisfying the three fields required by the compact (`size='sm'`) `<ProductReleaseCard>` variant without requiring hub-side extras.
+
+## Key Components
+
+### Interfaces
+- **`ReleaseLike`** — Loosely typed shape for raw API row data, covering image URLs, video URLs, and release date fields
+- **`DerivedSmProps`** — Output shape containing only the three sm-relevant props: `coverImage`, `hasVideoCover`, and `formattedDate`
+
+### Functions
+- **`pickCover(item)`** — Resolves the best cover image URL by mirroring the hub's `resolveReleaseCover` precedence: video thumbnails take priority when a video is set, falling back to `featured_image` then `og_image_url`
+- **`defaultBuildProductReleaseCardProps(item)`** — Main export; builds the `DerivedSmProps` bundle from an unknown API row, using `formatReleaseDate` for TZ-safe date formatting
+
+## Usage Example
+
+```typescript
+import { defaultBuildProductReleaseCardProps } from './product-release-card-defaults'
+
+// Used as fallback when opts.extras.buildProductReleaseCardProps is not supplied
+const props = defaultBuildProductReleaseCardProps(apiRow)
+// → { coverImage: 'https://...', hasVideoCover: true, formattedDate: 'Jan 15, 2025' }
+
+// Hub-side embedders override with their richer builder via extras:
+const cardProps = (opts.extras?.buildProductReleaseCardProps ?? defaultBuildProductReleaseCardProps)(row)
+```
+
+## Notes
+
+- Uses `formatReleaseDate` (not `new Date().toLocaleDateString`) to avoid UTC off-by-one day shifts on date-only `YYYY-MM-DD` strings
+- Produces an empty string for `formattedDate` when `release_date` is absent, rather than throwing
+- lg-only fields (`changelogCounts`, badge color, view count) are intentionally omitted — hub embedders supply those via `extras`