@octavus/docs 0.0.5 → 0.0.6

package/dist/sections.json

@@ -10,7 +10,7 @@
         "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** — No unified way to define, manage, and deploy agents\n- **Prompt management** — Prompts are scattered across codebases, hard to version and iterate\n- **Integration complexity** — Connecting agents to tools, resources, and other agents requires significant custom work\n- **Observability** — Difficult to debug, monitor, and understand agent behavior in production\n- **Infrastructure overhead** — 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 — 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** — Respond to a text message in a chat interface\n- **User Action** — Respond to UI actions (button clicks, form submissions)\n- **API Call** — Direct invocation via SDK\n\n### Tools\n\n**Tools** extend what agents can do:\n\n- **External Tools** — Consumer-defined tools that call back to your systems\n- **Internal Tools** — 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) — Get your first agent running in minutes\n- [Server SDK](/docs/server-sdk/overview) — Learn about backend integration\n- [Client SDK](/docs/client-sdk/overview) — Build chat interfaces with React\n- [Protocol Reference](/docs/protocol/overview) — Deep dive into agent protocols\n\n",
+        "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** — No unified way to define, manage, and deploy agents\n- **Prompt management** — Prompts are scattered across codebases, hard to version and iterate\n- **Integration complexity** — Connecting agents to tools, resources, and other agents requires significant custom work\n- **Observability** — Difficult to debug, monitor, and understand agent behavior in production\n- **Infrastructure overhead** — 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 — 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** — Respond to a text message in a chat interface\n- **User Action** — Respond to UI actions (button clicks, form submissions)\n- **API Call** — Direct invocation via SDK\n\n### Tools\n\n**Tools** extend what agents can do:\n\n- **External Tools** — Consumer-defined tools that call back to your systems\n- **Internal Tools** — 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) — Get your first agent running in minutes\n- [Server SDK](/docs/server-sdk/overview) — Learn about backend integration\n- [Client SDK](/docs/client-sdk/overview) — Build chat interfaces with React (or other frameworks)\n- [Protocol Reference](/docs/protocol/overview) — 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
       },
@@ -19,7 +19,7 @@
         "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# Client SDK for frontend (React)\nnpm install @octavus/client-sdk\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 { 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 get the stream\n  const { stream } = session.trigger(triggerName, input);\n\n  // Return as streaming response\n  return new Response(stream, {\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 to build a chat interface:\n\n```tsx\n// components/chat.tsx\n'use client';\n\nimport { useOctavusChat, type UIMessage } from '@octavus/client-sdk';\nimport { useState } from 'react';\n\ninterface ChatProps {\n  sessionId: string;\n}\n\nexport function Chat({ sessionId }: ChatProps) {\n  const [inputValue, setInputValue] = useState('');\n\n  const { messages, status, error, send } = useOctavusChat({\n    onTrigger: async (triggerName, input) => {\n      return fetch('/api/trigger', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ sessionId, triggerName, input }),\n      });\n    },\n  });\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('user-message', { 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",
+        "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 { 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 get the stream\n  const { stream } = session.trigger(triggerName, input);\n\n  // Return as streaming response\n  return new Response(stream, {\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 to build a chat interface:\n\n```tsx\n// components/chat.tsx\n'use client';\n\nimport { useOctavusChat, type UIMessage } from '@octavus/react';\nimport { useState } from 'react';\n\ninterface ChatProps {\n  sessionId: string;\n}\n\nexport function Chat({ sessionId }: ChatProps) {\n  const [inputValue, setInputValue] = useState('');\n\n  const { messages, status, error, send } = useOctavusChat({\n    onTrigger: async (triggerName, input) => {\n      return fetch('/api/trigger', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ sessionId, triggerName, input }),\n      });\n    },\n  });\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('user-message', { 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
       }
@@ -36,7 +36,7 @@
         "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.5`\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('support-chat', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n});\n\n// Get session state\nconst state = await client.agentSessions.get(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\nconst { stream } = session.trigger('user-message', { \n  USER_MESSAGE: 'Hello!' \n});\n\n// Use as a streaming response\nreturn new Response(stream, {\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 session state (includes UI-ready messages)\n  async get(sessionId: string): Promise<UISessionState>;\n  \n  // Attach to a session for triggering\n  attach(sessionId: string, options?: SessionAttachOptions): AgentSession;\n}\n\ninterface UISessionState {\n  id: string;\n  agentId: string;\n  input: Record<string, unknown>;\n  variables: Record<string, unknown>;\n  resources: Record<string, unknown>;\n  messages: UIMessage[];  // UI-ready messages for session restore\n  createdAt: string;\n  updatedAt: string;\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 the response\n  trigger(\n    triggerName: string,\n    input?: Record<string, unknown>\n  ): { stream: ReadableStream<Uint8Array> };\n  \n  // Get the session ID\n  getSessionId(): string;\n}\n```\n\n## Next Steps\n\n- [Sessions](/docs/server-sdk/sessions) — Deep dive into session management\n- [Tools](/docs/server-sdk/tools) — Implementing tool handlers\n- [Streaming](/docs/server-sdk/streaming) — Understanding stream events\n",
+        "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.6`\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('support-chat', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n});\n\n// Get session state\nconst state = await client.agentSessions.get(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\nconst { stream } = session.trigger('user-message', { \n  USER_MESSAGE: 'Hello!' \n});\n\n// Use as a streaming response\nreturn new Response(stream, {\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 session state (includes UI-ready messages)\n  async get(sessionId: string): Promise<UISessionState>;\n  \n  // Attach to a session for triggering\n  attach(sessionId: string, options?: SessionAttachOptions): AgentSession;\n}\n\ninterface UISessionState {\n  id: string;\n  agentId: string;\n  input: Record<string, unknown>;\n  variables: Record<string, unknown>;\n  resources: Record<string, unknown>;\n  messages: UIMessage[];  // UI-ready messages for session restore\n  createdAt: string;\n  updatedAt: string;\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 the response\n  trigger(\n    triggerName: string,\n    input?: Record<string, unknown>\n  ): { stream: ReadableStream<Uint8Array> };\n  \n  // Get the session ID\n  getSessionId(): string;\n}\n```\n\n## Next Steps\n\n- [Sessions](/docs/server-sdk/sessions) — Deep dive into session management\n- [Tools](/docs/server-sdk/tools) — Implementing tool handlers\n- [Streaming](/docs/server-sdk/streaming) — 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
       },
@@ -72,16 +72,16 @@
   {
     "slug": "client-sdk",
     "title": "Client SDK",
-    "description": "Frontend integration with @octavus/client-sdk for React applications.",
+    "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 SDK for building chat interfaces.",
-        "content": "\n# Client SDK Overview\n\nThe `@octavus/client-sdk` package provides React hooks for building chat interfaces with Octavus agents. It handles streaming, message state, and real-time updates.\n\n**Current version:** `0.0.5`\n\n## Installation\n\n```bash\nnpm install @octavus/client-sdk\n```\n\n## Basic Usage\n\n```tsx\nimport { useOctavusChat, type UIMessage } from '@octavus/client-sdk';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const { messages, status, send } = useOctavusChat({\n    onTrigger: async (triggerName, input) => {\n      return fetch(`/api/trigger`, {\n        method: 'POST',\n        body: JSON.stringify({ sessionId, triggerName, input }),\n      });\n    },\n  });\n\n  const sendMessage = async (text: string) => {\n    await send('user-message', { 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## 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({...});\n\n// Add user message to UI and trigger agent\nawait send('user-message', { 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({...});\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({...});\n\n// status: 'idle' | 'streaming' | 'error'\n```\n\n### Stop Streaming\n\n```tsx\nconst { stop } = useOctavusChat({...});\n\n// Stop current stream and finalize message\nstop();\n```\n\n## Hook Reference\n\n### useOctavusChat\n\n```typescript\nfunction useOctavusChat(options: UseOctavusChatOptions): UseOctavusChatReturn;\n\ninterface UseOctavusChatOptions {\n  // Required: Function that calls your backend trigger endpoint\n  onTrigger: TriggerFunction;\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\ntype TriggerFunction = (\n  triggerName: string,\n  input?: Record<string, unknown>,\n) => Promise<Response>;\n\ninterface UserMessageInput {\n  content: string;\n}\n```\n\n## Next Steps\n\n- [Messages](/docs/client-sdk/messages) — Working with message state\n- [Streaming](/docs/client-sdk/streaming) — Building streaming UIs\n- [Execution Blocks](/docs/client-sdk/execution-blocks) — Showing agent progress\n",
-        "excerpt": "Client SDK Overview The  package provides React hooks for building chat interfaces with Octavus agents. It handles streaming, message state, and real-time updates. Current version:   Installation ...",
+        "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`** — 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.6`\n\n### Other Frameworks\n\n```bash\nnpm install @octavus/client-sdk\n```\n\n**Current version:** `0.0.6`\n\n## React Usage\n\nThe `useOctavusChat` hook provides state management and streaming for React applications:\n\n```tsx\nimport { useOctavusChat, type UIMessage } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const { messages, status, send } = useOctavusChat({\n    onTrigger: async (triggerName, input) => {\n      return fetch(`/api/trigger`, {\n        method: 'POST',\n        body: JSON.stringify({ sessionId, triggerName, input }),\n      });\n    },\n  });\n\n  const sendMessage = async (text: string) => {\n    await send('user-message', { 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 } from '@octavus/client-sdk';\n\nconst chat = new OctavusChat({\n  onTrigger: async (triggerName, input) => {\n    return fetch('/api/trigger', {\n      method: 'POST',\n      body: JSON.stringify({ sessionId, triggerName, input }),\n    });\n  },\n});\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('user-message', { 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({...});\n\n// Add user message to UI and trigger agent\nawait send('user-message', { 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({...});\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({...});\n\n// status: 'idle' | 'streaming' | 'error'\n```\n\n### Stop Streaming\n\n```tsx\nconst { stop } = useOctavusChat({...});\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: Function that calls your backend trigger endpoint\n  onTrigger: TriggerFunction;\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\ntype TriggerFunction = (\n  triggerName: string,\n  input?: Record<string, unknown>,\n) => Promise<Response>;\n\ninterface UserMessageInput {\n  content: string;\n}\n```\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- [Messages](/docs/client-sdk/messages) — Working with message state\n- [Streaming](/docs/client-sdk/streaming) — Building streaming UIs\n- [Execution Blocks](/docs/client-sdk/execution-blocks) — Showing agent progress\n",
+        "excerpt": "Client SDK Overview Octavus provides two packages for frontend integration: | Package | Purpose | Use When | |---------|---------|----------| |  | React hooks and bindings | Building React...",
         "order": 1
       },
       {
@@ -89,7 +89,7 @@
         "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\nconst { send } = useOctavusChat({...});\n\nasync function handleSend(text: string) {\n  // Add user message to UI and trigger agent\n  await send('user-message', { USER_MESSAGE: text }, {\n    userMessage: { content: text },\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/client-sdk';\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          🔧 {part.displayName || part.toolName}\n          {part.status === 'done' && ' ✓'}\n          {part.status === 'error' && ` ✗ ${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' && ' ✓'}\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/client-sdk';\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, pass existing messages:\n\n```tsx\n// Fetch session state from your backend\nconst sessionState = await fetchSession(sessionId);\n\n// Pass to hook\nconst { messages } = useOctavusChat({\n  initialMessages: sessionState.messages,\n  onTrigger: ...\n});\n```\n\n## Callbacks\n\n```tsx\nuseOctavusChat({\n  onTrigger: ...,\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",
+        "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\nconst { send } = useOctavusChat({...});\n\nasync function handleSend(text: string) {\n  // Add user message to UI and trigger agent\n  await send('user-message', { USER_MESSAGE: text }, {\n    userMessage: { content: text },\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          🔧 {part.displayName || part.toolName}\n          {part.status === 'done' && ' ✓'}\n          {part.status === 'error' && ` ✗ ${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' && ' ✓'}\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, pass existing messages:\n\n```tsx\n// Fetch session state from your backend\nconst sessionState = await fetchSession(sessionId);\n\n// Pass to hook\nconst { messages } = useOctavusChat({\n  initialMessages: sessionState.messages,\n  onTrigger: ...\n});\n```\n\n## Callbacks\n\n```tsx\nuseOctavusChat({\n  onTrigger: ...,\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
       },
@@ -98,7 +98,7 @@
         "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({...});\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\nfunction Chat() {\n  const { messages, status, error, send, stop } = useOctavusChat({...});\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 && (\n        <div className=\"text-red-500\">{error.message}</div>\n      )}\n\n      {/* Stop button during streaming */}\n      {status === 'streaming' && (\n        <button onClick={stop}>Stop</button>\n      )}\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/client-sdk';\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' ? '💭 Thinking...' : '💭 Thought process'}\n        {expanded ? '▼' : '▶'}\n      </button>\n      \n      {expanded && (\n        <pre className=\"mt-2 text-sm text-gray-600\">\n          {part.text}\n        </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/client-sdk';\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\">🔧</span>\n        <span className=\"font-medium\">\n          {part.displayName || part.toolName}\n        </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\">○</span>;\n    case 'running':\n      return <span className=\"text-blue-500 animate-spin\">◐</span>;\n    case 'done':\n      return <span className=\"text-green-500\">✓</span>;\n    case 'error':\n      return <span className=\"text-red-500\">✗</span>;\n  }\n}\n```\n\n## Status Indicator\n\n```tsx\nfunction StatusIndicator() {\n  const { status } = useOctavusChat({...});\n\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  onTrigger: ...,\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({...});\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 } from '@octavus/client-sdk';\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) => <PartRenderer key={i} part={part} />)}\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) => <PartRenderer key={i} part={part} />)}\n        </div>\n      )}\n    </div>\n  );\n}\n```\n",
+        "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({...});\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\nfunction Chat() {\n  const { messages, status, error, send, stop } = useOctavusChat({...});\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 && (\n        <div className=\"text-red-500\">{error.message}</div>\n      )}\n\n      {/* Stop button during streaming */}\n      {status === 'streaming' && (\n        <button onClick={stop}>Stop</button>\n      )}\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' ? '💭 Thinking...' : '💭 Thought process'}\n        {expanded ? '▼' : '▶'}\n      </button>\n      \n      {expanded && (\n        <pre className=\"mt-2 text-sm text-gray-600\">\n          {part.text}\n        </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\">🔧</span>\n        <span className=\"font-medium\">\n          {part.displayName || part.toolName}\n        </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\">○</span>;\n    case 'running':\n      return <span className=\"text-blue-500 animate-spin\">◐</span>;\n    case 'done':\n      return <span className=\"text-green-500\">✓</span>;\n    case 'error':\n      return <span className=\"text-red-500\">✗</span>;\n  }\n}\n```\n\n## Status Indicator\n\n```tsx\nfunction StatusIndicator() {\n  const { status } = useOctavusChat({...});\n\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  onTrigger: ...,\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({...});\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 } 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) => <PartRenderer key={i} part={part} />)}\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) => <PartRenderer key={i} part={part} />)}\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
       },
@@ -107,7 +107,7 @@
         "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/client-sdk';\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\">✓</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/client-sdk';\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' ? '⏳' : '✓'}\n          <span>{op.name}</span>\n        </div>\n      ))}\n    </div>\n  );\n}\n\n// Example output during escalation:\n// ✓ Serialize conversation\n// ✓ Save conversation summary\n// ⏳ 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 — 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\">✓</span>}\n    </div>\n  );\n}\n```\n",
+        "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\">✓</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' ? '⏳' : '✓'}\n          <span>{op.name}</span>\n        </div>\n      ))}\n    </div>\n  );\n}\n\n// Example output during escalation:\n// ✓ Serialize conversation\n// ✓ Save conversation summary\n// ⏳ 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 — 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\">✓</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
       }
@@ -133,7 +133,7 @@
         "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## 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",
+        "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
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octavus/docs",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Documentation content for Octavus SDKs",
   "license": "MIT",
   "author": "Octavus AI <hello@octavus.ai>",