@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214-snapshot.20260528192313

package/src/components/chat/types/.network.types.md

@@ -1,45 +1,71 @@
-<!-- source-hash: d5397c1feb5364b7246e4091ad6ce652 -->
-Defines comprehensive network communication types for NATS messaging, WebSocket connections, and API responses. Includes configuration constants, chunk data structures, and error handling types for real-time messaging systems.
+<!-- source-hash: 8a6f81705a1810d60982ff3e397e9ebc -->
+Defines TypeScript types and constants for all network and communication layers in the Flamingo platform, including NATS messaging, WebSocket connections, streaming chunk data, and API response shapes.
 
 ## Key Components
 
-**Core Types:**
-- `NatsMessageType` - Message classification ('message' | 'admin-message')
-- `NatsConnectionStatus` - Connection state management
-- `ChunkData` - Streaming data chunks with tool integration support
-- `WebSocketMessage` & `WebSocketConfig` - WebSocket communication setup
+### Types & Enums
 
-**Configuration:**
-- `NETWORK_CONFIG` - Network timing and limits constants
-- Connection timeouts, reconnect intervals, and message limits
+| Export | Description |
+|--------|-------------|
+| `NatsMessageType` | Union type for NATS message categories: `'message'` or `'admin-message'` |
+| `NatsConnectionStatus` | Connection lifecycle states: `connecting`, `connected`, `disconnected`, `reconnecting`, `closed`, `error` |
+| `NatsConnectionSource` | Origin of a NATS connection: `client`, `agent`, or `dashboard` |
 
-**Response Types:**
-- `NetworkResponse<T>` - Standardized API response wrapper
-- `PaginatedResponse<T>` - Paginated data responses
-- `NetworkError` - Structured error information
+### Constants
+
+| Export | Description |
+|--------|-------------|
+| `NETWORK_CONFIG` | Frozen config object with timeouts, retry backoff, ping intervals, and message limits |
+| `NetworkConfig` | Inferred type from `NETWORK_CONFIG` |
+
+### Interfaces
+
+| Export | Description |
+|--------|-------------|
+| `ChunkData` | Streaming dialog chunk payload — carries sequence IDs, tool execution data, approval requests, model metadata, and stream state |
+| `BufferedChunk` | Wraps a `ChunkData` with its `NatsMessageType` for buffered delivery |
+| `WebSocketMessage` | Generic WebSocket envelope with `type`, `payload`, and optional metadata |
+| `WebSocketConfig` | Full WebSocket client configuration including reconnect strategy and event handlers |
+| `FetchChunksFunction` | Async function signature for polling dialog chunks by `dialogId` and `ChatType` |
+| `NetworkResponse<T>` | Standard API response wrapper with `success`, `data`, `error`, and `message` |
+| `PaginatedResponse<T>` | Extends `NetworkResponse<T>` with pagination metadata |
+| `NetworkError` | Structured error shape with `code`, `message`, optional `details`, and `timestamp` |
 
 ## Usage Example
 
 ```typescript
-import { ChunkData, NETWORK_CONFIG, WebSocketConfig } from './network.types'
-
-// Configure WebSocket connection
-const wsConfig: WebSocketConfig = {
-  url: 'ws://localhost:8080',
-  reconnect: true,
-  reconnectInterval: NETWORK_CONFIG.RECONNECT_TIME_WAIT_MS,
-  maxReconnectAttempts: 5,
-  onMessage: (event) => {
-    const chunk: ChunkData = JSON.parse(event.data)
-    console.log('Received chunk:', chunk.type, chunk.text)
+import type {
+  ChunkData,
+  FetchChunksFunction,
+  NetworkResponse,
+  PaginatedResponse,
+  NatsConnectionStatus,
+} from './network.types'
+import { NETWORK_CONFIG } from './network.types'
+
+// Use constants for consistent timeout configuration
+const client = createNatsClient({
+  timeout: NETWORK_CONFIG.CONNECT_TIMEOUT_MS,
+  reconnectTimeWait: NETWORK_CONFIG.RECONNECT_TIME_WAIT_MS,
+  maxPingOut: NETWORK_CONFIG.MAX_PING_OUT,
+})
+
+// Type-safe connection state handler
+function onStatusChange(status: NatsConnectionStatus) {
+  if (status === 'reconnecting') {
+    console.warn('NATS reconnecting...')
   }
 }
 
-// Handle streaming responses
-const processChunk = (chunk: ChunkData) => {
-  if (chunk.type === 'tool_call' && chunk.toolFunction) {
-    return executeFunction(chunk.toolFunction, chunk.parameters)
-  }
-  return chunk.text
+// Typed chunk fetch implementation
+const fetchChunks: FetchChunksFunction = async (dialogId, chatType, fromSequenceId) => {
+  const res = await api.get<ChunkData[]>(`/dialogs/${dialogId}/chunks`, {
+    params: { chatType, from: fromSequenceId },
+  })
+  return res.data
 }
+
+// Paginated API response
+const response: PaginatedResponse<ChunkData[]> = await fetchPage(dialogId, 1)
+console.log(`Page ${response.page} of ${response.totalPages}`)
 ```

package/src/components/chat/types/.processing.types.md

@@ -1,50 +1,68 @@
-<!-- source-hash: 66e8aa55f2252ec223d9953d34fa0194 -->
-TypeScript definitions for message processing and transformation, providing a complete type system for handling streaming chat messages, tool executions, approvals, and data transformations.
+<!-- source-hash: 118d3a4cacf89174498282067448e4bf -->
+Defines TypeScript types for message processing pipeline operations, including chunk parsing, accumulator state management, stream control, and buffer management for AI chat message flows.
 
 ## Key Components
 
-**Core Processing Types:**
-- `ParsedChunkAction` - Union type defining all possible chunk processing actions (text, tool execution, approvals, metadata)
-- `AccumulatorState` - State container tracking message segments, text buffers, and pending operations
-- `MessageProcessingOptions` - Configuration for message processing including assistant settings and approval callbacks
-
-**Processing Infrastructure:**
-- `ChunkProcessor` - Interface for processing individual data chunks with reset capability
-- `StreamProcessor` - Interface for managing streaming operations with lifecycle controls
-- `MessageTransformer` - Interface for converting raw data into processed messages
-
-**Buffer Management:**
-- `BufferManager` - Interface for managing chunk buffers with size limits and overflow handling
-- `BufferOptions` - Configuration for buffer behavior including flush intervals and callbacks
+| Export | Type | Description |
+|--------|------|-------------|
+| `ParsedChunkAction` | Union type | Discriminated union of all possible chunk parse results (text, tool execution, approvals, metadata, etc.) |
+| `AccumulatorState` | Interface | Stateful container tracking message segments, pending approvals, and executing tools during stream processing |
+| `PendingApproval` | Interface | Represents an approval request awaiting user action (command, explanation, type) |
+| `MessageProcessingOptions` | Interface | Configuration for assistant rendering, approval callbacks, chat filtering, and batch approval UI |
+| `ChunkProcessor` | Interface | Contract for processing raw `ChunkData` into `ParsedChunkAction` results |
+| `ChunkProcessorOptions` | Interface | Lifecycle callbacks for chunk processing events |
+| `MessageTransformer` | Interface | Contract for transforming raw inputs into `ProcessedMessage` objects |
+| `StreamProcessor` | Interface | Full lifecycle control (start/stop/pause/resume/reset) for stream consumers |
+| `StreamState` | Interface | Snapshot of stream health: active status, buffered chunks, error log, and last activity timestamp |
+| `BufferManager` | Interface | CRUD-style contract for managing `ChunkData` buffers |
+| `BufferOptions` | Interface | Configuration for buffer capacity, flush intervals, and overflow handling callbacks |
 
 ## Usage Example
 
 ```typescript
-import type { MessageProcessingOptions, AccumulatorState } from './processing.types'
+import type {
+  ParsedChunkAction,
+  AccumulatorState,
+  MessageProcessingOptions,
+  StreamState
+} from './processing.types'
 
-// Configure message processing
-const options: MessageProcessingOptions = {
-  assistantName: 'Fae',
-  assistantType: 'fae',
-  onApprove: async (requestId) => {
-    await handleApproval(requestId, true)
-  },
-  displayApprovalTypes: ['COMMAND_EXECUTION', 'FILE_ACCESS']
+// Handling a parsed chunk action via discriminated union
+function handleChunkAction(action: ParsedChunkAction): void {
+  switch (action.action) {
+    case 'text':
+      console.log('Received text:', action.text)
+      break
+    case 'tool_execution':
+      console.log('Tool executing:', action.segment)
+      break
+    case 'approval_batch':
+      console.log('Batch approval request:', action.requestId, action.toolCalls)
+      break
+    case 'error':
+      console.error('Processing error:', action.error, action.details)
+      break
+  }
 }
 
-// Initialize accumulator state
+// Initializing accumulator state
 const state: AccumulatorState = {
   segments: [],
-  currentTextBuffer: '',
   pendingApprovals: new Map(),
   executingTools: new Map()
 }
 
-// Process chunk with type safety
-const processor: ChunkProcessor = {
-  processChunk: (chunk, type) => {
-    return { action: 'text', text: chunk.content }
+// Configuring message processing
+const options: MessageProcessingOptions = {
+  assistantName: 'Mingo',
+  assistantType: 'mingo',
+  batchApprovalsEnabled: true,
+  displayApprovalTypes: ['shell', 'file'],
+  onApprove: async (requestId) => {
+    await submitApproval(requestId)
   },
-  reset: () => state.segments = []
+  onReject: (requestId) => {
+    logRejection(requestId)
+  }
 }
 ```

package/src/components/chat/types/.unified-chat-state.types.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 5419513463f6ad2b09f3c013740a3568 -->
+Shared TypeScript contract defining the unified state shape and supporting types that all chat transport hooks (SSE and NATS) must satisfy, enabling transport-agnostic consumption by UI components.
+
+## Key Components
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `StreamingPhase` | Type | `'idle' \| 'thinking' \| 'streaming'` — granular in-flight status for the streaming indicator UI |
+| `UnifiedUsageBreakdown` | Interface | SSE-only per-turn LLM telemetry (Haiku pipeline costs + routed answer metadata); always `null` in Mingo/NATS mode |
+| `UnifiedChatMessage` | Interface | Transport-agnostic message shape; SSE-only fields (`sources`, `chatRefs`) are optional, Mingo-safe |
+| `UnifiedSendMessageOptions` | Interface | Options for `sendMessage` — `hidden` (suppress UI render) and `attachments` (SSE-only image uploads) |
+| `UnifiedChatState` | Interface | The primary contract: full return shape every transport hook must implement, covering messages, actions, loading state, and SSE-only LLM metadata |
+
+## Usage Example
+
+```typescript
+// Consumer component — works identically for SSE (Guide) or NATS (Mingo)
+import type { UnifiedChatState, UnifiedSendMessageOptions } from './unified-chat-state.types'
+
+function ChatShell({ chat }: { chat: UnifiedChatState }) {
+  const { messages, isLoading, streamingPhase, sendMessage, stopMessage } = chat
+
+  async function handleSubmit(text: string, attachments?: ChatAttachment[]) {
+    const options: UnifiedSendMessageOptions = { attachments }
+    await sendMessage(text, options)
+  }
+
+  return (
+    <>
+      {/* SSE-only metadata — safely null in Mingo mode */}
+      {chat.currentModelLabel && <ModelDisplay label={chat.currentModelLabel} />}
+      {streamingPhase === 'thinking' && <span>Thinking...</span>}
+      {streamingPhase === 'streaming' && <span>Streaming...</span>}
+      <MessageList messages={messages.filter(m => !m.hidden)} />
+      <ChatInput onSubmit={handleSubmit} disabled={isLoading} onStop={stopMessage} />
+    </>
+  )
+}
+```
+
+> **Transport isolation:** `currentProvider`, `currentModelLabel`, `currentUsageBreakdown`, and related token fields are `null` in Mingo/NATS mode. Always guard with a null check before rendering LLM metadata.

package/src/components/chat/types/entities/.blog.md

@@ -0,0 +1,43 @@
+<!-- source-hash: 1be58b263102c7ac63390d5cdc4b8cba -->
+Re-exports blog entity types from the canonical `src/types/blog.ts` lib, providing a single import path for the chat card entity barrel.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `BlogPost` | Full blog post row shape |
+| `BlogPostSummary` | Catalog projection for listing/cards |
+| `BlogPostPlatform` | Platform identifier type |
+| `BlogPostCategory` | Post-level category association |
+| `BlogPostTag` | Post-level tag association |
+| `BlogCategory` | Blog category entity |
+| `BlogTag` | Blog tag entity |
+| `BlogAuthor` | Author entity shape |
+| `BlogMediaAsset` | Media/image asset type |
+| `BlogStatus` | Post status enum/union |
+| `BlogPagination` | Pagination metadata shape |
+| `BlogSearchParams` | Search/filter query params |
+
+## Usage Example
+
+```typescript
+// Import blog types from the entities barrel (single path)
+import type {
+  BlogPost,
+  BlogPostSummary,
+  BlogAuthor,
+  BlogPagination,
+} from '@/entities/blog';
+
+// Full post row (e.g. detail page)
+function renderPost(post: BlogPost) {
+  return `${post.title} by ${post.author.name}`;
+}
+
+// Summary projection (e.g. catalog card)
+function renderCard(summary: BlogPostSummary) {
+  return `${summary.title} — ${summary.category}`;
+}
+```
+
+> **Note:** Do not define competing blog shapes in the hub layer. Always consume from this barrel to ensure a single source of truth via `@/types/blog`.

package/src/components/chat/types/entities/.case-study.md

@@ -0,0 +1,26 @@
+<!-- source-hash: ef274b40abb94a68897a27d2ef3214c4 -->
+Re-exports `CaseStudy` entity types from the canonical lib definition (`src/types/case-study.ts`) into the chat card consumer barrel — no local type definitions are introduced.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `CaseStudy` | Core case study entity shape |
+| `CaseStudyFilters` | Filter parameters for querying case studies |
+| `CaseStudyListResponse` | Paginated/list response wrapper for case study results |
+
+## Usage Example
+
+```typescript
+import type { CaseStudy, CaseStudyFilters, CaseStudyListResponse } from '@/entities/case-study';
+
+const filters: CaseStudyFilters = { tag: 'networking' };
+
+const response: CaseStudyListResponse = await fetchCaseStudies(filters);
+
+response.items.forEach((study: CaseStudy) => {
+  console.log(study.title);
+});
+```
+
+> All types originate from `@/types/case-study` — this barrel acts as a stable re-export boundary so chat card consumers are decoupled from the underlying lib path.

package/src/components/chat/types/entities/.content-ref.md

@@ -0,0 +1,41 @@
+<!-- source-hash: c5cc84322439cd96dae36a797cb9a2cb -->
+Defines the `ContentRef` interface — the unified shape for link/embed references stored in JSONB columns across entities such as investor updates and performance baselines that surface "related content" rails.
+
+## Key Components
+
+### `ContentRef` Interface
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | `string` | ✅ | Content type identifier (e.g., `"video"`, `"article"`) |
+| `id` | `string` | ✅ | Unique content identifier |
+| `slug` | `string` | ✅ | URL-friendly slug |
+| `url` | `string` | ✅ | Canonical URL of the referenced content |
+| `targetPlatform` | `string \| null` | ❌ | Platform hint (e.g., `"youtube"`, `"notion"`) |
+| `title` | `string` | ✅ | Display title |
+| `summary` | `string` | ❌ | Short description or excerpt |
+| `image_url` | `string` | ❌ | Thumbnail or preview image URL |
+| `image_bg_color` | `string` | ❌ | Background color for image placeholder |
+| `visibility` | `'public' \| 'internal'` | ✅ | Access scope |
+| `display_order` | `number` | ✅ | Sort position within its parent list |
+
+## Usage Example
+
+```typescript
+import type { ContentRef } from './content-ref';
+
+const ref: ContentRef = {
+  type: 'video',
+  id: 'abc123',
+  slug: 'q1-investor-update',
+  url: 'https://www.youtube.com/watch?v=abc123',
+  targetPlatform: 'youtube',
+  title: 'Q1 2025 Investor Update',
+  summary: 'Quarterly performance highlights and roadmap preview.',
+  image_url: 'https://img.youtube.com/vi/abc123/hqdefault.jpg',
+  visibility: 'internal',
+  display_order: 1,
+};
+```
+
+> **Note:** This type is shared across client and server. Server-side data utilities (e.g., JSONB serialization, fetch helpers) remain hub-side and should import this interface rather than redeclare it locally.

package/src/components/chat/types/entities/.customer-interview.md

@@ -0,0 +1,28 @@
+<!-- source-hash: d2bea4092c5fb585f7b34695adfbf8c3 -->
+Re-exports Customer Interview entity types from the shared lib (`@/types/customer-interview`) into the chat card consumer barrel.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `CustomerInterview` | Canonical shape for a customer interview record |
+| `CustomerInterviewConfig` | Configuration options for a customer interview |
+| `CustomerInterviewFilters` | Filter parameters for querying interviews |
+| `CustomerInterviewListResponse` | Paginated/list response wrapper for interviews |
+
+## Usage Example
+
+```typescript
+import type {
+  CustomerInterview,
+  CustomerInterviewConfig,
+  CustomerInterviewFilters,
+  CustomerInterviewListResponse,
+} from '@/entities/chat/customer-interview';
+
+const filters: CustomerInterviewFilters = { status: 'completed' };
+
+const response: CustomerInterviewListResponse = await fetchInterviews(filters);
+```
+
+> **Note:** This is a pure re-export barrel — no logic or competing type definitions live here. The canonical source of truth is `src/types/customer-interview.ts`.

package/src/components/chat/types/entities/.data-room-doc.md

@@ -0,0 +1,36 @@
+<!-- source-hash: 24f09ae47345f49fc8da8100c8c8644b -->
+Defines the `DataRoomDocCardItem` wire shape used to render data-room document cards within the chat interface.
+
+## Key Components
+
+### `DataRoomDocCardItem` (interface)
+
+Covers both `data_room_documents` database rows and `openframe-docs` markdown rows. The card differentiates source type via `sourceRepo` and composes click destinations using the shared `resolveSourceRowCTA` helper.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Doc UUID (`external_id` / `id` from `data_room_documents`) |
+| `title` | `string` | Display name |
+| `path` | `string \| null` | Path within the data room (e.g. `legal/fundraising/seed/...`) |
+| `preview` | `string \| null` | Content snippet up to ~200 chars |
+| `url` | `string \| null` | Resolved URL (typically `/data-room/<path>`) |
+| `sourceRepo` | `string \| null` | `RagTableConfig.id` (e.g. `'openframe-docs'`, `'data-room-docs'`) — drives badge label via `SOURCE_LABELS_BY_TABLE` |
+| `baseRoute` | `string` | Chat shell base route (e.g. `/data-room`, `/knowledge-base`) — threaded down to `resolveSourceRowCTA` |
+| `chipBasePlatform` | `string` | Cross-platform target (e.g. `'flamingo'`) — composes an absolute cross-origin URL for new-tab navigation |
+
+## Usage Example
+
+```typescript
+const doc: DataRoomDocCardItem = {
+  id: "a1b2c3d4-...",
+  title: "Vertex VII SAFE Agreement",
+  path: "legal/fundraising/seed/executed/vertex-vii-3.5m-safe",
+  preview: "This Simple Agreement for Future Equity...",
+  url: "/data-room/legal/fundraising/seed/executed/vertex-vii-3.5m-safe",
+  sourceRepo: "data-room-docs",
+  baseRoute: "/data-room",
+  chipBasePlatform: "flamingo",
+};
+```
+
+> **Note:** When `chipBasePlatform` is set, `resolveSourceRowCTA` composes an absolute URL and the card renders a plain `<a>` tag (new tab). Without it, middleware may redirect `/knowledge-base/<path>` to `/` if the route is not in `allowedRoutes`.

package/src/components/chat/types/entities/.github-activity.md

@@ -0,0 +1,43 @@
+<!-- source-hash: 191ada0d5f9c1c69293935f38aeafd78 -->
+Defines TypeScript entity types for GitHub activity data used in chat card rendering across the Flamingo/OpenFrame platform.
+
+## Key Components
+
+- **`GitHubActivityKind`** — Union type discriminating between `'commit'`, `'pull_request'`, and `'pr_review'` activity variants
+- **`PrReviewState`** — Union type for PR review states (`APPROVED`, `CHANGES_REQUESTED`, `COMMENTED`, `DISMISSED`, `PENDING`); drives color/badge rendering in `GitHubActivityCard`
+- **`GitHubActivityItem`** — Core interface representing a single GitHub activity row passed to `GitHubActivityCard`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Commit SHA, PR number, or review ID |
+| `title` | `string` | Commit message, PR title, or review state label |
+| `repo` | `string?` | `"owner/repo"` format, derived from URL if omitted |
+| `dateUpdated` | `string \| number \| null` | ISO timestamp or ms epoch |
+| `url` | `string \| null` | GitHub URL used as link target |
+| `kind` | `GitHubActivityKind?` | Defaults to `'commit'` when not supplied |
+
+## Usage Example
+
+```typescript
+import type { GitHubActivityItem, PrReviewState } from '@/lib/types/github-activity';
+
+const commitActivity: GitHubActivityItem = {
+  id: 'a1b2c3d',
+  title: 'fix: resolve ticket sync edge case',
+  repo: 'flamingo-run/openframe',
+  dateUpdated: '2024-11-01T10:30:00Z',
+  url: 'https://github.com/flamingo-run/openframe/commit/a1b2c3d',
+  kind: 'commit',
+};
+
+const reviewActivity: GitHubActivityItem = {
+  id: 'review-42',
+  title: 'APPROVED',
+  repo: 'flamingo-run/openframe',
+  dateUpdated: Date.now(),
+  url: 'https://github.com/flamingo-run/openframe/pull/42#pullrequestreview',
+  kind: 'pr_review',
+};
+```
+
+This type is intentionally decoupled from `GitHubActivityCard` so clients can construct, pass, or extend activity data without importing UI components.

package/src/components/chat/types/entities/.hubspot-ticket.md

@@ -0,0 +1,53 @@
+<!-- source-hash: 487eacc5608879f64c680c5b15f48203 -->
+Defines the wire-shape contract for HubSpot ticket data surfaced in chat card components, supporting three display variants (FULL, ANON, SELF) with field-level redaction handled server-side before delivery to the client.
+
+## Key Components
+
+### `HubspotTicketItem` Interface
+
+The single export — a typed shape consumed by `hubspot-ticket-card.tsx` across all three rendering variants:
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `string` | Maps to `external_id` on `hubspot_tickets` table |
+| `title` | `string` | Ticket subject/title |
+| `preview` | `string?` | Sanitized body snippet via mapper's `buildPreview` |
+| `status` | `string \| null` | Canonical: `NEW \| IN_PROGRESS \| WAITING \| CLOSED` — drives badge color |
+| `statusLabel` | `string \| null` | Human-readable pipeline stage label; falls back to `status` |
+| `priority` | `string \| null` | `LOW \| MEDIUM \| HIGH \| URGENT` |
+| `customerCompany` | `string \| null` | **FULL variant only** — redacted to `null` for ANON |
+| `customerEmail` | `string \| null` | Submitter address; visible for proxy-auth surfaces |
+| `dateUpdated` | `string \| number \| null` | ISO timestamp or epoch |
+| `url` | `string \| null` | **FULL variant only** — HubSpot UI deep link |
+
+## Variant Redaction Model
+
+```text
+Variant │ customerCompany │ url
+────────┼─────────────────┼──────
+FULL    │ ✅ visible       │ ✅ visible
+ANON    │ ❌ null          │ ❌ null
+SELF    │ ✅ visible       │ ❌ null
+```
+
+Redaction happens in the **indexer**, not the client — the shape is identical across variants.
+
+## Usage Example
+
+```typescript
+import type { HubspotTicketItem } from './hubspot-ticket';
+
+const ticket: HubspotTicketItem = {
+  id: '12345',
+  title: 'VPN access not working',
+  preview: 'Unable to connect since the latest Windows update...',
+  status: 'IN_PROGRESS',
+  statusLabel: 'Code review',
+  priority: 'HIGH',
+  customerEmail: 'user@example.com',
+  dateUpdated: '2024-03-15T10:30:00Z',
+  // FULL variant — url and customerCompany populated by indexer
+  url: 'https://app.hubspot.com/contacts/123/ticket/12345',
+  customerCompany: 'Acme Corp',
+};
+```

package/src/components/chat/types/entities/.index.md

@@ -0,0 +1,42 @@
+<!-- source-hash: c776921bad26d5ec08d70dc63e9ff5b7 -->
+Barrel export file that centralises all **chat entity row types** — the canonical wire shapes consumed by chat cards across the Flamingo/OpenFrame platform.
+
+## Key Components
+
+Re-exports types from the following entity modules:
+
+| Module | Entity |
+|---|---|
+| `blog` | Blog post wire shape |
+| `case-study` | Case study wire shape |
+| `content-ref` | Generic content reference |
+| `customer-interview` | Customer interview wire shape |
+| `data-room-doc` | Data room document wire shape |
+| `github-activity` | Commit / PR / review wire shape |
+| `hubspot-ticket` | HubSpot ticket wire shape |
+| `investor-update` | Investor update wire shape |
+| `onboarding-guide` | Onboarding guide wire shape |
+| `program-types` | Program item wire shapes |
+| `roadmap-item` | Roadmap item wire shape |
+| `slack-message` | Slack message wire shape |
+
+## Usage Example
+
+```typescript
+// Import any chat entity type directly from the barrel
+import type {
+  GithubActivityRow,
+  SlackMessageRow,
+  HubspotTicketRow,
+} from '@lib/chat/entities';
+
+function renderCard(entity: GithubActivityRow | SlackMessageRow) {
+  // consume canonical wire shape — no hub-tree imports needed
+}
+```
+
+## Architecture Notes
+
+- **Types only** — pure wire shapes and formatters that operate on them live here; no DAL functions, RAG mappers, or sync engine logic.
+- **Hub isolation** — server-side utilities that *produce* these shapes remain in the hub; this package is the single source of truth for *consuming* them.
+- **Chat card contract** — any chat card component should import entity types from this barrel rather than reaching into hub internals.

package/src/components/chat/types/entities/.investor-update.md

@@ -0,0 +1,45 @@
+<!-- source-hash: cd90c6466cd8d12a5c8765efbf35dcb1 -->
+Defines the wire-shape types and a pure formatter for investor update entities, used across chat cards and `/api/investor-updates` API reads.
+
+## Key Components
+
+### Interfaces
+
+| Interface | Purpose |
+|---|---|
+| `MetricEntry` | A single financial or KPI metric with current/previous values and visibility scope |
+| `HighlightEntry` | A titled highlight item (milestone, note, etc.) with optional description and visibility |
+| `InvestorUpdateHighlights` | Grouped collections of `HighlightEntry` items by category |
+| `InvestorUpdate` | Full wire shape for an investor update — covers content, media, SEO, HubSpot, authorship, and visibility |
+
+### Functions
+
+- **`formatInvestorUpdatePeriod`** — Pure formatter that converts `period_start` / `period_end` ISO strings into a human-readable range (e.g. `Mar 2025 - May 2025`). Falls back to `?` for missing endpoints.
+
+## Usage Example
+
+```typescript
+import type { InvestorUpdate, MetricEntry } from './investor-update';
+import { formatInvestorUpdatePeriod } from './investor-update';
+
+// Format a period range for display
+const label = formatInvestorUpdatePeriod('2025-03-01', '2025-05-31');
+// → "Mar 2025 - May 2025"
+
+const labelLong = formatInvestorUpdatePeriod('2025-03-01', null, { monthFormat: 'long' });
+// → "March 2025 - ?"
+
+// Type-safe metric entry
+const mrr: MetricEntry = {
+  current: 42000,
+  previous: 38000,
+  change_pct: 10.5,
+  visibility: 'internal',
+};
+```
+
+## Notes
+
+- Visibility fields (`'public' | 'internal'`) control what surfaces in public-facing vs. internal views — filtering logic stays hub-side.
+- `section_visibility` is a freeform record allowing per-section overrides on any `InvestorUpdate`.
+- Server-side data utilities and DB access remain in `lib/data/investor-update-utils-shared.ts`; this file exports types and pure functions only.