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

package/src/components/chat/utils/.onboarding-icons.md

@@ -0,0 +1,28 @@
+<!-- source-hash: 32750bb1be67e7dcd8caa8e94a4aab6b -->
+Resolves backend `SlashCommandSummary.iconName` strings to React icon components for empty-state onboarding cards, with a `FileIcon` fallback for unknown keys.
+
+## Key Components
+
+- **`OnboardingIconComponent`** — Exported type describing the shared prop interface (`size`, `className`, `color`) for all registered icons.
+- **`LogoOpenframeIcon`** — Internal wrapper around `OpenFrameLogo` that overrides size via `style` (bypasses hardcoded `width`/`height` attributes) and pins both path colors to `currentColor` for correct rendering on card surfaces.
+- **`ONBOARDING_ICONS`** — Static registry mapping `iconName` strings to React components, organized into three tiers:
+  - **Production keys** — short identifiers matching the `/api/docs/commands` contract (e.g., `clickup`, `slack`, `github`, `openframe`).
+  - **Figma-canonical aliases** — long-form names (e.g., `clickup-logo-grey`, `rocket-02`) kept for Storybook fixtures and legacy feed entries.
+  - **Generic v2 fall-throughs** — brand-agnostic glyphs (e.g., `search`, `ticket`, `bug`) for slash commands without a dedicated brand icon.
+- **`resolveOnboardingIcon(iconName)`** — Exported lookup function; returns the matched component or `FileIcon` when the key is unknown or `null`/`undefined`.
+
+## Usage Example
+
+```typescript
+import { resolveOnboardingIcon } from './onboarding-icons'
+
+function OnboardingCard({ iconName }: { iconName: string | null }) {
+  const Icon = resolveOnboardingIcon(iconName)
+
+  return (
+    <div className="onboarding-card">
+      <Icon size={24} className="text-ods-text-secondary" />
+    </div>
+  )
+}
+```

package/src/components/chat/utils/.process-historical-messages.md

@@ -1,46 +1,57 @@
-<!-- source-hash: 7e09c2236a5e011ba67fbc791276c8dc -->
-Utility for converting raw historical messages from GraphQL/API responses into structured, display-ready format for chat interfaces. Handles message grouping, approval workflows, tool executions, and error processing.
+<!-- source-hash: abb044a6e8d133979dfd31cca4044960 -->
+Transforms raw `HistoricalMessage` arrays from GraphQL/API responses into display-ready `ProcessedMessage` objects, handling message grouping, approval state resolution, and tool call rendering.
 
 ## Key Components
 
-### Main Functions
-- **`processHistoricalMessages()`** - Primary function that converts historical messages into display format
-- **`processHistoricalMessagesWithErrors()`** - Enhanced version that includes error messages in correct chronological order
-- **`extractErrorMessages()`** - Extracts and formats error messages separately
-- **`processMessageData()`** - Processes individual message data items into segments
+### `processHistoricalMessages(messages, options)`
+Main export. Iterates over historical messages, groups consecutive assistant turns into single display messages, and returns a `ProcessHistoricalMessagesResult` containing:
+- `messages` — fully rendered `ProcessedMessage[]` ready for UI consumption
+- `escalatedApprovals` — approvals filtered out by `displayApprovalTypes` that the consumer handles separately (e.g., admin-side approvals in a client-facing view)
 
-### Types
-- **`ProcessHistoricalMessagesResult`** - Return type containing processed messages and escalated approvals map
-- **`MessageProcessingOptions`** - Configuration options for message processing behavior
+### `processMessageData(data, accumulator, approvalStatuses, options, escalatedApprovals)`
+Internal dispatcher. Routes each `MessageData` item by `MESSAGE_TYPE` to the correct accumulator method:
 
-### Message Processing Features
-- Groups consecutive assistant messages into single display units
-- Handles approval request/result pairing and escalation
-- Processes tool execution states (executing/executed)
-- Filters messages by chat type when specified
-- Manages approval status tracking and display permissions
+| Type | Action |
+|---|---|
+| `TEXT` | `appendText` |
+| `THINKING` | `appendThinking` |
+| `EXECUTING_TOOL` / `EXECUTED_TOOL` | `addToolExecution` |
+| `APPROVAL_REQUEST` | Batch or legacy approval card, or escalate |
+| `APPROVAL_RESULT` | Resolves pending/escalated approvals |
+
+### `flushAssistantMessage()` *(internal closure)*
+Drains the segment accumulator into a single assistant `ProcessedMessage`. Uses the **last** message ID in the group as the React key for stable pagination behavior.
+
+### `ProcessHistoricalMessagesResult`
+```typescript
+export interface ProcessHistoricalMessagesResult {
+  messages: ProcessedMessage[]
+  escalatedApprovals: Map<
+    string,
+    { command: string; explanation?: string; approvalType: string; toolCalls?: PendingToolCallData[] }
+  >
+}
+```
 
 ## Usage Example
 
 ```typescript
 import { processHistoricalMessages } from './process-historical-messages'
 
-// Basic usage
-const result = processHistoricalMessages(rawMessages, {
-  assistantName: 'Fae',
-  assistantType: 'fae',
-  chatTypeFilter: 'support'
-})
-
-// With approval handling
-const resultWithApprovals = processHistoricalMessages(rawMessages, {
-  assistantName: 'Mingo',
-  onApprove: (requestId) => handleApproval(requestId, true),
-  onReject: (requestId) => handleApproval(requestId, false),
-  approvalStatuses: { 'req-123': 'approved' },
-  displayApprovalTypes: ['CLIENT', 'ADMIN']
-})
-
-console.log(result.messages) // Array of ProcessedMessage objects
-console.log(result.escalatedApprovals) // Map of escalated approval requests
-```
+const { messages, escalatedApprovals } = processHistoricalMessages(
+  rawMessages,
+  {
+    assistantName: 'Fae',
+    assistantType: 'fae',
+    approvalStatuses: { 'req-123': 'approved' },
+    displayApprovalTypes: ['CLIENT'],
+    batchApprovalsEnabled: true,
+    onApprove: (id) => handleApprove(id),
+    onReject: (id) => handleReject(id),
+  }
+)
+
+// escalatedApprovals contains ADMIN-type approvals for separate rendering
+```
+
+> **Note on `batchApprovalsEnabled`:** Defaults to `true`. Pass `false` to unfold batch approval requests into individual legacy approval cards — useful when the consuming UI has not yet adopted the batch approval component.

package/src/components/chat/utils/.scroll-anchor.md

@@ -0,0 +1,40 @@
+<!-- source-hash: 39c5170915f66dc4b8399abe15eb750e -->
+Provides wire-layer glue for the per-message `scrollAnchor` render hint, re-exporting the canonical constant and type alongside a wire-frame key and a validation parser so server and client code share a single source of truth.
+
+## Key Components
+
+| Export | Kind | Description |
+|---|---|---|
+| `SCROLL_ANCHOR` | Re-export (const) | Canonical registry of valid scroll anchor values (`TOP`, `BOTTOM`) |
+| `ScrollAnchor` | Re-export (type) | TypeScript type derived from `SCROLL_ANCHOR` |
+| `SCROLL_ANCHOR_WIRE_KEY` | `const string` | Literal key `"scrollAnchor"` used on the metadata leading frame wire format |
+| `parseScrollAnchor` | `function` | Narrows an unknown wire value to `ScrollAnchor \| null` |
+
+## Usage Example
+
+```typescript
+import {
+  SCROLL_ANCHOR,
+  SCROLL_ANCHOR_WIRE_KEY,
+  parseScrollAnchor,
+} from './scroll-anchor'
+
+// SERVER — emit into the metadata leading frame
+const metadataFrame = {
+  ...(scrollAnchor ? { [SCROLL_ANCHOR_WIRE_KEY]: scrollAnchor } : {}),
+}
+
+// CLIENT — parse and validate incoming wire frame
+const parsed = parseScrollAnchor(frame[SCROLL_ANCHOR_WIRE_KEY])
+
+if (parsed !== null) {
+  // Safe to use: parsed is narrowed to ScrollAnchor
+  applyScrollAnchor(parsed) // e.g. SCROLL_ANCHOR.TOP | SCROLL_ANCHOR.BOTTOM
+}
+// null is silently dropped by metadata-merge logic
+```
+
+## Notes
+
+- Malformed or unrecognised wire values return `null` and are filtered out by metadata-merge logic — they never overwrite a previously valid anchor value.
+- Centralising `SCROLL_ANCHOR_WIRE_KEY` here means renaming the wire field requires a change in exactly one place.

package/src/components/chat/utils/.slash-dispatch-utils.md

@@ -0,0 +1,44 @@
+<!-- source-hash: 445fe5d7652052e5502c2026ce010a3c -->
+Portable wire-contract utilities and text helpers for slash-command dispatch, shared between the lib layer and hub UI chat surfaces.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `WireCommandOverride` | Interface | Client-safe wire shape for chat request bodies; excludes `systemPromptAddendum` to prevent Rule-5b injection |
+| `CommandOverride` | Interface | Server-built dispatch result passed to `buildChatContext`; includes entity lookup, ID filter, browse scope, and presentation hint |
+| `parseWireCommandOverride` | Function | Validates and parses raw wire input; enforces regex + length constraints on `entityIdFilter` and `retrievalQueryOverride` |
+| `extractEntityIdFilter` | Function | Safely resolves `entityIdFilter` from a `CommandOverride`, with optional `tableId` narrowing |
+| `sanitizeTitleForChat` | Function | Collapses control characters (`\r`, `\n`, `\t`) in free-text titles to single spaces |
+| `formatSingularLookupInvocation` | Function | Builds a `/cmd "value"` string with two-pass backslash/quote escaping for safe re-parsing |
+| `buildDiscussAddendum` | Function | Composes a server-trusted system-prompt addendum for the inline object-card "Discuss" action |
+
+## Usage Example
+
+```typescript
+import {
+  parseWireCommandOverride,
+  extractEntityIdFilter,
+  formatSingularLookupInvocation,
+  buildDiscussAddendum,
+} from './slash-dispatch-utils'
+
+// Validate incoming wire payload
+const override = parseWireCommandOverride(req.body.commandOverride)
+// override is null if malformed; typed WireCommandOverride if valid
+
+// Narrow to a specific table
+const filter = extractEntityIdFilter(override, 'tickets')
+if (filter) {
+  const { tableId, id } = filter // safe, both non-empty and tableId === 'tickets'
+}
+
+// Build a user-visible slash invocation
+const msg = formatSingularLookupInvocation('ticket', 'Fix "login" bug\\path')
+// → /ticket "Fix \"login\" bug\\path"
+
+// Compose a Discuss addendum server-side (never from wire input)
+const addendum = buildDiscussAddendum({ tableId: 'tickets', id: 'tkt-001' })
+```
+
+> **Security note:** `systemPromptAddendum` is intentionally absent from `WireCommandOverride`. Addendum text is always composed server-side via `buildDiscussAddendum` from trusted values, preventing arbitrary prompt injection from the client.

package/src/components/chat/utils/.source-icons.md

@@ -0,0 +1,35 @@
+<!-- source-hash: d57dc21ab260007a759f5621c538fd6e -->
+Client-side re-export shim that proxies source-icons utilities from the server-safe implementation at `src/utils/source-icons.ts`, allowing chat-side consumers to import from the chat-utils barrel path without duplication.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `SOURCE_ICON_NAMES` | Static map of source names to their icon identifiers |
+| `getSourceIconName` | Helper to resolve an icon name for a given source |
+| `SOURCE_LABELS_BY_TABLE` | Map of table IDs to human-readable source labels |
+| `getSourceLabel` | Helper to resolve a display label for a given table |
+| `DEFAULT_DOCUMENT_TYPE_TO_TABLE_ID` | Static map of document types to their default table IDs |
+| `defaultTableIdForDocumentType` | Helper to resolve the default table ID for a document type |
+
+## Usage Example
+
+```typescript
+// Chat-side consumers import via the chat-utils barrel
+import {
+  getSourceIconName,
+  getSourceLabel,
+  defaultTableIdForDocumentType,
+} from '@/chat-utils'
+
+// Resolve a source icon for rendering
+const iconName = getSourceIconName('zendesk') // e.g. "ZendeskIcon"
+
+// Get a human-readable label for a table
+const label = getSourceLabel('tickets') // e.g. "Zendesk Tickets"
+
+// Resolve the default table for a document type
+const tableId = defaultTableIdForDocumentType('article') // e.g. "kb_articles"
+```
+
+> **Note:** The actual logic lives in `src/utils/source-icons.ts`, which carries no `'use client'` directive, keeping it safe for server-side hub code. This shim exists purely to preserve the chat-utils barrel import path.

package/src/components/chat/utils/.source-row-cta.md

@@ -0,0 +1,54 @@
+<!-- source-hash: e259d6e958fa331a13973e9d2749ffbc -->
+Resolves the "what does clicking this row do?" CTA contract for source rows across chat-adjacent surfaces (chips, inline cards, search results). Pure function — no DOM, no fetch, no side effects.
+
+## Key Components
+
+### Interfaces
+
+| Interface | Purpose |
+|---|---|
+| `SourceRowInput` | Row data — `sourceRepo`, `documentType`, `id`, `title`, `externalUrl`, `path` |
+| `SourceRowContext` | Host-injected context — `baseRoute`, `chipBasePlatform`, `currentPlatform`, `tableIdForDocumentType` |
+| `SourceRowCTA` | Resolved contract — `icon`, `iconLabel`, `href`, `targetPlatform`, `askable`, `chatRef` |
+
+### Exports
+
+- **`resolveSourceRowCTA(row, ctx)`** — Primary resolver. Returns the full CTA contract for a row. Handles icon resolution, URL safety (`safeHref`), path sanitization, and Ask drill-in viability.
+- **`resolveSourceIcon(input, ctx)`** — Lightweight helper for surfaces that only need the icon + label (inline cards, search dropdown). Accepts `{ sourceRepo, documentType }` or a bare `string` (treated as `documentType`) for backward compatibility.
+
+### Internal Helpers
+
+- **`sanitizePath(path)`** — Strips non-alphanumeric characters except `/`, `-`, `.`, `_` to prevent path traversal or query injection.
+- **`shouldFallbackToPathNav(row)`** — Limits in-app path fallback to `markdown` and `data_room_doc` document types only.
+- **`pickSourceIcon(sourceRepo, documentType)`** — Maps `sourceRepo` → icon name → React component via `SOURCE_ICON_NAMES` + `ICON_REGISTRY`; falls back to `FileText`.
+
+## Usage Example
+
+```typescript
+import { resolveSourceRowCTA, resolveSourceIcon } from './source-row-cta'
+
+// Full CTA resolution for a chip or search result
+const cta = resolveSourceRowCTA(
+  {
+    sourceRepo: 'blog-posts',
+    documentType: 'blog_post',
+    id: 'post-42',
+    title: 'Series A Playbook',
+    externalUrl: 'https://example.com/posts/42',
+    targetPlatform: 'hub',
+  },
+  {
+    baseRoute: '/knowledge-base',
+    currentPlatform: 'hub',
+    tableIdForDocumentType: (type) => type === 'blog_post' ? 'blog-posts' : null,
+  },
+)
+// cta.href       → 'https://example.com/posts/42'  (safeHref-validated)
+// cta.askable   → true
+// cta.chatRef   → { type: 'blog_post', sourceRepo: 'blog-posts', id: 'post-42', ... }
+
+// Icon-only resolution for an inline card tracking strip
+const { Icon, label } = resolveSourceIcon({ documentType: 'cap_table' }, { tableIdForDocumentType })
+```
+
+> `href` is always `safeHref()`-sanitized — a hostile RAG row cannot inject `javascript:` or `data:` URIs into the DOM. Ask drill-in (`askable`) requires both a non-empty `id` and a `documentType`.

package/src/components/chat/utils/.tool-call-helpers.md

@@ -0,0 +1,42 @@
+<!-- source-hash: 6aecca2e05a8c612241168939fffcf70 -->
+Utility helpers for resolving, formatting, and rendering tool call data — titles, argument values, and execution results — used across approval and execution UI cards.
+
+## Key Components
+
+### Constants
+- **`COMMAND_BODY_ARG_KEYS`** — Ordered list of argument keys (`command`, `query`, `script`, `scriptContent`, `code`) checked when resolving a tool call's display title.
+
+### Functions
+
+| Function | Description |
+|---|---|
+| `getToolCallTitle(opts)` | Resolves a human-readable title from args, title, or name — shape-agnostic for both approval and execution cards. |
+| `getCommandText(call)` | Thin adapter over `getToolCallTitle` for `PendingToolCallData`. |
+| `expandedJsonStringify(value)` | Pretty-prints JSON with real newlines for multi-line strings instead of escaped `\n` sequences. |
+| `formatToolArgValue(value)` | Determines inline vs. block rendering for a single tool argument value. |
+| `formatToolResult(value)` | Determines inline vs. block rendering for a tool execution result, stripping markdown code fences if present. |
+
+### Types
+- **`FormattedArgValue`** — Discriminated union: `{ kind: 'inline'; text: string }` or `{ kind: 'block'; text: string; language: 'json' | 'text' }`.
+
+## Usage Example
+
+```typescript
+import {
+  getCommandText,
+  formatToolArgValue,
+  formatToolResult,
+} from './tool-call-helpers'
+
+// Resolve display title from a pending tool call
+const title = getCommandText(pendingCall)
+// → e.g. "Get-Process | Where-Object CPU -gt 50"
+
+// Render an argument value
+const rendered = formatToolArgValue({ host: 'server-01', port: 22 })
+// → { kind: 'block', text: '{\n  "host": "server-01",\n  "port": 22\n}', language: 'json' }
+
+// Render a tool execution result (strips fences, detects JSON)
+const result = formatToolResult('```json\n{"status":"ok"}\n```')
+// → { kind: 'block', text: '{\n  "status": "ok"\n}', language: 'json' }
+```

package/src/components/contact/.contact-form.md

@@ -0,0 +1,43 @@
+<!-- source-hash: e6e63274e2215026ef420402aa7a9e8f -->
+A self-contained, reusable contact form component that supports both standard contact submission and custom ticket-creation flows via configurable props. It handles field visibility toggling, attachment staging, Zod validation, and dual submit paths (built-in API vs. caller-provided handler).
+
+## Key Components
+
+**Exported Types**
+- `ContactFormHideableField` — Union type of the six fields that can be suppressed from the UI (`name`, `email`, `companySize`, `referralSource`, `helpCategory`, `message`)
+- `ContactFormProps` — Full prop interface covering attribution, pre-fill, layout, submission, and slot customization
+
+**Main Export**
+- `ContactForm` — The primary form component
+
+**Internal Hooks Used**
+- `useForm` (react-hook-form) + `zodResolver` against `ContactSchema`
+- `useContactSubmission` — built-in `/api/contact` submit path with toast + redirect
+- `useChatAttachments` — file staging shared with the chat composer
+- `useState` — tracks in-flight state for the custom submit path
+
+## Usage Example
+
+```typescript
+// Standard contact page — built-in submit flow
+<ContactForm
+  userId={user?.id}
+  helpCategoryOptions={appConfig.contact.contactReasons}
+  rdtCid={getStoredRedditClickId()}
+  onSubmitSuccess={clearStoredRedditClickId}
+/>
+
+// Ticket creation — custom submit, hidden fields, extra Subject input
+<ContactForm
+  hideFields={['name', 'email', 'companySize', 'referralSource', 'helpCategory']}
+  defaultValues={{ name: user.name, email: user.email, helpCategory: 'Support' }}
+  attachmentsEnabled
+  extraTopField={<SubjectInput value={subject} onChange={setSubject} />}
+  submitLabel="Open ticket"
+  onCustomSubmit={async (data, attachments) => {
+    await actions.submitTicket({ ...data, subject, attachments })
+  }}
+/>
+```
+
+> **Note:** When hiding `name`, `email`, or `helpCategory`, you **must** supply their values via `defaultValues` — Zod still validates them even when the fields are not rendered. Hidden `<input type="hidden">` elements ensure react-hook-form includes them in the submit payload.

package/src/components/contact/.index.md

@@ -0,0 +1,27 @@
+<!-- source-hash: 29826720baf088c1409fbd30046713a4 -->
+Re-exports the `ContactForm` component along with its associated TypeScript types from the `contact-form` module.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `ContactForm` | Component | The main contact form component |
+| `ContactFormProps` | Type | Props interface for the `ContactForm` component |
+| `ContactFormHideableField` | Type | Type representing fields that can be hidden in the form |
+
+## Usage Example
+
+```typescript
+import {
+  ContactForm,
+  type ContactFormProps,
+  type ContactFormHideableField,
+} from '@/components/contact-form'
+
+const hiddenFields: ContactFormHideableField[] = ['phone', 'company']
+
+const props: ContactFormProps = {
+  onSubmit: (data) => console.log(data),
+  hideFields: hiddenFields,
+}
+```

package/src/components/features/.array-entry-manager.md

@@ -1,53 +1,44 @@
-<!-- source-hash: b9899c71d148f2b5407351f417b4f050 -->
-A React component for managing arrays of entries with add/edit/remove functionality, supporting both immediate and deferred save modes.
+<!-- source-hash: 9a66a790bb4e14efee7ac5e9ffc0cfb8 -->
+A generic, reusable React component for managing arrays of objects with inline add, edit, remove, and multi-line paste support. Supports both immediate and deferred (save-gated) change modes.
 
 ## Key Components
 
-- **ArrayEntryManager** - Generic TypeScript component for managing array entries with configurable fields
-- **Props Interface** - Comprehensive configuration options including custom renderers, save modes, and styling
-- **State Management** - Handles both immediate updates and draft mode with dirty state tracking
-- **Paste Handling** - Smart multi-line paste support for bulk entry addition
+### `ArrayEntryManager<T>`
+A generic client component that renders a labeled list of editable input entries backed by a typed array.
 
-## Usage Example
-
-```typescript
-import { ArrayEntryManager } from './array-entry-manager';
-import { Github } from 'lucide-react';
+**Props:**
 
-interface Release {
-  github_release_url: string;
-  version?: string;
-}
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `ReactNode` | Section label; supports strings or badge components |
+| `items` | `T[]` | Array of objects to manage |
+| `onChange` | `(items: T[]) => void` | Called on change (immediate) or save (deferred) |
+| `fieldKey` | `keyof T` | Object key to bind each input to |
+| `requireSave` | `boolean` | When `true`, buffers edits locally until "Save" is clicked |
+| `onDirtyChange` | `(isDirty: boolean) => void` | Notifies parent of unsaved changes |
+| `renderLabel` | `(item: T, index: number) => ReactNode` | Custom renderer above each input |
+| `isSaving` | `boolean` | Shows spinner on the save button during async operations |
 
-function ReleaseManager() {
-  const [releases, setReleases] = useState<Release[]>([]);
-  const [isSaving, setIsSaving] = useState(false);
+**Behaviors:**
+- **Draft mode** (`requireSave=true`): edits are buffered in local state; `onChange` fires only on explicit save
+- **Immediate mode** (`requireSave=false`): every edit calls `onChange` directly
+- **Multi-line paste**: pasting newline-separated values auto-creates multiple entries
+- **Add at top**: new items are prepended for better UX
 
-  const handleSave = async (items: Release[]) => {
-    setIsSaving(true);
-    // Save to API
-    await saveReleases(items);
-    setIsSaving(false);
-  };
-
-  return (
-    <ArrayEntryManager
-      title="GitHub Releases"
-      items={releases}
-      onChange={handleSave}
-      fieldKey="github_release_url"
-      placeholder="https://github.com/owner/repo/releases/tag/v1.0.0"
-      emptyMessage="No releases configured"
-      addButtonText="Add Release"
-      icon={<Github className="h-5 w-5" />}
-      requireSave={true}
-      isSaving={isSaving}
-      renderLabel={(item, index) => 
-        item.version && <span className="badge">{item.version}</span>
-      }
-    />
-  );
-}
-```
+## Usage Example
 
-The component supports immediate onChange updates or deferred saves with dirty state tracking, multi-line paste for bulk additions, and custom label rendering for enhanced UX.
+```typescript
+<ArrayEntryManager<{ github_release_url: string }>
+  title="Release URLs"
+  items={releaseUrls}
+  onChange={setReleaseUrls}
+  fieldKey="github_release_url"
+  placeholder="https://github.com/org/repo/releases/tag/v1.0.0"
+  emptyMessage="No release URLs configured."
+  addButtonText="Add URL"
+  saveButtonText="Save URLs"
+  requireSave={true}
+  onDirtyChange={(dirty) => setHasUnsavedChanges(dirty)}
+  isSaving={isSaving}
+/>
+```

package/src/components/features/.changelog-manager.md

@@ -1,12 +1,35 @@
-<!-- source-hash: 3644c900574f6a351d839d94b7f4446b -->
-A client-side React component for managing changelog entries with expandable/collapsible sections, providing an interface to add, edit, and remove changelog items with title and description fields.
+<!-- source-hash: 2cb028936365715865c9571d3df0261e -->
+A reusable React component for managing a dynamic list of changelog entries, supporting add, remove, expand/collapse, and optional per-entry visibility toggling.
 
 ## Key Components
 
-- **ChangelogManager**: Main component that renders a list of expandable changelog entries
-- **ChangelogManagerProps**: Interface defining component props including title, entries array, change handler, and optional expand control
-- **State Management**: Uses `useState` for tracking expanded items and `useEffect` for handling expand-all functionality
-- **Entry Operations**: Functions for adding, removing, and updating changelog entries with automatic expansion state management
+### `ChangelogManager` (default export)
+
+A controlled list manager rendered as a collapsible accordion of `ChangelogEntry` items.
+
+**Props (`ChangelogManagerProps`):**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `string` | Section label displayed above the entry list |
+| `entries` | `ChangelogEntry[]` | Controlled array of changelog entries |
+| `onChange` | `(entries: ChangelogEntry[]) => void` | Callback fired on any mutation |
+| `className` | `string?` | Optional wrapper class override |
+| `expandAll` | `boolean?` | When `true`, expands all items (e.g. post-AI enrichment) |
+| `showVisibilityToggle` | `boolean?` | Renders a per-entry `Eye`/`EyeOff` toggle; used by investor updates |
+
+**Internal state:**
+- `expandedIndices` — `Set<number>` tracking which accordion items are open
+
+**Key functions:**
+
+| Function | Behavior |
+|----------|----------|
+| `addEntry()` | Appends a blank entry and auto-expands it |
+| `removeEntry(index)` | Removes entry and adjusts the expanded indices set |
+| `updateEntry(index, field, value)` | Immutably updates a single field on an entry |
+| `toggleExpanded(index)` | Toggles accordion open/close state |
+| `toggleVisibility(index)` | Flips `visibility` between `'public'` and `'internal'` |
 
 ## Usage Example
 
@@ -14,20 +37,23 @@ A client-side React component for managing changelog entries with expandable/col
 import { ChangelogManager } from './changelog-manager';
 import type { ChangelogEntry } from '../../types/product-release';
 
-function ReleaseNotesForm() {
-  const [features, setFeatures] = useState<ChangelogEntry[]>([]);
-  const [expandFeatures, setExpandFeatures] = useState(false);
-
-  return (
-    <ChangelogManager
-      title="New Features"
-      entries={features}
-      onChange={setFeatures}
-      expandAll={expandFeatures}
-      className="mb-6"
-    />
-  );
-}
+const [entries, setEntries] = useState<ChangelogEntry[]>([]);
+
+// Basic product release changelog
+<ChangelogManager
+  title="What's New"
+  entries={entries}
+  onChange={setEntries}
+/>
+
+// Investor update with visibility control + auto-expand after AI fill
+<ChangelogManager
+  title="Highlights"
+  entries={entries}
+  onChange={setEntries}
+  showVisibilityToggle
+  expandAll={aiEnrichmentComplete}
+/>
 ```
 
-The component provides a clean interface for managing changelog sections with collapsible entries, automatic expansion of new items, and responsive design with dark theme styling. Each entry includes title and description fields with validation indicators.
+> **Note:** `showVisibilityToggle` is intended for investor update flows. Leave it unset for standard product release changelogs to preserve their default UX. New entries default to `visibility: 'public'` when the toggle is enabled.