@flamingo-stack/openframe-frontend-core 0.0.510 → 0.0.512-1640.4207.1

package/src/components/chat/hooks/use-nats-chat-adapter.ts

@@ -56,6 +56,7 @@ import { createChatDialogStore, DEFAULT_DIALOG_SIDE } from '../stream/chat-dialo
 import { useChatStreamReducer } from '../stream/use-chat-stream-reducer'
 import { processHistoricalMessagesWithErrors } from '../utils/process-historical-messages'
 import { extractIncompleteTailState } from '../utils/extract-incomplete-message-state'
+import { buildDiscussPrompt } from '../utils/discuss-ref-prompt'
 import type {
   ChunkData,
   FetchChunksFunction,
@@ -1076,10 +1077,33 @@ export function useNatsChatAdapter(
     [],
   )
 
-  // No-op refs — Mingo agent has no RAG entity-card affordances.
-  const discussRef = useCallback((_ref: ChatRef) => {
-    /* no-op in Mingo mode */
-  }, [])
+  // "Ask Mingo" on an inline entity card. The agent transport has NO
+  // entity-id-filtered retrieval (its `ContextItemType` enum covers DEVICE /
+  // SCRIPT / TICKET / ORGANIZATION / USER / KB_ARTICLE / POLICY / QUERY /
+  // SCHEDULED_SCRIPT — no content types), so unlike the SSE path there is no
+  // `commandOverride.entityIdFilter` to send: the prompt carries the type + id
+  // as text and the agent resolves the row itself. Same sentence as guide mode
+  // (shared builder) so the affordance reads identically in both.
+  //
+  // This used to be a no-op, which made the card's "Ask Mingo" menu item dead
+  // in Mingo mode. Swap `includeReference` for a structured filter once the
+  // agent backend accepts one.
+  const discussRef = useCallback(
+    (reference: ChatRef) => {
+      const prompt = buildDiscussPrompt(reference, { includeReference: true })
+      // Menu-item click, so there is no composer promise for the rejection to
+      // surface through — a bare `void` would leave it unhandled. Logged in the
+      // same shape as `stopMessage`'s. NOTE: recovering the optimistic rows and
+      // the stuck `thinking` phase after a failed publish is a `sendMessage`
+      // concern (it affects composer sends identically) and is not done here.
+      void sendMessage(prompt).catch((err) => {
+        console.error('[useNatsChatAdapter] discussRef send failed:', err)
+      })
+    },
+    [sendMessage],
+  )
+  // Display stays a no-op: it dispatches a `/…  display "<x>"` slash command,
+  // and the agent transport has no slash-command registry.
   const displayRef = useCallback((_ref: ChatRef) => {
     /* no-op in Mingo mode */
   }, [])

package/src/components/chat/hooks/use-sse-chat-adapter.ts

@@ -67,6 +67,7 @@ import {
 } from '../utils/chat-conversation-storage'
 import { useChatHistoryHydration } from './use-chat-history-hydration'
 import { sanitizeTitleForChat } from '../utils/slash-dispatch-utils'
+import { buildDiscussPrompt } from '../utils/discuss-ref-prompt'
 import { defaultTableIdForDocumentType } from '../utils/source-icons'
 import type { WireCommandOverride } from '../utils/slash-dispatch-utils'
 import type { ChatAttachment } from '../utils/chat-attachment-markdown'
@@ -657,9 +658,10 @@ export function useSseChatAdapter(
       }
       // RETRIEVAL IS STRICTLY PRIMARY-KEY-DRIVEN. The visible prose
       // ("Tell me more about <title>") is UX-only; retrieval narrows
-      // via `entityIdFilter` before the LLM is invoked.
-      const sanitizedTitle = sanitizeTitleForChat(reference.title)
-      const prompt = `Tell me more about ${sanitizedTitle || 'this item'}`
+      // via `entityIdFilter` before the LLM is invoked. The sentence itself
+      // comes from the shared builder so the Mingo transport (which has no
+      // id filter and leans on the prose) phrases it identically.
+      const prompt = buildDiscussPrompt(reference)
       sendMessage(prompt, {
         commandOverride: { entityIdFilter: { tableId, id: refId } },
       })

package/src/components/chat/remark-mention-chips.ts

@@ -15,9 +15,12 @@
  * intact, and the marker disappears before any rehype-raw HTML pass.
  *
  * Grammar:
- *   - marker: `[a-z]+` — the backend `ContextItemType.marker()` short form
+ *   - marker: `[a-zA-Z]+` — the backend `ContextItemType.marker()` short form
  *     (`device`, `script`, `ticket`, `organization`, `user`, `kb`, `policy`,
- *     `query`, …). Always lowercase.
+ *     `query`, `scheduledScript`, …). Mostly lowercase, but NOT guaranteed to be:
+ *     the marker is matched verbatim by the backend's `MentionParser`, and
+ *     `SCHEDULED_SCRIPT` ships as camelCase `scheduledScript` — a lowercase-only
+ *     grammar silently dropped that whole token (no chip, raw text in the bubble).
  *   - id: charset `[A-Za-z0-9_.+/=-]` (UUIDs with hyphens, fleet numeric ids,
  *     base64 global ids, etc.; matches the composer's `MENTION_TOKEN`) — but the
  *     id may NOT END in `.` or `-`, so a trailing SENTENCE period/dash isn't
@@ -35,7 +38,7 @@ import type { Plugin } from 'unified'
 import type { Root, Text, Link } from 'mdast'
 import { visit, SKIP } from 'unist-util-visit'
 
-const MENTION_REGEX = /(^|[^\w@])@([a-z]+):([A-Za-z0-9_.+/=-]*[A-Za-z0-9_+/=])/g
+const MENTION_REGEX = /(^|[^\w@])@([a-zA-Z]+):([A-Za-z0-9_.+/=-]*[A-Za-z0-9_+/=])/g
 
 export const remarkMentionChips: Plugin<[], Root> = () => {
   return (tree: Root) => {

package/src/components/chat/utils/__tests__/discuss-ref-prompt.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest'
+import { buildDiscussPrompt } from '../discuss-ref-prompt'
+import { readFetchedCardTitle } from '../resolve-fetched-card-href'
+
+const ROADMAP_REF = {
+  type: 'roadmap_item',
+  id: '86ad3qvv5',
+  title: 'Deep Google Workspace tenant management',
+}
+
+describe('buildDiscussPrompt', () => {
+  it('guide/SSE shape — prose only, retrieval rides entityIdFilter', () => {
+    expect(buildDiscussPrompt(ROADMAP_REF)).toBe(
+      'Tell me more about Deep Google Workspace tenant management',
+    )
+  })
+
+  it('Mingo shape — appends the reference the agent has no filter for', () => {
+    expect(buildDiscussPrompt(ROADMAP_REF, { includeReference: true })).toBe(
+      'Tell me more about Deep Google Workspace tenant management (roadmap_item 86ad3qvv5)',
+    )
+  })
+
+  it('a synthetic ref (title === id) never leaks the id as the subject', () => {
+    const synthetic = { type: 'roadmap_item', id: '86ad3qvv5', title: '86ad3qvv5' }
+    expect(buildDiscussPrompt(synthetic, { includeReference: true })).toBe(
+      'Tell me more about this item (roadmap_item 86ad3qvv5)',
+    )
+  })
+
+  it('missing / blank title falls back to "this item"', () => {
+    expect(buildDiscussPrompt({ type: 'blog_post', id: 'b1' })).toBe('Tell me more about this item')
+    expect(buildDiscussPrompt({ type: 'blog_post', id: 'b1', title: '   ' })).toBe(
+      'Tell me more about this item',
+    )
+  })
+
+  it('no id → no reference suffix', () => {
+    expect(buildDiscussPrompt({ type: 'blog_post', id: '', title: 'Hello' }, { includeReference: true })).toBe(
+      'Tell me more about Hello',
+    )
+  })
+})
+
+describe('readFetchedCardTitle — what upgrades a synthetic ref before the prompt', () => {
+  it('prefers title, then name', () => {
+    expect(readFetchedCardTitle({ title: 'Roadmap row' })).toBe('Roadmap row')
+    expect(readFetchedCardTitle({ name: 'Named row' })).toBe('Named row')
+    expect(readFetchedCardTitle({ title: '  ', name: 'Named row' })).toBe('Named row')
+  })
+
+  it('null for rows with neither (and for non-objects)', () => {
+    expect(readFetchedCardTitle({ headline: 'nope' })).toBeNull()
+    expect(readFetchedCardTitle(null)).toBeNull()
+    expect(readFetchedCardTitle('string')).toBeNull()
+    expect(readFetchedCardTitle({ title: 42 })).toBeNull()
+  })
+
+  it('end to end: fetched row title reaches the prompt', () => {
+    const synthetic = { type: 'roadmap_item', id: '86ad3qvv5', title: '86ad3qvv5' }
+    const row = { id: 'db-9', title: 'Deep Google Workspace tenant management' }
+    const enriched = { ...synthetic, title: readFetchedCardTitle(row) ?? synthetic.title }
+    expect(buildDiscussPrompt(enriched, { includeReference: true })).toBe(
+      'Tell me more about Deep Google Workspace tenant management (roadmap_item 86ad3qvv5)',
+    )
+  })
+})

package/src/components/chat/utils/__tests__/resolve-fetched-card-href.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from 'vitest'
+import { makeComposeContentUrl } from '../../../../utils/content-href'
+import { resolveFetchedCardHref } from '../resolve-fetched-card-href'
+
+const HUB = 'https://www.flamingo.run'
+
+/** The OpenFrame Help Center seam, verbatim in shape from
+ *  `openframe-oss-frontend/src/app/(app)/help-center/help-center-content-href.ts`. */
+const compose = makeComposeContentUrl({
+  hostedTypes: new Set(['onboarding_guide', 'product_release']),
+  contentOrigin: HUB,
+  suffixes: {
+    onboarding_guide: 'help-center/onboarding-guides',
+    product_release: 'help-center/releases',
+    blog_post: 'blog',
+    case_study: 'case-studies',
+  },
+  overrides: {
+    roadmap_item: (id) => ({
+      href: `/help-center/roadmap?search=${encodeURIComponent(id)}`,
+      targetPlatform: null,
+    }),
+  },
+})
+
+describe('resolveFetchedCardHref — Mingo cards with no ref metadata', () => {
+  it('override type deep-links on the MARKER id, not the fetched row id', () => {
+    // The `[card://roadmap_item:86ad3qvv5]` id is the ClickUp task id the
+    // roadmap list filters by; the fetched row carries its own db id.
+    expect(
+      resolveFetchedCardHref({
+        contentRefType: 'roadmap_item',
+        id: '86ad3qvv5',
+        item: { id: 'db-uuid-9', title: 'Deep Google Workspace tenant management' },
+        composeContentUrl: compose,
+      }),
+    ).toEqual({ href: '/help-center/roadmap?search=86ad3qvv5', targetPlatform: null })
+  })
+
+  it('hosted type uses the fetched row slug for its in-app detail route', () => {
+    expect(
+      resolveFetchedCardHref({
+        contentRefType: 'product_release',
+        id: 'row-uuid-1',
+        item: { id: 'row-uuid-1', slug: 'v1-2-0' },
+        composeContentUrl: compose,
+      }),
+    ).toEqual({ href: '/help-center/releases/v1-2-0', targetPlatform: null })
+  })
+
+  it('hosted type with no slug falls back to the marker id', () => {
+    expect(
+      resolveFetchedCardHref({
+        contentRefType: 'onboarding_guide',
+        id: 'guide-7',
+        item: { id: 'guide-7' },
+        composeContentUrl: compose,
+      }),
+    ).toEqual({ href: '/help-center/onboarding-guides/guide-7', targetPlatform: null })
+  })
+
+  it('non-hosted type resolves to the content hub', () => {
+    expect(
+      resolveFetchedCardHref({
+        contentRefType: 'case_study',
+        id: 'cs-1',
+        item: { id: 'cs-1', slug: 'acme-migration' },
+        composeContentUrl: compose,
+      }),
+    ).toEqual({ href: `${HUB}/case-studies/acme-migration`, targetPlatform: null })
+  })
+
+  it('legacy rail-vocab alias resolves to the SAME url as the canonical type', () => {
+    // The card registry keys blog entries by `blog_post_existing` (what
+    // `buildListUrl` wants). Both spellings must produce one url — the reported
+    // split was `/blog/what-is-mdr` vs `/blog_post_existing/bitwarden-…`.
+    const canonical = resolveFetchedCardHref({
+      contentRefType: 'blog_post',
+      id: 'p1',
+      item: { id: 'p1', slug: 'bitwarden-review-for-msps' },
+      composeContentUrl: compose,
+    })
+    const alias = resolveFetchedCardHref({
+      contentRefType: 'blog_post_existing',
+      id: 'p1',
+      item: { id: 'p1', slug: 'bitwarden-review-for-msps' },
+      composeContentUrl: compose,
+    })
+    expect(alias).toEqual(canonical)
+    expect(alias).toEqual({
+      href: `${HUB}/blog/bitwarden-review-for-msps`,
+      targetPlatform: null,
+    })
+  })
+
+  it('no seam wired → null (card stays unlinked, pre-existing behavior)', () => {
+    expect(
+      resolveFetchedCardHref({
+        contentRefType: 'roadmap_item',
+        id: '86ad3qvv5',
+        item: { id: '86ad3qvv5' },
+      }),
+    ).toBeNull()
+  })
+
+  it('guards a missing type / id / malformed item', () => {
+    expect(
+      resolveFetchedCardHref({ contentRefType: '', id: 'x', item: {}, composeContentUrl: compose }),
+    ).toBeNull()
+    expect(
+      resolveFetchedCardHref({
+        contentRefType: 'case_study',
+        id: '',
+        item: {},
+        composeContentUrl: compose,
+      }),
+    ).toBeNull()
+    // A non-object item (or a non-string slug) must not throw — it just loses
+    // the slug hint and falls back to the marker id.
+    expect(
+      resolveFetchedCardHref({
+        contentRefType: 'case_study',
+        id: 'cs-2',
+        item: { slug: 42 },
+        composeContentUrl: compose,
+      }),
+    ).toEqual({ href: `${HUB}/case-studies/cs-2`, targetPlatform: null })
+  })
+})
+
+describe('makeComposeContentUrl — the new `slug` hint', () => {
+  it('externalUrl still wins over the hint (SSE path unchanged)', () => {
+    expect(
+      compose({
+        type: 'product_release',
+        identifier: 'row-uuid-1',
+        slug: 'from-the-row',
+        externalUrl: `${HUB}/releases/from-the-url`,
+      }),
+    ).toEqual({ href: '/help-center/releases/from-the-url', targetPlatform: null })
+  })
+
+  it('applies to non-hosted types too — hub detail routes are slug-based', () => {
+    expect(compose({ type: 'blog_post', identifier: 'id-1', slug: 'hello-world' })).toEqual({
+      href: `${HUB}/blog/hello-world`,
+      targetPlatform: null,
+    })
+  })
+
+  it('no hint → identifier, unchanged for page-view and SSE callers', () => {
+    expect(compose({ type: 'blog_post', identifier: 'hello-world' })).toEqual({
+      href: `${HUB}/blog/hello-world`,
+      targetPlatform: null,
+    })
+  })
+})

package/src/components/chat/utils/discuss-ref-prompt.ts

@@ -0,0 +1,63 @@
+/**
+ * The ONE place the "Ask Mingo" (discuss) prompt for an inline entity card is
+ * composed — shared by every transport so the affordance reads identically
+ * wherever it is clicked.
+ *
+ * ## Why the two transports still differ underneath
+ *
+ * The prose is UX only. What narrows retrieval differs:
+ *
+ *   - **SSE / guide** — `sendMessage(prompt, { commandOverride: { entityIdFilter:
+ *     { tableId, id } } })`. Retrieval is strictly primary-key-driven; the
+ *     sentence is decoration.
+ *   - **Mingo / NATS** — the agent backend has no entity-id-filtered retrieval
+ *     (`ContextItemType` covers DEVICE / SCRIPT / TICKET / ORGANIZATION / USER /
+ *     KB_ARTICLE / POLICY / QUERY / SCHEDULED_SCRIPT — no content types), so the
+ *     prompt is ALL the agent gets. Hence `includeReference`, which appends the
+ *     type + id so the agent can still identify the exact row by text.
+ *
+ * When the backend grows an id-filter for the agent transport, the Mingo callers
+ * switch to it and drop `includeReference` — the prose stays put.
+ */
+
+import { sanitizeTitleForChat } from './slash-dispatch-utils'
+
+export interface DiscussPromptRef {
+  /** documentType, e.g. `'roadmap_item'`. */
+  type: string
+  /** Primary key — the id from the `[card://type:id]` marker. */
+  id: string
+  /** Display title. May be the bare id on a synthetic ref (Mingo). */
+  title?: string | null
+}
+
+export interface BuildDiscussPromptOptions {
+  /**
+   * Append `(<type> <id>)` so a transport WITHOUT structured entity filtering
+   * still points the agent at the exact row. Default `false` — the SSE path
+   * sends `entityIdFilter` and must keep the sentence clean.
+   */
+  includeReference?: boolean
+}
+
+/**
+ * `Tell me more about <title>` — plus `(<type> <id>)` when
+ * `includeReference` is set and the title alone is ambiguous.
+ *
+ * Falls back to `this item` when the ref has no usable title, matching the
+ * long-standing SSE behavior. A title that is just the id (the synthetic ref a
+ * Mingo `[card://…]` marker produces before its row loads) is treated as
+ * missing, so the prompt never degrades to `Tell me more about 86ad3qvv5`.
+ */
+export function buildDiscussPrompt(
+  reference: DiscussPromptRef,
+  options: BuildDiscussPromptOptions = {},
+): string {
+  const id = (reference.id ?? '').trim()
+  const rawTitle = (reference.title ?? '').trim()
+  const usableTitle = rawTitle && rawTitle !== id ? sanitizeTitleForChat(rawTitle) : ''
+  const prompt = `Tell me more about ${usableTitle || 'this item'}`
+  if (!options.includeReference || !id) return prompt
+  // Only worth the noise when the reference adds something the title doesn't.
+  return `${prompt} (${reference.type} ${id})`
+}

package/src/components/chat/utils/index.ts

@@ -196,4 +196,20 @@ export {
   resolveSourceIcon,
 } from './source-row-cta'
 
+// Post-fetch enrichment for the synthetic ChatRef a `[card://type:id]` marker
+// produces when the transport ships no refs metadata (Mingo/NATS).
+export {
+  resolveFetchedCardHref,
+  readFetchedCardTitle,
+  type FetchedCardHrefInput,
+} from './resolve-fetched-card-href'
+
+// The ONE "Ask Mingo" prompt builder — shared by the SSE adapter, the NATS
+// adapter, and hosts that inject their own Mingo state (openframe-frontend).
+export {
+  buildDiscussPrompt,
+  type DiscussPromptRef,
+  type BuildDiscussPromptOptions,
+} from './discuss-ref-prompt'
+
 export * from './scripted-stream'

package/src/components/chat/utils/resolve-fetched-card-href.ts

@@ -0,0 +1,104 @@
+/**
+ * Post-fetch href fallback for an inline chat card whose `ChatRef` carried no
+ * `externalUrl`.
+ *
+ * ## Why a fetch-mode card can arrive without a URL
+ *
+ * The two chat transports deliver entity references differently:
+ *
+ *   - **SSE / guide transport** — the server ships a `refs` metadata frame, so
+ *     each `[card://type:id]` marker expands into a FULL `ChatRef`
+ *     (`title` / `url` / `targetPlatform` / `sourceRepo`). `resolveSourceRowCTA`
+ *     then routes that `externalUrl` through the host's `composeContentUrl`
+ *     seam and the card is clickable.
+ *   - **Mingo / NATS transport** (`messageData: [{ type: 'GUIDE' | 'TEXT', text }]`)
+ *     — the body carries bare `[card://type:id]` markers and NOTHING else.
+ *     `chat-message-enhanced.tsx` synthesizes a minimal `{ type, id, title: id,
+ *     url: null }` ref so fetch-mode cards can still self-fetch their row, but
+ *     `resolveSourceRowCTA` has no `externalUrl`, no `path` and no
+ *     `targetPlatform` to work with → `href: null` → the card renders with its
+ *     real title and description but goes nowhere when clicked.
+ *
+ * This resolver closes that gap WITHOUT a second URL vocabulary: it calls the
+ * exact same `composeContentUrl` seam the page cards (`resolveContentHref`) and
+ * the SSE cards (`resolveSourceRowCTA`) use, so one host config —
+ * `hostedTypes` / `suffixes` / `overrides` — governs all three.
+ *
+ * `identifier` stays the marker's primary key (that is what `overrides` such as
+ * roadmap's `?search=<task id>` deep-link on); the row's `slug` rides the
+ * separate `slug` hint for hosted types whose detail route is slug-based.
+ *
+ * Pure — no React, no DOM. The caller owns `safeHref` validation.
+ */
+
+import type { ComposeContentUrl } from '../../../utils/content-href'
+import { canonicalContentRefType } from '../../../utils/list-url'
+
+export interface FetchedCardHrefInput {
+  /** Canonical `documentType` for the seam (registry `contentRefType`). */
+  contentRefType: string
+  /** The marker's primary key — `ChatRef.id`, NOT the fetched row's id. */
+  id: string
+  /** The row the card fetched. Shape is per-type and opaque here; only
+   *  `slug` and `platforms` are read, both defensively. */
+  item: unknown
+  /** Host seam. Absent (unwired runtime) → no fallback, same as today. */
+  composeContentUrl?: ComposeContentUrl
+}
+
+/** Read `item.slug` when it is a non-empty string. */
+function readSlug(item: unknown): string | null {
+  if (!item || typeof item !== 'object') return null
+  const slug = (item as { slug?: unknown }).slug
+  return typeof slug === 'string' && slug.trim() ? slug.trim() : null
+}
+
+/**
+ * Human title of a fetched row — `title`, else `name`, else null.
+ *
+ * A Mingo synthetic ref carries `title: <the marker id>` because that is all
+ * the transport shipped. Everything downstream that prints or sends the title
+ * (the "Ask Mingo" prompt, host renderers falling back to `ref.title`) would
+ * otherwise say `86ad3qvv5`. Once the row loads, this is the real title.
+ */
+export function readFetchedCardTitle(item: unknown): string | null {
+  if (!item || typeof item !== 'object') return null
+  for (const key of ['title', 'name'] as const) {
+    const value = (item as Record<string, unknown>)[key]
+    if (typeof value === 'string' && value.trim()) return value.trim()
+  }
+  return null
+}
+
+/** Read `item.platforms` when it is an array — the hub composer keys its
+ *  cross-platform topology off it; the embedder default ignores it. */
+function readPlatforms(item: unknown): Array<{ name?: string }> | undefined {
+  if (!item || typeof item !== 'object') return undefined
+  const platforms = (item as { platforms?: unknown }).platforms
+  return Array.isArray(platforms) ? (platforms as Array<{ name?: string }>) : undefined
+}
+
+/**
+ * Resolve `{href, targetPlatform}` for a freshly fetched card row, or `null`
+ * when the host wired no seam (the caller then keeps the card unlinked, which
+ * is the pre-existing behavior).
+ */
+export function resolveFetchedCardHref({
+  contentRefType,
+  id,
+  item,
+  composeContentUrl,
+}: FetchedCardHrefInput): { href: string; targetPlatform: string | null } | null {
+  if (!composeContentUrl || !contentRefType || !id) return null
+  return composeContentUrl({
+    // The card registry keys some entries by the legacy rail vocabulary
+    // (`blog_post_existing`) because that is what `buildListUrl` expects.
+    // The seam speaks the CANONICAL vocabulary — a host's `hostedTypes` /
+    // `overrides` are written against `blog_post`, so an un-aliased type
+    // misses them all and lands on `<origin>/blog_post_existing/<slug>`.
+    type: canonicalContentRefType(contentRefType),
+    identifier: id,
+    slug: readSlug(item),
+    platforms: readPlatforms(item),
+  })
+}

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

@@ -29,6 +29,7 @@ import { getBaseUrl } from '../../../utils/cn'
 import { safeHref } from './compact-card-classes'
 import type { ChatRef } from '../chat-ref.types'
 import type { ComposeContentUrl } from '../../../utils/content-href'
+import { canonicalContentRefType } from '../../../utils/list-url'
 
 /** Path sanitization — keep alphanumerics, slash, dash, dot, underscore;
  *  strip everything else. Defends against a hostile mapper returning a
@@ -233,7 +234,10 @@ export function resolveSourceRowCTA(
     // from the externalUrl) and everything else to the externalUrl verbatim —
     // the SAME resolver the page-view cards use, so chat + page links match.
     const composed = ctx.composeContentUrl({
-      type: row.documentType,
+      // Canonical vocabulary only — a rail-vocab alias would miss the host's
+      // `hostedTypes` / `overrides` and fall through to the seam's default
+      // `<origin>/<type>/<id>` branch. Same canonicalizer `buildListUrl` uses.
+      type: canonicalContentRefType(row.documentType),
       identifier: idValue,
       externalUrl: row.externalUrl,
       targetPlatform: row.targetPlatform ?? null,

package/src/components/shared/doc-search/__tests__/resolve-search-result-action.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from 'vitest'
+import { makeComposeContentUrl } from '../../../../utils/content-href'
+import type { SearchResult } from '../../../ui/search-input'
+import { resolveSearchResultAction } from '../resolve-search-result-action'
+
+const HUB = 'https://www.flamingo.run'
+
+/** A RAG row for a guide the hub owns, shaped like `mapDocSearchResults` emits. */
+const guideRow: SearchResult = {
+  id: 'onboarding-guides/deploy-first-device',
+  title: 'Deploy your first device',
+  path: 'onboarding-guides/deploy-first-device',
+  metadata: {
+    documentType: 'onboarding_guide',
+    externalUrl: `${HUB}/onboarding-guides/deploy-first-device`,
+    sourceRepo: 'onboarding-guides',
+    id: 'guide-123',
+    targetPlatform: 'openframe',
+  },
+}
+
+/** The OpenFrame Help Center seam: the two hosted types live under
+ *  `/help-center/...`, list-filter types deep-link with `?search=<id>`. */
+const helpCenterCompose = makeComposeContentUrl({
+  hostedTypes: new Set(['onboarding_guide', 'product_release']),
+  contentOrigin: HUB,
+  suffixes: {
+    onboarding_guide: 'help-center/onboarding-guides',
+    product_release: 'help-center/releases',
+    blog_post: 'blog',
+  },
+  overrides: {
+    delivery_item: (id) => ({ href: `/help-center/bug-fixes?search=${id}`, targetPlatform: null }),
+  },
+})
+
+describe('resolveSearchResultAction — composeContentUrl seam', () => {
+  it('no seam wired → the RAG externalUrl verbatim (legacy behavior)', () => {
+    expect(resolveSearchResultAction(guideRow, 'openframe')).toEqual({
+      kind: 'navigate-same-tab',
+      href: `${HUB}/onboarding-guides/deploy-first-device`,
+    })
+  })
+
+  it('hosted type → the host in-app route, slug recovered from externalUrl', () => {
+    expect(
+      resolveSearchResultAction(guideRow, 'openframe', 'host', helpCenterCompose),
+    ).toEqual({
+      kind: 'navigate-same-tab',
+      href: '/help-center/onboarding-guides/deploy-first-device',
+    })
+  })
+
+  it('relative composed href stays same-tab even in embed mode', () => {
+    // `decideNewTab` forces new-tab under embed; an in-app path must not be
+    // handed to window.open — the short-circuit runs before that decision.
+    expect(
+      resolveSearchResultAction(guideRow, 'openframe', 'embed', helpCenterCompose),
+    ).toEqual({
+      kind: 'navigate-same-tab',
+      href: '/help-center/onboarding-guides/deploy-first-device',
+    })
+  })
+
+  it('override type → the host deep-link, primary key as identifier', () => {
+    const row: SearchResult = {
+      id: 'delivery-1',
+      title: 'Fix the thing',
+      metadata: {
+        documentType: 'delivery_item',
+        externalUrl: `${HUB}/bug-fixes-and-enhancements?search=abc123`,
+        sourceRepo: 'clickup-delivery',
+        id: 'abc123',
+      },
+    }
+    expect(resolveSearchResultAction(row, 'openframe', 'host', helpCenterCompose)).toEqual({
+      kind: 'navigate-same-tab',
+      href: '/help-center/bug-fixes?search=abc123',
+    })
+  })
+
+  it('non-hosted type → the seam returns externalUrl verbatim, opens out', () => {
+    const row: SearchResult = {
+      id: 'blog-1',
+      title: 'Hello',
+      metadata: {
+        documentType: 'blog_post',
+        externalUrl: `${HUB}/blog/hello`,
+        sourceRepo: 'blog-posts',
+        id: 'blog-1',
+        targetPlatform: 'flamingo',
+      },
+    }
+    expect(resolveSearchResultAction(row, 'openframe', 'host', helpCenterCompose)).toEqual({
+      kind: 'navigate-new-tab',
+      href: `${HUB}/blog/hello`,
+    })
+  })
+
+  it('row without documentType → seam skipped, externalUrl verbatim', () => {
+    const row: SearchResult = {
+      id: 'x',
+      title: 'Untyped',
+      metadata: { externalUrl: `${HUB}/somewhere`, targetPlatform: 'openframe' },
+    }
+    expect(resolveSearchResultAction(row, 'openframe', 'host', helpCenterCompose)).toEqual({
+      kind: 'navigate-same-tab',
+      href: `${HUB}/somewhere`,
+    })
+  })
+
+  it('no externalUrl → unchanged ask-ai / route / noop fallbacks', () => {
+    expect(
+      resolveSearchResultAction(
+        {
+          id: 'cap-1',
+          title: 'Cap Table',
+          metadata: { documentType: 'cap_table', sourceRepo: 'financial-cap-table', id: 'row-9' },
+        },
+        'company-hub',
+        'host',
+        helpCenterCompose,
+      ),
+    ).toEqual({
+      kind: 'ask-ai',
+      detail: {
+        source: 'company-hub',
+        ref: { type: 'cap_table', id: 'row-9', title: 'Cap Table', url: null },
+      },
+    })
+
+    expect(
+      resolveSearchResultAction(
+        { id: 'doc', title: 'Doc', path: 'repo/architecture/api.md' },
+        'openframe',
+        'host',
+        helpCenterCompose,
+      ),
+    ).toEqual({ kind: 'route', path: 'repo/architecture/api.md' })
+
+    expect(
+      resolveSearchResultAction({ id: 'empty', title: 'Empty' }, 'openframe', 'host', helpCenterCompose),
+    ).toEqual({ kind: 'noop' })
+  })
+})