let users know about how maestro works

README.md

@@ -12,6 +12,8 @@ Collaborate with AI to create detailed specification documents, then let Auto Ru
 
 Run multiple agents in parallel with a Linear/Superhuman-level responsive interface. Currently supporting **Claude Code**, **OpenAI Codex**, **OpenCode**, and **Factory Droid** with plans for additional agentic coding tools (Gemini CLI, Qwen3 Coder) based on user demand.
 
+> **How It Works:** Maestro is a pass-through to your AI provider. Whatever MCP tools, skills, permissions, or authentication you have configured in Claude Code, Codex, or OpenCode works identically in Maestro. The only difference is we're not running interactively—each task gets a prompt and returns a response, whether it's a new session or resuming a prior one.
+
 <div align="center">
   <a href="https://youtu.be/fmwwTOg7cyA?si=dJ89K54tGflKa5G4">
     <img src="https://github.com/user-attachments/assets/deaf601d-1898-4ede-bf5a-42e46874ebb3"

docs/about/overview.md

@@ -49,3 +49,4 @@ This approach mirrors methodologies like [Spec-Kit](https://github.com/github/sp
 | **History** | Timestamped log of all actions (user commands, AI responses, Auto Run completions) with session links. |
 | **Remote Control** | Web interface for mobile access. Local network or remote via Cloudflare tunnel. |
 | **CLI** | Headless command-line tool for scripting, automation, and CI/CD integration. |
+| **Provider Pass-Through** | Maestro delegates all AI work to your installed provider (Claude Code, Codex, OpenCode). Your MCP tools, custom skills, permissions, and authentication all carry over—Maestro runs them in batch mode (prompt in, response out) rather than interactive mode. |

docs/getting-started.md

@@ -14,6 +14,10 @@ Follow the [Installation](./installation) instructions for your platform, then l
 
 Maestro supports **Claude Code**, **Codex** (OpenAI), and **OpenCode** as providers. Make sure at least one is installed and authenticated.
 
+<Note>
+Maestro is a pass-through to your provider. Your MCP tools, custom skills, permissions, and authentication all work in Maestro exactly as they do when running the provider directly. The only difference is batch mode execution—Maestro sends a prompt and receives a response rather than running an interactive session.
+</Note>
+
 **Option A: Quick Setup**
 Create your first agent manually using the **+** button in the sidebar.
 

docs/installation.md

@@ -23,6 +23,10 @@ Download the latest release for your platform from the [Releases](https://github
   - [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Qwen3 Coder](https://github.com/QwenLM/Qwen-Agent) — Planned support
 - Git (optional, for git-aware features)
 
+<Note>
+Maestro is a pass-through to your provider. Your MCP tools, custom skills, permissions, and authentication all work in Maestro exactly as they do when running the provider directly—Maestro just orchestrates the conversation flow in batch mode.
+</Note>
+
 ## WSL2 Users (Windows Subsystem for Linux)
 
 <Warning>

docs/troubleshooting.md

@@ -4,6 +4,18 @@ description: System logs, process monitor, debug packages, and how to get help w
 icon: life-ring
 ---
 
+## Frequently Asked Questions
+
+**Do my MCP tools, skills, and permissions work in Maestro?**
+
+Yes. Maestro is a pass-through—it calls your provider (Claude Code, Codex, OpenCode) in batch mode rather than interactive mode. Whatever works when you run the provider directly will work in Maestro. Your MCP servers, custom skills, authentication, and tool permissions all carry over automatically.
+
+**What's the difference between running the provider directly vs. through Maestro?**
+
+The only difference is execution mode. When you run Claude Code directly, it's interactive—you send a message, watch it work, and respond in real-time. Maestro runs in batch mode: it sends a prompt, the provider processes it fully, and returns the response. This enables unattended automation via Auto Run and parallel agent management. Everything else—your tools, permissions, context—remains identical.
+
+---
+
 ## System Logs
 
 Maestro maintains detailed system logs that help diagnose issues. Access them via:

src/renderer/components/WelcomeContent.tsx

@@ -89,7 +89,7 @@ export function WelcomeContent({ theme, showGetStarted = false }: WelcomeContent
 
 			{/* How it works section */}
 			<div
-				className="text-sm leading-relaxed p-4 rounded-lg text-left"
+				className="text-sm leading-relaxed p-4 rounded-lg text-left space-y-2"
 				style={{
 					backgroundColor: theme.colors.bgActivity,
 					color: theme.colors.textDim,
@@ -97,6 +97,10 @@ export function WelcomeContent({ theme, showGetStarted = false }: WelcomeContent
 			>
 				<p>
 					<strong style={{ color: theme.colors.textMain }}>How it works:</strong>{' '}
+					Maestro is a pass-through to your AI provider. Your MCP tools, skills,
+					and permissions work exactly as they do when running the provider directly.
+				</p>
+				<p>
 					Agents run in auto-approve mode with tool calls accepted automatically.
 					Toggle Read-Only mode for guardrails.
 				</p>