@octavus/docs 0.0.6 → 0.0.8

package/dist/chunk-PMOVVTHO.js

@@ -0,0 +1,519 @@
+// dist/docs.json
+var docs_default = [
+  {
+    slug: "getting-started/introduction",
+    section: "getting-started",
+    title: "Introduction",
+    description: "Overview of Octavus AI - an agent orchestration platform for developers.",
+    content: "\n# Introduction to Octavus\n\nOctavus is an agent orchestration platform that lets developers define, manage, and deploy AI agents through a unified service. It handles the orchestration layer so teams can focus on their agent logic and business requirements.\n\n## What is Octavus?\n\nBuilding and managing AI agents is complex. Developers face challenges with:\n\n- **Fragmented tooling** \u2014 No unified way to define, manage, and deploy agents\n- **Prompt management** \u2014 Prompts are scattered across codebases, hard to version and iterate\n- **Integration complexity** \u2014 Connecting agents to tools, resources, and other agents requires significant custom work\n- **Observability** \u2014 Difficult to debug, monitor, and understand agent behavior in production\n- **Infrastructure overhead** \u2014 Teams rebuild the same agent infrastructure repeatedly\n\nOctavus solves these problems by providing:\n\n- A **protocol-based approach** to defining agent behavior\n- **Server and client SDKs** for easy integration\n- **Built-in streaming** support for real-time responses\n- **Tool execution** that runs on your servers with your data\n- **Session management** for stateful conversations\n\n## Core Concepts\n\n### Agents\n\nAn **Agent** is the main entity in Octavus \u2014 a self-contained unit that defines how an AI agent behaves. Agents are defined using YAML protocols that specify:\n\n- Input variables the agent accepts\n- Triggers that invoke the agent (user messages, button clicks, API calls)\n- Tools the agent can use\n- Handlers that define execution flow\n\n### Sessions\n\nA **Session** represents a conversation with an agent. Sessions:\n\n- Store conversation history\n- Track resources and variables\n- Enable stateful interactions across multiple messages\n\n### Triggers\n\n**Triggers** define how an agent is invoked:\n\n- **User Message** \u2014 Respond to a text message in a chat interface\n- **User Action** \u2014 Respond to UI actions (button clicks, form submissions)\n- **API Call** \u2014 Direct invocation via SDK\n\n### Tools\n\n**Tools** extend what agents can do:\n\n- **External Tools** \u2014 Consumer-defined tools that call back to your systems\n- **Internal Tools** \u2014 Built-in capabilities (web search, code execution)\n\nTools execute on your server, not on Octavus, giving you full control over data and authentication.\n\n## Architecture Overview\n\n```mermaid\nsequenceDiagram\n    participant App as Your App\n    participant API as Octavus API\n    participant LLM as LLM Provider\n\n    App->>API: 1. Trigger action\n    API->>LLM: 2. Execute protocol\n    LLM-->>API: Response\n    API-->>App: 3. Stream events\n    \n    Note over App: Tool request received\n    API-->>App: 4. Tool request\n    Note over App: 5. Execute tool locally\n    App->>API: 6. Return results\n    \n    API->>LLM: 7. Continue\n    LLM-->>API: Response\n    API-->>App: 8. Stream response\n```\n\n## Next Steps\n\n- [Quick Start](/docs/getting-started/quickstart) \u2014 Get your first agent running in minutes\n- [Server SDK](/docs/server-sdk/overview) \u2014 Learn about backend integration\n- [Client SDK](/docs/client-sdk/overview) \u2014 Build chat interfaces with React (or other frameworks)\n- [Protocol Reference](/docs/protocol/overview) \u2014 Deep dive into agent protocols\n\n",
+    excerpt: "Introduction to Octavus Octavus is an agent orchestration platform that lets developers define, manage, and deploy AI agents through a unified service. It handles the orchestration layer so teams can...",
+    order: 1
+  },
+  {
+    slug: "getting-started/quickstart",
+    section: "getting-started",
+    title: "Quick Start",
+    description: "Get your first Octavus agent running in minutes.",
+    content: "\n# Quick Start\n\nThis guide will walk you through integrating Octavus into your application in under 10 minutes.\n\n## Prerequisites\n\n- Node.js 18+\n- An Octavus account with API key\n- A Next.js application (or any Node.js backend)\n\n## Installation\n\nInstall the Octavus SDKs in your project:\n\n```bash\n# Server SDK for backend\nnpm install @octavus/server-sdk\n\n# React bindings for frontend\nnpm install @octavus/react\n```\n\n## Backend Setup\n\n### 1. Initialize the Client\n\nCreate an Octavus client instance in your backend:\n\n```typescript\n// lib/octavus.ts\nimport { OctavusClient } from '@octavus/server-sdk';\n\nexport const octavus = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n```\n\n### 2. Create a Session Endpoint\n\nCreate an API endpoint that creates sessions and returns the session ID:\n\n```typescript\n// app/api/chat/create/route.ts\nimport { NextResponse } from 'next/server';\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { agentSlug, input } = await request.json();\n\n  // Look up agent by slug to get its ID\n  const agent = await octavus.agents.getBySlug(agentSlug);\n  if (!agent) {\n    return NextResponse.json({ error: 'Agent not found' }, { status: 404 });\n  }\n\n  // Create a new session using the agent ID\n  const sessionId = await octavus.agentSessions.create(agent.id, input);\n\n  return NextResponse.json({ sessionId });\n}\n```\n\n### 3. Create a Trigger Endpoint\n\nCreate an endpoint that handles triggers and streams responses:\n\n```typescript\n// app/api/trigger/route.ts\nimport { toSSEStream } from '@octavus/server-sdk';\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { sessionId, triggerName, input } = await request.json();\n\n  // Attach to session with tool handlers\n  const session = octavus.agentSessions.attach(sessionId, {\n    tools: {\n      // Define tool handlers that run on your server\n      'get-user-account': async (args) => {\n        const userId = args.userId as string;\n        // Fetch from your database\n        return {\n          name: 'Demo User',\n          email: 'demo@example.com',\n          plan: 'pro',\n        };\n      },\n      'create-support-ticket': async (args) => {\n        // Create ticket in your system\n        return {\n          ticketId: 'TICKET-123',\n          estimatedResponse: '24 hours',\n        };\n      },\n    },\n  });\n\n  // Trigger the action and convert to SSE stream\n  const events = session.trigger(triggerName, input);\n\n  // Return as streaming response\n  return new Response(toSSEStream(events), {\n    headers: {\n      'Content-Type': 'text/event-stream',\n      'Cache-Control': 'no-cache',\n      Connection: 'keep-alive',\n    },\n  });\n}\n```\n\n## Frontend Setup\n\n### 1. Create a Chat Component\n\nUse the `useOctavusChat` hook with the HTTP transport:\n\n```tsx\n// components/chat.tsx\n'use client';\n\nimport { useState, useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';\n\ninterface ChatProps {\n  sessionId: string;\n}\n\nexport function Chat({ sessionId }: ChatProps) {\n  const [inputValue, setInputValue] = useState('');\n\n  // Create a stable transport instance\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { messages, status, error, send } = useOctavusChat({ transport });\n\n  const isStreaming = status === 'streaming';\n\n  const handleSubmit = async (e: React.FormEvent) => {\n    e.preventDefault();\n    if (!inputValue.trim() || isStreaming) return;\n\n    const message = inputValue.trim();\n    setInputValue('');\n\n    // Add user message and trigger in one call\n    await send(\n      'user-message',\n      { USER_MESSAGE: message },\n      { userMessage: { content: message } },\n    );\n  };\n\n  return (\n    <div className=\"flex flex-col h-full\">\n      {/* Messages */}\n      <div className=\"flex-1 overflow-y-auto p-4 space-y-4\">\n        {messages.map((msg) => (\n          <MessageBubble key={msg.id} message={msg} />\n        ))}\n      </div>\n\n      {/* Input */}\n      <form onSubmit={handleSubmit} className=\"p-4 border-t\">\n        <div className=\"flex gap-2\">\n          <input\n            type=\"text\"\n            value={inputValue}\n            onChange={(e) => setInputValue(e.target.value)}\n            placeholder=\"Type a message...\"\n            className=\"flex-1 px-4 py-2 border rounded-lg\"\n            disabled={isStreaming}\n          />\n          <button\n            type=\"submit\"\n            disabled={isStreaming}\n            className=\"px-4 py-2 bg-blue-500 text-white rounded-lg disabled:opacity-50\"\n          >\n            Send\n          </button>\n        </div>\n      </form>\n    </div>\n  );\n}\n\nfunction MessageBubble({ message }: { message: UIMessage }) {\n  const isUser = message.role === 'user';\n\n  return (\n    <div className={`flex ${isUser ? 'justify-end' : 'justify-start'}`}>\n      <div\n        className={`p-3 rounded-lg max-w-md ${\n          isUser ? 'bg-blue-500 text-white' : 'bg-gray-100'\n        }`}\n      >\n        {message.parts.map((part, i) => {\n          if (part.type === 'text') {\n            return <p key={i}>{part.text}</p>;\n          }\n          return null;\n        })}\n\n        {/* Streaming indicator */}\n        {message.status === 'streaming' && (\n          <span className=\"inline-block w-2 h-4 bg-gray-400 animate-pulse ml-1\" />\n        )}\n      </div>\n    </div>\n  );\n}\n```\n\n### 2. Create Session and Render Chat\n\n```tsx\n// app/chat/page.tsx\n'use client';\n\nimport { useEffect, useState } from 'react';\nimport { Chat } from '@/components/chat';\n\nexport default function ChatPage() {\n  const [sessionId, setSessionId] = useState<string | null>(null);\n\n  useEffect(() => {\n    async function createSession() {\n      const response = await fetch('/api/chat/create', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({\n          agentSlug: 'support-chat',\n          input: {\n            COMPANY_NAME: 'Acme Corp',\n            PRODUCT_NAME: 'Widget Pro',\n          },\n        }),\n      });\n      const { sessionId } = await response.json();\n      setSessionId(sessionId);\n    }\n\n    createSession();\n  }, []);\n\n  if (!sessionId) {\n    return <div>Loading...</div>;\n  }\n\n  return <Chat sessionId={sessionId} />;\n}\n```\n\n## Environment Variables\n\nAdd these to your `.env.local`:\n\n```bash\nOCTAVUS_API_URL=https://octavus.ai\nOCTAVUS_API_KEY=your-api-key-here\n```\n\n## What's Next?\n\nNow that you have a basic integration working:\n\n- [Learn about the protocol](/docs/protocol/overview) to define custom agent behavior\n- [Explore the Server SDK](/docs/server-sdk/overview) for advanced backend features\n- [Build rich UIs](/docs/client-sdk/overview) with the Client SDK\n",
+    excerpt: "Quick Start This guide will walk you through integrating Octavus into your application in under 10 minutes.  Prerequisites - Node.js 18+ - An Octavus account with API key - A Next.js application (or...",
+    order: 2
+  },
+  {
+    slug: "server-sdk/overview",
+    section: "server-sdk",
+    title: "Overview",
+    description: "Introduction to the Octavus Server SDK for backend integration.",
+    content: "\n# Server SDK Overview\n\nThe `@octavus/server-sdk` package provides a Node.js SDK for integrating Octavus agents into your backend application. It handles session management, streaming, and the tool execution continuation loop.\n\n**Current version:** `0.0.7`\n\n## Installation\n\n```bash\nnpm install @octavus/server-sdk\n```\n\n## Basic Usage\n\n```typescript\nimport { OctavusClient } from '@octavus/server-sdk';\n\nconst client = new OctavusClient({\n  baseUrl: 'https://octavus.ai',\n  apiKey: 'your-api-key',\n});\n```\n\n## Key Features\n\n### Session Management\n\nCreate and manage agent sessions:\n\n```typescript\n// Create a new session\nconst sessionId = await client.agentSessions.create('agent-id', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n});\n\n// Get UI-ready session messages (for session restore)\nconst session = await client.agentSessions.getMessages(sessionId);\n```\n\n### Tool Handlers\n\nTools run on your server with your data:\n\n```typescript\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    'get-user-account': async (args) => {\n      // Access your database, APIs, etc.\n      return await db.users.findById(args.userId);\n    },\n  },\n});\n```\n\n### Streaming\n\nAll responses stream in real-time:\n\n```typescript\nimport { toSSEStream } from '@octavus/server-sdk';\n\n// trigger() returns an async generator of events\nconst events = session.trigger('user-message', {\n  USER_MESSAGE: 'Hello!',\n});\n\n// Convert to SSE stream for HTTP responses\nreturn new Response(toSSEStream(events), {\n  headers: { 'Content-Type': 'text/event-stream' },\n});\n```\n\n## API Reference\n\n### OctavusClient\n\nThe main entry point for interacting with Octavus.\n\n```typescript\ninterface OctavusClientConfig {\n  baseUrl: string;  // Octavus API URL\n  apiKey?: string;  // Your API key\n}\n\nclass OctavusClient {\n  readonly agents: AgentsApi;\n  readonly agentSessions: AgentSessionsApi;\n\n  constructor(config: OctavusClientConfig);\n}\n```\n\n### AgentSessionsApi\n\nManages agent sessions.\n\n```typescript\nclass AgentSessionsApi {\n  // Create a new session\n  async create(agentId: string, input?: Record<string, unknown>): Promise<string>;\n\n  // Get full session state (for debugging/internal use)\n  async get(sessionId: string): Promise<SessionState>;\n\n  // Get UI-ready messages (for client display)\n  async getMessages(sessionId: string): Promise<UISessionState>;\n\n  // Attach to a session for triggering\n  attach(sessionId: string, options?: SessionAttachOptions): AgentSession;\n}\n\n// Full session state (internal format)\ninterface SessionState {\n  id: string;\n  agentId: string;\n  input: Record<string, unknown>;\n  variables: Record<string, unknown>;\n  resources: Record<string, unknown>;\n  messages: ChatMessage[];  // Internal message format\n  createdAt: string;\n  updatedAt: string;\n}\n\n// UI-ready session state\ninterface UISessionState {\n  sessionId: string;\n  agentId: string;\n  messages: UIMessage[];  // UI-ready messages for frontend\n}\n```\n\n### AgentSession\n\nHandles triggering and streaming for a specific session.\n\n```typescript\nclass AgentSession {\n  // Trigger an action and stream parsed events\n  trigger(\n    triggerName: string,\n    input?: Record<string, unknown>\n  ): AsyncGenerator<StreamEvent>;\n\n  // Get the session ID\n  getSessionId(): string;\n}\n\n// Helper to convert events to SSE stream\nfunction toSSEStream(events: AsyncIterable<StreamEvent>): ReadableStream<Uint8Array>;\n```\n\n## Next Steps\n\n- [Sessions](/docs/server-sdk/sessions) \u2014 Deep dive into session management\n- [Tools](/docs/server-sdk/tools) \u2014 Implementing tool handlers\n- [Streaming](/docs/server-sdk/streaming) \u2014 Understanding stream events\n",
+    excerpt: "Server SDK Overview The  package provides a Node.js SDK for integrating Octavus agents into your backend application. It handles session management, streaming, and the tool execution continuation...",
+    order: 1
+  },
+  {
+    slug: "server-sdk/sessions",
+    section: "server-sdk",
+    title: "Sessions",
+    description: "Managing agent sessions with the Server SDK.",
+    content: "\n# Sessions\n\nSessions represent conversations with an agent. They store conversation history, track resources and variables, and enable stateful interactions.\n\n## Creating Sessions\n\nCreate a session by specifying the agent ID and initial input variables:\n\n```typescript\nimport { OctavusClient } from '@octavus/server-sdk';\n\nconst client = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n\n// Create a session with the support-chat agent\nconst sessionId = await client.agentSessions.create('support-chat', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n  USER_ID: 'user-123', // Optional inputs\n});\n\nconsole.log('Session created:', sessionId);\n```\n\n## Getting Session Messages\n\nTo restore a conversation on page load, use `getMessages()` to retrieve UI-ready messages:\n\n```typescript\nconst session = await client.agentSessions.getMessages(sessionId);\n\nconsole.log({\n  sessionId: session.sessionId,\n  agentId: session.agentId,\n  messages: session.messages.length,  // UIMessage[] ready for frontend\n});\n```\n\nThe returned messages can be passed directly to the client SDK's `initialMessages` option.\n\n### UISessionState Interface\n\n```typescript\ninterface UISessionState {\n  sessionId: string;\n  agentId: string;\n  messages: UIMessage[];  // UI-ready conversation history\n}\n```\n\n## Full Session State (Debug)\n\nFor debugging or internal use, you can retrieve the complete session state including all variables and internal message format:\n\n```typescript\nconst state = await client.agentSessions.get(sessionId);\n\nconsole.log({\n  id: state.id,\n  agentId: state.agentId,\n  messages: state.messages.length,  // ChatMessage[] (internal format)\n  resources: state.resources,\n  variables: state.variables,\n  createdAt: state.createdAt,\n  updatedAt: state.updatedAt,\n});\n```\n\n> **Note**: Use `getMessages()` for client-facing code. The `get()` method returns internal message format that includes hidden content not intended for end users.\n\n## Attaching to Sessions\n\nTo trigger actions on a session, you need to attach to it first:\n\n```typescript\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    // Tool handlers (see Tools documentation)\n  },\n  resources: [\n    // Resource watchers (optional)\n  ],\n});\n```\n\n## Triggering Actions\n\nOnce attached, trigger actions on the session:\n\n```typescript\nimport { toSSEStream } from '@octavus/server-sdk';\n\n// trigger() returns an async generator of events\nconst events = session.trigger('user-message', {\n  USER_MESSAGE: 'How do I reset my password?',\n});\n\n// Convert to SSE stream for HTTP responses\nreturn new Response(toSSEStream(events), {\n  headers: { 'Content-Type': 'text/event-stream' },\n});\n```\n\n## Session Lifecycle\n\n```mermaid\nflowchart TD\n    A[1. CREATE] --> B[2. ATTACH]\n    B --> C[3. TRIGGER]\n    C --> C\n    C --> D[4. RETRIEVE]\n    D --> C\n    C --> E[5. EXPIRE]\n\n    A -.- A1[\"`**client.agentSessions.create()**\n    Returns sessionId\n    Initializes state`\"]\n    \n    B -.- B1[\"`**client.agentSessions.attach()**\n    Configure tool handlers\n    Configure resource watchers`\"]\n    \n    C -.- C1[\"`**session.trigger()**\n    Execute handler\n    Stream events\n    Update state`\"]\n    \n    D -.- D1[\"`**client.agentSessions.getMessages()**\n    Get UI-ready messages\n    Restore conversation`\"]\n    \n    E -.- E1[\"`Sessions expire after\n    24 hours (configurable)`\"]\n```\n\n## Restoring Sessions\n\nWhen a user returns to your app, restore their session:\n\n```typescript\n// On page load\nconst session = await client.agentSessions.getMessages(sessionId);\n\n// Pass messages to frontend - they're already UI-ready\nreturn {\n  sessionId: session.sessionId,\n  messages: session.messages,  // UIMessage[] with parts\n};\n```\n\nThe `messages` array contains `UIMessage` objects with properly structured `parts`, enabling direct use with the client SDK's `initialMessages` option.\n\n## Error Handling\n\n```typescript\nimport { ApiError } from '@octavus/server-sdk';\n\ntry {\n  const session = await client.agentSessions.getMessages(sessionId);\n} catch (error) {\n  if (error instanceof ApiError) {\n    if (error.status === 404) {\n      // Session not found or expired\n      console.log('Session expired, create a new one');\n    } else {\n      console.error('API Error:', error.message);\n    }\n  }\n  throw error;\n}\n```\n",
+    excerpt: "Sessions Sessions represent conversations with an agent. They store conversation history, track resources and variables, and enable stateful interactions.  Creating Sessions Create a session by...",
+    order: 2
+  },
+  {
+    slug: "server-sdk/tools",
+    section: "server-sdk",
+    title: "Tools",
+    description: "Implementing tool handlers with the Server SDK.",
+    content: "\n# Tools\n\nTools extend what agents can do. In Octavus, tools execute on your server, giving you full control over data access and authentication.\n\n## Why Tools Run on Your Server\n\nUnlike traditional AI platforms where tools run in a sandbox, Octavus tools execute in your backend:\n\n- \u2705 **Full data access** \u2014 Query your database directly\n- \u2705 **Your authentication** \u2014 Use your existing auth context\n- \u2705 **No data exposure** \u2014 Sensitive data never leaves your infrastructure\n- \u2705 **Custom logic** \u2014 Any complexity you need\n\n## Defining Tool Handlers\n\nTool handlers are async functions that receive arguments and return results:\n\n```typescript\nimport type { ToolHandlers } from '@octavus/server-sdk';\n\nconst tools: ToolHandlers = {\n  'get-user-account': async (args) => {\n    const userId = args.userId as string;\n    \n    // Query your database\n    const user = await db.users.findById(userId);\n    \n    return {\n      name: user.name,\n      email: user.email,\n      plan: user.subscription.plan,\n      createdAt: user.createdAt.toISOString(),\n    };\n  },\n  \n  'create-support-ticket': async (args) => {\n    const summary = args.summary as string;\n    const priority = args.priority as string;\n    \n    // Create ticket in your system\n    const ticket = await ticketService.create({\n      summary,\n      priority,\n      source: 'ai-chat',\n    });\n    \n    return {\n      ticketId: ticket.id,\n      estimatedResponse: getEstimatedResponse(priority),\n    };\n  },\n};\n```\n\n## Using Tools in Sessions\n\nPass tool handlers when attaching to a session:\n\n```typescript\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    'get-user-account': async (args) => {\n      // Implementation\n    },\n    'create-support-ticket': async (args) => {\n      // Implementation\n    },\n  },\n});\n```\n\n## Tool Handler Signature\n\n```typescript\ntype ToolHandler = (args: Record<string, unknown>) => Promise<unknown>;\ntype ToolHandlers = Record<string, ToolHandler>;\n```\n\n### Arguments\n\nArguments are passed as a `Record<string, unknown>`. Type-check as needed:\n\n```typescript\n'search-products': async (args) => {\n  const query = args.query as string;\n  const category = args.category as string | undefined;\n  const maxPrice = args.maxPrice as number | undefined;\n  \n  return await productSearch({ query, category, maxPrice });\n}\n```\n\n### Return Values\n\nReturn any JSON-serializable value. The result is:\n1. Sent back to the LLM as context\n2. Stored in session state\n3. Optionally stored in a variable for protocol use\n\n```typescript\n// Return object\nreturn { id: '123', status: 'created' };\n\n// Return array\nreturn [{ id: '1' }, { id: '2' }];\n\n// Return primitive\nreturn 42;\n\n// Return null for \"no result\"\nreturn null;\n```\n\n## Error Handling\n\nThrow errors for failures. They're captured and sent to the LLM:\n\n```typescript\n'get-user-account': async (args) => {\n  const userId = args.userId as string;\n  \n  const user = await db.users.findById(userId);\n  \n  if (!user) {\n    throw new Error(`User not found: ${userId}`);\n  }\n  \n  return user;\n}\n```\n\nThe LLM receives the error message and can respond appropriately (e.g., \"I couldn't find that account\").\n\n## Tool Execution Flow\n\nWhen the LLM calls a tool:\n\n```mermaid\nsequenceDiagram\n    participant LLM\n    participant Platform as Octavus Platform\n    participant SDK as Server SDK\n    participant UI as Your Frontend\n\n    LLM->>Platform: 1. Decides to call tool\n    Platform-->>UI: tool-input-start, tool-input-delta\n    Platform-->>UI: tool-input-available\n    Platform-->>SDK: 2. tool-request (stream pauses)\n    \n    Note over SDK: 3. Execute handler<br/>tools['get-user']()\n    \n    SDK-->>UI: 4. tool-output-available\n    SDK->>Platform: 5. POST /trigger with results\n    Platform->>LLM: 6. Continue with results\n    LLM-->>Platform: Response\n    Platform-->>UI: text-delta events\n    \n    Note over LLM,UI: 7. Repeat if more tools needed\n```\n\n## Accessing Request Context\n\nFor request-specific data (auth, headers), create handlers dynamically:\n\n```typescript\nimport { toSSEStream } from '@octavus/server-sdk';\n\n// In your API route\nexport async function POST(request: Request) {\n  const authToken = request.headers.get('Authorization');\n  const user = await validateToken(authToken);\n  \n  const session = client.agentSessions.attach(sessionId, {\n    tools: {\n      'get-user-account': async (args) => {\n        // Use request context\n        return await db.users.findById(user.id);\n      },\n      'create-order': async (args) => {\n        // Create with user context\n        return await orderService.create({\n          ...args,\n          userId: user.id,\n          createdBy: user.email,\n        });\n      },\n    },\n  });\n  \n  const events = session.trigger(triggerName, input);\n  return new Response(toSSEStream(events));\n}\n```\n\n## Best Practices\n\n### 1. Validate Arguments\n\n```typescript\n'create-ticket': async (args) => {\n  const summary = args.summary;\n  if (typeof summary !== 'string' || summary.length === 0) {\n    throw new Error('Summary is required');\n  }\n  // ...\n}\n```\n\n### 2. Handle Timeouts\n\n```typescript\n'external-api-call': async (args) => {\n  const controller = new AbortController();\n  const timeout = setTimeout(() => controller.abort(), 10000);\n  \n  try {\n    const response = await fetch(url, { signal: controller.signal });\n    return await response.json();\n  } finally {\n    clearTimeout(timeout);\n  }\n}\n```\n\n### 3. Log Tool Calls\n\n```typescript\n'search-products': async (args) => {\n  console.log('Tool call: search-products', { args });\n  \n  const result = await productSearch(args);\n  \n  console.log('Tool result: search-products', { \n    resultCount: result.length \n  });\n  \n  return result;\n}\n```\n\n",
+    excerpt: "Tools Tools extend what agents can do. In Octavus, tools execute on your server, giving you full control over data access and authentication.  Why Tools Run on Your Server Unlike traditional AI...",
+    order: 3
+  },
+  {
+    slug: "server-sdk/streaming",
+    section: "server-sdk",
+    title: "Streaming",
+    description: "Understanding stream events from the Server SDK.",
+    content: "\n# Streaming\n\nAll Octavus responses stream in real-time using Server-Sent Events (SSE). This enables responsive UX with incremental updates.\n\n## Stream Response\n\nWhen you trigger an action, you get an async generator of parsed events:\n\n```typescript\nimport { toSSEStream } from '@octavus/server-sdk';\n\n// trigger() returns an async generator of StreamEvent\nconst events = session.trigger('user-message', { \n  USER_MESSAGE: 'Hello!' \n});\n\n// For HTTP endpoints, convert to SSE stream\nreturn new Response(toSSEStream(events), {\n  headers: {\n    'Content-Type': 'text/event-stream',\n    'Cache-Control': 'no-cache',\n    'Connection': 'keep-alive',\n  },\n});\n\n// For sockets, iterate events directly\nfor await (const event of events) {\n  conn.write(JSON.stringify(event));\n}\n```\n\n## Event Types\n\nThe stream emits various event types. Octavus events align with the [Vercel AI SDK](https://sdk.vercel.ai/) naming conventions where applicable.\n\n### Lifecycle Events\n\n```typescript\n// Stream started\n{ type: 'start', messageId: '...' }\n\n// Stream completed\n{ type: 'finish', finishReason: 'stop' }\n\n// Possible finish reasons:\n// - 'stop': Normal completion\n// - 'tool-calls': Waiting for tool execution (handled by SDK)\n// - 'length': Max tokens reached\n// - 'content-filter': Content filtered\n// - 'error': Error occurred\n// - 'other': Other reason\n\n// Error event\n{ type: 'error', errorText: 'Something went wrong' }\n```\n\n### Block Events\n\nTrack execution progress:\n\n```typescript\n// Block started\n{ type: 'block-start', blockId: '...', blockName: 'Respond to user', blockType: 'next-message', display: 'stream', thread: 'main' }\n\n// Block completed\n{ type: 'block-end', blockId: '...', summary: 'Generated response' }\n```\n\n### Text Events\n\nStreaming text content:\n\n```typescript\n// Text generation started\n{ type: 'text-start', id: '...' }\n\n// Incremental text (most common event)\n{ type: 'text-delta', id: '...', delta: 'Hello' }\n{ type: 'text-delta', id: '...', delta: '!' }\n{ type: 'text-delta', id: '...', delta: ' How' }\n{ type: 'text-delta', id: '...', delta: ' can' }\n{ type: 'text-delta', id: '...', delta: ' I' }\n{ type: 'text-delta', id: '...', delta: ' help?' }\n\n// Text generation ended\n{ type: 'text-end', id: '...' }\n```\n\n### Reasoning Events\n\nExtended reasoning (for supported models like Claude):\n\n```typescript\n// Reasoning started\n{ type: 'reasoning-start', id: '...' }\n\n// Reasoning content\n{ type: 'reasoning-delta', id: '...', delta: 'Let me analyze this request...' }\n\n// Reasoning ended\n{ type: 'reasoning-end', id: '...' }\n```\n\n### Tool Events\n\nTool call lifecycle:\n\n```typescript\n// Tool input started\n{ type: 'tool-input-start', toolCallId: '...', toolName: 'get-user-account', title: 'Looking up account' }\n\n// Tool input/arguments streaming\n{ type: 'tool-input-delta', toolCallId: '...', inputTextDelta: '{\"userId\":\"user-123\"}' }\n\n// Tool input streaming ended\n{ type: 'tool-input-end', toolCallId: '...' }\n\n// Tool input is complete and available\n{ type: 'tool-input-available', toolCallId: '...', toolName: 'get-user-account', input: { userId: 'user-123' } }\n\n// Tool output available (success)\n{ type: 'tool-output-available', toolCallId: '...', output: { name: 'Demo User', email: '...' } }\n\n// Tool output error (failure)\n{ type: 'tool-output-error', toolCallId: '...', errorText: 'User not found' }\n```\n\n### Resource Events\n\nResource updates:\n\n```typescript\n{ type: 'resource-update', name: 'CONVERSATION_SUMMARY', value: 'User asked about...' }\n```\n\n## Display Modes\n\nEach block/tool specifies how it should appear to users:\n\n| Mode | Description |\n|------|-------------|\n| `hidden` | Not shown to user (background work) |\n| `name` | Shows block/tool name |\n| `description` | Shows description text |\n| `stream` | Streams content to chat |\n\n**Note**: Hidden events are filtered before reaching the client SDK. Your frontend only sees user-facing events.\n\n## Stream Event Type\n\n```typescript\ntype StreamEvent =\n  // Lifecycle\n  | StartEvent\n  | FinishEvent\n  | ErrorEvent\n  // Text\n  | TextStartEvent\n  | TextDeltaEvent\n  | TextEndEvent\n  // Reasoning\n  | ReasoningStartEvent\n  | ReasoningDeltaEvent\n  | ReasoningEndEvent\n  // Tool Input/Output\n  | ToolInputStartEvent\n  | ToolInputDeltaEvent\n  | ToolInputEndEvent\n  | ToolInputAvailableEvent\n  | ToolOutputAvailableEvent\n  | ToolOutputErrorEvent\n  // Octavus-Specific\n  | BlockStartEvent\n  | BlockEndEvent\n  | ResourceUpdateEvent\n  | ToolRequestEvent;\n```\n\n## Error Recovery\n\nThe SDK handles common error scenarios:\n\n```typescript\n// Network errors are caught and emitted\n{ type: 'error', errorText: 'Network request failed' }\n\n// Tool errors are captured per-tool\n{ type: 'tool-output-error', toolCallId: '...', errorText: 'Handler threw exception' }\n\n// The stream always ends with either 'finish' or 'error'\n```\n",
+    excerpt: "Streaming All Octavus responses stream in real-time using Server-Sent Events (SSE). This enables responsive UX with incremental updates.  Stream Response When you trigger an action, you get an async...",
+    order: 4
+  },
+  {
+    slug: "client-sdk/overview",
+    section: "client-sdk",
+    title: "Overview",
+    description: "Introduction to the Octavus Client SDKs for building chat interfaces.",
+    content: "\n# Client SDK Overview\n\nOctavus provides two packages for frontend integration:\n\n| Package | Purpose | Use When |\n|---------|---------|----------|\n| `@octavus/react` | React hooks and bindings | Building React applications |\n| `@octavus/client-sdk` | Framework-agnostic core | Using Vue, Svelte, vanilla JS, or custom integrations |\n\n**Most users should install `@octavus/react`** \u2014 it includes everything from `@octavus/client-sdk` plus React-specific hooks.\n\n## Installation\n\n### React Applications\n\n```bash\nnpm install @octavus/react\n```\n\n**Current version:** `0.0.7`\n\n### Other Frameworks\n\n```bash\nnpm install @octavus/client-sdk\n```\n\n**Current version:** `0.0.7`\n\n## Transport Pattern\n\nThe Client SDK uses a **transport abstraction** to handle communication with your backend. This gives you flexibility in how events are delivered:\n\n| Transport | Use Case | Docs |\n|-----------|----------|------|\n| `createHttpTransport` | HTTP/SSE (Next.js, Express, etc.) | [HTTP Transport](/docs/client-sdk/http-transport) |\n| `createSocketTransport` | WebSocket, SockJS, or other socket protocols | [Socket Transport](/docs/client-sdk/socket-transport) |\n\nWhen the transport changes (e.g., when `sessionId` changes), the `useOctavusChat` hook automatically reinitializes with the new transport.\n\n> **Recommendation**: Use HTTP transport unless you specifically need WebSocket features (custom real-time events, Meteor/Phoenix, etc.).\n\n## React Usage\n\nThe `useOctavusChat` hook provides state management and streaming for React applications:\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  // Create a stable transport instance (memoized on sessionId)\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { messages, status, send } = useOctavusChat({ transport });\n\n  const sendMessage = async (text: string) => {\n    await send(\n      'user-message',\n      { USER_MESSAGE: text },\n      { userMessage: { content: text } },\n    );\n  };\n\n  return (\n    <div>\n      {messages.map((msg) => (\n        <MessageBubble key={msg.id} message={msg} />\n      ))}\n    </div>\n  );\n}\n\nfunction MessageBubble({ message }: { message: UIMessage }) {\n  return (\n    <div>\n      {message.parts.map((part, i) => {\n        if (part.type === 'text') {\n          return <p key={i}>{part.text}</p>;\n        }\n        return null;\n      })}\n    </div>\n  );\n}\n```\n\n## Framework-Agnostic Usage\n\nThe `OctavusChat` class can be used with any framework or vanilla JavaScript:\n\n```typescript\nimport { OctavusChat, createHttpTransport } from '@octavus/client-sdk';\n\nconst transport = createHttpTransport({\n  triggerRequest: (triggerName, input) =>\n    fetch('/api/trigger', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ sessionId, triggerName, input }),\n    }),\n});\n\nconst chat = new OctavusChat({ transport });\n\n// Subscribe to state changes\nconst unsubscribe = chat.subscribe(() => {\n  console.log('Messages:', chat.messages);\n  console.log('Status:', chat.status);\n  // Update your UI here\n});\n\n// Send a message\nawait chat.send(\n  'user-message',\n  { USER_MESSAGE: 'Hello' },\n  { userMessage: { content: 'Hello' } },\n);\n\n// Cleanup when done\nunsubscribe();\n```\n\n## Key Features\n\n### Unified Send Function\n\nThe `send` function handles both user message display and agent triggering in one call:\n\n```tsx\nconst { send } = useOctavusChat({ transport });\n\n// Add user message to UI and trigger agent\nawait send(\n  'user-message',\n  { USER_MESSAGE: text },\n  { userMessage: { content: text } },\n);\n\n// Trigger without adding a user message (e.g., button click)\nawait send('request-human');\n```\n\n### Message Parts\n\nMessages contain ordered `parts` for rich content:\n\n```tsx\nconst { messages } = useOctavusChat({ transport });\n\n// Each message has typed parts\nmessage.parts.map((part) => {\n  switch (part.type) {\n    case 'text':       // Text content\n    case 'reasoning':  // Extended reasoning/thinking\n    case 'tool-call':  // Tool execution\n    case 'operation':  // Internal operations (set-resource, etc.)\n  }\n});\n```\n\n### Status Tracking\n\n```tsx\nconst { status } = useOctavusChat({ transport });\n\n// status: 'idle' | 'streaming' | 'error'\n```\n\n### Stop Streaming\n\n```tsx\nconst { stop } = useOctavusChat({ transport });\n\n// Stop current stream and finalize message\nstop();\n```\n\n## Hook Reference (React)\n\n### useOctavusChat\n\n```typescript\nfunction useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn;\n\ninterface OctavusChatOptions {\n  // Required: Transport for streaming events\n  transport: Transport;\n\n  // Optional: Pre-populate with existing messages (session restore)\n  initialMessages?: UIMessage[];\n\n  // Optional: Callbacks\n  onError?: (error: Error) => void;\n  onFinish?: () => void;\n  onResourceUpdate?: (name: string, value: unknown) => void;\n}\n\ninterface UseOctavusChatReturn {\n  // State\n  messages: UIMessage[];\n  status: ChatStatus;  // 'idle' | 'streaming' | 'error'\n  error: Error | null;\n\n  // Actions\n  send: (\n    triggerName: string,\n    input?: Record<string, unknown>,\n    options?: { userMessage?: UserMessageInput }\n  ) => Promise<void>;\n  stop: () => void;\n}\n\ninterface UserMessageInput {\n  content: string;\n}\n```\n\n## Transport Reference\n\n### createHttpTransport\n\nCreates an HTTP/SSE transport using native `fetch()`:\n\n```typescript\nimport { createHttpTransport } from '@octavus/react';\n\nconst transport = createHttpTransport({\n  triggerRequest: (triggerName, input) =>\n    fetch('/api/trigger', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ sessionId, triggerName, input }),\n    }),\n});\n```\n\n### createSocketTransport\n\nCreates a WebSocket/SockJS transport for real-time connections:\n\n```typescript\nimport { createSocketTransport } from '@octavus/react';\n\nconst transport = createSocketTransport({\n  connect: () =>\n    new Promise((resolve, reject) => {\n      const ws = new WebSocket(`wss://api.example.com/stream?sessionId=${sessionId}`);\n      ws.onopen = () => resolve(ws);\n      ws.onerror = () => reject(new Error('Connection failed'));\n    }),\n});\n```\n\nFor detailed WebSocket/SockJS usage including custom events, reconnection patterns, and server-side implementation, see [Socket Transport](/docs/client-sdk/socket-transport).\n\n## Class Reference (Framework-Agnostic)\n\n### OctavusChat\n\n```typescript\nclass OctavusChat {\n  constructor(options: OctavusChatOptions);\n\n  // State (read-only)\n  readonly messages: UIMessage[];\n  readonly status: ChatStatus;\n  readonly error: Error | null;\n\n  // Actions\n  send(\n    triggerName: string,\n    input?: Record<string, unknown>,\n    options?: { userMessage?: UserMessageInput }\n  ): Promise<void>;\n  stop(): void;\n\n  // Subscription\n  subscribe(callback: () => void): () => void;  // Returns unsubscribe function\n}\n```\n\n## Next Steps\n\n- [HTTP Transport](/docs/client-sdk/http-transport) \u2014 HTTP/SSE integration (recommended)\n- [Socket Transport](/docs/client-sdk/socket-transport) \u2014 WebSocket and SockJS integration\n- [Messages](/docs/client-sdk/messages) \u2014 Working with message state\n- [Streaming](/docs/client-sdk/streaming) \u2014 Building streaming UIs\n- [Operations](/docs/client-sdk/execution-blocks) \u2014 Showing agent progress\n- [Examples](/docs/examples/overview) \u2014 Complete working examples\n",
+    excerpt: "Client SDK Overview Octavus provides two packages for frontend integration: | Package | Purpose | Use When | |---------|---------|----------| |  | React hooks and bindings | Building React...",
+    order: 1
+  },
+  {
+    slug: "client-sdk/messages",
+    section: "client-sdk",
+    title: "Messages",
+    description: "Working with message state in the Client SDK.",
+    content: "\n# Messages\n\nMessages represent the conversation history. The Client SDK tracks messages automatically and provides structured access to their content through typed parts.\n\n## Message Structure\n\n```typescript\ninterface UIMessage {\n  id: string;\n  role: 'user' | 'assistant';\n  parts: UIMessagePart[];\n  status: 'streaming' | 'done';\n  createdAt: Date;\n}\n```\n\n### Message Parts\n\nMessages contain ordered `parts` that preserve content ordering:\n\n```typescript\ntype UIMessagePart =\n  | UITextPart\n  | UIReasoningPart\n  | UIToolCallPart\n  | UIOperationPart;\n\n// Text content\ninterface UITextPart {\n  type: 'text';\n  text: string;\n  status: 'streaming' | 'done';\n  thread?: string;  // For named threads (e.g., \"summary\")\n}\n\n// Extended reasoning/thinking\ninterface UIReasoningPart {\n  type: 'reasoning';\n  text: string;\n  status: 'streaming' | 'done';\n  thread?: string;\n}\n\n// Tool execution\ninterface UIToolCallPart {\n  type: 'tool-call';\n  toolCallId: string;\n  toolName: string;\n  displayName?: string;  // Human-readable name\n  args: Record<string, unknown>;\n  result?: unknown;\n  error?: string;\n  status: 'pending' | 'running' | 'done' | 'error';\n  thread?: string;\n}\n\n// Internal operations (set-resource, serialize-thread)\ninterface UIOperationPart {\n  type: 'operation';\n  operationId: string;\n  name: string;\n  operationType: string;\n  status: 'running' | 'done';\n  thread?: string;\n}\n```\n\n## Sending Messages\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { send } = useOctavusChat({ transport });\n\n  async function handleSend(text: string) {\n    // Add user message to UI and trigger agent\n    await send(\n      'user-message',\n      { USER_MESSAGE: text },\n      { userMessage: { content: text } },\n    );\n  }\n\n  // ...\n}\n```\n\nThe `send` function:\n1. Adds the user message to the UI immediately (if `userMessage` is provided)\n2. Triggers the agent with the specified trigger name and input\n3. Streams the assistant's response back\n\n## Rendering Messages\n\n### Basic Rendering\n\n```tsx\nfunction MessageList({ messages }: { messages: UIMessage[] }) {\n  return (\n    <div className=\"space-y-4\">\n      {messages.map((msg) => (\n        <MessageBubble key={msg.id} message={msg} />\n      ))}\n    </div>\n  );\n}\n\nfunction MessageBubble({ message }: { message: UIMessage }) {\n  const isUser = message.role === 'user';\n\n  return (\n    <div className={isUser ? 'text-right' : 'text-left'}>\n      <div className=\"inline-block p-3 rounded-lg\">\n        {message.parts.map((part, i) => (\n          <PartRenderer key={i} part={part} />\n        ))}\n      </div>\n    </div>\n  );\n}\n```\n\n### Rendering Parts\n\n```tsx\nimport { isOtherThread, type UIMessagePart } from '@octavus/react';\n\nfunction PartRenderer({ part }: { part: UIMessagePart }) {\n  // Check if part belongs to a named thread (e.g., \"summary\")\n  if (isOtherThread(part)) {\n    return <OtherThreadPart part={part} />;\n  }\n\n  switch (part.type) {\n    case 'text':\n      return <TextPart part={part} />;\n\n    case 'reasoning':\n      return (\n        <details className=\"text-gray-500\">\n          <summary>Thinking...</summary>\n          <pre className=\"text-sm\">{part.text}</pre>\n        </details>\n      );\n\n    case 'tool-call':\n      return (\n        <div className=\"bg-gray-100 p-2 rounded text-sm\">\n          \u{1F527} {part.displayName || part.toolName}\n          {part.status === 'done' && ' \u2713'}\n          {part.status === 'error' && ` \u2717 ${part.error}`}\n        </div>\n      );\n\n    case 'operation':\n      return (\n        <div className=\"text-gray-500 text-sm\">\n          {part.name}\n          {part.status === 'done' && ' \u2713'}\n        </div>\n      );\n\n    default:\n      return null;\n  }\n}\n\nfunction TextPart({ part }: { part: UITextPart }) {\n  return (\n    <p>\n      {part.text}\n      {part.status === 'streaming' && (\n        <span className=\"inline-block w-2 h-4 bg-gray-400 animate-pulse ml-1\" />\n      )}\n    </p>\n  );\n}\n```\n\n## Named Threads\n\nContent from named threads (like \"summary\") is identified by the `thread` property. Use the `isOtherThread` helper:\n\n```tsx\nimport { isOtherThread } from '@octavus/react';\n\nfunction PartRenderer({ part }: { part: UIMessagePart }) {\n  if (isOtherThread(part)) {\n    // Render differently for named threads\n    return (\n      <div className=\"bg-amber-50 p-2 rounded border border-amber-200\">\n        <span className=\"text-amber-600 text-sm\">\n          {part.thread}: {part.type === 'text' && part.text}\n        </span>\n      </div>\n    );\n  }\n\n  // Regular rendering for main thread\n  // ...\n}\n```\n\n## Session Restore\n\nWhen restoring a session, fetch messages from your backend and pass them to the hook:\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';\n\ninterface ChatProps {\n  sessionId: string;\n  initialMessages: UIMessage[];\n}\n\nfunction Chat({ sessionId, initialMessages }: ChatProps) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  // Pass existing messages to restore the conversation\n  const { messages } = useOctavusChat({\n    transport,\n    initialMessages,\n  });\n\n  // ...\n}\n```\n\nOn your backend, use `agentSessions.getMessages()` to fetch UI-ready messages:\n\n```typescript\n// Server-side\nconst session = await client.agentSessions.getMessages(sessionId);\n// session.messages is UIMessage[] ready for the client\n```\n\n## Callbacks\n\n```tsx\nuseOctavusChat({\n  transport,\n  onFinish: () => {\n    console.log('Stream completed');\n    // Scroll to bottom, play sound, etc.\n  },\n  onError: (error) => {\n    console.error('Error:', error);\n    toast.error('Failed to get response');\n  },\n  onResourceUpdate: (name, value) => {\n    console.log('Resource updated:', name, value);\n  },\n});\n```\n",
+    excerpt: "Messages Messages represent the conversation history. The Client SDK tracks messages automatically and provides structured access to their content through typed parts.  Message Structure  Message...",
+    order: 2
+  },
+  {
+    slug: "client-sdk/streaming",
+    section: "client-sdk",
+    title: "Streaming",
+    description: "Building streaming UIs with the Client SDK.",
+    content: "\n# Streaming\n\nThe Client SDK provides real-time access to streaming content through the message `parts` array. Each part has its own status, enabling responsive UIs that update as the agent generates responses.\n\n## Streaming State\n\n```tsx\nconst { messages, status, error } = useOctavusChat({ transport });\n\n// status: 'idle' | 'streaming' | 'error'\n// Each message has status: 'streaming' | 'done'\n// Each part has its own status too\n```\n\n## Building a Streaming UI\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { messages, status, error, send, stop } = useOctavusChat({ transport });\n\n  return (\n    <div>\n      {/* Messages with streaming parts */}\n      {messages.map((msg) => (\n        <MessageBubble key={msg.id} message={msg} />\n      ))}\n\n      {/* Error state */}\n      {error && <div className=\"text-red-500\">{error.message}</div>}\n\n      {/* Stop button during streaming */}\n      {status === 'streaming' && <button onClick={stop}>Stop</button>}\n    </div>\n  );\n}\n```\n\n## Rendering Streaming Parts\n\nParts update in real-time during streaming. Use the part's `status` to show appropriate UI:\n\n```tsx\nimport type { UITextPart, UIReasoningPart } from '@octavus/react';\n\nfunction TextPart({ part }: { part: UITextPart }) {\n  return (\n    <div>\n      {part.text}\n      {part.status === 'streaming' && (\n        <span className=\"inline-block w-2 h-4 bg-gray-400 animate-pulse ml-1\" />\n      )}\n    </div>\n  );\n}\n\nfunction ReasoningPart({ part }: { part: UIReasoningPart }) {\n  // Expand while streaming, collapse when done\n  const [expanded, setExpanded] = useState(part.status === 'streaming');\n\n  return (\n    <div className=\"bg-purple-50 p-3 rounded-lg\">\n      <button onClick={() => setExpanded(!expanded)}>\n        {part.status === 'streaming' ? '\u{1F4AD} Thinking...' : '\u{1F4AD} Thought process'}\n        {expanded ? '\u25BC' : '\u25B6'}\n      </button>\n\n      {expanded && (\n        <pre className=\"mt-2 text-sm text-gray-600\">{part.text}</pre>\n      )}\n    </div>\n  );\n}\n```\n\n## Tool Call States\n\nTool calls progress through multiple states:\n\n```tsx\nimport type { UIToolCallPart } from '@octavus/react';\n\nfunction ToolCallPart({ part }: { part: UIToolCallPart }) {\n  return (\n    <div className=\"border rounded p-3\">\n      <div className=\"flex items-center gap-2\">\n        <span className=\"text-lg\">\u{1F527}</span>\n        <span className=\"font-medium\">{part.displayName || part.toolName}</span>\n        <StatusBadge status={part.status} />\n      </div>\n\n      {/* Show result when done */}\n      {part.status === 'done' && part.result && (\n        <pre className=\"mt-2 text-xs bg-gray-50 p-2 rounded\">\n          {JSON.stringify(part.result, null, 2)}\n        </pre>\n      )}\n\n      {/* Show error if failed */}\n      {part.status === 'error' && (\n        <p className=\"mt-2 text-red-500 text-sm\">{part.error}</p>\n      )}\n    </div>\n  );\n}\n\nfunction StatusBadge({ status }: { status: UIToolCallPart['status'] }) {\n  switch (status) {\n    case 'pending':\n      return <span className=\"text-gray-400\">\u25CB</span>;\n    case 'running':\n      return <span className=\"text-blue-500 animate-spin\">\u25D0</span>;\n    case 'done':\n      return <span className=\"text-green-500\">\u2713</span>;\n    case 'error':\n      return <span className=\"text-red-500\">\u2717</span>;\n  }\n}\n```\n\n## Status Indicator\n\n```tsx\nfunction StatusIndicator({ status }: { status: ChatStatus }) {\n  switch (status) {\n    case 'idle':\n      return null;\n    case 'streaming':\n      return <div>Agent is responding...</div>;\n    case 'error':\n      return <div className=\"text-red-500\">Something went wrong</div>;\n  }\n}\n```\n\n## Handling Completion\n\n```tsx\nuseOctavusChat({\n  transport,\n  onFinish: () => {\n    console.log('Stream completed');\n    // Scroll to bottom, play sound, etc.\n  },\n  onError: (error) => {\n    console.error('Stream error:', error);\n    toast.error('Failed to get response');\n  },\n});\n```\n\n## Stop Function\n\nStop the current stream and finalize any partial message:\n\n```tsx\nconst { status, stop } = useOctavusChat({ transport });\n\n// Stop button\n{status === 'streaming' && (\n  <button onClick={stop} className=\"text-gray-500\">\n    Stop generating\n  </button>\n)}\n```\n\nWhen `stop()` is called:\n1. The current request is aborted\n2. Any partial message is finalized with current content\n3. Status changes to `'idle'`\n\n## Named Thread Content\n\nContent from named threads (like \"summary\") streams separately and is identified by the `thread` property:\n\n```tsx\nimport { isOtherThread, type UIMessage } from '@octavus/react';\n\nfunction MessageBubble({ message }: { message: UIMessage }) {\n  // Separate main thread from named threads\n  const mainParts = message.parts.filter((p) => !isOtherThread(p));\n  const otherParts = message.parts.filter((p) => isOtherThread(p));\n\n  return (\n    <div>\n      {/* Main conversation */}\n      {mainParts.map((part, i) => (\n        <PartRenderer key={i} part={part} />\n      ))}\n\n      {/* Named thread content (e.g., summarization) */}\n      {otherParts.length > 0 && (\n        <div className=\"bg-amber-50 p-3 rounded mt-4 border border-amber-200\">\n          <div className=\"text-amber-600 font-medium mb-2\">\n            Background processing\n          </div>\n          {otherParts.map((part, i) => (\n            <PartRenderer key={i} part={part} />\n          ))}\n        </div>\n      )}\n    </div>\n  );\n}\n```\n",
+    excerpt: "Streaming The Client SDK provides real-time access to streaming content through the message  array. Each part has its own status, enabling responsive UIs that update as the agent generates responses....",
+    order: 3
+  },
+  {
+    slug: "client-sdk/execution-blocks",
+    section: "client-sdk",
+    title: "Operations",
+    description: "Showing agent operations and progress with the Client SDK.",
+    content: "\n# Operations\n\nOperations represent internal agent activities like setting resources or serializing threads. They appear as `operation` parts in messages and help users understand what the agent is doing.\n\n## Operation Structure\n\n```typescript\ninterface UIOperationPart {\n  type: 'operation';\n  operationId: string;\n  name: string;           // Human-readable name\n  operationType: string;  // e.g., 'set-resource', 'serialize-thread'\n  status: 'running' | 'done';\n  thread?: string;        // For named threads\n}\n```\n\n## Rendering Operations\n\nOperations are typically shown as compact status indicators:\n\n```tsx\nimport type { UIOperationPart } from '@octavus/react';\n\nfunction OperationCard({ operation }: { operation: UIOperationPart }) {\n  return (\n    <div className=\"flex items-center gap-2 text-sm text-gray-500\">\n      {operation.status === 'running' ? (\n        <span className=\"h-2 w-2 animate-pulse rounded-full bg-blue-500\" />\n      ) : (\n        <span className=\"text-green-500\">\u2713</span>\n      )}\n      <span>{operation.name}</span>\n    </div>\n  );\n}\n```\n\n## Operations in Messages\n\nOperations appear alongside text, reasoning, and tool calls in the message's `parts` array:\n\n```tsx\nimport type { UIMessage, UIMessagePart } from '@octavus/react';\n\nfunction MessageBubble({ message }: { message: UIMessage }) {\n  return (\n    <div>\n      {message.parts.map((part, i) => (\n        <PartRenderer key={i} part={part} />\n      ))}\n    </div>\n  );\n}\n\nfunction PartRenderer({ part }: { part: UIMessagePart }) {\n  switch (part.type) {\n    case 'text':\n      return <TextPart part={part} />;\n    case 'reasoning':\n      return <ReasoningPart part={part} />;\n    case 'tool-call':\n      return <ToolCallCard part={part} />;\n    case 'operation':\n      return <OperationCard operation={part} />;\n    default:\n      return null;\n  }\n}\n```\n\n## Common Operation Types\n\n| Type | Description |\n|------|-------------|\n| `set-resource` | Updating a resource value |\n| `serialize-thread` | Converting thread messages to text |\n\n## Example: Progress During Escalation\n\nWhen a user clicks \"Talk to Human\", multiple operations may occur:\n\n```tsx\nfunction EscalationProgress({ message }: { message: UIMessage }) {\n  const operations = message.parts.filter(\n    (p): p is UIOperationPart => p.type === 'operation'\n  );\n\n  return (\n    <div className=\"space-y-2\">\n      {operations.map((op) => (\n        <div key={op.operationId} className=\"flex items-center gap-2 text-sm\">\n          {op.status === 'running' ? '\u23F3' : '\u2713'}\n          <span>{op.name}</span>\n        </div>\n      ))}\n    </div>\n  );\n}\n\n// Example output during escalation:\n// \u2713 Serialize conversation\n// \u2713 Save conversation summary\n// \u23F3 Creating support ticket...\n```\n\n## Display Modes\n\nOperations are only sent to the client if their protocol block has a visible display mode (`name`, `description`, or `stream`). Hidden operations (`display: hidden`) are filtered out by the platform before reaching the client.\n\nThis means you can safely render all operations without checking display mode \u2014 hidden ones won't be in the message parts.\n\n## Named Thread Operations\n\nOperations can belong to named threads. Use the `thread` property to identify them:\n\n```tsx\nfunction OperationCard({ operation }: { operation: UIOperationPart }) {\n  return (\n    <div className=\"flex items-center gap-2 text-sm\">\n      {operation.thread && (\n        <span className=\"text-amber-500\">[{operation.thread}]</span>\n      )}\n      <span>{operation.name}</span>\n      {operation.status === 'done' && <span className=\"text-green-500\">\u2713</span>}\n    </div>\n  );\n}\n```\n",
+    excerpt: "Operations Operations represent internal agent activities like setting resources or serializing threads. They appear as  parts in messages and help users understand what the agent is doing. ...",
+    order: 4
+  },
+  {
+    slug: "client-sdk/socket-transport",
+    section: "client-sdk",
+    title: "Socket Transport",
+    description: "Using WebSocket or SockJS for real-time streaming with Octavus.",
+    content: "\n# Socket Transport\n\nThe socket transport enables real-time bidirectional communication using WebSocket or SockJS. Use this when you need persistent connections, custom server events, or when HTTP/SSE isn't suitable for your infrastructure.\n\n## When to Use Socket Transport\n\n| Use Case | Recommended Transport |\n|----------|----------------------|\n| Standard web apps (Next.js, etc.) | HTTP (`createHttpTransport`) |\n| Real-time apps with custom events | Socket (`createSocketTransport`) |\n| Apps behind proxies that don't support SSE | Socket |\n| Need for typing indicators, presence, etc. | Socket |\n| Meteor, Phoenix, or socket-based frameworks | Socket |\n\n## Patterns Overview\n\nThere are two main patterns for socket-based integrations:\n\n| Pattern | When to Use |\n|---------|-------------|\n| [Server-Managed Sessions](#server-managed-sessions-recommended) | **Recommended.** Server creates sessions lazily. Client doesn't need sessionId. |\n| [Client-Provided Session ID](#client-provided-session-id) | When client must control session creation or pass sessionId from URL. |\n\n## Server-Managed Sessions (Recommended)\n\nThe cleanest pattern is to have the server manage session lifecycle. The client never needs to know about `sessionId` \u2014 the server creates it lazily on first message.\n\n### Client Setup\n\n```typescript\nimport { useMemo } from 'react';\nimport SockJS from 'sockjs-client';\nimport { useOctavusChat, createSocketTransport, type SocketLike } from '@octavus/react';\n\nfunction connectSocket(): Promise<SocketLike> {\n  return new Promise((resolve, reject) => {\n    const sock = new SockJS('/octavus');\n    sock.onopen = () => resolve(sock);\n    sock.onerror = () => reject(new Error('Connection failed'));\n  });\n}\n\nfunction Chat() {\n  // Transport is stable \u2014 no dependencies on sessionId\n  const transport = useMemo(\n    () => createSocketTransport({ connect: connectSocket }),\n    [],\n  );\n\n  const { messages, status, send } = useOctavusChat({ transport });\n\n  const sendMessage = async (text: string) => {\n    await send(\n      'user-message',\n      { USER_MESSAGE: text },\n      { userMessage: { content: text } },\n    );\n  };\n\n  // ... render messages\n}\n```\n\n### Server Setup (Express + SockJS)\n\nThe server creates a session on first trigger message:\n\n```typescript\nimport sockjs from 'sockjs';\nimport { OctavusClient, type AgentSession } from '@octavus/server-sdk';\n\nconst client = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n\nfunction createSocketHandler() {\n  return (conn: sockjs.Connection) => {\n    let session: AgentSession | null = null;\n    let abortController: AbortController | null = null;\n\n    conn.on('data', (rawData: string) => {\n      void handleMessage(rawData);\n    });\n\n    async function handleMessage(rawData: string) {\n      const msg = JSON.parse(rawData);\n\n      if (msg.type === 'stop') {\n        abortController?.abort();\n        return;\n      }\n\n      if (msg.type === 'trigger') {\n        // Create session lazily on first trigger\n        if (!session) {\n          const sessionId = await client.agentSessions.create('your-agent-id', {\n            // Initial input variables\n            COMPANY_NAME: 'Acme Corp',\n          });\n          session = client.agentSessions.attach(sessionId, {\n            tools: {\n              // Your tool handlers\n            },\n          });\n        }\n\n        abortController = new AbortController();\n\n        // Iterate events directly \u2014 no SSE parsing needed\n        const events = session.trigger(msg.triggerName, msg.input);\n\n        try {\n          for await (const event of events) {\n            if (abortController.signal.aborted) break;\n            conn.write(JSON.stringify(event));\n          }\n        } catch {\n          // Handle errors\n        }\n      }\n    }\n\n    conn.on('close', () => abortController?.abort());\n  };\n}\n\nconst sockServer = sockjs.createServer({ prefix: '/octavus' });\nsockServer.on('connection', createSocketHandler());\nsockServer.installHandlers(httpServer);\n```\n\n**Benefits of this pattern:**\n- Client code is simple \u2014 no sessionId management\n- No transport caching issues\n- Session is created only when needed\n- Server controls session configuration\n\n## Client-Provided Session ID\n\nIf you need the client to control the session (e.g., resuming a specific session from URL), pass the sessionId in an init message after connecting:\n\n```typescript\nimport { useMemo } from 'react';\nimport SockJS from 'sockjs-client';\nimport { useOctavusChat, createSocketTransport, type SocketLike } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createSocketTransport({\n        connect: () =>\n          new Promise((resolve, reject) => {\n            const sock = new SockJS('/octavus');\n            sock.onopen = () => {\n              // Send init message with sessionId\n              sock.send(JSON.stringify({ type: 'init', sessionId }));\n              resolve(sock);\n            };\n            sock.onerror = () => reject(new Error('Connection failed'));\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { messages, status, send } = useOctavusChat({ transport });\n  // ... render chat\n}\n```\n\nWhen `sessionId` changes, the hook automatically reinitializes with the new transport.\n\n### Server Handler with Init Message\n\nWhen using client-provided sessionId, the server must handle an `init` message:\n\n```typescript\nsockServer.on('connection', (conn) => {\n  let session: AgentSession | null = null;\n  let abortController: AbortController | null = null;\n\n  conn.on('data', (rawData: string) => {\n    void handleMessage(rawData);\n  });\n\n  async function handleMessage(rawData: string) {\n    const msg = JSON.parse(rawData);\n\n    // Handle session initialization\n    if (msg.type === 'init') {\n      session = client.agentSessions.attach(msg.sessionId, {\n        tools: { /* ... */ },\n      });\n      return;\n    }\n\n    if (msg.type === 'stop') {\n      abortController?.abort();\n      return;\n    }\n\n    // All other messages require initialized session\n    if (!session) {\n      conn.write(JSON.stringify({\n        type: 'error',\n        errorText: 'Session not initialized. Send init message first.',\n      }));\n      return;\n    }\n\n    if (msg.type === 'trigger') {\n      // ... handle trigger (same as server-managed pattern)\n    }\n  }\n});\n```\n\n## Async Session ID\n\nWhen the session ID is fetched asynchronously (e.g., from an API), you have two options:\n\n### Option 1: Conditionally Render (Recommended)\n\nDon't render the chat component until `sessionId` is available:\n\n```tsx\nfunction ChatPage() {\n  const [sessionId, setSessionId] = useState<string | null>(null);\n\n  useEffect(() => {\n    api.createSession().then(res => setSessionId(res.sessionId));\n  }, []);\n\n  // Don't render until sessionId is ready\n  if (!sessionId) {\n    return <LoadingSpinner />;\n  }\n\n  return <Chat sessionId={sessionId} />;\n}\n```\n\nThis is the cleanest approach \u2014 the `Chat` component always receives a valid `sessionId`.\n\n### Option 2: Server-Managed Sessions\n\nUse the [server-managed sessions pattern](#server-managed-sessions-recommended) where the server creates the session lazily. The client never needs to know about `sessionId`.\n\n## Native WebSocket\n\nIf you're using native WebSocket instead of SockJS, you can pass sessionId via URL:\n\n```typescript\nconst transport = useMemo(\n  () =>\n    createSocketTransport({\n      connect: () =>\n        new Promise((resolve, reject) => {\n          const ws = new WebSocket(\n            `wss://your-server.com/octavus?sessionId=${sessionId}`\n          );\n          ws.onopen = () => resolve(ws);\n          ws.onerror = () => reject(new Error('WebSocket connection failed'));\n        }),\n    }),\n  [sessionId],\n);\n```\n\nWhen `sessionId` changes, the hook automatically reinitializes with the new transport.\n\n## Custom Events\n\nHandle custom events alongside Octavus stream events:\n\n```typescript\nconst transport = createSocketTransport({\n  connect: connectSocket,\n\n  onMessage: (data) => {\n    const msg = data as { type: string; [key: string]: unknown };\n\n    switch (msg.type) {\n      case 'typing-indicator':\n        setAgentTyping(msg.isTyping as boolean);\n        break;\n\n      case 'presence-update':\n        setOnlineUsers(msg.users as string[]);\n        break;\n\n      case 'notification':\n        showToast(msg.message as string);\n        break;\n\n      // Octavus events (text-delta, finish, etc.) are handled automatically\n    }\n  },\n});\n```\n\n## Connection Management\n\n### Handling Disconnections\n\n```typescript\nconst transport = createSocketTransport({\n  connect: connectSocket,\n\n  onClose: () => {\n    console.log('Socket disconnected');\n    setConnectionStatus('disconnected');\n  },\n});\n```\n\n### Reconnection with Exponential Backoff\n\n```typescript\nimport { useRef, useCallback, useMemo } from 'react';\nimport { createSocketTransport, type SocketLike } from '@octavus/react';\n\nfunction useReconnectingTransport() {\n  const reconnectAttempts = useRef(0);\n  const maxAttempts = 5;\n\n  const connect = useCallback((): Promise<SocketLike> => {\n    return new Promise((resolve, reject) => {\n      const sock = new SockJS('/octavus');\n\n      sock.onopen = () => {\n        reconnectAttempts.current = 0;\n        resolve(sock);\n      };\n\n      sock.onerror = () => {\n        if (reconnectAttempts.current < maxAttempts) {\n          reconnectAttempts.current++;\n          const delay = Math.min(1000 * 2 ** reconnectAttempts.current, 30000);\n          console.log(`Reconnecting in ${delay}ms...`);\n          setTimeout(() => connect().then(resolve).catch(reject), delay);\n        } else {\n          reject(new Error('Max reconnection attempts reached'));\n        }\n      };\n    });\n  }, []);\n\n  return useMemo(\n    () => createSocketTransport({ connect }),\n    [connect],\n  );\n}\n```\n\n## Framework Notes\n\n### Meteor\n\nMeteor's bundler may have issues with ES6 imports of `sockjs-client`. Use `require()` instead:\n\n```typescript\n// \u274C May fail in Meteor\nimport SockJS from 'sockjs-client';\n\n// \u2705 Works in Meteor\nconst SockJS: typeof import('sockjs-client') = require('sockjs-client');\n```\n\n### SockJS vs WebSocket\n\n| Feature | WebSocket | SockJS |\n|---------|-----------|--------|\n| Browser support | Modern browsers | All browsers (with fallbacks) |\n| Session ID | Via URL query params | Via init message |\n| Proxy compatibility | Varies | Excellent (polling fallback) |\n| Setup complexity | Lower | Higher (requires server library) |\n\n## Protocol Reference\n\n### Client \u2192 Server Messages\n\n```typescript\n// Initialize session (only for client-provided sessionId pattern)\n{ type: 'init', sessionId: string }\n\n// Trigger an action\n{ type: 'trigger', triggerName: string, input?: Record<string, unknown> }\n\n// Stop current stream\n{ type: 'stop' }\n```\n\n### Server \u2192 Client Messages\n\nThe server sends Octavus `StreamEvent` objects as JSON. See [Streaming Events](/docs/server-sdk/streaming#event-types) for the full list.\n\n```typescript\n// Examples\n{ type: 'start', messageId: '...' }\n{ type: 'text-delta', id: '...', delta: 'Hello' }\n{ type: 'tool-input-start', toolCallId: '...', toolName: 'get-user' }\n{ type: 'finish', finishReason: 'stop' }\n{ type: 'error', errorText: 'Something went wrong' }\n```\n\n## Full Example\n\nFor a complete walkthrough of building a chat interface with SockJS, see the [Socket Chat Example](/docs/examples/socket-chat).\n",
+    excerpt: "Socket Transport The socket transport enables real-time bidirectional communication using WebSocket or SockJS. Use this when you need persistent connections, custom server events, or when HTTP/SSE...",
+    order: 5
+  },
+  {
+    slug: "client-sdk/http-transport",
+    section: "client-sdk",
+    title: "HTTP Transport",
+    description: "Using HTTP/SSE for streaming with Octavus in Next.js, Express, and other frameworks.",
+    content: "\n# HTTP Transport\n\nThe HTTP transport uses standard HTTP requests with Server-Sent Events (SSE) for streaming. This is the simplest and most compatible transport option.\n\n## When to Use HTTP Transport\n\n| Use Case | Recommendation |\n|----------|----------------|\n| Next.js, Remix, or similar frameworks | \u2705 Use HTTP |\n| Standard web apps without special requirements | \u2705 Use HTTP |\n| Serverless deployments (Vercel, etc.) | \u2705 Use HTTP |\n| Need custom real-time events | Consider [Socket Transport](/docs/client-sdk/socket-transport) |\n\n## Basic Setup\n\n### Client\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { messages, status, error, send, stop } = useOctavusChat({ transport });\n\n  const sendMessage = async (text: string) => {\n    await send(\n      'user-message',\n      { USER_MESSAGE: text },\n      { userMessage: { content: text } },\n    );\n  };\n\n  // ... render chat\n}\n```\n\n### Server (Next.js API Route)\n\n```typescript\n// app/api/trigger/route.ts\nimport { OctavusClient, toSSEStream } from '@octavus/server-sdk';\n\nconst client = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n\nexport async function POST(request: Request) {\n  const { sessionId, triggerName, input } = await request.json();\n\n  const session = client.agentSessions.attach(sessionId, {\n    tools: {\n      'get-user-account': async (args) => {\n        return { name: 'Demo User', plan: 'pro' };\n      },\n    },\n  });\n\n  // trigger() returns parsed events, toSSEStream() converts to SSE format\n  const events = session.trigger(triggerName, input);\n\n  return new Response(toSSEStream(events), {\n    headers: {\n      'Content-Type': 'text/event-stream',\n      'Cache-Control': 'no-cache',\n      Connection: 'keep-alive',\n    },\n  });\n}\n```\n\n## Session Creation\n\nSessions should be created server-side before rendering the chat. There are two patterns:\n\n### Pattern 1: Create Session on Page Load\n\n```tsx\n// app/chat/page.tsx\n'use client';\n\nimport { useEffect, useState } from 'react';\nimport { Chat } from '@/components/Chat';\n\nexport default function ChatPage() {\n  const [sessionId, setSessionId] = useState<string | null>(null);\n\n  useEffect(() => {\n    fetch('/api/sessions', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({\n        agentId: 'your-agent-id',\n        input: { COMPANY_NAME: 'Acme Corp' },\n      }),\n    })\n      .then(res => res.json())\n      .then(data => setSessionId(data.sessionId));\n  }, []);\n\n  if (!sessionId) {\n    return <LoadingSpinner />;\n  }\n\n  return <Chat sessionId={sessionId} />;\n}\n```\n\n### Pattern 2: Server-Side Session Creation (App Router)\n\n```tsx\n// app/chat/page.tsx\nimport { octavus } from '@/lib/octavus';\nimport { Chat } from '@/components/Chat';\n\nexport default async function ChatPage() {\n  // Create session server-side\n  const sessionId = await octavus.agentSessions.create('your-agent-id', {\n    COMPANY_NAME: 'Acme Corp',\n  });\n\n  return <Chat sessionId={sessionId} />;\n}\n```\n\nThis pattern is cleaner as the session is ready before the component renders.\n\n## Error Handling\n\nHandle errors in both the transport and the hook:\n\n```tsx\nconst { messages, status, error, send } = useOctavusChat({\n  transport,\n  onError: (err) => {\n    console.error('Stream error:', err);\n    // Show toast, update UI, etc.\n  },\n});\n\n// Also check error state\nif (error) {\n  return <ErrorMessage error={error} />;\n}\n```\n\n## Stop Streaming\n\nAllow users to cancel ongoing streams:\n\n```tsx\nconst { send, stop, status } = useOctavusChat({ transport });\n\nreturn (\n  <button\n    onClick={status === 'streaming' ? stop : () => sendMessage()}\n    disabled={status === 'streaming' && !inputValue}\n  >\n    {status === 'streaming' ? 'Stop' : 'Send'}\n  </button>\n);\n```\n\n## Express Server\n\nFor non-Next.js backends:\n\n```typescript\nimport express from 'express';\nimport { OctavusClient, toSSEStream } from '@octavus/server-sdk';\n\nconst app = express();\nconst client = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n\napp.post('/api/trigger', async (req, res) => {\n  const { sessionId, triggerName, input } = req.body;\n\n  const session = client.agentSessions.attach(sessionId, {\n    tools: {\n      // Your tool handlers\n    },\n  });\n\n  const events = session.trigger(triggerName, input);\n  const stream = toSSEStream(events);\n\n  // Set SSE headers\n  res.setHeader('Content-Type', 'text/event-stream');\n  res.setHeader('Cache-Control', 'no-cache');\n  res.setHeader('Connection', 'keep-alive');\n\n  // Pipe the stream to the response\n  const reader = stream.getReader();\n\n  try {\n    while (true) {\n      const { done, value } = await reader.read();\n      if (done) break;\n      res.write(value);\n    }\n  } finally {\n    reader.releaseLock();\n    res.end();\n  }\n});\n```\n\n## Transport Options\n\n```typescript\ninterface HttpTransportOptions {\n  // Function that makes the HTTP request\n  triggerRequest: (\n    triggerName: string,\n    input?: Record<string, unknown>\n  ) => Promise<Response>;\n}\n```\n\n## Protocol\n\n### Request Format\n\nThe `triggerRequest` function should send a POST request with:\n\n```json\n{\n  \"sessionId\": \"sess_abc123\",\n  \"triggerName\": \"user-message\",\n  \"input\": {\n    \"USER_MESSAGE\": \"Hello\"\n  }\n}\n```\n\n### Response Format\n\nThe server responds with an SSE stream:\n\n```\ndata: {\"type\":\"start\",\"messageId\":\"msg_xyz\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"msg_xyz\",\"delta\":\"Hello\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"msg_xyz\",\"delta\":\" there!\"}\n\ndata: {\"type\":\"finish\",\"finishReason\":\"stop\"}\n\ndata: [DONE]\n```\n\nSee [Streaming Events](/docs/server-sdk/streaming#event-types) for the full list of event types.\n\n## Next Steps\n\n- [Quick Start](/docs/getting-started/quickstart) \u2014 Complete Next.js integration guide\n- [Messages](/docs/client-sdk/messages) \u2014 Working with message state\n- [Streaming](/docs/client-sdk/streaming) \u2014 Building streaming UIs\n\n",
+    excerpt: "HTTP Transport The HTTP transport uses standard HTTP requests with Server-Sent Events (SSE) for streaming. This is the simplest and most compatible transport option.  When to Use HTTP Transport | Use...",
+    order: 6
+  },
+  {
+    slug: "protocol/overview",
+    section: "protocol",
+    title: "Overview",
+    description: "Introduction to Octavus agent protocols.",
+    content: '\n# Protocol Overview\n\nAgent protocols define how an AI agent behaves. They\'re written in YAML and specify inputs, triggers, tools, and execution handlers.\n\n## Why Protocols?\n\nProtocols provide:\n\n- **Declarative definition** \u2014 Define behavior, not implementation\n- **Portable agents** \u2014 Move agents between projects\n- **Versioning** \u2014 Track changes with git\n- **Validation** \u2014 Catch errors before runtime\n- **Visualization** \u2014 Debug execution flows\n\n## Protocol Structure\n\n```yaml\n# Agent inputs (provided when creating a session)\ninput:\n  COMPANY_NAME: { type: string }\n  USER_ID: { type: string, optional: true }\n\n# Persistent resources the agent can read/write\nresources:\n  CONVERSATION_SUMMARY:\n    description: Summary for handoff\n    default: ""\n\n# How the agent can be invoked\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n  request-human:\n    description: User clicks "Talk to Human"\n\n# Temporary variables for execution (with types)\nvariables:\n  SUMMARY:\n    type: string\n  TICKET:\n    type: unknown\n\n# Tools the agent can use\ntools:\n  get-user-account:\n    description: Looking up your account\n    parameters:\n      userId: { type: string }\n\n# Agent configuration (model, tools, etc.)\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system            # References prompts/system.md\n  tools: [get-user-account]\n  agentic: true             # Allow multiple tool calls\n  thinking: medium          # Extended reasoning\n\n# What happens when triggers fire\nhandlers:\n  user-message:\n    Add user message:\n      type: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n    \n    Respond to user:\n      type: next-message\n```\n\n## File Structure\n\nEach agent is a folder with:\n\n```\nmy-agent/\n\u251C\u2500\u2500 protocol.yaml           # Main logic (required)\n\u251C\u2500\u2500 settings.json           # Agent metadata (required)\n\u2514\u2500\u2500 prompts/               # Prompt templates\n    \u251C\u2500\u2500 system.md\n    \u251C\u2500\u2500 user-message.md\n    \u2514\u2500\u2500 escalation-summary.md\n```\n\n### settings.json\n\n```json\n{\n  "slug": "my-agent",\n  "name": "My Agent",\n  "description": "What this agent does",\n  "format": "interactive"\n}\n```\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `slug` | Yes | URL-safe identifier (lowercase, digits, dashes) |\n| `name` | Yes | Human-readable name |\n| `description` | No | Brief description |\n| `format` | Yes | `interactive` (chat) or `generation` (background) |\n\n## Naming Conventions\n\n- **Slugs**: `lowercase-with-dashes`\n- **Variables**: `UPPERCASE_SNAKE_CASE`\n- **Prompts**: `lowercase-with-dashes.md`\n- **Tools**: `lowercase-with-dashes`\n- **Triggers**: `lowercase-with-dashes`\n\n## Variables in Prompts\n\nReference variables with `{{VARIABLE_NAME}}`:\n\n```markdown\n<!-- prompts/system.md -->\nYou are a support agent for {{COMPANY_NAME}}.\n\nHelp users with their {{PRODUCT_NAME}} questions.\n\n## Support Policies\n\n{{SUPPORT_POLICIES}}\n```\n\nVariables are replaced with their values at runtime. If a variable is not provided, it\'s replaced with an empty string.\n\n## Next Steps\n\n- [Input & Resources](/docs/protocol/input-resources) \u2014 Defining agent inputs\n- [Triggers](/docs/protocol/triggers) \u2014 How agents are invoked\n- [Tools](/docs/protocol/tools) \u2014 External capabilities\n- [Handlers](/docs/protocol/handlers) \u2014 Execution blocks\n- [Agent Config](/docs/protocol/agent-config) \u2014 Model and settings\n\n',
+    excerpt: "Protocol Overview Agent protocols define how an AI agent behaves. They're written in YAML and specify inputs, triggers, tools, and execution handlers.  Why Protocols? Protocols provide: - Declarative...",
+    order: 1
+  },
+  {
+    slug: "protocol/input-resources",
+    section: "protocol",
+    title: "Input & Resources",
+    description: "Defining agent inputs and persistent resources.",
+    content: "\n# Input & Resources\n\nInputs are provided when creating a session. Resources are persistent state the agent can read and write.\n\n## Input Variables\n\nDefine inputs that consumers must (or may) provide:\n\n```yaml\ninput:\n  # Required input\n  COMPANY_NAME:\n    type: string\n    description: The company name to use in responses\n\n  # Required input with description\n  PRODUCT_NAME:\n    type: string\n    description: Product being supported\n\n  # Optional input (defaults to \"NONE\")\n  SUPPORT_POLICIES:\n    type: string\n    description: Company policies for support\n    optional: true\n\n  # Optional input with custom default\n  USER_ID:\n    type: string\n    description: Current user's ID\n    optional: true\n    default: \"\"\n```\n\n### Input Definition\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |\n| `description` | No | Describes what this input is for |\n| `optional` | No | If true, consumer doesn't have to provide it |\n| `default` | No | Default value if not provided (defaults to `\"NONE\"`) |\n\n### Using Inputs\n\nWhen creating a session, pass input values:\n\n```typescript\nconst sessionId = await client.agentSessions.create('support-chat', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n  SUPPORT_POLICIES: 'Refunds within 30 days...',\n  // USER_ID is optional, not provided\n});\n```\n\nIn prompts, reference with `{{INPUT_NAME}}`:\n\n```markdown\nYou are a support agent for {{COMPANY_NAME}}.\n```\n\n> **Note:** Variables must be `UPPER_SNAKE_CASE`. Nested properties (dot notation like `{{VAR.property}}`) are not supported. Objects are serialized as JSON when interpolated.\n\n## Resources\n\nResources are persistent state that:\n- Survive across triggers\n- Can be read and written by the agent\n- Are synced to the consumer's application\n\n```yaml\nresources:\n  # String resource with default\n  CONVERSATION_SUMMARY:\n    type: string\n    description: Running summary of the conversation\n    default: \"\"\n\n  # Resource with unknown type (for complex data)\n  USER_CONTEXT:\n    type: unknown\n    description: Cached user information\n    default: {}\n\n  # Read-only resource (agent can read but not write)\n  SYSTEM_CONFIG:\n    type: unknown\n    description: System configuration\n    readonly: true\n    default:\n      maxRetries: 3\n      timeout: 30000\n```\n\n### Resource Definition\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |\n| `description` | No | Describes the resource purpose |\n| `default` | No | Initial value |\n| `readonly` | No | If true, agent cannot write to it |\n\n### Writing Resources\n\nUse the `set-resource` block in handlers:\n\n```yaml\nhandlers:\n  request-human:\n    # ... generate summary ...\n    \n    Save summary:\n      type: set-resource\n      resource: CONVERSATION_SUMMARY\n      value: SUMMARY  # Variable containing the value\n```\n\n### Resource Events\n\nWhen a resource is updated, the client SDK receives a `resource-update` event:\n\n```typescript\nuseOctavusChat({\n  onResourceUpdate: (name, value) => {\n    if (name === 'CONVERSATION_SUMMARY') {\n      console.log('Summary updated:', value);\n    }\n  },\n});\n```\n\n## Variables\n\nVariables are internal state managed by block outputs. They persist across triggers but are not synced to the consumer (unlike resources).\n\n```yaml\nvariables:\n  SUMMARY:\n    type: string\n    description: Generated summary text\n  TICKET:\n    type: unknown\n    description: Ticket creation result\n  CONVERSATION_TEXT:\n    type: string\n    description: Serialized conversation\n```\n\n### Variable Definition\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |\n| `description` | No | Describes what this variable stores |\n| `default` | No | Initial value |\n\n### Using Variables\n\nSet variables as output from blocks:\n\n```yaml\nhandlers:\n  request-human:\n    Serialize conversation:\n      type: serialize-thread\n      format: markdown\n      output: CONVERSATION_TEXT  # Stores result in variable\n    \n    Generate summary:\n      type: next-message\n      output: SUMMARY  # LLM output stored in variable\n    \n    Create ticket:\n      type: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY  # Use variable as input\n      output: TICKET\n```\n\n## Scoping\n\n| Type | Scope | Persistence | Synced to Consumer |\n|------|-------|-------------|---------------------|\n| `input` | Session | Immutable | Yes (at creation) |\n| `resources` | Session | Persists across triggers | Yes (via callbacks) |\n| `variables` | Session | Persists across triggers | No (internal only) |\n\n",
+    excerpt: "Input & Resources Inputs are provided when creating a session. Resources are persistent state the agent can read and write.  Input Variables Define inputs that consumers must (or may) provide:  Input...",
+    order: 2
+  },
+  {
+    slug: "protocol/triggers",
+    section: "protocol",
+    title: "Triggers",
+    description: "Defining how agents are invoked.",
+    content: "\n# Triggers\n\nTriggers define how an agent can be invoked. Each trigger has a name, optional inputs, and a corresponding handler.\n\n## Trigger Types\n\n### User Message\n\nThe most common trigger \u2014 when a user sends a chat message:\n\n```yaml\ntriggers:\n  user-message:\n    description: User sends a chat message\n    input:\n      USER_MESSAGE:\n        type: string\n        description: The user's message\n```\n\n### User Action\n\nFor UI interactions like button clicks:\n\n```yaml\ntriggers:\n  request-human:\n    description: User clicks \"Talk to Human\" button\n    # No input needed - action is implicit\n\n  submit-feedback:\n    description: User submits feedback form\n    input:\n      RATING:\n        type: number\n        description: Rating from 1-5\n      COMMENT:\n        type: string\n        description: Optional comment\n        optional: true\n```\n\n### API Trigger\n\nDirect invocation through the SDK:\n\n```yaml\ntriggers:\n  analyze-document:\n    description: Analyze an uploaded document\n    input:\n      DOCUMENT_URL:\n        type: string\n      ANALYSIS_TYPE:\n        type: string\n        description: Type of analysis (summary, sentiment, extraction)\n```\n\n## Trigger Definition\n\n```yaml\ntriggers:\n  trigger-name:\n    description: Optional description\n    input:\n      VARIABLE_NAME:\n        type: string | number | boolean | unknown\n        description: What this input is for\n        optional: true | false  # defaults to false\n        default: value  # default if optional and not provided\n```\n\n## Invoking Triggers\n\n### From Client SDK\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { send } = useOctavusChat({ transport });\n\n  // User message trigger with UI message\n  await send(\n    'user-message',\n    { USER_MESSAGE: text },\n    { userMessage: { content: text } },\n  );\n\n  // User action trigger (no input, no UI message)\n  await send('request-human');\n\n  // Action with input\n  await send('submit-feedback', { RATING: 5, COMMENT: 'Great help!' });\n}\n```\n\n### From Server SDK\n\n```typescript\n// trigger() returns an async generator of events\nconst events = session.trigger('user-message', {\n  USER_MESSAGE: 'Help me with billing',\n});\n\n// Iterate events directly\nfor await (const event of events) {\n  console.log(event);\n}\n\n// Or convert to SSE for HTTP responses\nimport { toSSEStream } from '@octavus/server-sdk';\nreturn new Response(toSSEStream(events), { headers: { 'Content-Type': 'text/event-stream' } });\n```\n\n## Handlers\n\nEach trigger must have a corresponding handler:\n\n```yaml\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n\n  request-human:\n    description: Escalate to human support\n\nhandlers:\n  user-message:\n    # Blocks executed when user-message is triggered\n    Add user message:\n      type: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n\n    Respond:\n      type: next-message\n\n  request-human:\n    # Blocks executed when request-human is triggered\n    Summarize:\n      type: serialize-thread\n      # ...\n```\n\n## Trigger Input Naming\n\nTrigger inputs use `UPPERCASE_SNAKE_CASE`:\n\n```yaml\ntriggers:\n  search-products:\n    input:\n      SEARCH_QUERY: { type: string }\n      MAX_RESULTS: { type: number, optional: true, default: 10 }\n      FILTER_CATEGORY: { type: string, optional: true }\n```\n\n## Best Practices\n\n### 1. Use Descriptive Names\n\n```yaml\n# Good\ntriggers:\n  user-message:       # Clear - user sends chat message\n  request-human:      # Clear - wants human support\n  cancel-subscription: # Clear - specific action\n\n# Avoid\ntriggers:\n  trigger1:           # Unclear\n  msg:                # Too abbreviated\n  do-thing:           # Vague\n```\n\n### 2. Document Triggers\n\n```yaml\ntriggers:\n  escalate-to-tier2:\n    description: >\n      Escalate the conversation to tier 2 support.\n      Should be called when the issue cannot be resolved\n      at tier 1 level.\n    input:\n      REASON:\n        type: string\n        description: Why escalation is needed\n```\n\n### 3. Keep Triggers Focused\n\nEach trigger should do one thing:\n\n```yaml\n# Good - focused triggers\ntriggers:\n  send-message:\n    input: { MESSAGE: { type: string } }\n\n  upload-file:\n    input: { FILE_URL: { type: string } }\n\n  request-callback:\n    input: { PHONE: { type: string } }\n\n# Avoid - overloaded trigger\ntriggers:\n  user-action:\n    input:\n      ACTION_TYPE: { type: string }  # \"message\" | \"file\" | \"callback\"\n      PAYLOAD: { type: unknown }     # Different structure per type\n```\n",
+    excerpt: "Triggers Triggers define how an agent can be invoked. Each trigger has a name, optional inputs, and a corresponding handler.  Trigger Types  User Message The most common trigger \u2014 when a user sends a...",
+    order: 3
+  },
+  {
+    slug: "protocol/tools",
+    section: "protocol",
+    title: "Tools",
+    description: "Defining external tools agents can use.",
+    content: "\n# Tools\n\nTools extend what agents can do. They're defined in the protocol and implemented in your backend.\n\n## Tool Definition\n\n```yaml\ntools:\n  get-user-account:\n    description: Looking up your account information\n    display: description\n    parameters:\n      userId:\n        type: string\n        description: The user ID to look up\n```\n\n### Tool Fields\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `description` | Yes | What the tool does (shown to LLM and optionally user) |\n| `display` | No | How to show in UI: `hidden`, `name`, `description`, `stream` |\n| `parameters` | No | Input parameters the tool accepts |\n\n### Display Modes\n\n| Mode | Behavior |\n|------|----------|\n| `hidden` | Tool runs silently, user doesn't see it |\n| `name` | Shows tool name while executing |\n| `description` | Shows description while executing (default) |\n| `stream` | Streams tool progress if available |\n\n## Parameters\n\n### Parameter Fields\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |\n| `description` | No | Describes what this parameter is for |\n| `optional` | No | If true, parameter is not required (default: false) |\n\n### Optional Parameters\n\nParameters are **required by default**. Use `optional: true` to make a parameter optional:\n\n```yaml\ntools:\n  search-products:\n    description: Search the product catalog\n    parameters:\n      query:\n        type: string\n        description: Search query\n\n      category:\n        type: string\n        description: Filter by category\n        optional: true\n\n      maxPrice:\n        type: number\n        description: Maximum price filter\n        optional: true\n\n      inStock:\n        type: boolean\n        description: Only show in-stock items\n        optional: true\n```\n\n## Making Tools Available\n\nTools defined in `tools:` are available. To make them usable by the LLM, add them to `agent.tools`:\n\n```yaml\ntools:\n  get-user-account:\n    description: Look up user account\n    parameters:\n      userId: { type: string }\n\n  create-support-ticket:\n    description: Create a support ticket\n    parameters:\n      summary: { type: string }\n      priority: { type: string }  # low, medium, high, urgent\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  tools:\n    - get-user-account\n    - create-support-ticket  # LLM can decide when to call these\n  agentic: true\n```\n\n## Tool Invocation Modes\n\n### LLM-Decided (Agentic)\n\nThe LLM decides when to call tools based on the conversation:\n\n```yaml\nagent:\n  tools: [get-user-account, create-support-ticket]\n  agentic: true  # Allow multiple tool calls\n  maxSteps: 10   # Max tool call cycles\n```\n\n### Deterministic (Block-Based)\n\nForce tool calls at specific points in the handler:\n\n```yaml\nhandlers:\n  request-human:\n    # Always create a ticket when escalating\n    Create support ticket:\n      type: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY  # From variable\n        priority: medium  # Literal value\n      output: TICKET      # Store result\n```\n\n## Tool Results\n\n### In Prompts\n\nTool results are stored in variables. Reference the variable in prompts:\n\n```markdown\n<!-- prompts/ticket-directive.md -->\nA support ticket has been created:\n{{TICKET}}\n\nLet the user know their ticket has been created.\n```\n\nWhen the `TICKET` variable contains an object, it's automatically serialized as JSON in the prompt:\n\n```\nA support ticket has been created:\n{\n  \"ticketId\": \"TKT-123ABC\",\n  \"estimatedResponse\": \"24 hours\"\n}\n\nLet the user know their ticket has been created.\n```\n\n> **Note**: Variables use `{{VARIABLE_NAME}}` syntax with `UPPERCASE_SNAKE_CASE`. Dot notation (like `{{TICKET.ticketId}}`) is not supported. Objects are automatically JSON-serialized.\n\n### In Variables\n\nStore tool results for later use:\n\n```yaml\nhandlers:\n  request-human:\n    Get account:\n      type: tool-call\n      tool: get-user-account\n      input:\n        userId: USER_ID\n      output: ACCOUNT  # Result stored here\n\n    Create ticket:\n      type: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY\n        priority: medium\n      output: TICKET\n```\n\n## Implementing Tools\n\nTools are implemented in your backend:\n\n```typescript\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    'get-user-account': async (args) => {\n      const userId = args.userId as string;\n      const user = await db.users.findById(userId);\n\n      return {\n        name: user.name,\n        email: user.email,\n        plan: user.subscription.plan,\n        createdAt: user.createdAt.toISOString(),\n      };\n    },\n\n    'create-support-ticket': async (args) => {\n      const ticket = await ticketService.create({\n        summary: args.summary as string,\n        priority: args.priority as string,\n      });\n\n      return {\n        ticketId: ticket.id,\n        estimatedResponse: getEstimatedTime(args.priority),\n      };\n    },\n  },\n});\n```\n\n## Tool Best Practices\n\n### 1. Clear Descriptions\n\n```yaml\ntools:\n  # Good - clear and specific\n  get-user-account:\n    description: >\n      Retrieves the user's account information including name, email,\n      subscription plan, and account creation date. Use this when the\n      user asks about their account or you need to verify their identity.\n\n  # Avoid - vague\n  get-data:\n    description: Gets some data\n```\n\n### 2. Document Constrained Values\n\n```yaml\ntools:\n  create-support-ticket:\n    parameters:\n      priority:\n        type: string\n        description: Ticket priority level (low, medium, high, urgent)\n```\n",
+    excerpt: "Tools Tools extend what agents can do. They're defined in the protocol and implemented in your backend.  Tool Definition  Tool Fields | Field | Required | Description |...",
+    order: 4
+  },
+  {
+    slug: "protocol/handlers",
+    section: "protocol",
+    title: "Handlers",
+    description: "Defining execution handlers with blocks.",
+    content: "\n# Handlers\n\nHandlers define what happens when a trigger fires. They contain execution blocks that run in sequence.\n\n## Handler Structure\n\n```yaml\nhandlers:\n  trigger-name:\n    Block Name:\n      type: block-type\n      # block-specific properties\n    \n    Another Block:\n      type: another-type\n      # ...\n```\n\nEach block has a human-readable name (shown in debug UI) and a type that determines its behavior.\n\n## Block Types\n\n### next-message\n\nGenerate a response from the LLM:\n\n```yaml\nhandlers:\n  user-message:\n    Respond to user:\n      type: next-message\n      # Uses main conversation thread by default\n      # Display defaults to 'stream'\n```\n\nWith options:\n\n```yaml\nGenerate summary:\n  type: next-message\n  thread: summary           # Use named thread\n  display: stream           # Show streaming content\n  independent: true         # Don't add to main chat\n  output: SUMMARY           # Store output in variable\n  description: Generating summary  # Shown in UI\n```\n\n### add-message\n\nAdd a message to the conversation:\n\n```yaml\nAdd user message:\n  type: add-message\n  role: user                # user | assistant | system\n  prompt: user-message      # Reference to prompt file\n  input: [USER_MESSAGE]     # Variables to interpolate\n  display: hidden           # Don't show in UI\n```\n\nFor internal directives (LLM sees it, user doesn't):\n\n```yaml\nAdd internal directive:\n  type: add-message\n  role: user\n  prompt: ticket-directive\n  input: [TICKET_DETAILS]\n  visible: false            # LLM sees this, user doesn't\n```\n\n### tool-call\n\nCall a tool deterministically:\n\n```yaml\nCreate ticket:\n  type: tool-call\n  tool: create-support-ticket\n  input:\n    summary: SUMMARY        # Variable reference\n    priority: medium        # Literal value\n  output: TICKET           # Store result\n```\n\n### set-resource\n\nUpdate a persistent resource:\n\n```yaml\nSave summary:\n  type: set-resource\n  resource: CONVERSATION_SUMMARY\n  value: SUMMARY            # Variable to save\n  display: name             # Show block name\n```\n\n### start-thread\n\nCreate a named conversation thread:\n\n```yaml\nStart summary thread:\n  type: start-thread\n  thread: summary                    # Thread name\n  model: anthropic/claude-sonnet-4-5 # Optional: different model\n  thinking: low                      # Extended reasoning level\n  maxSteps: 1                        # Tool call limit\n  system: escalation-summary         # System prompt\n  input: [COMPANY_NAME]              # Variables for prompt\n```\n\n### serialize-thread\n\nConvert conversation to text:\n\n```yaml\nSerialize conversation:\n  type: serialize-thread\n  thread: main              # Which thread (default: main)\n  format: markdown          # markdown | json\n  output: CONVERSATION_TEXT # Variable to store result\n```\n\n## Display Modes\n\nEvery block has a `display` property:\n\n| Mode | Default For | Behavior |\n|------|-------------|----------|\n| `hidden` | add-message | Not shown to user |\n| `name` | set-resource | Shows block name |\n| `description` | tool-call | Shows description |\n| `stream` | next-message | Streams content |\n\n## Complete Example\n\n```yaml\nhandlers:\n  user-message:\n    # Add the user's message to conversation\n    Add user message:\n      type: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n      display: hidden\n    \n    # Generate response (LLM may call tools)\n    Respond to user:\n      type: next-message\n      # display: stream (default)\n\n  request-human:\n    # Step 1: Serialize conversation for summary\n    Serialize conversation:\n      type: serialize-thread\n      format: markdown\n      output: CONVERSATION_TEXT\n    \n    # Step 2: Create separate thread for summarization\n    Start summary thread:\n      type: start-thread\n      thread: summary\n      model: anthropic/claude-sonnet-4-5\n      thinking: low\n      system: escalation-summary\n      input: [COMPANY_NAME]\n    \n    # Step 3: Add request to summary thread\n    Add summarize request:\n      type: add-message\n      thread: summary\n      role: user\n      prompt: summarize-request\n      input:\n        - CONVERSATION: CONVERSATION_TEXT\n    \n    # Step 4: Generate summary\n    Generate summary:\n      type: next-message\n      thread: summary\n      display: stream\n      description: Summarizing your conversation\n      independent: true\n      output: SUMMARY\n    \n    # Step 5: Save to resource\n    Save summary:\n      type: set-resource\n      resource: CONVERSATION_SUMMARY\n      value: SUMMARY\n    \n    # Step 6: Create support ticket\n    Create ticket:\n      type: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY\n        priority: medium\n      output: TICKET\n    \n    # Step 7: Add directive for response\n    Add directive:\n      type: add-message\n      role: user\n      prompt: ticket-directive\n      input: [TICKET_DETAILS: TICKET]\n      visible: false\n    \n    # Step 8: Respond to user\n    Respond:\n      type: next-message\n```\n\n## Block Input Mapping\n\nMap variables to block inputs:\n\n```yaml\n# Simple list (variable name = prompt variable)\ninput: [USER_MESSAGE, COMPANY_NAME]\n\n# Mapping (different names)\ninput:\n  - CONVERSATION: CONVERSATION_TEXT  # CONVERSATION in prompt = CONVERSATION_TEXT\n  - TICKET_DETAILS: TICKET\n```\n\n## Independent Blocks\n\nUse `independent: true` for content that shouldn't go to the main chat:\n\n```yaml\nGenerate summary:\n  type: next-message\n  thread: summary\n  independent: true   # Output stored in variable, not main chat\n  output: SUMMARY\n```\n\nThis is useful for:\n- Background processing\n- Summarization in separate threads\n- Generating content for tools\n\n",
+    excerpt: "Handlers Handlers define what happens when a trigger fires. They contain execution blocks that run in sequence.  Handler Structure Each block has a human-readable name (shown in debug UI) and a type...",
+    order: 5
+  },
+  {
+    slug: "protocol/agent-config",
+    section: "protocol",
+    title: "Agent Config",
+    description: "Configuring the agent model and behavior.",
+    content: "\n# Agent Config\n\nThe `agent` section configures the LLM model, system prompt, tools, and behavior.\n\n## Basic Configuration\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system              # References prompts/system.md\n  tools: [get-user-account]   # Available tools\n```\n\n## Configuration Options\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `model` | Yes | Model identifier (provider/model-id) |\n| `system` | Yes | System prompt filename (without .md) |\n| `input` | No | Variables to interpolate in system prompt |\n| `tools` | No | List of tools the LLM can call |\n| `agentic` | No | Allow multiple tool call cycles |\n| `maxSteps` | No | Maximum agentic steps (default: 10) |\n| `temperature` | No | Model temperature (0-2) |\n| `thinking` | No | Extended reasoning level |\n\n## Models\n\nSpecify models in `provider/model-id` format:\n\n```yaml\n# Anthropic\nagent:\n  model: anthropic/claude-sonnet-4-5   # Claude 4.5 Sonnet\n  model: anthropic/claude-opus-4       # Claude 4 Opus\n\n# OpenAI\nagent:\n  model: openai/gpt-4o                 # GPT-4o\n  model: openai/gpt-4o-mini            # GPT-4o Mini\n  model: openai/o1                     # O1\n  model: openai/o3-mini                # O3 Mini\n```\n\n## System Prompt\n\nThe system prompt sets the agent's persona and instructions:\n\n```yaml\nagent:\n  system: system  # Uses prompts/system.md\n  input:\n    - COMPANY_NAME\n    - PRODUCT_NAME\n```\n\nExample `prompts/system.md`:\n\n```markdown\nYou are a friendly support agent for {{COMPANY_NAME}}.\n\n## Your Role\n\nHelp users with questions about {{PRODUCT_NAME}}.\n\n## Guidelines\n\n- Be helpful and professional\n- If you can't help, offer to escalate\n- Never share internal information\n```\n\n## Agentic Mode\n\nEnable multi-step tool calling:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  tools: [get-user-account, search-docs, create-ticket]\n  agentic: true    # LLM can call multiple tools\n  maxSteps: 10     # Limit cycles to prevent runaway\n```\n\n**How it works:**\n1. LLM receives user message\n2. LLM decides to call a tool\n3. Tool executes, result returned to LLM\n4. LLM decides if more tools needed\n5. Repeat until LLM responds or maxSteps reached\n\n## Extended Thinking\n\nEnable extended reasoning for complex tasks:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  thinking: medium  # low | medium | high\n```\n\n| Level | Token Budget | Use Case |\n|-------|-------------|----------|\n| `low` | ~5,000 | Simple reasoning |\n| `medium` | ~10,000 | Moderate complexity |\n| `high` | ~20,000 | Complex analysis |\n\nThinking content streams to the UI and can be displayed to users.\n\n## Temperature\n\nControl response randomness:\n\n```yaml\nagent:\n  model: openai/gpt-4o\n  temperature: 0.7  # 0 = deterministic, 2 = creative\n```\n\n**Guidelines:**\n- `0 - 0.3`: Factual, consistent responses\n- `0.4 - 0.7`: Balanced (good default)\n- `0.8 - 1.2`: Creative, varied responses\n- `> 1.2`: Very creative (may be inconsistent)\n\n## Thread-Specific Config\n\nOverride config for named threads:\n\n```yaml\nhandlers:\n  request-human:\n    Start summary thread:\n      type: start-thread\n      thread: summary\n      model: anthropic/claude-sonnet-4-5  # Different model\n      thinking: low                        # Different thinking\n      maxSteps: 1                          # Limit tool calls\n      system: escalation-summary           # Different prompt\n```\n\n## Full Example\n\n```yaml\ninput:\n  COMPANY_NAME: { type: string }\n  PRODUCT_NAME: { type: string }\n  USER_ID: { type: string, optional: true }\n\nresources:\n  CONVERSATION_SUMMARY:\n    type: string\n    default: \"\"\n\ntools:\n  get-user-account:\n    description: Look up user account\n    parameters:\n      userId: { type: string }\n  \n  search-docs:\n    description: Search help documentation\n    parameters:\n      query: { type: string }\n  \n  create-support-ticket:\n    description: Create a support ticket\n    parameters:\n      summary: { type: string }\n      priority: { type: string }  # low, medium, high\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  input:\n    - COMPANY_NAME\n    - PRODUCT_NAME\n  tools:\n    - get-user-account\n    - search-docs\n    - create-support-ticket\n  agentic: true\n  maxSteps: 10\n  thinking: medium\n\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n\nhandlers:\n  user-message:\n    Add message:\n      type: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n      display: hidden\n    \n    Respond:\n      type: next-message\n```\n\n",
+    excerpt: "Agent Config The  section configures the LLM model, system prompt, tools, and behavior.  Basic Configuration  Configuration Options | Field | Required | Description |...",
+    order: 6
+  },
+  {
+    slug: "api-reference/overview",
+    section: "api-reference",
+    title: "Overview",
+    description: "REST API overview and authentication.",
+    content: '\n# API Reference\n\nThe Octavus API is a RESTful API that enables programmatic access to agent management and session execution.\n\n## Base URL\n\n```\nhttps://octavus.ai\n```\n\n## Authentication\n\nAll API requests require authentication using a Bearer token:\n\n```bash\ncurl -H "Authorization: Bearer YOUR_API_KEY" \\\n  https://octavus.ai/api/agents\n```\n\nAPI keys can be created in the Octavus Platform under your project\'s **API Keys** page.\n\n## Response Format\n\nAll responses are JSON. Success responses return the data directly (not wrapped in a `data` field).\n\n### Success Response\n\n```json\n{\n  "sessionId": "sess_abc123"\n}\n```\n\n### Error Response\n\n```json\n{\n  "error": {\n    "code": "NOT_FOUND",\n    "message": "Agent not found"\n  }\n}\n```\n\n## HTTP Status Codes\n\n| Code | Description |\n|------|-------------|\n| 200 | Success |\n| 201 | Created |\n| 400 | Bad Request - Invalid parameters |\n| 401 | Unauthorized - Missing or invalid API key |\n| 403 | Forbidden - Insufficient permissions |\n| 404 | Not Found |\n| 500 | Internal Server Error |\n\n## Endpoints Overview\n\n### Agents\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/agents` | List all agents |\n| GET | `/api/agents/:id` | Get agent by ID |\n| POST | `/api/agents` | Create agent |\n| PATCH | `/api/agents/:id` | Update agent |\n\n### Sessions\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/api/agent-sessions` | Create session |\n| GET | `/api/agent-sessions/:id` | Get session state |\n| POST | `/api/agent-sessions/:id/trigger` | Execute trigger (SSE) |\n\n## Streaming\n\nThe trigger endpoint returns Server-Sent Events (SSE):\n\n```bash\ncurl -N -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{"triggerName": "user-message", "input": {"USER_MESSAGE": "Hello"}}\' \\\n  https://octavus.ai/api/agent-sessions/SESSION_ID/trigger\n```\n\nResponse format:\n\n```\ndata: {"type":"start","messageId":"..."}\n\ndata: {"type":"block-start","blockId":"...","blockName":"Respond","blockType":"next-message","display":"stream"}\n\ndata: {"type":"text-start","id":"..."}\n\ndata: {"type":"text-delta","id":"...","delta":"Hello"}\n\ndata: {"type":"text-delta","id":"...","delta":"!"}\n\ndata: {"type":"text-end","id":"..."}\n\ndata: {"type":"block-end","blockId":"..."}\n\ndata: {"type":"finish","finishReason":"stop"}\n\ndata: [DONE]\n```\n\n## SDKs\n\nWe recommend using our SDKs instead of calling the API directly:\n\n- **Server SDK**: `@octavus/server-sdk` - For Node.js backends\n- **React SDK**: `@octavus/react` - For React applications\n- **Client SDK**: `@octavus/client-sdk` - For other frontend frameworks\n\nThe SDKs handle authentication, streaming, and tool execution automatically.\n\n',
+    excerpt: "API Reference The Octavus API is a RESTful API that enables programmatic access to agent management and session execution.  Base URL  Authentication All API requests require authentication using a...",
+    order: 1
+  },
+  {
+    slug: "api-reference/sessions",
+    section: "api-reference",
+    title: "Sessions",
+    description: "Session management API endpoints.",
+    content: '\n# Sessions API\n\nSessions represent conversations with agents. They store conversation history, resources, and variables.\n\n## Create Session\n\nCreate a new agent session.\n\n```\nPOST /api/agent-sessions\n```\n\n### Request Body\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "input": {\n    "COMPANY_NAME": "Acme Corp",\n    "PRODUCT_NAME": "Widget Pro",\n    "USER_ID": "user-123"\n  }\n}\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `agentId` | string | Yes | Agent ID (the `id` field, not `slug`) |\n| `input` | object | No | Input variables for the agent |\n\n> To get the agent ID, copy it from the platform URL, use [Get Agent by slug](/docs/api-reference/agents#get-agent) (`GET /api/agents/:slug?by=slug`), or the SDK\'s `agents.getBySlug()` method.\n\n### Response\n\n```json\n{\n  "sessionId": "cm5xyz123abc456def"\n}\n```\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agent-sessions \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "agentId": "cm5xvz7k80001abcd",\n    "input": {\n      "COMPANY_NAME": "Acme Corp",\n      "PRODUCT_NAME": "Widget Pro"\n    }\n  }\'\n```\n\n## Get Session\n\nRetrieve session state including UI-ready messages and resources.\n\n```\nGET /api/agent-sessions/:sessionId\n```\n\n### Response\n\nThe response includes `UIMessage` objects that can be passed directly to the client SDK\'s `initialMessages` option:\n\n```json\n{\n  "id": "cm5xyz123abc456def",\n  "agentId": "cm5xvz7k80001abcd",\n  "input": {\n    "COMPANY_NAME": "Acme Corp",\n    "PRODUCT_NAME": "Widget Pro"\n  },\n  "variables": {},\n  "resources": {\n    "CONVERSATION_SUMMARY": ""\n  },\n  "messages": [\n    {\n      "id": "1702345800000-xyz789a",\n      "role": "user",\n      "parts": [\n        { "type": "text", "text": "How do I reset my password?", "status": "done" }\n      ],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:00.000Z"\n    },\n    {\n      "id": "1702345805000-def456b",\n      "role": "assistant",\n      "parts": [\n        { "type": "text", "text": "I can help you reset your password...", "status": "done" }\n      ],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:05.000Z"\n    }\n  ],\n  "createdAt": "2024-01-15T10:30:00Z",\n  "updatedAt": "2024-01-15T10:30:05Z"\n}\n```\n\n### UIMessage Parts\n\nMessages contain typed `parts` that preserve content ordering:\n\n| Part Type | Description |\n|-----------|-------------|\n| `text` | Text content with `text` and `status` fields |\n| `reasoning` | Extended reasoning with `text` and `status` fields |\n| `tool-call` | Tool execution with `toolCallId`, `toolName`, `displayName`, `args`, `result`, `status` |\n| `operation` | Internal operations with `operationId`, `name`, `operationType`, `status` |\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agent-sessions/:sessionId \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n```\n\n## Trigger Session\n\nExecute a trigger on a session. Returns a Server-Sent Events stream.\n\n```\nPOST /api/agent-sessions/:sessionId/trigger\n```\n\n### Request Body\n\n```json\n{\n  "triggerName": "user-message",\n  "input": {\n    "USER_MESSAGE": "How do I reset my password?"\n  },\n  "toolResults": []\n}\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `triggerName` | string | Yes | Name of the trigger to execute |\n| `input` | object | No | Input variables for the trigger |\n| `toolResults` | array | No | Tool results for continuation (handled by SDK) |\n\n### Response\n\nReturns `text/event-stream` with SSE events:\n\n```\ndata: {"type":"start","messageId":"msg-123"}\n\ndata: {"type":"block-start","blockId":"b1","blockName":"Add user message","blockType":"add-message","display":"hidden"}\n\ndata: {"type":"block-end","blockId":"b1"}\n\ndata: {"type":"block-start","blockId":"b2","blockName":"Respond to user","blockType":"next-message","display":"stream","outputToChat":true}\n\ndata: {"type":"text-start","id":"t1"}\n\ndata: {"type":"text-delta","id":"t1","delta":"I"}\n\ndata: {"type":"text-delta","id":"t1","delta":" can"}\n\ndata: {"type":"text-delta","id":"t1","delta":" help"}\n\ndata: {"type":"text-delta","id":"t1","delta":" you"}\n\ndata: {"type":"text-delta","id":"t1","delta":" reset"}\n\ndata: {"type":"text-delta","id":"t1","delta":" your"}\n\ndata: {"type":"text-delta","id":"t1","delta":" password"}\n\ndata: {"type":"text-delta","id":"t1","delta":"!"}\n\ndata: {"type":"text-end","id":"t1"}\n\ndata: {"type":"block-end","blockId":"b2"}\n\ndata: {"type":"finish","finishReason":"stop"}\n\ndata: [DONE]\n```\n\n### Event Types\n\n| Event | Description |\n|-------|-------------|\n| `start` | Stream started |\n| `finish` | Execution complete |\n| `error` | Error occurred |\n| `block-start` | Execution block started |\n| `block-end` | Execution block completed |\n| `text-start` | Text generation started |\n| `text-delta` | Incremental text content |\n| `text-end` | Text generation ended |\n| `reasoning-start` | Extended reasoning started |\n| `reasoning-delta` | Reasoning content |\n| `reasoning-end` | Extended reasoning ended |\n| `tool-input-start` | Tool call initiated |\n| `tool-input-delta` | Tool arguments streaming |\n| `tool-input-end` | Tool arguments streaming ended |\n| `tool-input-available` | Tool input complete |\n| `tool-output-available` | Tool completed with result |\n| `tool-output-error` | Tool failed |\n| `tool-request` | Platform requesting tool execution |\n| `resource-update` | Resource value changed |\n\n### Example\n\n```bash\ncurl -N -X POST https://octavus.ai/api/agent-sessions/:sessionId/trigger \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "triggerName": "user-message",\n    "input": { "USER_MESSAGE": "How do I reset my password?" }\n  }\'\n```\n\n## Tool Continuation\n\nWhen the agent calls external tools, you\'ll receive a `tool-request` event. Execute the tools and send results back:\n\n```json\n{\n  "triggerName": "user-message",\n  "input": { "USER_MESSAGE": "..." },\n  "toolResults": [\n    {\n      "toolCallId": "tc_123",\n      "toolName": "get-user-account",\n      "result": {\n        "name": "Demo User",\n        "email": "demo@example.com"\n      }\n    }\n  ]\n}\n```\n\nThe Server SDK handles this continuation pattern automatically.\n',
+    excerpt: "Sessions API Sessions represent conversations with agents. They store conversation history, resources, and variables.  Create Session Create a new agent session.  Request Body | Field | Type |...",
+    order: 2
+  },
+  {
+    slug: "api-reference/agents",
+    section: "api-reference",
+    title: "Agents",
+    description: "Agent management API endpoints.",
+    content: '\n# Agents API\n\nManage agent definitions including protocols and prompts.\n\n## List Agents\n\nGet all agents in the project.\n\n```\nGET /api/agents\n```\n\n### Response\n\n```json\n{\n  "agents": [\n    {\n      "id": "cm5xvz7k80001abcd",\n      "slug": "support-chat",\n      "name": "Support Chat",\n      "description": "Customer support agent",\n      "format": "interactive",\n      "createdAt": "2024-01-10T08:00:00Z",\n      "updatedAt": "2024-01-15T10:00:00Z"\n    }\n  ]\n}\n```\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agents \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n```\n\n## Get Agent\n\nGet a single agent by ID or slug.\n\n```\nGET /api/agents/:id\nGET /api/agents/:slug?by=slug\n```\n\n### Response\n\n```json\n{\n  "id": "cm5xvz7k80001abcd",\n  "settings": {\n    "slug": "support-chat",\n    "name": "Support Chat",\n    "description": "Customer support agent",\n    "format": "interactive"\n  },\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "You are a support agent for {{COMPANY_NAME}}..."\n    },\n    {\n      "name": "user-message",\n      "content": "{{USER_MESSAGE}}"\n    }\n  ]\n}\n```\n\n### Example\n\n```bash\n# By ID\ncurl https://octavus.ai/api/agents/:agentId \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n\n# By slug\ncurl "https://octavus.ai/api/agents/:slug?by=slug" \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n```\n\n## Create Agent\n\nCreate a new agent.\n\n```\nPOST /api/agents\n```\n\n### Request Body\n\n```json\n{\n  "settings": {\n    "slug": "support-chat",\n    "name": "Support Chat",\n    "description": "Customer support agent",\n    "format": "interactive"\n  },\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "You are a support agent..."\n    }\n  ]\n}\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `settings.slug` | string | Yes | URL-safe identifier |\n| `settings.name` | string | Yes | Display name |\n| `settings.description` | string | No | Agent description |\n| `settings.format` | string | Yes | `interactive` or `generation` |\n| `protocol` | string | Yes | YAML protocol definition |\n| `prompts` | array | Yes | Prompt files |\n\n### Response\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "message": "Agent created successfully"\n}\n```\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agents \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "settings": {\n      "slug": "my-agent",\n      "name": "My Agent",\n      "format": "interactive"\n    },\n    "protocol": "agent:\\n  model: anthropic/claude-sonnet-4-5\\n  system: system",\n    "prompts": [\n      { "name": "system", "content": "You are a helpful assistant." }\n    ]\n  }\'\n```\n\n## Update Agent\n\nUpdate an existing agent.\n\n```\nPATCH /api/agents/:id\nPATCH /api/agents/:slug?by=slug\n```\n\n### Request Body\n\n```json\n{\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "Updated system prompt..."\n    }\n  ]\n}\n```\n\nAll fields are optional. Only provided fields are updated.\n\n### Response\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "message": "Agent updated successfully"\n}\n```\n\n### Example\n\n```bash\ncurl -X PATCH https://octavus.ai/api/agents/:agentId \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "protocol": "agent:\\n  model: anthropic/claude-sonnet-4-5\\n  system: system\\n  thinking: high"\n  }\'\n```\n\n## Sync Agent\n\nThe Server SDK provides a `sync` method that creates or updates an agent:\n\n```typescript\nconst { agentId, created } = await client.agents.sync({\n  settings: {\n    slug: \'support-chat\',\n    name: \'Support Chat\',\n    format: \'interactive\',\n  },\n  protocol: protocolYaml,\n  prompts: [\n    { name: \'system\', content: systemPrompt },\n  ],\n});\n\nif (created) {\n  console.log(\'Created new agent:\', agentId);\n} else {\n  console.log(\'Updated existing agent:\', agentId);\n}\n```\n\nThis is useful for CI/CD pipelines to deploy agent updates.\n\n',
+    excerpt: "Agents API Manage agent definitions including protocols and prompts.  List Agents Get all agents in the project.  Response  Example  Get Agent Get a single agent by ID or slug.  Response  Example ...",
+    order: 3
+  },
+  {
+    slug: "examples/overview",
+    section: "examples",
+    title: "Overview",
+    description: "Complete integration examples for different architectures.",
+    content: "\n# Examples\n\nThis section provides complete integration examples for different architectures. Each example walks through building a functional chat interface from scratch.\n\n## Available Examples\n\n| Example | Transport | Best For |\n|---------|-----------|----------|\n| [Next.js Chat](/docs/examples/nextjs-chat) | HTTP/SSE | Next.js, Remix, standard web apps |\n| [Socket Chat](/docs/examples/socket-chat) | SockJS | Meteor, Phoenix, real-time apps |\n\n## Choosing a Transport\n\n**Use HTTP Transport when:**\n- Building with Next.js, Remix, or similar frameworks\n- You want the simplest integration\n- Deploying to serverless (Vercel, Netlify, etc.)\n\n**Use Socket Transport when:**\n- Using Meteor, Phoenix, or socket-based frameworks\n- Need custom real-time events (typing indicators, presence)\n- Behind proxies that don't support SSE well\n",
+    excerpt: "Examples This section provides complete integration examples for different architectures. Each example walks through building a functional chat interface from scratch.  Available Examples | Example |...",
+    order: 1
+  },
+  {
+    slug: "examples/nextjs-chat",
+    section: "examples",
+    title: "Next.js Chat",
+    description: "Building a chat interface with Next.js and HTTP transport.",
+    content: "\n# Next.js Chat Example\n\nThis example builds a support chat interface using Next.js App Router with HTTP/SSE transport. This is the recommended pattern for most web applications.\n\n## What You're Building\n\nA chat interface that:\n- Creates sessions server-side\n- Streams AI responses in real-time\n- Handles tool calls on your server\n- Shows typing status during streaming\n\n## Architecture\n\n```\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502                 \u2502   POST /api/chat   \u2502                 \u2502\n\u2502     Browser     \u2502 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BA\u2502   Next.js API   \u2502\n\u2502    (React)      \u2502                    \u2502     Routes      \u2502\n\u2502                 \u2502\u25C4\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500SSE\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2502                 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                                                \u2502\n                                                \u25BC\n                                       \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n                                       \u2502                 \u2502\n                                       \u2502 Octavus Platform\u2502\n                                       \u2502                 \u2502\n                                       \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## Prerequisites\n\n- Next.js 14+ with App Router\n- Octavus account with API key\n- An agent configured in Octavus\n\n## Step 1: Install Dependencies\n\n```bash\nnpm install @octavus/server-sdk @octavus/react\n```\n\n## Step 2: Configure Environment\n\n```bash\n# .env.local\nOCTAVUS_API_URL=https://octavus.ai\nOCTAVUS_API_KEY=your-api-key\n```\n\n## Step 3: Create the Octavus Client\n\n```typescript\n// lib/octavus.ts\nimport { OctavusClient } from '@octavus/server-sdk';\n\nexport const octavus = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n```\n\n## Step 4: Create Session Endpoint\n\nSessions hold conversation state. Create one when the user opens the chat:\n\n```typescript\n// app/api/sessions/route.ts\nimport { NextResponse } from 'next/server';\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { agentId, input } = await request.json();\n\n  // Create a new session with initial input variables\n  const sessionId = await octavus.agentSessions.create(agentId, input);\n\n  return NextResponse.json({ sessionId });\n}\n```\n\n**Protocol Note:** The `input` object contains variables defined in your agent's protocol. For example, if your agent has `COMPANY_NAME` as an input variable:\n\n```typescript\nconst sessionId = await octavus.agentSessions.create(agentId, {\n  COMPANY_NAME: 'Acme Corp',\n  USER_ID: user.id,\n});\n```\n\n## Step 5: Create Trigger Endpoint\n\nTriggers execute agent actions. The `user-message` trigger is the most common:\n\n```typescript\n// app/api/trigger/route.ts\nimport { toSSEStream } from '@octavus/server-sdk';\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { sessionId, triggerName, input } = await request.json();\n\n  // Attach to the session with tool handlers\n  const session = octavus.agentSessions.attach(sessionId, {\n    tools: {\n      // Tool handlers run on YOUR server, not Octavus\n      'get-user-account': async (args) => {\n        const userId = args.userId as string;\n        // Fetch from your database\n        const user = await db.users.findUnique({ where: { id: userId } });\n        return {\n          name: user.name,\n          email: user.email,\n          plan: user.plan,\n        };\n      },\n\n      'create-support-ticket': async (args) => {\n        const ticket = await db.tickets.create({\n          data: {\n            summary: args.summary as string,\n            priority: args.priority as string,\n          },\n        });\n        return {\n          ticketId: ticket.id,\n          estimatedResponse: '24 hours',\n        };\n      },\n    },\n  });\n\n  // trigger() returns parsed events, toSSEStream() converts to SSE format\n  const events = session.trigger(triggerName, input);\n\n  return new Response(toSSEStream(events), {\n    headers: {\n      'Content-Type': 'text/event-stream',\n      'Cache-Control': 'no-cache',\n      Connection: 'keep-alive',\n    },\n  });\n}\n```\n\n**Protocol Note:** Tool names and arguments are defined in your agent's protocol YAML. The tool handlers here must match those definitions.\n\n## Step 6: Build the Chat Component\n\n```tsx\n// components/Chat.tsx\n'use client';\n\nimport { useState, useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\ninterface ChatProps {\n  sessionId: string;\n}\n\nexport function Chat({ sessionId }: ChatProps) {\n  const [inputValue, setInputValue] = useState('');\n\n  // Create transport - memoized on sessionId\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { messages, status, send } = useOctavusChat({ transport });\n\n  const handleSubmit = async (e: React.FormEvent) => {\n    e.preventDefault();\n    if (!inputValue.trim() || status === 'streaming') return;\n\n    const message = inputValue.trim();\n    setInputValue('');\n\n    // Send triggers the 'user-message' action\n    // The third argument adds the user message to the UI\n    await send(\n      'user-message',\n      { USER_MESSAGE: message },\n      { userMessage: { content: message } },\n    );\n  };\n\n  return (\n    <div className=\"flex flex-col h-screen\">\n      {/* Messages */}\n      <div className=\"flex-1 overflow-y-auto p-4 space-y-4\">\n        {messages.map((msg) => (\n          <div\n            key={msg.id}\n            className={msg.role === 'user' ? 'text-right' : 'text-left'}\n          >\n            <div\n              className={`inline-block p-3 rounded-lg ${\n                msg.role === 'user'\n                  ? 'bg-blue-500 text-white'\n                  : 'bg-gray-100'\n              }`}\n            >\n              {msg.parts.map((part, i) => {\n                if (part.type === 'text') {\n                  return <p key={i}>{part.text}</p>;\n                }\n                if (part.type === 'tool-call') {\n                  return (\n                    <div key={i} className=\"text-sm opacity-70\">\n                      Using {part.toolName}...\n                    </div>\n                  );\n                }\n                return null;\n              })}\n            </div>\n          </div>\n        ))}\n      </div>\n\n      {/* Input */}\n      <form onSubmit={handleSubmit} className=\"p-4 border-t\">\n        <div className=\"flex gap-2\">\n          <input\n            type=\"text\"\n            value={inputValue}\n            onChange={(e) => setInputValue(e.target.value)}\n            placeholder=\"Type a message...\"\n            className=\"flex-1 px-4 py-2 border rounded-lg\"\n            disabled={status === 'streaming'}\n          />\n          <button\n            type=\"submit\"\n            disabled={status === 'streaming'}\n            className=\"px-4 py-2 bg-blue-500 text-white rounded-lg\"\n          >\n            {status === 'streaming' ? 'Sending...' : 'Send'}\n          </button>\n        </div>\n      </form>\n    </div>\n  );\n}\n```\n\n## Step 7: Create the Page\n\n```tsx\n// app/chat/page.tsx\n'use client';\n\nimport { useEffect, useState } from 'react';\nimport { Chat } from '@/components/Chat';\n\nconst AGENT_ID = 'your-agent-id'; // From Octavus dashboard\n\nexport default function ChatPage() {\n  const [sessionId, setSessionId] = useState<string | null>(null);\n\n  useEffect(() => {\n    // Create session on mount\n    fetch('/api/sessions', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({\n        agentId: AGENT_ID,\n        input: {\n          COMPANY_NAME: 'Acme Corp',\n        },\n      }),\n    })\n      .then((res) => res.json())\n      .then((data) => setSessionId(data.sessionId));\n  }, []);\n\n  if (!sessionId) {\n    return <div className=\"p-8\">Loading...</div>;\n  }\n\n  return <Chat sessionId={sessionId} />;\n}\n```\n\n## Protocol Integration\n\nYour agent's protocol defines the triggers and tools. Here's how the code maps to protocol:\n\n### Triggers\n\n```yaml\n# In your agent's protocol.yaml\ntriggers:\n  user-message:\n    description: User sends a chat message\n    input:\n      USER_MESSAGE:\n        type: string\n        description: The user's message\n```\n\nThe `send()` call maps directly:\n\n```typescript\nawait send(\n  'user-message',           // trigger name\n  { USER_MESSAGE: message }, // trigger inputs\n  { userMessage: { content: message } },\n);\n```\n\n### Tools\n\n```yaml\n# In your agent's protocol.yaml\ntools:\n  get-user-account:\n    description: Fetch user account details\n    parameters:\n      userId:\n        type: string\n        description: The user ID to look up\n```\n\nTool handlers receive the parameters as `args`:\n\n```typescript\n'get-user-account': async (args) => {\n  const userId = args.userId as string;\n  // ...\n}\n```\n\n## Next Steps\n\n- [Protocol Overview](/docs/protocol/overview) \u2014 Define agent behavior\n- [Messages](/docs/client-sdk/messages) \u2014 Rich message rendering\n- [Streaming](/docs/client-sdk/streaming) \u2014 Advanced streaming UI\n\n",
+    excerpt: "Next.js Chat Example This example builds a support chat interface using Next.js App Router with HTTP/SSE transport. This is the recommended pattern for most web applications.  What You're Building A...",
+    order: 2
+  },
+  {
+    slug: "examples/socket-chat",
+    section: "examples",
+    title: "Socket Chat",
+    description: "Building a chat interface with SockJS for real-time frameworks.",
+    content: "\n# Socket Chat Example\n\nThis example builds a chat interface using SockJS for bidirectional communication. Use this pattern for Meteor, Phoenix, or when you need custom real-time events.\n\n## What You're Building\n\nA chat interface that:\n- Uses SockJS for real-time streaming\n- Manages sessions server-side (client doesn't need sessionId)\n- Supports custom events alongside chat\n- Works with frameworks that use WebSocket-like transports\n\n## Architecture\n\n```\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502                 \u2502                    \u2502                 \u2502\n\u2502     Browser     \u2502\u25C4\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2502  Your Server    \u2502\n\u2502    (React)      \u2502      SockJS        \u2502  (Express)      \u2502\n\u2502                 \u2502\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u25BA\u2502                 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                                                \u2502\n                                                \u25BC\n                                       \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n                                       \u2502                 \u2502\n                                       \u2502 Octavus Platform\u2502\n                                       \u2502                 \u2502\n                                       \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n**Key difference from HTTP:** The server maintains a persistent socket connection and manages sessions internally. The client never needs to know about `sessionId`.\n\n## Prerequisites\n\n- Express (or similar Node.js server)\n- React frontend\n- `sockjs` (server) and `sockjs-client` (client)\n- Octavus account with API key\n\n## Step 1: Install Dependencies\n\n**Server:**\n```bash\nnpm install @octavus/server-sdk sockjs express\nnpm install -D @types/sockjs @types/express\n```\n\n**Client:**\n```bash\nnpm install @octavus/react sockjs-client\nnpm install -D @types/sockjs-client\n```\n\n## Step 2: Configure Environment\n\n```bash\n# .env\nOCTAVUS_API_URL=https://octavus.ai\nOCTAVUS_API_KEY=your-api-key\nOCTAVUS_AGENT_ID=your-agent-id\n```\n\n## Step 3: Create the Octavus Client (Server)\n\n```typescript\n// server/octavus/client.ts\nimport { OctavusClient } from '@octavus/server-sdk';\n\nexport const octavus = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n\nexport const AGENT_ID = process.env.OCTAVUS_AGENT_ID!;\n```\n\n## Step 4: Create the Socket Handler (Server)\n\nThis is the core of socket integration. Each connection gets its own session:\n\n```typescript\n// server/octavus/socket-handler.ts\nimport type { Connection } from 'sockjs';\nimport { OctavusClient, type AgentSession } from '@octavus/server-sdk';\n\nconst octavus = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n\nconst AGENT_ID = process.env.OCTAVUS_AGENT_ID!;\n\nexport function createSocketHandler() {\n  return (conn: Connection) => {\n    let session: AgentSession | null = null;\n    let abortController: AbortController | null = null;\n\n    conn.on('data', (rawData: string) => {\n      void handleMessage(rawData);\n    });\n\n    async function handleMessage(rawData: string) {\n      const msg = JSON.parse(rawData);\n\n      // Handle stop request\n      if (msg.type === 'stop') {\n        abortController?.abort();\n        return;\n      }\n\n      // Handle trigger\n      if (msg.type === 'trigger') {\n        // Create session lazily on first trigger\n        if (!session) {\n          const sessionId = await octavus.agentSessions.create(AGENT_ID, {\n            // Initial input variables from your protocol\n            COMPANY_NAME: 'Acme Corp',\n          });\n\n          session = octavus.agentSessions.attach(sessionId, {\n            tools: {\n              'get-user-account': async () => {\n                // Fetch from your database\n                return { name: 'Demo User', plan: 'pro' };\n              },\n              'create-support-ticket': async () => {\n                return { ticketId: 'TKT-123', estimatedResponse: '24h' };\n              },\n            },\n          });\n        }\n\n        abortController = new AbortController();\n\n        // trigger() returns parsed events \u2014 iterate directly\n        const events = session.trigger(msg.triggerName, msg.input);\n\n        try {\n          for await (const event of events) {\n            if (abortController.signal.aborted) break;\n            conn.write(JSON.stringify(event));\n          }\n        } catch {\n          // Handle errors\n        }\n      }\n    }\n\n    conn.on('close', () => {\n      abortController?.abort();\n    });\n  };\n}\n```\n\n## Step 5: Set Up the Express Server\n\n```typescript\n// server/index.ts\nimport express from 'express';\nimport http from 'http';\nimport sockjs from 'sockjs';\nimport { createSocketHandler } from './octavus/socket-handler';\n\nconst app = express();\nconst server = http.createServer(app);\n\n// Create SockJS server\nconst sockServer = sockjs.createServer({\n  prefix: '/octavus',\n  log: () => {}, // Silence logs\n});\n\n// Attach handler\nsockServer.on('connection', createSocketHandler());\nsockServer.installHandlers(server);\n\n// Serve your frontend\napp.use(express.static('dist/client'));\n\nserver.listen(3001, () => {\n  console.log('Server running on http://localhost:3001');\n});\n```\n\n## Step 6: Create the Socket Hook (Client)\n\n```typescript\n// src/hooks/useOctavusSocket.ts\nimport { useMemo } from 'react';\nimport SockJS from 'sockjs-client';\nimport { useOctavusChat, createSocketTransport, type SocketLike } from '@octavus/react';\n\nfunction connectSocket(): Promise<SocketLike> {\n  return new Promise((resolve, reject) => {\n    const sock = new SockJS('/octavus');\n\n    sock.onopen = () => resolve(sock);\n    sock.onerror = () => reject(new Error('Connection failed'));\n  });\n}\n\nexport function useOctavusSocket() {\n  // Transport is stable - empty deps because server manages sessions\n  const transport = useMemo(\n    () => createSocketTransport({ connect: connectSocket }),\n    [],\n  );\n\n  const { messages, status, error, send, stop } = useOctavusChat({\n    transport,\n    onError: (err) => console.error('Chat error:', err),\n  });\n\n  const sendMessage = async (message: string) => {\n    await send(\n      'user-message',\n      { USER_MESSAGE: message },\n      { userMessage: { content: message } },\n    );\n  };\n\n  return { messages, status, error, sendMessage, stop };\n}\n```\n\n## Step 7: Build the Chat Component\n\n```tsx\n// src/components/Chat.tsx\nimport { useState } from 'react';\nimport { useOctavusSocket } from '../hooks/useOctavusSocket';\n\nexport function Chat() {\n  const [inputValue, setInputValue] = useState('');\n  const { messages, status, sendMessage, stop } = useOctavusSocket();\n\n  const handleSubmit = async (e: React.FormEvent) => {\n    e.preventDefault();\n    if (!inputValue.trim() || status === 'streaming') return;\n\n    const message = inputValue.trim();\n    setInputValue('');\n    await sendMessage(message);\n  };\n\n  return (\n    <div className=\"flex flex-col h-screen\">\n      {/* Messages */}\n      <div className=\"flex-1 overflow-y-auto p-4 space-y-4\">\n        {messages.map((msg) => (\n          <div\n            key={msg.id}\n            className={msg.role === 'user' ? 'text-right' : 'text-left'}\n          >\n            <div\n              className={`inline-block p-3 rounded-lg ${\n                msg.role === 'user'\n                  ? 'bg-blue-500 text-white'\n                  : 'bg-gray-100'\n              }`}\n            >\n              {msg.parts.map((part, i) => {\n                if (part.type === 'text') return <p key={i}>{part.text}</p>;\n                return null;\n              })}\n            </div>\n          </div>\n        ))}\n      </div>\n\n      {/* Input */}\n      <form onSubmit={handleSubmit} className=\"p-4 border-t flex gap-2\">\n        <input\n          type=\"text\"\n          value={inputValue}\n          onChange={(e) => setInputValue(e.target.value)}\n          placeholder=\"Type a message...\"\n          className=\"flex-1 px-4 py-2 border rounded-lg\"\n          disabled={status === 'streaming'}\n        />\n        {status === 'streaming' ? (\n          <button\n            type=\"button\"\n            onClick={stop}\n            className=\"px-4 py-2 bg-red-500 text-white rounded-lg\"\n          >\n            Stop\n          </button>\n        ) : (\n          <button\n            type=\"submit\"\n            className=\"px-4 py-2 bg-blue-500 text-white rounded-lg\"\n          >\n            Send\n          </button>\n        )}\n      </form>\n    </div>\n  );\n}\n```\n\n## Custom Events\n\nSocket transport supports custom events alongside Octavus events:\n\n```typescript\n// Client - handle custom events\nconst transport = useMemo(\n  () =>\n    createSocketTransport({\n      connect: connectSocket,\n      onMessage: (data) => {\n        const msg = data as { type: string; [key: string]: unknown };\n\n        if (msg.type === 'typing-indicator') {\n          setAgentTyping(msg.isTyping as boolean);\n        }\n\n        if (msg.type === 'custom-notification') {\n          showToast(msg.message as string);\n        }\n\n        // Octavus events (text-delta, finish, etc.) are handled automatically\n      },\n    }),\n  [],\n);\n```\n\n```typescript\n// Server - send custom events\nconn.write(JSON.stringify({\n  type: 'typing-indicator',\n  isTyping: true,\n}));\n```\n\n## Protocol Integration\n\n### Triggers\n\nThe socket handler receives trigger messages and forwards them to Octavus:\n\n```typescript\n// Client sends:\n{ type: 'trigger', triggerName: 'user-message', input: { USER_MESSAGE: 'Hello' } }\n\n// Server handles:\nif (msg.type === 'trigger') {\n  const events = session.trigger(msg.triggerName, msg.input);\n  for await (const event of events) {\n    conn.write(JSON.stringify(event));\n  }\n}\n```\n\n### Tools\n\nTools are defined in your agent's protocol and handled server-side:\n\n```yaml\n# protocol.yaml\ntools:\n  get-user-account:\n    description: Fetch user details\n    parameters:\n      userId:\n        type: string\n```\n\n```typescript\n// Server tool handler\ntools: {\n  'get-user-account': async (args) => {\n    const userId = args.userId as string;\n    return await db.users.find(userId);\n  },\n}\n```\n\n## Meteor Integration Note\n\nMeteor's bundler may have issues with ES6 imports of `sockjs-client`:\n\n```typescript\n// Use require() instead of import\nconst SockJS: typeof import('sockjs-client') = require('sockjs-client');\n```\n\n## Next Steps\n\n- [Socket Transport](/docs/client-sdk/socket-transport) \u2014 Advanced socket patterns\n- [Protocol Overview](/docs/protocol/overview) \u2014 Define agent behavior\n- [Tools](/docs/protocol/tools) \u2014 Building tool handlers\n\n",
+    excerpt: "Socket Chat Example This example builds a chat interface using SockJS for bidirectional communication. Use this pattern for Meteor, Phoenix, or when you need custom real-time events.  What You're...",
+    order: 3
+  }
+];
+
+// dist/sections.json
+var sections_default = [
+  {
+    slug: "getting-started",
+    title: "Getting Started",
+    description: "Learn the basics of Octavus and how to integrate AI agents into your application.",
+    order: 1,
+    docs: [
+      {
+        slug: "getting-started/introduction",
+        section: "getting-started",
+        title: "Introduction",
+        description: "Overview of Octavus AI - an agent orchestration platform for developers.",
+        content: "\n# Introduction to Octavus\n\nOctavus is an agent orchestration platform that lets developers define, manage, and deploy AI agents through a unified service. It handles the orchestration layer so teams can focus on their agent logic and business requirements.\n\n## What is Octavus?\n\nBuilding and managing AI agents is complex. Developers face challenges with:\n\n- **Fragmented tooling** \u2014 No unified way to define, manage, and deploy agents\n- **Prompt management** \u2014 Prompts are scattered across codebases, hard to version and iterate\n- **Integration complexity** \u2014 Connecting agents to tools, resources, and other agents requires significant custom work\n- **Observability** \u2014 Difficult to debug, monitor, and understand agent behavior in production\n- **Infrastructure overhead** \u2014 Teams rebuild the same agent infrastructure repeatedly\n\nOctavus solves these problems by providing:\n\n- A **protocol-based approach** to defining agent behavior\n- **Server and client SDKs** for easy integration\n- **Built-in streaming** support for real-time responses\n- **Tool execution** that runs on your servers with your data\n- **Session management** for stateful conversations\n\n## Core Concepts\n\n### Agents\n\nAn **Agent** is the main entity in Octavus \u2014 a self-contained unit that defines how an AI agent behaves. Agents are defined using YAML protocols that specify:\n\n- Input variables the agent accepts\n- Triggers that invoke the agent (user messages, button clicks, API calls)\n- Tools the agent can use\n- Handlers that define execution flow\n\n### Sessions\n\nA **Session** represents a conversation with an agent. Sessions:\n\n- Store conversation history\n- Track resources and variables\n- Enable stateful interactions across multiple messages\n\n### Triggers\n\n**Triggers** define how an agent is invoked:\n\n- **User Message** \u2014 Respond to a text message in a chat interface\n- **User Action** \u2014 Respond to UI actions (button clicks, form submissions)\n- **API Call** \u2014 Direct invocation via SDK\n\n### Tools\n\n**Tools** extend what agents can do:\n\n- **External Tools** \u2014 Consumer-defined tools that call back to your systems\n- **Internal Tools** \u2014 Built-in capabilities (web search, code execution)\n\nTools execute on your server, not on Octavus, giving you full control over data and authentication.\n\n## Architecture Overview\n\n```mermaid\nsequenceDiagram\n    participant App as Your App\n    participant API as Octavus API\n    participant LLM as LLM Provider\n\n    App->>API: 1. Trigger action\n    API->>LLM: 2. Execute protocol\n    LLM-->>API: Response\n    API-->>App: 3. Stream events\n    \n    Note over App: Tool request received\n    API-->>App: 4. Tool request\n    Note over App: 5. Execute tool locally\n    App->>API: 6. Return results\n    \n    API->>LLM: 7. Continue\n    LLM-->>API: Response\n    API-->>App: 8. Stream response\n```\n\n## Next Steps\n\n- [Quick Start](/docs/getting-started/quickstart) \u2014 Get your first agent running in minutes\n- [Server SDK](/docs/server-sdk/overview) \u2014 Learn about backend integration\n- [Client SDK](/docs/client-sdk/overview) \u2014 Build chat interfaces with React (or other frameworks)\n- [Protocol Reference](/docs/protocol/overview) \u2014 Deep dive into agent protocols\n\n",
+        excerpt: "Introduction to Octavus Octavus is an agent orchestration platform that lets developers define, manage, and deploy AI agents through a unified service. It handles the orchestration layer so teams can...",
+        order: 1
+      },
+      {
+        slug: "getting-started/quickstart",
+        section: "getting-started",
+        title: "Quick Start",
+        description: "Get your first Octavus agent running in minutes.",
+        content: "\n# Quick Start\n\nThis guide will walk you through integrating Octavus into your application in under 10 minutes.\n\n## Prerequisites\n\n- Node.js 18+\n- An Octavus account with API key\n- A Next.js application (or any Node.js backend)\n\n## Installation\n\nInstall the Octavus SDKs in your project:\n\n```bash\n# Server SDK for backend\nnpm install @octavus/server-sdk\n\n# React bindings for frontend\nnpm install @octavus/react\n```\n\n## Backend Setup\n\n### 1. Initialize the Client\n\nCreate an Octavus client instance in your backend:\n\n```typescript\n// lib/octavus.ts\nimport { OctavusClient } from '@octavus/server-sdk';\n\nexport const octavus = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n```\n\n### 2. Create a Session Endpoint\n\nCreate an API endpoint that creates sessions and returns the session ID:\n\n```typescript\n// app/api/chat/create/route.ts\nimport { NextResponse } from 'next/server';\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { agentSlug, input } = await request.json();\n\n  // Look up agent by slug to get its ID\n  const agent = await octavus.agents.getBySlug(agentSlug);\n  if (!agent) {\n    return NextResponse.json({ error: 'Agent not found' }, { status: 404 });\n  }\n\n  // Create a new session using the agent ID\n  const sessionId = await octavus.agentSessions.create(agent.id, input);\n\n  return NextResponse.json({ sessionId });\n}\n```\n\n### 3. Create a Trigger Endpoint\n\nCreate an endpoint that handles triggers and streams responses:\n\n```typescript\n// app/api/trigger/route.ts\nimport { toSSEStream } from '@octavus/server-sdk';\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { sessionId, triggerName, input } = await request.json();\n\n  // Attach to session with tool handlers\n  const session = octavus.agentSessions.attach(sessionId, {\n    tools: {\n      // Define tool handlers that run on your server\n      'get-user-account': async (args) => {\n        const userId = args.userId as string;\n        // Fetch from your database\n        return {\n          name: 'Demo User',\n          email: 'demo@example.com',\n          plan: 'pro',\n        };\n      },\n      'create-support-ticket': async (args) => {\n        // Create ticket in your system\n        return {\n          ticketId: 'TICKET-123',\n          estimatedResponse: '24 hours',\n        };\n      },\n    },\n  });\n\n  // Trigger the action and convert to SSE stream\n  const events = session.trigger(triggerName, input);\n\n  // Return as streaming response\n  return new Response(toSSEStream(events), {\n    headers: {\n      'Content-Type': 'text/event-stream',\n      'Cache-Control': 'no-cache',\n      Connection: 'keep-alive',\n    },\n  });\n}\n```\n\n## Frontend Setup\n\n### 1. Create a Chat Component\n\nUse the `useOctavusChat` hook with the HTTP transport:\n\n```tsx\n// components/chat.tsx\n'use client';\n\nimport { useState, useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';\n\ninterface ChatProps {\n  sessionId: string;\n}\n\nexport function Chat({ sessionId }: ChatProps) {\n  const [inputValue, setInputValue] = useState('');\n\n  // Create a stable transport instance\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { messages, status, error, send } = useOctavusChat({ transport });\n\n  const isStreaming = status === 'streaming';\n\n  const handleSubmit = async (e: React.FormEvent) => {\n    e.preventDefault();\n    if (!inputValue.trim() || isStreaming) return;\n\n    const message = inputValue.trim();\n    setInputValue('');\n\n    // Add user message and trigger in one call\n    await send(\n      'user-message',\n      { USER_MESSAGE: message },\n      { userMessage: { content: message } },\n    );\n  };\n\n  return (\n    <div className=\"flex flex-col h-full\">\n      {/* Messages */}\n      <div className=\"flex-1 overflow-y-auto p-4 space-y-4\">\n        {messages.map((msg) => (\n          <MessageBubble key={msg.id} message={msg} />\n        ))}\n      </div>\n\n      {/* Input */}\n      <form onSubmit={handleSubmit} className=\"p-4 border-t\">\n        <div className=\"flex gap-2\">\n          <input\n            type=\"text\"\n            value={inputValue}\n            onChange={(e) => setInputValue(e.target.value)}\n            placeholder=\"Type a message...\"\n            className=\"flex-1 px-4 py-2 border rounded-lg\"\n            disabled={isStreaming}\n          />\n          <button\n            type=\"submit\"\n            disabled={isStreaming}\n            className=\"px-4 py-2 bg-blue-500 text-white rounded-lg disabled:opacity-50\"\n          >\n            Send\n          </button>\n        </div>\n      </form>\n    </div>\n  );\n}\n\nfunction MessageBubble({ message }: { message: UIMessage }) {\n  const isUser = message.role === 'user';\n\n  return (\n    <div className={`flex ${isUser ? 'justify-end' : 'justify-start'}`}>\n      <div\n        className={`p-3 rounded-lg max-w-md ${\n          isUser ? 'bg-blue-500 text-white' : 'bg-gray-100'\n        }`}\n      >\n        {message.parts.map((part, i) => {\n          if (part.type === 'text') {\n            return <p key={i}>{part.text}</p>;\n          }\n          return null;\n        })}\n\n        {/* Streaming indicator */}\n        {message.status === 'streaming' && (\n          <span className=\"inline-block w-2 h-4 bg-gray-400 animate-pulse ml-1\" />\n        )}\n      </div>\n    </div>\n  );\n}\n```\n\n### 2. Create Session and Render Chat\n\n```tsx\n// app/chat/page.tsx\n'use client';\n\nimport { useEffect, useState } from 'react';\nimport { Chat } from '@/components/chat';\n\nexport default function ChatPage() {\n  const [sessionId, setSessionId] = useState<string | null>(null);\n\n  useEffect(() => {\n    async function createSession() {\n      const response = await fetch('/api/chat/create', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({\n          agentSlug: 'support-chat',\n          input: {\n            COMPANY_NAME: 'Acme Corp',\n            PRODUCT_NAME: 'Widget Pro',\n          },\n        }),\n      });\n      const { sessionId } = await response.json();\n      setSessionId(sessionId);\n    }\n\n    createSession();\n  }, []);\n\n  if (!sessionId) {\n    return <div>Loading...</div>;\n  }\n\n  return <Chat sessionId={sessionId} />;\n}\n```\n\n## Environment Variables\n\nAdd these to your `.env.local`:\n\n```bash\nOCTAVUS_API_URL=https://octavus.ai\nOCTAVUS_API_KEY=your-api-key-here\n```\n\n## What's Next?\n\nNow that you have a basic integration working:\n\n- [Learn about the protocol](/docs/protocol/overview) to define custom agent behavior\n- [Explore the Server SDK](/docs/server-sdk/overview) for advanced backend features\n- [Build rich UIs](/docs/client-sdk/overview) with the Client SDK\n",
+        excerpt: "Quick Start This guide will walk you through integrating Octavus into your application in under 10 minutes.  Prerequisites - Node.js 18+ - An Octavus account with API key - A Next.js application (or...",
+        order: 2
+      }
+    ]
+  },
+  {
+    slug: "server-sdk",
+    title: "Server SDK",
+    description: "Backend integration with @octavus/server-sdk for Node.js applications.",
+    order: 2,
+    docs: [
+      {
+        slug: "server-sdk/overview",
+        section: "server-sdk",
+        title: "Overview",
+        description: "Introduction to the Octavus Server SDK for backend integration.",
+        content: "\n# Server SDK Overview\n\nThe `@octavus/server-sdk` package provides a Node.js SDK for integrating Octavus agents into your backend application. It handles session management, streaming, and the tool execution continuation loop.\n\n**Current version:** `0.0.7`\n\n## Installation\n\n```bash\nnpm install @octavus/server-sdk\n```\n\n## Basic Usage\n\n```typescript\nimport { OctavusClient } from '@octavus/server-sdk';\n\nconst client = new OctavusClient({\n  baseUrl: 'https://octavus.ai',\n  apiKey: 'your-api-key',\n});\n```\n\n## Key Features\n\n### Session Management\n\nCreate and manage agent sessions:\n\n```typescript\n// Create a new session\nconst sessionId = await client.agentSessions.create('agent-id', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n});\n\n// Get UI-ready session messages (for session restore)\nconst session = await client.agentSessions.getMessages(sessionId);\n```\n\n### Tool Handlers\n\nTools run on your server with your data:\n\n```typescript\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    'get-user-account': async (args) => {\n      // Access your database, APIs, etc.\n      return await db.users.findById(args.userId);\n    },\n  },\n});\n```\n\n### Streaming\n\nAll responses stream in real-time:\n\n```typescript\nimport { toSSEStream } from '@octavus/server-sdk';\n\n// trigger() returns an async generator of events\nconst events = session.trigger('user-message', {\n  USER_MESSAGE: 'Hello!',\n});\n\n// Convert to SSE stream for HTTP responses\nreturn new Response(toSSEStream(events), {\n  headers: { 'Content-Type': 'text/event-stream' },\n});\n```\n\n## API Reference\n\n### OctavusClient\n\nThe main entry point for interacting with Octavus.\n\n```typescript\ninterface OctavusClientConfig {\n  baseUrl: string;  // Octavus API URL\n  apiKey?: string;  // Your API key\n}\n\nclass OctavusClient {\n  readonly agents: AgentsApi;\n  readonly agentSessions: AgentSessionsApi;\n\n  constructor(config: OctavusClientConfig);\n}\n```\n\n### AgentSessionsApi\n\nManages agent sessions.\n\n```typescript\nclass AgentSessionsApi {\n  // Create a new session\n  async create(agentId: string, input?: Record<string, unknown>): Promise<string>;\n\n  // Get full session state (for debugging/internal use)\n  async get(sessionId: string): Promise<SessionState>;\n\n  // Get UI-ready messages (for client display)\n  async getMessages(sessionId: string): Promise<UISessionState>;\n\n  // Attach to a session for triggering\n  attach(sessionId: string, options?: SessionAttachOptions): AgentSession;\n}\n\n// Full session state (internal format)\ninterface SessionState {\n  id: string;\n  agentId: string;\n  input: Record<string, unknown>;\n  variables: Record<string, unknown>;\n  resources: Record<string, unknown>;\n  messages: ChatMessage[];  // Internal message format\n  createdAt: string;\n  updatedAt: string;\n}\n\n// UI-ready session state\ninterface UISessionState {\n  sessionId: string;\n  agentId: string;\n  messages: UIMessage[];  // UI-ready messages for frontend\n}\n```\n\n### AgentSession\n\nHandles triggering and streaming for a specific session.\n\n```typescript\nclass AgentSession {\n  // Trigger an action and stream parsed events\n  trigger(\n    triggerName: string,\n    input?: Record<string, unknown>\n  ): AsyncGenerator<StreamEvent>;\n\n  // Get the session ID\n  getSessionId(): string;\n}\n\n// Helper to convert events to SSE stream\nfunction toSSEStream(events: AsyncIterable<StreamEvent>): ReadableStream<Uint8Array>;\n```\n\n## Next Steps\n\n- [Sessions](/docs/server-sdk/sessions) \u2014 Deep dive into session management\n- [Tools](/docs/server-sdk/tools) \u2014 Implementing tool handlers\n- [Streaming](/docs/server-sdk/streaming) \u2014 Understanding stream events\n",
+        excerpt: "Server SDK Overview The  package provides a Node.js SDK for integrating Octavus agents into your backend application. It handles session management, streaming, and the tool execution continuation...",
+        order: 1
+      },
+      {
+        slug: "server-sdk/sessions",
+        section: "server-sdk",
+        title: "Sessions",
+        description: "Managing agent sessions with the Server SDK.",
+        content: "\n# Sessions\n\nSessions represent conversations with an agent. They store conversation history, track resources and variables, and enable stateful interactions.\n\n## Creating Sessions\n\nCreate a session by specifying the agent ID and initial input variables:\n\n```typescript\nimport { OctavusClient } from '@octavus/server-sdk';\n\nconst client = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n\n// Create a session with the support-chat agent\nconst sessionId = await client.agentSessions.create('support-chat', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n  USER_ID: 'user-123', // Optional inputs\n});\n\nconsole.log('Session created:', sessionId);\n```\n\n## Getting Session Messages\n\nTo restore a conversation on page load, use `getMessages()` to retrieve UI-ready messages:\n\n```typescript\nconst session = await client.agentSessions.getMessages(sessionId);\n\nconsole.log({\n  sessionId: session.sessionId,\n  agentId: session.agentId,\n  messages: session.messages.length,  // UIMessage[] ready for frontend\n});\n```\n\nThe returned messages can be passed directly to the client SDK's `initialMessages` option.\n\n### UISessionState Interface\n\n```typescript\ninterface UISessionState {\n  sessionId: string;\n  agentId: string;\n  messages: UIMessage[];  // UI-ready conversation history\n}\n```\n\n## Full Session State (Debug)\n\nFor debugging or internal use, you can retrieve the complete session state including all variables and internal message format:\n\n```typescript\nconst state = await client.agentSessions.get(sessionId);\n\nconsole.log({\n  id: state.id,\n  agentId: state.agentId,\n  messages: state.messages.length,  // ChatMessage[] (internal format)\n  resources: state.resources,\n  variables: state.variables,\n  createdAt: state.createdAt,\n  updatedAt: state.updatedAt,\n});\n```\n\n> **Note**: Use `getMessages()` for client-facing code. The `get()` method returns internal message format that includes hidden content not intended for end users.\n\n## Attaching to Sessions\n\nTo trigger actions on a session, you need to attach to it first:\n\n```typescript\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    // Tool handlers (see Tools documentation)\n  },\n  resources: [\n    // Resource watchers (optional)\n  ],\n});\n```\n\n## Triggering Actions\n\nOnce attached, trigger actions on the session:\n\n```typescript\nimport { toSSEStream } from '@octavus/server-sdk';\n\n// trigger() returns an async generator of events\nconst events = session.trigger('user-message', {\n  USER_MESSAGE: 'How do I reset my password?',\n});\n\n// Convert to SSE stream for HTTP responses\nreturn new Response(toSSEStream(events), {\n  headers: { 'Content-Type': 'text/event-stream' },\n});\n```\n\n## Session Lifecycle\n\n```mermaid\nflowchart TD\n    A[1. CREATE] --> B[2. ATTACH]\n    B --> C[3. TRIGGER]\n    C --> C\n    C --> D[4. RETRIEVE]\n    D --> C\n    C --> E[5. EXPIRE]\n\n    A -.- A1[\"`**client.agentSessions.create()**\n    Returns sessionId\n    Initializes state`\"]\n    \n    B -.- B1[\"`**client.agentSessions.attach()**\n    Configure tool handlers\n    Configure resource watchers`\"]\n    \n    C -.- C1[\"`**session.trigger()**\n    Execute handler\n    Stream events\n    Update state`\"]\n    \n    D -.- D1[\"`**client.agentSessions.getMessages()**\n    Get UI-ready messages\n    Restore conversation`\"]\n    \n    E -.- E1[\"`Sessions expire after\n    24 hours (configurable)`\"]\n```\n\n## Restoring Sessions\n\nWhen a user returns to your app, restore their session:\n\n```typescript\n// On page load\nconst session = await client.agentSessions.getMessages(sessionId);\n\n// Pass messages to frontend - they're already UI-ready\nreturn {\n  sessionId: session.sessionId,\n  messages: session.messages,  // UIMessage[] with parts\n};\n```\n\nThe `messages` array contains `UIMessage` objects with properly structured `parts`, enabling direct use with the client SDK's `initialMessages` option.\n\n## Error Handling\n\n```typescript\nimport { ApiError } from '@octavus/server-sdk';\n\ntry {\n  const session = await client.agentSessions.getMessages(sessionId);\n} catch (error) {\n  if (error instanceof ApiError) {\n    if (error.status === 404) {\n      // Session not found or expired\n      console.log('Session expired, create a new one');\n    } else {\n      console.error('API Error:', error.message);\n    }\n  }\n  throw error;\n}\n```\n",
+        excerpt: "Sessions Sessions represent conversations with an agent. They store conversation history, track resources and variables, and enable stateful interactions.  Creating Sessions Create a session by...",
+        order: 2
+      },
+      {
+        slug: "server-sdk/tools",
+        section: "server-sdk",
+        title: "Tools",
+        description: "Implementing tool handlers with the Server SDK.",
+        content: "\n# Tools\n\nTools extend what agents can do. In Octavus, tools execute on your server, giving you full control over data access and authentication.\n\n## Why Tools Run on Your Server\n\nUnlike traditional AI platforms where tools run in a sandbox, Octavus tools execute in your backend:\n\n- \u2705 **Full data access** \u2014 Query your database directly\n- \u2705 **Your authentication** \u2014 Use your existing auth context\n- \u2705 **No data exposure** \u2014 Sensitive data never leaves your infrastructure\n- \u2705 **Custom logic** \u2014 Any complexity you need\n\n## Defining Tool Handlers\n\nTool handlers are async functions that receive arguments and return results:\n\n```typescript\nimport type { ToolHandlers } from '@octavus/server-sdk';\n\nconst tools: ToolHandlers = {\n  'get-user-account': async (args) => {\n    const userId = args.userId as string;\n    \n    // Query your database\n    const user = await db.users.findById(userId);\n    \n    return {\n      name: user.name,\n      email: user.email,\n      plan: user.subscription.plan,\n      createdAt: user.createdAt.toISOString(),\n    };\n  },\n  \n  'create-support-ticket': async (args) => {\n    const summary = args.summary as string;\n    const priority = args.priority as string;\n    \n    // Create ticket in your system\n    const ticket = await ticketService.create({\n      summary,\n      priority,\n      source: 'ai-chat',\n    });\n    \n    return {\n      ticketId: ticket.id,\n      estimatedResponse: getEstimatedResponse(priority),\n    };\n  },\n};\n```\n\n## Using Tools in Sessions\n\nPass tool handlers when attaching to a session:\n\n```typescript\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    'get-user-account': async (args) => {\n      // Implementation\n    },\n    'create-support-ticket': async (args) => {\n      // Implementation\n    },\n  },\n});\n```\n\n## Tool Handler Signature\n\n```typescript\ntype ToolHandler = (args: Record<string, unknown>) => Promise<unknown>;\ntype ToolHandlers = Record<string, ToolHandler>;\n```\n\n### Arguments\n\nArguments are passed as a `Record<string, unknown>`. Type-check as needed:\n\n```typescript\n'search-products': async (args) => {\n  const query = args.query as string;\n  const category = args.category as string | undefined;\n  const maxPrice = args.maxPrice as number | undefined;\n  \n  return await productSearch({ query, category, maxPrice });\n}\n```\n\n### Return Values\n\nReturn any JSON-serializable value. The result is:\n1. Sent back to the LLM as context\n2. Stored in session state\n3. Optionally stored in a variable for protocol use\n\n```typescript\n// Return object\nreturn { id: '123', status: 'created' };\n\n// Return array\nreturn [{ id: '1' }, { id: '2' }];\n\n// Return primitive\nreturn 42;\n\n// Return null for \"no result\"\nreturn null;\n```\n\n## Error Handling\n\nThrow errors for failures. They're captured and sent to the LLM:\n\n```typescript\n'get-user-account': async (args) => {\n  const userId = args.userId as string;\n  \n  const user = await db.users.findById(userId);\n  \n  if (!user) {\n    throw new Error(`User not found: ${userId}`);\n  }\n  \n  return user;\n}\n```\n\nThe LLM receives the error message and can respond appropriately (e.g., \"I couldn't find that account\").\n\n## Tool Execution Flow\n\nWhen the LLM calls a tool:\n\n```mermaid\nsequenceDiagram\n    participant LLM\n    participant Platform as Octavus Platform\n    participant SDK as Server SDK\n    participant UI as Your Frontend\n\n    LLM->>Platform: 1. Decides to call tool\n    Platform-->>UI: tool-input-start, tool-input-delta\n    Platform-->>UI: tool-input-available\n    Platform-->>SDK: 2. tool-request (stream pauses)\n    \n    Note over SDK: 3. Execute handler<br/>tools['get-user']()\n    \n    SDK-->>UI: 4. tool-output-available\n    SDK->>Platform: 5. POST /trigger with results\n    Platform->>LLM: 6. Continue with results\n    LLM-->>Platform: Response\n    Platform-->>UI: text-delta events\n    \n    Note over LLM,UI: 7. Repeat if more tools needed\n```\n\n## Accessing Request Context\n\nFor request-specific data (auth, headers), create handlers dynamically:\n\n```typescript\nimport { toSSEStream } from '@octavus/server-sdk';\n\n// In your API route\nexport async function POST(request: Request) {\n  const authToken = request.headers.get('Authorization');\n  const user = await validateToken(authToken);\n  \n  const session = client.agentSessions.attach(sessionId, {\n    tools: {\n      'get-user-account': async (args) => {\n        // Use request context\n        return await db.users.findById(user.id);\n      },\n      'create-order': async (args) => {\n        // Create with user context\n        return await orderService.create({\n          ...args,\n          userId: user.id,\n          createdBy: user.email,\n        });\n      },\n    },\n  });\n  \n  const events = session.trigger(triggerName, input);\n  return new Response(toSSEStream(events));\n}\n```\n\n## Best Practices\n\n### 1. Validate Arguments\n\n```typescript\n'create-ticket': async (args) => {\n  const summary = args.summary;\n  if (typeof summary !== 'string' || summary.length === 0) {\n    throw new Error('Summary is required');\n  }\n  // ...\n}\n```\n\n### 2. Handle Timeouts\n\n```typescript\n'external-api-call': async (args) => {\n  const controller = new AbortController();\n  const timeout = setTimeout(() => controller.abort(), 10000);\n  \n  try {\n    const response = await fetch(url, { signal: controller.signal });\n    return await response.json();\n  } finally {\n    clearTimeout(timeout);\n  }\n}\n```\n\n### 3. Log Tool Calls\n\n```typescript\n'search-products': async (args) => {\n  console.log('Tool call: search-products', { args });\n  \n  const result = await productSearch(args);\n  \n  console.log('Tool result: search-products', { \n    resultCount: result.length \n  });\n  \n  return result;\n}\n```\n\n",
+        excerpt: "Tools Tools extend what agents can do. In Octavus, tools execute on your server, giving you full control over data access and authentication.  Why Tools Run on Your Server Unlike traditional AI...",
+        order: 3
+      },
+      {
+        slug: "server-sdk/streaming",
+        section: "server-sdk",
+        title: "Streaming",
+        description: "Understanding stream events from the Server SDK.",
+        content: "\n# Streaming\n\nAll Octavus responses stream in real-time using Server-Sent Events (SSE). This enables responsive UX with incremental updates.\n\n## Stream Response\n\nWhen you trigger an action, you get an async generator of parsed events:\n\n```typescript\nimport { toSSEStream } from '@octavus/server-sdk';\n\n// trigger() returns an async generator of StreamEvent\nconst events = session.trigger('user-message', { \n  USER_MESSAGE: 'Hello!' \n});\n\n// For HTTP endpoints, convert to SSE stream\nreturn new Response(toSSEStream(events), {\n  headers: {\n    'Content-Type': 'text/event-stream',\n    'Cache-Control': 'no-cache',\n    'Connection': 'keep-alive',\n  },\n});\n\n// For sockets, iterate events directly\nfor await (const event of events) {\n  conn.write(JSON.stringify(event));\n}\n```\n\n## Event Types\n\nThe stream emits various event types. Octavus events align with the [Vercel AI SDK](https://sdk.vercel.ai/) naming conventions where applicable.\n\n### Lifecycle Events\n\n```typescript\n// Stream started\n{ type: 'start', messageId: '...' }\n\n// Stream completed\n{ type: 'finish', finishReason: 'stop' }\n\n// Possible finish reasons:\n// - 'stop': Normal completion\n// - 'tool-calls': Waiting for tool execution (handled by SDK)\n// - 'length': Max tokens reached\n// - 'content-filter': Content filtered\n// - 'error': Error occurred\n// - 'other': Other reason\n\n// Error event\n{ type: 'error', errorText: 'Something went wrong' }\n```\n\n### Block Events\n\nTrack execution progress:\n\n```typescript\n// Block started\n{ type: 'block-start', blockId: '...', blockName: 'Respond to user', blockType: 'next-message', display: 'stream', thread: 'main' }\n\n// Block completed\n{ type: 'block-end', blockId: '...', summary: 'Generated response' }\n```\n\n### Text Events\n\nStreaming text content:\n\n```typescript\n// Text generation started\n{ type: 'text-start', id: '...' }\n\n// Incremental text (most common event)\n{ type: 'text-delta', id: '...', delta: 'Hello' }\n{ type: 'text-delta', id: '...', delta: '!' }\n{ type: 'text-delta', id: '...', delta: ' How' }\n{ type: 'text-delta', id: '...', delta: ' can' }\n{ type: 'text-delta', id: '...', delta: ' I' }\n{ type: 'text-delta', id: '...', delta: ' help?' }\n\n// Text generation ended\n{ type: 'text-end', id: '...' }\n```\n\n### Reasoning Events\n\nExtended reasoning (for supported models like Claude):\n\n```typescript\n// Reasoning started\n{ type: 'reasoning-start', id: '...' }\n\n// Reasoning content\n{ type: 'reasoning-delta', id: '...', delta: 'Let me analyze this request...' }\n\n// Reasoning ended\n{ type: 'reasoning-end', id: '...' }\n```\n\n### Tool Events\n\nTool call lifecycle:\n\n```typescript\n// Tool input started\n{ type: 'tool-input-start', toolCallId: '...', toolName: 'get-user-account', title: 'Looking up account' }\n\n// Tool input/arguments streaming\n{ type: 'tool-input-delta', toolCallId: '...', inputTextDelta: '{\"userId\":\"user-123\"}' }\n\n// Tool input streaming ended\n{ type: 'tool-input-end', toolCallId: '...' }\n\n// Tool input is complete and available\n{ type: 'tool-input-available', toolCallId: '...', toolName: 'get-user-account', input: { userId: 'user-123' } }\n\n// Tool output available (success)\n{ type: 'tool-output-available', toolCallId: '...', output: { name: 'Demo User', email: '...' } }\n\n// Tool output error (failure)\n{ type: 'tool-output-error', toolCallId: '...', errorText: 'User not found' }\n```\n\n### Resource Events\n\nResource updates:\n\n```typescript\n{ type: 'resource-update', name: 'CONVERSATION_SUMMARY', value: 'User asked about...' }\n```\n\n## Display Modes\n\nEach block/tool specifies how it should appear to users:\n\n| Mode | Description |\n|------|-------------|\n| `hidden` | Not shown to user (background work) |\n| `name` | Shows block/tool name |\n| `description` | Shows description text |\n| `stream` | Streams content to chat |\n\n**Note**: Hidden events are filtered before reaching the client SDK. Your frontend only sees user-facing events.\n\n## Stream Event Type\n\n```typescript\ntype StreamEvent =\n  // Lifecycle\n  | StartEvent\n  | FinishEvent\n  | ErrorEvent\n  // Text\n  | TextStartEvent\n  | TextDeltaEvent\n  | TextEndEvent\n  // Reasoning\n  | ReasoningStartEvent\n  | ReasoningDeltaEvent\n  | ReasoningEndEvent\n  // Tool Input/Output\n  | ToolInputStartEvent\n  | ToolInputDeltaEvent\n  | ToolInputEndEvent\n  | ToolInputAvailableEvent\n  | ToolOutputAvailableEvent\n  | ToolOutputErrorEvent\n  // Octavus-Specific\n  | BlockStartEvent\n  | BlockEndEvent\n  | ResourceUpdateEvent\n  | ToolRequestEvent;\n```\n\n## Error Recovery\n\nThe SDK handles common error scenarios:\n\n```typescript\n// Network errors are caught and emitted\n{ type: 'error', errorText: 'Network request failed' }\n\n// Tool errors are captured per-tool\n{ type: 'tool-output-error', toolCallId: '...', errorText: 'Handler threw exception' }\n\n// The stream always ends with either 'finish' or 'error'\n```\n",
+        excerpt: "Streaming All Octavus responses stream in real-time using Server-Sent Events (SSE). This enables responsive UX with incremental updates.  Stream Response When you trigger an action, you get an async...",
+        order: 4
+      }
+    ]
+  },
+  {
+    slug: "client-sdk",
+    title: "Client SDK",
+    description: "Frontend integration with @octavus/react for React applications and @octavus/client-sdk for other frameworks.",
+    order: 3,
+    docs: [
+      {
+        slug: "client-sdk/overview",
+        section: "client-sdk",
+        title: "Overview",
+        description: "Introduction to the Octavus Client SDKs for building chat interfaces.",
+        content: "\n# Client SDK Overview\n\nOctavus provides two packages for frontend integration:\n\n| Package | Purpose | Use When |\n|---------|---------|----------|\n| `@octavus/react` | React hooks and bindings | Building React applications |\n| `@octavus/client-sdk` | Framework-agnostic core | Using Vue, Svelte, vanilla JS, or custom integrations |\n\n**Most users should install `@octavus/react`** \u2014 it includes everything from `@octavus/client-sdk` plus React-specific hooks.\n\n## Installation\n\n### React Applications\n\n```bash\nnpm install @octavus/react\n```\n\n**Current version:** `0.0.7`\n\n### Other Frameworks\n\n```bash\nnpm install @octavus/client-sdk\n```\n\n**Current version:** `0.0.7`\n\n## Transport Pattern\n\nThe Client SDK uses a **transport abstraction** to handle communication with your backend. This gives you flexibility in how events are delivered:\n\n| Transport | Use Case | Docs |\n|-----------|----------|------|\n| `createHttpTransport` | HTTP/SSE (Next.js, Express, etc.) | [HTTP Transport](/docs/client-sdk/http-transport) |\n| `createSocketTransport` | WebSocket, SockJS, or other socket protocols | [Socket Transport](/docs/client-sdk/socket-transport) |\n\nWhen the transport changes (e.g., when `sessionId` changes), the `useOctavusChat` hook automatically reinitializes with the new transport.\n\n> **Recommendation**: Use HTTP transport unless you specifically need WebSocket features (custom real-time events, Meteor/Phoenix, etc.).\n\n## React Usage\n\nThe `useOctavusChat` hook provides state management and streaming for React applications:\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  // Create a stable transport instance (memoized on sessionId)\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { messages, status, send } = useOctavusChat({ transport });\n\n  const sendMessage = async (text: string) => {\n    await send(\n      'user-message',\n      { USER_MESSAGE: text },\n      { userMessage: { content: text } },\n    );\n  };\n\n  return (\n    <div>\n      {messages.map((msg) => (\n        <MessageBubble key={msg.id} message={msg} />\n      ))}\n    </div>\n  );\n}\n\nfunction MessageBubble({ message }: { message: UIMessage }) {\n  return (\n    <div>\n      {message.parts.map((part, i) => {\n        if (part.type === 'text') {\n          return <p key={i}>{part.text}</p>;\n        }\n        return null;\n      })}\n    </div>\n  );\n}\n```\n\n## Framework-Agnostic Usage\n\nThe `OctavusChat` class can be used with any framework or vanilla JavaScript:\n\n```typescript\nimport { OctavusChat, createHttpTransport } from '@octavus/client-sdk';\n\nconst transport = createHttpTransport({\n  triggerRequest: (triggerName, input) =>\n    fetch('/api/trigger', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ sessionId, triggerName, input }),\n    }),\n});\n\nconst chat = new OctavusChat({ transport });\n\n// Subscribe to state changes\nconst unsubscribe = chat.subscribe(() => {\n  console.log('Messages:', chat.messages);\n  console.log('Status:', chat.status);\n  // Update your UI here\n});\n\n// Send a message\nawait chat.send(\n  'user-message',\n  { USER_MESSAGE: 'Hello' },\n  { userMessage: { content: 'Hello' } },\n);\n\n// Cleanup when done\nunsubscribe();\n```\n\n## Key Features\n\n### Unified Send Function\n\nThe `send` function handles both user message display and agent triggering in one call:\n\n```tsx\nconst { send } = useOctavusChat({ transport });\n\n// Add user message to UI and trigger agent\nawait send(\n  'user-message',\n  { USER_MESSAGE: text },\n  { userMessage: { content: text } },\n);\n\n// Trigger without adding a user message (e.g., button click)\nawait send('request-human');\n```\n\n### Message Parts\n\nMessages contain ordered `parts` for rich content:\n\n```tsx\nconst { messages } = useOctavusChat({ transport });\n\n// Each message has typed parts\nmessage.parts.map((part) => {\n  switch (part.type) {\n    case 'text':       // Text content\n    case 'reasoning':  // Extended reasoning/thinking\n    case 'tool-call':  // Tool execution\n    case 'operation':  // Internal operations (set-resource, etc.)\n  }\n});\n```\n\n### Status Tracking\n\n```tsx\nconst { status } = useOctavusChat({ transport });\n\n// status: 'idle' | 'streaming' | 'error'\n```\n\n### Stop Streaming\n\n```tsx\nconst { stop } = useOctavusChat({ transport });\n\n// Stop current stream and finalize message\nstop();\n```\n\n## Hook Reference (React)\n\n### useOctavusChat\n\n```typescript\nfunction useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn;\n\ninterface OctavusChatOptions {\n  // Required: Transport for streaming events\n  transport: Transport;\n\n  // Optional: Pre-populate with existing messages (session restore)\n  initialMessages?: UIMessage[];\n\n  // Optional: Callbacks\n  onError?: (error: Error) => void;\n  onFinish?: () => void;\n  onResourceUpdate?: (name: string, value: unknown) => void;\n}\n\ninterface UseOctavusChatReturn {\n  // State\n  messages: UIMessage[];\n  status: ChatStatus;  // 'idle' | 'streaming' | 'error'\n  error: Error | null;\n\n  // Actions\n  send: (\n    triggerName: string,\n    input?: Record<string, unknown>,\n    options?: { userMessage?: UserMessageInput }\n  ) => Promise<void>;\n  stop: () => void;\n}\n\ninterface UserMessageInput {\n  content: string;\n}\n```\n\n## Transport Reference\n\n### createHttpTransport\n\nCreates an HTTP/SSE transport using native `fetch()`:\n\n```typescript\nimport { createHttpTransport } from '@octavus/react';\n\nconst transport = createHttpTransport({\n  triggerRequest: (triggerName, input) =>\n    fetch('/api/trigger', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ sessionId, triggerName, input }),\n    }),\n});\n```\n\n### createSocketTransport\n\nCreates a WebSocket/SockJS transport for real-time connections:\n\n```typescript\nimport { createSocketTransport } from '@octavus/react';\n\nconst transport = createSocketTransport({\n  connect: () =>\n    new Promise((resolve, reject) => {\n      const ws = new WebSocket(`wss://api.example.com/stream?sessionId=${sessionId}`);\n      ws.onopen = () => resolve(ws);\n      ws.onerror = () => reject(new Error('Connection failed'));\n    }),\n});\n```\n\nFor detailed WebSocket/SockJS usage including custom events, reconnection patterns, and server-side implementation, see [Socket Transport](/docs/client-sdk/socket-transport).\n\n## Class Reference (Framework-Agnostic)\n\n### OctavusChat\n\n```typescript\nclass OctavusChat {\n  constructor(options: OctavusChatOptions);\n\n  // State (read-only)\n  readonly messages: UIMessage[];\n  readonly status: ChatStatus;\n  readonly error: Error | null;\n\n  // Actions\n  send(\n    triggerName: string,\n    input?: Record<string, unknown>,\n    options?: { userMessage?: UserMessageInput }\n  ): Promise<void>;\n  stop(): void;\n\n  // Subscription\n  subscribe(callback: () => void): () => void;  // Returns unsubscribe function\n}\n```\n\n## Next Steps\n\n- [HTTP Transport](/docs/client-sdk/http-transport) \u2014 HTTP/SSE integration (recommended)\n- [Socket Transport](/docs/client-sdk/socket-transport) \u2014 WebSocket and SockJS integration\n- [Messages](/docs/client-sdk/messages) \u2014 Working with message state\n- [Streaming](/docs/client-sdk/streaming) \u2014 Building streaming UIs\n- [Operations](/docs/client-sdk/execution-blocks) \u2014 Showing agent progress\n- [Examples](/docs/examples/overview) \u2014 Complete working examples\n",
+        excerpt: "Client SDK Overview Octavus provides two packages for frontend integration: | Package | Purpose | Use When | |---------|---------|----------| |  | React hooks and bindings | Building React...",
+        order: 1
+      },
+      {
+        slug: "client-sdk/messages",
+        section: "client-sdk",
+        title: "Messages",
+        description: "Working with message state in the Client SDK.",
+        content: "\n# Messages\n\nMessages represent the conversation history. The Client SDK tracks messages automatically and provides structured access to their content through typed parts.\n\n## Message Structure\n\n```typescript\ninterface UIMessage {\n  id: string;\n  role: 'user' | 'assistant';\n  parts: UIMessagePart[];\n  status: 'streaming' | 'done';\n  createdAt: Date;\n}\n```\n\n### Message Parts\n\nMessages contain ordered `parts` that preserve content ordering:\n\n```typescript\ntype UIMessagePart =\n  | UITextPart\n  | UIReasoningPart\n  | UIToolCallPart\n  | UIOperationPart;\n\n// Text content\ninterface UITextPart {\n  type: 'text';\n  text: string;\n  status: 'streaming' | 'done';\n  thread?: string;  // For named threads (e.g., \"summary\")\n}\n\n// Extended reasoning/thinking\ninterface UIReasoningPart {\n  type: 'reasoning';\n  text: string;\n  status: 'streaming' | 'done';\n  thread?: string;\n}\n\n// Tool execution\ninterface UIToolCallPart {\n  type: 'tool-call';\n  toolCallId: string;\n  toolName: string;\n  displayName?: string;  // Human-readable name\n  args: Record<string, unknown>;\n  result?: unknown;\n  error?: string;\n  status: 'pending' | 'running' | 'done' | 'error';\n  thread?: string;\n}\n\n// Internal operations (set-resource, serialize-thread)\ninterface UIOperationPart {\n  type: 'operation';\n  operationId: string;\n  name: string;\n  operationType: string;\n  status: 'running' | 'done';\n  thread?: string;\n}\n```\n\n## Sending Messages\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { send } = useOctavusChat({ transport });\n\n  async function handleSend(text: string) {\n    // Add user message to UI and trigger agent\n    await send(\n      'user-message',\n      { USER_MESSAGE: text },\n      { userMessage: { content: text } },\n    );\n  }\n\n  // ...\n}\n```\n\nThe `send` function:\n1. Adds the user message to the UI immediately (if `userMessage` is provided)\n2. Triggers the agent with the specified trigger name and input\n3. Streams the assistant's response back\n\n## Rendering Messages\n\n### Basic Rendering\n\n```tsx\nfunction MessageList({ messages }: { messages: UIMessage[] }) {\n  return (\n    <div className=\"space-y-4\">\n      {messages.map((msg) => (\n        <MessageBubble key={msg.id} message={msg} />\n      ))}\n    </div>\n  );\n}\n\nfunction MessageBubble({ message }: { message: UIMessage }) {\n  const isUser = message.role === 'user';\n\n  return (\n    <div className={isUser ? 'text-right' : 'text-left'}>\n      <div className=\"inline-block p-3 rounded-lg\">\n        {message.parts.map((part, i) => (\n          <PartRenderer key={i} part={part} />\n        ))}\n      </div>\n    </div>\n  );\n}\n```\n\n### Rendering Parts\n\n```tsx\nimport { isOtherThread, type UIMessagePart } from '@octavus/react';\n\nfunction PartRenderer({ part }: { part: UIMessagePart }) {\n  // Check if part belongs to a named thread (e.g., \"summary\")\n  if (isOtherThread(part)) {\n    return <OtherThreadPart part={part} />;\n  }\n\n  switch (part.type) {\n    case 'text':\n      return <TextPart part={part} />;\n\n    case 'reasoning':\n      return (\n        <details className=\"text-gray-500\">\n          <summary>Thinking...</summary>\n          <pre className=\"text-sm\">{part.text}</pre>\n        </details>\n      );\n\n    case 'tool-call':\n      return (\n        <div className=\"bg-gray-100 p-2 rounded text-sm\">\n          \u{1F527} {part.displayName || part.toolName}\n          {part.status === 'done' && ' \u2713'}\n          {part.status === 'error' && ` \u2717 ${part.error}`}\n        </div>\n      );\n\n    case 'operation':\n      return (\n        <div className=\"text-gray-500 text-sm\">\n          {part.name}\n          {part.status === 'done' && ' \u2713'}\n        </div>\n      );\n\n    default:\n      return null;\n  }\n}\n\nfunction TextPart({ part }: { part: UITextPart }) {\n  return (\n    <p>\n      {part.text}\n      {part.status === 'streaming' && (\n        <span className=\"inline-block w-2 h-4 bg-gray-400 animate-pulse ml-1\" />\n      )}\n    </p>\n  );\n}\n```\n\n## Named Threads\n\nContent from named threads (like \"summary\") is identified by the `thread` property. Use the `isOtherThread` helper:\n\n```tsx\nimport { isOtherThread } from '@octavus/react';\n\nfunction PartRenderer({ part }: { part: UIMessagePart }) {\n  if (isOtherThread(part)) {\n    // Render differently for named threads\n    return (\n      <div className=\"bg-amber-50 p-2 rounded border border-amber-200\">\n        <span className=\"text-amber-600 text-sm\">\n          {part.thread}: {part.type === 'text' && part.text}\n        </span>\n      </div>\n    );\n  }\n\n  // Regular rendering for main thread\n  // ...\n}\n```\n\n## Session Restore\n\nWhen restoring a session, fetch messages from your backend and pass them to the hook:\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';\n\ninterface ChatProps {\n  sessionId: string;\n  initialMessages: UIMessage[];\n}\n\nfunction Chat({ sessionId, initialMessages }: ChatProps) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  // Pass existing messages to restore the conversation\n  const { messages } = useOctavusChat({\n    transport,\n    initialMessages,\n  });\n\n  // ...\n}\n```\n\nOn your backend, use `agentSessions.getMessages()` to fetch UI-ready messages:\n\n```typescript\n// Server-side\nconst session = await client.agentSessions.getMessages(sessionId);\n// session.messages is UIMessage[] ready for the client\n```\n\n## Callbacks\n\n```tsx\nuseOctavusChat({\n  transport,\n  onFinish: () => {\n    console.log('Stream completed');\n    // Scroll to bottom, play sound, etc.\n  },\n  onError: (error) => {\n    console.error('Error:', error);\n    toast.error('Failed to get response');\n  },\n  onResourceUpdate: (name, value) => {\n    console.log('Resource updated:', name, value);\n  },\n});\n```\n",
+        excerpt: "Messages Messages represent the conversation history. The Client SDK tracks messages automatically and provides structured access to their content through typed parts.  Message Structure  Message...",
+        order: 2
+      },
+      {
+        slug: "client-sdk/streaming",
+        section: "client-sdk",
+        title: "Streaming",
+        description: "Building streaming UIs with the Client SDK.",
+        content: "\n# Streaming\n\nThe Client SDK provides real-time access to streaming content through the message `parts` array. Each part has its own status, enabling responsive UIs that update as the agent generates responses.\n\n## Streaming State\n\n```tsx\nconst { messages, status, error } = useOctavusChat({ transport });\n\n// status: 'idle' | 'streaming' | 'error'\n// Each message has status: 'streaming' | 'done'\n// Each part has its own status too\n```\n\n## Building a Streaming UI\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { messages, status, error, send, stop } = useOctavusChat({ transport });\n\n  return (\n    <div>\n      {/* Messages with streaming parts */}\n      {messages.map((msg) => (\n        <MessageBubble key={msg.id} message={msg} />\n      ))}\n\n      {/* Error state */}\n      {error && <div className=\"text-red-500\">{error.message}</div>}\n\n      {/* Stop button during streaming */}\n      {status === 'streaming' && <button onClick={stop}>Stop</button>}\n    </div>\n  );\n}\n```\n\n## Rendering Streaming Parts\n\nParts update in real-time during streaming. Use the part's `status` to show appropriate UI:\n\n```tsx\nimport type { UITextPart, UIReasoningPart } from '@octavus/react';\n\nfunction TextPart({ part }: { part: UITextPart }) {\n  return (\n    <div>\n      {part.text}\n      {part.status === 'streaming' && (\n        <span className=\"inline-block w-2 h-4 bg-gray-400 animate-pulse ml-1\" />\n      )}\n    </div>\n  );\n}\n\nfunction ReasoningPart({ part }: { part: UIReasoningPart }) {\n  // Expand while streaming, collapse when done\n  const [expanded, setExpanded] = useState(part.status === 'streaming');\n\n  return (\n    <div className=\"bg-purple-50 p-3 rounded-lg\">\n      <button onClick={() => setExpanded(!expanded)}>\n        {part.status === 'streaming' ? '\u{1F4AD} Thinking...' : '\u{1F4AD} Thought process'}\n        {expanded ? '\u25BC' : '\u25B6'}\n      </button>\n\n      {expanded && (\n        <pre className=\"mt-2 text-sm text-gray-600\">{part.text}</pre>\n      )}\n    </div>\n  );\n}\n```\n\n## Tool Call States\n\nTool calls progress through multiple states:\n\n```tsx\nimport type { UIToolCallPart } from '@octavus/react';\n\nfunction ToolCallPart({ part }: { part: UIToolCallPart }) {\n  return (\n    <div className=\"border rounded p-3\">\n      <div className=\"flex items-center gap-2\">\n        <span className=\"text-lg\">\u{1F527}</span>\n        <span className=\"font-medium\">{part.displayName || part.toolName}</span>\n        <StatusBadge status={part.status} />\n      </div>\n\n      {/* Show result when done */}\n      {part.status === 'done' && part.result && (\n        <pre className=\"mt-2 text-xs bg-gray-50 p-2 rounded\">\n          {JSON.stringify(part.result, null, 2)}\n        </pre>\n      )}\n\n      {/* Show error if failed */}\n      {part.status === 'error' && (\n        <p className=\"mt-2 text-red-500 text-sm\">{part.error}</p>\n      )}\n    </div>\n  );\n}\n\nfunction StatusBadge({ status }: { status: UIToolCallPart['status'] }) {\n  switch (status) {\n    case 'pending':\n      return <span className=\"text-gray-400\">\u25CB</span>;\n    case 'running':\n      return <span className=\"text-blue-500 animate-spin\">\u25D0</span>;\n    case 'done':\n      return <span className=\"text-green-500\">\u2713</span>;\n    case 'error':\n      return <span className=\"text-red-500\">\u2717</span>;\n  }\n}\n```\n\n## Status Indicator\n\n```tsx\nfunction StatusIndicator({ status }: { status: ChatStatus }) {\n  switch (status) {\n    case 'idle':\n      return null;\n    case 'streaming':\n      return <div>Agent is responding...</div>;\n    case 'error':\n      return <div className=\"text-red-500\">Something went wrong</div>;\n  }\n}\n```\n\n## Handling Completion\n\n```tsx\nuseOctavusChat({\n  transport,\n  onFinish: () => {\n    console.log('Stream completed');\n    // Scroll to bottom, play sound, etc.\n  },\n  onError: (error) => {\n    console.error('Stream error:', error);\n    toast.error('Failed to get response');\n  },\n});\n```\n\n## Stop Function\n\nStop the current stream and finalize any partial message:\n\n```tsx\nconst { status, stop } = useOctavusChat({ transport });\n\n// Stop button\n{status === 'streaming' && (\n  <button onClick={stop} className=\"text-gray-500\">\n    Stop generating\n  </button>\n)}\n```\n\nWhen `stop()` is called:\n1. The current request is aborted\n2. Any partial message is finalized with current content\n3. Status changes to `'idle'`\n\n## Named Thread Content\n\nContent from named threads (like \"summary\") streams separately and is identified by the `thread` property:\n\n```tsx\nimport { isOtherThread, type UIMessage } from '@octavus/react';\n\nfunction MessageBubble({ message }: { message: UIMessage }) {\n  // Separate main thread from named threads\n  const mainParts = message.parts.filter((p) => !isOtherThread(p));\n  const otherParts = message.parts.filter((p) => isOtherThread(p));\n\n  return (\n    <div>\n      {/* Main conversation */}\n      {mainParts.map((part, i) => (\n        <PartRenderer key={i} part={part} />\n      ))}\n\n      {/* Named thread content (e.g., summarization) */}\n      {otherParts.length > 0 && (\n        <div className=\"bg-amber-50 p-3 rounded mt-4 border border-amber-200\">\n          <div className=\"text-amber-600 font-medium mb-2\">\n            Background processing\n          </div>\n          {otherParts.map((part, i) => (\n            <PartRenderer key={i} part={part} />\n          ))}\n        </div>\n      )}\n    </div>\n  );\n}\n```\n",
+        excerpt: "Streaming The Client SDK provides real-time access to streaming content through the message  array. Each part has its own status, enabling responsive UIs that update as the agent generates responses....",
+        order: 3
+      },
+      {
+        slug: "client-sdk/execution-blocks",
+        section: "client-sdk",
+        title: "Operations",
+        description: "Showing agent operations and progress with the Client SDK.",
+        content: "\n# Operations\n\nOperations represent internal agent activities like setting resources or serializing threads. They appear as `operation` parts in messages and help users understand what the agent is doing.\n\n## Operation Structure\n\n```typescript\ninterface UIOperationPart {\n  type: 'operation';\n  operationId: string;\n  name: string;           // Human-readable name\n  operationType: string;  // e.g., 'set-resource', 'serialize-thread'\n  status: 'running' | 'done';\n  thread?: string;        // For named threads\n}\n```\n\n## Rendering Operations\n\nOperations are typically shown as compact status indicators:\n\n```tsx\nimport type { UIOperationPart } from '@octavus/react';\n\nfunction OperationCard({ operation }: { operation: UIOperationPart }) {\n  return (\n    <div className=\"flex items-center gap-2 text-sm text-gray-500\">\n      {operation.status === 'running' ? (\n        <span className=\"h-2 w-2 animate-pulse rounded-full bg-blue-500\" />\n      ) : (\n        <span className=\"text-green-500\">\u2713</span>\n      )}\n      <span>{operation.name}</span>\n    </div>\n  );\n}\n```\n\n## Operations in Messages\n\nOperations appear alongside text, reasoning, and tool calls in the message's `parts` array:\n\n```tsx\nimport type { UIMessage, UIMessagePart } from '@octavus/react';\n\nfunction MessageBubble({ message }: { message: UIMessage }) {\n  return (\n    <div>\n      {message.parts.map((part, i) => (\n        <PartRenderer key={i} part={part} />\n      ))}\n    </div>\n  );\n}\n\nfunction PartRenderer({ part }: { part: UIMessagePart }) {\n  switch (part.type) {\n    case 'text':\n      return <TextPart part={part} />;\n    case 'reasoning':\n      return <ReasoningPart part={part} />;\n    case 'tool-call':\n      return <ToolCallCard part={part} />;\n    case 'operation':\n      return <OperationCard operation={part} />;\n    default:\n      return null;\n  }\n}\n```\n\n## Common Operation Types\n\n| Type | Description |\n|------|-------------|\n| `set-resource` | Updating a resource value |\n| `serialize-thread` | Converting thread messages to text |\n\n## Example: Progress During Escalation\n\nWhen a user clicks \"Talk to Human\", multiple operations may occur:\n\n```tsx\nfunction EscalationProgress({ message }: { message: UIMessage }) {\n  const operations = message.parts.filter(\n    (p): p is UIOperationPart => p.type === 'operation'\n  );\n\n  return (\n    <div className=\"space-y-2\">\n      {operations.map((op) => (\n        <div key={op.operationId} className=\"flex items-center gap-2 text-sm\">\n          {op.status === 'running' ? '\u23F3' : '\u2713'}\n          <span>{op.name}</span>\n        </div>\n      ))}\n    </div>\n  );\n}\n\n// Example output during escalation:\n// \u2713 Serialize conversation\n// \u2713 Save conversation summary\n// \u23F3 Creating support ticket...\n```\n\n## Display Modes\n\nOperations are only sent to the client if their protocol block has a visible display mode (`name`, `description`, or `stream`). Hidden operations (`display: hidden`) are filtered out by the platform before reaching the client.\n\nThis means you can safely render all operations without checking display mode \u2014 hidden ones won't be in the message parts.\n\n## Named Thread Operations\n\nOperations can belong to named threads. Use the `thread` property to identify them:\n\n```tsx\nfunction OperationCard({ operation }: { operation: UIOperationPart }) {\n  return (\n    <div className=\"flex items-center gap-2 text-sm\">\n      {operation.thread && (\n        <span className=\"text-amber-500\">[{operation.thread}]</span>\n      )}\n      <span>{operation.name}</span>\n      {operation.status === 'done' && <span className=\"text-green-500\">\u2713</span>}\n    </div>\n  );\n}\n```\n",
+        excerpt: "Operations Operations represent internal agent activities like setting resources or serializing threads. They appear as  parts in messages and help users understand what the agent is doing. ...",
+        order: 4
+      },
+      {
+        slug: "client-sdk/socket-transport",
+        section: "client-sdk",
+        title: "Socket Transport",
+        description: "Using WebSocket or SockJS for real-time streaming with Octavus.",
+        content: "\n# Socket Transport\n\nThe socket transport enables real-time bidirectional communication using WebSocket or SockJS. Use this when you need persistent connections, custom server events, or when HTTP/SSE isn't suitable for your infrastructure.\n\n## When to Use Socket Transport\n\n| Use Case | Recommended Transport |\n|----------|----------------------|\n| Standard web apps (Next.js, etc.) | HTTP (`createHttpTransport`) |\n| Real-time apps with custom events | Socket (`createSocketTransport`) |\n| Apps behind proxies that don't support SSE | Socket |\n| Need for typing indicators, presence, etc. | Socket |\n| Meteor, Phoenix, or socket-based frameworks | Socket |\n\n## Patterns Overview\n\nThere are two main patterns for socket-based integrations:\n\n| Pattern | When to Use |\n|---------|-------------|\n| [Server-Managed Sessions](#server-managed-sessions-recommended) | **Recommended.** Server creates sessions lazily. Client doesn't need sessionId. |\n| [Client-Provided Session ID](#client-provided-session-id) | When client must control session creation or pass sessionId from URL. |\n\n## Server-Managed Sessions (Recommended)\n\nThe cleanest pattern is to have the server manage session lifecycle. The client never needs to know about `sessionId` \u2014 the server creates it lazily on first message.\n\n### Client Setup\n\n```typescript\nimport { useMemo } from 'react';\nimport SockJS from 'sockjs-client';\nimport { useOctavusChat, createSocketTransport, type SocketLike } from '@octavus/react';\n\nfunction connectSocket(): Promise<SocketLike> {\n  return new Promise((resolve, reject) => {\n    const sock = new SockJS('/octavus');\n    sock.onopen = () => resolve(sock);\n    sock.onerror = () => reject(new Error('Connection failed'));\n  });\n}\n\nfunction Chat() {\n  // Transport is stable \u2014 no dependencies on sessionId\n  const transport = useMemo(\n    () => createSocketTransport({ connect: connectSocket }),\n    [],\n  );\n\n  const { messages, status, send } = useOctavusChat({ transport });\n\n  const sendMessage = async (text: string) => {\n    await send(\n      'user-message',\n      { USER_MESSAGE: text },\n      { userMessage: { content: text } },\n    );\n  };\n\n  // ... render messages\n}\n```\n\n### Server Setup (Express + SockJS)\n\nThe server creates a session on first trigger message:\n\n```typescript\nimport sockjs from 'sockjs';\nimport { OctavusClient, type AgentSession } from '@octavus/server-sdk';\n\nconst client = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n\nfunction createSocketHandler() {\n  return (conn: sockjs.Connection) => {\n    let session: AgentSession | null = null;\n    let abortController: AbortController | null = null;\n\n    conn.on('data', (rawData: string) => {\n      void handleMessage(rawData);\n    });\n\n    async function handleMessage(rawData: string) {\n      const msg = JSON.parse(rawData);\n\n      if (msg.type === 'stop') {\n        abortController?.abort();\n        return;\n      }\n\n      if (msg.type === 'trigger') {\n        // Create session lazily on first trigger\n        if (!session) {\n          const sessionId = await client.agentSessions.create('your-agent-id', {\n            // Initial input variables\n            COMPANY_NAME: 'Acme Corp',\n          });\n          session = client.agentSessions.attach(sessionId, {\n            tools: {\n              // Your tool handlers\n            },\n          });\n        }\n\n        abortController = new AbortController();\n\n        // Iterate events directly \u2014 no SSE parsing needed\n        const events = session.trigger(msg.triggerName, msg.input);\n\n        try {\n          for await (const event of events) {\n            if (abortController.signal.aborted) break;\n            conn.write(JSON.stringify(event));\n          }\n        } catch {\n          // Handle errors\n        }\n      }\n    }\n\n    conn.on('close', () => abortController?.abort());\n  };\n}\n\nconst sockServer = sockjs.createServer({ prefix: '/octavus' });\nsockServer.on('connection', createSocketHandler());\nsockServer.installHandlers(httpServer);\n```\n\n**Benefits of this pattern:**\n- Client code is simple \u2014 no sessionId management\n- No transport caching issues\n- Session is created only when needed\n- Server controls session configuration\n\n## Client-Provided Session ID\n\nIf you need the client to control the session (e.g., resuming a specific session from URL), pass the sessionId in an init message after connecting:\n\n```typescript\nimport { useMemo } from 'react';\nimport SockJS from 'sockjs-client';\nimport { useOctavusChat, createSocketTransport, type SocketLike } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createSocketTransport({\n        connect: () =>\n          new Promise((resolve, reject) => {\n            const sock = new SockJS('/octavus');\n            sock.onopen = () => {\n              // Send init message with sessionId\n              sock.send(JSON.stringify({ type: 'init', sessionId }));\n              resolve(sock);\n            };\n            sock.onerror = () => reject(new Error('Connection failed'));\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { messages, status, send } = useOctavusChat({ transport });\n  // ... render chat\n}\n```\n\nWhen `sessionId` changes, the hook automatically reinitializes with the new transport.\n\n### Server Handler with Init Message\n\nWhen using client-provided sessionId, the server must handle an `init` message:\n\n```typescript\nsockServer.on('connection', (conn) => {\n  let session: AgentSession | null = null;\n  let abortController: AbortController | null = null;\n\n  conn.on('data', (rawData: string) => {\n    void handleMessage(rawData);\n  });\n\n  async function handleMessage(rawData: string) {\n    const msg = JSON.parse(rawData);\n\n    // Handle session initialization\n    if (msg.type === 'init') {\n      session = client.agentSessions.attach(msg.sessionId, {\n        tools: { /* ... */ },\n      });\n      return;\n    }\n\n    if (msg.type === 'stop') {\n      abortController?.abort();\n      return;\n    }\n\n    // All other messages require initialized session\n    if (!session) {\n      conn.write(JSON.stringify({\n        type: 'error',\n        errorText: 'Session not initialized. Send init message first.',\n      }));\n      return;\n    }\n\n    if (msg.type === 'trigger') {\n      // ... handle trigger (same as server-managed pattern)\n    }\n  }\n});\n```\n\n## Async Session ID\n\nWhen the session ID is fetched asynchronously (e.g., from an API), you have two options:\n\n### Option 1: Conditionally Render (Recommended)\n\nDon't render the chat component until `sessionId` is available:\n\n```tsx\nfunction ChatPage() {\n  const [sessionId, setSessionId] = useState<string | null>(null);\n\n  useEffect(() => {\n    api.createSession().then(res => setSessionId(res.sessionId));\n  }, []);\n\n  // Don't render until sessionId is ready\n  if (!sessionId) {\n    return <LoadingSpinner />;\n  }\n\n  return <Chat sessionId={sessionId} />;\n}\n```\n\nThis is the cleanest approach \u2014 the `Chat` component always receives a valid `sessionId`.\n\n### Option 2: Server-Managed Sessions\n\nUse the [server-managed sessions pattern](#server-managed-sessions-recommended) where the server creates the session lazily. The client never needs to know about `sessionId`.\n\n## Native WebSocket\n\nIf you're using native WebSocket instead of SockJS, you can pass sessionId via URL:\n\n```typescript\nconst transport = useMemo(\n  () =>\n    createSocketTransport({\n      connect: () =>\n        new Promise((resolve, reject) => {\n          const ws = new WebSocket(\n            `wss://your-server.com/octavus?sessionId=${sessionId}`\n          );\n          ws.onopen = () => resolve(ws);\n          ws.onerror = () => reject(new Error('WebSocket connection failed'));\n        }),\n    }),\n  [sessionId],\n);\n```\n\nWhen `sessionId` changes, the hook automatically reinitializes with the new transport.\n\n## Custom Events\n\nHandle custom events alongside Octavus stream events:\n\n```typescript\nconst transport = createSocketTransport({\n  connect: connectSocket,\n\n  onMessage: (data) => {\n    const msg = data as { type: string; [key: string]: unknown };\n\n    switch (msg.type) {\n      case 'typing-indicator':\n        setAgentTyping(msg.isTyping as boolean);\n        break;\n\n      case 'presence-update':\n        setOnlineUsers(msg.users as string[]);\n        break;\n\n      case 'notification':\n        showToast(msg.message as string);\n        break;\n\n      // Octavus events (text-delta, finish, etc.) are handled automatically\n    }\n  },\n});\n```\n\n## Connection Management\n\n### Handling Disconnections\n\n```typescript\nconst transport = createSocketTransport({\n  connect: connectSocket,\n\n  onClose: () => {\n    console.log('Socket disconnected');\n    setConnectionStatus('disconnected');\n  },\n});\n```\n\n### Reconnection with Exponential Backoff\n\n```typescript\nimport { useRef, useCallback, useMemo } from 'react';\nimport { createSocketTransport, type SocketLike } from '@octavus/react';\n\nfunction useReconnectingTransport() {\n  const reconnectAttempts = useRef(0);\n  const maxAttempts = 5;\n\n  const connect = useCallback((): Promise<SocketLike> => {\n    return new Promise((resolve, reject) => {\n      const sock = new SockJS('/octavus');\n\n      sock.onopen = () => {\n        reconnectAttempts.current = 0;\n        resolve(sock);\n      };\n\n      sock.onerror = () => {\n        if (reconnectAttempts.current < maxAttempts) {\n          reconnectAttempts.current++;\n          const delay = Math.min(1000 * 2 ** reconnectAttempts.current, 30000);\n          console.log(`Reconnecting in ${delay}ms...`);\n          setTimeout(() => connect().then(resolve).catch(reject), delay);\n        } else {\n          reject(new Error('Max reconnection attempts reached'));\n        }\n      };\n    });\n  }, []);\n\n  return useMemo(\n    () => createSocketTransport({ connect }),\n    [connect],\n  );\n}\n```\n\n## Framework Notes\n\n### Meteor\n\nMeteor's bundler may have issues with ES6 imports of `sockjs-client`. Use `require()` instead:\n\n```typescript\n// \u274C May fail in Meteor\nimport SockJS from 'sockjs-client';\n\n// \u2705 Works in Meteor\nconst SockJS: typeof import('sockjs-client') = require('sockjs-client');\n```\n\n### SockJS vs WebSocket\n\n| Feature | WebSocket | SockJS |\n|---------|-----------|--------|\n| Browser support | Modern browsers | All browsers (with fallbacks) |\n| Session ID | Via URL query params | Via init message |\n| Proxy compatibility | Varies | Excellent (polling fallback) |\n| Setup complexity | Lower | Higher (requires server library) |\n\n## Protocol Reference\n\n### Client \u2192 Server Messages\n\n```typescript\n// Initialize session (only for client-provided sessionId pattern)\n{ type: 'init', sessionId: string }\n\n// Trigger an action\n{ type: 'trigger', triggerName: string, input?: Record<string, unknown> }\n\n// Stop current stream\n{ type: 'stop' }\n```\n\n### Server \u2192 Client Messages\n\nThe server sends Octavus `StreamEvent` objects as JSON. See [Streaming Events](/docs/server-sdk/streaming#event-types) for the full list.\n\n```typescript\n// Examples\n{ type: 'start', messageId: '...' }\n{ type: 'text-delta', id: '...', delta: 'Hello' }\n{ type: 'tool-input-start', toolCallId: '...', toolName: 'get-user' }\n{ type: 'finish', finishReason: 'stop' }\n{ type: 'error', errorText: 'Something went wrong' }\n```\n\n## Full Example\n\nFor a complete walkthrough of building a chat interface with SockJS, see the [Socket Chat Example](/docs/examples/socket-chat).\n",
+        excerpt: "Socket Transport The socket transport enables real-time bidirectional communication using WebSocket or SockJS. Use this when you need persistent connections, custom server events, or when HTTP/SSE...",
+        order: 5
+      },
+      {
+        slug: "client-sdk/http-transport",
+        section: "client-sdk",
+        title: "HTTP Transport",
+        description: "Using HTTP/SSE for streaming with Octavus in Next.js, Express, and other frameworks.",
+        content: "\n# HTTP Transport\n\nThe HTTP transport uses standard HTTP requests with Server-Sent Events (SSE) for streaming. This is the simplest and most compatible transport option.\n\n## When to Use HTTP Transport\n\n| Use Case | Recommendation |\n|----------|----------------|\n| Next.js, Remix, or similar frameworks | \u2705 Use HTTP |\n| Standard web apps without special requirements | \u2705 Use HTTP |\n| Serverless deployments (Vercel, etc.) | \u2705 Use HTTP |\n| Need custom real-time events | Consider [Socket Transport](/docs/client-sdk/socket-transport) |\n\n## Basic Setup\n\n### Client\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { messages, status, error, send, stop } = useOctavusChat({ transport });\n\n  const sendMessage = async (text: string) => {\n    await send(\n      'user-message',\n      { USER_MESSAGE: text },\n      { userMessage: { content: text } },\n    );\n  };\n\n  // ... render chat\n}\n```\n\n### Server (Next.js API Route)\n\n```typescript\n// app/api/trigger/route.ts\nimport { OctavusClient, toSSEStream } from '@octavus/server-sdk';\n\nconst client = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n\nexport async function POST(request: Request) {\n  const { sessionId, triggerName, input } = await request.json();\n\n  const session = client.agentSessions.attach(sessionId, {\n    tools: {\n      'get-user-account': async (args) => {\n        return { name: 'Demo User', plan: 'pro' };\n      },\n    },\n  });\n\n  // trigger() returns parsed events, toSSEStream() converts to SSE format\n  const events = session.trigger(triggerName, input);\n\n  return new Response(toSSEStream(events), {\n    headers: {\n      'Content-Type': 'text/event-stream',\n      'Cache-Control': 'no-cache',\n      Connection: 'keep-alive',\n    },\n  });\n}\n```\n\n## Session Creation\n\nSessions should be created server-side before rendering the chat. There are two patterns:\n\n### Pattern 1: Create Session on Page Load\n\n```tsx\n// app/chat/page.tsx\n'use client';\n\nimport { useEffect, useState } from 'react';\nimport { Chat } from '@/components/Chat';\n\nexport default function ChatPage() {\n  const [sessionId, setSessionId] = useState<string | null>(null);\n\n  useEffect(() => {\n    fetch('/api/sessions', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({\n        agentId: 'your-agent-id',\n        input: { COMPANY_NAME: 'Acme Corp' },\n      }),\n    })\n      .then(res => res.json())\n      .then(data => setSessionId(data.sessionId));\n  }, []);\n\n  if (!sessionId) {\n    return <LoadingSpinner />;\n  }\n\n  return <Chat sessionId={sessionId} />;\n}\n```\n\n### Pattern 2: Server-Side Session Creation (App Router)\n\n```tsx\n// app/chat/page.tsx\nimport { octavus } from '@/lib/octavus';\nimport { Chat } from '@/components/Chat';\n\nexport default async function ChatPage() {\n  // Create session server-side\n  const sessionId = await octavus.agentSessions.create('your-agent-id', {\n    COMPANY_NAME: 'Acme Corp',\n  });\n\n  return <Chat sessionId={sessionId} />;\n}\n```\n\nThis pattern is cleaner as the session is ready before the component renders.\n\n## Error Handling\n\nHandle errors in both the transport and the hook:\n\n```tsx\nconst { messages, status, error, send } = useOctavusChat({\n  transport,\n  onError: (err) => {\n    console.error('Stream error:', err);\n    // Show toast, update UI, etc.\n  },\n});\n\n// Also check error state\nif (error) {\n  return <ErrorMessage error={error} />;\n}\n```\n\n## Stop Streaming\n\nAllow users to cancel ongoing streams:\n\n```tsx\nconst { send, stop, status } = useOctavusChat({ transport });\n\nreturn (\n  <button\n    onClick={status === 'streaming' ? stop : () => sendMessage()}\n    disabled={status === 'streaming' && !inputValue}\n  >\n    {status === 'streaming' ? 'Stop' : 'Send'}\n  </button>\n);\n```\n\n## Express Server\n\nFor non-Next.js backends:\n\n```typescript\nimport express from 'express';\nimport { OctavusClient, toSSEStream } from '@octavus/server-sdk';\n\nconst app = express();\nconst client = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n\napp.post('/api/trigger', async (req, res) => {\n  const { sessionId, triggerName, input } = req.body;\n\n  const session = client.agentSessions.attach(sessionId, {\n    tools: {\n      // Your tool handlers\n    },\n  });\n\n  const events = session.trigger(triggerName, input);\n  const stream = toSSEStream(events);\n\n  // Set SSE headers\n  res.setHeader('Content-Type', 'text/event-stream');\n  res.setHeader('Cache-Control', 'no-cache');\n  res.setHeader('Connection', 'keep-alive');\n\n  // Pipe the stream to the response\n  const reader = stream.getReader();\n\n  try {\n    while (true) {\n      const { done, value } = await reader.read();\n      if (done) break;\n      res.write(value);\n    }\n  } finally {\n    reader.releaseLock();\n    res.end();\n  }\n});\n```\n\n## Transport Options\n\n```typescript\ninterface HttpTransportOptions {\n  // Function that makes the HTTP request\n  triggerRequest: (\n    triggerName: string,\n    input?: Record<string, unknown>\n  ) => Promise<Response>;\n}\n```\n\n## Protocol\n\n### Request Format\n\nThe `triggerRequest` function should send a POST request with:\n\n```json\n{\n  \"sessionId\": \"sess_abc123\",\n  \"triggerName\": \"user-message\",\n  \"input\": {\n    \"USER_MESSAGE\": \"Hello\"\n  }\n}\n```\n\n### Response Format\n\nThe server responds with an SSE stream:\n\n```\ndata: {\"type\":\"start\",\"messageId\":\"msg_xyz\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"msg_xyz\",\"delta\":\"Hello\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"msg_xyz\",\"delta\":\" there!\"}\n\ndata: {\"type\":\"finish\",\"finishReason\":\"stop\"}\n\ndata: [DONE]\n```\n\nSee [Streaming Events](/docs/server-sdk/streaming#event-types) for the full list of event types.\n\n## Next Steps\n\n- [Quick Start](/docs/getting-started/quickstart) \u2014 Complete Next.js integration guide\n- [Messages](/docs/client-sdk/messages) \u2014 Working with message state\n- [Streaming](/docs/client-sdk/streaming) \u2014 Building streaming UIs\n\n",
+        excerpt: "HTTP Transport The HTTP transport uses standard HTTP requests with Server-Sent Events (SSE) for streaming. This is the simplest and most compatible transport option.  When to Use HTTP Transport | Use...",
+        order: 6
+      }
+    ]
+  },
+  {
+    slug: "protocol",
+    title: "Protocol",
+    description: "Agent protocol reference - how to define agent behavior with YAML.",
+    order: 4,
+    docs: [
+      {
+        slug: "protocol/overview",
+        section: "protocol",
+        title: "Overview",
+        description: "Introduction to Octavus agent protocols.",
+        content: '\n# Protocol Overview\n\nAgent protocols define how an AI agent behaves. They\'re written in YAML and specify inputs, triggers, tools, and execution handlers.\n\n## Why Protocols?\n\nProtocols provide:\n\n- **Declarative definition** \u2014 Define behavior, not implementation\n- **Portable agents** \u2014 Move agents between projects\n- **Versioning** \u2014 Track changes with git\n- **Validation** \u2014 Catch errors before runtime\n- **Visualization** \u2014 Debug execution flows\n\n## Protocol Structure\n\n```yaml\n# Agent inputs (provided when creating a session)\ninput:\n  COMPANY_NAME: { type: string }\n  USER_ID: { type: string, optional: true }\n\n# Persistent resources the agent can read/write\nresources:\n  CONVERSATION_SUMMARY:\n    description: Summary for handoff\n    default: ""\n\n# How the agent can be invoked\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n  request-human:\n    description: User clicks "Talk to Human"\n\n# Temporary variables for execution (with types)\nvariables:\n  SUMMARY:\n    type: string\n  TICKET:\n    type: unknown\n\n# Tools the agent can use\ntools:\n  get-user-account:\n    description: Looking up your account\n    parameters:\n      userId: { type: string }\n\n# Agent configuration (model, tools, etc.)\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system            # References prompts/system.md\n  tools: [get-user-account]\n  agentic: true             # Allow multiple tool calls\n  thinking: medium          # Extended reasoning\n\n# What happens when triggers fire\nhandlers:\n  user-message:\n    Add user message:\n      type: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n    \n    Respond to user:\n      type: next-message\n```\n\n## File Structure\n\nEach agent is a folder with:\n\n```\nmy-agent/\n\u251C\u2500\u2500 protocol.yaml           # Main logic (required)\n\u251C\u2500\u2500 settings.json           # Agent metadata (required)\n\u2514\u2500\u2500 prompts/               # Prompt templates\n    \u251C\u2500\u2500 system.md\n    \u251C\u2500\u2500 user-message.md\n    \u2514\u2500\u2500 escalation-summary.md\n```\n\n### settings.json\n\n```json\n{\n  "slug": "my-agent",\n  "name": "My Agent",\n  "description": "What this agent does",\n  "format": "interactive"\n}\n```\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `slug` | Yes | URL-safe identifier (lowercase, digits, dashes) |\n| `name` | Yes | Human-readable name |\n| `description` | No | Brief description |\n| `format` | Yes | `interactive` (chat) or `generation` (background) |\n\n## Naming Conventions\n\n- **Slugs**: `lowercase-with-dashes`\n- **Variables**: `UPPERCASE_SNAKE_CASE`\n- **Prompts**: `lowercase-with-dashes.md`\n- **Tools**: `lowercase-with-dashes`\n- **Triggers**: `lowercase-with-dashes`\n\n## Variables in Prompts\n\nReference variables with `{{VARIABLE_NAME}}`:\n\n```markdown\n<!-- prompts/system.md -->\nYou are a support agent for {{COMPANY_NAME}}.\n\nHelp users with their {{PRODUCT_NAME}} questions.\n\n## Support Policies\n\n{{SUPPORT_POLICIES}}\n```\n\nVariables are replaced with their values at runtime. If a variable is not provided, it\'s replaced with an empty string.\n\n## Next Steps\n\n- [Input & Resources](/docs/protocol/input-resources) \u2014 Defining agent inputs\n- [Triggers](/docs/protocol/triggers) \u2014 How agents are invoked\n- [Tools](/docs/protocol/tools) \u2014 External capabilities\n- [Handlers](/docs/protocol/handlers) \u2014 Execution blocks\n- [Agent Config](/docs/protocol/agent-config) \u2014 Model and settings\n\n',
+        excerpt: "Protocol Overview Agent protocols define how an AI agent behaves. They're written in YAML and specify inputs, triggers, tools, and execution handlers.  Why Protocols? Protocols provide: - Declarative...",
+        order: 1
+      },
+      {
+        slug: "protocol/input-resources",
+        section: "protocol",
+        title: "Input & Resources",
+        description: "Defining agent inputs and persistent resources.",
+        content: "\n# Input & Resources\n\nInputs are provided when creating a session. Resources are persistent state the agent can read and write.\n\n## Input Variables\n\nDefine inputs that consumers must (or may) provide:\n\n```yaml\ninput:\n  # Required input\n  COMPANY_NAME:\n    type: string\n    description: The company name to use in responses\n\n  # Required input with description\n  PRODUCT_NAME:\n    type: string\n    description: Product being supported\n\n  # Optional input (defaults to \"NONE\")\n  SUPPORT_POLICIES:\n    type: string\n    description: Company policies for support\n    optional: true\n\n  # Optional input with custom default\n  USER_ID:\n    type: string\n    description: Current user's ID\n    optional: true\n    default: \"\"\n```\n\n### Input Definition\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |\n| `description` | No | Describes what this input is for |\n| `optional` | No | If true, consumer doesn't have to provide it |\n| `default` | No | Default value if not provided (defaults to `\"NONE\"`) |\n\n### Using Inputs\n\nWhen creating a session, pass input values:\n\n```typescript\nconst sessionId = await client.agentSessions.create('support-chat', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n  SUPPORT_POLICIES: 'Refunds within 30 days...',\n  // USER_ID is optional, not provided\n});\n```\n\nIn prompts, reference with `{{INPUT_NAME}}`:\n\n```markdown\nYou are a support agent for {{COMPANY_NAME}}.\n```\n\n> **Note:** Variables must be `UPPER_SNAKE_CASE`. Nested properties (dot notation like `{{VAR.property}}`) are not supported. Objects are serialized as JSON when interpolated.\n\n## Resources\n\nResources are persistent state that:\n- Survive across triggers\n- Can be read and written by the agent\n- Are synced to the consumer's application\n\n```yaml\nresources:\n  # String resource with default\n  CONVERSATION_SUMMARY:\n    type: string\n    description: Running summary of the conversation\n    default: \"\"\n\n  # Resource with unknown type (for complex data)\n  USER_CONTEXT:\n    type: unknown\n    description: Cached user information\n    default: {}\n\n  # Read-only resource (agent can read but not write)\n  SYSTEM_CONFIG:\n    type: unknown\n    description: System configuration\n    readonly: true\n    default:\n      maxRetries: 3\n      timeout: 30000\n```\n\n### Resource Definition\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |\n| `description` | No | Describes the resource purpose |\n| `default` | No | Initial value |\n| `readonly` | No | If true, agent cannot write to it |\n\n### Writing Resources\n\nUse the `set-resource` block in handlers:\n\n```yaml\nhandlers:\n  request-human:\n    # ... generate summary ...\n    \n    Save summary:\n      type: set-resource\n      resource: CONVERSATION_SUMMARY\n      value: SUMMARY  # Variable containing the value\n```\n\n### Resource Events\n\nWhen a resource is updated, the client SDK receives a `resource-update` event:\n\n```typescript\nuseOctavusChat({\n  onResourceUpdate: (name, value) => {\n    if (name === 'CONVERSATION_SUMMARY') {\n      console.log('Summary updated:', value);\n    }\n  },\n});\n```\n\n## Variables\n\nVariables are internal state managed by block outputs. They persist across triggers but are not synced to the consumer (unlike resources).\n\n```yaml\nvariables:\n  SUMMARY:\n    type: string\n    description: Generated summary text\n  TICKET:\n    type: unknown\n    description: Ticket creation result\n  CONVERSATION_TEXT:\n    type: string\n    description: Serialized conversation\n```\n\n### Variable Definition\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |\n| `description` | No | Describes what this variable stores |\n| `default` | No | Initial value |\n\n### Using Variables\n\nSet variables as output from blocks:\n\n```yaml\nhandlers:\n  request-human:\n    Serialize conversation:\n      type: serialize-thread\n      format: markdown\n      output: CONVERSATION_TEXT  # Stores result in variable\n    \n    Generate summary:\n      type: next-message\n      output: SUMMARY  # LLM output stored in variable\n    \n    Create ticket:\n      type: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY  # Use variable as input\n      output: TICKET\n```\n\n## Scoping\n\n| Type | Scope | Persistence | Synced to Consumer |\n|------|-------|-------------|---------------------|\n| `input` | Session | Immutable | Yes (at creation) |\n| `resources` | Session | Persists across triggers | Yes (via callbacks) |\n| `variables` | Session | Persists across triggers | No (internal only) |\n\n",
+        excerpt: "Input & Resources Inputs are provided when creating a session. Resources are persistent state the agent can read and write.  Input Variables Define inputs that consumers must (or may) provide:  Input...",
+        order: 2
+      },
+      {
+        slug: "protocol/triggers",
+        section: "protocol",
+        title: "Triggers",
+        description: "Defining how agents are invoked.",
+        content: "\n# Triggers\n\nTriggers define how an agent can be invoked. Each trigger has a name, optional inputs, and a corresponding handler.\n\n## Trigger Types\n\n### User Message\n\nThe most common trigger \u2014 when a user sends a chat message:\n\n```yaml\ntriggers:\n  user-message:\n    description: User sends a chat message\n    input:\n      USER_MESSAGE:\n        type: string\n        description: The user's message\n```\n\n### User Action\n\nFor UI interactions like button clicks:\n\n```yaml\ntriggers:\n  request-human:\n    description: User clicks \"Talk to Human\" button\n    # No input needed - action is implicit\n\n  submit-feedback:\n    description: User submits feedback form\n    input:\n      RATING:\n        type: number\n        description: Rating from 1-5\n      COMMENT:\n        type: string\n        description: Optional comment\n        optional: true\n```\n\n### API Trigger\n\nDirect invocation through the SDK:\n\n```yaml\ntriggers:\n  analyze-document:\n    description: Analyze an uploaded document\n    input:\n      DOCUMENT_URL:\n        type: string\n      ANALYSIS_TYPE:\n        type: string\n        description: Type of analysis (summary, sentiment, extraction)\n```\n\n## Trigger Definition\n\n```yaml\ntriggers:\n  trigger-name:\n    description: Optional description\n    input:\n      VARIABLE_NAME:\n        type: string | number | boolean | unknown\n        description: What this input is for\n        optional: true | false  # defaults to false\n        default: value  # default if optional and not provided\n```\n\n## Invoking Triggers\n\n### From Client SDK\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { send } = useOctavusChat({ transport });\n\n  // User message trigger with UI message\n  await send(\n    'user-message',\n    { USER_MESSAGE: text },\n    { userMessage: { content: text } },\n  );\n\n  // User action trigger (no input, no UI message)\n  await send('request-human');\n\n  // Action with input\n  await send('submit-feedback', { RATING: 5, COMMENT: 'Great help!' });\n}\n```\n\n### From Server SDK\n\n```typescript\n// trigger() returns an async generator of events\nconst events = session.trigger('user-message', {\n  USER_MESSAGE: 'Help me with billing',\n});\n\n// Iterate events directly\nfor await (const event of events) {\n  console.log(event);\n}\n\n// Or convert to SSE for HTTP responses\nimport { toSSEStream } from '@octavus/server-sdk';\nreturn new Response(toSSEStream(events), { headers: { 'Content-Type': 'text/event-stream' } });\n```\n\n## Handlers\n\nEach trigger must have a corresponding handler:\n\n```yaml\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n\n  request-human:\n    description: Escalate to human support\n\nhandlers:\n  user-message:\n    # Blocks executed when user-message is triggered\n    Add user message:\n      type: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n\n    Respond:\n      type: next-message\n\n  request-human:\n    # Blocks executed when request-human is triggered\n    Summarize:\n      type: serialize-thread\n      # ...\n```\n\n## Trigger Input Naming\n\nTrigger inputs use `UPPERCASE_SNAKE_CASE`:\n\n```yaml\ntriggers:\n  search-products:\n    input:\n      SEARCH_QUERY: { type: string }\n      MAX_RESULTS: { type: number, optional: true, default: 10 }\n      FILTER_CATEGORY: { type: string, optional: true }\n```\n\n## Best Practices\n\n### 1. Use Descriptive Names\n\n```yaml\n# Good\ntriggers:\n  user-message:       # Clear - user sends chat message\n  request-human:      # Clear - wants human support\n  cancel-subscription: # Clear - specific action\n\n# Avoid\ntriggers:\n  trigger1:           # Unclear\n  msg:                # Too abbreviated\n  do-thing:           # Vague\n```\n\n### 2. Document Triggers\n\n```yaml\ntriggers:\n  escalate-to-tier2:\n    description: >\n      Escalate the conversation to tier 2 support.\n      Should be called when the issue cannot be resolved\n      at tier 1 level.\n    input:\n      REASON:\n        type: string\n        description: Why escalation is needed\n```\n\n### 3. Keep Triggers Focused\n\nEach trigger should do one thing:\n\n```yaml\n# Good - focused triggers\ntriggers:\n  send-message:\n    input: { MESSAGE: { type: string } }\n\n  upload-file:\n    input: { FILE_URL: { type: string } }\n\n  request-callback:\n    input: { PHONE: { type: string } }\n\n# Avoid - overloaded trigger\ntriggers:\n  user-action:\n    input:\n      ACTION_TYPE: { type: string }  # \"message\" | \"file\" | \"callback\"\n      PAYLOAD: { type: unknown }     # Different structure per type\n```\n",
+        excerpt: "Triggers Triggers define how an agent can be invoked. Each trigger has a name, optional inputs, and a corresponding handler.  Trigger Types  User Message The most common trigger \u2014 when a user sends a...",
+        order: 3
+      },
+      {
+        slug: "protocol/tools",
+        section: "protocol",
+        title: "Tools",
+        description: "Defining external tools agents can use.",
+        content: "\n# Tools\n\nTools extend what agents can do. They're defined in the protocol and implemented in your backend.\n\n## Tool Definition\n\n```yaml\ntools:\n  get-user-account:\n    description: Looking up your account information\n    display: description\n    parameters:\n      userId:\n        type: string\n        description: The user ID to look up\n```\n\n### Tool Fields\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `description` | Yes | What the tool does (shown to LLM and optionally user) |\n| `display` | No | How to show in UI: `hidden`, `name`, `description`, `stream` |\n| `parameters` | No | Input parameters the tool accepts |\n\n### Display Modes\n\n| Mode | Behavior |\n|------|----------|\n| `hidden` | Tool runs silently, user doesn't see it |\n| `name` | Shows tool name while executing |\n| `description` | Shows description while executing (default) |\n| `stream` | Streams tool progress if available |\n\n## Parameters\n\n### Parameter Fields\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |\n| `description` | No | Describes what this parameter is for |\n| `optional` | No | If true, parameter is not required (default: false) |\n\n### Optional Parameters\n\nParameters are **required by default**. Use `optional: true` to make a parameter optional:\n\n```yaml\ntools:\n  search-products:\n    description: Search the product catalog\n    parameters:\n      query:\n        type: string\n        description: Search query\n\n      category:\n        type: string\n        description: Filter by category\n        optional: true\n\n      maxPrice:\n        type: number\n        description: Maximum price filter\n        optional: true\n\n      inStock:\n        type: boolean\n        description: Only show in-stock items\n        optional: true\n```\n\n## Making Tools Available\n\nTools defined in `tools:` are available. To make them usable by the LLM, add them to `agent.tools`:\n\n```yaml\ntools:\n  get-user-account:\n    description: Look up user account\n    parameters:\n      userId: { type: string }\n\n  create-support-ticket:\n    description: Create a support ticket\n    parameters:\n      summary: { type: string }\n      priority: { type: string }  # low, medium, high, urgent\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  tools:\n    - get-user-account\n    - create-support-ticket  # LLM can decide when to call these\n  agentic: true\n```\n\n## Tool Invocation Modes\n\n### LLM-Decided (Agentic)\n\nThe LLM decides when to call tools based on the conversation:\n\n```yaml\nagent:\n  tools: [get-user-account, create-support-ticket]\n  agentic: true  # Allow multiple tool calls\n  maxSteps: 10   # Max tool call cycles\n```\n\n### Deterministic (Block-Based)\n\nForce tool calls at specific points in the handler:\n\n```yaml\nhandlers:\n  request-human:\n    # Always create a ticket when escalating\n    Create support ticket:\n      type: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY  # From variable\n        priority: medium  # Literal value\n      output: TICKET      # Store result\n```\n\n## Tool Results\n\n### In Prompts\n\nTool results are stored in variables. Reference the variable in prompts:\n\n```markdown\n<!-- prompts/ticket-directive.md -->\nA support ticket has been created:\n{{TICKET}}\n\nLet the user know their ticket has been created.\n```\n\nWhen the `TICKET` variable contains an object, it's automatically serialized as JSON in the prompt:\n\n```\nA support ticket has been created:\n{\n  \"ticketId\": \"TKT-123ABC\",\n  \"estimatedResponse\": \"24 hours\"\n}\n\nLet the user know their ticket has been created.\n```\n\n> **Note**: Variables use `{{VARIABLE_NAME}}` syntax with `UPPERCASE_SNAKE_CASE`. Dot notation (like `{{TICKET.ticketId}}`) is not supported. Objects are automatically JSON-serialized.\n\n### In Variables\n\nStore tool results for later use:\n\n```yaml\nhandlers:\n  request-human:\n    Get account:\n      type: tool-call\n      tool: get-user-account\n      input:\n        userId: USER_ID\n      output: ACCOUNT  # Result stored here\n\n    Create ticket:\n      type: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY\n        priority: medium\n      output: TICKET\n```\n\n## Implementing Tools\n\nTools are implemented in your backend:\n\n```typescript\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    'get-user-account': async (args) => {\n      const userId = args.userId as string;\n      const user = await db.users.findById(userId);\n\n      return {\n        name: user.name,\n        email: user.email,\n        plan: user.subscription.plan,\n        createdAt: user.createdAt.toISOString(),\n      };\n    },\n\n    'create-support-ticket': async (args) => {\n      const ticket = await ticketService.create({\n        summary: args.summary as string,\n        priority: args.priority as string,\n      });\n\n      return {\n        ticketId: ticket.id,\n        estimatedResponse: getEstimatedTime(args.priority),\n      };\n    },\n  },\n});\n```\n\n## Tool Best Practices\n\n### 1. Clear Descriptions\n\n```yaml\ntools:\n  # Good - clear and specific\n  get-user-account:\n    description: >\n      Retrieves the user's account information including name, email,\n      subscription plan, and account creation date. Use this when the\n      user asks about their account or you need to verify their identity.\n\n  # Avoid - vague\n  get-data:\n    description: Gets some data\n```\n\n### 2. Document Constrained Values\n\n```yaml\ntools:\n  create-support-ticket:\n    parameters:\n      priority:\n        type: string\n        description: Ticket priority level (low, medium, high, urgent)\n```\n",
+        excerpt: "Tools Tools extend what agents can do. They're defined in the protocol and implemented in your backend.  Tool Definition  Tool Fields | Field | Required | Description |...",
+        order: 4
+      },
+      {
+        slug: "protocol/handlers",
+        section: "protocol",
+        title: "Handlers",
+        description: "Defining execution handlers with blocks.",
+        content: "\n# Handlers\n\nHandlers define what happens when a trigger fires. They contain execution blocks that run in sequence.\n\n## Handler Structure\n\n```yaml\nhandlers:\n  trigger-name:\n    Block Name:\n      type: block-type\n      # block-specific properties\n    \n    Another Block:\n      type: another-type\n      # ...\n```\n\nEach block has a human-readable name (shown in debug UI) and a type that determines its behavior.\n\n## Block Types\n\n### next-message\n\nGenerate a response from the LLM:\n\n```yaml\nhandlers:\n  user-message:\n    Respond to user:\n      type: next-message\n      # Uses main conversation thread by default\n      # Display defaults to 'stream'\n```\n\nWith options:\n\n```yaml\nGenerate summary:\n  type: next-message\n  thread: summary           # Use named thread\n  display: stream           # Show streaming content\n  independent: true         # Don't add to main chat\n  output: SUMMARY           # Store output in variable\n  description: Generating summary  # Shown in UI\n```\n\n### add-message\n\nAdd a message to the conversation:\n\n```yaml\nAdd user message:\n  type: add-message\n  role: user                # user | assistant | system\n  prompt: user-message      # Reference to prompt file\n  input: [USER_MESSAGE]     # Variables to interpolate\n  display: hidden           # Don't show in UI\n```\n\nFor internal directives (LLM sees it, user doesn't):\n\n```yaml\nAdd internal directive:\n  type: add-message\n  role: user\n  prompt: ticket-directive\n  input: [TICKET_DETAILS]\n  visible: false            # LLM sees this, user doesn't\n```\n\n### tool-call\n\nCall a tool deterministically:\n\n```yaml\nCreate ticket:\n  type: tool-call\n  tool: create-support-ticket\n  input:\n    summary: SUMMARY        # Variable reference\n    priority: medium        # Literal value\n  output: TICKET           # Store result\n```\n\n### set-resource\n\nUpdate a persistent resource:\n\n```yaml\nSave summary:\n  type: set-resource\n  resource: CONVERSATION_SUMMARY\n  value: SUMMARY            # Variable to save\n  display: name             # Show block name\n```\n\n### start-thread\n\nCreate a named conversation thread:\n\n```yaml\nStart summary thread:\n  type: start-thread\n  thread: summary                    # Thread name\n  model: anthropic/claude-sonnet-4-5 # Optional: different model\n  thinking: low                      # Extended reasoning level\n  maxSteps: 1                        # Tool call limit\n  system: escalation-summary         # System prompt\n  input: [COMPANY_NAME]              # Variables for prompt\n```\n\n### serialize-thread\n\nConvert conversation to text:\n\n```yaml\nSerialize conversation:\n  type: serialize-thread\n  thread: main              # Which thread (default: main)\n  format: markdown          # markdown | json\n  output: CONVERSATION_TEXT # Variable to store result\n```\n\n## Display Modes\n\nEvery block has a `display` property:\n\n| Mode | Default For | Behavior |\n|------|-------------|----------|\n| `hidden` | add-message | Not shown to user |\n| `name` | set-resource | Shows block name |\n| `description` | tool-call | Shows description |\n| `stream` | next-message | Streams content |\n\n## Complete Example\n\n```yaml\nhandlers:\n  user-message:\n    # Add the user's message to conversation\n    Add user message:\n      type: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n      display: hidden\n    \n    # Generate response (LLM may call tools)\n    Respond to user:\n      type: next-message\n      # display: stream (default)\n\n  request-human:\n    # Step 1: Serialize conversation for summary\n    Serialize conversation:\n      type: serialize-thread\n      format: markdown\n      output: CONVERSATION_TEXT\n    \n    # Step 2: Create separate thread for summarization\n    Start summary thread:\n      type: start-thread\n      thread: summary\n      model: anthropic/claude-sonnet-4-5\n      thinking: low\n      system: escalation-summary\n      input: [COMPANY_NAME]\n    \n    # Step 3: Add request to summary thread\n    Add summarize request:\n      type: add-message\n      thread: summary\n      role: user\n      prompt: summarize-request\n      input:\n        - CONVERSATION: CONVERSATION_TEXT\n    \n    # Step 4: Generate summary\n    Generate summary:\n      type: next-message\n      thread: summary\n      display: stream\n      description: Summarizing your conversation\n      independent: true\n      output: SUMMARY\n    \n    # Step 5: Save to resource\n    Save summary:\n      type: set-resource\n      resource: CONVERSATION_SUMMARY\n      value: SUMMARY\n    \n    # Step 6: Create support ticket\n    Create ticket:\n      type: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY\n        priority: medium\n      output: TICKET\n    \n    # Step 7: Add directive for response\n    Add directive:\n      type: add-message\n      role: user\n      prompt: ticket-directive\n      input: [TICKET_DETAILS: TICKET]\n      visible: false\n    \n    # Step 8: Respond to user\n    Respond:\n      type: next-message\n```\n\n## Block Input Mapping\n\nMap variables to block inputs:\n\n```yaml\n# Simple list (variable name = prompt variable)\ninput: [USER_MESSAGE, COMPANY_NAME]\n\n# Mapping (different names)\ninput:\n  - CONVERSATION: CONVERSATION_TEXT  # CONVERSATION in prompt = CONVERSATION_TEXT\n  - TICKET_DETAILS: TICKET\n```\n\n## Independent Blocks\n\nUse `independent: true` for content that shouldn't go to the main chat:\n\n```yaml\nGenerate summary:\n  type: next-message\n  thread: summary\n  independent: true   # Output stored in variable, not main chat\n  output: SUMMARY\n```\n\nThis is useful for:\n- Background processing\n- Summarization in separate threads\n- Generating content for tools\n\n",
+        excerpt: "Handlers Handlers define what happens when a trigger fires. They contain execution blocks that run in sequence.  Handler Structure Each block has a human-readable name (shown in debug UI) and a type...",
+        order: 5
+      },
+      {
+        slug: "protocol/agent-config",
+        section: "protocol",
+        title: "Agent Config",
+        description: "Configuring the agent model and behavior.",
+        content: "\n# Agent Config\n\nThe `agent` section configures the LLM model, system prompt, tools, and behavior.\n\n## Basic Configuration\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system              # References prompts/system.md\n  tools: [get-user-account]   # Available tools\n```\n\n## Configuration Options\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `model` | Yes | Model identifier (provider/model-id) |\n| `system` | Yes | System prompt filename (without .md) |\n| `input` | No | Variables to interpolate in system prompt |\n| `tools` | No | List of tools the LLM can call |\n| `agentic` | No | Allow multiple tool call cycles |\n| `maxSteps` | No | Maximum agentic steps (default: 10) |\n| `temperature` | No | Model temperature (0-2) |\n| `thinking` | No | Extended reasoning level |\n\n## Models\n\nSpecify models in `provider/model-id` format:\n\n```yaml\n# Anthropic\nagent:\n  model: anthropic/claude-sonnet-4-5   # Claude 4.5 Sonnet\n  model: anthropic/claude-opus-4       # Claude 4 Opus\n\n# OpenAI\nagent:\n  model: openai/gpt-4o                 # GPT-4o\n  model: openai/gpt-4o-mini            # GPT-4o Mini\n  model: openai/o1                     # O1\n  model: openai/o3-mini                # O3 Mini\n```\n\n## System Prompt\n\nThe system prompt sets the agent's persona and instructions:\n\n```yaml\nagent:\n  system: system  # Uses prompts/system.md\n  input:\n    - COMPANY_NAME\n    - PRODUCT_NAME\n```\n\nExample `prompts/system.md`:\n\n```markdown\nYou are a friendly support agent for {{COMPANY_NAME}}.\n\n## Your Role\n\nHelp users with questions about {{PRODUCT_NAME}}.\n\n## Guidelines\n\n- Be helpful and professional\n- If you can't help, offer to escalate\n- Never share internal information\n```\n\n## Agentic Mode\n\nEnable multi-step tool calling:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  tools: [get-user-account, search-docs, create-ticket]\n  agentic: true    # LLM can call multiple tools\n  maxSteps: 10     # Limit cycles to prevent runaway\n```\n\n**How it works:**\n1. LLM receives user message\n2. LLM decides to call a tool\n3. Tool executes, result returned to LLM\n4. LLM decides if more tools needed\n5. Repeat until LLM responds or maxSteps reached\n\n## Extended Thinking\n\nEnable extended reasoning for complex tasks:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  thinking: medium  # low | medium | high\n```\n\n| Level | Token Budget | Use Case |\n|-------|-------------|----------|\n| `low` | ~5,000 | Simple reasoning |\n| `medium` | ~10,000 | Moderate complexity |\n| `high` | ~20,000 | Complex analysis |\n\nThinking content streams to the UI and can be displayed to users.\n\n## Temperature\n\nControl response randomness:\n\n```yaml\nagent:\n  model: openai/gpt-4o\n  temperature: 0.7  # 0 = deterministic, 2 = creative\n```\n\n**Guidelines:**\n- `0 - 0.3`: Factual, consistent responses\n- `0.4 - 0.7`: Balanced (good default)\n- `0.8 - 1.2`: Creative, varied responses\n- `> 1.2`: Very creative (may be inconsistent)\n\n## Thread-Specific Config\n\nOverride config for named threads:\n\n```yaml\nhandlers:\n  request-human:\n    Start summary thread:\n      type: start-thread\n      thread: summary\n      model: anthropic/claude-sonnet-4-5  # Different model\n      thinking: low                        # Different thinking\n      maxSteps: 1                          # Limit tool calls\n      system: escalation-summary           # Different prompt\n```\n\n## Full Example\n\n```yaml\ninput:\n  COMPANY_NAME: { type: string }\n  PRODUCT_NAME: { type: string }\n  USER_ID: { type: string, optional: true }\n\nresources:\n  CONVERSATION_SUMMARY:\n    type: string\n    default: \"\"\n\ntools:\n  get-user-account:\n    description: Look up user account\n    parameters:\n      userId: { type: string }\n  \n  search-docs:\n    description: Search help documentation\n    parameters:\n      query: { type: string }\n  \n  create-support-ticket:\n    description: Create a support ticket\n    parameters:\n      summary: { type: string }\n      priority: { type: string }  # low, medium, high\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  input:\n    - COMPANY_NAME\n    - PRODUCT_NAME\n  tools:\n    - get-user-account\n    - search-docs\n    - create-support-ticket\n  agentic: true\n  maxSteps: 10\n  thinking: medium\n\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n\nhandlers:\n  user-message:\n    Add message:\n      type: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n      display: hidden\n    \n    Respond:\n      type: next-message\n```\n\n",
+        excerpt: "Agent Config The  section configures the LLM model, system prompt, tools, and behavior.  Basic Configuration  Configuration Options | Field | Required | Description |...",
+        order: 6
+      }
+    ]
+  },
+  {
+    slug: "api-reference",
+    title: "API Reference",
+    description: "REST API reference for the Octavus platform.",
+    order: 5,
+    docs: [
+      {
+        slug: "api-reference/overview",
+        section: "api-reference",
+        title: "Overview",
+        description: "REST API overview and authentication.",
+        content: '\n# API Reference\n\nThe Octavus API is a RESTful API that enables programmatic access to agent management and session execution.\n\n## Base URL\n\n```\nhttps://octavus.ai\n```\n\n## Authentication\n\nAll API requests require authentication using a Bearer token:\n\n```bash\ncurl -H "Authorization: Bearer YOUR_API_KEY" \\\n  https://octavus.ai/api/agents\n```\n\nAPI keys can be created in the Octavus Platform under your project\'s **API Keys** page.\n\n## Response Format\n\nAll responses are JSON. Success responses return the data directly (not wrapped in a `data` field).\n\n### Success Response\n\n```json\n{\n  "sessionId": "sess_abc123"\n}\n```\n\n### Error Response\n\n```json\n{\n  "error": {\n    "code": "NOT_FOUND",\n    "message": "Agent not found"\n  }\n}\n```\n\n## HTTP Status Codes\n\n| Code | Description |\n|------|-------------|\n| 200 | Success |\n| 201 | Created |\n| 400 | Bad Request - Invalid parameters |\n| 401 | Unauthorized - Missing or invalid API key |\n| 403 | Forbidden - Insufficient permissions |\n| 404 | Not Found |\n| 500 | Internal Server Error |\n\n## Endpoints Overview\n\n### Agents\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/agents` | List all agents |\n| GET | `/api/agents/:id` | Get agent by ID |\n| POST | `/api/agents` | Create agent |\n| PATCH | `/api/agents/:id` | Update agent |\n\n### Sessions\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/api/agent-sessions` | Create session |\n| GET | `/api/agent-sessions/:id` | Get session state |\n| POST | `/api/agent-sessions/:id/trigger` | Execute trigger (SSE) |\n\n## Streaming\n\nThe trigger endpoint returns Server-Sent Events (SSE):\n\n```bash\ncurl -N -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{"triggerName": "user-message", "input": {"USER_MESSAGE": "Hello"}}\' \\\n  https://octavus.ai/api/agent-sessions/SESSION_ID/trigger\n```\n\nResponse format:\n\n```\ndata: {"type":"start","messageId":"..."}\n\ndata: {"type":"block-start","blockId":"...","blockName":"Respond","blockType":"next-message","display":"stream"}\n\ndata: {"type":"text-start","id":"..."}\n\ndata: {"type":"text-delta","id":"...","delta":"Hello"}\n\ndata: {"type":"text-delta","id":"...","delta":"!"}\n\ndata: {"type":"text-end","id":"..."}\n\ndata: {"type":"block-end","blockId":"..."}\n\ndata: {"type":"finish","finishReason":"stop"}\n\ndata: [DONE]\n```\n\n## SDKs\n\nWe recommend using our SDKs instead of calling the API directly:\n\n- **Server SDK**: `@octavus/server-sdk` - For Node.js backends\n- **React SDK**: `@octavus/react` - For React applications\n- **Client SDK**: `@octavus/client-sdk` - For other frontend frameworks\n\nThe SDKs handle authentication, streaming, and tool execution automatically.\n\n',
+        excerpt: "API Reference The Octavus API is a RESTful API that enables programmatic access to agent management and session execution.  Base URL  Authentication All API requests require authentication using a...",
+        order: 1
+      },
+      {
+        slug: "api-reference/sessions",
+        section: "api-reference",
+        title: "Sessions",
+        description: "Session management API endpoints.",
+        content: '\n# Sessions API\n\nSessions represent conversations with agents. They store conversation history, resources, and variables.\n\n## Create Session\n\nCreate a new agent session.\n\n```\nPOST /api/agent-sessions\n```\n\n### Request Body\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "input": {\n    "COMPANY_NAME": "Acme Corp",\n    "PRODUCT_NAME": "Widget Pro",\n    "USER_ID": "user-123"\n  }\n}\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `agentId` | string | Yes | Agent ID (the `id` field, not `slug`) |\n| `input` | object | No | Input variables for the agent |\n\n> To get the agent ID, copy it from the platform URL, use [Get Agent by slug](/docs/api-reference/agents#get-agent) (`GET /api/agents/:slug?by=slug`), or the SDK\'s `agents.getBySlug()` method.\n\n### Response\n\n```json\n{\n  "sessionId": "cm5xyz123abc456def"\n}\n```\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agent-sessions \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "agentId": "cm5xvz7k80001abcd",\n    "input": {\n      "COMPANY_NAME": "Acme Corp",\n      "PRODUCT_NAME": "Widget Pro"\n    }\n  }\'\n```\n\n## Get Session\n\nRetrieve session state including UI-ready messages and resources.\n\n```\nGET /api/agent-sessions/:sessionId\n```\n\n### Response\n\nThe response includes `UIMessage` objects that can be passed directly to the client SDK\'s `initialMessages` option:\n\n```json\n{\n  "id": "cm5xyz123abc456def",\n  "agentId": "cm5xvz7k80001abcd",\n  "input": {\n    "COMPANY_NAME": "Acme Corp",\n    "PRODUCT_NAME": "Widget Pro"\n  },\n  "variables": {},\n  "resources": {\n    "CONVERSATION_SUMMARY": ""\n  },\n  "messages": [\n    {\n      "id": "1702345800000-xyz789a",\n      "role": "user",\n      "parts": [\n        { "type": "text", "text": "How do I reset my password?", "status": "done" }\n      ],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:00.000Z"\n    },\n    {\n      "id": "1702345805000-def456b",\n      "role": "assistant",\n      "parts": [\n        { "type": "text", "text": "I can help you reset your password...", "status": "done" }\n      ],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:05.000Z"\n    }\n  ],\n  "createdAt": "2024-01-15T10:30:00Z",\n  "updatedAt": "2024-01-15T10:30:05Z"\n}\n```\n\n### UIMessage Parts\n\nMessages contain typed `parts` that preserve content ordering:\n\n| Part Type | Description |\n|-----------|-------------|\n| `text` | Text content with `text` and `status` fields |\n| `reasoning` | Extended reasoning with `text` and `status` fields |\n| `tool-call` | Tool execution with `toolCallId`, `toolName`, `displayName`, `args`, `result`, `status` |\n| `operation` | Internal operations with `operationId`, `name`, `operationType`, `status` |\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agent-sessions/:sessionId \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n```\n\n## Trigger Session\n\nExecute a trigger on a session. Returns a Server-Sent Events stream.\n\n```\nPOST /api/agent-sessions/:sessionId/trigger\n```\n\n### Request Body\n\n```json\n{\n  "triggerName": "user-message",\n  "input": {\n    "USER_MESSAGE": "How do I reset my password?"\n  },\n  "toolResults": []\n}\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `triggerName` | string | Yes | Name of the trigger to execute |\n| `input` | object | No | Input variables for the trigger |\n| `toolResults` | array | No | Tool results for continuation (handled by SDK) |\n\n### Response\n\nReturns `text/event-stream` with SSE events:\n\n```\ndata: {"type":"start","messageId":"msg-123"}\n\ndata: {"type":"block-start","blockId":"b1","blockName":"Add user message","blockType":"add-message","display":"hidden"}\n\ndata: {"type":"block-end","blockId":"b1"}\n\ndata: {"type":"block-start","blockId":"b2","blockName":"Respond to user","blockType":"next-message","display":"stream","outputToChat":true}\n\ndata: {"type":"text-start","id":"t1"}\n\ndata: {"type":"text-delta","id":"t1","delta":"I"}\n\ndata: {"type":"text-delta","id":"t1","delta":" can"}\n\ndata: {"type":"text-delta","id":"t1","delta":" help"}\n\ndata: {"type":"text-delta","id":"t1","delta":" you"}\n\ndata: {"type":"text-delta","id":"t1","delta":" reset"}\n\ndata: {"type":"text-delta","id":"t1","delta":" your"}\n\ndata: {"type":"text-delta","id":"t1","delta":" password"}\n\ndata: {"type":"text-delta","id":"t1","delta":"!"}\n\ndata: {"type":"text-end","id":"t1"}\n\ndata: {"type":"block-end","blockId":"b2"}\n\ndata: {"type":"finish","finishReason":"stop"}\n\ndata: [DONE]\n```\n\n### Event Types\n\n| Event | Description |\n|-------|-------------|\n| `start` | Stream started |\n| `finish` | Execution complete |\n| `error` | Error occurred |\n| `block-start` | Execution block started |\n| `block-end` | Execution block completed |\n| `text-start` | Text generation started |\n| `text-delta` | Incremental text content |\n| `text-end` | Text generation ended |\n| `reasoning-start` | Extended reasoning started |\n| `reasoning-delta` | Reasoning content |\n| `reasoning-end` | Extended reasoning ended |\n| `tool-input-start` | Tool call initiated |\n| `tool-input-delta` | Tool arguments streaming |\n| `tool-input-end` | Tool arguments streaming ended |\n| `tool-input-available` | Tool input complete |\n| `tool-output-available` | Tool completed with result |\n| `tool-output-error` | Tool failed |\n| `tool-request` | Platform requesting tool execution |\n| `resource-update` | Resource value changed |\n\n### Example\n\n```bash\ncurl -N -X POST https://octavus.ai/api/agent-sessions/:sessionId/trigger \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "triggerName": "user-message",\n    "input": { "USER_MESSAGE": "How do I reset my password?" }\n  }\'\n```\n\n## Tool Continuation\n\nWhen the agent calls external tools, you\'ll receive a `tool-request` event. Execute the tools and send results back:\n\n```json\n{\n  "triggerName": "user-message",\n  "input": { "USER_MESSAGE": "..." },\n  "toolResults": [\n    {\n      "toolCallId": "tc_123",\n      "toolName": "get-user-account",\n      "result": {\n        "name": "Demo User",\n        "email": "demo@example.com"\n      }\n    }\n  ]\n}\n```\n\nThe Server SDK handles this continuation pattern automatically.\n',
+        excerpt: "Sessions API Sessions represent conversations with agents. They store conversation history, resources, and variables.  Create Session Create a new agent session.  Request Body | Field | Type |...",
+        order: 2
+      },
+      {
+        slug: "api-reference/agents",
+        section: "api-reference",
+        title: "Agents",
+        description: "Agent management API endpoints.",
+        content: '\n# Agents API\n\nManage agent definitions including protocols and prompts.\n\n## List Agents\n\nGet all agents in the project.\n\n```\nGET /api/agents\n```\n\n### Response\n\n```json\n{\n  "agents": [\n    {\n      "id": "cm5xvz7k80001abcd",\n      "slug": "support-chat",\n      "name": "Support Chat",\n      "description": "Customer support agent",\n      "format": "interactive",\n      "createdAt": "2024-01-10T08:00:00Z",\n      "updatedAt": "2024-01-15T10:00:00Z"\n    }\n  ]\n}\n```\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agents \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n```\n\n## Get Agent\n\nGet a single agent by ID or slug.\n\n```\nGET /api/agents/:id\nGET /api/agents/:slug?by=slug\n```\n\n### Response\n\n```json\n{\n  "id": "cm5xvz7k80001abcd",\n  "settings": {\n    "slug": "support-chat",\n    "name": "Support Chat",\n    "description": "Customer support agent",\n    "format": "interactive"\n  },\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "You are a support agent for {{COMPANY_NAME}}..."\n    },\n    {\n      "name": "user-message",\n      "content": "{{USER_MESSAGE}}"\n    }\n  ]\n}\n```\n\n### Example\n\n```bash\n# By ID\ncurl https://octavus.ai/api/agents/:agentId \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n\n# By slug\ncurl "https://octavus.ai/api/agents/:slug?by=slug" \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n```\n\n## Create Agent\n\nCreate a new agent.\n\n```\nPOST /api/agents\n```\n\n### Request Body\n\n```json\n{\n  "settings": {\n    "slug": "support-chat",\n    "name": "Support Chat",\n    "description": "Customer support agent",\n    "format": "interactive"\n  },\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "You are a support agent..."\n    }\n  ]\n}\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `settings.slug` | string | Yes | URL-safe identifier |\n| `settings.name` | string | Yes | Display name |\n| `settings.description` | string | No | Agent description |\n| `settings.format` | string | Yes | `interactive` or `generation` |\n| `protocol` | string | Yes | YAML protocol definition |\n| `prompts` | array | Yes | Prompt files |\n\n### Response\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "message": "Agent created successfully"\n}\n```\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agents \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "settings": {\n      "slug": "my-agent",\n      "name": "My Agent",\n      "format": "interactive"\n    },\n    "protocol": "agent:\\n  model: anthropic/claude-sonnet-4-5\\n  system: system",\n    "prompts": [\n      { "name": "system", "content": "You are a helpful assistant." }\n    ]\n  }\'\n```\n\n## Update Agent\n\nUpdate an existing agent.\n\n```\nPATCH /api/agents/:id\nPATCH /api/agents/:slug?by=slug\n```\n\n### Request Body\n\n```json\n{\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "Updated system prompt..."\n    }\n  ]\n}\n```\n\nAll fields are optional. Only provided fields are updated.\n\n### Response\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "message": "Agent updated successfully"\n}\n```\n\n### Example\n\n```bash\ncurl -X PATCH https://octavus.ai/api/agents/:agentId \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "protocol": "agent:\\n  model: anthropic/claude-sonnet-4-5\\n  system: system\\n  thinking: high"\n  }\'\n```\n\n## Sync Agent\n\nThe Server SDK provides a `sync` method that creates or updates an agent:\n\n```typescript\nconst { agentId, created } = await client.agents.sync({\n  settings: {\n    slug: \'support-chat\',\n    name: \'Support Chat\',\n    format: \'interactive\',\n  },\n  protocol: protocolYaml,\n  prompts: [\n    { name: \'system\', content: systemPrompt },\n  ],\n});\n\nif (created) {\n  console.log(\'Created new agent:\', agentId);\n} else {\n  console.log(\'Updated existing agent:\', agentId);\n}\n```\n\nThis is useful for CI/CD pipelines to deploy agent updates.\n\n',
+        excerpt: "Agents API Manage agent definitions including protocols and prompts.  List Agents Get all agents in the project.  Response  Example  Get Agent Get a single agent by ID or slug.  Response  Example ...",
+        order: 3
+      }
+    ]
+  },
+  {
+    slug: "examples",
+    title: "Examples",
+    description: "Complete working examples demonstrating Octavus integration patterns.",
+    order: 6,
+    docs: [
+      {
+        slug: "examples/overview",
+        section: "examples",
+        title: "Overview",
+        description: "Complete integration examples for different architectures.",
+        content: "\n# Examples\n\nThis section provides complete integration examples for different architectures. Each example walks through building a functional chat interface from scratch.\n\n## Available Examples\n\n| Example | Transport | Best For |\n|---------|-----------|----------|\n| [Next.js Chat](/docs/examples/nextjs-chat) | HTTP/SSE | Next.js, Remix, standard web apps |\n| [Socket Chat](/docs/examples/socket-chat) | SockJS | Meteor, Phoenix, real-time apps |\n\n## Choosing a Transport\n\n**Use HTTP Transport when:**\n- Building with Next.js, Remix, or similar frameworks\n- You want the simplest integration\n- Deploying to serverless (Vercel, Netlify, etc.)\n\n**Use Socket Transport when:**\n- Using Meteor, Phoenix, or socket-based frameworks\n- Need custom real-time events (typing indicators, presence)\n- Behind proxies that don't support SSE well\n",
+        excerpt: "Examples This section provides complete integration examples for different architectures. Each example walks through building a functional chat interface from scratch.  Available Examples | Example |...",
+        order: 1
+      },
+      {
+        slug: "examples/nextjs-chat",
+        section: "examples",
+        title: "Next.js Chat",
+        description: "Building a chat interface with Next.js and HTTP transport.",
+        content: "\n# Next.js Chat Example\n\nThis example builds a support chat interface using Next.js App Router with HTTP/SSE transport. This is the recommended pattern for most web applications.\n\n## What You're Building\n\nA chat interface that:\n- Creates sessions server-side\n- Streams AI responses in real-time\n- Handles tool calls on your server\n- Shows typing status during streaming\n\n## Architecture\n\n```\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502                 \u2502   POST /api/chat   \u2502                 \u2502\n\u2502     Browser     \u2502 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BA\u2502   Next.js API   \u2502\n\u2502    (React)      \u2502                    \u2502     Routes      \u2502\n\u2502                 \u2502\u25C4\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500SSE\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2502                 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                                                \u2502\n                                                \u25BC\n                                       \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n                                       \u2502                 \u2502\n                                       \u2502 Octavus Platform\u2502\n                                       \u2502                 \u2502\n                                       \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## Prerequisites\n\n- Next.js 14+ with App Router\n- Octavus account with API key\n- An agent configured in Octavus\n\n## Step 1: Install Dependencies\n\n```bash\nnpm install @octavus/server-sdk @octavus/react\n```\n\n## Step 2: Configure Environment\n\n```bash\n# .env.local\nOCTAVUS_API_URL=https://octavus.ai\nOCTAVUS_API_KEY=your-api-key\n```\n\n## Step 3: Create the Octavus Client\n\n```typescript\n// lib/octavus.ts\nimport { OctavusClient } from '@octavus/server-sdk';\n\nexport const octavus = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n```\n\n## Step 4: Create Session Endpoint\n\nSessions hold conversation state. Create one when the user opens the chat:\n\n```typescript\n// app/api/sessions/route.ts\nimport { NextResponse } from 'next/server';\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { agentId, input } = await request.json();\n\n  // Create a new session with initial input variables\n  const sessionId = await octavus.agentSessions.create(agentId, input);\n\n  return NextResponse.json({ sessionId });\n}\n```\n\n**Protocol Note:** The `input` object contains variables defined in your agent's protocol. For example, if your agent has `COMPANY_NAME` as an input variable:\n\n```typescript\nconst sessionId = await octavus.agentSessions.create(agentId, {\n  COMPANY_NAME: 'Acme Corp',\n  USER_ID: user.id,\n});\n```\n\n## Step 5: Create Trigger Endpoint\n\nTriggers execute agent actions. The `user-message` trigger is the most common:\n\n```typescript\n// app/api/trigger/route.ts\nimport { toSSEStream } from '@octavus/server-sdk';\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { sessionId, triggerName, input } = await request.json();\n\n  // Attach to the session with tool handlers\n  const session = octavus.agentSessions.attach(sessionId, {\n    tools: {\n      // Tool handlers run on YOUR server, not Octavus\n      'get-user-account': async (args) => {\n        const userId = args.userId as string;\n        // Fetch from your database\n        const user = await db.users.findUnique({ where: { id: userId } });\n        return {\n          name: user.name,\n          email: user.email,\n          plan: user.plan,\n        };\n      },\n\n      'create-support-ticket': async (args) => {\n        const ticket = await db.tickets.create({\n          data: {\n            summary: args.summary as string,\n            priority: args.priority as string,\n          },\n        });\n        return {\n          ticketId: ticket.id,\n          estimatedResponse: '24 hours',\n        };\n      },\n    },\n  });\n\n  // trigger() returns parsed events, toSSEStream() converts to SSE format\n  const events = session.trigger(triggerName, input);\n\n  return new Response(toSSEStream(events), {\n    headers: {\n      'Content-Type': 'text/event-stream',\n      'Cache-Control': 'no-cache',\n      Connection: 'keep-alive',\n    },\n  });\n}\n```\n\n**Protocol Note:** Tool names and arguments are defined in your agent's protocol YAML. The tool handlers here must match those definitions.\n\n## Step 6: Build the Chat Component\n\n```tsx\n// components/Chat.tsx\n'use client';\n\nimport { useState, useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\ninterface ChatProps {\n  sessionId: string;\n}\n\nexport function Chat({ sessionId }: ChatProps) {\n  const [inputValue, setInputValue] = useState('');\n\n  // Create transport - memoized on sessionId\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        triggerRequest: (triggerName, input) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, triggerName, input }),\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { messages, status, send } = useOctavusChat({ transport });\n\n  const handleSubmit = async (e: React.FormEvent) => {\n    e.preventDefault();\n    if (!inputValue.trim() || status === 'streaming') return;\n\n    const message = inputValue.trim();\n    setInputValue('');\n\n    // Send triggers the 'user-message' action\n    // The third argument adds the user message to the UI\n    await send(\n      'user-message',\n      { USER_MESSAGE: message },\n      { userMessage: { content: message } },\n    );\n  };\n\n  return (\n    <div className=\"flex flex-col h-screen\">\n      {/* Messages */}\n      <div className=\"flex-1 overflow-y-auto p-4 space-y-4\">\n        {messages.map((msg) => (\n          <div\n            key={msg.id}\n            className={msg.role === 'user' ? 'text-right' : 'text-left'}\n          >\n            <div\n              className={`inline-block p-3 rounded-lg ${\n                msg.role === 'user'\n                  ? 'bg-blue-500 text-white'\n                  : 'bg-gray-100'\n              }`}\n            >\n              {msg.parts.map((part, i) => {\n                if (part.type === 'text') {\n                  return <p key={i}>{part.text}</p>;\n                }\n                if (part.type === 'tool-call') {\n                  return (\n                    <div key={i} className=\"text-sm opacity-70\">\n                      Using {part.toolName}...\n                    </div>\n                  );\n                }\n                return null;\n              })}\n            </div>\n          </div>\n        ))}\n      </div>\n\n      {/* Input */}\n      <form onSubmit={handleSubmit} className=\"p-4 border-t\">\n        <div className=\"flex gap-2\">\n          <input\n            type=\"text\"\n            value={inputValue}\n            onChange={(e) => setInputValue(e.target.value)}\n            placeholder=\"Type a message...\"\n            className=\"flex-1 px-4 py-2 border rounded-lg\"\n            disabled={status === 'streaming'}\n          />\n          <button\n            type=\"submit\"\n            disabled={status === 'streaming'}\n            className=\"px-4 py-2 bg-blue-500 text-white rounded-lg\"\n          >\n            {status === 'streaming' ? 'Sending...' : 'Send'}\n          </button>\n        </div>\n      </form>\n    </div>\n  );\n}\n```\n\n## Step 7: Create the Page\n\n```tsx\n// app/chat/page.tsx\n'use client';\n\nimport { useEffect, useState } from 'react';\nimport { Chat } from '@/components/Chat';\n\nconst AGENT_ID = 'your-agent-id'; // From Octavus dashboard\n\nexport default function ChatPage() {\n  const [sessionId, setSessionId] = useState<string | null>(null);\n\n  useEffect(() => {\n    // Create session on mount\n    fetch('/api/sessions', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({\n        agentId: AGENT_ID,\n        input: {\n          COMPANY_NAME: 'Acme Corp',\n        },\n      }),\n    })\n      .then((res) => res.json())\n      .then((data) => setSessionId(data.sessionId));\n  }, []);\n\n  if (!sessionId) {\n    return <div className=\"p-8\">Loading...</div>;\n  }\n\n  return <Chat sessionId={sessionId} />;\n}\n```\n\n## Protocol Integration\n\nYour agent's protocol defines the triggers and tools. Here's how the code maps to protocol:\n\n### Triggers\n\n```yaml\n# In your agent's protocol.yaml\ntriggers:\n  user-message:\n    description: User sends a chat message\n    input:\n      USER_MESSAGE:\n        type: string\n        description: The user's message\n```\n\nThe `send()` call maps directly:\n\n```typescript\nawait send(\n  'user-message',           // trigger name\n  { USER_MESSAGE: message }, // trigger inputs\n  { userMessage: { content: message } },\n);\n```\n\n### Tools\n\n```yaml\n# In your agent's protocol.yaml\ntools:\n  get-user-account:\n    description: Fetch user account details\n    parameters:\n      userId:\n        type: string\n        description: The user ID to look up\n```\n\nTool handlers receive the parameters as `args`:\n\n```typescript\n'get-user-account': async (args) => {\n  const userId = args.userId as string;\n  // ...\n}\n```\n\n## Next Steps\n\n- [Protocol Overview](/docs/protocol/overview) \u2014 Define agent behavior\n- [Messages](/docs/client-sdk/messages) \u2014 Rich message rendering\n- [Streaming](/docs/client-sdk/streaming) \u2014 Advanced streaming UI\n\n",
+        excerpt: "Next.js Chat Example This example builds a support chat interface using Next.js App Router with HTTP/SSE transport. This is the recommended pattern for most web applications.  What You're Building A...",
+        order: 2
+      },
+      {
+        slug: "examples/socket-chat",
+        section: "examples",
+        title: "Socket Chat",
+        description: "Building a chat interface with SockJS for real-time frameworks.",
+        content: "\n# Socket Chat Example\n\nThis example builds a chat interface using SockJS for bidirectional communication. Use this pattern for Meteor, Phoenix, or when you need custom real-time events.\n\n## What You're Building\n\nA chat interface that:\n- Uses SockJS for real-time streaming\n- Manages sessions server-side (client doesn't need sessionId)\n- Supports custom events alongside chat\n- Works with frameworks that use WebSocket-like transports\n\n## Architecture\n\n```\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502                 \u2502                    \u2502                 \u2502\n\u2502     Browser     \u2502\u25C4\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2502  Your Server    \u2502\n\u2502    (React)      \u2502      SockJS        \u2502  (Express)      \u2502\n\u2502                 \u2502\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u25BA\u2502                 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                                                \u2502\n                                                \u25BC\n                                       \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n                                       \u2502                 \u2502\n                                       \u2502 Octavus Platform\u2502\n                                       \u2502                 \u2502\n                                       \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n**Key difference from HTTP:** The server maintains a persistent socket connection and manages sessions internally. The client never needs to know about `sessionId`.\n\n## Prerequisites\n\n- Express (or similar Node.js server)\n- React frontend\n- `sockjs` (server) and `sockjs-client` (client)\n- Octavus account with API key\n\n## Step 1: Install Dependencies\n\n**Server:**\n```bash\nnpm install @octavus/server-sdk sockjs express\nnpm install -D @types/sockjs @types/express\n```\n\n**Client:**\n```bash\nnpm install @octavus/react sockjs-client\nnpm install -D @types/sockjs-client\n```\n\n## Step 2: Configure Environment\n\n```bash\n# .env\nOCTAVUS_API_URL=https://octavus.ai\nOCTAVUS_API_KEY=your-api-key\nOCTAVUS_AGENT_ID=your-agent-id\n```\n\n## Step 3: Create the Octavus Client (Server)\n\n```typescript\n// server/octavus/client.ts\nimport { OctavusClient } from '@octavus/server-sdk';\n\nexport const octavus = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n\nexport const AGENT_ID = process.env.OCTAVUS_AGENT_ID!;\n```\n\n## Step 4: Create the Socket Handler (Server)\n\nThis is the core of socket integration. Each connection gets its own session:\n\n```typescript\n// server/octavus/socket-handler.ts\nimport type { Connection } from 'sockjs';\nimport { OctavusClient, type AgentSession } from '@octavus/server-sdk';\n\nconst octavus = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n\nconst AGENT_ID = process.env.OCTAVUS_AGENT_ID!;\n\nexport function createSocketHandler() {\n  return (conn: Connection) => {\n    let session: AgentSession | null = null;\n    let abortController: AbortController | null = null;\n\n    conn.on('data', (rawData: string) => {\n      void handleMessage(rawData);\n    });\n\n    async function handleMessage(rawData: string) {\n      const msg = JSON.parse(rawData);\n\n      // Handle stop request\n      if (msg.type === 'stop') {\n        abortController?.abort();\n        return;\n      }\n\n      // Handle trigger\n      if (msg.type === 'trigger') {\n        // Create session lazily on first trigger\n        if (!session) {\n          const sessionId = await octavus.agentSessions.create(AGENT_ID, {\n            // Initial input variables from your protocol\n            COMPANY_NAME: 'Acme Corp',\n          });\n\n          session = octavus.agentSessions.attach(sessionId, {\n            tools: {\n              'get-user-account': async () => {\n                // Fetch from your database\n                return { name: 'Demo User', plan: 'pro' };\n              },\n              'create-support-ticket': async () => {\n                return { ticketId: 'TKT-123', estimatedResponse: '24h' };\n              },\n            },\n          });\n        }\n\n        abortController = new AbortController();\n\n        // trigger() returns parsed events \u2014 iterate directly\n        const events = session.trigger(msg.triggerName, msg.input);\n\n        try {\n          for await (const event of events) {\n            if (abortController.signal.aborted) break;\n            conn.write(JSON.stringify(event));\n          }\n        } catch {\n          // Handle errors\n        }\n      }\n    }\n\n    conn.on('close', () => {\n      abortController?.abort();\n    });\n  };\n}\n```\n\n## Step 5: Set Up the Express Server\n\n```typescript\n// server/index.ts\nimport express from 'express';\nimport http from 'http';\nimport sockjs from 'sockjs';\nimport { createSocketHandler } from './octavus/socket-handler';\n\nconst app = express();\nconst server = http.createServer(app);\n\n// Create SockJS server\nconst sockServer = sockjs.createServer({\n  prefix: '/octavus',\n  log: () => {}, // Silence logs\n});\n\n// Attach handler\nsockServer.on('connection', createSocketHandler());\nsockServer.installHandlers(server);\n\n// Serve your frontend\napp.use(express.static('dist/client'));\n\nserver.listen(3001, () => {\n  console.log('Server running on http://localhost:3001');\n});\n```\n\n## Step 6: Create the Socket Hook (Client)\n\n```typescript\n// src/hooks/useOctavusSocket.ts\nimport { useMemo } from 'react';\nimport SockJS from 'sockjs-client';\nimport { useOctavusChat, createSocketTransport, type SocketLike } from '@octavus/react';\n\nfunction connectSocket(): Promise<SocketLike> {\n  return new Promise((resolve, reject) => {\n    const sock = new SockJS('/octavus');\n\n    sock.onopen = () => resolve(sock);\n    sock.onerror = () => reject(new Error('Connection failed'));\n  });\n}\n\nexport function useOctavusSocket() {\n  // Transport is stable - empty deps because server manages sessions\n  const transport = useMemo(\n    () => createSocketTransport({ connect: connectSocket }),\n    [],\n  );\n\n  const { messages, status, error, send, stop } = useOctavusChat({\n    transport,\n    onError: (err) => console.error('Chat error:', err),\n  });\n\n  const sendMessage = async (message: string) => {\n    await send(\n      'user-message',\n      { USER_MESSAGE: message },\n      { userMessage: { content: message } },\n    );\n  };\n\n  return { messages, status, error, sendMessage, stop };\n}\n```\n\n## Step 7: Build the Chat Component\n\n```tsx\n// src/components/Chat.tsx\nimport { useState } from 'react';\nimport { useOctavusSocket } from '../hooks/useOctavusSocket';\n\nexport function Chat() {\n  const [inputValue, setInputValue] = useState('');\n  const { messages, status, sendMessage, stop } = useOctavusSocket();\n\n  const handleSubmit = async (e: React.FormEvent) => {\n    e.preventDefault();\n    if (!inputValue.trim() || status === 'streaming') return;\n\n    const message = inputValue.trim();\n    setInputValue('');\n    await sendMessage(message);\n  };\n\n  return (\n    <div className=\"flex flex-col h-screen\">\n      {/* Messages */}\n      <div className=\"flex-1 overflow-y-auto p-4 space-y-4\">\n        {messages.map((msg) => (\n          <div\n            key={msg.id}\n            className={msg.role === 'user' ? 'text-right' : 'text-left'}\n          >\n            <div\n              className={`inline-block p-3 rounded-lg ${\n                msg.role === 'user'\n                  ? 'bg-blue-500 text-white'\n                  : 'bg-gray-100'\n              }`}\n            >\n              {msg.parts.map((part, i) => {\n                if (part.type === 'text') return <p key={i}>{part.text}</p>;\n                return null;\n              })}\n            </div>\n          </div>\n        ))}\n      </div>\n\n      {/* Input */}\n      <form onSubmit={handleSubmit} className=\"p-4 border-t flex gap-2\">\n        <input\n          type=\"text\"\n          value={inputValue}\n          onChange={(e) => setInputValue(e.target.value)}\n          placeholder=\"Type a message...\"\n          className=\"flex-1 px-4 py-2 border rounded-lg\"\n          disabled={status === 'streaming'}\n        />\n        {status === 'streaming' ? (\n          <button\n            type=\"button\"\n            onClick={stop}\n            className=\"px-4 py-2 bg-red-500 text-white rounded-lg\"\n          >\n            Stop\n          </button>\n        ) : (\n          <button\n            type=\"submit\"\n            className=\"px-4 py-2 bg-blue-500 text-white rounded-lg\"\n          >\n            Send\n          </button>\n        )}\n      </form>\n    </div>\n  );\n}\n```\n\n## Custom Events\n\nSocket transport supports custom events alongside Octavus events:\n\n```typescript\n// Client - handle custom events\nconst transport = useMemo(\n  () =>\n    createSocketTransport({\n      connect: connectSocket,\n      onMessage: (data) => {\n        const msg = data as { type: string; [key: string]: unknown };\n\n        if (msg.type === 'typing-indicator') {\n          setAgentTyping(msg.isTyping as boolean);\n        }\n\n        if (msg.type === 'custom-notification') {\n          showToast(msg.message as string);\n        }\n\n        // Octavus events (text-delta, finish, etc.) are handled automatically\n      },\n    }),\n  [],\n);\n```\n\n```typescript\n// Server - send custom events\nconn.write(JSON.stringify({\n  type: 'typing-indicator',\n  isTyping: true,\n}));\n```\n\n## Protocol Integration\n\n### Triggers\n\nThe socket handler receives trigger messages and forwards them to Octavus:\n\n```typescript\n// Client sends:\n{ type: 'trigger', triggerName: 'user-message', input: { USER_MESSAGE: 'Hello' } }\n\n// Server handles:\nif (msg.type === 'trigger') {\n  const events = session.trigger(msg.triggerName, msg.input);\n  for await (const event of events) {\n    conn.write(JSON.stringify(event));\n  }\n}\n```\n\n### Tools\n\nTools are defined in your agent's protocol and handled server-side:\n\n```yaml\n# protocol.yaml\ntools:\n  get-user-account:\n    description: Fetch user details\n    parameters:\n      userId:\n        type: string\n```\n\n```typescript\n// Server tool handler\ntools: {\n  'get-user-account': async (args) => {\n    const userId = args.userId as string;\n    return await db.users.find(userId);\n  },\n}\n```\n\n## Meteor Integration Note\n\nMeteor's bundler may have issues with ES6 imports of `sockjs-client`:\n\n```typescript\n// Use require() instead of import\nconst SockJS: typeof import('sockjs-client') = require('sockjs-client');\n```\n\n## Next Steps\n\n- [Socket Transport](/docs/client-sdk/socket-transport) \u2014 Advanced socket patterns\n- [Protocol Overview](/docs/protocol/overview) \u2014 Define agent behavior\n- [Tools](/docs/protocol/tools) \u2014 Building tool handlers\n\n",
+        excerpt: "Socket Chat Example This example builds a chat interface using SockJS for bidirectional communication. Use this pattern for Meteor, Phoenix, or when you need custom real-time events.  What You're...",
+        order: 3
+      }
+    ]
+  }
+];
+
+// src/content.ts
+var docs = docs_default;
+var sections = sections_default;
+function getAllDocs() {
+  return docs;
+}
+function getDocSections() {
+  return sections;
+}
+function getDocsData() {
+  return { docs, sections };
+}
+function getDocBySlug(slug) {
+  return docs.find((doc) => doc.slug === slug) ?? null;
+}
+function getDocSlugs() {
+  return docs.map((doc) => doc.slug);
+}
+function getSectionBySlug(sectionSlug) {
+  return sections.find((section) => section.slug === sectionSlug) ?? null;
+}
+
+export {
+  getAllDocs,
+  getDocSections,
+  getDocsData,
+  getDocBySlug,
+  getDocSlugs,
+  getSectionBySlug
+};
+//# sourceMappingURL=chunk-PMOVVTHO.js.map