@flamingo-stack/openframe-frontend-core 0.0.579-1952.5335.1 → 0.0.579

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.579-1952.5335.1",
+  "version": "0.0.579",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",
@@ -350,9 +350,6 @@
     "@atlaskit/pragmatic-drag-and-drop": "^3.0.0",
     "@atlaskit/pragmatic-drag-and-drop-auto-scroll": "^3.0.1",
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "^2.1.0",
-    "@dnd-kit/core": "^6.3.1",
-    "@dnd-kit/sortable": "^10.0.0",
-    "@dnd-kit/utilities": "^3.2.2",
     "@eslint/js": "^9.39.0",
     "@floating-ui/react": "^0.27.15",
     "@headlessui/react": "^2.2.9",

package/src/chat-protocol/__tests__/__snapshots__/nats-decoder-golden.test.ts.snap

@@ -254,6 +254,86 @@ exports[`decodeNatsChunk — golden corpus > maps the full recorded corpus to no
     },
     "type": "tool-execution",
   },
+  "guide": {
+    "text": "## Enroll a device
+1. Open Settings",
+    "type": "guide-delta",
+  },
+  "guide_empty_string": {
+    "text": "",
+    "type": "guide-delta",
+  },
+  "guide_frame_approval_batch": {
+    "approvalType": "chat",
+    "origin": "guide",
+    "requestId": "batch:prop-1",
+    "status": "pending",
+    "toolCalls": [
+      {
+        "requiresApproval": true,
+        "toolCallArguments": null,
+        "toolExecutionRequestId": "prop-1",
+        "toolName": "create_ticket",
+        "toolTitle": "Open a ticket",
+      },
+    ],
+    "type": "approval-request",
+  },
+  "guide_frame_approval_request": {
+    "approvalType": "create_ticket",
+    "command": "Open a support ticket",
+    "fields": [
+      {
+        "label": "Subject",
+        "value": "Agent will not enroll",
+      },
+    ],
+    "origin": "guide",
+    "requestId": "prop-1",
+    "status": "pending",
+    "type": "approval-request",
+  },
+  "guide_frame_decision_resolved": {
+    "ok": true,
+    "origin": "guide",
+    "requestId": "prop-1",
+    "status": "approved",
+    "type": "approval-resolved",
+    "willAutoContinue": false,
+  },
+  "guide_frame_metadata": {
+    "conversationId": "conv-1",
+    "origin": "guide",
+    "type": "metadata",
+  },
+  "guide_frame_payload_array": null,
+  "guide_frame_payload_empty": null,
+  "guide_frame_payload_not_object": null,
+  "guide_frame_routing": null,
+  "guide_frame_status_thinking": null,
+  "guide_frame_text_leading": {
+    "text": "I'll look that up in the docs.",
+    "type": "guide-delta",
+  },
+  "guide_frame_text_wins": {
+    "text": "body",
+    "type": "guide-delta",
+  },
+  "guide_frame_thinking": {
+    "text": "The user asked about <policies> setup",
+    "type": "thinking-delta",
+  },
+  "guide_frame_tool_error": {
+    "title": "Could not reach HubSpot",
+    "type": "error",
+  },
+  "guide_frame_usage_start": null,
+  "guide_frame_with_seq": {
+    "seq": 77,
+    "text": "Checking the docs…",
+    "type": "guide-delta",
+  },
+  "guide_missing_text": null,
   "message_end": {
     "type": "turn-end",
   },

package/src/chat-protocol/__tests__/nats-decoder-golden.test.ts

@@ -11,7 +11,8 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { decodeNatsChunk } from '../nats-decoder';
+import type { ChatStreamEvent } from '../events';
+import { decodeNatsChunk, guideEventForNats } from '../nats-decoder';
 
 /** Recorded corpus of realistic NATS chunk shapes, keyed by scenario name. */
 const CORPUS: Record<string, unknown> = {
@@ -25,6 +26,73 @@ const CORPUS: Record<string, unknown> = {
   thinking: { type: 'THINKING', text: 'Considering options…' },
   thinking_missing_text: { type: 'THINKING' },
 
+  guide: { type: 'GUIDE', text: '## Enroll a device\n1. Open Settings' },
+  guide_empty_string: { type: 'GUIDE', text: '' },
+  guide_missing_text: { type: 'GUIDE' },
+
+  // GUIDE frames — hub frames the agent re-streams verbatim inside the same
+  // chunk type, under `payload`. They cross over by DEFAULT; only the dialog's
+  // own accounting and phase stop at the seam. See `guideEventForNats`.
+  guide_frame_text_leading: {
+    type: 'GUIDE',
+    payload: { kind: 'text-leading', text: "I'll look that up in the docs." },
+  },
+  guide_frame_thinking: {
+    type: 'GUIDE',
+    payload: { kind: 'thinking-delta', text: 'The user asked about <policies> setup' },
+  },
+  guide_frame_tool_error: {
+    type: 'GUIDE',
+    payload: { kind: 'tool_error', message: 'Could not reach HubSpot' },
+  },
+  // Dropped: would blank the model badge / relabel the turn with the hub's model.
+  guide_frame_routing: {
+    type: 'GUIDE',
+    payload: { kind: 'routing', routedComplexity: 'deep', routedModel: 'claude-x', routedThinkingBudget: 8000 },
+  },
+  guide_frame_metadata: {
+    type: 'GUIDE',
+    payload: { model: 'claude-x', modelLabel: 'Guide model', conversationId: 'conv-1' },
+  },
+  // Dropped: the dialog owns its own phase and token accounting.
+  guide_frame_status_thinking: { type: 'GUIDE', payload: { status: 'thinking' } },
+  guide_frame_usage_start: { type: 'GUIDE', payload: { kind: 'usage', stage: 'start', input_tokens: 12 } },
+  // Crosses over stamped `origin: 'guide'` — the marker that keeps the card
+  // inline and sends its buttons to the hub's confirm route.
+  guide_frame_approval_request: {
+    type: 'GUIDE',
+    payload: {
+      kind: 'approval_request',
+      proposalId: 'prop-1',
+      toolName: 'create_ticket',
+      title: 'Open a support ticket',
+      fields: [{ label: 'Subject', value: 'Agent will not enroll' }],
+    },
+  },
+  guide_frame_approval_batch: {
+    type: 'GUIDE',
+    payload: {
+      kind: 'approval_batch',
+      batchId: 'batch:prop-1',
+      proposals: [{ proposalId: 'prop-1', toolName: 'create_ticket', title: 'Open a ticket' }],
+    },
+  },
+  guide_frame_decision_resolved: {
+    type: 'GUIDE',
+    payload: { kind: 'decision_resolved', proposalId: 'prop-1', ok: true, action: 'approved', willAutoContinue: false },
+  },
+  // Malformed payloads degrade to a no-op, like every other chunk shape.
+  guide_frame_payload_not_object: { type: 'GUIDE', payload: 'text-leading' },
+  guide_frame_payload_array: { type: 'GUIDE', payload: [{ kind: 'text-leading', text: 'hi' }] },
+  guide_frame_payload_empty: { type: 'GUIDE', payload: {} },
+  // `text` wins when both are present — the body is what the agent persists.
+  guide_frame_text_wins: { type: 'GUIDE', text: 'body', payload: { kind: 'thinking-delta', text: 'ignored' } },
+  guide_frame_with_seq: {
+    type: 'GUIDE',
+    streamSeq: 77,
+    payload: { kind: 'text-leading', text: 'Checking the docs…' },
+  },
+
   // ASK — the guide-routing clarification card. `text` is the intro sentence
   // riding the same chunk; a card without a question or without usable options
   // is dropped (nothing the user could answer).
@@ -319,6 +387,55 @@ describe('decodeNatsChunk — golden corpus', () => {
   });
 });
 
+describe('guideEventForNats — the two kernels reconciled', () => {
+  // The property that matters for maintenance: `leading-frames` is the ONE
+  // place a hub frame kind is taught to the client, so an event kind that
+  // reaches this adapter must cross over WITHOUT an edit here. These use event
+  // types the frame table cannot produce today on purpose — they stand in for
+  // whatever the hub ships next.
+  it('passes an unfamiliar event through unchanged', () => {
+    const ask: ChatStreamEvent = {
+      type: 'ask',
+      question: 'Which workspace?',
+      options: [{ label: 'Acme' }],
+    };
+    expect(guideEventForNats(ask)).toEqual(ask);
+  });
+
+  it('stamps origin on the events that carry it, so the card routes to the hub', () => {
+    expect(
+      guideEventForNats({ type: 'approval-request', requestId: 'prop-1', approvalType: 'create_ticket' }),
+    ).toMatchObject({ approvalType: 'create_ticket', origin: 'guide' });
+    expect(guideEventForNats({ type: 'approval-resolved', requestId: 'prop-1', status: 'approved' })).toMatchObject({
+      origin: 'guide',
+    });
+  });
+
+  it('stops the events the agent owns for this dialog', () => {
+    expect(guideEventForNats({ type: 'usage', stage: 'start', input_tokens: 10 })).toBeNull();
+    expect(guideEventForNats({ type: 'status', phase: 'thinking' })).toBeNull();
+    expect(
+      guideEventForNats({
+        type: 'token-usage',
+        inputTokensSize: 1,
+        outputTokensSize: 2,
+        totalTokensSize: 3,
+        contextSize: 4,
+      }),
+    ).toBeNull();
+    expect(guideEventForNats({ type: 'dialog-closed' })).toBeNull();
+  });
+
+  it('keeps metadata only for the hub conversation id every confirm must quote back', () => {
+    expect(guideEventForNats({ type: 'metadata', conversationId: 'conv-1', modelName: 'hub-model' })).toEqual({
+      type: 'metadata',
+      conversationId: 'conv-1',
+      origin: 'guide',
+    });
+    expect(guideEventForNats({ type: 'metadata', modelName: 'hub-model' })).toBeNull();
+  });
+});
+
 describe('decodeNatsChunk — seq envelope', () => {
   it('lifts a numeric JetStream `streamSeq` into `seq`, and omits it otherwise (snapshot)', () => {
     expect({

package/src/chat-protocol/decode.ts

@@ -36,9 +36,10 @@
 import type { ChatStreamEvent } from './events';
 import type { UsageTelemetry } from './frames';
 import { FRAME_TERMINATOR, END_OF_LEADING, TRAILER_SENTINEL } from './frames';
-// The frame table lives in its own module so it is reusable outside this
-// decoder. `frameNum` comes from there too: the trailing usage frame's token
-// counts must pass the SAME typeof gate the leading `usage:start` frame's do.
+// The frame table is SHARED with the NATS decoder — guide answers re-stream the
+// hub's frames verbatim inside `GUIDE` chunks — so it lives in its own module.
+// `frameNum` comes from there too: the trailing usage frame's token counts must
+// pass the SAME typeof gate the leading `usage:start` frame's already do.
 import { mapLeadingFrame, frameNum } from './leading-frames';
 
 export interface SseFrameDecoder {

package/src/chat-protocol/events.ts

@@ -54,6 +54,18 @@ export interface ThinkingDeltaEvent extends ChatStreamEventBase {
   text: string;
 }
 
+/** Guide-body delta (NATS `GUIDE` chunk) — the assistant's how-to /
+ *  documentation answer, rendered as a titled "OpenFrame Guide" card rather
+ *  than bare prose. Same APPEND-ONLY contract as `text-delta` /
+ *  `thinking-delta`: each event carries the next verbatim slice and consumers
+ *  coalesce into the trailing `guide` segment. NATS-only today — the SSE
+ *  frame grammar has no guide frame — but it lives in the shared union
+ *  because the reducer is transport-agnostic. */
+export interface GuideDeltaEvent extends ChatStreamEventBase {
+  type: 'guide-delta';
+  text: string;
+}
+
 /** Clarification card (NATS `ASK` chunk) — the assistant asking which reading
  *  of an ambiguous question to answer. NOT a delta: the chunk carries the
  *  finished card, so consumers push it whole instead of coalescing. `text` is
@@ -122,6 +134,35 @@ export interface ApprovalRequestEvent extends ChatStreamEventBase {
   fields?: ApprovalRequestField[];
   toolCalls?: ApprovalToolCall[];
   status?: 'pending';
+  /** Set when the card came from a Product Guide frame — see {@link GuideOrigin}. */
+  origin?: GuideOrigin;
+}
+
+/**
+ * Marks an event whose payload is a Product Guide frame, whatever transport
+ * carried it. It exists because ONE stream can now mix both worlds: the agent
+ * re-streams the hub's frames into a NATS dialog, so a card typed the hub's way
+ * (`approvalType` = the tool name, resolved through the hub's confirm route)
+ * travels beside cards typed the agent's way (`approvalType` = an approval TIER
+ * routed to human escalation).
+ *
+ * Consumers read it to keep the guide half behaving exactly as it does in the
+ * hub's own chat — NOT to give it special treatment. Without it the NATS kernel
+ * would have to guess from `approvalType`, and every tool the hub adds would
+ * silently fall into the escalation path.
+ */
+export type GuideOrigin = 'guide';
+
+/** The only value of {@link GuideOrigin}. Lives beside the type, and beside the
+ *  predicate below, because both decoders and every consumer that branches on
+ *  provenance must compare against the same token — a bare `'guide'` literal
+ *  typo silently disables the branch instead of failing to compile. */
+export const GUIDE_ORIGIN: GuideOrigin = 'guide';
+
+/** True for anything stamped as coming from the Product Guide — a stream event
+ *  or the `data` of a segment built from one. */
+export function isGuideOrigin(source: { origin?: GuideOrigin | string } | null | undefined): boolean {
+  return source?.origin === GUIDE_ORIGIN;
 }
 
 /** An approval request was resolved (SSE `decision_resolved` frame /
@@ -137,6 +178,8 @@ export interface ApprovalResolvedEvent extends ChatStreamEventBase {
   receiptText?: string;
   result?: DecisionResolvedFrame['result'];
   willAutoContinue?: boolean;
+  /** Set when the resolution came from a Product Guide frame — see {@link GuideOrigin}. */
+  origin?: GuideOrigin;
 }
 
 /** The client is offered a handoff of this ticket to a human technician
@@ -238,6 +281,13 @@ export interface ChatMetadataEvent extends ChatStreamEventBase {
     routedModel?: string;
     routedThinkingBudget: number | null;
   };
+  /**
+   * Set when the metadata came from a Product Guide frame — see
+   * {@link GuideOrigin}. Such an event carries ONLY `conversationId`: it exists
+   * to record the hub's conversation id (every confirm-tool call must quote it
+   * back), NOT to describe the dialog's model, which stays the agent's.
+   */
+  origin?: GuideOrigin;
 }
 
 /** SSE usage frames — raw wire keys (snake_case) preserved. */
@@ -352,6 +402,7 @@ export type ChatStreamEvent =
   | TurnEndEvent
   | TextDeltaEvent
   | ThinkingDeltaEvent
+  | GuideDeltaEvent
   | AskEvent
   | StatusEvent
   | ToolExecutionEvent

package/src/chat-protocol/leading-frames.ts

@@ -2,9 +2,15 @@
  * Leading-frame → `ChatStreamEvent` table — the ONE mapping both transports read.
  *
  * The SSE decoder (`./decode.ts`) reaches it while walking the hub's byte
- * framing. It lives outside that decoder so a second transport can reuse the
- * table rather than re-implement it and drift the moment the hub adds a frame
- * kind.
+ * framing. The NATS decoder (`./nats-decoder.ts`) reaches it for `GUIDE` chunks
+ * carrying a `payload`: the saas-ai-agent re-streams the Product Guide's hub
+ * frames VERBATIM into the Mingo chunk stream (`GuideStreamingService`), so the
+ * bytes a guide answer is made of are the same frames on both transports — only
+ * the envelope differs. Decoding them twice would drift the moment the hub adds
+ * a frame kind, which is why this table lives outside either decoder.
+ *
+ * The NATS side does NOT take every event this table can produce; see
+ * `guideFrameEvent` in `./nats-decoder.ts` for which ones cross over and why.
  *
  * Server-safe: no React, no browser APIs.
  */

package/src/chat-protocol/nats-decoder.ts

@@ -18,8 +18,9 @@
 
 import { MESSAGE_TYPE } from '../components/chat/types/message.types';
 import type { AskOptionData } from '../components/chat/types/message.types';
-import { ESCALATION_STATE, escalationResolvedStatus } from './events';
+import { ESCALATION_STATE, GUIDE_ORIGIN, escalationResolvedStatus } from './events';
 import type { ApprovalToolCall, ChatStreamEvent } from './events';
+import { escapeThinkingTags, mapLeadingFrame } from './leading-frames';
 
 /** Minimal structural view of a NATS chunk (see `ChunkData` in
  *  `src/components/chat/types/network.types.ts`). */
@@ -47,6 +48,11 @@ function numOr(value: unknown, fallback = 0): number {
   return typeof value === 'number' ? value : fallback;
 }
 
+// `GUIDE_ORIGIN` moved to `./events`, beside the `GuideOrigin` type it is the
+// only value of — the SSE half reads it too, so it never belonged to the NATS
+// decoder. Re-exported here because that is the import path consumers know.
+export { GUIDE_ORIGIN } from './events';
+
 /** Coerce the wire's `toolCalls[]` into the batch-approval shape, dropping
  *  non-object entries and defaulting every field. */
 function normalizeToolCalls(raw: unknown): ApprovalToolCall[] {
@@ -77,6 +83,94 @@ export function normalizeAskOptions(raw: unknown): AskOptionData[] {
     .filter(option => option.label.length > 0);
 }
 
+/**
+ * Events whose meaning belongs to the AGENT's dialog rather than to the guide
+ * turn embedded inside it. The hub emits its own copies of these, and the Mingo
+ * dialog already has authoritative ones: letting the hub's through would
+ * double-count the dialog's tokens or fight the agent's own phase chunks.
+ *
+ * Note this is a DENYLIST, and that is the point. `./leading-frames` is the ONE
+ * place a hub frame kind is taught to the client; whatever it learns to emit —
+ * including kinds that do not exist yet — must reach a Mingo dialog without a
+ * second edit here. An allowlist would silently swallow every card the hub adds
+ * next, and the guide half would quietly lag the guide chat.
+ */
+const AGENT_OWNED_EVENTS: ReadonlySet<ChatStreamEvent['type']> = new Set([
+  'usage',
+  'token-usage',
+  'status',
+  'compaction',
+  'participant',
+  'dialog-closed',
+]);
+
+/** Event types that declare `origin` (see `GuideOrigin`). Data rather than a
+ *  branch per type, so a future hub card opts in by adding the field to its
+ *  interface and its name here — the pass-through below needs no edit. */
+const ORIGIN_BEARING_EVENTS: ReadonlySet<ChatStreamEvent['type']> = new Set(['approval-request', 'approval-resolved']);
+
+/**
+ * Adapt ONE Product Guide event to the NATS kernel.
+ *
+ * The guide half of a Mingo dialog is the hub's own stream, so it is decoded by
+ * the shared table in `./leading-frames` and then passed through here — the ONE
+ * place that reconciles the two kernels. Both entry points use it: frames
+ * re-streamed by the agent inside `GUIDE` chunks, and the SSE response of the
+ * hub's confirm-tool route, which a host replays into the same dialog.
+ *
+ * Pass-through is the DEFAULT; only these rules alter an event, and each exists
+ * because the two kernels genuinely disagree:
+ *
+ *   - `text-delta` becomes `guide-delta`: the body of a guide turn belongs
+ *     inside the "OpenFrame Guide" card, and a `text` segment would strand part
+ *     of the same answer outside it.
+ *   - thinking is escaped HERE. The SSE kernel escapes `<` on the way in, the
+ *     NATS kernel does not, and the guide's thinking is full of XML-ish tokens
+ *     that would otherwise render as markup.
+ *   - `metadata` survives ONLY to carry `conversationId`, which the hub mints
+ *     and every confirm-tool call must quote back. Everything else on that
+ *     frame (the hub's model, routing) is dropped: `applyNats` rebuilds the
+ *     dialog's live model from a metadata event, so letting it through would
+ *     relabel a Mingo turn with the hub's model, and a routing frame — which
+ *     carries no model at all — would blank the badge mid-answer.
+ *   - dialog-level events stop here (`AGENT_OWNED_EVENTS`).
+ *
+ * Everything else crosses over as the hub typed it, gaining only `origin`.
+ * `approvalType` in particular stays the TOOL NAME, exactly as in the hub's own
+ * chat: the NATS kernel gates approvals on approval TIER and escalates the rest,
+ * which is an agent-side concept a hub proposal has no tier for. Rewriting the
+ * tool name into a fake tier to slip past that gate would make the guide half of
+ * the stream diverge from the guide chat itself.
+ */
+export function guideEventForNats(event: ChatStreamEvent): ChatStreamEvent | null {
+  switch (event.type) {
+    case 'text-delta':
+      return { type: 'guide-delta', text: event.text };
+    case 'thinking-delta':
+      return { type: 'thinking-delta', text: escapeThinkingTags(event.text) };
+    case 'metadata':
+      return typeof event.conversationId === 'string' && event.conversationId
+        ? { type: 'metadata', conversationId: event.conversationId, origin: GUIDE_ORIGIN }
+        : null;
+    default:
+      if (AGENT_OWNED_EVENTS.has(event.type)) return null;
+      return ORIGIN_BEARING_EVENTS.has(event.type) ? ({ ...event, origin: GUIDE_ORIGIN } as ChatStreamEvent) : event;
+  }
+}
+
+/**
+ * Decode one re-streamed Product Guide frame (a `GUIDE` chunk's `payload`) into
+ * a NATS event. The frame grammar is decoded by the shared table, never by a
+ * second copy here; the kernel reconciliation is `guideEventForNats`.
+ */
+export function guideFrameEvent(frame: Record<string, unknown>): ChatStreamEvent | null {
+  const events: ChatStreamEvent[] = [];
+  // Every branch of the table pushes at most one event, so the first is the one.
+  mapLeadingFrame(frame, events);
+  const event = events[0];
+  return event ? guideEventForNats(event) : null;
+}
+
 /**
  * Parse one raw NATS chunk into a normalized event. Returns `null` for
  * unknown/malformed chunks — an unrecognized `type`, a missing required
@@ -125,6 +219,21 @@ export function decodeNatsChunk(chunk: unknown): ChatStreamEvent | null {
       }
       return null;
 
+    // Two shapes share this chunk type. `text` is the answer body the agent
+    // streams (and persists). `payload` is a Product Guide frame re-streamed
+    // verbatim from the hub — decoded through the shared frame table, with the
+    // narrowing `guideFrameEvent` documents.
+    case MESSAGE_TYPE.GUIDE: {
+      if (typeof data.text === 'string') {
+        return { type: 'guide-delta', text: data.text, ...seq };
+      }
+      const frame = data.payload;
+      if (!frame || typeof frame !== 'object' || Array.isArray(frame)) return null;
+      const event = guideFrameEvent(frame as Record<string, unknown>);
+      if (!event) return null;
+      return { ...event, ...seq };
+    }
+
     // An ask card is only an ask card with something to pick: a question and at
     // least one option. Anything less is dropped rather than rendered as an
     // empty card the user can't answer — the backend already falls back to a

package/src/components/chat/__tests__/chat-pending-turn.test.tsx

@@ -203,6 +203,25 @@ describe('a thinking turn has exactly ONE pending affordance', () => {
     expect(names()).toEqual(['Michael Assraf', 'Mingo']);
   });
 
+  it('renders the assistant row when it carries ONLY a guide segment', () => {
+    // A `guide` body is the whole visible answer for a how-to question. If
+    // the empty-pending-turn predicate ever counted it as "nothing visible"
+    // (e.g. by widening its text-only clause), a guide-only turn would render
+    // NOTHING until the turn ended — the footer loader would be the sole
+    // affordance while a fully-formed guide card sat in state.
+    const withGuide: Message[] = [
+      pending[0],
+      {
+        id: 'a1',
+        role: 'assistant',
+        name: 'Mingo',
+        content: [{ type: 'guide', text: '## Enroll a device' }],
+      },
+    ];
+    render(<ChatMessageList dialogId="d" messages={withGuide} isTyping />);
+    expect(names()).toEqual(['Michael Assraf', 'Mingo']);
+  });
+
   it('renders a completed empty-ish assistant row when NOT typing', () => {
     render(<ChatMessageList dialogId="d" messages={pending} />);
     expect(names()).toEqual(['Michael Assraf', 'Mingo']);

package/src/components/chat/chat-message-enhanced.tsx

@@ -16,6 +16,7 @@ import { ContextCompactionDisplay } from './context-compaction-display';
 import { BlockCard, type BlockCardProps } from './entity-cards/block-card';
 import { ErrorMessageDisplay } from './error-message-display';
 import { EscalationOfferMessage } from './escalation-offer-message';
+import { GuideDisplay } from './guide-display';
 import { remarkCardLinks } from './remark-card-links';
 import { remarkMentionChips } from './remark-mention-chips';
 import { remarkStripCitations } from './remark-strip-citations';
@@ -225,7 +226,12 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
       // duplicates so two siblings never collide on the same React key.
       const emittedBlockKeys = new Set<string>();
       segments.forEach((segment, segIdx) => {
-        if (segment.type !== 'text') return;
+        // Both markdown-bearing segment types take part: a `guide` body is
+        // authored by the same LLM and carries the same `[card://]` markers,
+        // so skipping it here left its markers with no `inlineByKey` entry and
+        // no hoisted card — the `<a card://>` override silently degraded them
+        // to a bare title / id.
+        if (segment.type !== 'text' && segment.type !== 'guide') return;
         const text = segment.text;
         const parts: SegmentPart[] = [];
         let cursor = 0;
@@ -602,6 +608,12 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
                       {renderSegmentBody(index, segment.text, segmentIsStreaming)}
                     </div>
                   );
+                } else if (segment.type === 'guide') {
+                  return (
+                    <GuideDisplay key={index}>
+                      {renderSegmentBody(index, segment.text, segmentIsStreaming)}
+                    </GuideDisplay>
+                  );
                 } else if (segment.type === 'ask') {
                   // Only the run's head draws — the tail segments are pages of
                   // the card already rendered above them.

package/src/components/chat/guide-display.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import { forwardRef } from 'react';
+
+import { cn } from '../../utils/cn';
+import { CompassIcon } from '../icons-v2-generated';
+import type { GuideDisplayProps } from './types';
+
+const GUIDE_LABEL = 'OpenFrame Guide';
+
+/**
+ * `GUIDE` segment — the assistant's how-to/documentation answer, framed as a
+ * titled card instead of a bare paragraph.
+ *
+ * Chrome only: the caller renders the markdown body and passes it as children,
+ * so a guide goes through the SAME body pipeline as a text segment
+ * (`[card://]` splitting + hoisted entity cards + mention chips). Rendering the
+ * raw markdown here instead would bypass that plan and degrade every card
+ * marker inside a guide to a bare title.
+ */
+const GuideDisplay = forwardRef<HTMLDivElement, GuideDisplayProps>(({ className, children, ...props }, ref) => {
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        'flex flex-col gap-[var(--spacing-system-m)] rounded-md border border-ods-border bg-ods-card p-[var(--spacing-system-m)]',
+        className,
+      )}
+      {...props}
+    >
+      <div className="flex items-center gap-[var(--spacing-system-xs)]">
+        <CompassIcon size={16} className="shrink-0 text-ods-open-yellow" />
+        <span className="text-ods-open-yellow text-h5">{GUIDE_LABEL}</span>
+      </div>
+      <div className="w-full min-w-0 break-words text-ods-text-primary text-h4">{children}</div>
+    </div>
+  );
+});
+
+GuideDisplay.displayName = 'GuideDisplay';
+
+export { GuideDisplay };

package/src/components/chat/index.ts

@@ -10,6 +10,7 @@ export * from './ai-assistant-info';
 export * from './context-compaction-display';
 export * from './expand-chevron';
 export * from './thinking-display';
+export * from './guide-display';
 export * from './ask-display';
 export * from './error-message-display';
 export * from './chat-container';