docs: tighten README copy, add app screenshots

Strip the README down to what matters: problem, fix, 3 steps, features
with inline screenshots. Dashboard hero shot, Spaces and Settings as
feature callouts. Remove verbose sections and collapse project structure
into a <details> block.

https://claude.ai/code/session_01W32JdTpYeN92qNrHPgMyVo

Author: claude

README.md

@@ -5,49 +5,45 @@
 
 ### Configure your MCP servers once. Connect every AI client.
 
-McpMux is a desktop app that gives you **one place** to manage all your MCP servers — so you never have to copy-paste server configs across Cursor, Claude Desktop, VS Code, or any other AI client again.
+![McpMux Dashboard](docs/screenshots/dashboard.png)
 
 ---
 
-## Why McpMux?
+## The Problem
 
-### The problem: MCP config is per-client
-
-Every AI client that supports MCP has its own configuration file. Want to use a GitHub server, a database server, and a Slack server? You configure all three **separately** in every single client.
+Every AI client has its own MCP config file. Same servers, same credentials — duplicated everywhere.
 
 ```
-Cursor          → config.json    → github, slack, db servers + credentials
-Claude Desktop  → config.json    → github, slack, db servers + credentials  (again)
-VS Code         → settings.json  → github, slack, db servers + credentials  (again)
-Windsurf        → config.json    → github, slack, db servers + credentials  (again)
+Cursor          → config.json   → github, slack, db  + API keys
+Claude Desktop  → config.json   → github, slack, db  + API keys  (again)
+VS Code         → settings.json → github, slack, db  + API keys  (again)
+Windsurf        → config.json   → github, slack, db  + API keys  (again)
 ```
 
-Add a new server? Update **every client**. Rotate an API key? Update **every client**. Start a new project with different servers? Reconfigure **everything**.
-
-### The other problem: credentials in plain text
+Add a server? **Update every client.** Rotate an API key? **Update every client.** New project? **Reconfigure everything.**
 
-MCP configs store API keys and tokens in **plain JSON files on disk**. No encryption, no access control — just raw secrets sitting in your home directory.
+And all those credentials? Sitting in **plain-text JSON files** on disk.
 
-### The fix: configure once, connect everywhere
+## The Fix
 
-McpMux runs a local gateway on your machine. You configure your servers and credentials **once** inside McpMux, then point all your AI clients to a single local URL. That's it.
+McpMux is a desktop app that runs a local gateway. Configure your servers once, point all clients to one URL.
 
 ```
 Cursor          ─┐
-Claude Desktop  ─┤──→  McpMux (localhost:9315)  ──→  github, slack, db servers
-VS Code         ─┤      manages all credentials
-Windsurf        ─┘      one config, one place
+Claude Desktop  ─┤──→  McpMux (localhost)  ──→  all your MCP servers
+VS Code         ─┤     encrypted credentials
+Windsurf        ─┘     one config, one place
 ```
 
-Add a server in McpMux → every client has it instantly. No files to edit. No credentials to copy.
+Add a server in McpMux and every client has it instantly. No files to edit.
 
 ---
 
 ## How It Works
 
-**1. Install servers** — Browse the built-in registry or add servers manually.
+**1.** Install servers from the built-in registry (or add manually)
 
-**2. Copy one config** — McpMux gives you a single JSON snippet to paste into any AI client:
+**2.** Paste one config into your AI clients:
 
 ```json
 {
@@ -59,131 +55,91 @@ Add a server in McpMux → every client has it instantly. No files to edit. No c
 }
 ```
 
-**3. Done** — Every tool, prompt, and resource from all your servers is now available in every connected client.
+**3.** Done. All tools from all servers are available in every client.
 
-When an AI client calls a tool, McpMux routes the request to the right server automatically. OAuth tokens refresh in the background. Credentials stay encrypted in your OS keychain. You don't think about it.
+McpMux routes calls to the right server, refreshes OAuth tokens automatically, and keeps credentials encrypted in your OS keychain. You don't think about it.
 
 ---
 
 ## Features
 
-### One Dashboard for Everything
-See all your servers, their connection status, available tools, and connected clients in one place. Install new servers from the registry with a click. View logs when something goes wrong.
+**Spaces** — Isolated workspaces with their own servers and credentials. Switch between "Work" and "Personal" in one click.
+
+![Workspaces](docs/screenshots/spaces.png)
+
+**Encrypted Credentials** — Stored in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) with AES-256-GCM encryption. Not in plain-text JSON files.
 
-### Spaces — Switch Contexts Instantly
-Working on multiple projects that need different servers? Create **Spaces** like "Work", "Personal", or "Client Project". Each Space has its own servers, credentials, and permissions. Switch between them in the sidebar — your AI clients follow automatically.
+**OAuth That Just Works** — Handles the full OAuth 2.1 + PKCE flow for remote servers. Automatic token refresh. Authenticate once and forget about it.
 
-### Credentials That Aren't in Plain Text
-McpMux stores credentials in your **OS keychain** (macOS Keychain, Windows Credential Manager, Linux Secret Service). Database fields are encrypted with AES-256-GCM. No more API keys sitting in plain JSON files.
+**Server Registry** — Browse, search, and one-click install MCP servers. Cached for offline use.
 
-### OAuth That Just Works
-Remote MCP servers that require OAuth? McpMux handles the entire flow — browser-based login, token storage, and **automatic refresh** when tokens expire. You authenticate once and forget about it.
+**Per-Client Permissions** — Control which tools each AI client can access with Feature Sets.
 
-### Server Registry
-Browse, search, and install MCP servers from the built-in registry. Filter by category, see what tools each server provides, and install with one click. Servers you've used before are cached for offline access.
+**System Tray** — Runs in the background, starts with your OS. Always available.
 
-### Control What Each Client Can Access
-Not every AI client should have access to every tool. Create **Feature Sets** — permission bundles that control which tools, prompts, and resources a client can see. Give Cursor full access but limit VS Code to read-only tools. It's up to you.
+![Settings](docs/screenshots/settings.png)
 
-### Runs in the Background
-McpMux sits in your system tray and starts automatically with your OS. The gateway is always running, so your AI clients always have their tools available.
+**Auto-Updates** — Signed updates delivered automatically.
 
 ---
 
 ## Security
 
-MCP's default approach is plain-text JSON config files with raw credentials. McpMux replaces that with proper security:
+MCP defaults to plain-text config files with raw API keys. McpMux replaces that with:
 
-- **OS Keychain** — Encryption keys and secrets stored in your platform's native keychain, not on disk
-- **AES-256-GCM Encryption** — Sensitive database fields are encrypted with authenticated encryption
-- **Memory Zeroization** — Secrets are wiped from memory after use
-- **OAuth 2.1 + PKCE** — Industry-standard auth flow for remote servers with automatic token refresh
-- **Local-Only Gateway** — Binds to `127.0.0.1` only — nothing is exposed to the network
-- **Per-Client Permissions** — Access keys and Feature Sets control what each client can do
-- **Sanitized Logs** — Tokens and secrets never appear in log files
+- **OS Keychain** — secrets in platform-native secure storage, not on disk
+- **AES-256-GCM** — field-level database encryption
+- **OAuth 2.1 + PKCE** — standard auth with automatic token refresh
+- **Local-only gateway** — binds to `127.0.0.1`, nothing exposed to the network
+- **Per-client access keys** — granular permissions per AI client
+- **Sanitized logs** — tokens never appear in log files
+- **Memory zeroization** — secrets wiped from memory after use
 
-All MCP traffic stays on your machine. McpMux never routes tool calls through external services. Cloud sync (optional) only covers configuration metadata — never credentials or MCP payloads.
+All MCP traffic stays on your machine. Cloud sync (optional) only covers config metadata — never credentials or payloads.
 
 ---
 
 ## Getting Started
 
-### 1. Download McpMux
-
-Grab the latest release for your platform from the [Releases page](https://github.com/MCP-Mux/mcp-mux/releases):
-
-| Platform | Format |
-|----------|--------|
-| Windows | MSI installer |
-| macOS | DMG |
-| Linux | DEB, RPM, AppImage |
-
-### 2. Add Your Servers
+**1. [Download McpMux](https://github.com/MCP-Mux/mcp-mux/releases)** — Windows (MSI), macOS (DMG), Linux (DEB/RPM/AppImage)
 
-Open McpMux and head to the **Discover** tab to browse the registry, or add servers manually via **My Servers → Add Server Manually**.
+**2. Add servers** — Discover tab to browse the registry, or add manually
 
-### 3. Connect Your AI Clients
-
-Copy the gateway config from the Dashboard and paste it into your AI client's MCP settings:
-
-```json
-{
-  "mcpServers": {
-    "mcpmux": {
-      "url": "http://localhost:9315/mcp"
-    }
-  }
-}
-```
+**3. Paste config** — Copy the snippet from the Dashboard into your AI clients
 
 That's the last config file you'll need to touch.
 
 ---
 
 ## Development
 
-### Prerequisites
-
-- [Rust](https://rustup.rs/) 1.75+
-- [Node.js](https://nodejs.org/) 18+
-- [pnpm](https://pnpm.io/) 9+
-
-Linux also needs: `gnome-keyring libsecret-1-dev librsvg2-dev pkg-config`
-
-### Setup
-
 ```bash
-pnpm setup    # First-time: installs all dependencies
+pnpm setup    # First-time: install dependencies
 pnpm dev      # Start development
-pnpm build    # Build for production
+pnpm build    # Production build
+pnpm test     # Run all tests
 ```
 
-### Testing
+**Prerequisites:** Rust 1.75+, Node.js 18+, pnpm 9+. Linux also needs `gnome-keyring libsecret-1-dev librsvg2-dev pkg-config`.
 
-```bash
-pnpm test              # All tests
-pnpm test:rust:unit    # Rust unit tests
-pnpm test:ts           # TypeScript tests
-pnpm test:e2e:web      # E2E tests (all platforms)
-```
+Built with **Tauri 2** (Rust + React 19), **Axum** for the gateway, **ring** for encryption, **rmcp** for MCP.
 
-### Project Structure
+<details>
+<summary>Project structure</summary>
 
 ```
 mcp-mux/
 ├── apps/desktop/          # Tauri desktop app (React + Rust)
 ├── crates/
 │   ├── mcpmux-core/       # Domain logic
-│   ├── mcpmux-gateway/    # Local HTTP gateway, OAuth, routing
+│   ├── mcpmux-gateway/    # HTTP gateway, OAuth, routing
 │   ├── mcpmux-storage/    # SQLite + encryption + OS keychain
 │   └── mcpmux-mcp/        # MCP protocol
 ├── packages/ui/           # Shared UI components
-└── tests/                 # Unit, integration, and E2E tests
+└── tests/                 # Unit, integration, E2E tests
 ```
 
-Built with **Tauri 2** (Rust + React 19), using **Axum** for the gateway, **ring** for encryption, and **rmcp** for the MCP protocol.
-
----
+</details>
 
 ## Contributing