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

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.

package/src/components/chat/types/entities/.onboarding-guide.md

@@ -0,0 +1,50 @@
+<!-- source-hash: 5421df27f5f23a658e7a9769d35c1b32 -->
+Brief description of the file's purpose in 1-2 sentences.
+
+Defines the shared TypeScript wire types for the onboarding guide feature, covering the full row shape returned by `/api/onboarding-guides` and the chat onboarding-guide card. These types are intentionally client-safe — DAL mutations stay hub-side.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `OnboardingGuide` | `interface` | Full row shape: identity, ordering, body content, video pipeline, images, SEO, workflow, and audit fields |
+| `OnboardingGuideFilters` | `interface` | Query parameters for list endpoints (`status`, `search`, `section`, `platform`, pagination, `ids`) |
+| `OnboardingGuideListResponse` | `interface` | Paginated list response wrapping `OnboardingGuide[]` with a total `count` |
+| `OnboardingGuideSectionSummary` | `interface` | Lightweight section rollup: name, ordering, and guide count |
+
+## Usage Example
+
+```typescript
+import type {
+  OnboardingGuide,
+  OnboardingGuideFilters,
+  OnboardingGuideListResponse,
+} from './onboarding-guide';
+
+// Fetch guides for a specific platform section
+async function fetchGuides(
+  filters: OnboardingGuideFilters
+): Promise<OnboardingGuideListResponse> {
+  const params = new URLSearchParams({
+    ...(filters.status && { status: filters.status }),
+    ...(filters.platform && { platform: filters.platform }),
+    ...(filters.section && { section: filters.section }),
+    limit: String(filters.limit ?? 20),
+    offset: String(filters.offset ?? 0),
+  });
+
+  const res = await fetch(`/api/onboarding-guides?${params}`);
+  return res.json() as Promise<OnboardingGuideListResponse>;
+}
+
+// Resolve video source (Mux/MP4 preferred, YouTube as fallback)
+function resolveVideoUrl(guide: OnboardingGuide): string | null {
+  return guide.main_video_url ?? guide.youtube_url ?? null;
+}
+```
+
+## Notes
+
+- **Video pipeline**: `main_video_url` (Mux/MP4) and `youtube_url` are independent columns — consumers should use whichever is populated, matching the `<VideoSourceSelector>` admin toggle.
+- **Multi-platform**: `onboarding_guide_platforms` is a junction array; a single guide can be featured across multiple platforms with independent `featured_order` values.
+- **Ordering**: Use `section_order` + `step_order` together for deterministic sort within a section.

package/src/components/chat/types/entities/.program-types.md

@@ -0,0 +1,57 @@
+<!-- source-hash: a31da27a1da7444bbcbd4a8716703941 -->
+Defines the Unified Program System's TypeScript type hierarchy, providing base interfaces, database row types, program-specific extensions, configuration objects, and pure transform utilities for events, podcasts, and webinars across a single set of generic components.
+
+## Key Components
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `ProgramHost` | Interface | Host/speaker info (name, avatar, role, etc.) |
+| `LumaEventRow` / `PodcastEpisodeRow` / `WebinarRow` | Interfaces | Raw DB row shapes for each program source table |
+| `BaseProgramItem` | Interface | Shared contract all program items must satisfy |
+| `EventItem` / `PodcastItem` / `WebinarItem` | Interfaces | Extended shapes with program-specific fields |
+| `ProgramType` | Type | `'event' \| 'podcast' \| 'webinar'` discriminant |
+| `ProgramConfig<T>` | Interface | Configuration object that drives generic component behavior (labels, routing, icons, sort order) |
+| `ProgramLabels` | Interface | Display strings (singular, plural, archive, empty, etc.) |
+| `ProgramListResponse<T>` / `ProgramItemResponse<T>` | Interfaces | Generic API response wrappers |
+| `ProgramFilter` / `AdminProgramFilter` | Interfaces | Query/filter option shapes |
+| `transformEventToProgram` | Function | Maps `LumaEventRow` → `EventItem` |
+| `transformPodcastToProgram` | Function | Maps `PodcastEpisodeRow` → `PodcastItem` |
+| `transformWebinarToProgram` | Function | Maps `WebinarRow` → `WebinarItem` |
+
+## Usage Example
+
+```typescript
+import type {
+  ProgramConfig,
+  EventItem,
+  ProgramLabels,
+} from './program-types';
+import { transformEventToProgram } from './program-types';
+import { CalendarDays } from 'lucide-react';
+
+// Define a typed config for events
+const eventConfig: ProgramConfig<EventItem> = {
+  type: 'event',
+  table: 'luma_events',
+  apiEndpoint: '/api/events',
+  dateField: 'start_at',
+  detailRoute: '/events',
+  externalLinkLabel: 'View on Luma',
+  icon: <CalendarDays />,
+  sortOrder: 'asc',
+  labels: {
+    singular: 'Event',
+    plural: 'Events',
+    upcoming: 'Next Event',
+    upcomingSection: 'Upcoming Events',
+    archive: 'Past Events',
+    empty: 'No events yet',
+  },
+};
+
+// Transform a raw DB row into a typed EventItem
+const row = await db.from('luma_events').select('*').single();
+const eventItem: EventItem = transformEventToProgram(row);
+```
+
+> `BaseProgramItem` is the generic constraint used throughout — any new program type only needs to extend it and supply a matching `ProgramConfig` to plug into all shared components automatically.

package/src/components/chat/types/entities/.roadmap-item.md

@@ -0,0 +1,58 @@
+<!-- source-hash: ad455db496eef8ee2c54f68792ebfef2 -->
+Defines the canonical wire-shape interfaces for roadmap items consumed by the chat roadmap card and the public `/api/roadmap` endpoint.
+
+## Key Components
+
+### `RoadmapItem`
+Strongly-typed entity mirroring the `roadmap_items` projection produced by `transformTask()` in `clickup-sync-utils.ts`. Represents a single ClickUp task surfaced as a public roadmap entry.
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | Unique identifier |
+| `status` / `statusColor` | `string` | Display status and its hex/named color |
+| `icon` | `string \| null` | Optional icon URL |
+| `figmaUrl` | `string \| null` | Linked Figma design |
+| `screenshots` | `string[]` | Attached screenshot URLs |
+| `targetVersion` | `string \| null` | Planned release version |
+| `upvotes` / `downvotes` | `number` | Community voting counts |
+| `quarter` | `string` | Planning quarter label |
+| `clickupUrl` | `string` | Canonical ClickUp task URL |
+| `customItemId` | `number \| null` | ClickUp task-type taxonomy ID (e.g. `1008`=Bug, `1009`=Request, `1010`=Feature) — drives type icons via `getTaskTypeIcon` |
+
+### `RoadmapStaleness`
+Tracks cache freshness for roadmap data synced from ClickUp.
+
+| Field | Type | Description |
+|---|---|---|
+| `lastSyncedAt` | `string \| null` | ISO timestamp of last successful sync |
+| `staleSinceMs` | `number` | Milliseconds elapsed since last sync |
+
+## Usage Example
+
+```typescript
+import type { RoadmapItem, RoadmapStaleness } from '@/components/chat/types/entities/roadmap-item';
+
+const item: RoadmapItem = {
+  id: 'task_abc123',
+  title: 'Dark mode support',
+  description: 'Add system-level dark mode across all views',
+  status: 'In Progress',
+  statusColor: '#f5a623',
+  icon: null,
+  figmaUrl: 'https://figma.com/file/...',
+  screenshots: [],
+  targetVersion: 'v2.4.0',
+  upvotes: 42,
+  downvotes: 3,
+  quarter: 'Q3 2025',
+  clickupUrl: 'https://app.clickup.com/t/abc123',
+  customItemId: 1010, // Feature
+};
+
+const staleness: RoadmapStaleness = {
+  lastSyncedAt: '2025-07-01T12:00:00Z',
+  staleSinceMs: 3600000, // 1 hour
+};
+```
+
+> **Import note:** Always import from `@/components/chat/types/entities/roadmap-item` for the strongly-typed shape. The legacy `RoadmapItem` stub in `product-release/release-detail-page.tsx` is untyped (`{ id: string; [key: string]: unknown }`) and will be reconciled in a follow-up.

package/src/components/chat/types/entities/.slack-message.md

@@ -0,0 +1,35 @@
+<!-- source-hash: 5dd665815decf79ecf870dd4eb652947 -->
+Defines the minimal wire shape for Slack message data as displayed in the chat RAG result card, representing a post-retrieval projection stripped of community-feature fields like reactions and threading.
+
+## Key Components
+
+### `SlackMessageItem` interface
+
+A lean projection of a `slack_messages` RAG table row containing only the fields required to render the `slack-message-card` UI component.
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | Slack message ID (`ts` or URL-derived) |
+| `title` | `string` | Display title — typically `"author · channel"` |
+| `preview` | `string?` | PII-sanitized message body preview |
+| `channel` | `string?` | Channel name parsed from URL or stored row |
+| `dateUpdated` | `string \| number \| null?` | ISO timestamp or millisecond epoch |
+| `url` | `string \| null?` | Full Slack permalink (`https://*.slack.com/archives/...`) |
+
+## Usage Example
+
+```typescript
+import { SlackMessageItem } from '@/types/slack-message';
+
+// Mapping a RAG table row to the card's wire shape
+const item: SlackMessageItem = {
+  id: '1712345678.000100',
+  title: 'jane.doe · #support',
+  preview: 'Has anyone seen the ticket for the VPN issue?',
+  channel: 'support',
+  dateUpdated: '2024-04-05T14:22:00.000Z',
+  url: 'https://acme.slack.com/archives/C01AB2CD3EF/p1712345678000100',
+};
+```
+
+> **Naming note:** This interface is intentionally distinct from the broader `SlackMessage` type in `src/types/slack.ts`, which covers the full Slack Community feature shape including reactions, threading, and user objects.

package/src/components/chat/utils/.agent-status-message.md

@@ -0,0 +1,45 @@
+<!-- source-hash: 75abfd053b43306b990d3311c7dd4813 -->
+Resolves a status string to an abstract color scheme name for use in `StatusBadge` components across job, ClickUp task, and log-level status surfaces.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `ColorScheme` | `type` | Union type: `'success' \| 'error' \| 'warning' \| 'cyan' \| 'default'` |
+| `getStatusColorScheme` | `function` | Maps a status string to a `ColorScheme` value |
+
+### Resolution Strategy
+
+`getStatusColorScheme` applies a two-pass lookup:
+
+1. **Exact match** — case-sensitive switch on common statuses
+2. **Partial match** — lowercase substring checks for ClickUp-style freeform statuses (e.g. `"In Progress"`, `"Complete"`)
+
+| ColorScheme | Matched statuses |
+|-------------|-----------------|
+| `success` | `completed`, `success`, `active`, `*complete*`, `*done*` |
+| `error` | `failed`, `failure`, `cancelled`, `error`, `*blocked*`, `*failed*` |
+| `cyan` | `running`, `processing`, `closed`, `*review*` |
+| `warning` | `pending`, `warning`, `*working*`, `*progress*` |
+| `default` | `draft`, `info`, or any unmatched value |
+
+## Usage Example
+
+```typescript
+import { getStatusColorScheme } from './agent-status-message'
+
+// Exact match
+getStatusColorScheme('completed')   // → 'success'
+getStatusColorScheme('failed')      // → 'error'
+getStatusColorScheme('running')     // → 'cyan'
+
+// Partial match (ClickUp-style)
+getStatusColorScheme('In Progress') // → 'warning'
+getStatusColorScheme('Done')        // → 'success'
+getStatusColorScheme('Code Review') // → 'cyan'
+
+// Consumed by StatusBadge
+<StatusBadge colorScheme={getStatusColorScheme(task.status)} label={task.status} />
+```
+
+> **Note:** This is the lib-side subset of the hub's `agent-status-message.ts`. CSS class resolvers and the `AgentStatusMessage` SSE builder live hub-side, as they reference hub-only ODS class names.

package/src/components/chat/utils/.auto-continuation-directive.md

@@ -0,0 +1,58 @@
+<!-- source-hash: 202df1de78269679793058f2735da78c -->
+Brief description of the file's purpose and what it does.
+
+Defines the shared cross-process contract for the post-approval auto-continuation directive, providing a single source of truth for both server-side routing and client-side message construction.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `AUTO_CONTINUATION_DIRECTIVE_PREFIX` | `const string` | Sentinel prefix used by both `decideRoute` (server) and `autoContinueRef` (client) to identify hidden directive messages |
+| `BuildAutoContinuationOptions` | `interface` | Options bag for `ticketId` and `status` to branch directive logic |
+| `buildAutoContinuationDirective` | `function` | Builds the hidden synthetic user message injected after every successful tool approval |
+
+## Directive Branches
+
+```mermaid
+graph TD
+    A["buildAutoContinuationDirective(toolName, opts)"] --> B{"toolName?"}
+    B -->|"create_ticket"| C["§1a — Ask 2-4 diagnostic\nfollow-up questions"]
+    B -->|"update_ticket + CLOSED"| D["§1b — Ask ONE closing\nresolution question"]
+    B -->|"update_ticket (other)"| E["Acknowledge change,\nask if anything else needed"]
+    C --> F["Prefix + prose only\nNo tool call this turn"]
+    D --> F
+    E --> F
+```
+
+## Usage Example
+
+```typescript
+import {
+  AUTO_CONTINUATION_DIRECTIVE_PREFIX,
+  buildAutoContinuationDirective,
+} from './auto-continuation-directive'
+
+// After a create_ticket approval — injects diagnostic follow-up Qs
+const directive = buildAutoContinuationDirective('create_ticket', {
+  ticketId: '4821',
+})
+// → "[internal-auto-continuation] The user just approved create_ticket (ticket #4821). ..."
+
+// After closing a ticket
+const closeDirective = buildAutoContinuationDirective('update_ticket', {
+  ticketId: '4821',
+  status: 'CLOSED',
+})
+// → "[internal-auto-continuation] The user just approved closing ticket #4821. ..."
+
+// Server-side route guard — tools disabled for directive turns
+if (rawUserQuery.startsWith(AUTO_CONTINUATION_DIRECTIVE_PREFIX)) {
+  disableTools()
+}
+```
+
+## Important Constraints
+
+- **Never drift the prefix** — server `decideRoute` and client `autoContinueRef` must both import from this file. A mismatched literal silently re-enables tools, causing the LLM to duplicate the just-approved tool call.
+- **Tools are hard-disabled** on the directive turn — all branches instruct the LLM to respond with prose only.
+- `toolName` is typed as `string` (not a const-union) intentionally, keeping the module generic across hub deployments.

package/src/components/chat/utils/.chat-attachment-markdown.md

@@ -0,0 +1,54 @@
+<!-- source-hash: 3113ae48366d1440e4d993a3e0404da3 -->
+Shared utility providing a single source of truth for formatting and parsing chat attachment markdown between the host-side bubble renderer and server-side LLM input cleaner, preventing drift between the two systems.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `CHAT_ATTACHMENT_VIEW_URL_PREFIX` | `const` | Hub-default proxy URL prefix for attachment view routes |
+| `CHAT_ATTACHMENT_VIEW_TOKEN_QUERY_PARAM` | `const` | Query param name (`t`) for the HMAC view token |
+| `ANTHROPIC_SUPPORTED_IMAGE_MIME` | `const` | Image MIME types renderable as Anthropic image blocks |
+| `ChatAttachment` | `interface` | Wire shape for a single chat attachment |
+| `buildChatAttachmentViewUrl` | `function` | Constructs the signed proxy URL for an attachment |
+| `escapeMarkdownInline` | `function` | Sanitizes filenames against markdown injection attacks |
+| `formatChatAttachmentMarkdownForBubble` | `function` | Produces the `![]()` or `[Attached: ...]` markdown line |
+| `CHAT_ATTACHMENT_MARKDOWN_PATTERN` | `RegExp` | Anchored regex matching both image and link attachment forms |
+| `stripChatAttachmentMarkdown` | `function` | Strips attachment markdown from text and extracts storage paths |
+
+## Usage Example
+
+```typescript
+import {
+  CHAT_ATTACHMENT_VIEW_URL_PREFIX,
+  formatChatAttachmentMarkdownForBubble,
+  stripChatAttachmentMarkdown,
+} from './chat-attachment-markdown'
+
+// Host-side: format attachment for user bubble (pass runtime prefix)
+const attachment: ChatAttachment = {
+  storagePath: 'org-123/chat/screenshot.png',
+  viewToken: 'hmac-signed-token',
+  contentType: 'image/png',
+  fileName: 'screenshot.png',
+  size: 204800,
+}
+
+// Embedded app overrides prefix; hub uses the constant directly
+const markdown = formatChatAttachmentMarkdownForBubble(
+  attachment,
+  'https://hub.example.com/api/storage/view/chat-attachments/',
+)
+// → "\n\n![screenshot.png](https://hub.example.com/api/storage/view/...?t=...)"
+
+// Server-side: strip attachment lines before sending to LLM
+const userMessage = `Please review this\n\n![screenshot.png](/api/storage/view/chat-attachments/org-123/chat/screenshot.png?t=abc)`
+const { stripped, storagePaths } = stripChatAttachmentMarkdown(userMessage)
+// stripped    → "Please review this"
+// storagePaths → ["org-123/chat/screenshot.png"]
+```
+
+## Security Notes
+
+- **Markdown injection**: `escapeMarkdownInline` escapes `[`, `]`, `(`, `)`, `\`, `<`, `>`, and `"` from filenames — preventing a crafted name like `screenshot](https://evil.com).png` from hijacking the image URL.
+- **Anthropic image blocks**: raw Supabase signed URLs are used (not the proxy) because Anthropic's fetcher does not reliably follow `302` redirects.
+- **View tokens**: HMAC-signed server-side; the client never generates them.