@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/shared/dev-section/.dev-card-row.md

@@ -1,60 +1,52 @@
-<!-- source-hash: 8d3da3a7c730a952779ad08cf7640368 -->
-Shared row chrome components for `DevSectionPage` list surfaces (delivery, tickets, etc.), providing a consistent two-column layout with fixed min-height blocks for vertical alignment across grid rows, plus a thread-style conversation variant for ticket detail drawers.
+<!-- source-hash: 0c00c0d0fde761ce69fdbcdde8644ab9 -->
+Shared layout component for `DevSectionPage` list rows, providing a consistent two-column structure (title/subtitle/description left, badges right) with matching skeleton states to prevent layout shift during loading.
 
 ## Key Components
 
 | Export | Type | Description |
-|--------|------|-------------|
-| `DevCardRowContent` | Component | Two-column card row: left (title/subtitle/description) + right (caller-supplied badges) |
-| `DevCardRowSkeleton` | Component | Loading skeleton mirroring `DevCardRowContent` min-heights |
-| `ConversationCardRow` | Component | Thread-style message row with avatar, author header, body, and attachments |
-| `ConversationCardRowSkeleton` | Component | Loading skeleton for a single `ConversationCardRow` |
-| `ConversationCardRowSkeletonList` | Component | Multi-row skeleton list (default: 2 rows) for conversation timeline loading state |
-| `DevCardRowContentProps` | Interface | Props for `DevCardRowContent` |
-| `ConversationCardRowProps` | Interface | Props for `ConversationCardRow` |
+|---|---|---|
+| `DevCardRowContent` | Component | Main row layout with fixed min-height blocks for title, subtitle, and description columns |
+| `DevCardRowContentProps` | Interface | Props contract for `DevCardRowContent` |
+| `DevCardRowSkeleton` | Component | Single animated skeleton row mirroring `DevCardRowContent` min-heights |
+| `DevCardRowSkeletonList` | Component | Bordered card wrapping `n` skeleton rows (default: 5); used by delivery and tickets list shells |
 
 ## Usage Example
 
 ```typescript
-// Static delivery card row (wrapped in a div)
-<div className="border-b border-ods-border p-[12px] md:p-[16px]">
+// Static row (e.g. delivery surface)
+<div>
   <DevCardRowContent
-    title="Deploy v2.4.1 to production"
+    title="Deploy to production"
     subtitle="UPDATED today, #4271, Code review"
-    description="Bumps the API gateway to support new webhook endpoints."
+    description="Automated deployment pipeline triggered by merge to main."
+    emptyDescription="No deployment notes available."
     rightBadges={
       <>
         <StatusBadge status="in-progress" />
-        <PriorityBadge priority="high" />
+        <EnvironmentBadge env="production" />
       </>
     }
   />
 </div>
 
-// Clickable ticket card row (wrapped in a button)
-<button onClick={openTicket}>
+// Clickable row (e.g. tickets surface)
+<button onClick={handleSelect}>
   <DevCardRowContent
-    title="Login page throws 502 on Safari"
-    subtitle="OPEN · #1042 · Bug"
-    description=""
-    emptyDescription="No description provided for this ticket."
-    rightBadges={<SeverityBadge level="critical" />}
+    title="Login page broken on Safari"
+    subtitle="OPEN, #1042, Bug"
+    description="Users on Safari 17 cannot submit the login form."
+    rightBadges={<PriorityBadge level="high" />}
   />
 </button>
 
-// Conversation thread row
-<ConversationCardRow
-  author="Jane Smith"
-  role="Resolution"
-  avatarSrc="https://cdn.example.com/avatars/jane.png"
-  timestamp="2026-01-15T14:32:00Z"
-  body="The issue has been resolved by restarting the gateway service."
-  attachments={[{ name: "fix-log.txt", url: "/files/fix-log.txt" }]}
-  variant="support"
-/>
-
-// Loading state
-<ConversationCardRowSkeletonList rows={3} />
+// Loading state — swap in before data arrives
+<DevCardRowSkeletonList rows={5} />
 ```
 
-> **Design note:** `DevCardRowContent` is layout-only — no click behavior is baked in. Wrap in `<div>` for static rows or `<button>` for interactive ones. `rightBadges` accepts any `ReactNode`, keeping badge composition flexible per surface.
+## Notes
+
+- `rightBadges` accepts any `ReactNode` — the caller controls badge count and type; no badge logic is embedded here.
+- Ticket conversation rows are intentionally excluded; they use the shared `<ChatMessageRow>` component (`components/chat/chat-message-row.tsx`).
+- Skeleton min-heights mirror content min-heights exactly to prevent reflow on data load.
+
+**Source:** [`dev-card-row.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/dev-card-row.tsx)

package/src/components/shared/dev-section/.dev-section-page.md

@@ -1,48 +1,59 @@
-<!-- source-hash: 0de96ea9df1ea6a28df1ff674cfc5e14 -->
-Full-page wrapper component for dev-center sections (`/roadmap`, `/bug-fixes-and-enhancements`, `/releases`) in the OpenFrame platform. It composes `PageShell → PageLayout → DevSectionView` to deliver a consistent hero icon, search, and filter pill layout across all dev sections.
+<!-- source-hash: 74cc123810f84748ea66fdf5666e6ad6 -->
+Full-page wrapper component for dev-center sections (`/roadmap`, `/bug-fixes-and-enhancements`, `/releases`) in the OpenFrame lib, composing `PageShell → PageLayout → DevSectionView → list body` into a single reusable factory.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `DevSectionPage` | Component | Main page wrapper factory for any `OpenframeDevSectionKey` section |
-| `DevSectionPageProps` | Interface | Props contract for `sectionKey`, `children`, `preControls`, and `backButton` |
-| `SECTION_HERO_ICON_CLASS` | Constant | Tailwind class applied uniformly to all section hero icons |
+### `DevSectionPage` (default export)
 
-### Props
+The primary component. Resolves section metadata from `OPENFRAME_DEV_SECTIONS` by `sectionKey`, wires the back-button navigation, and renders the page hierarchy.
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `sectionKey` | `OpenframeDevSectionKey` | Looks up section metadata from `OPENFRAME_DEV_SECTIONS` |
-| `children` | `ReactNode` | Page-specific list body (e.g. `<RoadmapList />`) |
-| `preControls` | `ReactNode` (optional) | Slot rendered between the hero and search/filter controls |
-| `backButton` | `{ label?, href? } \| false` (optional) | Configures or hides the back button; defaults to `Back to home → /` |
+### `DevSectionPageProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `sectionKey` | `OpenframeDevSectionKey` | required | Key into `OPENFRAME_DEV_SECTIONS` config |
+| `children` | `ReactNode` | required | List body (e.g. `<RoadmapList />`) |
+| `preControls` | `ReactNode` | — | Slot rendered between hero and search/filter controls |
+| `backButton` | `{ label?, href? } \| false` | `{ label: 'Back to home', href: '/' }` | Back-button config; `false` hides it |
+| `title` | `string` | section hero title | Override hero title for non-OpenFrame embeds |
+| `subtitle` | `string` | section hero description | Override hero subtitle |
+| `shell` | `boolean` | `true` | Wraps in `<PageShell>` (`<main>`); set `false` when host layout already provides the container |
 
 ## Usage Example
 
 ```typescript
-// Adding a new section page is a single mount:
-import { DevSectionPage } from '@/components/dev-center/dev-section-page';
+// Standard standalone page (e.g. app/roadmap/page.tsx)
+import { DevSectionPage } from '@/components/dev-sections/dev-section-page';
+import { RoadmapList } from '@/components/roadmap/roadmap-list';
 
 export default function RoadmapPage() {
   return (
-    <DevSectionPage
-      sectionKey="roadmap"
-      backButton={{ label: 'Back to home', href: '/' }}
-    >
+    <DevSectionPage sectionKey="roadmap">
       <RoadmapList />
     </DevSectionPage>
   );
 }
 
-// With a preControls slot (e.g. Help Center ticket form above filters):
+// Embedded inside a host app that already provides <main>
 <DevSectionPage
-  sectionKey="help-center"
+  sectionKey="releases"
+  shell={false}
+  backButton={{ label: 'Back to dashboard', href: '/dashboard' }}
   preControls={<OpenTicketForm />}
-  backButton={false} // hide back button
 >
-  <TicketList />
+  <ReleasesList />
+</DevSectionPage>
+
+// Hide back button entirely
+<DevSectionPage sectionKey="bug-fixes-and-enhancements" backButton={false}>
+  <BugFixList />
 </DevSectionPage>
 ```
 
-> **Extensibility:** Adding a new dev-center section requires only one entry in `OPENFRAME_DEV_SECTIONS` plus a single page file mounting `DevSectionPage` with the new key. Design system changes to `BackButton` or `TitleBlock` propagate automatically via the shared `PageLayout`.
+## Adding a New Section
+
+Register one entry in `OPENFRAME_DEV_SECTIONS` with the new key, then create a single-line page file mounting `DevSectionPage` with that key — no changes to this component required.
+
+---
+
+**Source:** [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib)

package/src/components/shared/dev-section/.dev-section-view.md

@@ -1,43 +1,53 @@
-<!-- source-hash: 508a1c69dd2d082f4bed6cb98c63998b -->
-Canonical chrome wrapper for dev-center sections (Roadmap, Delivery, Releases), handling title rendering, inline search, filter pills, and URL-param wiring in both tabbed and full-page layout modes.
+<!-- source-hash: 688a1a5f1e7d29524e457ab234690ffe -->
+Canonical chrome wrapper for dev-center sections (Roadmap, Delivery, Releases) that owns title rendering, inline search input, filter pill row, and URL parameter wiring. Designed for dual-mode use: tabbed compact headings or full-page hero layouts.
 
 ## Key Components
 
 ### `DevSectionView`
-The single shared layout shell consumed by every dev-center section page. Supports two display modes:
-- **Hero mode** — full-page layout with icon, `<h1>`, and description (pass `hero` prop)
-- **Compact mode** — tab-context `<h2>` heading only (omit `hero`)
 
-### `DevSectionViewProps`
+The primary export. A client component that renders section-level chrome and delegates list rendering to `children`.
+
+**Props (`DevSectionViewProps`):**
+
 | Prop | Type | Description |
-|------|------|-------------|
-| `sectionKey` | `OpenframeDevSectionKey` | Registry key driving title, search, and filter config |
-| `hero` | `{ icon: ReactNode, description: string }` | Enables full-page hero rendering |
+|---|---|---|
+| `sectionKey` | `OpenframeDevSectionKey` | Drives title, search, and filter config via the registry |
+| `hero` | `{ icon, title?, description }` | Enables full-page hero mode with icon + h1 + description |
 | `preControls` | `ReactNode` | Optional slot between hero and search/filter controls |
-| `children` | `ReactNode` | Section-specific list body; reads URL params set by this component |
+| `children` | `ReactNode` | List body; reads URL params set by this component |
+| `showHeading` | `boolean` | Defaults `true`; pass `false` when host renders the title elsewhere |
 
-### URL Contract
-- Search commits to `?<paramKey>=...` on **Enter only** (not every keystroke)
-- Filter changes are applied immediately via `router.replace` with `scroll: false`
-- Default filter values are omitted from the URL (cleaned via `params.delete`)
-- `searchValue` is lazy-initialized from URL params to prevent stale flash on tab switch
+**Internal behavior:**
+
+- Search input is **controlled** — commits to URL only on Enter (not every keystroke), preventing excessive navigation events
+- Filter changes write immediately to URL params via `router.replace` with `scroll: false`
+- Default filter value removes the param from the URL entirely (clean URLs)
+- `useEffect` syncs controlled search state from URL on param changes (e.g., tab switches)
 
 ## Usage Example
 
 ```typescript
-// Hero (full-page) mode
+// Full-page hero mode (e.g. /roadmap route)
 <DevSectionView
   sectionKey="roadmap"
-  hero={{ icon: <RoadmapIcon />, description: "Track upcoming features." }}
-  preControls={<NewTicketForm />}
+  hero={{
+    icon: <RoadmapIcon />,
+    title: "Product Roadmap",
+    description: "See what's coming next across the platform.",
+  }}
 >
   <RoadmapList />
 </DevSectionView>
 
-// Compact (tabbed) mode
-<DevSectionView sectionKey="releases">
-  <ReleasesList />
+// Compact tab mode (e.g. inside /roadmap-and-releases tabbed view)
+<DevSectionView
+  sectionKey="roadmap"
+  showHeading={false}
+>
+  <RoadmapList />
 </DevSectionView>
 ```
 
-Children read filter/search state directly from URL params via `useSearchParams()` — no prop drilling required.
+## Source
+
+[`dev-section-view.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/dev-section-view.tsx)

package/src/components/shared/doc-search/.doc-search-bar.md

@@ -0,0 +1,58 @@
+<!-- source-hash: 07409d514305754ffc933394824594aa -->
+A presentation-layer wrapper that connects `<SearchInput>` with `<DocSearchResultRow>` to deliver a consistent RAG-search dropdown across all doc-search surfaces (data-room sidebar, onboarding guide catalog, etc.).
+
+## Key Components
+
+### `DocSearchBar` (default export)
+
+A controlled, stateless component that delegates data-fetching entirely to the caller's hook (`useDocSearch`, hub-side). Renders `<SearchInput>` pre-wired with the standard `<DocSearchResultRow>` so the dropdown UI stays identical across every consumer.
+
+### `DocSearchBarProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `placeholder` | `string` | — | Input placeholder text |
+| `query` | `string` | — | Controlled query value |
+| `onQueryChange` | `(value: string) => void` | — | Query change handler |
+| `results` | `SearchResult[]` | — | Hook-fetched results |
+| `isLoading` | `boolean` | — | Loading state |
+| `onResultSelect` | `(result, modifiers?) => void` | — | Selection handler; preserves `cmd/ctrl/shift/alt` click modifiers for new-tab behavior |
+| `showDropdown` | `boolean \| undefined` | `undefined` | Force dropdown open after internal navigation |
+| `minQueryLength` | `number` | `2` | Minimum chars before search fires |
+| `debounceMs` | `number` | `0` | Debounce delay (consumers typically debounce in the hook) |
+| `className` | `string` | `"w-full"` | Root element class |
+| `renderResult` | `(result, isHighlighted) => ReactNode` | `<DocSearchResultRow>` | Custom row renderer override |
+
+## Usage Example
+
+```typescript
+// Minimal usage — hub hook provides data, component handles display
+function DocSidebarSearch() {
+  const { query, setQuery, results, isLoading, handleSelect } = useDocSearch()
+
+  return (
+    <DocSearchBar
+      placeholder="Search docs..."
+      query={query}
+      onQueryChange={setQuery}
+      results={results}
+      isLoading={isLoading}
+      onResultSelect={handleSelect}
+    />
+  )
+}
+
+// With custom row renderer override
+<DocSearchBar
+  {...searchProps}
+  renderResult={(result, isHighlighted) => (
+    <MyCustomRow result={result} highlighted={isHighlighted} />
+  )}
+/>
+```
+
+## Design Notes
+
+The hook (`useDocSearch`) intentionally lives hub-side — it depends on hub-only context (`useDocNavigation`, the RAG-table-config registry, `decideNewTab`). This component accepts hook output as plain props, keeping both consumers to ~5 lines while the dropdown chrome stays canonical.
+
+**Source:** [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/doc-search-bar.tsx)

package/src/components/shared/doc-search/.doc-search-result-row.md

@@ -0,0 +1,50 @@
+<!-- source-hash: fcada161400f637c1d8ff032c7fc20dd -->
+Renders a single search result row inside `<SearchInput>` dropdowns, providing a consistent visual layout for all doc-search surfaces (data-room sidebar, onboarding-guide catalog, etc.).
+
+## Key Components
+
+### Interfaces
+
+- **`DocSearchResultRowEntry`** — Minimal result shape; compatible with any `useDocSearch` hook result exposing `{ title?, path?, metadata? }`.
+- **`DocSearchResultRowProps`** — Props for the row: a `DocSearchResultRowEntry` and a boolean `isHighlighted` flag.
+
+### Component
+
+- **`DocSearchResultRow`** — Renders a flex row with:
+  - A source icon resolved via `resolveSourceIcon()` (same registry used by inline chat-card refs, preventing cross-surface icon drift).
+  - A truncating title/path label styled with `text-ods-accent` when highlighted.
+  - An optional relative path subtitle (hidden for group entries or single-segment paths), formatted via `formatRelativePath()`.
+
+## Usage Example
+
+```typescript
+import { DocSearchResultRow } from './doc-search-result-row'
+
+// Inside a SearchInput dropdown list:
+results.map((result, index) => (
+  <DocSearchResultRow
+    key={result.path}
+    result={result}
+    isHighlighted={index === highlightedIndex}
+  />
+))
+
+// Result shape — satisfied by useDocSearch hook output:
+const result = {
+  title: 'Getting Started Guide',
+  path: 'onboarding/getting-started',
+  metadata: {
+    documentType: 'onboarding-guide',
+    sourceRepo: 'internal-docs',
+    isGroup: false,
+  },
+}
+```
+
+## Notes
+
+- **Single source of truth** — centralises row appearance so all search dropdowns are visually identical.
+- Icon resolution is shared with the chat-card ref system via `resolveSourceIcon()`, ensuring glyph consistency (e.g. `<GraduationCap>` for onboarding guides) across every surface.
+- Group entries (`metadata.isGroup === true`) suppress the path subtitle.
+
+**Source:** [`doc-search-result-row.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/doc-search-result-row.tsx)

package/src/components/shared/doc-search/.format-relative-path.md

@@ -0,0 +1,30 @@
+<!-- source-hash: ab6e8805ed4afb72f4daaf8533fb546d -->
+Formats a full document path into a human-readable breadcrumb trail, showing only parent folder segments (excluding the filename).
+
+## Key Components
+
+- **`formatRelativePath(fullPath: string): string`** — Strips the `.md` extension, splits on `/`, drops the last segment (filename), then capitalizes and hyphen-decodes each folder name before joining with ` / `.
+
+## Usage Example
+
+```typescript
+import { formatRelativePath } from './format-relative-path'
+
+formatRelativePath('openframe-oss-tenant/architecture/api-controllers.md')
+// → 'Openframe oss tenant / Architecture'
+
+formatRelativePath('getting-started.md')
+// → 'Getting started'
+
+formatRelativePath('')
+// → ''
+```
+
+## Behavior Notes
+
+| Input | Output |
+|---|---|
+| Multi-segment path | Parent folders only, title-cased, hyphens → spaces |
+| Single segment (no `/`) | That segment formatted (no parent to strip) |
+| Empty string | Returns `''` immediately |
+| `.md` extension | Stripped before processing |

package/src/components/shared/doc-search/.index.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 1a3cdf4f2baf4c14c3068d549bbbc83a -->
+Public API barrel file for the `doc-search` package, re-exporting all components, hooks, utilities, and types needed to embed document search functionality in consuming applications.
+
+## Key Components
+
+| Export | Source | Description |
+|---|---|---|
+| `DocSearchBar` / `DocSearchBarProps` | `./doc-search-bar` | Search input component |
+| `DocSearchResultRow` / props + entry types | `./doc-search-result-row` | Renders a single search result |
+| `formatRelativePath` | `./format-relative-path` | Path formatting utility |
+| `useDocSearch` / `UseDocSearchConfig` | `./use-doc-search` | Debounced fetch + result navigation hook |
+| `resolveSearchResultAction` / `SearchResultAction` | `./resolve-search-result-action` | Determines the action for a given result |
+| `mapDocSearchResults` | `./map-doc-search-results` | Transforms raw API results into UI-ready shape |
+| `DocSearchResult` | `./types` | Shared result type |
+
+## Usage Example
+
+```typescript
+import {
+  DocSearchBar,
+  DocSearchResultRow,
+  useDocSearch,
+  type UseDocSearchConfig,
+  type DocSearchResult,
+} from '@openframe/doc-search'
+
+const config: UseDocSearchConfig = {
+  endpoint: '/api/docs/search',
+  debounceMs: 300,
+}
+
+function MySearchPanel() {
+  const { query, setQuery, results, navigate } = useDocSearch(config)
+
+  return (
+    <>
+      <DocSearchBar query={query} onChange={setQuery} />
+      {results.map((result: DocSearchResult) => (
+        <DocSearchResultRow key={result.id} entry={result} onSelect={navigate} />
+      ))}
+    </>
+  )
+}
+```
+
+> **Note for embedders:** `useDocSearch` bundles the debounced fetch and result navigation logic previously in `hub/hooks/use-docs.ts`, so you do not need to re-implement it when mounting `DocSearchBar` outside the hub.

package/src/components/shared/doc-search/.map-doc-search-results.md

@@ -0,0 +1,44 @@
+<!-- source-hash: 0432b27945c1f7d64624ec15662b0110 -->
+Transforms raw RAG `/api/docs/search` API results into typed `SearchResult` rows for the `<DocSearchBar>` dropdown, collapsing multiple financial entity-table rows into a single grouped result.
+
+## Key Components
+
+### Constants
+
+- **`SEARCH_GROUP_REPOS`** — `Set<string>` of source repos whose rows should be collapsed into grouped results (financial tables only: cap table, KPIs, P&L, balance sheet, cash flow)
+- **`ENTITY_LABELS`** — Display label map from `sourceRepo` key to human-readable string (e.g. `'financial-cap-table'` → `'Cap Table'`)
+
+### Exports
+
+- **`mapDocSearchResults(docs: DocSearchResult[]): SearchResult[]`** — Pure transform function; groups financial entity rows by `sourceRepo` while preserving insertion order, then maps each entry to the dropdown's `SearchResult` shape
+
+## Usage Example
+
+```typescript
+import { mapDocSearchResults } from './map-doc-search-results'
+
+const rawResults = await fetchDocSearch(query)
+const dropdownRows = mapDocSearchResults(rawResults)
+
+// Financial table rows are collapsed:
+// 12 cap-table rows → { title: "Cap Table (12 records)", metadata: { isGroup: true, items: [...] } }
+
+// Regular docs remain individual:
+// { id: '/docs/setup.md', title: 'Setup Guide', description: '...snippet...' }
+```
+
+## Grouping Behavior
+
+| Source repo | Behavior |
+|---|---|
+| `financial-*` repos | Collapsed → single group row with record count |
+| `blog-posts`, `webinars`, etc. | Individual rows (each has a unique URL) |
+| All other docs | Individual rows with snippet as description |
+
+Grouped results carry a `metadata.isGroup: true` flag and a `metadata.items` array of the collapsed records. Non-markdown individual results use `doc.name` as description instead of the snippet.
+
+> **Note:** This is a pure transform with no side effects. Callers that need telemetry or navigation should wrap this function rather than importing hub-specific logic.
+
+## Source
+
+[`map-doc-search-results.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/map-doc-search-results.ts)

package/src/components/shared/doc-search/.resolve-search-result-action.md

@@ -0,0 +1,52 @@
+<!-- source-hash: f287f0ffda0699577d87fde5f21130f1 -->
+Resolves what action to take when a user selects a search result, returning one of five typed discriminated union variants for the caller to handle via a single `switch`.
+
+## Key Components
+
+### `SearchResultAction` (type)
+
+Discriminated union with five variants:
+
+| Kind | Payload | Triggered when |
+|---|---|---|
+| `navigate-same-tab` | `href: string` | External URL, same-platform navigation |
+| `navigate-new-tab` | `href: string` | External URL, cross-platform navigation |
+| `ask-ai` | `{ source, ref: ChatRef }` | Row has `id`, `sourceRepo`, and `documentType` |
+| `route` | `path: string` | Row has only a `path` (legacy fallback) |
+| `noop` | — | Nothing actionable found |
+
+### `resolveSearchResultAction(result, source, runtimeMode?)` (function)
+
+Pure function — no React, no side effects, no telemetry. Evaluates `result.metadata` in priority order:
+
+1. **`externalUrl`** → delegates to `decideNewTab` using `targetPlatform`, `runtimeMode`, and `source` as `currentSource`
+2. **`id` + `sourceRepo` + `documentType`** → returns `ask-ai` with a `ChatRef` entity reference
+3. **`result.path`** → returns `route` for legacy path-based navigation
+4. **Fallthrough** → returns `noop`
+
+## Usage Example
+
+```typescript
+import { resolveSearchResultAction } from './resolve-search-result-action'
+
+const action = resolveSearchResultAction(searchResult, 'my-source', 'host')
+
+switch (action.kind) {
+  case 'navigate-same-tab':
+    router.push(action.href)
+    break
+  case 'navigate-new-tab':
+    window.open(action.href, '_blank')
+    break
+  case 'ask-ai':
+    chat.openWithRef(action.detail.ref)
+    break
+  case 'route':
+    router.push(action.path)
+    break
+  case 'noop':
+    break
+}
+```
+
+> **Source:** [`resolve-search-result-action.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/resolve-search-result-action.ts) — lifted from the hub's `hooks/use-docs.ts` and extracted as a standalone pure utility.

package/src/components/shared/doc-search/.types.md

@@ -0,0 +1,49 @@
+<!-- source-hash: 537733be76caba7ce3819410ae7e37fd -->
+Wire type for a single search result row returned by `/api/docs/search`, shared between the hub's RAG layer and the lib's search hook.
+
+## Key Components
+
+### `DocSearchResult` Interface
+
+| Field | Type | Description |
+|---|---|---|
+| `path` | `string` | Document path identifier |
+| `name` | `string` | Display name of the result |
+| `type` | `'file' \| 'folder'` | Whether the result is a file or folder |
+| `snippet` | `string` | Short excerpt from the matched content |
+| `matchType` | `'title' \| 'content'` | Whether the match occurred in title or body |
+| `documentType` | `string?` | Optional content type classification |
+| `externalUrl` | `string?` | External URL when result links outside the hub |
+| `targetPlatform` | `string \| null \| undefined` | Platform owning `externalUrl`; drives same-tab vs. new-tab logic via `decideNewTab` |
+| `sourceRepo` | `string?` | Repository the document originates from |
+| `entityId` | `string?` | Primary key value for RAG table rows; enables chat panel drill-in via `entityIdFilter` for entities with no public viewer |
+
+## Usage Example
+
+```typescript
+import type { DocSearchResult } from '@openframe-oss-lib/types'
+
+const result: DocSearchResult = {
+  path: '/docs/billing/cap-table',
+  name: 'Cap Table Overview',
+  type: 'file',
+  snippet: '...equity breakdown by shareholder...',
+  matchType: 'content',
+  documentType: 'financial',
+  entityId: 'row_abc123',
+}
+
+// Use entityId to open chat panel instead of navigating to a URL
+if (result.entityId && !result.externalUrl) {
+  openChatPanel({ entityIdFilter: result.entityId })
+} else {
+  navigate(result.externalUrl, { newTab: decideNewTab(result.targetPlatform) })
+}
+```
+
+## Notes
+
+- Must remain **field-for-field identical** with `lib/data/doc-search-utils.ts:DocSearchResult` in the hub — changes to either side must be mirrored.
+- `entityId` is specifically intended for RAG table rows (e.g. `cap_table`, `financial-kpis`) that have no public viewer URL; consumers should prefer chat-panel drill-in over synthesizing a potentially invalid path URL.
+
+**Source:** [`types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/types.ts)

package/src/components/shared/doc-search/.use-doc-search.md

@@ -0,0 +1,66 @@
+<!-- source-hash: ae4b7ed4a0dc9b425085be368f8c0a0e -->
+Debounced RAG-powered search hook that queries `/api/docs/search` and resolves result navigation across hub, embed, and bare-embedder contexts.
+
+## Key Components
+
+### `UseDocSearchConfig`
+
+Configuration interface with the following fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `source` | `string` | Discriminator forwarded as `?source=` to the search endpoint |
+| `baseRoute` | `string` | Route prefix used to detect in-page swappable results |
+| `onNavigate` | `(path: string) => void` | Imperative fallback navigation (e.g. `router.push`) |
+| `tableIds` | `string[]` | Optional RAG table IDs to narrow the search scope |
+| `onInPageSwap` | `(path: string) => boolean` | Optional callback for in-page doc-tree swaps |
+| `searchEndpoint` | `string` | Endpoint override; defaults to `/api/docs/search` |
+
+### `useDocSearch(config)`
+
+Returns:
+
+| Return | Description |
+|---|---|
+| `query` / `setQuery` | Controlled input state |
+| `results` | Mapped `SearchResult[]` from the API |
+| `isLoading` | True while debounce is pending or fetch is in-flight |
+| `handleResultSelect` | Click/keyboard handler resolving one of four action kinds: `navigate-same-tab`, `navigate-new-tab`, `ask-ai`, or `route` |
+| `keepDropdownOpen` | Stays `true` after new-tab navigations so the user can pick another result |
+
+## Usage Example
+
+```typescript
+import { useDocSearch } from './use-doc-search'
+import { useRouter } from 'next/navigation'
+
+function DocsSearchBar() {
+  const router = useRouter()
+
+  const { query, setQuery, results, isLoading, handleResultSelect } =
+    useDocSearch({
+      source: 'openframe',
+      baseRoute: '/onboarding-guides',
+      tableIds: ['onboarding-guides'],
+      onNavigate: (path) => router.push(path),
+      onInPageSwap: (path) => {
+        // Return true if handled in-page; false to fall through to router.push
+        return docTreeNavigate(path)
+      },
+    })
+
+  return (
+    <SearchInput
+      value={query}
+      onChange={setQuery}
+      results={results}
+      isLoading={isLoading}
+      onSelect={handleResultSelect}
+    />
+  )
+}
+```
+
+## Navigation Resolution
+
+The `handleResultSelect` handler respects modifier keys (`metaKey`, `ctrlKey`, `shiftKey`, middle-click) to force new-tab behavior, mirroring native anchor semantics on non-anchor rows. In `embed` mode, all same-tab results are routed through `resolveExternalNavigation` instead.