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

package/src/components/chat/.nav-link-anchor-via-runtime.md

@@ -0,0 +1,40 @@
+<!-- source-hash: 7bb7ab52d16e8c26a26fa5ab1feba948 -->
+A client-side `<a>` wrapper used within the chat tree to handle link navigation by reading the active `ChatRuntime` and routing clicks through the shared `handleChatNavClick` utility.
+
+## Key Components
+
+### `NavLinkAnchorViaRuntimeProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `href` | `string` | Raw href to resolve |
+| `path` | `string \| null` | Optional internal path hint |
+| `targetPlatform` | `string \| null` | Platform target override |
+| `className` | `string` | Optional CSS class |
+| `children` | `ReactNode` | Optional child content |
+
+### `NavLinkAnchorViaRuntime`
+The main exported component. Orchestrates four responsibilities:
+1. **Resolves `href`** via `resolveHrefForRuntime` (runtime-aware URL normalization)
+2. **Decides new-tab vs. same-tab** via `computeIsNewTab` (embed-mode short-circuit → `runtime.navigation.decideNewTab` → lib fallback)
+3. **Sets `target`/`rel`** attributes via `newTabAnchorAttrs`
+4. **Closes the chat panel** on same-tab navigation via `ChatPanelContext.closeChat`
+
+> **⚠️ Chat-tree only:** Uses `useRequiredChatRuntime`, which **throws** when mounted outside a `<ChatRuntimeContext.Provider>`. This is intentional — no silent fallback. For surfaces outside the chat tree (header chrome, marketing pages), use the hub's `useNavLink`-based anchor instead.
+
+## Usage Example
+
+```typescript
+// Used in markdown-rendered chat bodies or source-chip drill-ins
+<NavLinkAnchorViaRuntime
+  href="https://example.com/docs/setup"
+  path="/docs/setup"
+  targetPlatform="web"
+  className="chat-link"
+>
+  View Setup Guide
+</NavLinkAnchorViaRuntime>
+```
+
+At runtime:
+- **Same-tab click** → navigates and calls `panel.closeChat()` to dismiss the chat panel
+- **New-tab click** → opens in a new tab, leaving the chat panel open

package/src/components/chat/.remark-card-links.md

@@ -0,0 +1,38 @@
+<!-- source-hash: dab5bf3f8a2e52f871c282c3d6212649 -->
+A remark plugin for the unified/react-markdown pipeline that transforms `[card://<type>:<id>]` markers in markdown text nodes into synthetic `link` mdast nodes with a `card://` URL scheme, enabling downstream component overrides to render entity cards.
+
+## Key Components
+
+- **`CARD_REGEX`** — Global regex matching `[card://type:id]` patterns, intentionally tolerating both `]` and `)` as closing characters to handle LLM bracket-balancing drift on opaque token IDs (e.g. UUIDs)
+- **`remarkCardLinks`** — Unified `Plugin<[], Root>` factory; visits all `text` leaves in the mdast tree and splits them into interleaved `Text` and `Link` nodes where card markers are found
+- **`card://` URL scheme** — Non-standard scheme placed on the synthetic link's `url` so the `<a>` component override in `chat-message-enhanced.tsx` can detect and delegate rendering to `renderEntityCard`
+
+## Usage Example
+
+```typescript
+import ReactMarkdown from "react-markdown"
+import { remarkCardLinks } from "./remark-card-links"
+
+// The plugin is registered in the remark pipeline:
+<ReactMarkdown
+  remarkPlugins={[remarkCardLinks]}
+  components={{
+    a({ href, children }) {
+      if (href?.startsWith("card://")) {
+        const [, cardType, cardId] = href.split(/[:/]+/)
+        return renderEntityCard(cardType, cardId)
+      }
+      return <a href={href}>{children}</a>
+    },
+  }}
+>
+  {`**The [card://webinar:42] discussed pricing**`}
+</ReactMarkdown>
+// bold wrapper is preserved; only the text leaf is split
+```
+
+## Notes
+
+- Operates on text leaves only — bold, italic, list, and code wrappers around markers are preserved untouched
+- Resets `CARD_REGEX.lastIndex` per invocation to avoid stale state from the `g` flag
+- Returns `[SKIP, index + parts.length]` after splicing to prevent the visitor from re-entering the newly inserted nodes

package/src/components/chat/.slash-command-suggestions.md

@@ -0,0 +1,47 @@
+<!-- source-hash: b3b4c24e822f3ccb1b39897c02cee900 -->
+Renders an accessible autocomplete dropdown for slash commands, mapping each command to a `MingoOnboardingCard` row with unified icon resolution, keyboard/mouse highlight sync, and optional inline action buttons.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `SlashCommandSuggestions` | `React.FC` | Main dropdown component; returns `null` when `commands` is empty |
+| `SlashCommandSuggestionsProps` | `interface` | Props contract covering command list, highlight state, and action callbacks |
+
+**Icon resolution priority (highest → lowest):**
+1. `cmd.iconName` → `resolveOnboardingIcon` (v2 registry)
+2. `cmd.primarySourceId` → consumer `resolveSourceIcon` (legacy fallback)
+3. `FileIcon` (default inside `resolveOnboardingIcon`)
+
+## Usage Example
+
+```typescript
+import { SlashCommandSuggestions } from './slash-command-suggestions'
+import type { SlashCommandSummary } from './types'
+
+function ChatInput() {
+  const [commands, setCommands] = useState<SlashCommandSummary[]>([])
+  const [highlightedIdx, setHighlightedIdx] = useState(0)
+
+  return (
+    <div className="relative">
+      <SlashCommandSuggestions
+        commands={commands}
+        highlightedIdx={highlightedIdx}
+        onHover={(idx) => setHighlightedIdx(idx)}
+        onSelect={(cmd) => setValue(`/${cmd.id} `)}
+        onAction={(cmd, actionId) => dispatch({ cmd, actionId })}
+        className="absolute bottom-full"
+      />
+      <input ... />
+    </div>
+  )
+}
+```
+
+## Accessibility Notes
+
+- Outer container: `role="menu"` with `aria-label`
+- Each row: `role="menuitem"` + `aria-current` on the highlighted item
+- `Enter`/`Space` activate the focused row; arrow-key navigation is delegated to the parent input
+- Action buttons call `stopPropagation` to prevent double-firing the row's `onSelect`

package/src/components/chat/.source-action-button.md

@@ -0,0 +1,48 @@
+<!-- source-hash: 770809a15a2a56eec700f22e576bdc99 -->
+Unified "Ask / Display" action button rendered across source chips, inline cards, and search-result list rows. Replaces three divergent ad-hoc implementations with a single `Button`-backed primitive that keeps DOM shape, accessibility attributes, and hover behavior in one place.
+
+## Key Components
+
+### `SourceActionButton`
+The sole export. Returns `null` when either `chatRef` or `onDiscuss` is absent, making the guard declarative at the call site.
+
+### `SourceActionDensity`
+Union type `'inline' | 'card' | 'list-row'` that selects the visual variant via the `DENSITY_STYLES` map.
+
+### `DENSITY_STYLES`
+Internal record keyed by `SourceActionDensity`. Each entry carries `size`, `showLabel`, `iconSize`, and `className`. Adding a fourth surface requires one new entry here — no changes to the render path.
+
+### Icon selection
+Label-driven: `'Display'` renders `FileText` (verbatim-content semantics); any other label renders `MessageSquare` (conversational semantics).
+
+## Usage Example
+
+```typescript
+// Inline chip — icon only, small footprint
+<SourceActionButton
+  chatRef={{ id: 'row-42', title: 'Ticket #42' }}
+  onDiscuss={(ref) => openChat(ref)}
+  density="inline"
+/>
+
+// Card — shows "Ask" label beside icon
+<SourceActionButton
+  chatRef={row}
+  onDiscuss={handleDiscuss}
+  density="card"
+/>
+
+// List row with custom label
+<SourceActionButton
+  chatRef={row}
+  onDiscuss={handleDiscuss}
+  density="list-row"
+  label="Display"
+/>
+
+// Hidden — chatRef is null, renders nothing
+<SourceActionButton
+  chatRef={null}
+  onDiscuss={handleDiscuss}
+/>
+```

package/src/components/chat/.thinking-display.md

@@ -0,0 +1,42 @@
+<!-- source-hash: 85a298f4c8461aee81841a6a960437a6 -->
+Collapsible UI component that displays AI "thinking" or reasoning text with a muted markdown aesthetic, supporting both streaming and completed states.
+
+## Key Components
+
+- **`ThinkingDisplay`** — `forwardRef` component rendering AI thought content inside a bordered card with expand/collapse behavior
+- **`thoughtMdClasses`** — Tailwind override class string that tunes `SimpleMarkdownRenderer` output to a quieter secondary-tone aesthetic (muted text, tighter spacing, flat code chips)
+- **`useCollapsible`** — Hook managing overflow detection, container height animation, and collapsed/expanded state
+- **`ExpandChevron`** — Chevron indicator shown only when content overflows or is already expanded
+- **`SimpleMarkdownRenderer`** — Underlying markdown renderer wrapped with thought-specific style overrides
+
+## Props (`ThinkingDisplayProps`)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `text` | `string` | — | Markdown content to render |
+| `isStreaming` | `boolean` | `false` | Shows animated dots loader and "Thinking" label when `true` |
+| `className` | `string` | — | Additional classes for the outer card |
+
+## Usage Example
+
+```typescript
+import { ThinkingDisplay } from "./thinking-display"
+
+// Streaming state (model is still generating)
+<ThinkingDisplay
+  text="Analyzing the user's request..."
+  isStreaming={true}
+/>
+
+// Completed thought (collapsible if content overflows)
+<ThinkingDisplay
+  text="## Approach\nI need to check the ticket status first, then query the CMDB for affected assets."
+  isStreaming={false}
+/>
+```
+
+## Behavior Notes
+
+- Label switches between `"Thinking"` (streaming) and `"Thought"` (complete)
+- Collapsed height is `19px` (~one line of `text-sm leading-snug`); transitions are disabled while streaming to avoid layout thrashing
+- Toggle is keyboard-accessible (`Enter`/`Space`) with proper `aria-expanded`; `tabIndex` is `-1` when content fits in one line

package/src/components/chat/.tool-call-blocks.md

@@ -0,0 +1,45 @@
+<!-- source-hash: c2806ae4c954c7e6f9d20b3fe6ddb5f6 -->
+Reusable React components for rendering tool call arguments and results in the Flamingo/OpenFrame AI chat interface, handling both inline and block display formats.
+
+## Key Components
+
+### `ArgRow`
+Renders a single tool argument as either an inline `key: value` pair (for short values) or a labeled scrollable `<pre>` block (for long JSON, scripts, or multiline content). Shared across `ApprovalBatchMessage` and `ToolExecutionDisplay` for consistent rendering.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `argKey` | `string` | The argument name/key |
+| `value` | `unknown` | The argument value (any type) |
+
+### `ResultBlock`
+Renders a tool execution result as either inline text or a scrollable code block, depending on length and content type. Returns `null` when result is empty.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `result` | `string \| undefined \| null` | The tool execution output |
+| `className` | `string?` | Optional additional CSS classes |
+
+## Usage Example
+
+```typescript
+import { ArgRow, ResultBlock } from "./tool-call-blocks"
+
+// Rendering tool arguments
+<ArgRow argKey="script" value={`console.log("hello")`} />
+<ArgRow argKey="timeout" value={30} />
+
+// Rendering tool result
+<ResultBlock result={toolOutput} className="mt-2" />
+```
+
+## Display Logic
+
+Both components delegate format decisions to `formatToolArgValue` and `formatToolResult` helpers, which return a `kind` of `"inline"` or `"block"`:
+
+```mermaid
+graph TD
+    A["Raw Value/Result"] --> B["Format Helper"]
+    B --> C{"kind?"}
+    C -->|inline| D["Inline span"]
+    C -->|block| E["Scrollable pre/code"]
+```

package/src/components/chat/.tool-execution-display.md

@@ -1,45 +1,53 @@
-<!-- source-hash: 1e0dcb1d3ca121148412ec84dd43fee6 -->
-A React component that displays the execution status and details of integrated tools, with collapsible sections showing parameters and results.
+<!-- source-hash: 51e80592b1ae4e56c89af6c06ba53a04 -->
+Renders a collapsible card UI for displaying AI tool call execution state — including tool arguments, execution status (running/success/failure), and result output.
 
 ## Key Components
 
-- **ToolExecutionDisplay** - Main forwardRef component that renders tool execution information
-- **handleToggle** - Function to manage expand/collapse state (controlled or uncontrolled)
-- **formatToolName** - Utility to format tool type names by replacing underscores with spaces
-- **formatParameters** - Utility to format parameter objects for display, with truncation for long strings
+| Export | Type | Description |
+|--------|------|-------------|
+| `ToolExecutionDisplay` | `forwardRef<HTMLDivElement>` | Main component displaying tool call lifecycle in a collapsible card |
+
+### Internal Helpers
+
+- **`renderStatusIcon`** — Returns `DotsLoaderIcon` (executing), `CheckCircleIcon` (success), or `XmarkCircleIcon` (failure) based on message state
+- **`argEntries`** — Filters `message.parameters` to exclude `COMMAND_BODY_KEYS`, nulls, undefined, and empty strings
+- **`previewText`** — Memoized title derived from `getToolCallTitle` using tool args, title, and function name
+- **`useCollapsible`** — Hook providing animated expand/collapse container styles
+- **`hasBody`** — Guards rendering of the collapsible body section
+
+### Props (`ToolExecutionDisplayProps`)
+
+| Prop | Description |
+|------|-------------|
+| `message` | Tool execution message with `type`, `parameters`, `result`, `success`, `toolTitle`, `toolFunction`, `integratedToolType` |
+| `className` | Optional CSS class override |
 
 ## Usage Example
 
 ```typescript
-import { ToolExecutionDisplay } from './tool-execution-display'
-
-// Executing tool message
-const executingMessage = {
-  type: "EXECUTING_TOOL",
-  integratedToolType: "OPENFRAME_API",
-  toolFunction: "createUser",
-  parameters: { name: "John", email: "john@example.com" }
-}
-
-// Executed tool message
-const executedMessage = {
-  type: "EXECUTED_TOOL", 
-  integratedToolType: "OPENFRAME_API",
-  toolFunction: "createUser",
-  parameters: { name: "John", email: "john@example.com" },
-  result: "User created successfully",
-  success: true
-}
-
-// Usage with controlled expansion
-<ToolExecutionDisplay 
-  message={executingMessage}
-  isExpanded={false}
-  onToggleExpand={() => setExpanded(!expanded)}
+import { ToolExecutionDisplay } from "./tool-execution-display"
+
+// Executing state
+<ToolExecutionDisplay
+  message={{
+    type: "EXECUTING_TOOL",
+    toolTitle: "Query Database",
+    toolFunction: "run_query",
+    parameters: { query: "SELECT * FROM tickets LIMIT 10" },
+    integratedToolType: "OPENFRAME",
+  }}
 />
 
-// Usage with uncontrolled expansion
-<ToolExecutionDisplay message={executedMessage} />
-```
-
-The component displays different visual states (loading spinner, success/error icons) based on execution status, shows parameters during execution, and displays results after completion with appropriate success/error styling.
+// Completed with result
+<ToolExecutionDisplay
+  message={{
+    type: "EXECUTED_TOOL",
+    toolTitle: "Query Database",
+    toolFunction: "run_query",
+    parameters: { query: "SELECT * FROM tickets LIMIT 10" },
+    result: "Returned 10 rows",
+    success: true,
+    integratedToolType: "OPENFRAME",
+  }}
+/>
+```

package/src/components/chat/chat-container.tsx

@@ -65,7 +65,7 @@ const ChatHeader = React.forwardRef<HTMLDivElement, ChatHeaderProps>(
   ({ className, userName = 'Grace "Fae" Meadows', userTitle = "Your Personal Assistant", userAvatar, userIcon, onSettingsClick, onNewChat, onClose, onBack, showNewChat = false, connectionStatus = 'disconnected', serverUrl = null, headerActions, ticketInfo, fullWidth = false, bare = false, ...props }, ref) => {
     const cardClasses = bare
       ? ""
-      : "rounded-md bg-ods-card shadow-[0_18px_48px_rgba(0,0,0,0.45)] border border-ods-border ring-1 ring-black/20"
+      : "rounded-md bg-ods-card border border-ods-border"
     return (
       <div
         ref={ref}

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

@@ -0,0 +1,43 @@
+<!-- source-hash: 5014a5d76cff7f765951023b41048390 -->
+Reusable admin content card component that renders a cover image with edge-color fill, title, subtitle, summary, platform badges, meta info, and action buttons in a consistent card layout.
+
+## Key Components
+
+### `AdminContentCard`
+Main exported component. Renders an `<article>` card with a 3:2 aspect-ratio cover image and a flexible content body.
+
+### `AdminContentCardProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `imageUrl` | `string \| null` | Primary cover image URL |
+| `placeholderUrl` | `string \| null` | Fallback image URL when `imageUrl` is missing or errors |
+| `title` | `string` | Required heading and image alt text |
+| `summary` | `string \| null` | Two-line clamped description |
+| `subtitle` | `string \| null` | Secondary line (e.g. customer name) |
+| `platforms` | `PlatformInfo[]` | Renders `<PlatformBadge>` chips |
+| `badges` | `ReactNode` | Additional status badges after platform chips |
+| `meta` | `ReactNode` | Date, views, or other metadata row |
+| `actions` | `ReactNode` | Pinned-to-bottom action buttons |
+| `className` | `string` | Extra Tailwind classes |
+
+### Internal Hooks
+- **`useImageEdgeColor`** — samples the edge color of `displayUrl` to use as the image container background, blending the cover image seamlessly.
+- **`useState / useEffect`** — tracks `imageError` and `imageLoaded` states; resets load state on URL change to replay the fade-in.
+
+## Usage Example
+
+```typescript
+import { AdminContentCard } from './admin-content-card'
+
+<AdminContentCard
+  imageUrl="https://cdn.example.com/cover.png"
+  placeholderUrl="https://cdn.example.com/og-placeholder.png"
+  title="Quarterly Security Report"
+  subtitle="Acme Corp"
+  summary="Overview of vulnerabilities patched in Q2 2025."
+  platforms={[{ id: 'azure', name: 'Azure', display_name: 'Microsoft Azure' }]}
+  badges={<span className="badge">Published</span>}
+  meta={<span>June 12, 2025 · 142 views</span>}
+  actions={<button>Edit</button>}
+/>
+```

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

@@ -0,0 +1,47 @@
+<!-- source-hash: c4f460ddb603f582424bec5b5d1e9d76 -->
+Sentinel component used by `renderEntityCard` to signal that a card's content is block-level HTML (e.g. `<div>`, `<EntityVideoSection>`) and cannot legally render inside a markdown `<p>` tag.
+
+## Key Components
+
+### `BlockCard`
+A no-op sentinel function component — it always returns `null`. Its purpose is **not** to render, but to be detected by type identity during the pre-scan in `chat-message-enhanced.tsx`, which splits its props into two placement zones.
+
+### `BlockCardProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `inline` | `React.ReactNode` (optional) | Compact UI placed **at** the marker position inside the `<p>` (e.g. a 56×56 thumbnail card). Falls back to a plain `<span>` with the ref title if omitted. |
+| `children` | `React.ReactNode` | Block-level content appended as a **sibling below** the paragraph, where it is HTML-valid. |
+
+## How the Pre-Scan Works
+
+```mermaid
+graph TD
+    A["chat-message-enhanced.tsx"] --> B["Scan text segment for [card://type:id] markers"]
+    B --> C["Call renderEntityCard(ref)"]
+    C --> D{"Result is BlockCard?"}
+    D -->|Yes| E["Place inline prop AT marker inside paragraph"]
+    D -->|Yes| F["Append children as sibling BELOW paragraph"]
+    D -->|No| G["Render inline as-is inside paragraph"]
+```
+
+## Usage Example
+
+```typescript
+// Inside renderEntityCard — return a BlockCard when the card
+// contains block-level elements that can't nest in <p>
+import { BlockCard } from './block-card'
+
+function renderEntityCard(ref: EntityRef) {
+  if (ref.type === 'video') {
+    return (
+      <BlockCard
+        inline={<CompactVideoThumbnail ref={ref} />}  // placed inside <p>
+      >
+        <EntityVideoSection ref={ref} />              // hoisted below <p>
+      </BlockCard>
+    )
+  }
+}
+```
+
+> **Note:** `BlockCard` is a protocol tag, not a UI wrapper. Never render it directly outside of the `chat-message-enhanced` pipeline — if one escapes that path, the defensive `return null` prevents a crash.

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

@@ -0,0 +1,52 @@
+<!-- source-hash: 84fe8c9e8dffcbf0ae0ec8ff163a67e2 -->
+Pure presentation component for rendering blog post cards in two density modes (`default` and `sm`), with no built-in click/navigation logic — callers supply the resolved `href` and wrap with their own anchor strategy.
+
+## Key Components
+
+### `BlogCard`
+Main card component supporting two layouts:
+- **`default`**: Full vertical card with cover image, title, summary, author avatar, date, and view count
+- **`sm`**: Compact horizontal card (~80px tall) designed for chat-inline rendering, showing a thumbnail, title, category, and summary
+
+### `BlogCardSkeleton`
+Loading placeholder matching both `default` and `sm` density layouts using animated pulse styles.
+
+### `BlogCardProps`
+| Prop | Type | Description |
+|---|---|---|
+| `post` | `BlogPostSummary` | Post data (title, image, author, etc.) |
+| `href` | `string` | Resolved detail URL from caller |
+| `target` | `'_blank'` | Opens in new tab (set by chat dispatch) |
+| `placeholderUrl` | `string \| null` | Fallback image when `featured_image` is missing |
+| `size` | `'default' \| 'sm'` | Card density mode |
+| `hasEmbeddedVideo` | `boolean` | Surfaces a "Video" badge in compact mode |
+| `priority` | `boolean` | Passes LCP priority hint to the cover image |
+
+**Image fallback chain:** `post.featured_image` → `placeholderUrl` → `bg-ods-bg` background slot
+
+## Usage Example
+
+```typescript
+// Default full card — caller wraps with navigation anchor
+<BlogCard
+  post={blogPostSummary}
+  href={buildContentURL(post.slug)}
+  placeholderUrl={useOgPlaceholder(post)}
+  size="default"
+  priority={true}
+/>
+
+// Compact card for chat-inline rendering
+<BlogCard
+  post={blogPostSummary}
+  href={detailUrl}
+  target="_blank"
+  rel="noopener noreferrer"
+  size="sm"
+  hasEmbeddedVideo={true}
+  placeholderUrl={staticFallbackUrl}
+/>
+
+// Skeleton while loading
+<BlogCardSkeleton size="sm" />
+```

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

@@ -0,0 +1,39 @@
+<!-- source-hash: d68b2db5f05c474ec9bdb96a22e60341 -->
+Thin presentation component that renders a blog post cover image (or OG-generated placeholder) with graceful 404 recovery.
+
+## Key Components
+
+### `BlogImagePlaceholder`
+A client-side React component that wraps a cover image in an HTML phrasing-content–safe `<span>`. Key behaviors:
+
+- Returns `null` when `imageUrl` is `null`, rendering nothing
+- Uses a plain `<img>` tag (bypasses `next/image`) to support query-string–based dynamic placeholder URLs
+- Hides the broken-image icon via `onError` when the URL 404s, letting the parent `bg-ods-bg` background show through cleanly
+- Wrapped in `<span className="block">` instead of `<div>` for HTML validity when rendered inside markdown `<p>` tags (e.g., compact `BlogCard` in the chat shell)
+
+### `BlogImagePlaceholderProps`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `imageUrl` | `string \| null` | Pre-resolved cover/OG image URL; `null` renders nothing |
+| `title` | `string` | Used for the `alt` attribute |
+| `className` | `string` | Optional extra Tailwind classes |
+
+## Usage Example
+
+```typescript
+import { BlogImagePlaceholder } from './blog-image-placeholder'
+
+// Typical usage in a BlogCard with a pre-resolved OG placeholder URL
+<BlogImagePlaceholder
+  imageUrl="https://og.flamingo.run/placeholder?title=My+Post&category=devops"
+  title="My Post"
+  className="rounded-lg"
+/>
+
+// When imageUrl is null, renders nothing — safe to use unconditionally
+<BlogImagePlaceholder
+  imageUrl={null}
+  title="Draft Post"
+/>
+```

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"
+/>
+```