diff --git a/agent-os/connect-your-os.mdx b/agent-os/connect-your-os.mdx
index 0a999763a..701f5c6d2 100644
--- a/agent-os/connect-your-os.mdx
+++ b/agent-os/connect-your-os.mdx
@@ -1,12 +1,14 @@
 ---
 title: "Connect Your AgentOS"
-description: "Connect your AgentOS to the control plane for monitoring and management."
+description: "Connect an AgentOS runtime to the Control Plane to manage and monitor it from one web interface."
 ---
 
-## Connect Your AgentOS
+Connect local, staging, and production AgentOS runtimes to the Control Plane. Test registered components, inspect sessions and traces, and manage runtime data from the same interface.
+
+The Control Plane connects directly from your browser to the runtime endpoint.
 
 1. Open [os.agno.com](https://os.agno.com) and sign in
-2. Click **"Add new OS"**
+2. Click **Add new OS**
 
 <Frame>
   <video
@@ -21,7 +23,7 @@ description: "Connect your AgentOS to the control plane for monitoring and manag
   </video>
 </Frame>
 
-## Configure Connection
+## Configure the connection
 
 | Field | Description |
 |-------|-------------|
@@ -30,12 +32,12 @@ description: "Connect your AgentOS to the control plane for monitoring and manag
 | **OS Name** | A descriptive name, e.g. "Development OS" |
 | **Tags** | Optional. Organize with labels like `dev`, `stg`, `prd` |
 
-Click **"CONNECT"**. If successful, your OS appears in the dashboard.
+Click **CONNECT**. If successful, your runtime appears in the dashboard.
 
-## Verify Connection
+## Verify the connection
 
 | Indicator | Expected |
 |-----------|----------|
-| Status | "Running" |
-| Features | Chat, Knowledge, Memory, Sessions accessible |
-| Agents | Configured agents appear in the chat interface |
\ No newline at end of file
+| Status | The runtime shows as running |
+| Components | Registered agents, teams, and workflows appear |
+| Runtime data | Sessions, memory, knowledge, and traces appear when configured |
diff --git a/agent-os/control-plane.mdx b/agent-os/control-plane.mdx
index cf3b64963..5fdaafc22 100644
--- a/agent-os/control-plane.mdx
+++ b/agent-os/control-plane.mdx
@@ -1,9 +1,9 @@
 ---
 title: "AgentOS Control Plane"
-description: "A web interface for testing, monitoring, and managing your multi-agent system."
+description: "Manage and monitor AgentOS runtimes from one web interface."
 ---
 
-The control plane at [os.agno.com](https://os.agno.com) is where you chat with agents, view traces, manage knowledge, track sessions, and monitor performance.
+The AgentOS Control Plane at [os.agno.com](https://os.agno.com) lets you manage and monitor connected AgentOS runtimes. Chat with agents, inspect traces and sessions, manage knowledge and memory, review approvals, and operate schedules from one web interface.
 
 <Frame>
   <img
@@ -15,7 +15,7 @@ The control plane at [os.agno.com](https://os.agno.com) is where you chat with a
 
 <Tip>
 
-It connects directly from your browser to your AgentOS runtime. No data is sent to Agno.
+The Control Plane connects directly from your browser to your AgentOS runtime.
 
 </Tip>
 
diff --git a/agent-os/custom-fastapi/overview.mdx b/agent-os/custom-fastapi/overview.mdx
index faeacfee3..8d104eb5e 100644
--- a/agent-os/custom-fastapi/overview.mdx
+++ b/agent-os/custom-fastapi/overview.mdx
@@ -1,260 +1,165 @@
 ---
-title: Bring Your Own FastAPI App
-sidebarTitle: Overview
-description: Integrate your own FastAPI app with AgentOS.
+title: "Bring Your Own FastAPI App"
+sidebarTitle: "Overview"
+description: "Integrate your own FastAPI app with AgentOS."
 keywords: [fastapi, custom routes, agentos integration, middleware, asgi server, uvicorn, custom app, fastapi app]
 ---
 
-AgentOS is built on FastAPI, which means you can easily integrate your existing FastAPI applications or add custom routes and routers to extend your agent's capabilities.
+AgentOS is built on FastAPI, which means you can integrate your existing FastAPI application, routes, middleware, dependencies, and deployment entrypoints with AgentOS.
 
-## Quick Start
-
-The simplest way to bring your own FastAPI app is to pass it to the AgentOS constructor:
-
-```python
-from fastapi import FastAPI
+```python app.py
 from agno.agent import Agent
 from agno.models.openai import OpenAIResponses
 from agno.os import AgentOS
+from fastapi import FastAPI
 
-# Create your custom FastAPI app
-app = FastAPI(title="My Custom App")
-
-# Add your custom routes
-@app.get("/status")
-async def status_check():
-    return {"status": "healthy"}
-
-# Pass your app to AgentOS
-agent_os = AgentOS(
-    agents=[Agent(id="basic-agent", model=OpenAIResponses(id="gpt-5.2"))],
-    base_app=app  # Your custom FastAPI app
-)
-
-# Get the combined app with both AgentOS and your routes
-app = agent_os.get_app()
-```
-
-<Tip>
-Your custom FastAPI app can have its own middleware and dependencies.
-
-If you have your own CORS middleware, it will be updated to include the AgentOS allowed origins, to make the AgentOS instance compatible with the Control Plane.
-Otherwise, the appropriate CORS middleware will be added to the app.
-</Tip>
-
-### Adding Middleware
-
-You can add any FastAPI middleware to your custom FastAPI app and it will be respected by AgentOS.
+app = FastAPI(title="Product API")
 
-Agno also provides some built-in middleware for common use cases, including authentication.
 
-See the [Middleware](/agent-os/middleware/overview) page for more details.
+@app.get("/account/{account_id}")
+async def get_account(account_id: str):
+    return {"account_id": account_id, "status": "active"}
 
 
-### Running with FastAPI CLI
+support_agent = Agent(
+    id="support-agent",
+    model=OpenAIResponses(id="gpt-5.4"),
+)
 
-AgentOS applications are compatible with the [FastAPI CLI](https://fastapi.tiangolo.com/deployment/manually/) for development.
+agent_os = AgentOS(
+    agents=[support_agent],
+    base_app=app,
+)
 
-First, install the FastAPI CLI:
+app = agent_os.get_app()
 
-```bash Install FastAPI CLI
-uv pip install "fastapi[standard]"
+if __name__ == "__main__":
+    agent_os.serve(app="app:app", reload=True)
 ```
 
-Then run the app:
+The returned app serves both routes:
 
-<CodeGroup>
-
-```bash Run with FastAPI CLI
-fastapi run your_app.py
-```
-
-```bash Run with auto-reload
-fastapi run your_app.py --reload
-```
+| Route | Owner |
+|---|---|
+| `GET /account/{account_id}` | Product API |
+| `POST /agents/support-agent/runs` | AgentOS |
 
-```bash Custom host and port
-fastapi run your_app.py --host 0.0.0.0 --port 8000
-```
-</CodeGroup>
+## Handle Route Conflicts
 
-### Running in Production
+Set `on_route_conflict` when the base application already defines a path and method used by AgentOS.
 
-For production deployments, you can use any ASGI server:
+| Value | Behavior | Use when |
+|---|---|---|
+| `"preserve_agentos"` | AgentOS replaces the conflicting base-app route | AgentOS should own its standard API paths |
+| `"preserve_base_app"` | AgentOS skips the conflicting route | The product route must keep its existing behavior |
+| `"error"` | Application construction raises a `ValueError` | Every conflict should block deployment |
 
-<CodeGroup>
-```bash Uvicorn
-uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
-```
+`"preserve_agentos"` is the default.
 
-```bash Gunicorn with Uvicorn workers
-gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
+```python
+agent_os = AgentOS(
+    agents=[support_agent],
+    base_app=app,
+    on_route_conflict="error",
+)
 ```
 
-```bash FastAPI CLI (Production)
-fastapi run main.py --host 0.0.0.0 --port 8000
-```
-</CodeGroup>
+See [Override Routes](/agent-os/custom-fastapi/override-routes) for conflict examples and matching behavior.
 
+## Keep Existing Application Behavior
 
-## Adding More Routes
+AgentOS prepares the supplied FastAPI app in place:
 
-Register as many routes on your app as you need:
+| Existing behavior | AgentOS behavior |
+|---|---|
+| Routes and routers | Preserved unless they conflict with an AgentOS route |
+| Middleware | Retained on the combined application |
+| FastAPI dependencies | Continue to apply to the routes that declare them |
+| Lifespan | Combined with the lifespan passed to AgentOS |
+| CORS | Existing CORS middleware is updated with AgentOS origins, or AgentOS adds CORS middleware |
 
-```python custom_fastapi_app.py
-from agno.agent import Agent
-from agno.db.sqlite import SqliteDb
-from agno.models.anthropic import Claude
-from agno.os import AgentOS
-from agno.tools.hackernews import HackerNewsTools
-from fastapi import FastAPI
+Use AgentOS [authorization](/agent-os/security/authorization/overview) for runtime access control. Keep product-specific FastAPI dependencies on the custom routes that need them.
 
-# Set up the database
-db = SqliteDb(db_file="tmp/agentos.db")
-
-# Set up the agent
-web_research_agent = Agent(
-    name="Basic Agent",
-    model=Claude(id="claude-sonnet-4-5"),
-    db=db,
-    tools=[HackerNewsTools()],
-    add_history_to_context=True,
-    num_history_runs=3,
-    add_datetime_to_context=True,
-    markdown=True,
-)
+## Add Middleware
 
-# Create custom FastAPI app
-app: FastAPI = FastAPI(
-    title="Custom FastAPI App",
-    version="1.0.0",
-)
+Add FastAPI or Starlette middleware to the base app before calling `get_app()`:
 
-# Add your own routes
-@app.get("/customers")
-async def get_customers():
-    return [
-        {
-            "id": 1,
-            "name": "John Doe",
-            "email": "john.doe@example.com",
-        },
-        {
-            "id": 2,
-            "name": "Jane Doe",
-            "email": "jane.doe@example.com",
-        },
+```python
+from starlette.middleware import Middleware
+from starlette.middleware.trustedhost import TrustedHostMiddleware
+
+app = FastAPI(
+    middleware=[
+        Middleware(
+            TrustedHostMiddleware,
+            allowed_hosts=["api.example.com"],
+        )
     ]
+)
 
-
-# Set up the AgentOS app by passing your FastAPI app
 agent_os = AgentOS(
-    description="Example app with custom routers",
-    agents=[web_research_agent],
+    agents=[support_agent],
     base_app=app,
 )
-
 app = agent_os.get_app()
-
-
-if __name__ == "__main__":
-    """Run the AgentOS application.
-
-    You can see the docs at:
-    http://localhost:7777/docs
-
-    """
-    agent_os.serve(app="custom_fastapi_app:app", reload=True)
 ```
 
-Run it end to end:
-
-<Steps>
-  <Snippet file="create-venv-step.mdx" />
-
-  <Step title="Set environment variables">
-    ```bash
-    export ANTHROPIC_API_KEY=your_anthropic_api_key
-    ```
-  </Step>
+See [AgentOS Middleware](/agent-os/middleware/overview) for JWT validation, request context, logging, and custom middleware.
 
-  <Step title="Install dependencies">
-    ```bash
-    uv pip install -U agno anthropic openai fastapi uvicorn sqlalchemy
-    ```
-  </Step>
+## Combine Lifespans
 
-  <Step title="Run the example">
-    ```bash
-    python custom_fastapi_app.py
-    ```
-  </Step>
-</Steps>
-
-
-## Middleware and Dependencies
-
-You can add middleware and dependencies to your custom FastAPI app:
+Pass a lifespan to AgentOS when the runtime needs its own startup and shutdown work. AgentOS wraps the lifespan already configured on the base app.
 
 ```python
-from agno.agent import Agent
-from agno.models.openai import OpenAIResponses
-from agno.os import AgentOS
-from fastapi import FastAPI, Depends, HTTPException
-from fastapi.middleware.cors import CORSMiddleware
-from fastapi.security import HTTPBearer
-
-app = FastAPI()
-
-# Add CORS middleware
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["https://yourdomain.com"],
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
+from contextlib import asynccontextmanager
 
-# Security dependency
-security = HTTPBearer()
 
-async def verify_token(token: str = Depends(security)):
-    if token.credentials != "your-secret-token":
-        raise HTTPException(status_code=401, detail="Invalid token")
-    return token
+@asynccontextmanager
+async def agent_os_lifespan(app):
+    app.state.runtime_status = "ready"
+    yield
+    app.state.runtime_status = "stopped"
 
-# Protected route
-@app.get("/protected", dependencies=[Depends(verify_token)])
-async def protected_endpoint():
-    return {"message": "Access granted"}
 
-# Integrate with AgentOS
 agent_os = AgentOS(
-    agents=[Agent(id="basic-agent", model=OpenAIResponses(id="gpt-5.2"))],
-    base_app=app
+    agents=[support_agent],
+    base_app=app,
+    lifespan=agent_os_lifespan,
 )
 
 app = agent_os.get_app()
 ```
 
-## Access AgentOS Routes
+See [Custom Lifespan](/agent-os/lifespan) for a complete example.
 
-You can programmatically access and inspect the routes added by AgentOS:
+## Run the Combined App
 
-```python
-agent_os = AgentOS(agents=[agent])
-app = agent_os.get_app()
+Install the AgentOS and FastAPI CLI dependencies:
+
+```bash
+uv pip install -U "agno[os]" openai "fastapi[standard]"
+```
 
-# Get all routes
-routes = agent_os.get_routes()
+<CodeGroup>
+```bash Development
+fastapi dev app.py
+```
 
-for route in routes:
-    print(f"Route: {route.path}")
-    if hasattr(route, 'methods'):
-        print(f"Methods: {route.methods}")
+```bash Production
+fastapi run app.py --host 0.0.0.0 --port 8000
 ```
 
-## Developer Resources
+```bash Uvicorn
+uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4
+```
+</CodeGroup>
+
+## Next Steps
 
-- [AgentOS Reference](/reference/agent-os/agent-os)
-- [FastAPI Documentation](https://fastapi.tiangolo.com/)
+| Task | Guide |
+|---|---|
+| Resolve path and method conflicts | [Override Routes](/agent-os/custom-fastapi/override-routes) |
+| Add authentication and request middleware | [AgentOS Middleware](/agent-os/middleware/overview) |
+| Configure runtime authorization | [Authorization](/agent-os/security/authorization/overview) |
+| Run startup and shutdown logic | [Custom Lifespan](/agent-os/lifespan) |
+| Review `base_app` parameters | [AgentOS class reference](/reference/agent-os/agent-os) |
diff --git a/agent-os/interfaces/overview.mdx b/agent-os/interfaces/overview.mdx
index 545056fb8..45b1d7d97 100644
--- a/agent-os/interfaces/overview.mdx
+++ b/agent-os/interfaces/overview.mdx
@@ -1,74 +1,102 @@
 ---
 title: "Interfaces"
 sidebarTitle: "Overview"
-description: "Expose Agno agents through various communication protocols and platforms"
+description: "Expose agents, teams, and workflows through product frontends, messaging platforms, and agent protocols."
 keywords: [interfaces, a2a, ag-ui, slack, whatsapp, telegram, protocols, integration]
 ---
 
-Interfaces enable exposing Agno agents, teams, and workflows through various communication protocols and platforms. Each interface provides a standardized way to connect Agno agents to external systems, messaging platforms, and frontend applications.
-
-## Available Interfaces
-
-<CardGroup cols={2}>
-  <Card
-    title="AG-UI"
-    icon="desktop"
-    href="/agent-os/interfaces/ag-ui/introduction"
-  >
-    Connect agents to frontend applications using the Agent-User Interaction Protocol
-  </Card>
-  <Card
-    title="Slack"
-    icon="slack"
-    href="/agent-os/interfaces/slack/introduction"
-  >
-    Deploy agents as Slack applications for team collaboration
-  </Card>
-  <Card
-    title="WhatsApp"
-    icon="whatsapp"
-    href="/agent-os/interfaces/whatsapp/introduction"
-  >
-    Serve agents via WhatsApp for direct messaging interactions
-  </Card>
-  <Card
-    title="Telegram"
-    icon="telegram"
-    href="/agent-os/interfaces/telegram/introduction"
-  >
-    Deploy agents as Telegram bots for direct and group chat conversations
-  </Card>
-  <Card
-    title="A2A"
-    icon="code"
-    href="/agent-os/interfaces/a2a/introduction"
-  >
-    Expose agents via the Agent-to-Agent Protocol for inter-agent communication
-  </Card>
-</CardGroup>
+Product teams use interfaces to place agents in the channel where users already work. Mount AG-UI for a product frontend, Slack or Telegram for conversations, WhatsApp for customer messaging, or A2A for agent-to-agent calls.
+
+```python slack_agent.py
+from agno.agent import Agent
+from agno.models.openai import OpenAIResponses
+from agno.os import AgentOS
+from agno.os.interfaces.slack import Slack
+
+support_agent = Agent(
+    id="support-agent",
+    model=OpenAIResponses(id="gpt-5.4"),
+)
+
+agent_os = AgentOS(
+    agents=[support_agent],
+    interfaces=[Slack(agent=support_agent)],
+)
+
+app = agent_os.get_app()
+```
+
+The Slack interface mounts its webhook routes on the AgentOS application and routes each conversation to `support_agent`.
+
+## Choose an Interface
+
+| Interface | Use when | Components |
+|---|---|---|
+| [AG-UI](/agent-os/interfaces/ag-ui/introduction) | A web or mobile frontend speaks the Agent-User Interaction Protocol | Agents, teams |
+| [Slack](/agent-os/interfaces/slack/introduction) | Teams use an agent in channels, direct messages, and threads | Agents, teams, workflows |
+| [Telegram](/agent-os/interfaces/telegram/introduction) | Users reach an agent through direct messages or group chats | Agents, teams, workflows |
+| [WhatsApp](/agent-os/interfaces/whatsapp/introduction) | Customers interact with an agent through WhatsApp Business | Agents, teams, workflows |
+| [A2A](/agent-os/interfaces/a2a/introduction) | Other agent systems call AgentOS through the Agent-to-Agent Protocol | Agents, teams, workflows |
+
+<Note>
+Discord uses the standalone `DiscordClient` integration from `agno.integrations.discord`. See the [Discord guide](/agent-os/interfaces/discord/introduction).
+</Note>
 
 ## How Interfaces Work
 
-Interfaces are FastAPI routers that mount protocol-specific endpoints on an AgentOS instance. Each interface:
+Each interface mounts a FastAPI router on AgentOS and translates between the external protocol and an Agent, Team, or Workflow.
+
+| Responsibility | Behavior |
+|---|---|
+| Request handling | Parse platform events or protocol messages into Agno run input |
+| Session routing | Map the external user and conversation to AgentOS user and session IDs |
+| Streaming | Translate run events into the format supported by the client |
+| Media | Pass supported files, images, audio, and video to the component |
+| Responses | Return text, generated media, progress, and human-in-the-loop state through the interface |
+
+Support varies by interface. Use each interface guide for its events, media types, and response behavior.
+
+## Authentication
 
-- Wraps Agno agents, teams, or workflows into protocol-compatible endpoints
-- Handles authentication and request validation for the target platform
-- Manages session tracking and context preservation
-- Streams responses back to clients in the appropriate format
+Messaging platforms authenticate their own webhook routes. Protocol interfaces follow the AgentOS authentication mode and scope mappings.
 
-## Using Interfaces
+| Interface | Request verification |
+|---|---|
+| Slack | Slack signing secret |
+| Telegram | Telegram webhook secret token |
+| WhatsApp | Meta webhook signature using the WhatsApp app secret |
+| AG-UI | AgentOS bearer authentication and run scopes when configured |
+| A2A | AgentOS bearer authentication and resource scopes when configured |
 
-Interfaces are added to an AgentOS instance through the `interfaces` parameter:
+The regular AgentOS REST routes continue to use the runtime's configured [authentication and authorization](/agent-os/security/overview).
+
+## Mount Multiple Interfaces
+
+One AgentOS application can expose the same component through several interfaces:
 
 ```python
-from agno.os import AgentOS
+from agno.os.interfaces.agui import AGUI
 from agno.os.interfaces.slack import Slack
 
 agent_os = AgentOS(
-    agents=[my_agent],
-    interfaces=[Slack(agent=my_agent)],
+    agents=[support_agent],
+    interfaces=[
+        AGUI(agent=support_agent),
+        Slack(agent=support_agent),
+    ],
 )
+
 app = agent_os.get_app()
 ```
 
-Multiple interfaces can be added to a single AgentOS instance, allowing the same agents to be exposed through different protocols simultaneously.
+The agent keeps one implementation while each interface owns protocol handling, routing, and response formatting.
+
+## Next Steps
+
+| Task | Guide |
+|---|---|
+| Connect a product frontend | [AG-UI](/agent-os/interfaces/ag-ui/introduction) |
+| Build a workplace agent | [Slack](/agent-os/interfaces/slack/introduction) |
+| Serve a messaging bot | [Telegram](/agent-os/interfaces/telegram/introduction) |
+| Reach customers on WhatsApp | [WhatsApp](/agent-os/interfaces/whatsapp/introduction) |
+| Expose agents to other agent systems | [A2A](/agent-os/interfaces/a2a/introduction) |
diff --git a/agent-os/introduction.mdx b/agent-os/introduction.mdx
index a8bc38b87..e23f98959 100644
--- a/agent-os/introduction.mdx
+++ b/agent-os/introduction.mdx
@@ -1,20 +1,14 @@
 ---
 title: "What is AgentOS?"
 sidebarTitle: "Introduction"
-description: "The runtime for your agent platform."
+description: "Run agents, teams, and workflows using a FastAPI application with persistence, authorization, and observability."
 ---
 
-**AgentOS is a FastAPI app that turns your agents into a platform.** It's a backend service that:
+**AgentOS is the runtime for your agent platform.**
 
-1. Runs agents via REST API, MCP, or interfaces like Slack, WhatsApp and Telegram.
-2. Maintains long-running stateful sessions that last from minutes to days to weeks.
-3. Is durable across restarts, replicas, and infrastructure failures.
-4. Is secure against unauthenticated access.
-5. Logs, traces and audits every run and action.
+Product and platform teams use AgentOS to serve agents, teams, and workflows through REST, MCP, and interfaces such as Slack, WhatsApp, and Telegram. The same API covers runs, sessions, memory, knowledge, evaluations, approvals, and schedules.
 
-Build your agents using the [Agno SDK](/sdk/introduction). Run them using the AgentOS runtime.
-
-Here's the smallest possible AgentOS:
+Build your system with the Agno SDK. Run it with AgentOS. Manage and monitor it with the Control Plane.
 
 ```python agno_assist.py
 from agno.agent import Agent
@@ -22,34 +16,39 @@ from agno.db.sqlite import SqliteDb
 from agno.models.anthropic import Claude
 from agno.os import AgentOS
 
+db = SqliteDb(db_file="agno.db")
+
 agent = Agent(
     name="Agno Assist",
     model=Claude(id="claude-sonnet-4-5"),
-    db=SqliteDb(db_file="agno.db"),
+    db=db,
 )
 
-agent_os = AgentOS(agents=[agent])
+agent_os = AgentOS(agents=[agent], db=db)
 app = agent_os.get_app()
 ```
 
-## Key Features
-
-- **Production API**: 50+ ready to use endpoints with SSE-compatible streaming.
-- **Data Ownership**: Sessions, memory, knowledge, and traces stored in your database.
-- **Request Isolation**: No state bleed between users, agents, or sessions.
-- **Security**: JWT-based RBAC with hierarchical scopes.
-- **Observability**: Traces stored in your database with no third-party egress or vendor lock-in.
-- **Governance**: Guardrails, human-in-the-loop, and approval flows for full control.
-- **Multi-framework**: Serve agents built with the Claude Agent SDK, LangGraph and DSPy alongside native Agno agents. See [Multi-Framework Support](/agent-os/multi-framework/overview).
+## What AgentOS gives you
 
-## Architecture
+| Need | AgentOS capability |
+|------|--------------------|
+| Product API | 80+ REST endpoints for running agents and managing sessions, memory, knowledge, traces, evaluations, schedules, and approvals |
+| Persistent state | Sessions, memory, knowledge, and runtime data stored in databases you configure |
+| Long-running work | Streaming, background execution, run cancellation, and persisted run history |
+| Operations | Metrics, evaluations, opt-in tracing, approvals, schedules, and component versions |
+| Interfaces | REST, SSE, MCP, A2A, AG-UI, Slack, Telegram, and WhatsApp |
+| Access control | JWT authorization with RBAC, a shared security key, and scoped service accounts |
+| Framework support | Native Agno components plus adapters for the Claude Agent SDK, LangGraph, DSPy, and Antigravity |
 
-AgentOS has two parts:
+## Build, run, and manage
 
-1. **Runtime**: A FastAPI service that runs agents, teams, and workflows.
-2. **Control plane**: A UI for managing, monitoring, and debugging your system.
+| Layer | Role |
+|-------|------|
+| **SDK** | Build agents, teams, and workflows with memory, knowledge, guardrails, and 100+ integrations |
+| **AgentOS** | Run your agent platform in production with a stateless, secure FastAPI backend |
+| **Control Plane** | Manage and monitor AgentOS runtimes from one web interface |
 
-The runtime exposes the APIs that power both the control plane and your AI products. The runtime can serve agents built with the [Agno SDK](/sdk/introduction), the [Claude Agent SDK, LangGraph, or DSPy](/agent-os/multi-framework/overview).
+The runtime exposes the APIs that power the Control Plane and your products.
 
 <img
   className="block dark:hidden"
@@ -63,41 +62,25 @@ The runtime exposes the APIs that power both the control plane and your AI produ
   alt="AgentOS Architecture"
 />
 
-## Private by Design
-
-Most AI tooling stores your data on their servers. You pay retention costs, deal with egress fees, and depend on their security. AgentOS runs entirely in your infrastructure: the runtime runs as a container in your cloud, and the [control plane](/agent-os/control-plane) connects directly from your browser. No proxies. No data relays.
-
-- **Your database**: Sessions, memory, knowledge, traces. All stored where you control it.
-- **Zero transmission**: No conversations, logs, or metrics sent to Agno.
-- **From browser to runtime**: The control plane connects from your browser to the runtime. Agno stores no data except for your runtime endpoint. All data resides in your database.
+## Your runtime, your data
 
-See [AgentOS Security](/agent-os/security/overview) for more details.
+AgentOS runs in your infrastructure and writes runtime state to databases you configure. The Control Plane connects directly from your browser to the runtime endpoint.
 
-<Frame>
-  <img
-    src="/images/agentos-secure-infra-illustration.png"
-    alt="AgentOS Security and Privacy Architecture"
-    style={{ borderRadius: "0.5rem" }}
-  />
-</Frame>
+Model providers, tools, telemetry, and other external services follow the configuration of your application. See [Security & Auth](/agent-os/security/overview) for authentication modes, service accounts, and endpoint permissions.
 
-## Next Steps
+## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Run Your First AgentOS" icon="plus" href="/agent-os/run-your-os">
-    Initialize and serve a basic agent.
+  <Card title="Run your first AgentOS" icon="plus" href="/agent-os/run-your-os">
+    Serve an agent through FastAPI and inspect its local API.
   </Card>
-  <Card
-    title="Connect AgentOS to UI"
-    icon="link"
-    href="/agent-os/connect-your-os"
-  >
-    Manage AgentOS using a Web UI.
+  <Card title="Connect the Control Plane" icon="link" href="/agent-os/connect-your-os">
+    Manage and monitor a local or deployed runtime.
   </Card>
-  <Card title="Control Plane" icon="desktop" href="/agent-os/control-plane">
-    Inspect sessions and debug traces.
+  <Card title="Use the API" icon="server" href="/agent-os/using-the-api">
+    Run components and manage runtime data over REST.
   </Card>
-  <Card title="Learn More" icon="book" href="/agent-os/overview">
-    Parameter reference and configuration options for the AgentOS class.
+  <Card title="Secure your runtime" icon="shield-halved" href="/agent-os/security/overview">
+    Configure authentication, permissions, and user isolation.
   </Card>
 </CardGroup>
diff --git a/agent-os/overview.mdx b/agent-os/overview.mdx
index 79582e8f7..c182a4832 100644
--- a/agent-os/overview.mdx
+++ b/agent-os/overview.mdx
@@ -1,124 +1,95 @@
 ---
-title: "Overview"
-description: "The production runtime and control plane for your agentic systems."
+title: "AgentOS Runtime"
+sidebarTitle: "Runtime"
+description: "Configure the FastAPI runtime that serves your agents, teams, and workflows."
 ---
 
-AgentOS transforms your agents into a production-ready API.
+Platform teams use AgentOS to serve agents, teams, and workflows through one FastAPI application. The runtime provides execution APIs, persistent state, authorization, tracing, and operational endpoints.
 
-A minimal application looks like this:
-
-```python my_os.py
+```python agent_os.py
+from agno.agent import Agent
+from agno.db.sqlite import SqliteDb
+from agno.models.openai import OpenAIResponses
 from agno.os import AgentOS
 
+db = SqliteDb(db_file="tmp/agentos.db")
+
+assistant = Agent(
+    id="assistant",
+    model=OpenAIResponses(id="gpt-5.4"),
+)
+
 agent_os = AgentOS(
-    name="My AgentOS",
-    agents=[my_agent],
-    teams=[my_team],
-    workflows=[my_workflow],
-    tracing=True
+    id="product-agent-os",
+    agents=[assistant],
+    db=db,
+    tracing=True,
 )
 
 app = agent_os.get_app()
 
 if __name__ == "__main__":
-    agent_os.serve(app="my_os:app", reload=True)
+    agent_os.serve(app="agent_os:app", reload=True)
 ```
 
-## Parameters
-
-| Parameter                 | Type                     | Default | Description                                                    |
-| ------------------------- | ------------------------ | ------- | -------------------------------------------------------------- |
-| `id`                      | `str`                    | `None`  | Unique instance ID. Generated from `name` or a UUID when unset |
-| `name`                    | `str`                    | `None`  | AgentOS name                                                   |
-| `description`             | `str`                    | `None`  | AgentOS description                                            |
-| `version`                 | `str`                    | `None`  | AgentOS version                                                |
-| `agents`                  | `List[Agent]`            | `None`  | Agents to include                                              |
-| `teams`                   | `List[Team]`             | `None`  | Teams to include                                               |
-| `workflows`               | `List[Workflow]`         | `None`  | Workflows to include                                           |
-| `db`                      | `BaseDb` or `AsyncBaseDb` | `None`  | Database used for the AgentOS                                  |
-| `checkpoint`              | `str`                    | `None`  | Default checkpoint level for agents without their own: `"runs"`, `"tool-batch"`, or `"tools"` |
-| `tracing`                 | `bool`                   | `False` | Enable tracing to AgentOS `db`                                 |
-| `knowledge`               | `List[Knowledge]`        | `None`  | Knowledge bases                                                |
-| `interfaces`              | `List[BaseInterface]`    | `None`  | Agent interfaces ([docs](/agent-os/interfaces/overview))                |
-| `a2a_interface`           | `bool`                   | `False` | Expose agents and teams over an A2A server ([docs](/agent-os/interfaces/a2a/introduction)) |
-| `config`                  | `str` or `AgentOSConfig` | `None`  | Configuration path or object ([docs](/agent-os/config))        |
-| `settings`                | `AgnoAPISettings`        | `None`  | API settings for the OS                                        |
-| `base_app`                | `FastAPI`                | `None`  | Custom FastAPI app ([docs](/agent-os/custom-fastapi/overview)) |
-| `on_route_conflict`       | `str`                    | `"preserve_agentos"` | Route conflict handling with a custom `base_app`: `"preserve_agentos"`, `"preserve_base_app"`, or `"error"` |
-| `lifespan`                | `Any`                    | `None`  | Lifespan context manager ([docs](/agent-os/lifespan))          |
-| `authorization`           | `bool`                   | `False` | Enable authorization ([docs](/agent-os/security/authorization/overview))                  |
-| `authorization_config`    | `AuthorizationConfig`    | `None`  | JWT verification config                                        |
-| `mcp_server`              | `bool` or `MCPServerConfig` | `False` | Enable MCP server ([docs](/agent-os/mcp/mcp))               |
-| `mcp_auth`                | `AuthProvider`           | `None`  | Auth provider for the MCP endpoint (OAuth for connector clients). Requires `mcp_server` |
-| `cors_allowed_origins`    | `List[str]`              | `None`  | Allowed CORS origins                                           |
-| `auto_provision_dbs`      | `bool`                   | `True`  | Auto-provision databases                                       |
-| `run_hooks_in_background` | `bool`                   | `False` | Run hooks in background                                        |
-| `telemetry`               | `bool`                   | `True`  | Enable telemetry                                               |
-| `registry`                | `Registry`               | `None`  | Component registry for the OS ([docs](/agent-os/studio/registry)) |
-| `scheduler`               | `bool`                   | `False` | Enable the cron scheduler ([docs](/agent-os/scheduler/overview)) |
-| `scheduler_poll_interval` | `int`                    | `15`    | Seconds between scheduler poll cycles                          |
-| `scheduler_base_url`      | `str`                    | `None`  | Base URL for scheduler HTTP calls. Falls back to `http://127.0.0.1:7777` |
-| `internal_service_token`  | `str`                    | `None`  | Token for scheduler-to-OS auth. Auto-generated when the scheduler is enabled |
-
-See [AgentOS class reference](/reference/agent-os/agent-os) for details.
-
-## Methods
-
-### `get_app()`
-
-Returns the configured FastAPI application.
-
-### `serve()`
-
-Starts the AgentOS server.
-
-| Parameter | Type               | Default     | Description                         |
-| --------- | ------------------ | ----------- | ----------------------------------- |
-| `app`     | `str` or `FastAPI` | Required    | FastAPI app instance or module path |
-| `host`    | `str`              | `localhost` | Host to bind                        |
-| `port`    | `int`              | `7777`      | Port to bind                        |
-| `workers` | `int`              | `None`      | Number of workers                   |
-| `reload`  | `bool`             | `False`     | Enable auto-reload                  |
-
-#### Environment variable overrides
-
-`serve()` reads `AGENT_OS_HOST` and `AGENT_OS_PORT` from the environment. When set, they override the `host` and `port` arguments.
-
-| Environment Variable | Overrides | Default     |
-| -------------------- | --------- | ----------- |
-| `AGENT_OS_HOST`      | `host`    | `localhost` |
-| `AGENT_OS_PORT`      | `port`    | `7777`      |
-
-Precedence: environment variable > explicit argument > default value.
-
-This is useful for containerized deployments where host and port are configured externally:
+The AgentOS database becomes the default for local agents, teams, and workflows that do not define their own database. In this example it stores the agent's sessions and the runtime's traces.
 
-```bash
-# In your Dockerfile or orchestrator config
-ENV AGENT_OS_HOST=0.0.0.0
-ENV AGENT_OS_PORT=8000
-```
+## Choose Runtime Capabilities
 
-```python my_os.py
-# No host/port needed. serve() reads from AGENT_OS_HOST and AGENT_OS_PORT.
-if __name__ == "__main__":
-    agent_os.serve(app="my_os:app", reload=True)
-```
+Add capabilities as the application needs them:
 
-### `resync(app)`
+| Requirement | AgentOS configuration | Guide |
+|---|---|---|
+| Serve agents, teams, and workflows | `agents`, `teams`, `workflows` | [Using the API](/agent-os/using-the-api) |
+| Use a shared default database | `db` | [Database](/database/overview) |
+| Require JWT authorization | `authorization=True` | [Authorization](/agent-os/security/authorization/overview) |
+| Store execution traces | `tracing=True` | [Tracing](/agent-os/tracing/overview) |
+| Expose an MCP server | `mcp_server=True` | [AgentOS as MCP Server](/agent-os/mcp/mcp) |
+| Mount product and messaging interfaces | `interfaces=[...]` | [Interfaces](/agent-os/interfaces/overview) |
+| Run cron schedules | `scheduler=True` | [Scheduler](/agent-os/scheduler/overview) |
+| Extend an existing FastAPI application | `base_app=app` | [Bring Your Own FastAPI App](/agent-os/custom-fastapi/overview) |
 
-Reloads agents, teams, workflows, and resources on the given FastAPI app.
+## Database Behavior
 
-## Configuration
+| Configuration | Behavior |
+|---|---|
+| Set `db` on AgentOS | Components without a database inherit the AgentOS database |
+| Set a database on a component | That component keeps its own database |
+| Set `db` and `tracing=True` | AgentOS stores all traces in the AgentOS database |
+| Omit `db` with `tracing=True` | AgentOS uses the first component database it discovers |
+| Keep `auto_provision_dbs=True` | AgentOS creates the required tables when the application starts |
 
-The `config` parameter accepts a YAML path or `AgentOSConfig` object. Use it to configure prompts, display names, and database settings.
+Set an explicit AgentOS database when the runtime manages several component databases. This gives tracing, service accounts, and scheduled jobs a predictable store.
 
-```python
-agent_os = AgentOS(
-    name="My AgentOS",
-    agents=[my_agent],
-    config="config.yaml",  # or AgentOSConfig(...)
-)
+## Runtime Methods
+
+| Method | Purpose |
+|---|---|
+| `get_app()` | Build and return the configured FastAPI application |
+| `serve()` | Start the application with Uvicorn |
+| `get_routes()` | Return the FastAPI routes mounted by AgentOS |
+| `resync(app)` | Discover, initialize, and configure agents, teams, workflows, databases, and knowledge on an existing app |
+
+### Host and Port
+
+`serve()` reads `AGENT_OS_HOST` and `AGENT_OS_PORT`. Environment variables take precedence over method arguments.
+
+| Setting | Default |
+|---|---|
+| `AGENT_OS_HOST` | `localhost` |
+| `AGENT_OS_PORT` | `7777` |
+
+```bash
+export AGENT_OS_HOST=0.0.0.0
+export AGENT_OS_PORT=8000
+python agent_os.py
 ```
 
-See [Configuration](/agent-os/config) for details.
+## Next Steps
+
+| Task | Guide |
+|---|---|
+| Call the runtime from an application | [Using the API](/agent-os/using-the-api) |
+| Add AgentOS to an existing backend | [Bring Your Own FastAPI App](/agent-os/custom-fastapi/overview) |
+| Configure the Control Plane experience | [AgentOS Configuration](/agent-os/config) |
+| Review every constructor parameter | [AgentOS class reference](/reference/agent-os/agent-os) |
diff --git a/agent-os/run-your-os.mdx b/agent-os/run-your-os.mdx
index c90efa727..2cc65c1ab 100644
--- a/agent-os/run-your-os.mdx
+++ b/agent-os/run-your-os.mdx
@@ -1,6 +1,6 @@
 ---
-title: "Run Your AgentOS"
-description: "Run a local AgentOS in a few lines of code."
+title: "Run Your First AgentOS"
+description: "Serve an agent through FastAPI with persistent sessions and a local REST API."
 ---
 
 Save the following code to `agno_assist.py`:
@@ -11,13 +11,15 @@ from agno.db.sqlite import SqliteDb
 from agno.models.anthropic import Claude
 from agno.os import AgentOS
 
+db = SqliteDb(db_file="agno.db")
+
 agent = Agent(
     name="Agno Assist",
     model=Claude(id="claude-sonnet-4-5"),
-    db=SqliteDb(db_file="agno.db"),
+    db=db,
 )
 
-agent_os = AgentOS(agents=[agent])
+agent_os = AgentOS(agents=[agent], db=db)
 app = agent_os.get_app()
 
 if __name__ == "__main__":
@@ -26,11 +28,11 @@ if __name__ == "__main__":
 
 <Check>
 
-An Agent served as a FastAPI application with persistent sessions.
+Your agent now has a FastAPI API and persistent sessions.
 
 </Check>
 
-## Run Your AgentOS
+## Run it locally
 
 <Steps>
   <Step title="Set up your virtual environment">
@@ -57,8 +59,8 @@ An Agent served as a FastAPI application with persistent sessions.
     ```bash Mac
     export ANTHROPIC_API_KEY=sk-***
     ```
-    ```bash Windows
-    setx ANTHROPIC_API_KEY sk-***
+    ```powershell Windows
+    $env:ANTHROPIC_API_KEY = "sk-***"
     ```
     </CodeGroup>
   </Step>
@@ -74,10 +76,20 @@ Your AgentOS is now running at `http://localhost:7777`.
 
 | Endpoint | Description |
 |----------|-------------|
-| `http://localhost:7777` | Connect to the control plane |
+| `http://localhost:7777/health` | Runtime health check |
 | `http://localhost:7777/docs` | Interactive API documentation |
-| `http://localhost:7777/config` | View AgentOS configuration |
+| `http://localhost:7777/info` | Runtime information and registered component counts |
+| `http://localhost:7777/config` | Registered components and runtime capabilities |
+
+Use `http://localhost:7777` as the endpoint when connecting this runtime to the Control Plane.
+
+This local quickstart runs without authentication. Configure [Security & Auth](/agent-os/security/overview) before deploying it.
 
-To manage your AgentOS in a UI, head to [os.agno.com](https://os.agno.com) and connect this runtime. See [Connect Your AgentOS](/agent-os/connect-your-os) for the steps.
+## Next steps
 
-For the full list of endpoints AgentOS exposes, see the [AgentOS API reference](/reference-api/overview).
+| Task | Guide |
+|------|-------|
+| Manage and monitor the runtime | [Connect Your AgentOS](/agent-os/connect-your-os) |
+| Call agents through REST | [Using the API](/agent-os/using-the-api) |
+| Explore every endpoint | [AgentOS API reference](/reference-api/overview) |
+| Protect the runtime | [Security & Auth](/agent-os/security/overview) |
diff --git a/agent-os/tracing/overview.mdx b/agent-os/tracing/overview.mdx
index aaf4d58cc..fd4eed2a8 100644
--- a/agent-os/tracing/overview.mdx
+++ b/agent-os/tracing/overview.mdx
@@ -1,173 +1,141 @@
 ---
-title: Tracing
-description: Configure tracing for agents, teams, and workflows in AgentOS.
-sidebarTitle: Overview
+title: "Tracing"
+sidebarTitle: "Overview"
+description: "Store AgentOS traces to inspect run behavior, latency, errors, model calls, and tool calls."
 keywords: [tracing, agentos, observability, debugging]
 ---
 
-Set `tracing=True` on `AgentOS` to record agent, team, workflow, model, and tool spans in a database. View stored traces in the [AgentOS UI](https://os.agno.com/traces).
+Engineering teams use tracing to diagnose failed runs, slow tools, and unexpected model behavior. Set `tracing=True` to record AgentOS execution spans in a database.
 
-<Note>
-For a comprehensive introduction to Agno Tracing concepts (traces, spans, and what gets captured), see the [Tracing Overview](/tracing/overview).
-</Note>
-
-## Prerequisites
-
-Install the required packages:
-
-```bash
-uv pip install -U "agno[os]" openai opentelemetry-api opentelemetry-sdk openinference-instrumentation-agno ddgs
-export OPENAI_API_KEY=***
-```
-
-## Database Configuration
-
-How you configure tracing depends on your database setup:
-
-| Scenario | Configuration | Where Traces Are Stored |
-|----------|---------------|------------------------|
-| Single shared database | `tracing=True` | The shared database |
-| Multiple databases | `tracing=True` + `db=...` | The dedicated `db` |
-| No `db` specified | `tracing=True` | First database found (not recommended) |
-
-<Note>
-We recommend a separate, dedicated database for traces. It keeps them all in one place, which makes them easier to query and analyze.
-</Note>
-
-## Single Database Setup
-
-If all your agents and teams share the **same database instance**, enabling tracing is simple:
-
-```python
+```python traced_agent_os.py
 from agno.agent import Agent
 from agno.db.sqlite import SqliteDb
 from agno.models.openai import OpenAIResponses
 from agno.os import AgentOS
 
-# Single shared database for everything
-db = SqliteDb(db_file="tmp/agno.db")
+db = SqliteDb(db_file="tmp/agentos.db")
 
-agent = Agent(
-    name="Research Agent",
-    model=OpenAIResponses(id="gpt-5.2"),
-    db=db,  # Uses shared db
+research_agent = Agent(
+    id="research-agent",
+    model=OpenAIResponses(id="gpt-5.4"),
 )
 
-# Enable tracing - traces stored in the shared db
 agent_os = AgentOS(
-    agents=[agent],
+    agents=[research_agent],
     db=db,
-    tracing=True,  # Traces go to the shared db
+    tracing=True,
 )
 
 app = agent_os.get_app()
+
+if __name__ == "__main__":
+    agent_os.serve(app="traced_agent_os:app", reload=True)
 ```
 
-In this setup, traces are automatically stored in the shared database alongside sessions and other data.
+The AgentOS database stores the agent's sessions and its traces. View traces in the [AgentOS Control Plane](https://os.agno.com/traces) or query them through the AgentOS API.
+
+## What Tracing Captures
+
+| Span | What you can inspect |
+|---|---|
+| Agent, team, and workflow runs | Input, output, status, duration, and child operations |
+| Model calls | Model execution within a run |
+| Tool calls | Tool name, execution timing, result, and errors |
+| Team coordination | Calls made while the team delegates or coordinates |
+| Workflow steps | Execution order and duration for each step |
+
+AgentOS uses OpenTelemetry instrumentation and stores the resulting traces in an Agno database.
 
-## Multiple Databases Setup
+## Choose a Trace Database
 
-<Warning>
-  When agents or teams have **different databases**, it is highly recommended that you specify a dedicated `db` to ensure all traces are stored in one central location.
-</Warning>
+| Runtime setup | Configuration | Trace location |
+|---|---|---|
+| Components share one database | `db=shared_db, tracing=True` | Shared AgentOS database |
+| Components use separate databases | `db=trace_db, tracing=True` | Dedicated AgentOS database |
+| AgentOS has no `db` | `tracing=True` | First component database discovered |
 
-If you have multiple agents with their own databases, traces need a dedicated database:
+Set `db` explicitly when the runtime contains components with different databases. Component order determines the fallback database when AgentOS has no database of its own.
+
+## Use a Dedicated Trace Database
+
+Give each component its application database and pass the trace database to AgentOS:
 
 ```python
 from agno.agent import Agent
 from agno.db.sqlite import SqliteDb
 from agno.models.openai import OpenAIResponses
 from agno.os import AgentOS
-from agno.tools.hackernews import HackerNewsTools
-from agno.tools.websearch import WebSearchTools
-
-# Each agent has its own database
-agent1_db = SqliteDb(db_file="tmp/agent1.db", id="agent1_db")
-agent2_db = SqliteDb(db_file="tmp/agent2.db", id="agent2_db")
-
-# Dedicated database for traces (separate from agent databases)
-db = SqliteDb(db_file="tmp/traces.db", id="traces_db")
-
-# Agent 1 with its own database
-hackernews_agent = Agent(
-    name="HackerNews Agent",
-    model=OpenAIResponses(id="gpt-5.2"),
-    tools=[HackerNewsTools()],
-    db=agent1_db,
-)
 
-# Agent 2 with its own database
-search_agent = Agent(
-    name="Search Agent",
-    model=OpenAIResponses(id="gpt-5.2"),
-    tools=[WebSearchTools()],
-    db=agent2_db,
+agent_db = SqliteDb(db_file="tmp/agent.db", id="agent-db")
+trace_db = SqliteDb(db_file="tmp/traces.db", id="trace-db")
+
+research_agent = Agent(
+    id="research-agent",
+    model=OpenAIResponses(id="gpt-5.4"),
+    db=agent_db,
 )
 
-# AgentOS with dedicated tracing database
 agent_os = AgentOS(
-    agents=[hackernews_agent, search_agent],
+    agents=[research_agent],
+    db=trace_db,
     tracing=True,
-    db=db,  # All traces go here
 )
 
 app = agent_os.get_app()
 ```
 
-### Why Use a Dedicated Tracing Database?
-
-Without `db`, AgentOS stores all traces in the **first database it finds** from your agents, teams, or workflows. The selected database depends on component order.
+This layout gives traces their own retention and access policy while the agent keeps its application data in `agent_db`.
 
-With a dedicated `db`:
+## Configure the Span Processor
 
-- **Unified observability**: All traces in one queryable location
-- **Cross-agent analysis**: Compare performance across agents
-- **Independent scaling**: Traces don't affect agent data storage
-- **Predictable behavior**: You control exactly where traces go
+Use `setup_tracing()` when you need batched writes or explicit queue settings:
 
-## Using setup_tracing() with AgentOS
-
-You can also use `setup_tracing()` for more control over tracing configuration. In this case, you still need to ensure the tracing database is available to AgentOS:
-
-```python
+```python custom_tracing.py
 from agno.agent import Agent
 from agno.db.sqlite import SqliteDb
 from agno.models.openai import OpenAIResponses
 from agno.os import AgentOS
 from agno.tracing import setup_tracing
 
-# Agent databases
-agent1_db = SqliteDb(db_file="tmp/agent1.db", id="agent1_db")
-agent2_db = SqliteDb(db_file="tmp/agent2.db", id="agent2_db")
-
-# Dedicated tracing database
-db = SqliteDb(db_file="tmp/traces.db", id="traces_db")
+trace_db = SqliteDb(db_file="tmp/traces.db", id="trace-db")
 
-# Set up tracing with custom configuration
 setup_tracing(
-    db=db,
+    db=trace_db,
     batch_processing=True,
     max_queue_size=2048,
+    max_export_batch_size=512,
     schedule_delay_millis=3000,
 )
 
-# Create agents
-agent1 = Agent(name="Agent 1", model=OpenAIResponses(id="gpt-5.2"), db=agent1_db)
-agent2 = Agent(name="Agent 2", model=OpenAIResponses(id="gpt-5.2"), db=agent2_db)
+research_agent = Agent(
+    id="research-agent",
+    model=OpenAIResponses(id="gpt-5.4"),
+)
 
-# Pass db to AgentOS for trace querying via API
 agent_os = AgentOS(
-    agents=[agent1, agent2],
-    db=db,  # Makes traces queryable via AgentOS API
+    agents=[research_agent],
+    db=trace_db,
 )
 
 app = agent_os.get_app()
 ```
 
-<Note>
-  Even when using `setup_tracing()`, pass `db` to AgentOS so traces are accessible through the AgentOS API and UI.
-</Note>
+`setup_tracing()` configures tracing globally, so call it before creating agents and omit `tracing=True` from AgentOS. Pass the same database to AgentOS so its API and Control Plane can read the stored traces.
+
+## Install Dependencies
+
+The AgentOS extra includes the tracing packages:
+
+```bash
+uv pip install -U "agno[os]" openai
+```
+
+## Next Steps
 
-<Tip>
-  Use a dedicated `db` when traces need separate retention, access, or scaling policies.
-</Tip>
+| Task | Guide |
+|---|---|
+| Understand traces and spans | [Tracing concepts](/tracing/overview) |
+| Filter stored traces | [Filter Options](/agent-os/tracing/filter-options) |
+| Trace an agent | [Basic Agent Tracing](/agent-os/tracing/usage/basic-agent-tracing) |
+| Trace a team | [Basic Team Tracing](/agent-os/tracing/usage/basic-team-tracing) |
+| Trace a workflow | [Basic Workflow Tracing](/agent-os/tracing/usage/basic-workflow-tracing) |
diff --git a/agent-os/using-the-api.mdx b/agent-os/using-the-api.mdx
index 6420322f3..064333dcd 100644
--- a/agent-os/using-the-api.mdx
+++ b/agent-os/using-the-api.mdx
@@ -1,114 +1,151 @@
 ---
 title: "Using the API"
 sidebarTitle: "Using the API"
-description: "Call the AgentOS API to run agents, teams, and workflows."
+description: "Run agents, manage state, and operate AgentOS through its REST API."
 ---
 
-AgentOS exposes endpoints for running agents and managing sessions, memories, knowledge, and evals. The same API powers the [control plane](/agent-os/control-plane) and can be used to build your AI products.
+Application engineers use the AgentOS API to embed agents in products and manage runtime state from any HTTP client.
 
-## Instance Discovery
+```bash
+curl http://localhost:7777/agents/support-agent/runs \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "message=Where is my order?" \
+  -d "user_id=customer-42" \
+  -d "session_id=order-support-42" \
+  -d "stream=false"
+```
+
+The response includes the run output, `run_id`, and `session_id`. Reuse the same `session_id` to group later runs in the same thread. Configure [chat history](/history/overview) when the model needs messages from earlier runs.
+
+Teams and workflows use the same run pattern:
 
-`GET /info` is unauthenticated and returns what a client needs to bootstrap against an instance: which authentication mode it enforces and whether an MCP server is mounted.
+| Component | Run endpoint |
+|---|---|
+| Agent | `POST /agents/{agent_id}/runs` |
+| Team | `POST /teams/{team_id}/runs` |
+| Workflow | `POST /workflows/{workflow_id}/runs` |
+
+## Discover an Instance
+
+`GET /info` returns the metadata a client needs before making authenticated calls. The endpoint is public.
 
 ```bash
 curl http://localhost:7777/info
 ```
 
-```json
-{
-  "os_id": "my-agent-os",
-  "name": null,
-  "agno_version": "2.7.2",
-  "agent_count": 1,
-  "team_count": 0,
-  "workflow_count": 0,
-  "mcp": {
-    "enabled": true,
-    "path": "/mcp",
-    "oauth": null
-  },
-  "auth_mode": "none"
-}
-```
-
 | Field | Description |
-|-------|-------------|
-| `auth_mode` | Authentication enforced by the instance: `none`, `security_key`, or `jwt` |
+|---|---|
+| `auth_mode` | Active authentication mode: `none`, `security_key`, or `jwt` |
+| `agent_count`, `team_count`, `workflow_count` | Number of registered runtime components |
 | `mcp.enabled` | Whether the MCP server is mounted |
-| `mcp.path` | Mount path of the MCP server, `null` when disabled |
-| `mcp.oauth` | OAuth discovery details when the MCP endpoint is OAuth-protected, `null` otherwise |
-| `agent_count`, `team_count`, `workflow_count` | Registered components |
+| `mcp.path` | MCP mount path when enabled |
+| `mcp.oauth` | OAuth discovery details when the MCP endpoint uses OAuth |
 | `agno_version` | Agno version running on the instance |
 
-## Endpoints
+Use `GET /config` to retrieve component IDs, database IDs, interfaces, and domain configuration. Send credentials when `auth_mode` requires them.
 
-| Resource | Operations |
-|----------|------------|
-| Agents | Run, list, get |
-| Teams | Run, list, get |
-| Workflows | Run, list, get |
-| Sessions | Create, list, get, update, delete |
-| Memories | Create, list, get, update, delete |
-| Knowledge | Add, search, list, get, update, delete |
-| Evals | Create, list, get, update, delete |
-| Metrics | Get, refresh |
+## API Surfaces
 
-See the [API reference](/reference-api/overview) for full documentation.
+| Task | Resources |
+|---|---|
+| Execute application logic | Agents, teams, workflows, runs |
+| Manage conversation and user state | Sessions, memories, learnings |
+| Manage retrieval content | Knowledge, content sources, search |
+| Measure behavior | Evaluations, metrics, traces |
+| Control sensitive operations | Approvals, run continuation, cancellation |
+| Automate recurring work | Schedules and schedule runs |
+| Operate the runtime | Configuration, models, databases, service accounts |
+
+See the [API reference](/reference-api/overview) for every path and schema.
+
+## Stream Run Events
+
+Run endpoints stream Server-Sent Events by default. Use `curl -N` to print events as they arrive:
 
-## Running Agents
 ```bash
-curl http://localhost:7777/agents/my-agent/runs \
+curl -N http://localhost:7777/agents/support-agent/runs \
   -H "Content-Type: application/x-www-form-urlencoded" \
-  -d "message=Tell me about Agno" \
-  -d "stream=true" \
-  -d "user_id=john@example.com" \
-  -d "session_id=session_123"
+  -d "message=Investigate this account" \
+  -d "stream=true"
 ```
 
-Teams and workflows follow the same pattern:
-- `POST /teams/{team_id}/runs`
-- `POST /workflows/{workflow_id}/runs`
+Set `stream=false` when the caller needs one JSON response after the run completes.
+
+## Pass Runtime Context
+
+Run endpoints accept JSON-encoded form fields alongside the message:
+
+| Field | Use |
+|---|---|
+| `dependencies` | Values available to tools and runtime functions |
+| `session_state` | State carried through the current session |
+| `metadata` | Application metadata stored with the run |
+| `knowledge_filters` | Filters applied during knowledge retrieval |
+| `output_schema` | JSON Schema for structured output |
+
+```bash
+curl http://localhost:7777/agents/story-writer/runs \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "message=Write a short story" \
+  -d 'dependencies={"reader_age":10}' \
+  -d 'metadata={"source":"reading-app"}' \
+  -d 'output_schema={"type":"object","properties":{"title":{"type":"string"},"story":{"type":"string"}},"required":["title","story"]}' \
+  -d "stream=false"
+```
 
-## Authentication
+## Authenticate Requests
 
-The `auth_mode` field from `GET /info` tells you which credential to send:
+Read `auth_mode` from `GET /info`, then send the matching credential:
 
 | `auth_mode` | Credential |
-|-------------|------------|
-| `none` | No header required |
+|---|---|
+| `none` | No authorization header |
 | `security_key` | `Authorization: Bearer <OS_SECURITY_KEY>` |
 | `jwt` | `Authorization: Bearer <jwt-token>` |
 
 ```bash
-curl http://localhost:7777/agents/my-agent/runs \
+curl http://localhost:7777/agents/support-agent/runs \
   -H "Authorization: Bearer <your-token>" \
   -H "Content-Type: application/x-www-form-urlencoded" \
-  -d "message=Your query here"
+  -d "message=Summarize my open tickets" \
+  -d "stream=false"
 ```
 
-Service-account tokens (`agno_pat_...`) are accepted as bearer credentials in every mode on instances with a database. See [Security & Authorization](/agent-os/security/overview) to configure authentication.
+Service-account tokens beginning with `agno_pat_` are bearer credentials for machine callers. They are available when the AgentOS instance has a database.
 
-## Passing Dependencies
+## REST or Python Client
 
-Pass runtime parameters like `dependencies`, `session_state`, or `metadata` as form fields:
-```bash
-curl http://localhost:7777/agents/story-writer/runs \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -d "message=Write me a 5 line story" \
-  -d 'dependencies={"robot_name": "Anna"}'
-```
+| Client | Use when |
+|---|---|
+| REST API | The application uses another language, needs direct HTTP control, or calls a small set of endpoints |
+| `AgentOSClient` | A Python application needs typed run outputs and helpers for sessions, memory, knowledge, and configuration |
 
-## Output Schema
+```python
+import asyncio
 
-Pass a JSON schema to structure the response:
-```bash
-curl http://localhost:7777/agents/story-writer/runs \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -d "message=Write a story" \
-  -d 'output_schema={"type":"object","properties":{"title":{"type":"string"},"content":{"type":"string"}},"required":["title","content"]}'
-```
+from agno.client import AgentOSClient
 
-## Cancelling Runs
-```bash
-curl -X POST http://localhost:7777/agents/story-writer/runs/123/cancel
+
+async def main():
+    client = AgentOSClient(base_url="http://localhost:7777")
+    response = await client.run_agent(
+        agent_id="support-agent",
+        message="Where is my order?",
+        user_id="customer-42",
+        session_id="order-support-42",
+    )
+    print(response.content)
+
+
+asyncio.run(main())
 ```
+
+## Next Steps
+
+| Task | Guide |
+|---|---|
+| Browse every endpoint | [API reference](/reference-api/overview) |
+| Use the Python client | [AgentOS Client](/agent-os/client/agentos-client) |
+| Configure authentication | [Security & Auth](/agent-os/security/overview) |
+| Manage sessions | [Session management example](/agent-os/usage/client/session-management) |
+| Run AgentOS as an MCP server | [AgentOS as MCP Server](/agent-os/mcp/mcp) |
diff --git a/context/overview.mdx b/context/overview.mdx
index f6c30332e..6542c05a3 100644
--- a/context/overview.mdx
+++ b/context/overview.mdx
@@ -1,69 +1,90 @@
 ---
 title: Context Engineering
 sidebarTitle: Overview
-description: Design and control the information sent to language models to guide their behavior.
+description: Control the instructions, data, history, and tools sent to a model for each run.
 keywords: [context, context engineering, system message, user message, prompts, prompt engineering]
 ---
 
-Context engineering is the process of designing and controlling the information (context) that is sent to language models to guide their behavior and outputs. 
-In practice, building context comes down to one question: "Which information is most likely to achieve the desired outcome?"
+Context engineering controls what a model sees when an agent or team runs. Product teams use it to give the model the right instructions and application data while keeping each request focused.
 
-In Agno, this means carefully crafting the system message, which includes the agent or team description, instructions, and other relevant settings. By thoughtfully constructing this context, you can:
+```bash
+uv pip install -U agno openai sqlalchemy
+```
 
-- Steer your agent or team toward specific behaviors or roles.
-- Constrain or expand your agent or team's capabilities.
-- Ensure outputs are consistent, relevant, and aligned with your application's needs.
-- Enable advanced use cases such as multi-step reasoning, tool use, or structured output.
+```python support_agent.py
+from agno.agent import Agent
+from agno.db.sqlite import SqliteDb
+from agno.models.openai import OpenAIResponses
 
-Effective context engineering is an iterative process: refining the system message, trying out different descriptions and instructions, and using features such as schemas, delegation, and tool integrations.
+agent = Agent(
+    model=OpenAIResponses(id="gpt-5.4-mini"),
+    db=SqliteDb(db_file="tmp/support.db"),
+    instructions=[
+        "Answer product questions clearly and concisely.",
+        "The customer's plan is {plan}.",
+    ],
+    session_state={"plan": "enterprise"},
+    add_history_to_context=True,
+    num_history_runs=3,
+)
 
-The context of an Agno agent consists of the following:
-- **System message**: The system message is the main context that is sent to the agent or team, including all additional context
-- **User message**: The user message is the message that is sent to the agent or team.
-- **Chat history**: The chat history is the history of the conversation between the agent or team and the user.
-- **Additional input**: Any few-shot examples or other additional input that is added to the context.
+agent.print_response(
+    "Which support channels can I use?",
+    user_id="customer-42",
+    session_id="support-thread-7",
+)
+```
 
+The system message carries the agent's instructions and resolved plan. The user message carries the current request. Up to three previous runs from the same stored session can also enter the model context.
 
-## Context Caching
+## Sources of Context
+
+| Source | What it contributes | Use it for |
+|--------|---------------------|------------|
+| Description and instructions | Stable role, behavior, and constraints | Product behavior that applies across runs |
+| Run input | The current user request | The task to complete now |
+| [Knowledge](/knowledge/overview) | Retrieved content from documents and data | Domain grounding and source-backed answers |
+| [Memory](/memory/overview) | Persistent facts associated with a user | Preferences and details that cross sessions |
+| [Chat history](/history/overview) | Messages from earlier runs in one session | Multi-turn continuity |
+| [Session state](/state/overview) | Application data stored with the session | Carts, task progress, plans, and counters |
+| [Dependencies](/dependencies/overview) | Static or callable values resolved at run time | Request-specific application data |
+| Tool definitions and results | Available operations and their outputs | Reading data and taking actions |
+| `additional_context` and `additional_input` | Explicit system or message context | Few-shot examples and custom context blocks |
+
+Agno can assemble these sources for each run. Enable only the sources the model needs for the current use case.
 
-Most model providers support caching of system and user messages, though the implementation differs between providers.
+## Control Context Size
 
-The general approach is to cache repetitive content and common instructions, and then reuse that cached content in subsequent requests as the prefix of your system message.
-In other words, if the model supports it, you can reduce the number of tokens sent to the model by putting static content at the start of your system message.
+| Requirement | Configuration |
+|-------------|---------------|
+| Include recent conversation turns | `add_history_to_context=True` with `num_history_runs` or `num_history_messages` |
+| Condense a long conversation | [Session summaries](/sessions/session-summaries) |
+| Reduce stored tool-result context | [Context compression](/compression/overview) |
+| Retrieve relevant domain content | [Knowledge search](/knowledge/concepts/search-and-retrieval/overview) |
+| Add runtime values to the user message | `add_dependencies_to_context=True` |
+| Add session state as a context block | `add_session_state_to_context=True` |
+
+Start with the smallest set that supports the task. Inspect model messages in [debug mode](/agents/debugging-agents) when behavior suggests the model received missing, stale, or conflicting context.
+
+## Context Caching
 
-Agno's context construction is designed to place the most likely static content at the beginning of the system message.  
-If you wish to fine-tune this, the recommended approach is to manually set the system message.
+Some model providers cache repeated prompt prefixes. Provider requirements and pricing differ. Keep stable instructions consistent between requests, place changing data in the appropriate runtime fields, and verify the selected provider's caching behavior.
 
-Some examples of prompt caching:
-- [OpenAI's prompt caching](https://platform.openai.com/docs/guides/prompt-caching)
-- [Anthropic prompt caching](https://docs.claude.com/en/docs/build-with-claude/prompt-caching) -> See an [Agno example](/models/providers/native/anthropic/usage/prompt-caching) of this
+- [OpenAI prompt caching](https://platform.openai.com/docs/guides/prompt-caching)
+- [Anthropic prompt caching](https://docs.claude.com/en/docs/build-with-claude/prompt-caching)
+- [Anthropic caching with Agno](/models/providers/native/anthropic/usage/prompt-caching)
 - [OpenRouter prompt caching](https://openrouter.ai/docs/features/prompt-caching)
 
+## Next Steps
 
-## Learn more
 <CardGroup cols={3}>
-  <Card
-    title="Context Engineering for Agents"
-    icon="robot"
-    iconType="duotone"
-    href="/context/agent/overview"
-  >
-    Craft system messages and instructions for agents.
+  <Card title="Agent Context" icon="robot" iconType="duotone" href="/context/agent/overview">
+    Configure system messages and instructions for agents.
   </Card>
-  <Card
-    title="Context Engineering for Teams"
-    icon="users"
-    iconType="duotone"
-    href="/context/team/overview"
-  >
-    Configure context for multi-agent coordination.
+  <Card title="Team Context" icon="users" iconType="duotone" href="/context/team/overview">
+    Configure context for a leader and its members.
   </Card>
-  <Card
-    title="Chat History"
-    icon="history"
-    iconType="duotone"
-    href="/history/overview"
-  >
-    Include conversation history in context.
+  <Card title="Chat History" icon="history" iconType="duotone" href="/history/overview">
+    Select previous messages for model context.
   </Card>
-</CardGroup>
\ No newline at end of file
+</CardGroup>
diff --git a/deploy/introduction.mdx b/deploy/introduction.mdx
index c018eeffa..d099bd7d5 100644
--- a/deploy/introduction.mdx
+++ b/deploy/introduction.mdx
@@ -5,82 +5,72 @@ description: "Pre-built starter templates for running AgentOS in your cloud."
 mode: "wide"
 ---
 
-The Agno team provides a number of starter templates for running AgentOS, and agentic applications built on top of it, in your cloud of choice. We provide two kinds of templates:
+Starter templates give you a working platform with deployment, persistence, evals, and coding-agent workflows already wired in. Choose a template for your deployment target, or fork a complete agent application and adapt it to your use case.
 
-1. **AgentOS Starters:** clean AgentOS installations, one per platform: Railway, AWS, Fly, GCP and more.
-2. **Application Blueprints:** ready-to-use agentic solutions that you can deploy today.
+## Choose a template
 
-## What's inside every Starter
+<Tabs>
+  <Tab title="AgentOS Starters">
+    <CardGroup cols={3}>
+      <Card title="Railway" icon="train" href="/deploy/templates/railway/deploy">
+        Run AgentOS and PostgreSQL on Railway.
+      </Card>
+      <Card title="Docker" icon="docker" href="/deploy/templates/docker/deploy">
+        Run locally or self-host anywhere Docker runs.
+      </Card>
+      <Card title="AWS" icon="aws" href="/deploy/templates/aws/deploy">
+        ECS Express Mode with RDS PostgreSQL.
+      </Card>
+      <Card title="Fly" icon="plane" href="/deploy/templates/fly/deploy">
+        A single always-on machine on Fly.io.
+      </Card>
+      <Card title="GCP" icon="google" href="/deploy/templates/gcp/deploy">
+        Cloud Run with Cloud SQL.
+      </Card>
+      <Card title="Kubernetes" icon="dharmachakra" href="/deploy/templates/helm/deploy">
+        A Helm chart for EKS, GKE, AKS, or your own cluster.
+      </Card>
+      <Card title="Azure" icon="microsoft" href="/deploy/templates/azure/deploy">
+        Container Apps with PostgreSQL.
+      </Card>
+      <Card title="Render" icon="cloud" href="/deploy/templates/render/deploy">
+        A Blueprint with managed PostgreSQL.
+      </Card>
+      <Card title="Modal" icon="bolt" href="/deploy/templates/modal/deploy">
+        Modal with Neon Postgres.
+      </Card>
+    </CardGroup>
+  </Tab>
+  <Tab title="Apps">
+    <CardGroup cols={2}>
+      <Card title="Dash" icon="chart-mixed" href="/deploy/templates/dash/overview">
+        Ask business questions in plain English and get grounded answers from your data.
+      </Card>
+      <Card title="Coda" icon="code-branch" href="/deploy/templates/coda/overview">
+        Review pull requests, triage issues, and answer architecture questions from Slack.
+      </Card>
+      <Card title="Scout" icon="radar" href="/deploy/templates/scout/overview">
+        Find company knowledge across Slack, Drive, wikis, the web, and MCP sources.
+      </Card>
+      <Card title="Context" icon="address-book" href="/deploy/templates/context/overview">
+        Give your AI tools a shared CRM and knowledge base for your work.
+      </Card>
+    </CardGroup>
+  </Tab>
+</Tabs>
 
-Every starter template comes with a common platform core, along with cloud-specific deploy instructions.
+## What every AgentOS Starter includes
 
-| Component | What it does |
-|-----------|--------------|
-| **Two platform agents** | _**Agent Builder**_ creates agents, teams, and workflows. _**Platform Manager**_ helps manage the platform. |
-| **Two workflows** | _**Deployment Check**_ checks platform health and _**Run Evals**_ runs the eval suite. |
-| **MCP server** | Makes your platform available to any AI app or MCP client. |
-| **Coding-agent skills** | Manage your platform using skills like `/create-new-agent`, `/improve-agent` and more. |
-| **Eval suite** | Full AgentAsJudge and Reliability eval suite, ready to catch regressions. |
-| **PostgreSQL** | Sessions, memory, knowledge, and traces all stored in your database. |
+| Included | Why it matters |
+|----------|----------------|
+| **Agent Builder and Platform Manager** | Create agents, teams, and workflows from chat, then inspect runtime state and platform health |
+| **Coding-agent skills** | Set up the repository, create and extend agents, run evals, and check the project for drift |
+| **AgentOS API and MCP server** | Serve agents, teams, and workflows through REST and MCP, then manage and monitor them from the Control Plane |
+| **Evals and scheduled checks** | Check response quality and tool calls, then run deployment checks on a schedule |
+| **PostgreSQL** | Persist sessions, memory, knowledge, eval results, and traces in your database |
 
-## Get started
+## Build with a coding agent
 
-<Steps>
-  <Step title="Pick a template">
-    <Tabs>
-      <Tab title="AgentOS Starters">
-        <CardGroup cols={3}>
-          <Card title="Railway" icon="train" href="/deploy/templates/railway/deploy">
-            Run AgentOS and PostgreSQL on Railway.
-          </Card>
-          <Card title="Docker" icon="docker" href="/deploy/templates/docker/deploy">
-            Run locally or self-host anywhere Docker runs.
-          </Card>
-          <Card title="AWS" icon="aws" href="/deploy/templates/aws/deploy">
-            ECS Express Mode with RDS PostgreSQL.
-          </Card>
-          <Card title="Fly" icon="plane" href="/deploy/templates/fly/deploy">
-            A single always-on machine on Fly.io.
-          </Card>
-          <Card title="GCP" icon="google" href="/deploy/templates/gcp/deploy">
-            Cloud Run with Cloud SQL.
-          </Card>
-          <Card title="Kubernetes" icon="dharmachakra" href="/deploy/templates/helm/deploy">
-            A Helm chart for any cluster: EKS, GKE, AKS.
-          </Card>
-          <Card title="Azure" icon="microsoft" href="/deploy/templates/azure/deploy">
-            Container Apps with PostgreSQL.
-          </Card>
-          <Card title="Render" icon="cloud" href="/deploy/templates/render/deploy">
-            A Blueprint with managed PostgreSQL.
-          </Card>
-          <Card title="Modal" icon="bolt" href="/deploy/templates/modal/deploy">
-            Modal + Neon Postgres.
-          </Card>
-        </CardGroup>
-      </Tab>
-      <Tab title="Application Blueprints">
-        <CardGroup cols={3}>
-          <Card title="Dash" icon="chart-mixed" href="/deploy/templates/dash/overview">
-            Self-learning data agent with 6 layers of context.
-          </Card>
-          <Card title="Coda" icon="code-branch" href="/deploy/templates/coda/overview">
-            Code companion that lives in Slack.
-          </Card>
-          <Card title="Scout" icon="radar" href="/deploy/templates/scout/overview">
-            Company brain across Slack, Drive, and wikis.
-          </Card>
-          <Card title="Context" icon="address-book" href="/deploy/templates/context/overview">
-            Self-hosted context manager: a private CRM and knowledge base your AI tools share.
-          </Card>
-        </CardGroup>
-      </Tab>
-    </Tabs>
-  </Step>
-  <Step title="Set up with a coding agent">
-    Each Starter comes with a setup prompt you can give to coding agents like Claude Code, Cursor, or Codex. The agent clones the repo and sets everything up. Every template also comes with manual steps, but we recommend using coding agents for setup.
-  </Step>
-  <Step title="Connect your frontends">
-    Connect your AgentOS to the [AgentOS UI](https://os.agno.com) with **Connect OS**, and to coding agents on your machine by running `uvx agno connect`. You can also use the AgentOS MCP server (`https://<agentos-domain>/mcp`) to connect your AgentOS to the Claude and ChatGPT apps.
-  </Step>
-</Steps>
+Each Starter includes a setup prompt and a `/setup-platform` skill for Claude Code, Codex, and Cursor. It checks Docker, configures the environment, starts AgentOS, verifies the MCP endpoint, and builds your first agent with you.
+
+[Build with coding agents](/deploy/templates/improve-agents)
diff --git a/deploy/templates/aws/deploy.mdx b/deploy/templates/aws/deploy.mdx
index 7a59279c1..323e522e3 100644
--- a/deploy/templates/aws/deploy.mdx
+++ b/deploy/templates/aws/deploy.mdx
@@ -1,21 +1,24 @@
 ---
 title: "AgentOS on AWS"
 sidebarTitle: "Deploy"
-description: "Run AgentOS locally using Docker and deploy to production on AWS."
+description: "AgentOS template for teams that develop locally with Docker and deploy to production on AWS."
 ---
 
-AgentOS is a secure, scalable platform for running agents. The [agentos-aws](https://github.com/agno-agi/agentos-aws) codebase runs AgentOS locally using Docker and deploys to production on AWS. It comes with:
+**The [agentos-aws](https://github.com/agno-agi/agentos-aws) template is for teams that develop locally with Docker and deploy to production on AWS.**
 
-- **2 platform agents** that build and run the platform for you. **Agent Builder** creates agents, teams, and workflows. **Platform Manager** understands, monitors, and explains the platform.
-- **5 [skills](/deploy/templates/improve-agents)** that let coding agents build, test, and improve the platform for you.
+It includes:
 
-Because the trace data, agent code, evals, and system logs all live in one place, the platform can inspect and improve itself automatically.
+- **Agent Builder**, which creates agents, teams, and workflows.
+- **Platform Manager**, which inspects and explains the platform, eval history, deployment checks, and schedules.
+- **Six [skills](/deploy/templates/improve-agents)** for setting up, building, testing, and improving the project with a coding agent.
+
+Coding agents can use these skills with the AgentOS API, evals, traces, and container logs to inspect and improve the platform.
 
 Production runs in your own AWS account: the deploy scripts use ECS Express Mode for the service and RDS for Postgres.
 
 ## Get started
 
-The fastest way to get started is using a coding agent. Copy the prompt below into Claude Code, Cursor or Codex and it'll take you from zero to a running platform.
+Copy the prompt below into Claude Code, Cursor, or Codex to configure and run the template with a coding agent.
 
 <Snippet file="setup-prompt-aws.mdx" />
 
diff --git a/deploy/templates/azure/deploy.mdx b/deploy/templates/azure/deploy.mdx
index 84ada58c7..bc389f770 100644
--- a/deploy/templates/azure/deploy.mdx
+++ b/deploy/templates/azure/deploy.mdx
@@ -1,21 +1,24 @@
 ---
 title: "AgentOS on Azure Container Apps"
 sidebarTitle: "Deploy"
-description: "Run AgentOS locally using Docker and deploy to production on Azure Container Apps."
+description: "AgentOS template for teams that develop locally with Docker and deploy to production on Azure Container Apps."
 ---
 
-AgentOS is a secure, scalable platform for running agents. The [agentos-azure](https://github.com/agno-agi/agentos-azure) codebase runs AgentOS locally using Docker and deploys to production on Azure Container Apps. It comes with:
+**The [agentos-azure](https://github.com/agno-agi/agentos-azure) template is for teams that develop locally with Docker and deploy to production on Azure Container Apps.**
 
-- **2 platform agents** that build and run the platform for you. **Agent Builder** creates agents, teams, and workflows. **Platform Manager** understands, monitors, and explains the platform.
-- **5 [skills](/deploy/templates/improve-agents)** that let coding agents build, test, and improve the platform for you.
+It includes:
 
-Because the trace data, agent code, evals, and system logs all live in one place, the platform can inspect and improve itself automatically.
+- **Agent Builder**, which creates agents, teams, and workflows.
+- **Platform Manager**, which inspects and explains the platform, eval history, deployment checks, and schedules.
+- **Six [skills](/deploy/templates/improve-agents)** for setting up, building, testing, and improving the project with a coding agent.
+
+Coding agents can use these skills with the AgentOS API, evals, traces, and container logs to inspect and improve the platform.
 
 Everything runs in your own Azure subscription, and one script provisions the network, database, registry, and app into a single resource group.
 
 ## Get started
 
-The fastest way to get started is using a coding agent. Copy the prompt below into Claude Code, Cursor or Codex and it'll take you from zero to a running platform.
+Copy the prompt below into Claude Code, Cursor, or Codex to configure and run the template with a coding agent.
 
 <Snippet file="setup-prompt-azure.mdx" />
 
diff --git a/deploy/templates/coda/overview.mdx b/deploy/templates/coda/overview.mdx
index 1d8373bed..d533a9c89 100644
--- a/deploy/templates/coda/overview.mdx
+++ b/deploy/templates/coda/overview.mdx
@@ -1,14 +1,14 @@
 ---
 title: "Coda"
 sidebarTitle: "Coda"
-description: "A code companion that lives in Slack. It reviews PRs, triages issues, and answers architecture questions."
+description: "Code companion for engineering teams that review pull requests, triage issues, and answer architecture questions in Slack."
 ---
 
-**Coda is a code companion that lives in Slack.**
+**Coda is a code companion for engineering teams that review pull requests, triage issues, and answer architecture questions in Slack.**
 
-Coding agents help us write code faster, but most engineering work is understanding how things work, reviewing PRs, figuring out what broke and why, triaging the backlog, and deciding what's safe to change. That work happens in Slack and GitHub, not in an editor.
+Engineering teams spend a large part of the day understanding existing code, reviewing changes, triaging the backlog, and deciding what is safe to ship. Much of that coordination already happens in Slack and GitHub.
 
-Coda fills that gap. It answers architecture questions like "how does auth work" or "where is the model API call". It reviews PRs and open branches, diffs them against your conventions, and leaves comments. It reads open issues and flags the urgent ones worth tackling next. And it does all of this in Slack, alongside your team.
+Coda brings repository context and specialist agents into those conversations. It answers architecture questions with code references, reviews changes against your conventions, triages issues, plans work, and can prepare changes in isolated worktrees for human review.
 
 The code is public at [agno-agi/coda](https://github.com/agno-agi/coda).
 
@@ -24,7 +24,7 @@ Coda is a team of five specialist agents coordinated by a leader:
 | **Triager** | Labels, comments on, and closes issues based on code analysis |
 | **Researcher** | Searches the web for docs, APIs, and error messages |
 
-Coda writes code in git worktrees on `coda/*` branches, so your main branch is never touched. It opens PRs; a human merges them. And it runs in your infrastructure, so your code stays on your machines. The only external calls go to your configured LLM provider.
+The Coder works in isolated git worktrees on `coda/*` branches and opens pull requests for human review. Coda runs in your infrastructure and connects to the model provider, GitHub, Slack, and optional research services you configure.
 
 Between them, the agents cover:
 
@@ -50,11 +50,7 @@ Repo sync always runs. The daily digest only registers when both `DIGEST_CHANNEL
 
 ### Self-learning
 
-Coda gets sharper the more you use it. It picks up your coding standards, conventions, and patterns. The learning is powered by Agno's [Learning Machines](/learning/overview):
-
-| Week 1 | Week 4 |
-|--------|--------|
-| Writes working code using generic patterns | Follows your service layer conventions, uses your team's error handling pattern, matches your naming style |
+Coda uses a shared [Learning Machine](/learning/overview) to keep non-obvious conventions, such as service boundaries, error-handling patterns, and naming rules, available to every specialist. Relevant learnings are added to the context for later tasks.
 
 ## Run locally
 
diff --git a/deploy/templates/context/overview.mdx b/deploy/templates/context/overview.mdx
index 1f6f0694b..d8d36d956 100644
--- a/deploy/templates/context/overview.mdx
+++ b/deploy/templates/context/overview.mdx
@@ -1,12 +1,14 @@
 ---
 title: "Context"
 sidebarTitle: "Context"
-description: "Self-hosted context manager that organizes your work into a private CRM and knowledge base your AI tools share over MCP."
+description: "Self-hosted context manager that gives your AI tools one private CRM and knowledge base for your work."
 ---
 
-**@context is a self-hosted context manager. It organizes your work context into a private CRM and knowledge base and helps you stay on top of things.**
+**@context is a self-hosted context manager that gives your AI tools one private CRM and knowledge base for your work.**
 
-It plugs into clients like Claude, ChatGPT, Claude Code, Codex, and Cursor, and gives them a single source of context about your work. Anyone can write to your context. Only you can read it or act through it.
+Individuals and small teams use @context to capture relationships, decisions, reminders, and knowledge once, then retrieve them from Claude, ChatGPT, Claude Code, Codex, Cursor, Slack, and the AgentOS UI.
+
+Teammates and their agents can submit updates while your private context and action tools remain owner-only.
 
 @context is an [App](/deploy/introduction): a complete agent product you fork, run on your own infrastructure, and adapt. See the [repo](https://github.com/agno-agi/context) for the source.
 
diff --git a/deploy/templates/dash/overview.mdx b/deploy/templates/dash/overview.mdx
index 22dc968d7..8ff85193b 100644
--- a/deploy/templates/dash/overview.mdx
+++ b/deploy/templates/dash/overview.mdx
@@ -1,12 +1,14 @@
 ---
 title: "Dash"
 sidebarTitle: "Dash"
-description: "Self-learning data agent that grounds answers in six layers of context and improves with every query."
+description: "Self-learning data agent for teams that need grounded answers from company data, business rules, and proven query patterns."
 ---
 
-**Dash is a self-learning data agent built with systems engineering principles. It grounds answers in six layers of context and improves with every query.**
+**Dash is a self-learning data agent for teams that need grounded answers from company data, business rules, and proven query patterns.**
 
-Ask a question in English and get a correct, meaningful answer. That's the goal. But raw LLMs writing SQL hit a wall fast: schemas lack meaning, types are misleading, tribal knowledge is missing, there's no way to learn from mistakes, and results lack interpretation. The root cause is missing context and missing memory. Dash solves this with six layers of grounded context, a self-learning loop that captures every fix, and a focus on delivering insights you can act on.
+Data and analytics teams need answers that respect metric definitions, schema quirks, business rules, and queries that are known to work. Dash brings those inputs together as six layers of context and retains useful corrections through a learning loop.
+
+Ask a question in English and Dash queries read-only company data, interprets the result, and explains it using your business context.
 
 Chat with Dash in Slack, the terminal, or the [AgentOS UI](https://os.agno.com). The code is public at [agno-agi/dash](https://github.com/agno-agi/dash).
 
diff --git a/deploy/templates/docker/deploy.mdx b/deploy/templates/docker/deploy.mdx
index 554f8ccd0..ffabae936 100644
--- a/deploy/templates/docker/deploy.mdx
+++ b/deploy/templates/docker/deploy.mdx
@@ -1,16 +1,18 @@
 ---
 title: "AgentOS on self-hosted Docker"
 sidebarTitle: "Deploy"
-description: "Run AgentOS locally using Docker and deploy to production on self-hosted Docker."
+description: "AgentOS template for teams that want to run the same Docker Compose stack locally and on their own infrastructure."
 ---
 
-The [agentos-docker](https://github.com/agno-agi/agentos-docker) template runs AgentOS locally and in production with Docker Compose. It includes:
+**The [agentos-docker](https://github.com/agno-agi/agentos-docker) template is for teams that want to run the same Docker Compose stack locally and on their own infrastructure.**
 
-- **Agent Builder**, which creates agents, teams, and workflows when prompted.
+It includes:
+
+- **Agent Builder**, which creates agents, teams, and workflows.
 - **Platform Manager**, which inspects and explains registered agents, eval history, deployment checks, and schedules.
-- **Five [skills](/deploy/templates/improve-agents)** that coding agents can invoke to build, test, and improve the project.
+- **Six [skills](/deploy/templates/improve-agents)** for setting up, building, testing, and improving the project with a coding agent.
 
-Agent code, evals, traces, and logs stay in one project so users and coding agents can inspect them together.
+Coding agents can use these skills with the AgentOS API, evals, traces, and container logs to inspect and improve the platform.
 
 Production uses the local Docker Compose configuration plus one override file on a host you control.
 
diff --git a/deploy/templates/fly/deploy.mdx b/deploy/templates/fly/deploy.mdx
index e3ad11a71..3383d3f71 100644
--- a/deploy/templates/fly/deploy.mdx
+++ b/deploy/templates/fly/deploy.mdx
@@ -1,19 +1,22 @@
 ---
 title: "AgentOS on Fly.io"
 sidebarTitle: "Deploy"
-description: "Run AgentOS locally using Docker and deploy to production on Fly.io."
+description: "AgentOS template for teams that develop locally with Docker and deploy to production on Fly.io."
 ---
 
-AgentOS is a secure, scalable platform for running agents. The [agentos-fly](https://github.com/agno-agi/agentos-fly) codebase runs AgentOS locally using Docker and deploys to production on Fly.io. It comes with:
+**The [agentos-fly](https://github.com/agno-agi/agentos-fly) template is for teams that develop locally with Docker and deploy to production on Fly.io.**
 
-- **2 platform agents** that build and run the platform for you. **Agent Builder** creates agents, teams, and workflows. **Platform Manager** understands, monitors, and explains the platform.
-- **5 [skills](/deploy/templates/improve-agents)** that let coding agents build, test, and improve the platform for you.
+It includes:
 
-Because the trace data, agent code, evals, and system logs all live in one place, the platform can inspect and improve itself automatically.
+- **Agent Builder**, which creates agents, teams, and workflows.
+- **Platform Manager**, which inspects and explains the platform, eval history, deployment checks, and schedules.
+- **Six [skills](/deploy/templates/improve-agents)** for setting up, building, testing, and improving the project with a coding agent.
+
+Coding agents can use these skills with the AgentOS API, evals, traces, and container logs to inspect and improve the platform.
 
 ## Get started
 
-The fastest way to get started is using a coding agent. Copy the prompt below into Claude Code, Cursor or Codex and it'll take you from zero to a running platform.
+Copy the prompt below into Claude Code, Cursor, or Codex to configure and run the template with a coding agent.
 
 <Snippet file="setup-prompt-fly.mdx" />
 
diff --git a/deploy/templates/gcp/deploy.mdx b/deploy/templates/gcp/deploy.mdx
index c9a412678..67363e394 100644
--- a/deploy/templates/gcp/deploy.mdx
+++ b/deploy/templates/gcp/deploy.mdx
@@ -1,21 +1,24 @@
 ---
 title: "AgentOS on Google Cloud Run"
 sidebarTitle: "Deploy"
-description: "Run AgentOS locally using Docker and deploy to production on Google Cloud Run."
+description: "AgentOS template for teams that develop locally with Docker and deploy to production on Google Cloud Run."
 ---
 
-AgentOS is a secure, scalable platform for running agents. The [agentos-gcp](https://github.com/agno-agi/agentos-gcp) codebase runs AgentOS locally using Docker and deploys to production on Google Cloud Run. It comes with:
+**The [agentos-gcp](https://github.com/agno-agi/agentos-gcp) template is for teams that develop locally with Docker and deploy to production on Google Cloud Run.**
 
-- **2 platform agents** that build and run the platform for you. **Agent Builder** creates agents, teams, and workflows. **Platform Manager** understands, monitors, and explains the platform.
-- **5 [skills](/deploy/templates/improve-agents)** that let coding agents build, test, and improve the platform for you.
+It includes:
 
-Because the trace data, agent code, evals, and system logs all live in one place, the platform can inspect and improve itself automatically.
+- **Agent Builder**, which creates agents, teams, and workflows.
+- **Platform Manager**, which inspects and explains the platform, eval history, deployment checks, and schedules.
+- **Six [skills](/deploy/templates/improve-agents)** for setting up, building, testing, and improving the project with a coding agent.
+
+Coding agents can use these skills with the AgentOS API, evals, traces, and container logs to inspect and improve the platform.
 
 Everything runs in your own Google Cloud project: Cloud Run serves the platform and Cloud SQL holds your data.
 
 ## Get started
 
-The fastest way to get started is using a coding agent. Copy the prompt below into Claude Code, Cursor or Codex and it'll take you from zero to a running platform.
+Copy the prompt below into Claude Code, Cursor, or Codex to configure and run the template with a coding agent.
 
 <Snippet file="setup-prompt-gcp.mdx" />
 
diff --git a/deploy/templates/helm/deploy.mdx b/deploy/templates/helm/deploy.mdx
index 75c0d6952..e8be201fa 100644
--- a/deploy/templates/helm/deploy.mdx
+++ b/deploy/templates/helm/deploy.mdx
@@ -1,21 +1,24 @@
 ---
 title: "AgentOS on Kubernetes"
 sidebarTitle: "Deploy"
-description: "Run AgentOS locally using Docker and deploy to production on Kubernetes."
+description: "AgentOS template for teams that develop locally with Docker and deploy to production on Kubernetes with Helm."
 ---
 
-AgentOS is a secure, scalable platform for running agents. The [agentos-helm](https://github.com/agno-agi/agentos-helm) codebase runs AgentOS locally using Docker and deploys to production on Kubernetes. It comes with:
+**The [agentos-helm](https://github.com/agno-agi/agentos-helm) template is for teams that develop locally with Docker and deploy to production on Kubernetes with Helm.**
 
-- **2 platform agents** that build and run the platform for you. **Agent Builder** creates agents, teams, and workflows. **Platform Manager** understands, monitors, and explains the platform.
-- **5 [skills](/deploy/templates/improve-agents)** that let coding agents build, test, and improve the platform for you.
+It includes:
 
-Because the trace data, agent code, evals, and system logs all live in one place, the platform can inspect and improve itself automatically.
+- **Agent Builder**, which creates agents, teams, and workflows.
+- **Platform Manager**, which inspects and explains the platform, eval history, deployment checks, and schedules.
+- **Six [skills](/deploy/templates/improve-agents)** for setting up, building, testing, and improving the project with a coding agent.
+
+Coding agents can use these skills with the AgentOS API, evals, traces, and container logs to inspect and improve the platform.
 
 The Helm chart in `charts/agentos` deploys to any Kubernetes cluster, cloud-managed (EKS, GKE, AKS) or your own.
 
 ## Get started
 
-The fastest way to get started is using a coding agent. Copy the prompt below into Claude Code, Cursor or Codex and it'll take you from zero to a running platform.
+Copy the prompt below into Claude Code, Cursor, or Codex to configure and run the template with a coding agent.
 
 <Snippet file="setup-prompt-helm.mdx" />
 
diff --git a/deploy/templates/improve-agents.mdx b/deploy/templates/improve-agents.mdx
index c89d84e88..f518eeac5 100644
--- a/deploy/templates/improve-agents.mdx
+++ b/deploy/templates/improve-agents.mdx
@@ -1,42 +1,51 @@
 ---
 title: "Build with Coding Agents"
 sidebarTitle: "Coding Agents"
-description: "Bundled skills that let Claude Code, Codex, and Cursor create, improve, evaluate, and maintain your agents."
+description: "Use Claude Code, Codex, or Cursor to set up, build, improve, evaluate, and maintain an AgentOS Starter."
 ---
 
-Every template is designed for coding agents to drive the full agent-development lifecycle: create, improve, evaluate, maintain.
+Use Claude Code, Codex, or Cursor to set up, build, improve, evaluate, and maintain an AgentOS Starter.
 
-Everything on this page runs inside a cloned template. If you don't have one running yet, [pick a Starter](/deploy/introduction) first.
+The repository gives your coding agent the source code, a live MCP endpoint, evals, and runtime logs in one place. It can make a change, exercise it against the running platform, and bring back a verified result.
 
-The skills live in `.agents/skills/`. Claude Code picks them up on clone through a committed `.claude/skills` symlink; other harnesses like Codex and Cursor can symlink the same folder. Invoke a skill by name (`/create-new-agent`) or describe the task and the coding agent matches it.
+Everything on this page runs inside a cloned AgentOS Starter. If you don't have one running yet, [pick a Starter](/deploy/introduction) first.
 
 ## Skills
 
-| Skill | What it does | Who drives |
-|-------|--------------|------------|
-| `/create-new-agent` | Scaffolds an agent, registers it in `app/main.py`, smoke-tests it live. | You + the agent |
-| `/extend-agent` | Adds a tool or capability, refines instructions, fixes a known bug. | You |
-| `/improve-agent` | Derives probes from the agent's `INSTRUCTIONS`, judges responses, edits until they pass. | The agent |
-| `/eval-and-improve` | Runs the eval suite, diagnoses failures, fixes in scope until green. | The agent |
-| `/review-and-improve` | Sweeps for drift between docs, code, and config. Auto-fixes mechanical drift. | The agent |
+Each AgentOS Starter stores its coding-agent workflows in `.agents/skills/`.
 
-## Your platform as an MCP tool
+| Skill | Use it when |
+|-------|-------------|
+| `/setup-platform` | Bring up a fresh clone, verify the platform, and build the first agent |
+| `/create-new-agent` | Turn an idea into a registered agent and smoke-test it live |
+| `/extend-agent` | Add a tool, capability, instruction change, or targeted fix |
+| `/improve-agent` | Derive probes from an agent's instructions and harden its behavior |
+| `/eval-and-improve` | Diagnose failing evals and repair the affected behavior |
+| `/review-and-improve` | Check code, documentation, configuration, and registered components for drift |
 
-Coding agents edit the platform's code and call its live agents over MCP. Register your AgentOS with the MCP clients on your machine:
+Claude Code discovers the skills through the Starter's committed `.claude/skills` symlink. Codex and Cursor can link to the same `.agents/skills/` directory.
+
+## Connect the live platform
+
+Connect the local AgentOS to the supported clients on your machine:
 
 ```bash
 uvx agno connect
 ```
 
-It auto-detects Claude Code, Claude Desktop, Codex, and Cursor and registers `http://localhost:8000/mcp`. To check the connection, open one of those apps and ask: "can you access my agentos mcp?". Your coding agent can then call `run_agent`, `run_team`, and `run_workflow` against the live platform.
+The command registers AgentOS with detected Claude Code, Claude Desktop, Codex, and Cursor clients. Your coding agent can then call `run_agent`, `run_team`, and `run_workflow` while it works on the repository.
+
+For a deployed platform:
 
-For a deployed platform, point the same command at your domain: `uvx agno connect --url https://<your-domain>`.
+```bash
+uvx agno connect --url https://<your-domain>
+```
 
-`agno connect` writes client credentials according to the endpoint's authentication. It writes tokenless entries for an unauthenticated MCP endpoint. It mints scoped service-account tokens (`agno_pat_...`) for a token-protected endpoint when the AgentOS has a REST admin credential that can authorize the mint. For an OAuth-enabled endpoint, it writes tokenless entries and prints one-time browser sign-in steps for supported clients. Use `--pat` when a headless client needs a service-account token on an OAuth-enabled AgentOS; minting still requires a REST admin credential or an existing admin PAT. With the built-in OAuth provider, `MCP_CONNECT_SECRET` is the secret entered on the AgentOS consent page. Coding clients use OAuth tokens from that flow or a separately minted PAT.
+See [Connect Your Clients](/cli/connect) for authentication modes and client-specific setup.
 
-## Evals
+## Keep behavior stable with evals
 
-Lock in agent behavior with the eval suite in `evals/`. The evals run on the host machine, so set up the venv once:
+Use the bundled eval suite to check response quality and tool calls as you change instructions, tools, and models. The evals run on the host machine, so set up the virtual environment once:
 
 ```bash
 ./scripts/venv_setup.sh
@@ -46,7 +55,7 @@ source .venv/bin/activate
 Then run:
 
 ```bash
-python -m evals --tag smoke      # fast checks of the self-driving surfaces
+python -m evals --tag smoke      # fast checks of the platform agents
 python -m evals --tag release    # broader pre-release confidence
 python -m evals --name <case>    # one case while iterating
 python -m evals -v               # stream the full run with rich panels
@@ -66,15 +75,6 @@ The bundled agents demonstrate three patterns to copy:
 | Context provider | `agents/platform_manager.py` | You want many tools collapsed into one `query_<thing>` interface that hands off to a sub-agent. |
 | Studio builder | `agents/agent_builder.py` | Users create and refine components from chat; deletes keep a confirmation gate. |
 
-## Teams and workflows
-
-| Pattern | When to use |
-|---------|-------------|
-| [Teams](/teams/overview) | Route to specialists, coordinate parallel work, synthesize results. |
-| [Workflows](/workflows/overview) | Processes with defined, repeatable control flow. |
-
-Agents for open questions, teams for routing, workflows for processes.
-
 ## Scheduled tasks
 
 The scheduler is on by default. Two reference workflows are registered out of the box:
@@ -85,3 +85,11 @@ The scheduler is on by default. Two reference workflows are registered out of th
 | Run evals | Daily smoke-tag eval run. Uses model calls. | Off. Enable with `ENABLE_SCHEDULED_EVALS=True`. |
 
 See [Scheduler](/agent-os/scheduler/overview) for the cron API.
+
+## Next steps
+
+| Task | Guide |
+|------|-------|
+| Choose a Starter | [AgentOS Templates](/deploy/introduction) |
+| Connect coding clients | [Connect Your Clients](/cli/connect) |
+| Add or customize evals | [Evals](/evals/overview) |
diff --git a/deploy/templates/modal/deploy.mdx b/deploy/templates/modal/deploy.mdx
index 446ff3a1d..2f6b22f52 100644
--- a/deploy/templates/modal/deploy.mdx
+++ b/deploy/templates/modal/deploy.mdx
@@ -1,16 +1,18 @@
 ---
 title: "AgentOS on Modal"
 sidebarTitle: "Deploy"
-description: "Run AgentOS locally using Docker and deploy to production on Modal."
+description: "AgentOS template for teams that develop locally with Docker and deploy to production on Modal."
 ---
 
-The [agentos-modal](https://github.com/agno-agi/agentos-modal) template runs AgentOS locally with Docker and deploys it to Modal. It includes:
+**The [agentos-modal](https://github.com/agno-agi/agentos-modal) template is for teams that develop locally with Docker and deploy to production on Modal.**
+
+It includes:
 
 - **Agent Builder**, which creates agents, teams, and workflows.
-- **Platform Manager**, which reports on evals, deployment checks, and schedules.
-- **5 [skills](/deploy/templates/improve-agents)** for coding-agent development and validation.
+- **Platform Manager**, which inspects and explains the platform, eval history, deployment checks, and schedules.
+- **Six [skills](/deploy/templates/improve-agents)** for setting up, building, testing, and improving the project with a coding agent.
 
-The template keeps agent code, evals, traces, and system logs in one project.
+Coding agents can use these skills with the AgentOS API, evals, traces, and deployment logs to inspect and improve the platform.
 
 ## Get started
 
diff --git a/deploy/templates/railway/deploy.mdx b/deploy/templates/railway/deploy.mdx
index 326f26a64..ad113ecea 100644
--- a/deploy/templates/railway/deploy.mdx
+++ b/deploy/templates/railway/deploy.mdx
@@ -1,15 +1,18 @@
 ---
 title: "AgentOS on Railway"
 sidebarTitle: "Deploy"
-description: "Run AgentOS locally using Docker and deploy to production on Railway."
+description: "AgentOS template for teams that develop locally with Docker and deploy with Postgres on Railway."
 ---
 
-The [agentos-railway](https://github.com/agno-agi/agentos-railway) template runs AgentOS locally with Docker and deploys it to Railway. It includes:
+**The [agentos-railway](https://github.com/agno-agi/agentos-railway) template is for teams that develop locally with Docker and deploy with Postgres on Railway.**
 
-- **2 platform agents** that build and run the platform for you. **Agent Builder** creates agents, teams, and workflows. **Platform Manager** understands, monitors, and explains the platform.
-- **5 [skills](/deploy/templates/improve-agents)** that let coding agents build, test, and improve the platform for you.
+It includes:
 
-Coding agents can use the repository skills, live AgentOS API, evals, and container logs to inspect and improve the platform.
+- **Agent Builder**, which creates agents, teams, and workflows.
+- **Platform Manager**, which inspects and explains the platform, eval history, deployment checks, and schedules.
+- **Six [skills](/deploy/templates/improve-agents)** for setting up, building, testing, and improving the project with a coding agent.
+
+Coding agents can use these skills with the AgentOS API, evals, traces, and container logs to inspect and improve the platform.
 
 ## Get started
 
diff --git a/deploy/templates/render/deploy.mdx b/deploy/templates/render/deploy.mdx
index a4af94f39..2d03aa691 100644
--- a/deploy/templates/render/deploy.mdx
+++ b/deploy/templates/render/deploy.mdx
@@ -1,21 +1,24 @@
 ---
 title: "AgentOS on Render"
 sidebarTitle: "Deploy"
-description: "Run AgentOS locally using Docker and deploy to production on Render."
+description: "AgentOS template for teams that develop locally with Docker and deploy to production on Render."
 ---
 
-AgentOS is a secure, scalable platform for running agents. The [agentos-render](https://github.com/agno-agi/agentos-render) codebase runs AgentOS locally using Docker and deploys to production on Render. It comes with:
+**The [agentos-render](https://github.com/agno-agi/agentos-render) template is for teams that develop locally with Docker and deploy to production on Render.**
 
-- **2 platform agents** that build and run the platform for you. **Agent Builder** creates agents, teams, and workflows. **Platform Manager** understands, monitors, and explains the platform.
-- **5 [skills](/deploy/templates/improve-agents)** that let coding agents build, test, and improve the platform for you.
+It includes:
 
-Because the trace data, agent code, evals, and system logs all live in one place, the platform can inspect and improve itself automatically.
+- **Agent Builder**, which creates agents, teams, and workflows.
+- **Platform Manager**, which inspects and explains the platform, eval history, deployment checks, and schedules.
+- **Six [skills](/deploy/templates/improve-agents)** for setting up, building, testing, and improving the project with a coding agent.
+
+Coding agents can use these skills with the AgentOS API, evals, traces, and container logs to inspect and improve the platform.
 
 Deployment is Blueprint-driven: Render provisions everything from `render.yaml` when you connect your repo, and one wiring script finishes the setup.
 
 ## Get started
 
-The fastest way to get started is using a coding agent. Copy the prompt below into Claude Code, Cursor or Codex and it'll take you from zero to a running platform.
+Copy the prompt below into Claude Code, Cursor, or Codex to configure and run the template with a coding agent.
 
 <Snippet file="setup-prompt-render.mdx" />
 
diff --git a/deploy/templates/scout/overview.mdx b/deploy/templates/scout/overview.mdx
index d2e1d9cdb..79fcd226d 100644
--- a/deploy/templates/scout/overview.mdx
+++ b/deploy/templates/scout/overview.mdx
@@ -1,12 +1,14 @@
 ---
 title: "Scout"
 sidebarTitle: "Scout"
-description: "Open-source company intelligence agent that navigates web, Slack, Drive, and MCP sources and builds its own wiki and CRM as it learns about your company."
+description: "Company intelligence agent for teams that need answers across live web, Slack, Drive, wiki, CRM, and MCP sources."
 ---
 
-**Scout is an open-source company intelligence agent.** It navigates live information sources (web, Slack, Drive, wiki, CRM, MCP servers) to assemble context on demand, and it builds its own wiki and CRM as it learns about your company. The code is public at [agno-agi/scout](https://github.com/agno-agi/scout).
+**Scout is a company intelligence agent for teams that need answers across live web, Slack, Drive, wiki, CRM, and MCP sources.**
 
-The default move when working with knowledge sources is to ingest everything into a vector database, chunk, embed, and pray. Coding agents figured out the right approach. They navigate: `ls`, `grep`, open the file, follow the import. Scout does the same thing across Slack, Drive, and the rest. It searches the channel, opens the doc, expands the thread, and assembles context at question time from the live source.
+Scout searches the system that owns the information and assembles context at question time. It can open a document, expand a Slack thread, search the web, and follow related information across sources. Scout also maintains a wiki and CRM so useful company context becomes easier to retrieve over time.
+
+The code is public at [agno-agi/scout](https://github.com/agno-agi/scout).
 
 ## How it works
 
diff --git a/evals/overview.mdx b/evals/overview.mdx
index 42cb01006..aefb47c64 100644
--- a/evals/overview.mdx
+++ b/evals/overview.mdx
@@ -1,70 +1,118 @@
 ---
 title: What are Evals?
-description: Measure the quality of your Agents and Teams across accuracy, agent as judge, performance, and reliability dimensions.
+description: Measure agent and team quality across expected answers, custom criteria, tool behavior, and performance.
 sidebarTitle: Overview
-keywords: [evals,reliability evals,accuracy evals,performance evals,agent as judge, agent evals, team evals]
+keywords: [evals, reliability evals, accuracy evals, performance evals, agent as judge, agent evals, team evals]
 ---
 
-Evaluate your Agno Agents and Teams across four dimensions: **accuracy** (simple correctness checks), **agent as judge** (custom quality criteria), **performance** (runtime and memory), and **reliability** (tool calls). Combine judge and reliability checks across many cases with [eval suites](/evals/suite/overview).
+Teams shipping agents need to know whether a prompt, model, tool, or context change improved the product. Evals turn expected behavior into repeatable checks that can run during development and in CI.
 
-## Evaluation Dimensions
+```python accuracy_eval.py
+from agno.agent import Agent
+from agno.eval.accuracy import AccuracyEval
+from agno.models.openai import OpenAIResponses
+from agno.tools.calculator import CalculatorTools
 
-<CardGroup cols={2}>
-  <Card title="Accuracy" icon="bullseye" href="/evals/accuracy/overview">
-    The accuracy of the Agent's response using LLM-as-a-judge methodology.
-  </Card>
-  <Card title="Agent as Judge" icon="scale-balanced" href="/evals/agent-as-judge/overview">
-    Evaluate custom quality criteria using LLM-as-a-judge with scoring.
-  </Card>
-  <Card title="Performance" icon="stopwatch" href="/evals/performance/overview">
-    The performance of the Agent's response, including latency and memory footprint.
-  </Card>
-  <Card title="Reliability" icon="shield-check" href="/evals/reliability/overview">
-    The reliability of the Agent's response, including tool calls and error handling.
-  </Card>
-</CardGroup>
+agent = Agent(
+    model=OpenAIResponses(id="gpt-5.4-mini"),
+    tools=[CalculatorTools()],
+)
+
+evaluation = AccuracyEval(
+    name="Calculator accuracy",
+    model=OpenAIResponses(id="gpt-5.4-mini"),
+    agent=agent,
+    input="What is 10 factorial?",
+    expected_output="3628800",
+)
+
+result = evaluation.run(print_results=True)
+assert result is not None and result.avg_score >= 8
+```
+
+`AccuracyEval` runs the agent, then uses the evaluator model to compare its response with the expected output.
 
-## Eval Suites
+## Choose an Eval
 
-[Eval suites](/evals/suite/overview) run many judge and reliability checks as one batch. Declare a `Case` per input, select cases by tag or name, and gate CI with the exit code and JSON report.
+| Question | Eval |
+|----------|------|
+| Does the response match an expected answer? | [Accuracy](/evals/accuracy/overview) |
+| Does the response meet product-specific quality criteria? | [Agent as Judge](/evals/agent-as-judge/overview) |
+| Did the agent or team call the expected tools with the expected arguments? | [Reliability](/evals/reliability/overview) |
+| How long does the code take and how much memory does it use? | [Performance](/evals/performance/overview) |
+| Do many judge and reliability cases pass together? | [Eval Suites](/evals/suite/overview) |
 
-## Quick Start
+Accuracy and agent-as-judge checks use a model to evaluate output. Reliability checks inspect recorded tool calls and arguments. Performance checks execute a function repeatedly and report runtime and memory statistics.
 
-Here's a simple example of running an accuracy evaluation:
+## Build a Regression Suite
+
+Eval suites run multiple `Case` definitions against agents or teams. Each case can check custom criteria, expected tool calls, or both.
+
+```python evals.py
+import sys
 
-```python quick_eval.py
-from typing import Optional
 from agno.agent import Agent
-from agno.eval.accuracy import AccuracyEval, AccuracyResult
+from agno.eval import Case, cli
 from agno.models.openai import OpenAIResponses
 from agno.tools.calculator import CalculatorTools
 
-# Create an evaluation
-evaluation = AccuracyEval(
-    model=OpenAIResponses(id="gpt-5.2"),
-    agent=Agent(model=OpenAIResponses(id="gpt-5.2"), tools=[CalculatorTools()]),
-    input="What is 10*5 then to the power of 2? do it step by step",
-    expected_output="2500",
-    additional_guidelines="Agent output should include the steps and the final answer.",
+agent = Agent(
+    id="calculator-agent",
+    model=OpenAIResponses(id="gpt-5.4-mini"),
+    tools=[CalculatorTools()],
+    instructions="Use calculator tools for arithmetic.",
+)
+
+CASES = (
+    Case(
+        name="factorial_uses_calculator",
+        agent=agent,
+        input="What is 10 factorial?",
+        tags=("smoke",),
+        criteria="States that 10 factorial equals 3628800.",
+        expected_tool_calls=("factorial",),
+    ),
 )
 
-# Run the evaluation
-result: Optional[AccuracyResult] = evaluation.run(print_results=True)
+if __name__ == "__main__":
+    sys.exit(cli(CASES))
 ```
 
-## Best Practices
+```bash
+python evals.py --tag smoke --json-output tmp/evals.json
+```
+
+The CLI returns a failing exit code when a selected case fails and can write a JSON report for CI artifacts. See [Eval Suites](/evals/suite/overview) for selectors, timeouts, judge modes, and programmatic execution.
+
+## What to Evaluate
 
-- **Start Simple:** Begin with basic accuracy tests before progressing to complex performance and reliability evaluations
-- **Use Multiple Test Cases:** Don't rely on a single test case. Build suites that cover edge cases
-- **Track Over Time:** Monitor your eval metrics continuously as you iterate on your agents
-- **Combine Dimensions:** Evaluate across all four dimensions for a holistic view of agent quality
+Start with behavior that matters to the product:
 
-## Guides
+| Product requirement | Check |
+|---------------------|-------|
+| Support answers cite the correct policy | Accuracy against reviewed expected answers |
+| Responses follow your tone and escalation rules | Agent-as-judge criteria |
+| Refund requests call the approval tool | Reliability tool-call checks |
+| Search stays within a latency budget | Performance thresholds tracked by your test harness |
 
-Dive deeper into each evaluation dimension:
+Keep cases focused on one behavior so failures point to a clear prompt, model, context, or tool change.
 
-1. **[Accuracy Evals](/evals/accuracy/overview)** - Learn LLM-as-a-judge techniques and multiple test case strategies
-2. **[Agent as Judge Evals](/evals/agent-as-judge/overview)** - Define custom quality criteria with flexible scoring strategies
-3. **[Performance Evals](/evals/performance/overview)** - Measure latency, memory usage, and compare different configurations
-4. **[Reliability Evals](/evals/reliability/overview)** - Test tool calls, error handling, and rate limiting behavior
-5. **[Eval Suites](/evals/suite/overview)** - Batch cases into a suite with a built-in CLI for CI gating
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Accuracy" icon="bullseye" href="/evals/accuracy/overview">
+    Compare responses with expected answers.
+  </Card>
+  <Card title="Agent as Judge" icon="scale-balanced" href="/evals/agent-as-judge/overview">
+    Score custom quality criteria.
+  </Card>
+  <Card title="Reliability" icon="shield-check" href="/evals/reliability/overview">
+    Check tool calls and arguments.
+  </Card>
+  <Card title="Performance" icon="stopwatch" href="/evals/performance/overview">
+    Measure runtime and memory usage.
+  </Card>
+  <Card title="Eval Suites" icon="list-check" href="/evals/suite/overview">
+    Run many judge and reliability cases in CI.
+  </Card>
+</CardGroup>
diff --git a/memory/overview.mdx b/memory/overview.mdx
index 477612eea..cf6645629 100644
--- a/memory/overview.mdx
+++ b/memory/overview.mdx
@@ -5,200 +5,92 @@ sidebarTitle: Overview
 keywords: [memory, agent memory, user memories, persistent memory, session history, automatic memory, agentic memory, user preferences, context retention]
 ---
 
-Memory lets a customer support agent recall your product preferences from last week, or a personal assistant remember that you prefer morning meetings. Agents store facts about each user and retrieve them in later conversations.
+Customer support agents, product copilots, and personal assistants often serve the same user across many conversations. Memory keeps facts such as preferences, responsibilities, and recurring goals available across those conversations.
 
-## How Memory Works
-
-When relevant information appears in a conversation, like a user's name, preferences, or habits, an Agent with Memory automatically stores it in your database. Later, when that information becomes relevant again, the agent retrieves and uses it naturally in the conversation. The agent is effectively **learning about each user** across interactions.
-
-<Tip>
-**Memory ≠ Session History:** Memory stores learned user facts ("Sarah prefers email"). [Session history](/history/overview) stores conversation messages for continuity ("what did we just discuss?").
-</Tip>
-
-## Getting Started with Memory
-
-Setting up memory is straightforward: just connect a database and enable the memory feature. Here's a basic setup:
-
-```python
+```python memory_agent.py
 from agno.agent import Agent
 from agno.db.sqlite import SqliteDb
+from agno.models.openai import OpenAIResponses
 
-# Setup your database
-db = SqliteDb(db_file="agno.db")
-
-# Setup your Agent with Memory
 agent = Agent(
-    db=db,
-    update_memory_on_run=True, # This enables Memory for the Agent
+    model=OpenAIResponses(id="gpt-5.4-mini"),
+    db=SqliteDb(db_file="tmp/memory.db"),
+    update_memory_on_run=True,
 )
-```
-
-With `update_memory_on_run=True`, your agent automatically creates and updates memories after each conversation. It extracts relevant information, stores it, and recalls it when needed, with no manual intervention required.
-
-## Two Approaches: Automatic vs Agentic Memory
-
-Agno gives you two ways to manage memories, depending on how much control you want the agent to have:
-
-### Automatic Memory (`update_memory_on_run=True`)
 
-Memories are automatically created and updated after each agent run. Agno handles the extraction, storage, and retrieval behind the scenes. This is the recommended approach for most use cases. It's reliable and predictable.
-
-```python
-from agno.agent import Agent
-from agno.db.sqlite import SqliteDb
-
-# Setup your database
-db = SqliteDb(db_file="agno.db")
-
-# Setup your Agent with Automatic User Memory
-agent = Agent(
-    db=db,
-    update_memory_on_run=True, # Automatic memory management
+agent.print_response(
+    "I prefer email updates and morning meetings.",
+    user_id="sarah",
+    session_id="onboarding",
 )
 
-# Memories are automatically created from this conversation
-agent.print_response("My name is Sarah and I prefer email over phone calls.")
-
-# And automatically recalled here
-agent.print_response("What's the best way to reach me?")
+agent.print_response(
+    "How should you schedule and send my project updates?",
+    user_id="sarah",
+    session_id="project-planning",
+)
 ```
 
-**Best for:** Customer support, personal assistants, conversational apps where you want consistent memory behavior.
+The first run stores useful facts for `sarah`. The second run uses the same `user_id`, so the agent can recall those facts in a different session.
 
-### Agentic Memory (`enable_agentic_memory=True`)
+## How Memory Works
 
-The agent gets full control over memory management through built-in tools. It decides when to create, update, or delete memories based on the conversation context.
+1. `user_id` identifies whose memories should be loaded.
+2. The configured database stores each user's memory records.
+3. Stored memories for that user are added to the model context for later runs.
+4. The selected memory mode controls when records are created, updated, or deleted.
 
-```python
-from agno.agent import Agent
-from agno.db.sqlite import SqliteDb
-
-# Setup your database
-db = SqliteDb(db_file="agno.db")
+Use a stable application user ID for every run that should share the same memories.
 
-# Setup your Agent with Agentic Memory
-agent = Agent(
-    db=db,
-    enable_agentic_memory=True, # This enables Agentic Memory for the Agent
-)
-```
+## Choose a Memory Mode
 
-With agentic memory, the agent is equipped with tools to manage memories when it deems relevant. This gives more flexibility but requires the agent to make intelligent decisions about what to remember.
+| Mode | Configuration | Use it when |
+|------|---------------|-------------|
+| Automatic | `update_memory_on_run=True` | Each user input should be processed into memories automatically |
+| Agentic | `enable_agentic_memory=True` | The model should decide when to inspect, create, update, or delete memories during a run |
 
-**Best for:** Complex workflows, multi-turn interactions where the agent needs to decide what's worth remembering based on context.
+Automatic memory applies one consistent extraction step during each run. Agentic memory adds memory tools to the agent's toolset and lets the model choose when to call them.
 
 <Note>
-**Important:** Don't enable both `update_memory_on_run` and `enable_agentic_memory` at the same time, as they're mutually exclusive. While nothing will break if you set both, `enable_agentic_memory` will always take precedence and `update_memory_on_run` will be ignored.
+When both settings are enabled, agentic memory takes precedence and the automatic extraction step is skipped. Choose one mode for each agent.
 </Note>
 
-## Storage: Where Memories Live
-
-Memories are stored in the database you connect to your agent. Agno supports all major database systems: Postgres, SQLite, MongoDB, and more. Check the [Storage documentation](/database/overview) for the full list of supported databases and setup instructions.
-
-By default, memories are stored in the `agno_memories` table (or collection, for document databases). If this table doesn't exist when your agent first tries to store a memory, Agno creates it automatically with no manual schema setup required.
-
-### Custom Table Names
-
-You can specify a custom table name for storing memories:
-
-```python
-from agno.agent import Agent
-from agno.db.postgres import PostgresDb
-
-# Setup your database
-db = PostgresDb(
-    db_url="postgresql+psycopg://user:password@localhost:5432/my_database",
-    memory_table="my_memory_table", # Specify the table to store memories
-)
-
-# Setup your Agent with the database
-agent = Agent(db=db, update_memory_on_run=True)
+## Memory, History, and State
 
-# Run the Agent. This will store a memory in our "my_memory_table"
-agent.print_response("Hi! My name is John Doe and I like to play basketball on the weekends.")
+| Feature | Stores | Scope | Use it for |
+|---------|--------|-------|------------|
+| Memory | Extracted facts about a user | `user_id` across sessions | Preferences, profile details, recurring goals |
+| [Chat history](/history/overview) | Messages and tool calls from previous runs | `session_id` | Conversational continuity within one thread |
+| [Session state](/state/overview) | Application data managed by code or tools | `session_id` | Carts, task lists, workflow progress, counters |
 
-agent.print_response("What are my hobbies?")
-```
+These features can work together. A support agent can use memory for the customer's communication preference, history for the current ticket, and state for the ticket status.
 
-### Manual Memory Retrieval
+## Store and Inspect Memories
 
-While memories are automatically recalled during conversations, you can also manually retrieve them using the `get_user_memories` method. This is useful for debugging, displaying user profiles, or building custom memory interfaces:
+Memories use the database configured on the agent. The default table or collection name is `agno_memories`. Set `memory_table` on the database when your application needs a custom name.
 
 ```python
-from agno.agent import Agent
-from agno.db.postgres import PostgresDb
-
-# Setup your database
-db = PostgresDb(
-    db_url="postgresql+psycopg://user:password@localhost:5432/my_database",
-    memory_table="my_memory_table", # Specify the table to store memories
-)
-
-# Setup your Agent with the database
-agent = Agent(db=db, update_memory_on_run=True)
-
-# Run the Agent. This will store a memory in our "my_memory_table"
-agent.print_response("I love sushi!", user_id="123")
+memories = agent.get_user_memories(user_id="sarah")
 
-# Retrieve the memories about the user
-memories = agent.get_user_memories(user_id="123")
-print(memories)
+for memory in memories or []:
+    print(memory.memory_id, memory.memory)
 ```
 
-## Memory Data Model
-
-Each memory stored in your database contains the following fields:
-
-| Field        | Type   | Description                                     |
-| ------------ | ------ | ----------------------------------------------- |
-| `memory_id`  | `str`  | The unique identifier for the memory.           |
-| `memory`     | `str`  | The memory content, stored as a string.         |
-| `topics`     | `list` | The topics of the memory.                       |
-| `input`      | `str`  | The input that generated the memory.            |
-| `user_id`    | `str`  | The user ID of the memory.                      |
-| `agent_id`   | `str`  | The agent ID of the memory.                     |
-| `team_id`    | `str`  | The team ID of the memory.                      |
-| `feedback`   | `str`  | Feedback on the memory.                         |
-| `created_at` | `int`  | The timestamp when the memory was created.      |
-| `updated_at` | `int`  | The timestamp when the memory was last updated. |
-
-<Tip>
-View and manage all your memories visually through the [Memories page in AgentOS](https://os.agno.com/memory).
-</Tip>
+Manual retrieval is useful for customer profile screens, debugging, review, and deletion workflows. You can also [manage memories in the AgentOS UI](https://os.agno.com/memory).
 
-## Learn more
+## Next Steps
 
 <CardGroup cols={3}>
-  <Card
-    title="Agent Memory"
-    icon="robot"
-    iconType="duotone"
-    href="/memory/agent/overview"
-  >
-    Store and recall user facts in single agents.
+  <Card title="Agent Memory" icon="robot" iconType="duotone" href="/memory/agent/overview">
+    Configure memory for a single agent.
   </Card>
-  <Card
-    title="Team Memory"
-    icon="users"
-    iconType="duotone"
-    href="/memory/team/overview"
-  >
-    Share memories across team members.
+  <Card title="Team Memory" icon="users" iconType="duotone" href="/memory/team/overview">
+    Share user memories with a team and its members.
   </Card>
-  <Card
-    title="Working with Memories"
-    icon="file-lines"
-    iconType="duotone"
-    href="/memory/working-with-memories/overview"
-  >
-    Customize memory creation, context inclusion, and sharing across agents.
+  <Card title="Working with Memories" icon="file-lines" iconType="duotone" href="/memory/working-with-memories/overview">
+    Customize memory creation, retrieval, and storage.
   </Card>
-  <Card
-    title="Production Best Practices"
-    icon="shield-check"
-    iconType="duotone"
-    href="/memory/best-practices"
-  >
-    Optimize memory for scale and reliability.
+  <Card title="Production Best Practices" icon="shield-check" iconType="duotone" href="/memory/best-practices">
+    Plan user isolation, retention, and memory quality checks.
   </Card>
-</CardGroup>
\ No newline at end of file
+</CardGroup>
diff --git a/sdk/introduction.mdx b/sdk/introduction.mdx
index 2bf0ddded..6bdbba90d 100644
--- a/sdk/introduction.mdx
+++ b/sdk/introduction.mdx
@@ -1,9 +1,10 @@
 ---
-title: Introduction
-description: "Build agents, teams, and workflows in pure Python."
+title: Agno SDK
+sidebarTitle: Introduction
+description: "Build agents, teams, and workflows with memory, knowledge, guardrails, and 100+ integrations."
 ---
 
-Agno is a Python SDK for building multi-agent systems. It gives you three primitives (agents, teams and workflows) and a large set of capabilities you can attach to them. Examples:
+Engineering teams use the Agno SDK to turn agents into products, automate repeatable work, and build multi-agent systems. Start with one agent, add a team when the work needs multiple roles, and use a workflow when execution needs a defined path.
 
 <CodeGroup>
 
@@ -92,15 +93,15 @@ workflow.print_response("Analyze NVIDIA for investment.")
 
 </CodeGroup>
 
-## Three primitives
+## Choose the right primitive
 
-| Primitive | Use it to |
-|-----------|-----------|
-| [Agent](/agents/overview) | Autonomous programs with a model, tools, and instructions |
-| [Team](/teams/overview) | Coordinate multiple agents on a single task |
-| [Workflow](/workflows/overview) | Defined, step-based pipelines over agents, teams, and functions |
+| Primitive | Use it when | What Agno handles |
+|-----------|-------------|-------------------|
+| [Agent](/agents/overview) | One model-driven program can own the task | Context, tool calls, sessions, memory, knowledge, and guardrails |
+| [Team](/teams/overview) | The task benefits from specialist roles or dynamic delegation | Coordination, routing, broadcast, task lists, and nested teams |
+| [Workflow](/workflows/overview) | The process needs repeatable steps, branches, loops, or parallel work | Control flow across agents, teams, functions, and nested workflows |
 
-## Capabilities
+## Add what your use case needs
 
 ### Model and tools
 
@@ -145,17 +146,15 @@ workflow.print_response("Analyze NVIDIA for investment.")
 
 ## From SDK to platform
 
-Agents built using the SDK need to run in a Python process: a script, a notebook, a job.
-
-When you're ready to go live, wrap your agents in **AgentOS** and you get an API server, persistence, auth, tracing, scheduling, and interfaces.
+Register the same agents, teams, and workflows with AgentOS to run them behind a FastAPI application. AgentOS provides REST APIs and runtime support for persistence, authorization, tracing, background execution, scheduling, and interfaces.
 
 ## Where to start
 
 <CardGroup cols={2}>
-  <Card title="Install & Setup" icon="rocket" iconType="duotone" href="/sdk/setup">
-    Install Agno and run your first agent.
+  <Card title="Build your first agent" icon="rocket" iconType="duotone" href="/sdk/setup">
+    Install Agno, configure a model, and run an agent locally.
   </Card>
   <Card title="Run on AgentOS" icon="server" iconType="duotone" href="/agent-os/introduction">
-    Run your agent as a service.
+    Serve your agents, teams, and workflows through an API.
   </Card>
 </CardGroup>
diff --git a/sessions/overview.mdx b/sessions/overview.mdx
index 2017bccd9..81bb19766 100644
--- a/sessions/overview.mdx
+++ b/sessions/overview.mdx
@@ -1,86 +1,89 @@
 ---
 title: Sessions
 sidebarTitle: Overview
-description: Multi-turn conversation threads with persistent history and state.
+description: Group related runs under a stable session ID, with database-backed history and state.
 keywords: [sessions, session, session id, run]
 ---
 
-When you call `Agent.run()`, it creates a single, stateless interaction. The agent responds to your message with no memory of what came before.
+Product agents use sessions to keep each conversation thread separate and continue it across requests. A stable `session_id` groups related runs, while `user_id` associates the thread with the person using your product.
 
-Most real applications need multi-turn **conversations**, and that's what sessions give you.
+```python support_agent.py
+from agno.agent import Agent
+from agno.db.sqlite import SqliteDb
+from agno.models.openai import OpenAIResponses
 
-## What's a Session?
+agent = Agent(
+    model=OpenAIResponses(id="gpt-5.4-mini"),
+    db=SqliteDb(db_file="tmp/support.db"),
+    add_history_to_context=True,
+    num_history_runs=3,
+)
+
+agent.print_response(
+    "My order number is ORD-123.",
+    user_id="customer-42",
+    session_id="support-thread-7",
+)
+
+agent.print_response(
+    "Which order are we discussing?",
+    user_id="customer-42",
+    session_id="support-thread-7",
+)
+```
 
-A session is a conversation thread: a collection of multi-turn interactions (called "runs") between a user and your Agent, Team, or Workflow. Each session gets a unique `session_id` that ties together all the runs, chat history, state, and metrics for that conversation.
+The database stores both runs under `support-thread-7`. On the second run, `add_history_to_context=True` loads messages from the same session into the model context.
 
-Key concepts:
+## IDs and Persistence
 
-- **Session**: A multi-turn conversation identified by a `session_id`. Contains all the runs, history, state, and metrics for that conversation thread.
-- **Run**: A single interaction within a session. Every time you call `Agent.run()`, `Team.run()`, or `Workflow.run()`, a new `run_id` is created. One run is one message-and-response pair in the conversation.
-Runs can pause for human-in-the-loop requirements and continue after those requirements are resolved.
+| Value | Purpose | Generation |
+|-------|---------|------------|
+| `run_id` | Identifies one execution | Agno generates a new value for every run unless you provide one |
+| `session_id` | Groups related runs into one thread | Agno generates one when the Agent instance first runs without a supplied value, then reuses it on that instance |
+| `user_id` | Associates a run and session with a user | Your application supplies it, or the agent uses its configured default |
 
-<Note>
-Sessions require a database to store history and state. See [Session Storage](/database/overview) for setup details.
-</Note>
+An ID labels a run or thread. A configured database provides durable storage.
 
-<Note>
-**Workflow sessions work differently:** Unlike agent and team sessions that store conversation messages, workflow sessions track complete pipeline executions (runs) with inputs and outputs. Because of these unique characteristics, we've created a [dedicated Workflow Sessions section](/sessions/workflow-sessions) that covers workflow-specific features like run-based history, session state, and workflow agents.
-</Note>
+## Persistence and Model Context
 
-## Single-Run Example
+Session storage and chat history serve separate purposes:
 
-When you run an agent without specifying a `session_id`, Agno automatically generates both a `run_id` and a `session_id` for you:
+| Configuration | Effect |
+|---------------|--------|
+| `db=...` | Persists session records, runs, state, and stored messages |
+| `add_history_to_context=True` | Adds messages from previous runs in the session to the next model request |
+| `num_history_runs=N` | Limits history by run count |
+| `num_history_messages=N` | Limits history by message count |
+| `session_state={...}` | Stores application state with the session |
 
-```python
-from agno.agent import Agent
-from agno.models.openai import OpenAIResponses
-
-agent = Agent(model=OpenAIResponses(id="gpt-5.2"))
+`add_history_to_context` defaults to `False`. Configure it when the model needs conversational continuity. See [Chat History](/history/overview) for message selection and storage controls.
 
-# Run the agent - Agno auto-generates session_id and run_id
-response = agent.run("Tell me a 5 second short story about a robot")
-print(response.content)
-print(f"Run ID: {response.run_id}")        # Auto-generated UUID
-print(f"Session ID: {response.session_id}") # Auto-generated UUID
-```
+## Multi-User Applications
 
-This creates a new session with a single run. But here's the catch: without a database configured, there's no persistence. The `session_id` exists for this single run, but you can't continue the conversation later because nothing is saved. To actually use sessions for multi-turn conversations, you need to configure a database (even an `InMemoryDb` works).
+Use IDs from your application instead of sharing one generated session across customers:
 
-## Multi-User Conversations
+| Product concept | Agno value |
+|-----------------|------------|
+| Account or customer | `user_id` |
+| Chat thread, ticket, or workspace conversation | `session_id` |
+| One request and response cycle | `run_id` |
 
-In production, multiple users often talk to the same agent or team simultaneously. Sessions keep those threads isolated:
+A user can have multiple session IDs, such as separate support tickets or chat tabs. Reuse a session ID only for runs that belong to the same thread.
 
-- `user_id` distinguishes the person using your product.
-- `session_id` distinguishes conversation threads for that user (think "chat tabs").
-- Conversation history only flows into the run when you enable it via [`add_history_to_context`](/history/agent/overview#add-history-to-the-agent-context).
+## Workflow Sessions
 
-For a full walkthrough that includes persistence, history, and per-user session IDs, follow the [Session Management guide](/sessions/session-management) or the [History guide](/history/overview).
+Agent and team sessions store conversational runs and messages. Workflow sessions track pipeline executions with their inputs, outputs, and state. See [Workflow Sessions](/sessions/workflow-sessions) for workflow-specific behavior.
 
-## Learn more
+## Next Steps
 
 <CardGroup cols={3}>
-  <Card
-    title="Session Management"
-    icon="tag"
-    iconType="duotone"
-    href="/sessions/session-management"
-  >
-    Manage session IDs, names, and performance for agents and teams.
+  <Card title="Session Management" icon="tag" iconType="duotone" href="/sessions/session-management">
+    Assign IDs and manage agent and team sessions.
   </Card>
-  <Card
-    title="History Management"
-    icon="clock-rotate-left"
-    iconType="duotone"
-    href="/sessions/history-management"
-  >
-    Control how conversation history flows into context.
+  <Card title="History Management" icon="clock-rotate-left" iconType="duotone" href="/sessions/history-management">
+    Control which previous messages enter model context.
   </Card>
-  <Card
-    title="Session Summaries"
-    icon="file-lines"
-    iconType="duotone"
-    href="/sessions/session-summaries"
-  >
-    Condense long conversations to reduce token costs.
+  <Card title="Session Summaries" icon="file-lines" iconType="duotone" href="/sessions/session-summaries">
+    Condense long conversations to manage context size.
   </Card>
 </CardGroup>
diff --git a/tools/overview.mdx b/tools/overview.mdx
index a8ef71e62..9fe870774 100644
--- a/tools/overview.mdx
+++ b/tools/overview.mdx
@@ -1,565 +1,143 @@
 ---
 title: What are Tools?
 sidebarTitle: Overview
-description: Tools are functions Agents call to interact with external systems.
+description: Give agents functions they can call to read data and take actions in external systems.
 ---
 
-Tools are what make Agents and Teams capable of real-world action. While using LLMs directly you can only generate text responses, Agents and Teams equipped with tools can interact with external systems and perform practical actions.
-Tools can require confirmation. When that happens, the run pauses until the requirement is resolved.
-
-Some examples of actions that can be performed with tools are: searching the web, running SQL, sending an email or calling APIs.
-
-Agno comes with 120+ pre-built toolkits, which you can use to give your Agents all kinds of abilities. You can also write your own tools to give your Agents even more capabilities. The general syntax is:
-
-```python
-import random
+Agents use tools to take actions, like looking up records, calling APIs, updating systems, and completing work for users. Add a Python function or toolkit to `tools`, and the model can select it when a request requires it.
 
+```python order_agent.py
 from agno.agent import Agent
 from agno.models.openai import OpenAIResponses
 
-def get_weather(city: str) -> str:
-    """Get the weather for the given city.
-
-    Args:
-        city (str): The city to get the weather for.
-    """
-
-    # In a real implementation, this would call a weather API
-    weather_conditions = ["sunny", "cloudy", "rainy", "snowy", "windy"]
-    random_weather = random.choice(weather_conditions)
-
-    return f"The weather in {city} is {random_weather}."
-
-# To equip our Agent with our tool, we simply pass it with the tools parameter
-agent = Agent(
-    model=OpenAIResponses(id="gpt-5.2"),
-    tools=[get_weather],
-    markdown=True,
-)
-
-# Our Agent will now be able to use our tool, when it deems it relevant
-agent.print_response("What is the weather in San Francisco?", stream=True)
-```
-
-<Tip>
-In the example above, the `get_weather` function is a tool. When called, the tool result is shown in the output.
-</Tip>
-
-
-## How do tools work?
-
-The heart of Agent execution is the LLM loop. The typical execution flow of the LLM loop is:
-1. The agent sends the run context (system message, user message, chat history, etc) and tool definitions to the model.
-2. The model responds with a message or a tool call.
-3. If the model makes a tool call, the tool is executed and the result is returned to the model.
-4. The model processes the updated context, repeating this loop until it produces a final message without any tool calls.
-5. The agent returns this final response to the caller.
-
-### Tool definitions
 
-Agno automatically converts your tool functions into the required tool definition format for the model. Typically this is a JSON schema that describes the parameters and return type of the tool.
-
-For example:
-
-```python
-def get_weather(city: str) -> str:
-    """
-    Get the weather for a given city.
+def lookup_order(order_id: str) -> dict:
+    """Return the status and delivery date for an order.
 
     Args:
-        city (str): The city to get the weather for.
+        order_id: The order ID to look up.
     """
-    return f"The weather in {city} is sunny."
-```
-
-This will be converted into the following tool definition:
-
-```json
-{
-    "type": "function",
-    "function": {
-        "name": "get_weather",
-        "description": "Get the weather for a given city.",
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "city": {
-                    "type": "string",
-                    "description": "The city to get the weather for."
-                }
-            },
-            "required": ["city"]
-        }
+    return {
+        "order_id": order_id,
+        "status": "shipped",
+        "delivery_date": "2026-07-22",
     }
-}
-```
-
-This tool definition is then sent to the model so that it knows how to call the tool when it is requested.
-You'll notice as well that the `Args` section is automatically stripped from the definition, parsed and used to populate the definitions of individual properties.
 
-When using a Pydantic model in an argument of a tool function, Agno will automatically convert the model into the required tool definition format.
-
-For example:
-
-```python
-
-from pydantic import BaseModel, Field
-
-class GetWeatherRequest(BaseModel):
-    city: str = Field(description="The city to get the weather for")
-
-def get_weather(request: GetWeatherRequest) -> str:
-    """
-    Get the weather for a given city.
-
-    Args:
-        request (GetWeatherRequest): The request object containing the city to get the weather for.
 
-    """
-    return f"The weather in {request.city} is sunny."
-```
+agent = Agent(
+    model=OpenAIResponses(id="gpt-5.4-mini"),
+    tools=[lookup_order],
+    instructions="Use the order tool when a customer asks about a delivery.",
+)
 
-This will be converted into the following tool definition:
-
-```json
-{
-    "type": "function",
-    "function": {
-        "name": "get_weather",
-        "description": "Get the weather for a given city.",
-        "parameters": {
-            "type": "object",
-            "properties": {
-              "request": {
-                "type": "object",
-                "properties": {
-                  "city": {
-                    "type": "string",
-                    "description": "The city to get the weather for."
-                  }
-                },
-                "required": ["city"]
-              }
-            },
-            "required": ["request"]
-        }
-    }
-}
+agent.print_response("When will order ORD-123 arrive?")
 ```
 
-<Tip>
- - Always create a docstring for your tool functions. Make sure to include the `Args` section and cover each of the arguments of the function.
- - Use sensible names for your tool functions. Remember this is directly used by the model to call the tool when it is requested.
-</Tip>
+Agno builds a tool definition from the function name, docstring, and type hints. The model receives that definition, chooses the tool and arguments, then uses the result to produce its response.
 
-### Tool Execution
+## Choose a Tool Source
 
-When the model requests a tool call, the tool is executed and the result is returned to the model.
+| Use case | Tool source |
+|----------|-------------|
+| Call application code or an internal API | [Python function](/tools/creating-tools/python-functions) |
+| Add a packaged integration with related operations | [Toolkit](/tools/toolkits/overview) |
+| Connect to a service exposed through Model Context Protocol | [MCPTools](/tools/mcp/overview) |
+| Give an agent a compact interface to a complex external system | [Context Provider](/context-providers/overview) |
+| Select tools for each user or session at run time | [Callable factory](/agents/building-agents#callable-factories) |
 
-- A model can request multiple tool calls in a single response.
-- When using `arun` to execute the agent or team, and the model requests multiple tool calls, the tools will be executed concurrently.
+## Tool Execution
 
-Agno Agents can execute multiple tools concurrently, allowing you to process function calls that the model makes efficiently. This is especially valuable when the functions involve time-consuming operations. It improves responsiveness and reduces overall execution time.
+The execution flow:
 
-<Check>
-When you call `arun` or `aprint_response`, your tools will execute concurrently. If you provide synchronous functions as tools, they will execute concurrently on separate threads.
-</Check>
+1. The agent sends the model its context and available tool definitions.
+2. The model returns a response or requests one or more tool calls.
+3. Agno validates the arguments and executes each requested tool.
+4. Tool results are added to the model context.
+5. The loop continues until the model returns a final response.
 
-<Note>
-  Concurrent execution of tools requires a model that supports parallel function
-  calling. For example, OpenAI models have a `parallel_tool_calls` parameter
-  (enabled by default) that allows multiple tool calls to be requested and
-  executed simultaneously.
-</Note>
+When a model requests multiple tool calls, `arun()` and `aprint_response()` can execute them concurrently. The selected model must support parallel tool calls.
 
-<Accordion title="Async Execution Example">
+## Design Tools for Reliable Calls
 
-```python async_tools.py
-import asyncio
-import time
+The model uses the tool schema to decide when and how to call a function.
 
-from agno.agent import Agent
-from agno.models.openai import OpenAIResponses
-from agno.utils.log import logger
+| Practice | Why it matters |
+|----------|----------------|
+| Use a specific function name | Helps the model select the correct operation |
+| Write a concise docstring | Explains when the tool should be used |
+| Add type hints and argument descriptions | Produces a precise input schema |
+| Expose only the tools needed for the task | Reduces ambiguous choices and limits access |
+| Return structured, relevant results | Gives the model useful context for its response |
 
-async def atask1(delay: int):
-    """Simulate a task that takes a random amount of time to complete
-    Args:
-        delay (int): The amount of time to delay the task
-    """
-    logger.info("Task 1 has started")
-    for _ in range(delay):
-        await asyncio.sleep(1)
-        logger.info("Task 1 has slept for 1s")
-    logger.info("Task 1 has completed")
-    return f"Task 1 completed in {delay:.2f}s"
+Use `include_tools` and `exclude_tools` to limit operations exposed by a toolkit. See [Including and Excluding Tools](/tools/selecting-tools).
 
+## Control Tool Execution
 
-async def atask2(delay: int):
-    """Simulate a task that takes a random amount of time to complete
-    Args:
-        delay (int): The amount of time to delay the task
-    """
-    logger.info("Task 2 has started")
-    for _ in range(delay):
-        await asyncio.sleep(1)
-        logger.info("Task 2 has slept for 1s")
-    logger.info("Task 2 has completed")
-    return f"Task 2 completed in {delay:.2f}s"
-
-
-async def atask3(delay: int):
-    """Simulate a task that takes a random amount of time to complete
-    Args:
-        delay (int): The amount of time to delay the task
-    """
-    logger.info("Task 3 has started")
-    for _ in range(delay):
-        await asyncio.sleep(1)
-        logger.info("Task 3 has slept for 1s")
-    logger.info("Task 3 has completed")
-    return f"Task 3 completed in {delay:.2f}s"
-
-
-async_agent = Agent(
-    model=OpenAIResponses(id="gpt-5.2"),
-    tools=[atask2, atask1, atask3],
-    markdown=True,
-)
-
-asyncio.run(
-    async_agent.aprint_response("Please run all tasks with a delay of 3s", stream=True)
-)
-```
+| Requirement | Configuration |
+|-------------|---------------|
+| Limit calls during one run | Set [`tool_call_limit`](/tools/tool-call-limit) |
+| Review a sensitive action | Mark the tool with [`requires_confirmation=True`](/hitl/user-confirmation) |
+| Collect missing fields from a user | Use [`requires_user_input=True`](/hitl/user-input) |
+| Execute an operation in your application | Use [`external_execution=True`](/hitl/external-execution) |
+| Handle failures from custom tools | Configure [tool exceptions](/tools/exceptions) |
 
-In this example, `gpt-5.2` makes three simultaneous tool calls to `atask1`, `atask2` and `atask3`. Normally these tool calls would execute sequentially, but using the `aprint_response` function, they run concurrently, improving execution time.
-
-<img
-  height="200"
-  src="/images/async-tools.png"
-  style={{ borderRadius: "8px" }}
-/>
-
-</Accordion>
-
-## Using a Toolkit
-
-An Agno Toolkit provides a way to manage multiple tools with additional control over their execution.
-
-```python
-from agno.agent import Agent
-from agno.models.openai import OpenAIResponses
-from agno.tools.hackernews import HackerNewsTools
-
-agent = Agent(
-    model=OpenAIResponses(id="gpt-5.2"),
-    tools=[
-        HackerNewsTools(),
-    ],
-)
-
-agent.print_response("What are the top stories on HackerNews?", markdown=True)
-```
-
-In this example, the `HackerNewsTools` toolkit is added to the agent. This toolkit enables the agent to fetch stories from HackerNews.
+Runs with human-in-the-loop requirements pause until your application resolves the active requirement and continues the run.
 
 ## Tool Built-in Parameters
 
-Agno automatically provides special parameters to your tools that give access to the agent's parameters, state and other variables. Agno strips these parameters from the tool definition sent to the model and injects the values at execution time, so the model never sees them.
+Agno strips built-in parameters from the schema sent to the model and injects them when the tool runs.
 
-### Using the Run Context
+| Parameter | Use |
+|-----------|-----|
+| `run_context` | Access the current user, session state, dependencies, metadata, and knowledge filters |
+| `agent` | Access the active Agent from an agent tool |
+| `team` | Access the active Team from a team tool |
+| `images`, `videos`, `audios`, `files` | Access media attached to the run |
 
-You can access values from the current run via the `run_context` parameter: `run_context.session_state`, `run_context.dependencies`, `run_context.knowledge_filters`, `run_context.metadata`. See the [RunContext schema](/reference/run/run-context).
+### Access Run Context
 
-This allows tools to access and modify persistent data across conversations.
-
-This is useful in cases where a tool result is relevant for the next steps of the conversation.
-
-Add `run_context` as a parameter in your tool function to access the agent's persistent state:
+Add a `run_context: RunContext` parameter when a tool needs the current user, session state, dependencies, metadata, or knowledge filters. Agno injects the value at execution time and omits it from the schema sent to the model.
 
 ```python
-from agno.agent import Agent
-from agno.db.sqlite import SqliteDb
-from agno.models.openai import OpenAIResponses
 from agno.run import RunContext
 
 
 def add_item(run_context: RunContext, item: str) -> str:
-    """Add an item to the shopping list."""
-    if not run_context.session_state:
+    """Add an item to the current session's shopping list."""
+    if run_context.session_state is None:
         run_context.session_state = {}
-
-    run_context.session_state["shopping_list"].append(item)  # type: ignore
-    return f"The shopping list is now {run_context.session_state['shopping_list']}"  # type: ignore
-
-
-# Create an Agent that maintains state
-agent = Agent(
-    model=OpenAIResponses(id="gpt-5.2"),
-    # Initialize the session state with a counter starting at 0 (this is the default session state for all users)
-    session_state={"shopping_list": []},
-    db=SqliteDb(db_file="tmp/agents.db"),
-    tools=[add_item],
-    # You can use variables from the session state in the instructions
-    instructions="Current state (shopping list) is: {shopping_list}",
-    markdown=True,
-)
-
-# Example usage
-agent.print_response("Add milk, eggs, and bread to the shopping list", stream=True)
-print(f"Final session state: {agent.get_session_state()}")
-```
-
-See more in [Agent State](/state/agent/overview).
-
-### Using the Agent or Team
-
-You can access the `Agent` or `Team` instance directly in your tool function by adding `agent` or `team` as a parameter. This gives you full access to the agent's or team's properties like model, instructions, etc.
-
-```python
-from agno.agent import Agent
-from agno.models.openai import OpenAIResponses
-
-def get_agent_instructions(agent: Agent) -> str:
-    """Get the instructions of the agent."""
-    return agent.instructions
-
-agent = Agent(
-    model=OpenAIResponses(id="gpt-5.2"),
-    instructions="You are a helpful assistant that can answer questions about the agent.",
-    tools=[get_agent_instructions],
-)
-
-agent.print_response("What are the instructions of the agent?", stream=True)
+    shopping_list = run_context.session_state.setdefault("shopping_list", [])
+    shopping_list.append(item)
+    return f"Shopping list: {shopping_list}"
 ```
 
-<Note>
-When using `team` as a parameter, make sure the tool is being used within a Team context. Similarly, use `agent` when the tool is used with an Agent.
-</Note>
+See the [RunContext reference](/reference/run/run-context) and [State Management](/state/overview).
 
-### Media Parameters
+## Return Tool Results
 
-The built-in parameters `images`, `videos`, `audios`, and `files` allow tools to access and modify the input media to an agent.
-
-<Note>
-Using the `send_media_to_model` parameter, you can control whether the media is sent to the model or not and using `store_media` parameter, you can control whether the
-media is stored in the `RunOutput` or not.
-</Note>
-
-See the [legacy image input reference](/multimodal/agent/usage/image-input-for-tool) and [file input example](/multimodal/agent/usage/file-input-for-tool) for advanced media patterns.
-
-## Tool Results
-
-Tools can return different types of results depending on their complexity and what they need to communicate back to the agent.
-
-### Simple Return Types
-
-Most tools can return simple Python types directly like `str`, `int`, `float`, `dict`, and `list`:
-
-```python
-from agno.tools import tool
-
-@tool
-def get_weather(city: str) -> str:
-    """Get the weather for a city."""
-    return f"The weather in {city} is sunny and 75°F"
-
-@tool
-def calculate_sum(a: int, b: int) -> int:
-    """Calculate the sum of two numbers."""
-    return a + b
-
-@tool
-def get_user_info(user_id: str) -> dict:
-    """Get user information."""
-    return {
-        "user_id": user_id,
-        "name": "John Doe",
-        "email": "john@example.com",
-        "status": "active"
-    }
-
-@tool
-def search_products(query: str) -> list:
-    """Search for products."""
-    return [
-        {"id": 1, "name": "Product A", "price": 29.99},
-        {"id": 2, "name": "Product B", "price": 39.99}
-    ]
-```
-
-### `ToolResult` for Media Content
-
-When your tool needs to return media artifacts (images, videos, audio), you **must** use `ToolResult`:
+Functions can return strings, numbers, dictionaries, lists, and other serializable values. Use `ToolResult` when a tool needs to return media or files alongside text.
 
 <Snippet file="tool-result-reference.mdx" />
 
-```python
-from agno.media import Image
-from agno.tools import tool
-from agno.tools.function import ToolResult
-
-@tool
-def generate_image(prompt: str) -> ToolResult:
-    """Generate an image from a prompt."""
-
-    # Create your image (example)
-    image_artifact = Image(
-        id="img_123",
-        url="https://example.com/generated-image.jpg",
-        original_prompt=prompt
-    )
-
-    return ToolResult(
-        content=f"Generated image for: {prompt}",
-        images=[image_artifact]
-    )
-```
-
-This would **make generated media available** to the LLM model.
-
-## Callable Factories
-
-Agno tools support callable factory pattern for dynamic configuration. Implement a dynamic tool factory using callables for runtime dependency injection and context-aware toolset customization.
-
-* **Runtime Resolution:** Tools are lazily initialized at the start of each run via signature-based injection.
-
-* **Context Injection:** Automatically maps `agent`/`team`, `run_context`, and `session_state` to the factory parameters.
-
-* **Granular Scoping:** Enables unique tool sets tailored specifically to the `user_id` or `session_id`.
-
-* **Performance Optimization:** Includes built-in caching (`cache_callables`) to memoize toolsets based on unique session keys.
-
-
-| Parameters | Purpose |
-| --- | --- |
-| `agent` | Accesses the base agent instance/configuration.|
-| `run_context` | Provides metadata like user_id for scoping tools.|
-| `session_state` | Allows tools to be shaped by current conversation memory.|
-
-```python
-from agno.agent import Agent
-from agno.models.openai import OpenAIResponses
-from agno.run import RunContext
-
-# ---------------------------------------------------------------------------
-# Tools
-# ---------------------------------------------------------------------------
-
-
-def search_web(query: str) -> str:
-    """Search the web for information."""
-    return f"Search results for: {query}"
-
-
-def search_internal_docs(query: str) -> str:
-    """Search internal documentation (admin only)."""
-    return f"Internal doc results for: {query}"
-
-
-def get_account_balance(account_id: str) -> str:
-    """Get account balance (finance only)."""
-    return f"Balance for {account_id}: $42,000"
-
-
-# ---------------------------------------------------------------------------
-# Callable Factory
-# ---------------------------------------------------------------------------
-
-
-def tools_for_user(run_context: RunContext):
-    """Return different tools based on the user's role stored in session_state."""
-    role = (run_context.session_state or {}).get("role", "viewer")
-    print(f"--> Resolving tools for role: {role}")
-
-    base_tools = [search_web]
-    if role == "admin":
-        base_tools.append(search_internal_docs)
-    if role in ("admin", "finance"):
-        base_tools.append(get_account_balance)
-
-    return base_tools
-
-
-# ---------------------------------------------------------------------------
-# Create Agent
-# ---------------------------------------------------------------------------
-agent = Agent(
-    model=OpenAIResponses(id="gpt-5-mini"),
-    tools=tools_for_user,
-    instructions=[
-        "You are a helpful assistant.",
-        "Use the tools available to you to answer the user's question.",
-    ],
-)
-
-
-# ---------------------------------------------------------------------------
-# Run Agent
-# ---------------------------------------------------------------------------
-if __name__ == "__main__":
-    # Run 1: viewer role - only search_web available
-    # Each user_id gets its own cached toolset
-    print("=== Run as viewer ===")
-    agent.print_response(
-        "Search for recent news about AI agents",
-        user_id="viewer_user",
-        session_state={"role": "viewer"},
-        stream=True,
-    )
-
-    # Run 2: admin role - all tools available
-    # Different user_id means the factory is called again with new context
-    print("\n=== Run as admin ===")
-    agent.print_response(
-        "Search internal docs for the deployment guide and check account balance for ACC-001",
-        user_id="admin_user",
-        session_state={"role": "admin"},
-        stream=True,
-    )
-```
-
-## Learn more
+## Next Steps
 
 <CardGroup cols={3}>
-  <Card title="Agent Tools" href="/tools/agent"
-  icon="robot"
-  iconType="duotone"
-  >
-    Equip agents with tools for external actions
+  <Card title="Agent Tools" href="/tools/agent" icon="robot" iconType="duotone">
+    Add functions and toolkits to an agent.
   </Card>
-  <Card title="Updating an Agent's Tools" href="/tools/attaching-tools"
-  icon="users"
-  iconType="duotone"
-  >
-    Add or update tools after initialization
+  <Card title="Available Toolkits" icon="box-open" href="/tools/toolkits/overview">
+    Browse integrations by data source and operation.
   </Card>
-  <Card
-    title="Available Toolkits"
-    icon="box-open"
-    href="/tools/toolkits/overview"
-  >
-    Browse 120+ pre-built toolkits
+  <Card title="Create Tools" icon="code" href="/tools/creating-tools/overview">
+    Build Python functions and reusable toolkits.
   </Card>
-  <Card
-    title="MCP Tools"
-    icon="robot"
-    href="/tools/mcp/overview"
-  >
-    Connect to Model Context Protocol servers
+  <Card title="MCP Tools" icon="plug" href="/tools/mcp/overview">
+    Connect agents to Model Context Protocol servers.
   </Card>
-  <Card
-    title="Reasoning Tools"
-    icon="brain-circuit"
-    href="/tools/reasoning_tools/reasoning-tools"
-  >
-    Give agents think and analyze tools for step-by-step reasoning
+  <Card title="Update Tools" href="/tools/attaching-tools" icon="sliders">
+    Add or replace tools after initialization.
   </Card>
-  <Card
-    title="Creating your own tools"
-    icon="code"
-    href="/tools/creating-tools/overview"
-  >
-    Write custom Python functions as tools
+  <Card title="Tool Hooks" href="/tools/hooks" icon="code-branch">
+    Run logic before and after tool calls.
   </Card>
 </CardGroup>
diff --git a/tracing/overview.mdx b/tracing/overview.mdx
index 828f82ce1..6409ce338 100644
--- a/tracing/overview.mdx
+++ b/tracing/overview.mdx
@@ -1,157 +1,140 @@
 ---
 title: Tracing
-description: Trace agent, team, and workflow runs with OpenTelemetry and store the spans in your own database
+description: Trace agent, team, and workflow runs with OpenTelemetry and store spans in a configured database or observability backend.
 sidebarTitle: Overview
 keywords: [tracing, observability, opentelemetry, debugging, monitoring]
 ---
 
 <Badge icon="code-branch" color="orange">
-    <Tooltip tip="Introduced in v2.3.5" cta="View release notes" href="https://github.com/agno-agi/agno/releases/tag/v2.3.5">v2.3.5</Tooltip>
+  <Tooltip tip="Introduced in v2.3.5" cta="View release notes" href="https://github.com/agno-agi/agno/releases/tag/v2.3.5">v2.3.5</Tooltip>
 </Badge>
 
-In the systems you build with Agno, agents will make autonomous decisions, interact with external tools, and coordinate with each other in ways that aren't immediately visible from your recorded sessions alone. Observability is key to staying on top of what your agents are doing and how your system is performing.
+A final run response shows the outcome. Tracing shows the model calls, tool executions, and nested agent, team, or workflow operations that produced it. Developers use traces to investigate failures, latency, token usage, and unexpected tool behavior.
 
-**Agno Tracing** is the recommended way to introduce observability for your Agno agents, teams, and workflows. 
-It automatically captures all relevant execution details, helping you understand what your agents are doing, simplifying debugging and helping you optimize your system.
+## Trace an Agent
 
-Tracing uses [OpenTelemetry](https://opentelemetry.io/) to instrument Agno agents, teams, and workflows, capturing traces and spans.
+<Steps>
+  <Step title="Install tracing dependencies">
+    ```bash
+    uv pip install -U "agno[os]" openai opentelemetry-api opentelemetry-sdk openinference-instrumentation-agno
+    ```
+  </Step>
 
-<Frame caption="Traces stored in SQLite database viewed with AgentOS">
-  <img src="/images/traces-in-os.png" alt="Traces viewed in AgentOS" />
-</Frame>
+  <Step title="Configure database export">
+    Call `setup_tracing()` once at application startup, before creating agents.
 
-## Why is Observability Important?
+    ```python tracing_agent.py
+    from agno.agent import Agent
+    from agno.db.sqlite import SqliteDb
+    from agno.models.openai import OpenAIResponses
+    from agno.tracing import setup_tracing
 
-As your Agno system becomes more complex (Agents using multiple tools, making sequential decisions, and coordinating with other agents), understanding its behavior becomes challenging. 
+    traces_db = SqliteDb(db_file="tmp/traces.db")
+    setup_tracing(db=traces_db)
 
-**Agno Tracing** solves this:
+    agent = Agent(
+        id="support-agent",
+        model=OpenAIResponses(id="gpt-5.4-mini"),
+        instructions="Answer support questions concisely.",
+    )
 
-- **Debugging**: See exactly what went wrong when an agent fails
-- **Performance**: Identify bottlenecks in agent execution
-- **Cost Tracking**: Monitor token usage and API calls
-- **Behavior Analysis**: Understand decision-making patterns
-- **Audit Trail**: Track what agents did and why
+    agent.run("Summarize the latest support request.")
+    ```
+  </Step>
 
-<Note>
-All Agno Tracing data is stored in your own database. No tracing data will leave your system, or be sent to third parties: you are in complete control.
-</Note>
+  <Step title="Query stored traces">
+    ```python
+    traces, total = traces_db.get_traces(agent_id="support-agent", limit=10)
 
-## Understanding Traces and Spans
+    for trace in traces:
+        print(trace.name, trace.duration_ms)
+    ```
+  </Step>
+</Steps>
 
-Traces and spans form a parent-child hierarchy that mirrors your agent's execution:
+`setup_tracing(db=...)` installs Agno's `DatabaseSpanExporter` and instruments agents, teams, and workflows through OpenTelemetry.
 
-### Trace
-A **trace** represents one complete agent execution from start to finish. Each trace has a unique `trace_id` that groups all related operations together.
+<Frame caption="Traces stored in SQLite and viewed in AgentOS">
+  <img src="/images/traces-in-os.png" alt="Traces viewed in AgentOS" />
+</Frame>
 
-### Span
-A **span** is a single operation within that execution. Spans form a parent-child hierarchy:
+## Traces and Spans
 
-<img 
-  className="block dark:hidden" 
-  src="/images/traces-vs-spans-light.png" 
-  alt="Traces vs spans diagram"
-/>
+| Concept | Description |
+|---------|-------------|
+| Trace | One complete execution, identified by `trace_id` |
+| Span | One timed operation within the trace, such as an agent run, model response, or tool execution |
+| Parent-child relationship | Connects nested operations into the execution hierarchy |
 
-<img 
-  className="hidden dark:block" 
-  src="/images/traces-vs-spans-dark.png" 
-  alt="Traces vs spans diagram"
+<img
+  className="block dark:hidden"
+  src="/images/traces-vs-spans-light.png"
+  alt="Trace and span hierarchy"
 />
 
-Each span captures:
-- **What happened**: Operation name (e.g., `agent.run`, `model.response`)
-- **When**: Start and end timestamps
-- **Context**: Input arguments, outputs, token usage
-- **Relationships**: Parent span, child spans
-- **Metadata**: Agent ID, session ID, run ID
+<img
+  className="hidden dark:block"
+  src="/images/traces-vs-spans-dark.png"
+  alt="Trace and span hierarchy"
+/>
 
 ## What Gets Traced
 
-Agno automatically captures:
+Agno instrumentation captures spans for:
 
-| Operation          | What Gets Traced                                                                 |
-|--------------------|---------------------------------------------------------------------------------|
-| **Agent Runs**     | Every `agent.run()` or `agent.arun()` call with full context                    |
-| **Model Calls**    | LLM interactions including prompts, responses, and token usage                  |
-| **Tool Executions**| Tool invocations with arguments and results                                     |
-| **Team Operations**| Team coordination and member agent runs                                         |
-| **Workflow Operations**| Workflow coordination and step runs                                         |
+| Operation | Examples |
+|-----------|----------|
+| Agent runs | `agent.run()` and `agent.arun()` |
+| Model calls | Model requests and responses |
+| Tool execution | Tool calls and results |
+| Team execution | Leader coordination and member runs |
+| Workflow execution | Workflow runs and step execution |
 
+Spans carry timing, status, relationships, and operation attributes. Trace payloads can include application inputs and outputs. Review captured attributes before sending traces to a shared or external destination.
 
-## Key Features
+## Choose a Trace Destination
 
-- **Zero-Code Instrumentation**: No need to modify your agent code
-- **Database Storage**: Traces stored in your Agno database (SQLite, PostgreSQL, etc.)
-- **Flexible Querying**: Filter by agent, session, run, or time range
-- **OpenTelemetry Standard**: Export to external tools like Arize Phoenix, Langfuse, and The Context Company
-- **Low Overhead**: Set `batch_processing=True` to batch and export traces in the background
-- **Configurable**: Adjust batch sizes and processing for your needs
+Tracing storage follows the OpenTelemetry configuration in your application:
 
-## Quick Start
+| Configuration | Destination |
+|---------------|-------------|
+| `setup_tracing(db=...)` | The selected Agno database through `DatabaseSpanExporter` |
+| `AgentOS(..., tracing=True, db=...)` | The AgentOS database, available through its API and Control Plane |
+| A custom OpenTelemetry provider instrumented with `AgnoInstrumentor` | The backend configured by that provider's exporter |
 
-<Steps>
-  <Step title="Install Dependencies">
-    ```bash
-    uv pip install -U openai agno sqlalchemy opentelemetry-api opentelemetry-sdk openinference-instrumentation-agno
-    ```
-  </Step>
-  
-  <Step title="Enable Tracing">
-    ```python
-    from agno.tracing import setup_tracing
-    from agno.db.sqlite import SqliteDb
+Use [Agno OpenTelemetry integrations](/observability/overview) when traces should go to an external observability backend. The exporter configuration determines where those spans are sent.
 
-    db = SqliteDb(db_file="tmp/traces.db")
-    setup_tracing(db=db) # Call this once at startup
-    ```
-  </Step>
-  
-  <Step title="Run Your Agent">
-    ```python
-    from agno.agent import Agent
-    from agno.models.openai import OpenAIResponses
+## Immediate and Batch Export
 
-    agent = Agent(
-        name="My Agent",
-        model=OpenAIResponses(id="gpt-5.2"),
-        instructions="You are a helpful assistant",
-    )
-    
-    agent.run("Hello!")  # Automatically traced!
-    ```
-  </Step>
-  
-  <Step title="Query Traces">
-    ```python
-    traces, total = db.get_traces(agent_id=agent.id, limit=10)
-    for trace in traces:
-        print(f"{trace.name}: {trace.duration_ms}ms")
-    ```
-  </Step>
-</Steps>
+`setup_tracing()` writes each completed span immediately by default. Set `batch_processing=True` to queue spans and export them in batches.
+
+```python
+setup_tracing(
+    db=traces_db,
+    batch_processing=True,
+    max_queue_size=2048,
+    max_export_batch_size=512,
+    schedule_delay_millis=5000,
+)
+```
+
+| Parameter | Default | Purpose |
+|-----------|---------|---------|
+| `batch_processing` | `False` | Use batched export instead of immediate export |
+| `max_queue_size` | `2048` | Maximum queued spans |
+| `max_export_batch_size` | `512` | Maximum spans in one export batch |
+| `schedule_delay_millis` | `5000` | Delay between scheduled batch exports |
 
-## Guides
+## Next Steps
 
 <CardGroup cols={3}>
-  <Card
-    title="Basic Setup"
-    icon="rocket"
-    href="/tracing/basic-setup"
-  >
-    Configure and enable tracing
+  <Card title="Basic Setup" icon="rocket" href="/tracing/basic-setup">
+    Configure SDK and AgentOS tracing.
   </Card>
-  <Card
-    title="Tracing in AgentOS"
-    icon="rocket"
-    href="/agent-os/tracing/overview"
-  >
-    Trace your agents, teams, and workflows in AgentOS
+  <Card title="Tracing in AgentOS" icon="chart-network" href="/agent-os/tracing/overview">
+    Store and inspect traces for an AgentOS runtime.
   </Card>
-  <Card
-    title="DB Functions"
-    icon="database"
-    href="/tracing/db-functions"
-  >
-    Query traces and spans from your database
+  <Card title="Database Functions" icon="database" href="/tracing/db-functions">
+    Query traces and spans from an Agno database.
   </Card>
 </CardGroup>