@cms.ai/brand_brain 0.0.1 → 0.1.0

package/llms.txt

@@ -0,0 +1,115 @@
+# @cms.ai/brand_brain
+
+> Client-side SDK for building CMS.ai Brand Brain (Guide) chat experiences into your own UI. Streaming chat over SSE with structured "skill" deliverables (documents, recommendations, how-tos, playlists, business cases, solution designs, self-assessments), visitor identity, consent, analytics, and email lead capture. Framework-agnostic core + React binding at `@cms.ai/brand_brain/react`. All types below are exported from the package root.
+
+## Setup
+
+```ts
+import { initGuide } from "@cms.ai/brand_brain";
+const guide = await initGuide({ baseUrl: "https://guide.customer.com", slug: "default" });
+```
+
+- `baseUrl`: the customer's branded CMS.ai host. Same-site with the page = full visitor identity. Cross-site (e.g. app on `*.lovable.app`, guide on `*.guides.navless.ai`) still works, but Safari drops the visitor cookies — treat the visitor as anonymous per page load and depend on nothing persisting across visits.
+- `InitGuideConfig`: `{ baseUrl: string; slug: string; domain?: string; consent?: "auto" | { functional?: boolean; analytical?: boolean } | false; trackLoad?: boolean; fetch?: typeof fetch }`.
+
+## React binding (preferred for React apps)
+
+```tsx
+import { useGuide } from "@cms.ai/brand_brain/react";
+const { client, guide, messages, skillTurn, gate, isReady, isStreaming, error, ask, submitGate, retryLastAsk, reset } =
+  useGuide({ baseUrl, slug: "default", onEvent: (e) => {} });
+```
+
+- `messages: { id, role: "user" | "assistant", content: string }[]` — render as chat bubbles; assistant content streams in.
+- `skillTurn: GuideSkillTurn | null` — structured deliverable of the current turn (see below).
+- `gate: { skill, prompt?, skillInstanceId? } | null` — when non-null, render an email form; `await submitGate(email)`; if `!result.needsVerification`, `await retryLastAsk()`.
+- `ask(message, { forcedSkill?, signal? })` — send a message. Disable input while `isStreaming`.
+- Guide branding: `guide.theme`, `guide.logoUrl`, `guide.companyName`, `guide.customization?.welcomeMessage`, `guide.customization?.chatInputPlaceholders`.
+
+## Event stream contract (`client.ask()` yields `GuideStreamEvent`)
+
+```
+{ type: "run-started"; runId }
+{ type: "message-start"; messageId; role }
+{ type: "text"; messageId; delta }                    // chat reply token chunk
+{ type: "message-end"; messageId }
+{ type: "skill"; name; value }                        // discriminated on `name`, payloads below
+{ type: "skill-unknown"; name; value }                // newer server event; safe to ignore
+{ type: "gate"; skill; prompt?; skillInstanceId? }    // email required; stream ends after this
+{ type: "error"; message; code?; retryable?; retryHint?: { prompt; forcedSkill? } }
+{ type: "run-finished"; finishReason? }
+```
+
+Skill event payloads (`value` per `name`); every turn runs one skill bracketed by `skill_start` … `skill_end`:
+
+```
+skill_start                { skill: SkillResponseTypeType; messageId: string; diagnoseSubtype?: "standalone" | "context_gathering"; followUpSkill?: string }
+skill_content              { delta: string }                                     // markdown chunk of long-form body
+skill_documents            { documents: GuideDocument[] }                        // replace, don't append
+skill_recommendations      { recommendations: ContentRecommendation[] | SkillRecommendation[] }  // ContentRecommendation has `targetSkill`; SkillRecommendation has `skill`
+skill_ctas                 { ctas: SkillCTA[] }                                  // render only the first
+skill_diagnose_header      { header: DiagnosticHeader }
+skill_diagnose_question    { question: DiagnosticQuestion }                      // append; arrives one per event
+skill_playlist_header      { header: { title: string; description: string } }
+skill_playlist_items       { items: PlaylistItem[] }                             // replace
+skill_playlist_rationale   { itemId: string; rationale: string }                 // late patch to one item
+skill_howto_outline        { outline: { title: string; steps: { id: string; title: string }[] }; skillInstanceId?: string }
+skill_howto_steps          { steps: HowToStep[] }                                // replaces outline detail
+skill_businesscase_chooser { formats: { subType: string; label: string; description: string; icon: string }[]; drafts: Record<string, { draftId: string; skillInstanceId: string }> }
+skill_businesscase_delta   { subType: "roi-analysis" | "stakeholder-brief" | "vendor-comparison"; delta: string }  // append per subType
+skill_solutiondesign_header  { header: { title: string; summary: string } }
+skill_solutiondesign_diagram { nodes: SolutionDesignNode[]; edges: { id: string; source: string; target: string; label?: string }[] }
+skill_end                  { skillInstanceId?: string }                          // persisted deliverable id
+```
+
+Key payload types:
+
+```ts
+type SkillResponseTypeType = "answer" | "howto" | "diagnose" | "recommend" | "playlist" | "businesscase" | "solutiondesign";
+interface GuideDocument { id: string; title: string; tag?: string; icon?: string; url?: string; contentType?: string; body?: string; thumbnailUrl?: string; citationIndex?: number } // citationIndex matches [N] in reply text
+interface SkillRecommendation { id: string; skill: SkillResponseTypeType; label: string; prompt: string }                       // pill → ask(prompt, { forcedSkill: skill })
+interface ContentRecommendation { id: string; targetSkill: string; title: string; rationale: string; prompt: string; confidence: "high" | "medium" | "low" } // card → ask(prompt, { forcedSkill: targetSkill })
+type SkillCTA = { kind: "url"; label; href; bannerText?; ... } | { kind: "form"; label; formId; ... } | { kind: "product"; label; href; productId; ... } | { kind: "scheduler"; label; url; provider: "hubspot" | "calendly"; ... };
+interface DiagnosticHeader { targetTopic: string; subtitle: string; questionCount: number; subtype?: "standalone" | "context_gathering"; followUpSkill?: string }
+interface DiagnosticQuestion { id: string; category: string; questionText: string; options: { label: "A" | "B" | "C" | "D"; text: string; score?: number }[]; prerequisiteConceptId: string | null; prerequisiteConceptName: string | null } // single-choice self-assessment, no correct answer
+interface HowToStep { id: string; title: string; description: string; icon?: string; content: { contentId: string; title: string; url: string | null; excerpt: string; thumbnailUrl?: string } | null }
+interface PlaylistItem { id: string; title: string; description: string | null; contentType: string; url: string | null; thumbnailUrl?: string; rationale?: string }
+interface SolutionDesignNode { id: string; label: string; description: string; nodeType: "process" | "decision" | "datastore" | "external" | "trigger" | "start" | "end"; icon: string } // icon = Lucide name
+```
+
+## GuideSkillTurn (pre-reduced render state)
+
+`useGuide().skillTurn`, or fold manually: `turn = reduceSkillEvent(turn ?? createSkillTurn(), event)` for `event.type === "skill"`.
+
+```ts
+interface GuideSkillTurn {
+  skill: SkillResponseTypeType | null; status: "streaming" | "complete"; messageId: string | null;
+  diagnoseSubtype: "standalone" | "context_gathering" | null; followUpSkill: string | null;
+  content: string;                                           // accumulated markdown body
+  documents: GuideDocument[];                                // answer: source/citation cards
+  contentRecommendations: ContentRecommendation[];           // recommend: cards
+  followUpRecommendations: SkillRecommendation[];            // answer: follow-up pills
+  ctas: SkillCTA[];                                          // render first only, below response
+  diagnoseHeader: DiagnosticHeader | null; diagnoseQuestions: DiagnosticQuestion[];  // stepper UI
+  playlistHeader: { title; description } | null; playlistItems: PlaylistItem[];      // content cards
+  howToOutline: { title; steps: { id; title }[] } | null; howToSteps: HowToStep[];   // numbered steps; outline renders first as skeleton
+  businessCaseFormats: ...[]; businessCaseDrafts: Record<string, ...>;               // format chooser cards
+  businessCaseContent: Record<string, string>;               // per-subType markdown, render as it streams
+  solutionDesignHeader: { title; summary } | null; solutionDesignNodes: SolutionDesignNode[]; solutionDesignEdges: ...[];  // flowchart
+  skillInstanceId: string | null;                            // for client.skills.get/update
+}
+```
+
+UI guidance per skill: `answer` → streamed text + source cards + follow-up pills; `howto` → numbered step checklist (outline first, details replace); `recommend` → recommendation cards with confidence badge; `playlist` → media/content card list; `diagnose` → one-question-at-a-time stepper (self-assessment, no correct answers; standalone mode ⇒ score results per category at the end); `businesscase` → format chooser, then streamed markdown document per chosen format (send the chosen format's label as the next ask); `solutiondesign` → flowchart of nodes/edges (or grouped node list fallback).
+
+## Email gate
+
+A `gate` event means the guide requires an email to finish the turn (the stream ends). Flow: collect email → `submitGate(email)` (gate context auto-attached in the hook) → if `needsVerification` tell the user to check their inbox, else `retryLastAsk()`.
+
+## Theming
+
+`guide.theme` (`BrandKitTheme`) = optional CSS color strings (hex/oklch), shadcn-style tokens: `primary`, `primaryForeground`, `secondary`, `secondaryForeground`, `background`, `foreground`, `muted`, `mutedForeground`, `border`, `input`, `ring`. Map onto your CSS variables/Tailwind theme. Also: `guide.logoUrl`, `guide.faviconUrl`, `guide.heroImageUrl`, `guide.customization` (copy overrides: `welcomeMessage`, `chatInputPlaceholders`, `suggestionsTitle`, …), `guide.skillIconStyle`.
+
+## GuideClient API
+
+`guide` (ResolvedGuide) · `ask(message, { forcedSkill?, signal? })` · `messages` / `reset()` · `setConsent({ functional?, analytical? })` / `getStatus()` · `submitGate(email, options?)` · `track(eventType, properties?)` / `trackPageView(url?)` (call on SPA route changes) · `endSession()` (call on pagehide; the hook handles it) · `conversations.getOrCreate()/list()/get(id)/delete(id)` · `skills.listHistory()/get(id)/update(id, data)/selectDraft(id)/markShared(id)/importShared(id)`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cms.ai/brand_brain",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "license": "MIT",
   "description": "Client-side SDK for building CMS.ai Brand Brain (Guide) experiences into your own website UI.",
   "type": "module",
@@ -12,7 +12,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "llms.txt"
   ],
   "main": "./dist/index.cjs",
   "types": "./dist/index.d.cts",
@@ -65,10 +66,10 @@
     "react-dom": "^19",
     "typescript": "^5.9",
     "vitest": "^4.1.6",
-    "@navless/eslint-config": "0.0.1",
     "@navless/orpc": "0.0.19",
-    "@navless/typescript-config": "0.0.1",
-    "@navless/types": "0.0.34"
+    "@navless/eslint-config": "0.0.1",
+    "@navless/types": "0.0.34",
+    "@navless/typescript-config": "0.0.1"
   },
   "scripts": {
     "build": "tsdown",

package/src/GuideClient.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { hostnameFromBaseUrl } from "./GuideClient";
+
+describe("hostnameFromBaseUrl", () => {
+  it("returns the bare host from a branded origin", () => {
+    expect(hostnameFromBaseUrl("https://guide.acme.com")).toBe("guide.acme.com");
+  });
+
+  it("ignores the appended /api/v3 path", () => {
+    expect(hostnameFromBaseUrl("https://guide.acme.com/api/v3")).toBe("guide.acme.com");
+  });
+
+  it("strips a leading www. so it matches the stored domain", () => {
+    expect(hostnameFromBaseUrl("https://www.acme.com")).toBe("acme.com");
+  });
+
+  it("drops the port", () => {
+    expect(hostnameFromBaseUrl("http://localhost:3000")).toBe("localhost");
+  });
+
+  it("lowercases the host", () => {
+    expect(hostnameFromBaseUrl("https://Guide.Acme.com")).toBe("guide.acme.com");
+  });
+
+  it("accepts a bare host without a protocol", () => {
+    expect(hostnameFromBaseUrl("guide.acme.com")).toBe("guide.acme.com");
+  });
+});

package/src/GuideClient.ts

@@ -43,10 +43,27 @@ interface SkillsApi {
   importShared(sourceSkillInstanceId: string): Promise<ImportSharedResult>;
 }
 
+/**
+ * The account is resolved by the branded host the SDK talks to, and that host
+ * must be same-site with `baseUrl` for the visitor cookies to attach — so the
+ * `baseUrl` hostname IS the registered account domain. Derive it from there
+ * rather than the host page's `window.location`, which is an unrelated origin
+ * for cross-site embeds and produces a "Domain not found" 404 on resolve.
+ */
 function resolveDomain(config: InitGuideConfig): string {
   if (config.domain) return config.domain;
-  if (typeof window !== "undefined") return window.location.hostname;
-  throw new Error("[brand_brain] `domain` is required when running without a browser `window`.");
+  return hostnameFromBaseUrl(config.baseUrl);
+}
+
+/**
+ * Normalize `baseUrl` to the bare host the server stores: lowercased, no port,
+ * no leading `www.` (the domain write-path strips it, so a `www.` host can
+ * never match). Accepts a bare host too, in case `baseUrl` omits the protocol.
+ */
+export function hostnameFromBaseUrl(baseUrl: string): string {
+  const withProtocol = /^[a-z][a-z0-9+.-]*:\/\//i.test(baseUrl) ? baseUrl : `https://${baseUrl}`;
+  const hostname = new URL(withProtocol).hostname.toLowerCase();
+  return hostname.replace(/^www\./, "");
 }
 
 interface GuideClientParams {
@@ -81,7 +98,11 @@ export class GuideClient {
   }
 
   static async init(config: InitGuideConfig): Promise<GuideClient> {
-    const fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    const globalFetch = typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : undefined;
+    const fetchImpl = config.fetch ?? globalFetch;
+    if (!fetchImpl) {
+      throw new Error("[brand_brain] No `fetch` is available — pass `config.fetch` when running without a global fetch.");
+    }
     const apiBaseUrl = toApiBaseUrl(config.baseUrl);
     const domain = resolveDomain(config);
 

package/src/chat-stream.test.ts

@@ -52,4 +52,32 @@ describe("streamConversation", () => {
     const failing: typeof globalThis.fetch = () => Promise.resolve(new Response(null, { status: 500 }));
     await expect(collect("", { fetchImpl: failing })).rejects.toThrow("status 500");
   });
+
+  it("maps a known custom frame to a typed skill event", async () => {
+    const documents = [{ id: "d1", title: "Pricing guide", url: "https://acme.com/pricing" }];
+    const events = await collect(frame({ type: "CUSTOM", name: "skill_documents", value: { documents } }) + DONE);
+    expect(events).toContainEqual({ type: "skill", name: "skill_documents", value: { documents } });
+  });
+
+  it("maps an unrecognized custom frame to a skill-unknown event", async () => {
+    const events = await collect(frame({ type: "CUSTOM", name: "skill_new_thing", value: { foo: 1 } }) + DONE);
+    expect(events).toContainEqual({ type: "skill-unknown", name: "skill_new_thing", value: { foo: 1 } });
+  });
+
+  it("carries retryable and retryHint on a skill_error frame", async () => {
+    const events = await collect(
+      frame({
+        type: "CUSTOM",
+        name: "skill_error",
+        value: { errorType: "skill_timeout", message: "Timed out", retryable: true, retryHint: { prompt: "try again" } },
+      }) + DONE,
+    );
+    expect(events).toContainEqual({
+      type: "error",
+      message: "Timed out",
+      code: "skill_timeout",
+      retryable: true,
+      retryHint: { prompt: "try again" },
+    });
+  });
 });

package/src/chat-stream.ts

@@ -1,5 +1,5 @@
 import { GuideEvent, SSEMessageType } from "./types";
-import type { ChatMessage, GuideEventName, GuideStreamEvent, SkillResponseTypeType } from "./types";
+import type { ChatMessage, GuideSkillEvent, GuideStreamEvent, SkillErrorRetryHint, SkillResponseTypeType } from "./types";
 
 export interface StreamConversationParams {
   apiBaseUrl: string;
@@ -50,7 +50,15 @@ export async function* streamConversation(params: StreamConversationParams): Asy
   });
 
   if (!response.ok || !response.body) {
-    throw new Error(`[brand_brain] Conversation request failed with status ${response.status}`);
+    // Surface the server's error body (e.g. `{ "error": "guideId is required" }`)
+    // so integration failures are debuggable rather than just a bare status.
+    let detail = "";
+    try {
+      detail = (await response.text()).trim();
+    } catch {
+      // ignore — the body may be empty or already consumed
+    }
+    throw new Error(`[brand_brain] Conversation request failed with status ${response.status}${detail ? `: ${detail}` : ""}`);
   }
 
   const reader = response.body.getReader();
@@ -105,6 +113,16 @@ function mapFrame(frame: SSEFrame): GuideStreamEvent | null {
   }
 }
 
+/**
+ * Names that surface as typed `skill` events. `SkillGate`/`SkillError` are
+ * re-mapped to the `gate`/`error` variants below, so they are excluded here;
+ * any name outside this set is a server event this SDK version predates and
+ * flows through as `skill-unknown`.
+ */
+const SKILL_EVENT_NAMES: ReadonlySet<string> = new Set(
+  Object.values(GuideEvent).filter((name) => name !== GuideEvent.SkillGate && name !== GuideEvent.SkillError),
+);
+
 function mapCustomFrame(frame: SSEFrame): GuideStreamEvent | null {
   if (!frame.name) return null;
   const value = frame.value ?? {};
@@ -124,7 +142,14 @@ function mapCustomFrame(frame: SSEFrame): GuideStreamEvent | null {
       type: "error",
       message: (value.message as string | undefined) ?? "Skill error",
       code: value.errorType as string | undefined,
+      retryable: value.retryable as boolean | undefined,
+      retryHint: value.retryHint as SkillErrorRetryHint | undefined,
     };
   }
-  return { type: "skill", name: frame.name as GuideEventName, value };
+  if (SKILL_EVENT_NAMES.has(frame.name)) {
+    // Wire-boundary assertion: membership in SKILL_EVENT_NAMES pins `name` to a
+    // known skill event, and toSSE writes the payload shape the union declares.
+    return { type: "skill", name: frame.name, value } as GuideSkillEvent;
+  }
+  return { type: "skill-unknown", name: frame.name, value };
 }

package/src/index.ts

@@ -1,2 +1,4 @@
 export { GuideClient, initGuide } from "./GuideClient";
+export { createSkillTurn, reduceSkillEvent } from "./skill-state";
+export type { GuideSkillTurn } from "./skill-state";
 export * from "./types";

package/src/react/index.ts

@@ -1,2 +1,2 @@
 export { useGuide } from "./useGuide";
-export type { UseGuideResult } from "./useGuide";
+export type { GateRequest, UseGuideConfig, UseGuideResult } from "./useGuide";

package/src/react/useGuide.ts

@@ -2,7 +2,34 @@
 
 import { useCallback, useEffect, useRef, useState } from "react";
 import { initGuide, type GuideClient } from "../GuideClient";
-import type { AskOptions, ChatMessage, InitGuideConfig, ResolvedGuide } from "../types";
+import { createSkillTurn, reduceSkillEvent, type GuideSkillTurn } from "../skill-state";
+import type {
+  AskOptions,
+  ChatMessage,
+  GuideStreamEvent,
+  InitGuideConfig,
+  ResolvedGuide,
+  SkillResponseTypeType,
+  SubmitGateOptions,
+  SubmitGateResult,
+} from "../types";
+
+export interface UseGuideConfig extends InitGuideConfig {
+  /**
+   * Called with every raw stream event, in order — the escape hatch for
+   * anything the hook's derived state doesn't cover.
+   */
+  onEvent?: (event: GuideStreamEvent) => void;
+}
+
+/** A pending email gate — the guide wants an email before finishing the turn. */
+export interface GateRequest {
+  /** The skill that was gated. */
+  skill: SkillResponseTypeType;
+  /** The visitor prompt that triggered the gate (re-sent after unlocking). */
+  prompt?: string;
+  skillInstanceId?: string;
+}
 
 export interface UseGuideResult {
   /** The client once bootstrapped, else `null`. */
@@ -11,41 +38,77 @@ export interface UseGuideResult {
   guide: ResolvedGuide | null;
   /** Conversation history, kept in sync with the client. */
   messages: ChatMessage[];
+  /**
+   * Structured deliverable of the current / most recent turn (documents,
+   * recommendations, CTAs, how-to steps, …). `null` before the first ask.
+   */
+  skillTurn: GuideSkillTurn | null;
+  /**
+   * Set when the guide asks for an email mid-turn. Render an email form, call
+   * `submitGate(email)`, then `retryLastAsk()` to finish the interrupted turn.
+   */
+  gate: GateRequest | null;
   /** `true` once the client has finished initializing. */
   isReady: boolean;
   /** `true` while a reply is streaming. */
   isStreaming: boolean;
   /** Init or stream error, else `null`. */
   error: Error | null;
-  /** Send a message and stream the reply into `messages`. */
+  /** Send a message and stream the reply into `messages` / `skillTurn`. */
   ask: (message: string, options?: AskOptions) => Promise<void>;
+  /**
+   * Submit the visitor's email — for the pending `gate` (its context is merged
+   * in automatically) or as general lead capture. Clears `gate` on success.
+   */
+  submitGate: (email: string, options?: SubmitGateOptions) => Promise<SubmitGateResult>;
+  /** Re-send the last user message, e.g. to finish a gated turn after `submitGate`. */
+  retryLastAsk: () => Promise<void>;
   /** Clear the in-memory conversation. */
   reset: () => void;
 }
 
 /**
  * React binding over {@link initGuide}. Bootstraps once per `baseUrl`+`slug`,
- * mirrors the streamed reply into state, and ends the session on unmount —
+ * mirrors the streamed reply into `messages`, folds structured skill events
+ * into `skillTurn`, surfaces email gates, and ends the session on unmount —
  * encapsulating the streaming/cleanup patterns so generated UIs stay correct.
  */
-export function useGuide(config: InitGuideConfig): UseGuideResult {
+export function useGuide(config: UseGuideConfig): UseGuideResult {
   const [client, setClient] = useState<GuideClient | null>(null);
   const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [skillTurn, setSkillTurn] = useState<GuideSkillTurn | null>(null);
+  const [gate, setGate] = useState<GateRequest | null>(null);
   const [isStreaming, setIsStreaming] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
   const { baseUrl, slug } = config;
   const configRef = useRef(config);
   configRef.current = config;
+  // The turn state lives in a ref (not just React state) so the reducer can
+  // fold consecutive events synchronously and business-case continuations can
+  // read the previous turn without a re-render in between.
+  const turnRef = useRef<GuideSkillTurn | null>(null);
+  const lastAskRef = useRef<{ message: string; options?: AskOptions } | null>(null);
 
   useEffect(() => {
     let active = true;
     let created: GuideClient | null = null;
 
+    // Clear any prior guide's client + state so a baseUrl/slug change doesn't
+    // leave callers talking to the old guide (or rendering its messages) while
+    // the new one resolves.
+    setClient(null);
+    setMessages([]);
+    setSkillTurn(null);
+    setGate(null);
+    setError(null);
+    turnRef.current = null;
+    lastAskRef.current = null;
+
     void initGuide(configRef.current)
       .then((instance) => {
         if (!active) {
-          void instance.endSession();
+          void instance.endSession().catch(() => {});
           return;
         }
         created = instance;
@@ -58,19 +121,30 @@ export function useGuide(config: InitGuideConfig): UseGuideResult {
 
     return () => {
       active = false;
-      void created?.endSession();
+      void created?.endSession().catch(() => {});
     };
   }, [baseUrl, slug]);
 
   const ask = useCallback(
     async (message: string, options?: AskOptions) => {
       if (!client) return;
+      lastAskRef.current = { message, options };
       setIsStreaming(true);
       setError(null);
+      // A new ask supersedes a pending gate for the previous turn.
+      setGate(null);
       try {
         for await (const event of client.ask(message, options)) {
+          configRef.current.onEvent?.(event);
           if (event.type === "text" || event.type === "message-start") {
             setMessages([...client.messages]);
+          } else if (event.type === "skill") {
+            turnRef.current = reduceSkillEvent(turnRef.current ?? createSkillTurn(), event);
+            setSkillTurn(turnRef.current);
+          } else if (event.type === "gate") {
+            setGate({ skill: event.skill, prompt: event.prompt, skillInstanceId: event.skillInstanceId });
+          } else if (event.type === "error") {
+            setError(new Error(event.message));
           }
         }
         setMessages([...client.messages]);
@@ -83,19 +157,46 @@ export function useGuide(config: InitGuideConfig): UseGuideResult {
     [client],
   );
 
+  const submitGate = useCallback(
+    async (email: string, options?: SubmitGateOptions): Promise<SubmitGateResult> => {
+      if (!client) throw new Error("[brand_brain] Guide is not ready yet — wait for isReady before submitting the gate.");
+      const pending = gate;
+      const result = await client.submitGate(email, {
+        ...(pending && { skill: pending.skill, prompt: pending.prompt, skillInstanceId: pending.skillInstanceId }),
+        ...options,
+      });
+      if (result.success) setGate(null);
+      return result;
+    },
+    [client, gate],
+  );
+
+  const retryLastAsk = useCallback(async () => {
+    const last = lastAskRef.current;
+    if (last) await ask(last.message, last.options);
+  }, [ask]);
+
   const reset = useCallback(() => {
     client?.reset();
     setMessages([]);
+    setSkillTurn(null);
+    setGate(null);
+    turnRef.current = null;
+    lastAskRef.current = null;
   }, [client]);
 
   return {
     client,
     guide: client?.guide ?? null,
     messages,
+    skillTurn,
+    gate,
     isReady: client !== null,
     isStreaming,
     error,
     ask,
+    submitGate,
+    retryLastAsk,
     reset,
   };
 }

package/src/skill-state.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+import { createSkillTurn, reduceSkillEvent, type GuideSkillTurn } from "./skill-state";
+import { GuideEvent } from "./types";
+import type { GuideSkillEvent, SkillResponseTypeType } from "./types";
+
+function reduceAll(events: GuideSkillEvent[], initial: GuideSkillTurn = createSkillTurn()): GuideSkillTurn {
+  return events.reduce(reduceSkillEvent, initial);
+}
+
+const start = (skill: SkillResponseTypeType): GuideSkillEvent => ({
+  type: "skill",
+  name: GuideEvent.SkillStart,
+  value: { skill, messageId: "m1" },
+});
+
+describe("reduceSkillEvent", () => {
+  it("captures the running skill from skill_start", () => {
+    const turn = reduceAll([start("answer")]);
+    expect(turn.skill).toBe("answer");
+  });
+
+  it("accumulates skill_content deltas in order", () => {
+    const turn = reduceAll([
+      start("answer"),
+      { type: "skill", name: GuideEvent.SkillContent, value: { delta: "Hello " } },
+      { type: "skill", name: GuideEvent.SkillContent, value: { delta: "world" } },
+    ]);
+    expect(turn.content).toBe("Hello world");
+  });
+
+  it("replaces documents with the latest skill_documents payload", () => {
+    const turn = reduceAll([
+      start("answer"),
+      { type: "skill", name: GuideEvent.SkillDocuments, value: { documents: [{ id: "d1", title: "Old" }] } },
+      { type: "skill", name: GuideEvent.SkillDocuments, value: { documents: [{ id: "d2", title: "New" }] } },
+    ]);
+    expect(turn.documents).toEqual([{ id: "d2", title: "New" }]);
+  });
+
+  it("routes recommendations with targetSkill to contentRecommendations", () => {
+    const recommendation = {
+      id: "r1",
+      targetSkill: "howto" as const,
+      title: "Set it up",
+      rationale: "You asked about setup",
+      prompt: "How do I set it up?",
+      confidence: "high" as const,
+    };
+    const turn = reduceAll([
+      start("recommend"),
+      { type: "skill", name: GuideEvent.SkillRecommendations, value: { recommendations: [recommendation] } },
+    ]);
+    expect(turn.contentRecommendations).toEqual([recommendation]);
+  });
+
+  it("routes recommendations without targetSkill to followUpRecommendations", () => {
+    const pill = { id: "r1", skill: "howto" as const, label: "Show me how", prompt: "Show me how" };
+    const turn = reduceAll([
+      start("answer"),
+      { type: "skill", name: GuideEvent.SkillRecommendations, value: { recommendations: [pill] } },
+    ]);
+    expect(turn.followUpRecommendations).toEqual([pill]);
+  });
+
+  it("appends diagnose questions across events", () => {
+    const question = (id: string) => ({
+      id,
+      category: "Fit",
+      questionText: `Q${id}`,
+      options: [],
+      prerequisiteConceptId: null,
+      prerequisiteConceptName: null,
+    });
+    const turn = reduceAll([
+      start("diagnose"),
+      { type: "skill", name: GuideEvent.SkillDiagnoseQuestion, value: { question: question("q1") } },
+      { type: "skill", name: GuideEvent.SkillDiagnoseQuestion, value: { question: question("q2") } },
+    ]);
+    expect(turn.diagnoseQuestions.map((q) => q.id)).toEqual(["q1", "q2"]);
+  });
+
+  it("patches a playlist item's rationale by itemId", () => {
+    const item = { id: "p1", title: "Video", description: null, contentType: "video_youtube" as const, url: null };
+    const turn = reduceAll([
+      start("playlist"),
+      { type: "skill", name: GuideEvent.SkillPlaylistItems, value: { items: [item] } },
+      { type: "skill", name: GuideEvent.SkillPlaylistRationale, value: { itemId: "p1", rationale: "Because reasons" } },
+    ]);
+    expect(turn.playlistItems[0].rationale).toBe("Because reasons");
+  });
+
+  it("accumulates business case deltas per subType", () => {
+    const turn = reduceAll([
+      start("businesscase"),
+      { type: "skill", name: GuideEvent.SkillBusinessCaseDelta, value: { subType: "roi-analysis", delta: "# ROI" } },
+      { type: "skill", name: GuideEvent.SkillBusinessCaseDelta, value: { subType: "roi-analysis", delta: " body" } },
+    ]);
+    expect(turn.businessCaseContent["roi-analysis"]).toBe("# ROI body");
+  });
+
+  it("preserves business case state across a continuation skill_start", () => {
+    const chooser: GuideSkillEvent = {
+      type: "skill",
+      name: GuideEvent.SkillBusinessCaseChooser,
+      value: { formats: [], drafts: { "roi-analysis": { draftId: "d1", skillInstanceId: "s1" } } },
+    };
+    const turn = reduceAll([start("businesscase"), chooser, start("businesscase")]);
+    expect(turn.businessCaseDrafts["roi-analysis"]).toEqual({ draftId: "d1", skillInstanceId: "s1" });
+  });
+
+  it("resets prior state when a different skill starts", () => {
+    const turn = reduceAll([
+      start("answer"),
+      { type: "skill", name: GuideEvent.SkillDocuments, value: { documents: [{ id: "d1", title: "Doc" }] } },
+      start("howto"),
+    ]);
+    expect(turn.documents).toEqual([]);
+  });
+
+  it("marks the turn complete with its skillInstanceId on skill_end", () => {
+    const turn = reduceAll([start("howto"), { type: "skill", name: GuideEvent.SkillEnd, value: { skillInstanceId: "si-1" } }]);
+    expect(turn).toMatchObject({ status: "complete", skillInstanceId: "si-1" });
+  });
+
+  it("captures the early skillInstanceId from skill_howto_outline", () => {
+    const turn = reduceAll([
+      start("howto"),
+      {
+        type: "skill",
+        name: GuideEvent.SkillHowToOutline,
+        value: { outline: { title: "Setup", steps: [] }, skillInstanceId: "si-early" },
+      },
+    ]);
+    expect(turn.skillInstanceId).toBe("si-early");
+  });
+
+  it("falls back to the legacy skillResponseId alias on skill_end", () => {
+    const turn = reduceAll([
+      start("howto"),
+      { type: "skill", name: GuideEvent.SkillEnd, value: { skillResponseId: "si-legacy" } },
+    ]);
+    expect(turn.skillInstanceId).toBe("si-legacy");
+  });
+});