converse-mcp-server 2.29.2 → 3.0.1

package/docs/EXAMPLES.md

@@ -1,6 +1,8 @@
 # Converse MCP Server - Usage Examples
 
-## 🚀 Getting Started Examples
+All examples call the unified `chat` tool. The `mode` parameter (`chat`, `consensus`, or `roundtable`) selects how the models are orchestrated; `models` is always an array of plain name strings.
+
+## 🚀 Getting Started
 
 ### Basic Chat Interaction
 
@@ -13,28 +15,23 @@
 }
 ```
 
-**Response:**
+**Response** (status line, continuation_id, then the answer):
+```
+✅ COMPLETED | CHAT | conv_abc123 | 1.2s elapsed | openai/gpt-5.6-sol
+continuation_id: conv_abc123
+
+I'd be happy to help you understand JavaScript promises! Promises are objects that represent the eventual completion or failure of an asynchronous operation…
+```
+
 ```json
 {
-  "content": "I'd be happy to help you understand JavaScript promises! Promises are objects that represent the eventual completion or failure of an asynchronous operation...",
+  "content": "…status line + continuation_id + answer…",
   "continuation": {
     "id": "conv_abc123",
     "provider": "openai",
-    "model": "o4-mini",
+    "model": "gpt-5.6-sol",
     "messageCount": 2
-  },
-  "metadata": {
-    "model": "o4-mini",
-    "usage": {
-      "input_tokens": 15,
-      "output_tokens": 145,
-      "total_tokens": 160
-    },
-    "response_time_ms": 1200,
-    "provider": "openai"
-  },
-  "title": "Understanding JavaScript Promises",  // When summarization enabled
-  "final_summary": "Explained JavaScript promises as objects for handling asynchronous operations with practical examples."  // When summarization enabled
+  }
 }
 ```
 
@@ -50,247 +47,58 @@
 }
 ```
 
-## ⏱️ Asynchronous Execution Examples
-
-### Basic Async Chat
-
-For long-running tasks, use async mode to get immediate response and monitor progress:
-
-```json
-{
-  "tool": "chat",
-  "arguments": {
-    "prompt": "Analyze this large codebase and provide comprehensive optimization recommendations",
-    "model": "gpt-5",
-    "files": ["/path/to/large-project"],
-    "async": true,
-    "continuation_id": "analysis-task-001"
-  }
-}
-```
-
-**Immediate Response:**
-```json
-{
-  "content": "⏳ PROCESSING | CHAT | analysis-task-001 | 1/1 | Started: 2023-12-01 10:30:00 | openai/gpt-5",
-  "continuation": {
-    "id": "analysis-task-001",
-    "status": "processing"
-  },
-  "async_execution": true
-}
-```
-
-### Monitoring Async Progress
-
-```json
-{
-  "tool": "check_status",
-  "arguments": {
-    "continuation_id": "analysis-task-001"
-  }
-}
-```
-
-**While Processing (with summarization enabled):**
-```json
-{
-  "content": {
-    "id": "analysis-task-001",
-    "status": "processing",
-    "tool": "chat",
-    "title": "Codebase Optimization Analysis",  // AI-generated title
-    "streaming_summary": "Analyzing codebase structure and dependencies. Currently examining performance bottlenecks in the API layer.",  // Summary based on partially streamed response
-    "progress": {
-      "completed": 1,
-      "total": 1,
-      "percentage": 100
-    },
-    "elapsed_seconds": 12.5
-  }
-}
-```
-
-**When Complete (with summarization enabled):**
-```json
-{
-  "content": {
-    "id": "analysis-task-001",
-    "status": "completed",
-    "tool": "chat",
-    "title": "Codebase Optimization Analysis",  // AI-generated title
-    "final_summary": "Identified 5 critical performance bottlenecks and provided refactoring recommendations for improved scalability.",  // Final summary
-    "result": {
-      "content": "# Codebase Analysis Results\n\nAfter analyzing your codebase, here are the key optimization opportunities...",
-      "metadata": {
-        "provider": "openai",
-        "model": "gpt-5",
-        "usage": {
-          "input_tokens": 15420,
-          "output_tokens": 2340
-        }
-      }
-    },
-    "elapsed_seconds": 45.2,
-    "completed_at": "2023-12-01T10:30:45.200Z"
-  }
-}
-```
-
-### Async Consensus Example
-
-```json
-{
-  "tool": "consensus",
-  "arguments": {
-    "prompt": "Design a scalable microservices architecture for our e-commerce platform",
-    "models": ["gpt-5", "gemini-2.5-pro", "claude-sonnet-4-6"],
-    "files": ["/docs/requirements.md", "/docs/current-architecture.md"],
-    "async": true,
-    "enable_cross_feedback": true
-  }
-}
-```
-
-**Immediate Response:**
-```json
-{
-  "content": "⏳ PROCESSING | CONSENSUS | consensus_xyz789 | 0/3 | Started: 2023-12-01 10:30:00 | gpt-5,gemini-2.5-pro,claude-sonnet-4-6",
-  "continuation": {
-    "id": "consensus_xyz789",
-    "status": "processing"
-  },
-  "async_execution": true,
-  "metadata": {
-    "total_models": 3,
-    "successful_models": 0,
-    "models_list": "gpt-5,gemini-2.5-pro,claude-sonnet-4-6"
-  }
-}
-```
-
-### Cancelling Long-Running Jobs
-
-```json
-{
-  "tool": "cancel_job",
-  "arguments": {
-    "continuation_id": "analysis-task-001"
-  }
-}
-```
-
-**Response:**
-```json
-{
-  "content": {
-    "status": "cancelled",
-    "message": "Job analysis-task-001 cancelled successfully",
-    "job_id": "analysis-task-001",
-    "elapsed_seconds": 15.3,
-    "cancelled_at": "2023-12-01T10:30:15.300Z"
-  }
-}
-```
-
-### Listing Recent Jobs
+## 🎯 Choosing a Model
 
-```json
-{
-  "tool": "check_status",
-  "arguments": {}
-}
-```
-
-**Response (with summarization enabled):**
-```json
-{
-  "content": {
-    "jobs": [
-      {
-        "id": "analysis-task-001",
-        "status": "completed",
-        "tool": "chat",
-        "title": "Codebase Optimization Analysis",  // AI-generated title
-        "final_summary": "Identified 5 critical performance bottlenecks and provided refactoring recommendations.",  // Summary shown in listing
-        "elapsed_seconds": 45.2,
-        "completed_at": "2023-12-01T10:30:45.200Z"
-      },
-      {
-        "id": "consensus_xyz789",
-        "status": "processing",
-        "tool": "consensus",
-        "title": "E-commerce Architecture Design",  // AI-generated title
-        "progress": {
-          "completed": 2,
-          "total": 3,
-          "percentage": 67
-        },
-        "elapsed_seconds": 28.7
-      }
-    ]
-  }
-}
-```
-
-## 🚀 GPT-5 Advanced Features
-
-### Using Minimal Reasoning for Fast Responses
+### Auto-selection (recommended)
 
 ```json
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "Write a simple SQL query to get all users created today",
-    "model": "gpt-5",
-    "reasoning_effort": "minimal",
-    "verbosity": "low"
+    "prompt": "What's the syntax for async/await in JavaScript?",
+    "models": ["auto"]
   }
 }
 ```
 
-### High Verbosity for Detailed Explanations
+### A specific model
 
 ```json
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "Explain the architecture of this authentication system and suggest improvements",
-    "model": "gpt-5",
-    "files": ["/c/Users/username/project/src/auth.js"],
-    "reasoning_effort": "high",
-    "verbosity": "high"
+    "prompt": "Design a distributed caching strategy for a platform with 10M+ users",
+    "models": ["gpt-5.6"],
+    "reasoning_effort": "max"
   }
 }
 ```
 
-### Cost-Efficient with GPT-5-nano
+### Fast responses with a lightweight model
 
 ```json
 {
   "tool": "chat",
   "arguments": {
     "prompt": "Summarize the main points from this document",
-    "model": "gpt-5-nano",
-    "files": ["/c/Users/username/docs/report.md"],
-    "verbosity": "low"
+    "models": ["gemini-2.5-flash"],
+    "files": ["/c/Users/username/docs/report.md"]
   }
 }
 ```
 
-## 🔧 Code Analysis Examples
+## 🔧 Code Analysis
 
-### Single File Analysis
+### Single File Review
 
 ```json
 {
   "tool": "chat",
   "arguments": {
     "prompt": "Review this function for potential bugs and improvements",
-    "model": "gpt-5",
-    "files": ["/c/Users/username/project/src/auth.js"],
-    "reasoning_effort": "high",
-    "temperature": 0.1
+    "models": ["gpt-5.6"],
+    "files": ["/c/Users/username/project/src/auth.js{1:120}"],
+    "reasoning_effort": "high"
   }
 }
 ```
@@ -302,155 +110,45 @@ For long-running tasks, use async mode to get immediate response and monitor pro
   "tool": "chat",
   "arguments": {
     "prompt": "Analyze the overall architecture and suggest improvements for scalability",
-    "model": "gemini-2.5-pro",
+    "models": ["gemini-2.5-pro"],
     "files": [
       "/c/Users/username/project/src/server.js",
       "/c/Users/username/project/src/routes/index.js",
       "/c/Users/username/project/src/middleware/auth.js",
-      "/c/Users/username/project/config/database.js"
-    ],
-    "temperature": 0.2
-  }
-}
-```
-
-## 🎯 Model-Specific Examples
-
-### Using GPT-5 for Complex Reasoning
-
-```json
-{
-  "tool": "chat",
-  "arguments": {
-    "prompt": "Design a distributed caching strategy for a social media platform with 10M+ users",
-    "model": "gpt-5",
-    "reasoning_effort": "max",
-    "temperature": 0.1
-  }
-}
-```
-
-### Using Flash for Quick Responses
-
-```json
-{
-  "tool": "chat",
-  "arguments": {
-    "prompt": "What's the syntax for async/await in JavaScript?",
-    "model": "gemini-2.5-flash",
-    "temperature": 0.3
-  }
-}
-```
-
-### Using Grok for Creative Solutions
-
-```json
-{
-  "tool": "chat",
-  "arguments": {
-    "prompt": "Brainstorm creative ways to gamify a productivity app",
-    "model": "grok-4",
-    "temperature": 0.7
-  }
-}
-```
-
-## 🤖 Codex Examples
-
-Codex is an agentic coding assistant that runs locally with direct filesystem access.
-
-### Basic Code Analysis
-
-```json
-{
-  "tool": "chat",
-  "arguments": {
-    "prompt": "Explain what this function does",
-    "model": "codex",
-    "files": ["/path/to/src/utils.js"]
-  }
-}
-```
-
-### Thread Continuation
-
-Codex maintains conversation history through threads:
-
-```json
-// First request
-{
-  "tool": "chat",
-  "arguments": {
-    "prompt": "Review this authentication module",
-    "model": "codex",
-    "files": ["/path/to/auth.js"]
-  }
-}
-// Response includes: "continuation": { "id": "conv_abc123" }
-
-// Follow-up request (maintains context)
-{
-  "tool": "chat",
-  "arguments": {
-    "prompt": "Now add rate limiting to the login endpoint",
-    "model": "codex",
-    "continuation_id": "conv_abc123"
+      "/c/Users/username/config/database.js"
+    ]
   }
 }
 ```
 
-### Async Mode for Long Tasks
+## 🧠 Independent Parallel Answers (chat mode, multiple models)
 
-Codex responses can take several minutes for complex tasks:
+In `chat` mode, listing more than one model runs them in parallel; each answers independently and the response has one labeled section per model.
 
 ```json
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "Analyze this entire codebase and suggest refactoring opportunities",
-    "model": "codex",
-    "files": ["/path/to/project"],
-    "async": true
-  }
-}
-// Response: { "job_id": "conv_xyz789", "status": "SUBMITTED" }
-
-// Check progress
-{
-  "tool": "check_status",
-  "arguments": {
-    "continuation_id": "conv_xyz789"
+    "prompt": "What could be causing our API response times to degrade?",
+    "models": ["gemini-2.5-flash", "o4-mini", "gpt-4.1"],
+    "files": ["/c/Users/username/monitoring/performance_report.json"]
   }
 }
 ```
 
-### Sandbox Modes
-
-Control filesystem access through `CODEX_SANDBOX_MODE`:
-
-```bash
-# Read-only mode (default) - safe for exploration
-CODEX_SANDBOX_MODE=read-only
+## 🤝 Consensus (parallel + cross-feedback)
 
-# Workspace-write - allow modifications in project directory
-CODEX_SANDBOX_MODE=workspace-write
-
-# Full access - use only in containers with proper isolation
-CODEX_SANDBOX_MODE=danger-full-access
-```
-
-## 🤝 Consensus Examples
+`consensus` mode runs all models on the same prompt in parallel, then always runs a refinement phase where each model sees the others' answers and refines its own. It requires at least 2 available models.
 
 ### Simple Technical Decision
 
 ```json
 {
-  "tool": "consensus",
+  "tool": "chat",
   "arguments": {
     "prompt": "Should we use PostgreSQL or MongoDB for our e-commerce inventory system?",
-    "models": ["gpt-5", "gemini-2.5-pro", "grok-4"],
-    "temperature": 0.2
+    "models": ["gpt-5.6", "gemini-2.5-pro", "grok-4.5"],
+    "mode": "consensus"
   }
 }
 ```
@@ -465,20 +163,20 @@ CODEX_SANDBOX_MODE=danger-full-access
   "phases": {
     "initial": [
       {
-        "model": "gpt-5",
+        "model": "gpt-5.6",
         "status": "success",
-        "response": "For an e-commerce inventory system, I recommend PostgreSQL because...",
-        "metadata": {"input_tokens": 50, "output_tokens": 180}
+        "response": "For an e-commerce inventory system, I recommend PostgreSQL because…"
       }
     ],
     "refined": [
       {
-        "model": "gpt-5",
+        "model": "gpt-5.6",
         "status": "success",
-        "initial_response": "For an e-commerce inventory system, I recommend PostgreSQL...",
-        "refined_response": "After considering the other perspectives on MongoDB's flexibility, I still lean towards PostgreSQL but acknowledge that MongoDB could work well if..."
+        "initial_response": "For an e-commerce inventory system, I recommend PostgreSQL…",
+        "refined_response": "After considering the other perspectives on MongoDB's flexibility, I still lean towards PostgreSQL but acknowledge that…"
       }
-    ]
+    ],
+    "failed": []
   }
 }
 ```
@@ -487,56 +185,53 @@ CODEX_SANDBOX_MODE=danger-full-access
 
 ```json
 {
-  "tool": "consensus",
+  "tool": "chat",
   "arguments": {
-    "prompt": "Given our current system architecture, what's the best approach for implementing real-time notifications?",
-    "models": [
-      "gpt-5",        // Most intelligent: Superior reasoning
-      "grok-4",    // Most intelligent: Advanced analysis
-      "gemini-2.5-pro"  // Most intelligent: Deep thinking
-    ],
+    "prompt": "Given our current architecture, what's the best approach for real-time notifications?",
+    "models": ["gpt-5.6", "grok-4.5", "gemini-2.5-pro"],
+    "mode": "consensus",
     "files": [
       "/c/Users/username/docs/current_architecture.md",
       "/c/Users/username/src/server.js",
       "/c/Users/username/package.json"
-    ],
-    "enable_cross_feedback": true,
-    "temperature": 0.15
+    ]
   }
 }
 ```
 
-### Fast Consensus (No Cross-Feedback)
+### Auto Consensus
+
+`["auto"]` in consensus mode expands to the first 3 available providers:
 
 ```json
 {
-  "tool": "consensus",
+  "tool": "chat",
   "arguments": {
-    "prompt": "What's the best CSS framework for rapid prototyping in 2024?",
-    "models": ["gemini-2.5-flash", "o4-mini", "grok-4"],
-    "enable_cross_feedback": false,
-    "temperature": 0.3
+    "prompt": "Which CSS framework fits rapid prototyping best?",
+    "models": ["auto"],
+    "mode": "consensus"
   }
 }
 ```
 
-## 🔄 Conversation (Round-Table) Examples
+## 🔄 Roundtable (sequential turn-based dialogue)
 
-The `conversation` tool runs a turn-based round-table: models respond **in the order given**, and each model sees the full running transcript of every turn before it. One call = one lap. Pass the returned `continuation_id` to run another lap; every lap appends to one shared transcript. This differs from `consensus`, where all models answer the same prompt in parallel.
+`roundtable` mode has models respond **in the order given**, each seeing the full running transcript of every turn before it. One call = one lap. Pass the returned `continuation_id` to run another lap; every lap appends to one shared transcript.
 
 ### Basic Two-Model Round-Table
 
 ```json
 {
-  "tool": "conversation",
+  "tool": "chat",
   "arguments": {
     "prompt": "Should we adopt event sourcing for the order service?",
-    "models": ["codex", "gemini"]
+    "models": ["codex", "gemini"],
+    "mode": "roundtable"
   }
 }
 ```
 
-On this lap, `codex` opens, then `gemini` responds having seen codex's turn. The response contains both labeled turns in order plus a `continuation_id`.
+On this lap, `codex` opens, then `gemini` responds having seen codex's turn. The result contains both labeled turns in order plus a `continuation_id`.
 
 ### Continuing the Round-Table (More Laps)
 
@@ -545,51 +240,59 @@ On this lap, `codex` opens, then `gemini` responds having seen codex's turn. The
 
 // Lap 2 — every model again sees the full accumulated transcript
 {
-  "tool": "conversation",
+  "tool": "chat",
   "arguments": {
     "prompt": "Now focus specifically on the migration path from the current design.",
     "models": ["codex", "gemini"],
+    "mode": "roundtable",
     "continuation_id": "conv_abc123"
   }
 }
 ```
 
-You may also change the model list on a resuming lap (e.g. drop a participant or add one); the shared transcript persists regardless of who ran in earlier laps:
+You may also change the model list on a resuming lap; the shared transcript persists regardless of who ran in earlier laps:
 
 ```json
 {
-  "tool": "conversation",
+  "tool": "chat",
   "arguments": {
     "prompt": "Bring in a third perspective on testability.",
     "models": ["codex", "gemini", "claude"],
+    "mode": "roundtable",
     "continuation_id": "conv_abc123"
   }
 }
 ```
 
-### Round-Table with Files and a Custom Per-Turn Instruction
+### Round-Table with Files
 
 ```json
 {
-  "tool": "conversation",
+  "tool": "chat",
   "arguments": {
-    "prompt": "Review this module design and push back on weak assumptions.",
+    "prompt": "Review this module design and push back on weak assumptions. Call out concrete failure modes you would test for.",
     "models": ["codex", "gemini", "claude"],
-    "files": ["/c/Users/username/project/src/orders/design.md"],
-    "turn_prompt": "Call out concrete failure modes you would test for."
+    "mode": "roundtable",
+    "files": ["/c/Users/username/project/src/orders/design.md"]
   }
 }
 ```
 
-### Async Round-Table with Progress Monitoring
+## ⏱️ Asynchronous Execution
+
+For long-running work, set `async: true` to get an immediate `continuation_id` and monitor progress with `check_status`.
+
+### Async Chat
 
 ```json
 {
-  "tool": "conversation",
+  "tool": "chat",
   "arguments": {
-    "prompt": "Design a rollout plan for the new pricing engine.",
-    "models": ["codex", "gemini", "claude"],
-    "async": true
+    "prompt": "Analyze this large codebase and provide comprehensive optimization recommendations",
+    "models": ["gpt-5.6"],
+    "files": ["/path/to/large-project"],
+    "async": true,
+    "continuation_id": "analysis-task-001"
   }
 }
 ```
@@ -597,477 +300,347 @@ You may also change the model list on a resuming lap (e.g. drop a participant or
 **Immediate Response:**
 ```json
 {
-  "content": "⏳ SUBMITTED | CONVERSATION | conv_xyz789 | 1/1 | Started: 01/12/2023 10:30:00 | \"Pricing Engine Rollout\" | codex, gemini, claude",
-  "continuation": {
-    "id": "conv_xyz789",
-    "status": "processing"
-  },
+  "content": "⏳ SUBMITTED | CHAT | analysis-task-001 | 1/1 | Started: 01/12/2026 10:30:00 | \"Codebase Optimization Analysis\" | gpt-5.6\ncontinuation_id: analysis-task-001",
+  "continuation": { "id": "analysis-task-001", "status": "processing" },
   "async_execution": true
 }
 ```
 
-**Monitor per-turn progress, then read the full transcript on completion:**
+### Monitoring Progress
+
 ```json
 {
   "tool": "check_status",
-  "arguments": {
-    "continuation_id": "conv_xyz789"
-  }
+  "arguments": { "continuation_id": "analysis-task-001" }
 }
 ```
 
-While running, the status line shows turn progress (e.g. `2/3 turns`) and the accumulating transcript. When complete, `check_status` renders the full lap transcript along with the AI-generated title and final summary.
+While processing (with summarization enabled), the status shows an AI-generated title and a streaming summary based on the partial response. When complete, it renders the full result plus the final summary.
 
-## 🖼️ Image Analysis Examples
-
-### Screenshot Analysis
+### Async Consensus
 
 ```json
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "Analyze this UI design and suggest improvements for user experience",
-    "model": "gpt-4.1",
-    "images": ["/c/Users/username/designs/dashboard_mockup.png"],
-    "temperature": 0.3
-  }
-}
-```
-
-### Multi-Image Comparison
-
-```json
-{
-  "tool": "consensus",
-  "arguments": {
-    "prompt": "Compare these three design options and recommend the best one for our mobile app",
-    "models": ["gpt-4.1", "gemini-2.5-pro", "grok-4"],
-    "images": [
-      "/c/Users/username/designs/option_a.png",
-      "/c/Users/username/designs/option_b.png", 
-      "/c/Users/username/designs/option_c.png"
-    ],
-    "temperature": 0.2
+    "prompt": "Design a scalable microservices architecture for our e-commerce platform",
+    "models": ["gpt-5.6", "gemini-2.5-pro", "claude"],
+    "mode": "consensus",
+    "files": ["/docs/requirements.md", "/docs/current-architecture.md"],
+    "async": true
   }
 }
 ```
 
-### Code + Diagram Analysis
+### Async Round-Table
 
 ```json
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "Review the implementation against the architecture diagram. Are we following the design correctly?",
-    "model": "gpt-5",
-    "files": ["/c/Users/username/src/services/payment.js", "/c/Users/username/src/models/transaction.js"],
-    "images": ["/c/Users/username/docs/payment_flow_diagram.png"],
-    "reasoning_effort": "high"
+    "prompt": "Design a rollout plan for the new pricing engine.",
+    "models": ["codex", "gemini", "claude"],
+    "mode": "roundtable",
+    "async": true
   }
 }
 ```
 
-## 🔍 Debugging & Problem Solving
+While running, `check_status` shows turn progress (e.g. `2/3 turns`) and the accumulating transcript; on completion it renders the full lap transcript, title, and final summary.
 
-### Error Investigation
+### Cancelling a Job
 
 ```json
 {
-  "tool": "chat",
-  "arguments": {
-    "prompt": "Help me debug this error. The application crashes intermittently with this stack trace.",
-    "model": "gpt-5",
-    "files": [
-      "/c/Users/username/src/server.js",
-      "/c/Users/username/logs/error.log",
-      "/c/Users/username/src/middleware/error-handler.js"
-    ],
-    "reasoning_effort": "high",
-    "temperature": 0.1
-  }
+  "tool": "cancel_job",
+  "arguments": { "continuation_id": "analysis-task-001" }
 }
 ```
 
-### Performance Analysis
+### Listing Recent Jobs
 
 ```json
 {
-  "tool": "consensus",
-  "arguments": {
-    "prompt": "Our API response times are degrading. What could be the root causes?",
-    "models": [
-      "gemini-2.5-flash",  // Fast: Quick analysis
-      "o4-mini",           // Fast: Rapid responses
-      "gpt-4.1"            // Fast: Efficient processing
-    ],
-    "files": [
-      "/c/Users/username/monitoring/performance_report.json",
-      "/c/Users/username/src/database/queries.js",
-      "/c/Users/username/src/api/routes.js"
-    ],
-    "cross_feedback_prompt": "Focus on the most likely performance bottlenecks based on the data"
-  }
+  "tool": "check_status",
+  "arguments": {}
 }
 ```
 
-## 📚 Learning & Documentation
+Returns the 10 most recent jobs with status, timing, and (when summarization is enabled) titles and summaries.
 
-### Concept Explanation
+## 🤖 Codex Examples
 
-```json
-{
-  "tool": "chat",
-  "arguments": {
-    "prompt": "Explain microservices architecture with pros, cons, and when to use it",
-    "model": "gemini-2.5-pro",
-    "temperature": 0.4
-  }
-}
-```
+Codex is an agentic coding assistant that runs locally with direct filesystem access.
 
-### Code Review & Learning
+### Basic Code Analysis
 
 ```json
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "Review this code and explain what it does, then suggest best practices improvements",
-    "model": "gpt-5",
-    "files": ["/c/Users/username/src/utils/encryption.js"],
-    "reasoning_effort": "medium",
-    "temperature": 0.2
-  }
-}
-```
-
-### Technology Comparison
-
-```json
-{
-  "tool": "consensus",
-  "arguments": {
-    "prompt": "Compare Next.js, Nuxt.js, and SvelteKit for our new web application project",
-    "models": ["gpt-5", "gemini-2.5-flash", "grok-4"],
-    "files": ["/c/Users/username/docs/project_requirements.md"],
-    "temperature": 0.25
+    "prompt": "Explain what this function does",
+    "models": ["codex"],
+    "files": ["/path/to/src/utils.js"]
   }
 }
 ```
 
-## 🛠️ Development Workflows
+### Thread Continuation
 
-### Feature Planning
+Codex maintains conversation history through threads in `chat` mode:
 
 ```json
+// First request
 {
-  "tool": "consensus",
+  "tool": "chat",
   "arguments": {
-    "prompt": "Plan the implementation of user authentication with social login support",
-    "models": ["gpt-5", "gemini-2.5-pro", "grok-4"],
-    "files": [
-      "/c/Users/username/docs/user_requirements.md",
-      "/c/Users/username/src/models/user.js"
-    ],
-    "cross_feedback_prompt": "Consider security, scalability, and user experience in your refinement"
+    "prompt": "Review this authentication module",
+    "models": ["codex"],
+    "files": ["/path/to/auth.js"]
   }
 }
-```
-
-### Code Generation
+// Response includes: "continuation": { "id": "conv_abc123" }
 
-```json
+// Follow-up request (maintains context)
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "Generate a React component for a responsive image gallery with lazy loading",
-    "model": "gemini-2.5-flash",
-    "files": ["/c/Users/username/src/styles/globals.css"],
-    "temperature": 0.3
+    "prompt": "Now add rate limiting to the login endpoint",
+    "models": ["codex"],
+    "continuation_id": "conv_abc123"
   }
 }
 ```
 
-### Refactoring Guidance
+### Async Mode for Long Tasks
 
 ```json
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "Help me refactor this legacy code to use modern ES6+ features and improve readability",
-    "model": "gpt-5",
-    "files": ["/c/Users/username/src/legacy/data-processor.js"],
-    "reasoning_effort": "medium",
-    "temperature": 0.2
+    "prompt": "Analyze this entire codebase and suggest refactoring opportunities",
+    "models": ["codex"],
+    "files": ["/path/to/project"],
+    "async": true
   }
 }
 ```
 
-## 🚀 Advanced Use Cases
+### Sandbox Modes
 
-### Multi-Step Problem Solving
+Control filesystem access through `CODEX_SANDBOX_MODE`:
 
-```json
-{
-  "tool": "chat",
-  "arguments": {
-    "prompt": "I need to migrate our monolith to microservices. What's the step-by-step approach?",
-    "model": "gpt-5",
-    "files": ["/c/Users/username/src/app.js", "/c/Users/username/docs/current_architecture.md"],
-    "reasoning_effort": "max",
-    "temperature": 0.1
-  }
-}
-```
+```bash
+# Read-only mode (default) - safe for exploration
+CODEX_SANDBOX_MODE=read-only
 
-### Cross-Technology Analysis
+# Workspace-write - allow modifications in the project directory
+CODEX_SANDBOX_MODE=workspace-write
 
-```json
-{
-  "tool": "consensus",
-  "arguments": {
-    "prompt": "Should we migrate from Python Django to Node.js Express for better performance?",
-    "models": ["gpt-5", "gemini-2.5-pro", "grok-4"],
-    "files": [
-      "/c/Users/username/backend/requirements.txt",
-      "/c/Users/username/monitoring/performance_metrics.json",
-      "/c/Users/username/docs/team_skills.md"
-    ],
-    "cross_feedback_prompt": "Consider team expertise, migration costs, and long-term maintainability"
-  }
-}
+# Full access - use only in containers with proper isolation
+CODEX_SANDBOX_MODE=danger-full-access
 ```
 
-### Research & Investigation
+## 🖼️ Image Analysis
+
+### Screenshot Analysis
 
 ```json
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "Research the latest trends in web development for 2024 and how they apply to our project",
-    "model": "grok-4",
-    "use_websearch": true,
-    "temperature": 0.5
+    "prompt": "Analyze this UI design and suggest improvements for user experience",
+    "models": ["gpt-5.6"],
+    "images": ["/c/Users/username/designs/dashboard_mockup.png"]
   }
 }
 ```
 
-## 🎛️ Configuration Examples
-
-### Custom Temperature Settings
+### Multi-Image Comparison (consensus)
 
 ```json
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "Generate creative marketing copy for our new product launch",
-    "model": "grok-4",
-    "temperature": 0.8
+    "prompt": "Compare these three design options and recommend the best one for our mobile app",
+    "models": ["gpt-5.6", "gemini-2.5-pro", "grok-4.5"],
+    "mode": "consensus",
+    "images": [
+      "/c/Users/username/designs/option_a.png",
+      "/c/Users/username/designs/option_b.png",
+      "/c/Users/username/designs/option_c.png"
+    ]
   }
 }
 ```
 
+### Code + Diagram Analysis
+
 ```json
 {
-  "tool": "chat", 
+  "tool": "chat",
   "arguments": {
-    "prompt": "Fix this bug in my authentication logic",
-    "model": "gpt-5",
-    "files": ["/c/Users/username/src/auth.js"],
-    "temperature": 0.0,
+    "prompt": "Review the implementation against the architecture diagram. Are we following the design correctly?",
+    "models": ["gpt-5.6"],
+    "files": ["/c/Users/username/src/services/payment.js", "/c/Users/username/src/models/transaction.js"],
+    "images": ["/c/Users/username/docs/payment_flow_diagram.png"],
     "reasoning_effort": "high"
   }
 }
 ```
 
-### Different Reasoning Levels
+## 🔍 Debugging & Problem Solving
 
-```json
-{
-  "tool": "chat",
-  "arguments": {
-    "prompt": "Quick syntax check - is this JavaScript valid?",
-    "model": "gpt-5",
-    "reasoning_effort": "minimal",
-    "temperature": 0.1
-  }
-}
-```
+### Error Investigation
 
 ```json
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "Design a comprehensive testing strategy for this complex system",
-    "model": "gpt-5",
-    "files": ["/src/", "/tests/"],
-    "reasoning_effort": "max",
-    "temperature": 0.1
+    "prompt": "Help me debug this error. The application crashes intermittently with this stack trace.",
+    "models": ["gpt-5.6"],
+    "files": [
+      "/c/Users/username/src/server.js",
+      "/c/Users/username/logs/error.log",
+      "/c/Users/username/src/middleware/error-handler.js"
+    ],
+    "reasoning_effort": "high"
   }
 }
 ```
 
-## 🔄 Continuation Examples
+### Web-Grounded Research
 
-### Long Research Session
+Grok 4.5 (and other web-search-capable models) attach web search automatically and decide per request whether to use it:
 
 ```json
-// First request
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "I'm building a real-time chat application. What architecture should I consider?",
-    "model": "gpt-5"
+    "prompt": "Research the latest trends in web development and how they apply to our project",
+    "models": ["grok-4.5"]
   }
 }
+```
 
-// Response includes: "continuation": {"id": "conv_research_123"}
-
-// Follow-up questions
-{
-  "tool": "chat",
-  "arguments": {
-    "prompt": "What about handling file uploads in real-time?",
-    "continuation_id": "conv_research_123"
-  }
-}
+For OpenRouter models, opt into web search explicitly by appending `:online` to the slug (adds a real per-request cost):
 
+```json
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "How would you implement message encryption?",
-    "continuation_id": "conv_research_123"
+    "prompt": "What changed in the latest React release?",
+    "models": ["z-ai/glm-5.2:online"]
   }
 }
 ```
 
-### Iterative Development
+## 📚 Learning & Documentation
+
+### Concept Explanation
 
 ```json
-// Initial code review
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "Review this API endpoint implementation",
-    "model": "gpt-5",
-    "files": ["/c/Users/username/src/api/users.js"]
+    "prompt": "Explain microservices architecture with pros, cons, and when to use it",
+    "models": ["gemini-2.5-pro"]
   }
 }
+```
 
-// Implementation improvement
-{
-  "tool": "chat",
-  "arguments": {
-    "prompt": "Now help me implement the error handling you suggested",
-    "continuation_id": "conv_dev_456",
-    "files": ["/c/Users/username/src/api/users.js"]
-  }
-}
+### Technology Comparison (consensus)
 
-// Testing guidance
+```json
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "What unit tests should I write for this endpoint?",
-    "continuation_id": "conv_dev_456"
+    "prompt": "Compare Next.js, Nuxt.js, and SvelteKit for our new web application project",
+    "models": ["gpt-5.6", "gemini-2.5-flash", "grok-4.5"],
+    "mode": "consensus",
+    "files": ["/c/Users/username/docs/project_requirements.md"]
   }
 }
 ```
 
-## 🎨 Creative & Brainstorming
+## 🛠️ Development Workflows
 
-### Feature Ideation
+### Feature Planning (consensus)
 
 ```json
 {
-  "tool": "consensus",
+  "tool": "chat",
   "arguments": {
-    "prompt": "Brainstorm innovative features for a fitness tracking app that would differentiate us from competitors",
-    "models": ["grok-4", "gemini-2.5-pro", "gpt-4.1"],
-    "temperature": 0.7,
-    "cross_feedback_prompt": "Build on each other's ideas and suggest combinations"
+    "prompt": "Plan the implementation of user authentication with social login support. Consider security, scalability, and UX.",
+    "models": ["gpt-5.6", "gemini-2.5-pro", "grok-4.5"],
+    "mode": "consensus",
+    "files": [
+      "/c/Users/username/docs/user_requirements.md",
+      "/c/Users/username/src/models/user.js"
+    ]
   }
 }
 ```
 
-### UI/UX Improvements
+### Refactoring Guidance
 
 ```json
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "Suggest creative ways to improve user onboarding for this interface",
-    "model": "grok-4",
-    "images": ["/c/Users/username/designs/current_onboarding.png"],
-    "temperature": 0.6
+    "prompt": "Help me refactor this legacy code to use modern ES6+ features and improve readability",
+    "models": ["gpt-5.6"],
+    "files": ["/c/Users/username/src/legacy/data-processor.js"],
+    "reasoning_effort": "medium"
   }
 }
 ```
 
-## 🧪 Testing Examples
+## 🔄 Continuation & Mode Switching
 
-### Test Strategy Planning
+A single thread can span modes. Start with a quick chat answer, then continue in roundtable on the same `continuation_id` — the shared transcript is the context.
 
 ```json
+// Chat: quick opening answer
 {
-  "tool": "consensus",
+  "tool": "chat",
   "arguments": {
-    "prompt": "What testing strategy should we implement for this e-commerce checkout flow?",
-    "models": ["gpt-5", "gemini-2.5-pro", "gemini-2.5-flash"],
-    "files": [
-      "/c/Users/username/src/checkout/payment.js",
-      "/c/Users/username/src/checkout/validation.js",
-      "/c/Users/username/docs/business_requirements.md"
-    ],
-    "temperature": 0.2
+    "prompt": "I'm building a real-time chat application. What architecture should I consider?",
+    "models": ["gpt-5.6"]
   }
 }
-```
-
-### Test Generation
+// Response includes: "continuation": { "id": "conv_research_123" }
 
-```json
+// Roundtable: bring several models into a discussion on the same thread
 {
   "tool": "chat",
   "arguments": {
-    "prompt": "Generate comprehensive unit tests for this user authentication module",
-    "model": "gemini-2.5-flash",
-    "files": ["/c/Users/username/src/auth/index.js"],
-    "temperature": 0.3
+    "prompt": "Debate the trade-offs of WebSockets vs. server-sent events for this design.",
+    "models": ["codex", "gemini", "claude"],
+    "mode": "roundtable",
+    "continuation_id": "conv_research_123"
   }
 }
 ```
 
-## 📊 Error Handling Examples
+## 📊 Partial Failures
 
-### Graceful Degradation
+Individual model or turn failures do not abort a consensus or roundtable request — they are recorded in the result and listed in trailing failure details.
 
+**Consensus with one failed model:**
 ```json
 {
-  "tool": "consensus",
-  "arguments": {
-    "prompt": "One of our models is unavailable, but we still need consensus",
-    "models": ["available-model-1", "available-model-2"],
-    "temperature": 0.2
-  }
-}
-```
-
-### Partial Success Response
-
-```json
-{
-  "status": "consensus_partial",
-  "models_consulted": 2,
+  "status": "consensus_complete",
+  "models_consulted": 3,
   "successful_initial_responses": 2,
   "failed_responses": 1,
-  "failed_models": ["unavailable-model"],
   "phases": {
-    "initial": [...],
-    "refined": [...],
+    "initial": [ /* … */ ],
+    "refined": [ /* … */ ],
     "failed": [
       {
-        "model": "unavailable-model",
-        "error": "Provider not available. Check API key configuration.",
+        "model": "some-model",
+        "error": "Provider is not available. Check API key configuration.",
         "status": "failed"
       }
     ]
@@ -1075,9 +648,11 @@ While running, the status line shows turn progress (e.g. `2/3 turns`) and the ac
 }
 ```
 
+In multi-model `chat` mode, if every model fails the request returns an error listing each model and its failure; if at least one succeeds, failures are appended as trailing "Model failures" details.
+
 ## 🔧 Integration Examples
 
-### CI/CD Pipeline Integration
+### CI/CD Pipeline
 
 ```bash
 # Use in GitHub Actions
@@ -1087,7 +662,7 @@ While running, the status line shows turn progress (e.g. `2/3 turns`) and the ac
       "tool": "chat",
       "arguments": {
         "prompt": "Review this pull request for security issues and best practices",
-        "model": "gpt-5",
+        "models": ["gpt-5.6"],
         "files": ["/c/Users/username/src/modified-file.js"],
         "reasoning_effort": "high"
       }
@@ -1097,12 +672,11 @@ While running, the status line shows turn progress (e.g. `2/3 turns`) and the ac
 ### Automated Documentation
 
 ```bash
-# Generate documentation
 echo '{
   "tool": "chat",
   "arguments": {
     "prompt": "Generate API documentation for these endpoints",
-    "model": "gemini-2.5-flash",
+    "models": ["gemini-2.5-flash"],
     "files": ["/c/Users/username/src/api/routes.js"]
   }
 }' | npx converse-mcp-server > /c/Users/username/docs/api.md
@@ -1110,4 +684,4 @@ echo '{
 
 ---
 
-These examples demonstrate the flexibility and power of the Converse MCP Server across various development scenarios, from simple queries to complex multi-model consensus gathering.
+These examples demonstrate the `chat` tool across common development scenarios — from a single quick answer to multi-model consensus and sequential round-table discussions.