feat(docs): voice agent panel, API routes, and Pagefind search

apps/docs/.gitignore

@@ -0,0 +1,2 @@
+# Local Netlify folder
+.netlify

apps/docs/astro.config.mjs

@@ -8,11 +8,14 @@ import pagefind from 'astro-pagefind';
 import llmsTxt from '@4hse/astro-llms-txt';
 import playformInline from '@playform/inline';
 import compress from '@playform/compress';
+import netlify from '@astrojs/netlify';
 import { remarkBaseUrl } from './src/lib/remark-base-url.mjs';
 import { remarkBrandName } from './src/lib/remark-brand-name.mjs';
 
 // https://astro.build/config
 export default defineConfig({
+	output: 'static',
+	adapter: netlify(),
 	site: process.env.CV_WEB_URL || 'http://localhost:4321',
 	base: '/docs',
 	markdown: {

apps/docs/package.json

@@ -13,8 +13,10 @@
   },
   "dependencies": {
     "@4hse/astro-llms-txt": "^1.0.4",
+    "@astrojs/netlify": "^6.6.5",
     "@astrojs/react": "^4.2.1",
     "@astrojs/sitemap": "^3.7.0",
+    "@lukeocodes/composite-voice": "workspace:*",
     "@lukeocodes/composite-voice-ui": "workspace:*",
     "@playform/compress": "^0.2.1",
     "@playform/inline": "^0.1.2",

apps/docs/src/components/VoiceAgentIsland.tsx

@@ -0,0 +1,200 @@
+/**
+ * React island that mounts the voice agent panel in the Astro docs site.
+ *
+ * Handles session creation, token fetching, and bridges the UI components
+ * with the CompositeVoice pipeline. Provides a `search_docs` tool so the
+ * agent can query the Pagefind index and give grounded answers.
+ */
+
+import { useState, useCallback } from 'react';
+import {
+  AgentPanel,
+  ChatPanel,
+  useVoiceAgent,
+} from '@lukeocodes/composite-voice-ui/agent';
+import type {
+  AgentToolDefinition,
+  AgentToolCall,
+  AgentToolResult,
+} from '@lukeocodes/composite-voice-ui/agent';
+
+/* ── Credentials ─────────────────────────────── */
+
+/** Fetch a Deepgram JWT from the serverless endpoint. */
+async function getToken(): Promise<{ token: string; expiresIn: number }> {
+  const res = await fetch('/docs/api/deepgram-token');
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error ?? `Token request failed: ${res.status}`);
+  }
+  const data = await res.json();
+  return { token: data.token, expiresIn: data.expiresIn };
+}
+
+/** Create a session cookie (required before token requests). */
+async function ensureSession(): Promise<void> {
+  await fetch('/docs/api/session', { method: 'POST' });
+}
+
+/* ── Pagefind search tool ────────────────────── */
+
+const SEARCH_TOOL: AgentToolDefinition = {
+  name: 'search_docs',
+  description:
+    'Search the CompositeVoice SDK documentation. Returns relevant page titles, URLs, and excerpts. Use this when the user asks about SDK features, configuration, providers, events, examples, or API reference.',
+  parameters: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'The search query to find relevant documentation pages',
+      },
+    },
+    required: ['query'],
+  },
+};
+
+/** Cached Pagefind instance. */
+let pagefindInstance: {
+  search: (query: string) => Promise<{
+    results: Array<{
+      data: () => Promise<{
+        url: string;
+        excerpt: string;
+        meta: { title?: string };
+        content: string;
+      }>;
+    }>;
+  }>;
+} | null = null;
+
+const PAGEFIND_BASE = '/docs';
+
+async function getPagefind() {
+  if (pagefindInstance) return pagefindInstance;
+  const mod = await import(/* @vite-ignore */ `${PAGEFIND_BASE}/pagefind/pagefind.js`);
+  if (mod.init) await mod.init();
+  pagefindInstance = mod;
+  return mod;
+}
+
+async function handleToolCall(toolCall: AgentToolCall): Promise<AgentToolResult> {
+  if (toolCall.name === 'search_docs') {
+    try {
+      const pagefind = await getPagefind();
+      const query = String(toolCall.arguments.query ?? '');
+      const { results } = await pagefind.search(query);
+
+      // Load data for top 5 results
+      const entries = await Promise.all(
+        results.slice(0, 5).map(async (r) => {
+          const data = await r.data();
+          return {
+            title: data.meta?.title ?? 'Untitled',
+            url: data.url,
+            excerpt: data.excerpt.replace(/<\/?mark>/g, ''),
+            content: data.content.slice(0, 300),
+          };
+        }),
+      );
+
+      return {
+        toolCallId: toolCall.id,
+        content: JSON.stringify(entries.length > 0 ? entries : { message: 'No results found' }),
+      };
+    } catch {
+      return {
+        toolCallId: toolCall.id,
+        content: JSON.stringify({ error: 'Search unavailable — index not built yet' }),
+        isError: true,
+      };
+    }
+  }
+
+  return {
+    toolCallId: toolCall.id,
+    content: JSON.stringify({ error: `Unknown tool: ${toolCall.name}` }),
+    isError: true,
+  };
+}
+
+/* ── Component ───────────────────────────────── */
+
+export default function VoiceAgentIsland() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [sessionReady, setSessionReady] = useState(false);
+
+  const [state, actions] = useVoiceAgent({
+    getToken,
+    anthropicProxyUrl: '/docs/api/proxy/anthropic',
+    model: 'claude-haiku-4-5',
+    maxTokens: 1024,
+    voice: 'aura-2-thalia-en',
+    systemPrompt: `You are a helpful voice assistant for the CompositeVoice SDK documentation site.
+Answer questions about the SDK concisely and conversationally.
+When discussing code, keep examples short and focused.
+You can help with: provider setup, configuration, pipeline architecture,
+proxy setup, event handling, conversation history, tool use, and custom providers.
+You have a search_docs tool — use it to find relevant documentation before answering technical questions.
+When you use search results, naturally weave the information into your response.
+Respond in plain text for voice — no markdown formatting, no bullet points, no code blocks unless specifically asked for code.`,
+    tools: {
+      definitions: [SEARCH_TOOL],
+      onToolCall: handleToolCall,
+    },
+  });
+
+  const handleOpen = useCallback(async () => {
+    setIsOpen(true);
+
+    if (!sessionReady) {
+      await ensureSession();
+      setSessionReady(true);
+    }
+
+    if (state.status === 'idle') {
+      await actions.initialize();
+      await actions.startListening();
+    }
+  }, [sessionReady, state.status, state.messages.length, actions]);
+
+  const handleClose = useCallback(() => {
+    setIsOpen(false);
+    actions.stopListening();
+  }, [actions]);
+
+  return (
+    <>
+      {/* FAB trigger button */}
+      {!isOpen && (
+        <button
+          onClick={handleOpen}
+          className="fixed bottom-6 right-6 z-[9998] flex items-center gap-2 rounded-full bg-primary-600 px-4 py-3 text-sm font-medium text-on-filled shadow-lg transition-all hover:bg-primary-500 hover:shadow-xl active:scale-95"
+          aria-label="Open voice assistant"
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth={2}
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className="h-5 w-5"
+          >
+            <path d="M12 1a3 3 0 0 0-3 3v8a3 3 0 0 0 6 0V4a3 3 0 0 0-3-3z" />
+            <path d="M19 10v2a7 7 0 0 1-14 0v-2" />
+            <line x1="12" y1="19" x2="12" y2="23" />
+            <line x1="8" y1="23" x2="16" y2="23" />
+          </svg>
+          Ask AI
+        </button>
+      )}
+
+      {/* Agent panel */}
+      <AgentPanel isOpen={isOpen} onClose={handleClose}>
+        <ChatPanel state={state} actions={actions} onClose={handleClose} />
+      </AgentPanel>
+    </>
+  );
+}

apps/docs/src/layouts/DocsLayout.astro

@@ -7,6 +7,7 @@ import { Breadcrumbs } from "astro-breadcrumbs";
 import { Navbar, Sidebar, Footer } from "@lukeocodes/composite-voice-ui";
 import type { SidebarItem } from "@lukeocodes/composite-voice-ui";
 import { nav, isNavFolder, isNavSection } from "../lib/nav";
+import VoiceAgentIsland from "../components/VoiceAgentIsland";
 import pkg from "../../../../package.json";
 
 interface Props {
@@ -69,6 +70,28 @@ const sections: SidebarItem[] = nav.map((item) => {
 });
 
 const currentPath = Astro.url.pathname;
+
+/* Derive pagefind section filter from the URL path */
+const pathWithoutBase = currentPath.replace(/^\/docs\/?/, '');
+const topSegment = pathWithoutBase.split('/')[0];
+const sectionMap: Record<string, string> = {
+  guides: 'Guides',
+  reference: 'Reference',
+  advanced: 'Advanced',
+  api: 'API Reference',
+  examples: 'Examples',
+};
+const pagefindSection = sectionMap[topSegment] ?? 'Overview';
+
+/* Rank guides/reference/advanced higher than API reference in search */
+const pagefindWeight: Record<string, string> = {
+  guides: '2',
+  reference: '2',
+  advanced: '1.5',
+  examples: '1',
+  api: '0.3',
+};
+const weight = pagefindWeight[topSegment] ?? '1';
 ---
 
 <html lang="en">
@@ -155,13 +178,16 @@ const currentPath = Astro.url.pathname;
       Skip to content
     </a>
 
-    <Navbar client:load sites={sites} version={pkg.version} hasSidebar />
+    <Navbar client:load sites={sites} version={pkg.version} hasSidebar showSearch searchBasePath="/docs" />
 
     <div class="flex min-h-screen pt-14">
       <Sidebar client:load sections={sections} currentPath={currentPath} ariaLabel="Documentation sections" />
 
       <main id="main-content" class="flex-1 min-w-0 md:ml-64">
         <div class="max-w-5xl mx-auto px-4 sm:px-6 lg:px-8 py-8 sm:py-12">
+          <meta data-pagefind-filter="section[content]" content={pagefindSection} />
+          <meta data-pagefind-weight={weight} />
+
           <Breadcrumbs indexText="Docs" linkTextFormat="capitalized">
             <span slot="separator">/</span>
           </Breadcrumbs>
@@ -183,6 +209,8 @@ const currentPath = Astro.url.pathname;
         <Footer client:load sites={sites} className="mt-auto" />
       </main>
     </div>
+    <VoiceAgentIsland client:idle />
+
     <script is:inline>
       // Inject copy-to-clipboard buttons on Prism code blocks
       document.querySelectorAll('pre[class*="language-"]').forEach(function(pre) {

apps/docs/src/pages/api/_session.ts

@@ -0,0 +1,78 @@
+/**
+ * Session management for API routes.
+ *
+ * Uses an HMAC-signed session cookie. The /api/session endpoint creates the
+ * cookie; other API routes validate it via validateSession().
+ *
+ * The session ID is a random value signed with a server-side secret. This
+ * prevents external scripts from calling the token endpoint directly — they
+ * would need to first load a page that creates the session.
+ */
+
+export const SESSION_COOKIE = 'cv_agent_session';
+const SESSION_MAX_AGE = 3600; // 1 hour
+
+/** Server secret for HMAC signing. Falls back to a build-time random value. */
+const SECRET = process.env.SESSION_SECRET || crypto.randomUUID();
+
+/**
+ * Create a signed session value: `id.signature`
+ */
+export function createSignedSession(): { value: string; id: string } {
+  const id = crypto.randomUUID();
+  const signature = signValue(id);
+  return { value: `${id}.${signature}`, id };
+}
+
+/**
+ * Validate a session cookie from a request. Returns the session ID if valid.
+ */
+export function validateSession(request: Request): string | null {
+  const cookieHeader = request.headers.get('cookie');
+  if (!cookieHeader) return null;
+
+  const cookies = parseCookies(cookieHeader);
+  const sessionValue = cookies[SESSION_COOKIE];
+  if (!sessionValue) return null;
+
+  const dotIndex = sessionValue.lastIndexOf('.');
+  if (dotIndex === -1) return null;
+
+  const id = sessionValue.slice(0, dotIndex);
+  const signature = sessionValue.slice(dotIndex + 1);
+
+  if (signValue(id) !== signature) return null;
+
+  return id;
+}
+
+/**
+ * Build a Set-Cookie header value for the session.
+ */
+export function buildSessionCookie(signedValue: string): string {
+  return `${SESSION_COOKIE}=${signedValue}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${SESSION_MAX_AGE}; Secure`;
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────
+
+function signValue(value: string): string {
+  // Simple HMAC-like signature using Web Crypto SubtleCrypto is async,
+  // so we use a sync hash approach with a keyed prefix instead.
+  // This is sufficient for session validation (not cryptographic security).
+  let hash = 0;
+  const input = `${SECRET}:${value}`;
+  for (let i = 0; i < input.length; i++) {
+    const char = input.charCodeAt(i);
+    hash = ((hash << 5) - hash + char) | 0;
+  }
+  return Math.abs(hash).toString(36);
+}
+
+function parseCookies(header: string): Record<string, string> {
+  const cookies: Record<string, string> = {};
+  for (const pair of header.split(';')) {
+    const [key, ...rest] = pair.trim().split('=');
+    if (key) cookies[key.trim()] = rest.join('=').trim();
+  }
+  return cookies;
+}