docs: update observability overview

website/observability/mental-model.md

@@ -0,0 +1,35 @@
+---
+title: Mental Model
+hide_table_of_contents: true
+---
+
+# Mental Model
+
+This page shows the minimum mental model you need to open a VoltOps trace and understand what happened.
+AI agents are hard to debug if you only look at final output.
+VoltOps solves this by showing each run as a trace with step-level spans.
+
+## One Request, One Trace
+
+```mermaid
+sequenceDiagram
+  participant U as User
+  participant T as Trace (traceId)
+  participant A as Agent span
+  participant L as LLM span
+  participant O as Tool span
+
+  U->>T: Send request
+  T->>A: Start agent step
+  A->>L: Generate response
+  L->>O: Call tool (if needed)
+  O-->>A: Return tool result
+  A-->>T: Complete execution
+  T-->>U: Final response
+```
+
+In VoltOps:
+
+- A **trace** is one end-to-end execution.
+- A **span** is one operation inside that execution.
+- Spans are connected by parent-child relationships and rendered as nodes.

website/observability/overview.md

@@ -5,7 +5,9 @@ slug: /
 
 # VoltOps LLM Observability Platform
 
-VoltOps monitors and debugs VoltAgent-based AI applications. It visualizes agent workflows as interactive flowcharts, showing multi-agent interactions, tool usage patterns, and decision flows.
+VoltOps helps you monitor and debug VoltAgent applications by turning executions into visual traces. You can inspect model calls, tool usage, multi-agent hops, logs, and latency from one place.
+
+This Getting Started section is for developers who want to go from setup to the first debuggable trace quickly.
 
 Experience VoltOps in action with [**Live Demo**](https://console.voltagent.dev/demo).
 
@@ -15,10 +17,15 @@ Experience VoltOps in action with [**Live Demo**](https://console.voltagent.dev/
   Your browser does not support the video tag.
 </video>
 
-## Next Steps
+## Why It Matters for AI Agent Builders
+
+- AI agents are non-deterministic; the same prompt can produce different paths. VoltOps helps you see what actually happened in each run.
+- Multi-step flows break in subtle places (model choice, tool inputs, retries, sub-agent delegation). VoltOps shows the exact failing step instead of forcing guesswork.
+- As agent complexity grows, debugging with plain logs becomes slow. Visual traces make root-cause analysis faster and safer in production.
+- Observability also improves iteration speed: you can compare runs, track behavior changes, and validate improvements before broad rollout.
 
-### Getting Started
+## Start Here
 
-- [**Understanding Concepts**](concept) - Learn the core concepts behind VoltOps observability
-- [**Why Observability Matters**](why) - Understand why observability is crucial for AI applications
-- [**Tracing Overview**](tracing/overview) - Deep dive into tracing your AI workflows
+1. [**Setup**](setup) - Connect your VoltAgent app to VoltOps in a few minutes.
+2. [**Mental Model**](mental-model) - Learn how traces, spans, and context map to the UI.
+3. [**Tracing Overview**](tracing/overview) - Continue with full tracing features.

website/observability/setup.md

@@ -2,8 +2,15 @@
 title: Setup
 ---
 
+import StepSection from '@site/src/components/docs-widgets/StepSection';
+
 # Setup
 
+This guide helps you connect a VoltAgent app to VoltOps, verify telemetry quickly, and resolve common setup issues.
+<br/>
+
+<StepSection stepNumber={1} title="Configure Project Keys">
+
 <video controls loop muted playsInline style={{width: '100%', height: 'auto'}}>
 
   <source src="https://cdn.voltagent.dev/docs/voltop-docs/observability-settings.mp4" type="video/mp4" />
@@ -13,31 +20,29 @@ title: Setup
 <br/>
 <br/>
 
-This guide explains how to connect your VoltAgent application to VoltOps for observability.
-
-## Prerequisites
-
-Get your API keys from [console.voltagent.dev/settings/projects](https://console.voltagent.dev/settings/projects).
+Get your project keys from [console.voltagent.dev/settings/projects](https://console.voltagent.dev/settings/projects).
 
 You need two keys:
 
 - **Public Key**: `pk_xxxx`
 - **Secret Key**: `sk_live_xxxx`
 
-## Quick Setup with Environment Variables
+### Add Environment Variables
 
-The simplest way to enable observability is through environment variables. VoltAgent automatically detects these and configures the VoltOps connection:
+VoltAgent auto-detects these variables and connects to VoltOps:
 
 ```bash
 VOLTAGENT_PUBLIC_KEY=pk_xxxx
 VOLTAGENT_SECRET_KEY=sk_live_xxxx
 ```
 
-With these environment variables set, all traces are sent to VoltOps without any code changes.
+No extra observability code is required for the basic path.
 
-## Explicit Configuration with VoltOpsClient
+</StepSection>
 
-For more control, configure the VoltOpsClient directly:
+<StepSection stepNumber={2} title="Configuration">
+
+For more control, configure observability explicitly with `VoltOpsClient`:
 
 ```typescript
 import { VoltAgent, VoltOpsClient } from "@voltagent/core";
@@ -61,9 +66,41 @@ new VoltAgent({
 });
 ```
 
-## Advanced Configuration
+Run one request through your agent, then open [console.voltagent.dev](https://console.voltagent.dev).
+
+If a trace does not appear, first confirm keys belong to the same project, restart after env changes, and check runtime logs for auth/export errors.
+
+</StepSection>
+
+## Advanced Options
+
+### Add Metadata to Traces
+
+Attach IDs so filtering and debugging is easier:
+
+```typescript
+const agent = new Agent({
+  name: "Support Agent",
+  model: openai("gpt-4"),
+  instructions: "Help users with their questions",
+});
+
+await agent.run("Hello", {
+  userId: "user-123",
+  conversationId: "conv-456",
+});
+```
+
+### Context Fields
+
+| Field            | Description                            |
+| ---------------- | -------------------------------------- |
+| `userId`         | Associates traces with a specific user |
+| `conversationId` | Groups traces by conversation          |
+
+### Advanced Observability Configuration
 
-For fine-grained control over observability behavior, use `createVoltAgentObservability`:
+Use `createVoltAgentObservability` for service naming and sampling control:
 
 ```typescript
 import { VoltAgent, createVoltAgentObservability } from "@voltagent/core";
@@ -89,6 +126,11 @@ new VoltAgent({
 });
 ```
 
+Recommended starting point:
+
+- `strategy: "always"` for local development
+- `strategy: "ratio"` in high-traffic production workloads
+
 ### Configuration Options
 
 | Option                             | Type                                               | Default       | Description                                  |
@@ -102,33 +144,9 @@ new VoltAgent({
 | `voltOpsSync.scheduledDelayMillis` | number                                             | 5000          | Delay between exports (ms)                   |
 | `voltOpsSync.exportTimeoutMillis`  | number                                             | 30000         | Export timeout (ms)                          |
 
-## Adding Context to Traces
-
-When running agents, you can add context that appears in VoltOps:
-
-```typescript
-const agent = new Agent({
-  name: "Support Agent",
-  model: openai("gpt-4"),
-  instructions: "Help users with their questions",
-});
-
-await agent.run("Hello", {
-  userId: "user-123",
-  conversationId: "conv-456",
-});
-```
-
-### Context Fields
+### Serverless Runtime
 
-| Field            | Description                            |
-| ---------------- | -------------------------------------- |
-| `userId`         | Associates traces with a specific user |
-| `conversationId` | Groups traces by conversation          |
-
-## Serverless Environments
-
-VoltAgent automatically detects serverless environments (Cloudflare Workers, Vercel Edge, Deno Deploy) and uses an optimized export strategy:
+VoltAgent automatically detects serverless environments (Cloudflare Workers, Vercel Edge, Deno Deploy). For serverless apps, use `serverlessHono`:
 
 ```typescript
 import { VoltAgent, serverlessHono } from "@voltagent/core";
@@ -143,9 +161,3 @@ new VoltAgent({
   }),
 });
 ```
-
-In serverless mode, traces are buffered and exported before the request completes.
-
-## Verifying the Connection
-
-After setup, run your agent and check the [VoltOps console](https://console.voltagent.dev) to see traces appearing in real-time.

website/sidebarsObservability.ts

@@ -8,7 +8,15 @@ const sidebars: SidebarsConfig = {
     {
       type: "category",
       label: "Getting Started",
-      items: ["overview", "setup", "concept", "why"],
+      items: [
+        {
+          type: "doc",
+          id: "overview",
+          label: "Overview",
+        },
+        "setup",
+        "mental-model",
+      ],
     },
     {
       type: "doc",

website/src/css/custom.css

@@ -5339,6 +5339,13 @@ nav.table-of-contents .table-of-contents__link--active,
   max-width: 300px;
 }
 
+/* Hide blog TOC wrapper on <= 1440px. Docs TOC visibility is handled in DocItem/Layout. */
+@media (max-width: 1440px) {
+  .tableOfContents {
+    display: none !important;
+  }
+}
+
 @media (min-width: 1024px) {
   .tableOfContents {
     padding-left: 0.5rem;