dexto 1.5.4 → 1.5.5

package/README.md

@@ -1,5 +1,11 @@
 <a href="https://dexto.ai">
-  <img src="https://raw.githubusercontent.com/truffle-ai/dexto/main/.github/assets/dexto-logo.svg" alt="Dexto" width="100%" style="max-width: 1000px" />
+  <div align="center">
+    <picture>
+      <source media="(prefers-color-scheme: light)" srcset=".github/assets/dexto_logo_light.svg">
+      <source media="(prefers-color-scheme: dark)" srcset=".github/assets/dexto_logo_dark.svg">
+      <img alt="Dexto" src=".github/assets/dexto_logo_dark.svg" width="55%" style="max-width: 1000px; padding: 48px 8px;">
+    </picture>
+  </div>
 </a>
 
 <p align="center">
@@ -9,433 +15,308 @@
   <a href="https://deepwiki.com/truffle-ai/dexto"><img src="https://deepwiki.com/badge.svg"></a>
 </p>
 
-**An all-in-one toolkit to build agentic applications that turn natural language into real-world actions.**
+<p align="center"><b>An open agent harness for AI applications—ships with a powerful coding agent.</b></p>
 
 <div align="center">
-  <img src="https://github.com/user-attachments/assets/89d30349-0cb1-4160-85db-d99a80a71d7a" alt="Dexto Demo" width="700" />
+  <img src=".github/assets/dexto_title.gif" alt="Dexto Demo" width="600" />
 </div>
 
+---
+
 ## What is Dexto?
 
-Dexto is a universal intelligence layer for building collaborative, context-aware AI Agents & agentic apps. It orchestrates LLMs, tools, and data into persistent, stateful systems with memory, so you can rapidly create AI assistants, digital companions & copilots that think, act and feel alive.
+Dexto is an **agent harness**—the orchestration layer that turns LLMs into reliable, stateful agents that can take actions, remember context, and recover from errors.
 
-Dexto combines a configuration-driven framework, robust runtime, and seamless developer experience so you can build, deploy, and iterate on your agents easily.
+Think of it like an operating system for AI agents:
 
-- **Framework** – Define agent behavior in YAML. Instantly swap models and tools without touching code.
-- **Runtime** – Execution with orchestration, session management, conversation memory, and multimodal support.
-- **Interfaces & Tooling** – Native support for CLI, Web, APIs, and the Dexto Agent SDK.
+| Component | Analogy | Role |
+|-----------|---------|------|
+| **LLM** | CPU | Raw processing power |
+| **Context Window** | RAM | Working memory |
+| **Dexto** | Operating System | Orchestration, state, tools, recovery |
+| **Your Agent** | Application | Domain-specific logic and clients |
 
-#### With Dexto, you can build:
+### Why Dexto?
 
-- **Autonomous Agents**  - Agents that plan, execute, and adapt to user goals.
-- **Digital Companions** - AI assistants & copilots that remember context and anticipate needs.
-- **MCP Clients** - Connect multiple tools, files, APIs, and data via MCP Servers.
-- **MCP Servers** - Dexto Web UI and MCP playground help you to easily test your own MCP servers.
-- **Multi-Agent Systems**  - Architect agents that collaborate, delegate, and solve complex tasks together.
-- **Agent-as-a-Service** – Transform your existing SaaS products and APIs into dynamic, conversational experiences.
-- **Agentic Applications** – Integrate Dexto as a reasoning engine to power interactive, multimodal, AI-native applications.
+- **Configuration-driven**: Define agents in YAML. Swap models and tools without touching code.
+- **Batteries included**: Session management, tool orchestration, memory, multimodal support, and observability—out of the box.
+- **Run anywhere**: Local, cloud, or hybrid. CLI, Web UI, REST API, Discord, Telegram, or embedded in your app.
 
-#### What You Get
+### What You Can Build
 
-- **Batteries Included** – Session management, tool orchestration, multimodal support, and production-ready observability.
-- **50+ LLMs** – Instantly switch between OpenAI, Anthropic, Google, Groq, local models or bring your own.
-- **Run Anywhere** – Local for privacy, cloud for reach, or hybrid. *Same agent, any deployment.*
-- **Native Multimodal** – Text, images, files, and tools in a single conversation. *Upload screenshots, ask questions, take actions.*
-- **Persistent Sessions** – Conversations, context, and memory are saved and can be exported, imported, or shared across environments.
-- **Flexible Interfaces** – One agent, endless ways to interact: Ready-to-use CLI, WebUI, APIs, or integrate with your own UI.
-- **30+ Tools & MCP** – Integrate tools and connect to external servers via the Model Context Protocol (MCP) or use our internal tools.
-- **Pluggable Storage** – Use Redis, PostgreSQL, SQLite, in-memory, S3 and more for cache, database & blob backends.
-- **Human in the loop** - Configure approval policies for tool execution, agents can also remember which tools are safe per session. 
-- **Observability** – Built-in OpenTelemetry distributed tracing, token usage monitoring, and error handling.
+- **Coding Agents** – Build, debug, and refactor code autonomously
+- **Autonomous Agents** – Plan, execute, and adapt to user goals
+- **Digital Companions** – Assistants that remember context and anticipate needs
+- **MCP Clients & Servers** – Connect tools, files, APIs via Model Context Protocol
+- **Multi-Agent Systems** – Agents that collaborate, delegate, and solve complex tasks together
 
 ---
 
-## Installation
-
-```bash
-# NPM global
-npm install -g dexto
-
-# —or— build from source
-# this sets up dexto CLI from the cloned code
-git clone https://github.com/truffle-ai/dexto.git
-cd dexto && pnpm install && pnpm install-cli
-
-```
+## Coding Agent
 
-## Quick Start
+Dexto ships with a **production-ready coding agent** you can use immediately via the CLI or Web UI.
 
 ```bash
-# 1. Run setup workflow - this prompts for your preferred LLM and API keys and opens the Web UI
+# Launch the coding agent (default)
 dexto
 
-# 2. Try a multi-step task in the web UI:
-"create a snake game in HTML/CSS/JS, then open it in the browser"
-
-# 3. Start interactive CLI mode instead of web UI
-dexto --mode cli
-```
-
-In 2 -> Dexto will use filesystem tools to write code and browser tools to open it — all from a single prompt. The Web UI (default mode) allows you to navigate previous conversations and experiment with different models, tools and more. 
-
-The interactive CLI (3) allows you to interact with agents in the terminal.
-
-See the [CLI Guide](https://docs.dexto.ai/docs/guides/cli/overview) for full details.
-
-### Skip Tool Prompts While Prototyping
-
-```bash
-dexto --auto-approve "refactor my project using the filesystem and browser tools"
+# Or explicitly
+dexto --agent coding-agent
 ```
 
-Use the `--auto-approve` flag to bypass confirmation prompts when you trust the tools being invoked—perfect for fast local iteration. Remove the flag when you want explicit approval again.
+**What it can do:**
+- Build new apps from scratch
+- Read, write, and refactor code across your entire codebase
+- Execute shell commands and run tests
+- Spawn specialized sub-agents for exploration and planning
+- Remember context across sessions with persistent memory
+- Work with any of 50+ LLMs (swap models mid-conversation)
 
-### Logs
+**Ready-to-use interfaces:**
+- **Web UI** – Chat interface with file uploads, syntax highlighting, and MCP tool browser
+- **CLI** – Terminal-native with `/commands`, streaming output, and session management
 
-Logs are stored in `~/.dexto/logs` directory by default.
+The coding agent is just one example of what you can build. Create your own agents by defining a YAML config—same architecture, your domain.
 
-Use `DEXTO_LOG_TO_CONSOLE=true` to log to console when running dexto.
-
-Use `DEXTO_LOG_LEVEL=debug` for debug logs.
+---
 
-## Agent Recipes
+## Quick Start
 
-Dexto comes with pre-built agent recipes for common use cases. Install and use them instantly:
+### Install
 
 ```bash
-# List available agents
-dexto list-agents
-
-# Install specific agents
-dexto install nano-banana-agent podcast-agent coding-agent
-
-# Use an agent with one shot prompt
-dexto --agent nano-banana-agent --mode cli "create a futuristic cityscape with flying cars"
-dexto --agent podcast-agent --mode cli "generate a podcast intro with two hosts discussing AI"
-dexto --agent coding-agent --mode cli "create a landing page for a coffee brand inspired by star wars"
+# Install globally via npm
+npm install -g dexto
 
-# Alternatively, start the agent in web UI and put in the prompt yourself
-dexto --agent nano-banana-agent
+# Or build from source
+git clone https://github.com/truffle-ai/dexto.git
+cd dexto && pnpm install && pnpm install-cli
 ```
 
-**Available Agents:**
-- **Coding Agent** – Code generation, refactoring, debugging
-- **Nano Banana Agent** – Advanced image generation and editing using Google's Nano Banana (Gemini 2.5 Flash Image)
-- **Podcast Agent** – Advanced podcast generation using Google Gemini TTS for multi-speaker audio content
-- **Sora Video Agent** – AI video generation using OpenAI's Sora with custom settings, remixing, and reference support
-- **Database Agent** – Demo agent for SQL queries and database operations
-- **GitHub Agent** – GitHub operations, PR analysis, and repository management
-- **Image Editor Agent** – Image editing and manipulation
-- **Music Agent** – Music creation and audio processing
-- **Talk2PDF Agent** – Document analysis and conversation
-- **Product Researcher** – Product naming and branding research
-- **Triage Agent** – Demo multi-agent customer support routing system
-- **Workflow Builder Agent** – Build and manage n8n automation workflows
-- **Product Analysis Agent** – Product analytics and insights using PostHog
-- **Gaming Agent** – Play GameBoy games like Pokemon through an emulator
-
-Each agent is pre-configured with the right tools, prompts, and LLM settings for its domain. No setup required—just install and start building.
-
-**📚 See the full [Agent Registry](https://docs.dexto.ai/docs/guides/agent-registry) for detailed information about all agents, their capabilities, use cases, and requirements.**
+### Run
 
-More ready-to-run recipes live in [`agents/`](https://github.com/truffle-ai/dexto/tree/HEAD/agents/).
-
-## Examples & Demos
-
-### 🎙️ Podcast Agent: Generate AI Podcasts
-**Task:** `Generate an intro for a podcast about the latest in AI.`
 ```bash
-dexto --agent podcast-agent
+# Start Dexto (launches setup wizard on first run)
+dexto
 ```
 
-<img src="https://github.com/user-attachments/assets/cfd59751-3daa-4ccd-97b2-1b2862c96af1" alt="Podcast Agent Demo" width="600"/>
+**More options:**
 
-### 👁️ Computer Vision Agent: Face Detection & Annotation Using OpenCV
-**Task:** `Detect all faces in this image and draw bounding boxes around them.`
 ```bash
-dexto --agent image-editor-agent
+dexto --mode cli                                   # Terminal mode
+dexto -p "create a landing page for a coffee shop" # One-shot task
+dexto --auto-approve "refactor this codebase"      # Skip confirmations
+dexto -m claude-sonnet-4-5-20250929                # Switch models
+dexto --help                                       # Explore all options
 ```
 
-<img src="https://github.com/user-attachments/assets/7e4b2043-c39a-47c7-a403-a9665ee762ce" alt="Face Detection Demo" width="600">
-
-### 🎮 Coding Agents: Create apps on demand
+**Inside the interactive CLI**, type `/` to explore commands—switch models, manage sessions, configure tools, and more.
 
-Build full-stack applications, websites, and interactive games with AI-powered coding agents. Customize them to create your own coding agents.
+### Manage Settings
 
-**Task:** `Can you create a snake game in a new folder and open it when done?`
 ```bash
-dexto --agent coding-agent
+# Configure defaults like LLM provider/model, API keys, or download local models
+dexto setup
 ```
 
-<img src=".github/assets/coding_agent_demo.gif" alt="Snake Game Development Demo" width="600"/>
+Logs are stored in `~/.dexto/logs/`. Use `DEXTO_LOG_LEVEL=debug` for verbose output.
 
+---
 
-### 📧 Portable Agents: Use your agents from Cursor
+## Core Features
 
-Dexto agents are designed to be modular, composable and portable, allowing you to run them from anywhere. In this example, we connect to dexto as an MCP server via Cursor to use our podcast agent from above.
+### 50+ LLMs, Instant Switching
 
-<img src="https://github.com/user-attachments/assets/fd75a63f-4d29-447a-be24-6943e34c387f" alt="Email to Slack Demo" width="600">
+Switch models mid-conversation—no code changes, no restarts.
 
+| Provider | Models |
+|----------|--------|
+| **OpenAI** | gpt-5.2, gpt-5.2-pro, gpt-5.2-codex, o4-mini |
+| **Anthropic** | Claude Sonnet, Opus, Haiku (with extended thinking) |
+| **Google** | Gemini 3 Pro, 2.5 Pro/Flash |
+| **Groq** | Llama 4, Qwen, DeepSeek |
+| **xAI** | Grok 4, Grok 3 |
+| **Local** | Ollama, GGUF via node-llama-cpp (Llama, Qwen, Mistral, etc.) |
+| **+ Gateways** | OpenRouter, AWS Bedrock, Vertex AI, LiteLLM |
 
+**Run locally for privacy**: Local models keep data on your machine with automatic GPU detection (Metal, CUDA, Vulkan).
 
-### 🎯 Triage Agent: Multi-Agent Customer Support
+### MCP Integration (30+ Tools)
 
-Create multi-agent systems that can intelligently coordinate and delegate tasks among themselves based on the user query.
+Connect to Model Context Protocol servers—Puppeteer, Linear, ElevenLabs, Firecrawl, Sora, and more.
 
-```bash
-dexto --agent triage-agent
+```yaml
+# agents/my-agent.yml
+mcpServers:
+  filesystem:
+    type: stdio
+    command: npx
+    args: ['-y', '@modelcontextprotocol/server-filesystem', '.']
+  browser:
+    type: stdio
+    command: npx
+    args: ['-y', '@anthropics/mcp-server-puppeteer']
 ```
-<img src=".github/assets/triage_agent_demo.gif" alt="Triage Agent Demo" width="600">
-
-### 🛠️ Adding Custom MCP Servers
-
-You can add your own Model Context Protocol (MCP) servers to extend Dexto's capabilities with new tools or data sources. Just edit your agent YAML or add it directly in the WebUI.
-
-<img src="https://github.com/user-attachments/assets/1a3ca1fd-31a0-4e1d-ba93-23e1772b1e79" alt="Add MCP Server Example" width="600"/>
-
-### 🧠 Memory: Persistent Context & Learning
 
-Create and save memories. Your agent automatically uses it to create personalized experiences.
+Browse and add servers from the MCP Store in the Web UI or via `/mcp` commands in the CLI.
 
-<img src=".github/assets/memory_demo.gif" alt="Memory Demo" width="600">
-
-### 🛒 MCP Store: Tool Discovery & Integration
-
-Equip your agents from 20+ MCP Servers and start using them via chat - instantly.
-- Bring your own keys
-- Can't find an MCP? [Contribute here!](https://github.com/truffle-ai/dexto/blob/main/CONTRIBUTING.md)  
-
-<img src=".github/assets/mcp_store_demo.gif" alt="MCP Store Demo" width="600">
+### Human-in-the-Loop Controls
 
-### 📝 Human In The Loop: Dynamic Form Generation
-
-Agents can generate structured forms when they need additional data to make it easier to collect extra info & approvals from users.
-
-<img src=".github/assets/user_form_demo.gif" alt="User Form Demo" width="600">
+Fine-grained control over what your agent can do:
 
+```yaml
+toolConfirmation:
+  mode: manual           # Require approval for each tool
+  # mode: auto-approve   # Trust mode for local development
+  toolPolicies:
+    alwaysAllow:
+      - mcp--filesystem--read_file
+      - mcp--filesystem--list_directory
+    alwaysDeny:
+      - mcp--filesystem--delete_file
+```
 
+Agents remember which tools you've approved per session.
 
-#### More Examples:
+### Persistent Sessions & Memory
 
-<details>
-<summary><strong>🛒 Browser Agent: Amazon Shopping Assistant</strong></summary>
+Conversations persist across restarts. Create memories that shape agent behavior.
 
-**Task:** `Can you go to amazon and add some snacks to my cart? I like trail mix, cheetos and maybe surprise me with something else?`
 ```bash
-# Default agent has browser tools
-dexto
-```
-<a href="https://youtu.be/C-Z0aVbl4Ik">
-  <img src="https://github.com/user-attachments/assets/3f5be5e2-7a55-4093-a071-8c52f1a83ba3" alt="Dexto: Amazon shopping agent demo" width="600"/>
-</a>
-
-</details>
+# Continue last conversation
+dexto -c
 
-<details>
-<summary><strong>🎮 Playground: Interactive Development Environment</strong></summary>
-
-A testing playground to view the tools in your MCP servers before connecting them to LLMs to see the detailed response structures.
+# Resume specific session
+dexto -r session-abc123
 
-<img src=".github/assets/playground_demo.gif" alt="Playground Demo" width="600">
+# Search across all conversations
+dexto search "database schema"
+```
 
-</details>
+### Multi-Agent Systems
 
-<details>
-<summary><strong>📧 Email to Slack: Automated Email Summaries</strong></summary>
+Agents can spawn specialized sub-agents to handle complex subtasks. The coding agent uses this to delegate exploration:
 
-**Task:** `Summarize emails and send highlights to Slack`
-```bash
-dexto --agent ./agents/examples/email_slack.yml
+```yaml
+# In your agent config
+customTools:
+  - type: agent-spawner
+    allowedAgents: ["explore-agent"]
+    maxConcurrentAgents: 5
+    defaultTimeout: 300000  # 5 minutes
 ```
-<img src="https://github.com/truffle-ai/dexto/blob/HEAD/assets/email_slack_demo.gif?raw=1" alt="Email to Slack Demo" width="600">
 
-</details>
-
-<details>
-<summary><strong>🖼️ Hugging Face: Image Generation</strong></summary>
-
-**Task:** `Generate a photo of a baby panda.`
+**Built-in sub-agents:**
+- **explore-agent** – Fast, read-only codebase exploration
 
-<img src="https://github.com/user-attachments/assets/570cbd3a-6990-43c5-b355-2b549a4ee6b3" alt="Hugging Face Image Generation Demo" width="600"/>
+Any agent in the [Agent Registry](#agent-registry) can be spawned as a sub-agent—including custom agents you create and register.
 
-</details>
+Sub-agents run ephemerally, auto-cleanup after completion, and forward tool approvals to the parent—so users see one unified approval flow.
 
 ---
 
 ## Run Modes
 
-| Mode | Command | Best for |
+| Mode | Command | Use Case |
 |------|---------|----------|
-| **Web UI** | `dexto` | Friendly chat interface w/ image support (default) |
-| **Interactive CLI** | `dexto --mode cli` | Everyday automation & quick tasks |
-| **Headless Server** | `dexto --mode server` | REST & SSE streaming APIs for agent interaction |
-| **MCP Server (Agent)** | `dexto --mode mcp` | Exposing your agent as a tool for others via stdio |
-| **MCP Server (Aggregator)** | `dexto mcp --group-servers` | Re-exposing tools from multiple MCP servers via stdio |
-| **Discord Bot** | [See `examples/discord-bot/`](examples/discord-bot/) | Community servers & channels (reference implementation) |
-| **Telegram Bot** | [See `examples/telegram-bot/`](examples/telegram-bot/) | Mobile chat (reference implementation) |
-
-Run `dexto --help` for **all flags, sub-commands, and environment variables**.
-
-## Configuration
-
-### Agent Configuration
+| **Web UI** | `dexto` | Chat interface with file uploads (default) |
+| **CLI** | `dexto --mode cli` | Terminal interaction |
+| **Web Server** | `dexto --mode server` | REST & SSE APIs |
+| **MCP Server** | `dexto --mode mcp` | Expose agent as an MCP server over stdio |
 
-Dexto treats each configuration as a unique agent allowing you to define and save combinations of LLMs, servers, storage options, etc. based on your needs for easy portability. Define agents in version-controlled YAML. Change the file, reload, and chat—state, memory, and tools update automatically.
+Platform integrations: [Discord](examples/discord-bot/), [Telegram](examples/telegram-bot/)
 
-Example configuration:
+<details>
+<summary><strong>Dexto as an MCP Server</strong></summary>
 
-```yaml
-# agents/my-agent.yml
-llm:
-  provider: openai
-  model: gpt-5-mini
-  apiKey: $OPENAI_API_KEY
+**Transport: `stdio`**
 
-mcpServers:
-  filesystem:
-    type: stdio
-    command: npx
-    args: ['-y', '@modelcontextprotocol/server-filesystem', '.']
-  web:
-    type: stdio
-    command: npx
-    args: ['-y', '@modelcontextprotocol/server-brave-search']
+Connect your Dexto agent as an MCP server in Claude Code or Cursor:
 
-systemPrompt: |
-  You are a helpful AI assistant with access to files and web search.
+```bash
+dexto --mode mcp --auto-approve --no-elicitation                # Default agent
+dexto --mode mcp --agent coding-agent --auto-approve --no-elicitation
+npx dexto --mode mcp --agent coding-agent --auto-approve --no-elicitation
 ```
 
-### LLM Providers
-
-Switch between providers instantly—no code changes required.
-
-#### Built-in Providers
-
-| Provider | Models | Setup |
-|----------|--------|-------|
-| **OpenAI** | `gpt-5.1-chat-latest`, `gpt-5.1`, `gpt-5.1-codex`, `gpt-5-mini`, `gpt-4.1`, `gpt-4o`, `o4-mini`, `o3`, `o1` | API key |
-| **Anthropic** | `claude-sonnet-4-5-20250929`, `claude-opus-4-5-20251101`, `claude-haiku-4-5-20251001`, `claude-3-7-sonnet-20250219` | API key |
-| **Google** | `gemini-3-pro-preview`, `gemini-3-pro-image-preview`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.0-flash` | API key |
-| **Groq** | `llama-3.3-70b-versatile`, `gemma-2-9b-it`, `openai/gpt-oss-20b`, `openai/gpt-oss-120b`, `moonshotai/kimi-k2-instruct`, `meta-llama/llama-4-scout-17b-16e-instruct`, `meta-llama/llama-4-maverick-17b-128e-instruct`, `deepseek-r1-distill-llama-70b`, `qwen/qwen3-32b` | API key |
-| **xAI** | `grok-4`, `grok-3`, `grok-3-mini`, `grok-code-fast-1` | API key |
-| **Cohere** | `command-a-03-2025`, `command-r-plus`, `command-r`, `command-r7b` | API key |
+Example MCP config for Claude Code or Cursor:
 
-#### Cloud Platforms
+```json
+{
+  "command": "npx",
+  "args": ["-y", "dexto", "--mode", "mcp", "--agent", "coding-agent", "--auto-approve", "--no-elicitation"]
+}
+```
 
-| Provider | Models | Setup |
-|----------|--------|-------|
-| **Vertex AI** | Gemini, Claude | GCP credentials ([docs](https://docs.dexto.ai/docs/guides/supported-llm-providers#google-cloud-vertex-ai)) |
-| **AWS Bedrock** | Claude, Nova, Llama, Mistral | AWS credentials ([docs](https://docs.dexto.ai/docs/guides/supported-llm-providers#amazon-bedrock)) |
+`--auto-approve` and `--no-elicitation` are required for MCP mode since it runs non-interactively.
 
-#### Gateway Providers
+**Transport: `http/sse`**
 
-| Provider | Models | Setup |
-|----------|--------|-------|
-| **OpenRouter** | 100+ models via `provider/model` format | API key |
-| **Glama** | Multi-provider access via `provider/model` format | API key |
-| **LiteLLM** | Self-hosted proxy for any provider | API key + baseURL |
+`dexto --mode server` exposes your agent as an MCP server at `/mcp` for remote clients:
 
 ```bash
-# Switch models via CLI
-dexto -m claude-sonnet-4-5-20250929
-dexto -m gemini-2.5-pro
+dexto --mode server --port 3001
+ngrok http 3001  # Optional: expose publicly
 ```
 
-You can configure things like LLM, system prompt, MCP servers, storage, sessions, human-in-the loop, telemetry and more!
-
-You can also switch within the interactive CLI (/model) and in the web UI easily without needing to set up configuration.
-
-See our [Configuration Guide](https://docs.dexto.ai/docs/category/agent-configuration-guide) and [Supported LLM Providers](https://docs.dexto.ai/docs/guides/supported-llm-providers) for complete setup instructions.
+</details>
 
+---
 
-## Dexto Agent SDK
+## Dexto Agents SDK
 
-Build AI agents programmatically with the `@dexto/core` package. Everything the CLI can do, your code can too.
+Build AI agents programmatically. Everything the CLI does, your code can too.
 
 ```bash
 npm install @dexto/core
 ```
 
-```ts
+```typescript
 import { DextoAgent } from '@dexto/core';
 
-// Create and start agent
 const agent = new DextoAgent({
-  llm: {
-    provider: 'openai',
-    model: 'gpt-5-mini',
-    apiKey: process.env.OPENAI_API_KEY
-  }
+  llm: { provider: 'openai', model: 'gpt-5.2', apiKey: process.env.OPENAI_API_KEY }
 });
 await agent.start();
 
-// Create a session for the conversation
 const session = await agent.createSession();
-
-// Use generate() for simple request/response
 const response = await agent.generate('What is TypeScript?', session.id);
 console.log(response.content);
 
-// Conversations maintain context within a session
-await agent.generate('Write a haiku about it', session.id);
-await agent.generate('Make it funnier', session.id);
+// Streaming
+for await (const event of await agent.stream('Write a story', session.id)) {
+  if (event.name === 'llm:chunk') process.stdout.write(event.content);
+}
 
-// Multimodal: send images or files
+// Multimodal
 await agent.generate([
   { type: 'text', text: 'Describe this image' },
   { type: 'image', image: base64Data, mimeType: 'image/png' }
 ], session.id);
 
-// Streaming for real-time UIs
-for await (const event of await agent.stream('Write a story', session.id)) {
-  if (event.name === 'llm:chunk') process.stdout.write(event.content);
-}
-
-await agent.stop();
+// Switch models mid-conversation
+await agent.switchLLM({ model: 'claude-sonnet-4-5-20250929' });
 ```
 
-See our [Dexto Agent SDK docs](https://docs.dexto.ai/docs/guides/dexto-sdk) for multimodal content, streaming, MCP tools, and advanced features.
-
----
-
-## Advanced Usage
-
-### Starting a Server
+**Start a server programmatically:**
 
 Start a Dexto server programmatically to expose REST and SSE streaming APIs to interact and manage your agent backend.
 
 ```typescript
 import { DextoAgent } from '@dexto/core';
-import { startHonoApiServer } from 'dexto';
-
-// Create and configure agent
-const agent = new DextoAgent({
-  llm: {
-    provider: 'openai',
-    model: 'gpt-5-mini',
-    apiKey: process.env.OPENAI_API_KEY
-  },
-  mcpServers: {
-    filesystem: {
-      type: 'stdio',
-      command: 'npx',
-      args: ['-y', '@modelcontextprotocol/server-filesystem', '.']
-    }
-  }
-});
+import { loadAgentConfig, startHonoApiServer } from 'dexto';
 
-// Start server on port 3001
+const config = await loadAgentConfig('./agents/my-agent.yml');
+const agent = new DextoAgent(config);
 const { server } = await startHonoApiServer(agent, 3001);
-
-console.log('Dexto server running at http://localhost:3001');
-// Server provides REST API and SSE streaming endpoints
-// POST /api/message - Send messages
-// GET /api/sessions - List sessions
-// See docs.dexto.ai/api/rest/ for all endpoints
+// POST /api/message, GET /api/sessions, etc.
 ```
 
 This starts an HTTP server with full REST and SSE APIs, enabling integration with web frontends, webhooks, and other services. See the [REST API Documentation](https://docs.dexto.ai/api/rest/) for available endpoints.
 
+<details>
+<summary><strong>Advanced SDK Usage</strong></summary>
+
 ### Session Management
 
 Create and manage multiple conversation sessions with persistent storage.
@@ -450,7 +331,7 @@ await agent.generate('Hello, how can you help me?', session.id);
 
 // List and manage sessions
 const sessions = await agent.listSessions();
-const sessionHistory = await agent.getSessionHistory('user-123');
+const history = await agent.getSessionHistory('user-123');
 await agent.deleteSession('user-123');
 
 // Search across conversations
@@ -466,21 +347,20 @@ Switch between models and providers dynamically.
 const currentLLM = agent.getCurrentLLMConfig();
 
 // Switch models (provider inferred automatically)
-await agent.switchLLM({ model: 'gpt-5-mini' });
+await agent.switchLLM({ model: 'gpt-5.2' });
 await agent.switchLLM({ model: 'claude-sonnet-4-5-20250929' });
 
-// Switch model for a specific session id 1234
-await agent.switchLLM({ model: 'gpt-5-mini' }, '1234')
+// Switch model for a specific session
+await agent.switchLLM({ model: 'gpt-5.2' }, 'session-123');
 
 // Get supported providers and models
 const providers = agent.getSupportedProviders();
 const models = agent.getSupportedModels();
-const openaiModels = agent.getSupportedModelsForProvider('openai');
 ```
 
 ### MCP Manager
 
-For advanced MCP server management, use the MCPManager directly. See the [MCP Manager SDK docs](https://docs.dexto.ai/api/sdk/mcp-manager) for full details.
+For advanced MCP server management, use the MCPManager directly.
 
 ```typescript
 import { MCPManager } from '@dexto/core';
@@ -507,7 +387,7 @@ await manager.disconnectAll();
 
 ### Storage & Persistence
 
-Configure storage backends for production-ready persistence and caching. See the [Storage Configuration guide](https://docs.dexto.ai/docs/guides/configuring-dexto/storage) for full details.
+Configure storage backends for production.
 
 ```yaml
 # agents/production-agent.yml
@@ -515,135 +395,222 @@ storage:
   cache:
     type: redis
     url: $REDIS_URL
-    maxConnections: 100
   database:
     type: postgres
     connectionString: $POSTGRES_CONNECTION_STRING
-    maxConnections: 25
 
 sessions:
   maxSessions: 1000
-  sessionTTL: 86400000 # 24 hours
+  sessionTTL: 86400000  # 24 hours
 ```
 
 **Supported Backends:**
-- **Cache**: Redis, In-Memory (fast, ephemeral)
-- **Database**: PostgreSQL, SQLite, In-Memory (persistent, reliable)
+- **Cache**: Redis, In-Memory
+- **Database**: PostgreSQL, SQLite, In-Memory
+
+See the [Storage Configuration guide](https://docs.dexto.ai/docs/guides/configuring-dexto/storage) for details.
+
+</details>
+
+---
+
+## Agent Registry
+
+Pre-built agents for common use cases:
+
+```bash
+# List available agents
+dexto list-agents
+
+# Install and run
+dexto install coding-agent podcast-agent
+dexto --agent coding-agent
+```
 
-**Use Cases:**
-- **Development**: In-memory for quick testing
-- **Production**: Redis + PostgreSQL for scale
-- **Simple**: SQLite for single-instance persistence
+**Available:** Coding, Podcast, Image Editor, Video (Sora), Database, GitHub, Triage (multi-agent), and more.
 
-See the [DextoAgent API Documentation](https://docs.dexto.ai/api/sdk/dexto-agent) for complete method references.
+See the full [Agent Registry](https://docs.dexto.ai/docs/guides/agent-registry).
 
 ---
 
-## CLI Reference
+## Agent Configuration
+
+Dexto treats each configuration as a unique agent allowing you to define and save combinations of LLMs, servers, storage options, etc. based on your needs for easy portability. Define agents in version-controlled YAML. Change the file, reload, and chat—state, memory, and tools update automatically.
+
+```yaml
+# agents/production-agent.yml
+llm:
+  provider: anthropic
+  model: claude-sonnet-4-5-20250929
+  apiKey: $ANTHROPIC_API_KEY
+
+mcpServers:
+  filesystem:
+    type: stdio
+    command: npx
+    args: ['-y', '@modelcontextprotocol/server-filesystem', '.']
+
+systemPrompt: |
+  You are a helpful assistant with filesystem access.
+
+storage:
+  cache:
+    type: redis
+    url: $REDIS_URL
+  database:
+    type: postgres
+    connectionString: $POSTGRES_CONNECTION_STRING
+
+toolConfirmation:
+  mode: manual
+```
+
+### LLM Providers
+
+Switch between providers instantly—no code changes required.
+
+#### Built-in Providers
+
+| Provider | Models | Setup |
+|----------|--------|-------|
+| **OpenAI** | `gpt-5.2`, `gpt-5.2-pro`, `gpt-5.2-codex`, `o4-mini` | API key |
+| **Anthropic** | `claude-sonnet-4-5-20250929`, `claude-opus-4-5-20250929`, extended thinking | API key |
+| **Google** | `gemini-3-pro`, `gemini-2.5-pro`, `gemini-2.5-flash` | API key |
+| **Groq** | `llama-4-scout`, `qwen-qwq`, `deepseek-r1-distill` | API key |
+| **xAI** | `grok-4`, `grok-3`, `grok-3-fast` | API key |
+| **Cohere** | `command-r-plus`, `command-r` | API key |
+
+#### Local Models (Privacy-First)
+
+| Provider | Models | Setup |
+|----------|--------|-------|
+| **Ollama** | Llama, Qwen, Mistral, DeepSeek, etc. | Local install |
+| **node-llama-cpp** | Any GGUF model | Bundled (auto GPU detection: Metal, CUDA, Vulkan) |
+
+#### Cloud Platforms
+
+| Provider | Models | Setup |
+|----------|--------|-------|
+| **AWS Bedrock** | Claude, Llama, Mistral | AWS credentials |
+| **Google Vertex AI** | Gemini, Claude | GCP credentials |
+
+#### Gateway Providers
+
+| Provider | Access | Setup |
+|----------|--------|-------|
+| **OpenRouter** | 100+ models from multiple providers | API key |
+| **LiteLLM** | Unified API for any provider | Self-hosted or API key |
+| **Glama** | Multi-provider gateway | API key |
+
+```bash
+# Switch models via CLI
+dexto -m claude-sonnet-4-5-20250929
+dexto -m gemini-2.5-pro
+dexto -m llama-4-scout
+```
+
+Switch within interactive CLI (`/model`) or Web UI without config changes.
+
+See the [Configuration Guide](https://docs.dexto.ai/docs/category/agent-configuration-guide).
+
+---
+
+## Demos & Examples
+
+| Image Editor | MCP Store | Portable Agents |
+|:---:|:---:|:---:|
+| <img src=".github/assets/image_editor_demo.gif" alt="Image Editor" width="280"/> | <img src=".github/assets/mcp_store_demo.gif" alt="MCP Store" width="280"/> | <img src=".github/assets/portable_agent_demo.gif" alt="Portable Agents" width="280"/> |
+| Face detection & annotation using OpenCV | Browse and add MCPs | Use agents in Cursor, Claude Code via MCP|
 
 <details>
-<summary>Click to expand for full CLI reference (`dexto --help`)</summary>
+<summary><strong>More Examples</strong></summary>
 
+### Coding Agent
+Build applications from natural language:
+```bash
+dexto --agent coding-agent
+# "Create a snake game and open it in the browser"
 ```
-Usage: dexto [options] [command] [prompt...]
+<img src=".github/assets/coding_agent_demo.gif" alt="Coding Agent Demo" width="600"/>
 
-Dexto CLI - AI-powered assistant with session management
+### Podcast Agent
+Generate multi-speaker audio content:
+```bash
+dexto --agent podcast-agent
+```
+<img src="https://github.com/user-attachments/assets/cfd59751-3daa-4ccd-97b2-1b2862c96af1" alt="Podcast Agent Demo" width="600"/>
 
-Basic Usage:
-  dexto                    Start web UI (default)
-  dexto "query"            Run one-shot query (auto-uses CLI mode)
-  dexto -p "query"         Run one-shot query, then exit
-  cat file | dexto -p "query"  Process piped content
+### Multi-Agent Triage
+Coordinate specialized agents:
+```bash
+dexto --agent triage-agent
+```
+<img src=".github/assets/triage_agent_demo.gif" alt="Triage Agent Demo" width="600">
 
-CLI Mode:
-  dexto --mode cli         Start interactive CLI REPL
+### Memory System
+Persistent context that shapes behavior:
+<img src=".github/assets/memory_demo.gif" alt="Memory Demo" width="600">
 
-Session Management:
-  dexto -c                 Continue most recent conversation
-  dexto -c -p "query"      Continue with one-shot query, then exit
-  dexto -r "<session-id>" "query"  Resume with one-shot query
+### Dynamic Forms
+Agents generate forms for structured input:
+<img src=".github/assets/user_form_demo.gif" alt="User Form Demo" width="600">
 
-Tool Confirmation:
-  dexto --auto-approve     Auto-approve all tool executions
+### Browser Automation
+<a href="https://youtu.be/C-Z0aVbl4Ik">
+  <img src="https://github.com/user-attachments/assets/3f5be5e2-7a55-4093-a071-8c52f1a83ba3" alt="Amazon Shopping Demo" width="600"/>
+</a>
 
-Agent Selection:
-  dexto --agent coding-agent       Use installed agent by name
-  dexto --agent ./my-agent.yml     Use agent from file path
-  dexto -a agents/custom.yml       Short form with relative path
+### MCP Playground
+Test tools before deploying:
+<img src=".github/assets/playground_demo.gif" alt="Playground Demo" width="600">
 
-Advanced Modes:
-  dexto --mode server      Run as API server
-  dexto --mode mcp         Run as MCP server
+</details>
 
-Platform Integrations (Reference Implementations):
-  See examples/discord-bot/     Run as Discord bot
-  See examples/telegram-bot/    Run as Telegram bot
+---
 
-Session Commands: dexto session list|history|delete • search
-Search: dexto search <query> [--session <id>] [--role <role>]
+<details>
+<summary><strong>CLI Reference</strong></summary>
 
-See https://docs.dexto.ai for documentation and examples
+```text
+Usage: dexto [options] [command] [prompt...]
+
+Basic Usage:
+  dexto                    Start web UI (default)
+  dexto "query"            Run one-shot query
+  dexto --mode cli         Interactive CLI
 
-Arguments:
-  prompt                           Natural-language prompt to run once. If not
-                                   passed, dexto will start as an interactive
-                                   CLI
+Session Management:
+  dexto -c                 Continue last conversation
+  dexto -r <id>            Resume specific session
 
 Options:
-  -v, --version                    output the current version
-  -a, --agent <id|path>            Agent ID or path to agent config file
-  -p, --prompt <text>              Run prompt and exit. Alternatively provide a
-                                   single quoted string as positional argument.
-  -s, --strict                     Require all server connections to succeed
-  --no-verbose                     Disable verbose output
-  --no-interactive                 Disable interactive prompts and API key
-                                   setup
-  --skip-setup                     Skip global setup validation (useful for MCP
-                                   mode, automation)
-  -m, --model <model>              Specify the LLM model to use
-  --auto-approve                   Always approve tool executions without
-                                   confirmation prompts
-  -c, --continue                   Continue most recent conversation
-  -r, --resume <sessionId>         Resume session by ID
-  --mode <mode>                    The application in which dexto should talk
-                                   to you - web | cli | server | mcp
-                                   (default: "web")
-  --port <port>                    port for the server (default: 3000 for web,
-                                   3001 for server mode)
-  --no-auto-install                Disable automatic installation of missing
-                                   agents from registry
-  -h, --help                       display help for command
+  -a, --agent <path>       Agent config file or ID
+  -m, --model <model>      LLM model to use
+  --auto-approve           Skip tool confirmations
+  --no-elicitation         Disable elicitation prompts
+  --mode <mode>            web | cli | server | mcp
+  --port <port>            Server port
 
 Commands:
-  create-app                       Scaffold a new Dexto Typescript app
-  init-app                         Initialize an existing Typescript app with
-                                   Dexto
-  setup [options]                  Configure global Dexto preferences
-  install [options] [agents...]    Install agents from registry or custom YAML
-                                   files/directories
-  uninstall [options] [agents...]  Uninstall agents from the local installation
-  list-agents [options]            List available and installed agents
-  which <agent>                    Show the path to an agent
-  session                          Manage chat sessions
-  search [options] <query>         Search session history
-  mcp [options]                    Start Dexto as an MCP server. Use
-                                   --group-servers to aggregate and re-expose
-                                   tools from configured MCP servers.
-                                   In the future, this command will expose the
-                                   agent as an MCP server by default.
+  setup                    Configure global preferences
+  install <agents...>      Install agents from registry
+  list-agents              List available agents
+  session list|history     Manage sessions
+  search <query>           Search conversation history
 ```
-</details>
 
-See the [CLI Guide](https://docs.dexto.ai/docs/guides/cli/overview) for full details.
+Full reference: `dexto --help`
+
+</details>
 
 ---
 
-## Next Steps
+## Documentation
 
-* **[Quick Start](https://docs.dexto.ai/docs/getting-started/intro/)** – Get up and running in minutes.
-* **[Configuration Guide](https://docs.dexto.ai/docs/category/guides/)** – Configure agents, LLMs, and tools.
-* **[Building with Dexto](https://docs.dexto.ai/docs/category/tutorials/)** – Developer guides and patterns.
-* **[API Reference](https://docs.dexto.ai/api/)** – REST APIs, SSE streaming, and SDKs.
+- **[Quick Start](https://docs.dexto.ai/docs/getting-started/intro/)** – Get running in minutes
+- **[Configuration Guide](https://docs.dexto.ai/docs/category/guides/)** – Agents, LLMs, tools
+- **[SDK Reference](https://docs.dexto.ai/api/sdk/dexto-agent)** – Programmatic usage
+- **[REST API](https://docs.dexto.ai/api/rest/)** – HTTP endpoints
 
 ---
 
@@ -659,38 +626,34 @@ We collect anonymous usage data (no personal/sensitive info) to help improve Dex
 
 To opt-out:
 
-Set env variable `DEXTO_ANALYTICS_DISABLED=1` 
+Set env variable `DEXTO_ANALYTICS_DISABLED=1`
 
-## Contributing
+---
 
-We welcome contributions! Refer to our [Contributing Guide](https://github.com/truffle-ai/dexto/blob/HEAD/CONTRIBUTING.md) for more details.
+## Contributing
 
-## Community & Support
+See [CONTRIBUTING.md](https://github.com/truffle-ai/dexto/blob/HEAD/CONTRIBUTING.md).
 
-Dexto is built by the team at [Truffle AI](https://www.trytruffle.ai).  
-Join our Discord to share projects, ask questions, or just say hi!
+---
 
-[![Discord](https://img.shields.io/badge/Discord-Join%20Chat-7289da?logo=discord&logoColor=white)](https://discord.gg/GFzWFAAZcm)
+## Community
 
-If you enjoy Dexto, please give us a ⭐ on GitHub—it helps a lot!
+Built by [Truffle AI](https://www.trytruffle.ai). Join [Discord](https://discord.gg/GFzWFAAZcm) for support.
 
- <div align="left"/>
+If you find Dexto useful, please give us a ⭐ on GitHub—it helps a lot!
 
+[![Twitter Follow](https://img.shields.io/twitter/follow/Dexto?style=social)](https://x.com/intent/user?screen_name=dexto_ai)
 [![Twitter Follow](https://img.shields.io/twitter/follow/Rahul?style=social)](https://x.com/intent/user?screen_name=Road_Kill11)
 [![Twitter Follow](https://img.shields.io/twitter/follow/Shaunak?style=social)](https://x.com/intent/user?screen_name=shaun5k_)
 
-</div>
-
 ---
 
 ## Contributors
 
-Thanks to all these amazing people for contributing to Dexto!
-
 [![Contributors](https://contrib.rocks/image?repo=truffle-ai/dexto)](https://github.com/truffle-ai/dexto/graphs/contributors)
 
 ---
 
 ## License
 
-Elastic License 2.0.  See [LICENSE](https://github.com/truffle-ai/dexto/blob/HEAD/LICENSE) for full terms.
+Elastic License 2.0. See [LICENSE](https://github.com/truffle-ai/dexto/blob/HEAD/LICENSE).