Readme

README.md

@@ -14,192 +14,34 @@
 
 ---
 
-## Table of Contents
-
-- [📦 Installation](#-installation)
-  - [For Humans](#for-humans)
-  - [For LLM Agents](#for-llm-agents)
-- [🏛️ Meet the Pantheon](#️-meet-the-pantheon)
-  - [01. Orchestrator: The Embodiment Of Order](#01-orchestrator-the-embodiment-of-order)
-  - [02. Explorer: The Eternal Wanderer](#02-explorer-the-eternal-wanderer)
-  - [03. Oracle: The Guardian of Paths](#03-oracle-the-guardian-of-paths)
-  - [04. Librarian: The Weaver of Knowledge](#04-librarian-the-weaver-of-knowledge)
-  - [05. Designer: The Guardian of Aesthetics](#05-designer-the-guardian-of-aesthetics)
-  - [06. Fixer: The Last Builder](#06-fixer-the-last-builder)
-- [🎚️ Presets](#️-presets)
-  - [Switching Presets](#switching-presets)
-  - [OpenAI Preset](#openai-preset)
-  - [Antigravity via CLIProxy Preset](#antigravity-via-cliproxy-preset)
-  - [Author's Preset](#authors-preset)
-- [🧩 Skills](#-skills)
-  - [Simplify](#simplify)
-  - [Agent Browser](#agent-browser)
-  - [Cartography](#cartography)
-  - [Skills Assignment](#skills-assignment)
-- [🔌 MCP Servers](#-mcp-servers)
-  - [MCP Permissions](#mcp-permissions)
-  - [Configuration & Syntax](#configuration--syntax-1)
-- [🛠️ Tools & Capabilities](#️-tools--capabilities)
-  - [Tmux Integration](#tmux-integration)
-  - [Background Tasks](#background-tasks)
-  - [LSP Tools](#lsp-tools)
-  - [Code Search Tools](#code-search-tools)
-  - [Formatters](#formatters)
-- [⚙️ Configuration](#️-configuration)
-  - [Files You Edit](#files-you-edit)
-  - [Prompt Overriding](#prompt-overriding)
-  - [Plugin Config (oh-my-opencode-slim.json)](#plugin-config-oh-my-opencode-slimjson)
-- [🗑️ Uninstallation](#️-uninstallation)
-- [🙏 Credits](#-credits)
-- [📄 License](#-license)
-
----
-
 ## 📦 Installation
 
-### For Humans
-
-Run the interactive installer:
+### Quick Start
 
 ```bash
 bunx oh-my-opencode-slim@latest install
 ```
 
-Or use non-interactive mode:
-
-```bash
-bunx oh-my-opencode-slim@latest install --no-tui --antigravity=yes --openai=yes --tmux=no
-```
-
-After installation, authenticate with your providers:
+Then authenticate:
 
 ```bash
 opencode auth login
-# Select your provider → Complete OAuth flow
-# Repeat for each provider you enabled
 ```
 
-Once authenticated, run opencode and `ping all agents` to verify all agents respond.
-
-<img src="img/ping.png" alt="Ping All Agents" width="800">
+Run `ping all agents` to verify everything works.
 
-> **💡 Tip: Models are fully customizable.** The installer sets sensible defaults, but you can assign *any* model to *any* agent. Edit `~/.config/opencode/oh-my-opencode-slim.json` to override models, adjust reasoning effort, or disable agents entirely. See [Configuration](#configuration) for details.
+> **💡 Models are fully customizable.** Edit `~/.config/opencode/oh-my-opencode-slim.json` to assign any model to any agent.
 
-**Alternative: Ask any coding agent**
+### For LLM Agents
 
-Paste this into Claude Code, AmpCode, Cursor, or any coding agent:
+Paste this into any coding agent:
 
 ```
 Install and configure by following the instructions here:
 https://raw.githubusercontent.com/alvinunreal/oh-my-opencode-slim/refs/heads/master/README.md
 ```
 
-### For LLM Agents
-
-<details>
-<summary>Instructions for LLM Agents (click to expand)</summary>
-
-If you're an LLM Agent helping set up oh-my-opencode-slim, follow these steps.
-
----
-
-#### Step 1: Check OpenCode Installation
-
-```bash
-opencode --version
-```
-
-If not installed, direct the user to https://opencode.ai/docs first.
-
----
-
-#### Step 2: Ask About Provider Access
-
-Ask these questions **one at a time**, waiting for responses:
-
-1. "Do you have an **Antigravity** subscription (via cliproxy)?" *(Provides Claude + Gemini via `cliproxy/` prefix)*
-2. "Do you have access to **OpenAI** API?" *(Enables `openai/` models)*
-
-Help the user understand the tradeoffs:
-- Antigravity via cliproxy provides Claude + Gemini routing.
-- OpenAI is optional; it enables `openai/` models.
-- If the user has **no providers**, the plugin still works using **OpenCode Zen** free models (`opencode/big-pickle`). They can switch to paid providers later by editing `~/.config/opencode/oh-my-opencode-slim.json`.
-
----
-
-#### Step 3: Run the Installer
-
-Based on answers, run:
-
-```bash
-bunx oh-my-opencode-slim@latest install --no-tui --antigravity=<yes|no> --openai=<yes|no>
-```
-
-**Examples:**
-```bash
-# Antigravity + OpenAI
-bunx oh-my-opencode-slim@latest install --no-tui --antigravity=yes --openai=yes --tmux=no
-
-# OpenAI only
-bunx oh-my-opencode-slim@latest install --no-tui --antigravity=no --openai=yes --tmux=no
-
-# No providers (Zen free models only)
-bunx oh-my-opencode-slim@latest install --no-tui --antigravity=no --openai=no --tmux=no
-```
-
-The installer automatically:
-- Adds the plugin to `~/.config/opencode/opencode.json`
-- Configures cliproxy provider for Antigravity models
-- Generates agent model mappings in `~/.config/opencode/oh-my-opencode-slim.json`
-
-**Crucial Advice for the User:**
-- They can easily assign **different models to different agents** by editing `~/.config/opencode/oh-my-opencode-slim.json`.
-- If they add a new provider later, they just need to update this file.
-- Read generated  `~/.config/opencode/oh-my-opencode-slim.json` file and report the model configuration.
-
----
-
-#### Step 4: Install and Configure Cliproxy (if using Antigravity)
-
-If the user selected Antigravity, guide them to install cliproxy:
-
-**macOS:**
-```bash
-brew install cliproxyapi
-brew services start cliproxyapi
-```
-
-**Linux:**
-```bash
-curl -fsSL https://raw.githubusercontent.com/brokechubb/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer | bash
-```
-
-**Authenticate with Antigravity:**
-```bash
-./cli-proxy-api --antigravity-login
-```
-
-**For OpenAI (if enabled):**
-Ask user to run the following command.
-Don't run it yourself, it requires user interaction.
-```bash
-opencode auth login
-# Select your provider and complete OAuth flow
-```
-
----
-
-#### Troubleshooting
-
-If the installer fails, check the expected config format:
-```bash
-bunx oh-my-opencode-slim@latest install --help
-```
-
-Then manually create the config files at:
-- `~/.config/opencode/oh-my-opencode-slim.json`
-
-</details>
+**Detailed installation guide:** [docs/installation.md](docs/installation.md)
 
 ---
 
@@ -487,504 +329,10 @@ Then manually create the config files at:
 
 ---
 
-## 🎚️ Presets
-
-Presets are pre-configured agent model mappings for different provider combinations. The installer generates these automatically based on your available providers, and you can switch between them instantly.
-
-### Switching Presets
-
-**Method 1: Edit Config File**
-
-Edit `~/.config/opencode/oh-my-opencode-slim.json` and change the `preset` field:
-
-```json
-{
-  "preset": "openai"
-}
-```
-
-**Method 2: Environment Variable**
-
-Set the environment variable before running OpenCode:
-
-```bash
-export OH_MY_OPENCODE_SLIM_PRESET=openai
-opencode
-```
-
-The environment variable takes precedence over the config file.
-
-
-### OpenAI Preset
-
-Uses OpenAI models exclusively:
-
-```json
-{
-  "preset": "openai",
-  "presets": {
-    "openai": {
-      "orchestrator": { "model": "openai/gpt-5.2-codex", "skills": ["*"], "mcps": ["websearch"] },
-      "oracle": { "model": "openai/gpt-5.2-codex", "variant": "high", "skills": [], "mcps": [] },
-      "librarian": { "model": "openai/gpt-5.1-codex-mini", "variant": "low", "skills": [], "mcps": ["websearch", "context7", "grep_app"] },
-      "explorer": { "model": "openai/gpt-5.1-codex-mini", "variant": "low", "skills": [], "mcps": [] },
-      "designer": { "model": "openai/gpt-5.1-codex-mini", "variant": "medium", "skills": ["agent-browser"], "mcps": [] },
-      "fixer": { "model": "openai/gpt-5.1-codex-mini", "variant": "low", "skills": [], "mcps": [] }
-    }
-  }
-}
-```
-
-### Antigravity via CLIProxy Preset
-
-Routes through Antigravity's CLIProxy for Claude + Gemini models:
-
-```json
-{
-  "preset": "cliproxy",
-  "presets": {
-    "cliproxy": {
-      "orchestrator": { "model": "cliproxy/gemini-claude-opus-4-5-thinking", "skills": ["*"], "mcps": ["websearch"] },
-      "oracle": { "model": "cliproxy/gemini-3-pro-preview", "variant": "high", "skills": [], "mcps": [] },
-      "librarian": { "model": "cliproxy/gemini-3-flash-preview", "variant": "low", "skills": [], "mcps": ["websearch", "context7", "grep_app"] },
-      "explorer": { "model": "cliproxy/gemini-3-flash-preview", "variant": "low", "skills": [], "mcps": [] },
-      "designer": { "model": "cliproxy/gemini-3-flash-preview", "variant": "medium", "skills": ["agent-browser"], "mcps": [] },
-      "fixer": { "model": "cliproxy/gemini-3-flash-preview", "variant": "low", "skills": [], "mcps": [] }
-    }
-  }
-}
-```
-
-<details>
-<summary>Verify provider configuration in ~/.config/opencode/opencode.json</summary>
-
-```json
-{
-  "provider": {
-    "cliproxy": {
-      "npm": "@ai-sdk/openai-compatible",
-      "name": "CliProxy",
-      "options": {
-        "baseURL": "http://127.0.0.1:8317/v1",
-        "apiKey": "your-api-key-1"
-      },
-      "models": {
-        "gemini-3-pro-high": {
-          "name": "Gemini 3 Pro High",
-          "thinking": true,
-          "attachment": true,
-          "limit": { "context": 1048576, "output": 65535 },
-          "modalities": { "input": [ "text", "image", "pdf" ], "output": [ "text" ] }
-        },
-        "gemini-3-flash-preview": {
-          "name": "Gemini 3 Flash",
-          "attachment": true,
-          "limit": { "context": 1048576, "output": 65536 },
-          "modalities": { "input": [ "text", "image", "pdf" ], "output": [ "text" ] }
-        },
-        "gemini-claude-opus-4-5-thinking": {
-          "name": "Claude Opus 4.5 Thinking",
-          "attachment": true,
-          "limit": { "context": 200000, "output": 32000 },
-          "modalities": { "input": [ "text", "image", "pdf" ], "output": [ "text" ] }
-        },
-        "gemini-claude-sonnet-4-5-thinking": {
-          "name": "Claude Sonnet 4.5 Thinking",
-          "attachment": true,
-          "limit": { "context": 200000, "output": 32000 },
-          "modalities": { "input": [ "text", "image", "pdf" ], "output": [ "text" ] }
-        }
-      }
-    }
-  }
-}
-```
-
-</details>
-
-### Author's Preset
-
-Mixed setup combining multiple providers:
-
-```json
-{
-  "preset": "alvin",
-  "presets": {
-    "alvin": {
-      "orchestrator": { "model": "cliproxy/gemini-claude-opus-4-5-thinking", "skills": ["*"], "mcps": ["*"] },
-      "oracle": { "model": "openai/gpt-5.2-codex", "variant": "high", "skills": [], "mcps": [] },
-      "librarian": { "model": "cliproxy/gemini-3-flash-preview", "variant": "low", "skills": [], "mcps": ["websearch", "context7", "grep_app"] },
-      "explorer": { "model": "cerebras/zai-glm-4.7", "variant": "low", "skills": [], "mcps": [] },
-      "designer": { "model": "cliproxy/gemini-3-flash-preview", "variant": "medium", "skills": ["agent-browser"], "mcps": [] },
-      "fixer": { "model": "cerebras/zai-glm-4.7", "variant": "low", "skills": [], "mcps": [] }
-    }
-  }
-}
-```
-
----
-
-## 🧩 Skills
-
-Skills are specialized capabilities provided by external agents and tools. Unlike MCPs which are servers, skills are prompt-based tool configurations installed via `npx skills add` during installation.
-
-### Recommended Skills (via npx)
-
-| Skill | Description | Assigned To |
-|-------|-------------|-------------|
-| [`simplify`](#simplify) | YAGNI code simplification expert | `orchestrator` |
-| [`agent-browser`](#agent-browser) | High-performance browser automation | `designer` |
-
-### Custom Skills (bundled in repo)
-
-| Skill | Description | Assigned To |
-|-------|-------------|-------------|
-| [`cartography`](#cartography) | Repository understanding and hierarchical codemap generation | `orchestrator` |
-
-### Simplify
-
-**The Minimalist's sacred truth: every line of code is a liability.**
-
-`simplify` is a specialized skill for complexity analysis and YAGNI enforcement. It identifies unnecessary abstractions and suggests minimal implementations.
-
-### Agent Browser
-
-**External browser automation for visual verification and testing.**
-
-`agent-browser` provides full high-performance browser automation capabilities. It allows agents to browse the web, interact with elements, and capture screenshots for visual state verification.
-
-### Cartography
-
-**Automated repository mapping through hierarchical codemaps.**
-
-<img src="img/cartography.png" alt="Cartography Skill" width="800" style="border-radius: 10px; margin: 20px 0;">
-
-`cartography` empowers the Orchestrator to build and maintain a deep architectural understanding of any codebase. Instead of reading thousands of lines of code every time, agents refer to hierarchical `codemap.md` files that describe the *why* and *how* of each directory.
-
-**How to use:**
-
-Just ask the **Orchestrator** to `run cartography`. It will automatically detect if it needs to initialize a new map or update an existing one.
-
-**Why it's useful:**
-
-- **Instant Onboarding:** Help agents (and humans) understand unfamiliar codebases in seconds.
-- **Efficient Context:** Agents only read architectural summaries, saving tokens and improving accuracy.
-- **Change Detection:** Only modified folders are re-analyzed, making updates fast and efficient.
-- **Timeless Documentation:** Focuses on high-level design patterns that don't get stale.
-
-<details>
-<summary><b>Technical Details & Manual Control</b></summary>
-
-The skill uses a background Python engine (`cartographer.py`) to manage state and detect changes.
-
-**How it works under the hood:**
-
-1. **Initialize** - Orchestrator analyzes repo structure and runs `init` to create `.slim/cartography.json` (hashes) and empty templates.
-2. **Map** - Orchestrator spawns specialized **Explorer** sub-agents to fill codemaps with timeless architectural details (Responsibility, Design, Flow, Integration).
-3. **Update** - On subsequent runs, the engine detects changed files and only refreshes codemaps for affected folders.
-
-**Manual Commands:**
-
-```bash
-# Initialize mapping manually
-python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py init \
-  --root . \
-  --include "src/**/*.ts" \
-  --exclude "**/*.test.ts"
-
-# Check for changes since last map
-python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py changes --root .
-
-# Sync hashes after manual map updates
-python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py update --root .
-```
-</details>
-
-### Skills Assignment
-
-You can customize which skills each agent is allowed to use in `~/.config/opencode/oh-my-opencode-slim.json`.
-
-**Syntax:**
-
-| Syntax | Description | Example |
-|--------|-------------|---------|
-| `"*"` | All installed skills | `["*"]` |
-| `"!item"` | Exclude specific skill | `["*", "!agent-browser"]` |
-| Explicit list | Only listed skills | `["simplify"]` |
-| `"!*"` | Deny all skills | `["!*"]` |
-
-**Rules:**
-- `*` expands to all available skills
-- `!item` excludes specific skills
-- Conflicts (e.g., `["a", "!a"]`) → deny wins (principle of least privilege)
-- Empty list `[]` → no skills allowed
-
-**Example Configuration:**
-
-```json
-{
-  "presets": {
-    "my-preset": {
-      "orchestrator": {
-        "skills": ["*", "!agent-browser"]
-      },
-      "designer": {
-        "skills": ["agent-browser", "simplify"]
-      }
-    }
-  }
-}
-```
-
----
-
-## 🔌 MCP Servers
-
-Built-in Model Context Protocol servers (enabled by default):
-
-| MCP | Purpose | URL |
-|-----|---------|-----|
-| `websearch` | Real-time web search via Exa AI | `https://mcp.exa.ai/mcp` |
-| `context7` | Official library documentation | `https://mcp.context7.com/mcp` |
-| `grep_app` | GitHub code search via grep.app | `https://mcp.grep.app` |
-
-### MCP Permissions
-
-Control which agents can access which MCP servers using per-agent allowlists:
-
-| Agent | Default MCPs |
-|-------|--------------|
-| `orchestrator` | `websearch` |
-| `designer` | none |
-| `oracle` | none |
-| `librarian` | `websearch`, `context7`, `grep_app` |
-| `explorer` | none |
-| `fixer` | none |
-
-### Configuration & Syntax
-
-You can configure MCP access in your plugin configuration file: `~/.config/opencode/oh-my-opencode-slim.json`.
-
-**Per-Agent Permissions**
-
-Control which agents can access which MCP servers using the `mcps` array in your preset. The syntax is the same as for skills:
-
-| Syntax | Description | Example |
-|--------|-------------|---------|
-| `"*"` | All MCPs | `["*"]` |
-| `"!item"` | Exclude specific MCP | `["*", "!context7"]` |
-| Explicit list | Only listed MCPs | `["websearch", "context7"]` |
-| `"!*"` | Deny all MCPs | `["!*"]` |
-
-**Rules:**
-- `*` expands to all available MCPs
-- `!item` excludes specific MCPs
-- Conflicts (e.g., `["a", "!a"]`) → deny wins
-- Empty list `[]` → no MCPs allowed
-
-**Example Configuration:**
-
-```json
-{
-  "presets": {
-    "my-preset": {
-      "orchestrator": {
-        "mcps": ["websearch"]
-      },
-      "librarian": {
-        "mcps": ["websearch", "context7", "grep_app"]
-      },
-      "oracle": {
-        "mcps": ["*", "!websearch"]
-      }
-    }
-  }
-}
-```
-
-**Global Disabling**
-
-You can disable specific MCP servers globally by adding them to the `disabled_mcps` array at the root of your config object.
-
----
-
-## 🛠️ Tools & Capabilities
-
-### Tmux Integration
-
-> ⚠️ **Temporary workaround:** Start OpenCode with `--port` to enable tmux integration. The port must match the `OPENCODE_PORT` environment variable (default: 4096). This is required until the upstream issue is resolved. [opencode#9099](https://github.com/anomalyco/opencode/issues/9099).
-
-<img src="img/tmux.png" alt="Tmux Integration" width="800">
-
-**Watch your agents work in real-time.** When the Orchestrator launches sub-agents or initiates background tasks, new tmux panes automatically spawn showing each agent's live progress. No more waiting in the dark.
-
-#### Quick Setup
-
-1. **Enable tmux integration** in `oh-my-opencode-slim.json` (see [Plugin Config](#plugin-config-oh-my-opencode-slimjson)).
-
-  ```json
-  {
-    "tmux": {
-      "enabled": true,
-      "layout": "main-vertical",
-      "main_pane_size": 60
-    }
-  }
-  ```
-
-2. **Run OpenCode inside tmux**:
-    ```bash
-    tmux
-    opencode --port 4096
-    ```
-
-   Or use a custom port (must match `OPENCODE_PORT` env var):
-    ```bash
-    tmux
-    export OPENCODE_PORT=5000
-    opencode --port 5000
-    ```
-
-   This allows multiple OpenCode instances on different ports.
-
-
-#### Layout Options
-
-| Layout | Description |
-|--------|-------------|
-| `main-vertical` | Your session on the left (60%), agents stacked on the right |
-| `main-horizontal` | Your session on top (60%), agents stacked below |
-| `tiled` | All panes in equal-sized grid |
-| `even-horizontal` | All panes side by side |
-| `even-vertical` | All panes stacked vertically |
-
----
-
-### Background Tasks
-
-The plugin provides tools to manage asynchronous work:
-
-| Tool | Description |
-|------|-------------|
-| `background_task` | Launch an agent in a new session (`sync=true` blocks, `sync=false` runs in background) |
-| `background_output` | Fetch the result of a background task by ID |
-| `background_cancel` | Abort running tasks |
-
----
-
-### LSP Tools
-
-Language Server Protocol integration for code intelligence:
-
-| Tool | Description |
-|------|-------------|
-| `lsp_goto_definition` | Jump to symbol definition |
-| `lsp_find_references` | Find all usages of a symbol across the workspace |
-| `lsp_diagnostics` | Get errors/warnings from the language server |
-| `lsp_rename` | Rename a symbol across all files |
-
-> **Built-in LSP Servers:** OpenCode includes pre-configured LSP servers for 30+ languages (TypeScript, Python, Rust, Go, etc.). See the [official documentation](https://opencode.ai/docs/lsp/#built-in) for the full list and requirements.
-
----
-
-### Code Search Tools
-
-Fast code search and refactoring:
-
-| Tool | Description |
-|------|-------------|
-| `grep` | Fast content search using ripgrep |
-| `ast_grep_search` | AST-aware code pattern matching (25 languages) |
-| `ast_grep_replace` | AST-aware code refactoring with dry-run support |
-
----
-
-### Formatters
-
-OpenCode automatically formats files after they're written or edited using language-specific formatters.
-
-> **Built-in Formatters:** Includes support for Prettier, Biome, gofmt, rustfmt, ruff, and 20+ others. See the [official documentation](https://opencode.ai/docs/formatters/#built-in) for the complete list.
-
----
-
-## ⚙️ Configuration
-
-### Files You Edit
-
-| File | Purpose |
-|------|---------|
-| `~/.config/opencode/opencode.json` | OpenCode core settings |
-| `~/.config/opencode/oh-my-opencode-slim.json` | Plugin settings (agents, tmux, MCPs) |
-| `.opencode/oh-my-opencode-slim.json` | Project-local plugin overrides (optional) |
-
----
-
-### Prompt Overriding
-
-You can customize agent prompts by creating markdown files in `~/.config/opencode/oh-my-opencode-slim/`:
-
-| File | Purpose |
-|------|---------|
-| `{agent}.md` | Replaces the default prompt entirely |
-| `{agent}_append.md` | Appends to the default prompt |
-
-**Example:**
-
-```
-~/.config/opencode/oh-my-opencode-slim/
-  ├── orchestrator.md          # Custom orchestrator prompt
-  ├── orchestrator_append.md   # Append to default orchestrator prompt
-  ├── explorer.md
-  ├── explorer_append.md
-  └── ...
-```
-
-**Usage:**
-
-- Create `{agent}.md` to completely replace an agent's default prompt
-- Create `{agent}_append.md` to add custom instructions to the default prompt
-- Both files can exist simultaneously - the replacement takes precedence
-- If neither file exists, the default prompt is used
-
-This allows you to fine-tune agent behavior without modifying the source code.
-
----
-
-### Plugin Config (`oh-my-opencode-slim.json`)
-
-The installer generates this file based on your providers. You can manually customize it to mix and match models. See the [Presets](#️-presets) section for detailed configuration options.
-
-#### Option Reference
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `preset` | string | - | Name of the preset to use (e.g., `"openai"`, `"cliproxy"`) |
-| `presets` | object | - | Named preset configurations containing agent mappings |
-| `presets.<name>.<agent>.model` | string | - | Model ID for the agent (e.g., `"google/claude-opus-4-5-thinking"`) |
-| `presets.<name>.<agent>.temperature` | number | - | Temperature setting (0-2) for the agent |
-| `presets.<name>.<agent>.variant` | string | - | Agent variant for reasoning effort (e.g., `"low"`, `"medium"`, `"high"`) |
-| `presets.<name>.<agent>.skills` | string[] | - | Array of skill names the agent can use (`"*"` for all, `"!item"` to exclude) |
-| `presets.<name>.<agent>.mcps` | string[] | - | Array of MCP names the agent can use (`"*"` for all, `"!item"` to exclude) |
-| `tmux.enabled` | boolean | `false` | Enable tmux pane spawning for sub-agents |
-| `tmux.layout` | string | `"main-vertical"` | Layout preset: `main-vertical`, `main-horizontal`, `tiled`, `even-horizontal`, `even-vertical` |
-| `tmux.main_pane_size` | number | `60` | Main pane size as percentage (20-80) |
-| `disabled_mcps` | string[] | `[]` | MCP server IDs to disable globally (e.g., `"websearch"`) |
-
-> **Note:** Agent configuration should be defined within `presets`. The root-level `agents` field is deprecated.
-
----
-
-## 🗑️ Uninstallation
-
-1. **Remove the plugin from your OpenCode config**:
-
-   Edit `~/.config/opencode/opencode.json` and remove `"oh-my-opencode-slim"` from the `plugin` array.
+## 📚 Documentation
 
-2. **Remove configuration files (optional)**:
-   ```bash
-   rm -f ~/.config/opencode/oh-my-opencode-slim.json
-   rm -f .opencode/oh-my-opencode-slim.json
-   ```
+- **[Quick Reference](docs/quick-reference.md)** - Presets, Skills, MCPs, Tools, Configuration
+- **[Installation Guide](docs/installation.md)** - Detailed installation and troubleshooting
 
 ---
 
@@ -996,4 +344,4 @@ This is a slimmed-down fork of [oh-my-opencode](https://github.com/code-yeongyu/
 
 ## 📄 License
 
-MIT
+MIT

docs/installation.md

@@ -0,0 +1,231 @@
+# Installation Guide
+
+Complete installation instructions for oh-my-opencode-slim.
+
+## Table of Contents
+
+- [For Humans](#for-humans)
+- [For LLM Agents](#for-llm-agents)
+- [Troubleshooting](#troubleshooting)
+- [Uninstallation](#uninstallation)
+
+---
+
+## For Humans
+
+### Quick Install
+
+Run the interactive installer:
+
+```bash
+bunx oh-my-opencode-slim@latest install
+```
+
+Or use non-interactive mode:
+
+```bash
+bunx oh-my-opencode-slim@latest install --no-tui --antigravity=yes --openai=yes --tmux=no
+```
+
+### After Installation
+
+Authenticate with your providers:
+
+```bash
+opencode auth login
+# Select your provider → Complete OAuth flow
+# Repeat for each provider you enabled
+```
+
+Once authenticated, run opencode and `ping all agents` to verify all agents respond.
+
+> **💡 Tip: Models are fully customizable.** The installer sets sensible defaults, but you can assign *any* model to *any* agent. Edit `~/.config/opencode/oh-my-opencode-slim.json` to override models, adjust reasoning effort, or disable agents entirely. See [Configuration](quick-reference.md#configuration) for details.
+
+### Alternative: Ask Any Coding Agent
+
+Paste this into Claude Code, AmpCode, Cursor, or any coding agent:
+
+```
+Install and configure by following the instructions here:
+https://raw.githubusercontent.com/alvinunreal/oh-my-opencode-slim/refs/heads/master/README.md
+```
+
+---
+
+## For LLM Agents
+
+If you're an LLM Agent helping set up oh-my-opencode-slim, follow these steps.
+
+### Step 1: Check OpenCode Installation
+
+```bash
+opencode --version
+```
+
+If not installed, direct the user to https://opencode.ai/docs first.
+
+### Step 2: Ask About Provider Access
+
+Ask these questions **one at a time**, waiting for responses:
+
+1. "Do you have an **Antigravity** subscription (via cliproxy)?" *(Provides Claude + Gemini via `cliproxy/` prefix)*
+2. "Do you have access to **OpenAI** API?" *(Enables `openai/` models)*
+
+Help the user understand the tradeoffs:
+- Antigravity via cliproxy provides Claude + Gemini routing.
+- OpenAI is optional; it enables `openai/` models.
+- If the user has **no providers**, the plugin still works using **OpenCode Zen** free models (`opencode/big-pickle`). They can switch to paid providers later by editing `~/.config/opencode/oh-my-opencode-slim.json`.
+
+### Step 3: Run the Installer
+
+Based on answers, run:
+
+```bash
+bunx oh-my-opencode-slim@latest install --no-tui --antigravity=<yes|no> --openai=<yes|no>
+```
+
+**Examples:**
+```bash
+# Antigravity + OpenAI
+bunx oh-my-opencode-slim@latest install --no-tui --antigravity=yes --openai=yes --tmux=no
+
+# OpenAI only
+bunx oh-my-opencode-slim@latest install --no-tui --antigravity=no --openai=yes --tmux=no
+
+# No providers (Zen free models only)
+bunx oh-my-opencode-slim@latest install --no-tui --antigravity=no --openai=no --tmux=no
+```
+
+The installer automatically:
+- Adds the plugin to `~/.config/opencode/opencode.json`
+- Configures cliproxy provider for Antigravity models
+- Generates agent model mappings in `~/.config/opencode/oh-my-opencode-slim.json`
+
+**Crucial Advice for the User:**
+- They can easily assign **different models to different agents** by editing `~/.config/opencode/oh-my-opencode-slim.json`.
+- If they add a new provider later, they just need to update this file.
+- Read generated `~/.config/opencode/oh-my-opencode-slim.json` file and report the model configuration.
+
+### Step 4: Install and Configure Cliproxy (if using Antigravity)
+
+If the user selected Antigravity, guide them to install cliproxy:
+
+**macOS:**
+```bash
+brew install cliproxyapi
+brew services start cliproxyapi
+```
+
+**Linux:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/brokechubb/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer | bash
+```
+
+**Authenticate with Antigravity:**
+```bash
+./cli-proxy-api --antigravity-login
+```
+
+**For OpenAI (if enabled):**
+Ask user to run the following command.
+Don't run it yourself, it requires user interaction.
+```bash
+opencode auth login
+# Select your provider and complete OAuth flow
+```
+
+---
+
+## Troubleshooting
+
+### Installer Fails
+
+Check the expected config format:
+```bash
+bunx oh-my-opencode-slim@latest install --help
+```
+
+Then manually create the config files at:
+- `~/.config/opencode/oh-my-opencode-slim.json`
+
+### Agents Not Responding
+
+1. Check your authentication:
+   ```bash
+   opencode auth status
+   ```
+
+2. Verify your config file exists and is valid:
+   ```bash
+   cat ~/.config/opencode/oh-my-opencode-slim.json
+   ```
+
+3. Check that your provider is configured in `~/.config/opencode/opencode.json`
+
+### Cliproxy Issues
+
+If cliproxy is not working:
+
+1. Check if the service is running:
+   ```bash
+   # macOS
+   brew services list | grep cliproxy
+
+   # Linux
+   ps aux | grep cli-proxy-api
+   ```
+
+2. Test the connection:
+   ```bash
+   curl http://127.0.0.1:8317/v1/models
+   ```
+
+3. Check your authentication:
+   ```bash
+   ./cli-proxy-api --antigravity-login
+   ```
+
+### Tmux Integration Not Working
+
+Make sure you're running OpenCode with the `--port` flag and the port matches your `OPENCODE_PORT` environment variable:
+
+```bash
+tmux
+export OPENCODE_PORT=4096
+opencode --port 4096
+```
+
+See the [Quick Reference](quick-reference.md#tmux-integration) for more details.
+
+---
+
+## Uninstallation
+
+1. **Remove the plugin from your OpenCode config**:
+
+   Edit `~/.config/opencode/opencode.json` and remove `"oh-my-opencode-slim"` from the `plugin` array.
+
+2. **Remove configuration files (optional)**:
+   ```bash
+   rm -f ~/.config/opencode/oh-my-opencode-slim.json
+   rm -f .opencode/oh-my-opencode-slim.json
+   ```
+
+3. **Remove skills (optional)**:
+   ```bash
+   npx skills remove simplify
+   npx skills remove agent-browser
+   ```
+
+4. **Stop cliproxy (if installed)**:
+   ```bash
+   # macOS
+   brew services stop cliproxyapi
+   brew uninstall cliproxyapi
+
+   # Linux
+   # Stop the service manually
+   pkill cli-proxy-api
+   # Remove the binary
+   rm -f /usr/local/bin/cli-proxy-api
+   ```

docs/quick-reference.md

@@ -0,0 +1,480 @@
+# Quick Reference Guide
+
+Complete reference for oh-my-opencode-slim configuration and capabilities.
+
+## Table of Contents
+
+- [Presets](#presets)
+- [Skills](#skills)
+- [MCP Servers](#mcp-servers)
+- [Tools & Capabilities](#tools--capabilities)
+- [Configuration](#configuration)
+
+---
+
+## Presets
+
+Presets are pre-configured agent model mappings for different provider combinations. The installer generates these automatically based on your available providers, and you can switch between them instantly.
+
+### Switching Presets
+
+**Method 1: Edit Config File**
+
+Edit `~/.config/opencode/oh-my-opencode-slim.json` and change the `preset` field:
+
+```json
+{
+  "preset": "openai"
+}
+```
+
+**Method 2: Environment Variable**
+
+Set the environment variable before running OpenCode:
+
+```bash
+export OH_MY_OPENCODE_SLIM_PRESET=openai
+opencode
+```
+
+The environment variable takes precedence over the config file.
+
+### OpenAI Preset
+
+Uses OpenAI models exclusively:
+
+```json
+{
+  "preset": "openai",
+  "presets": {
+    "openai": {
+      "orchestrator": { "model": "openai/gpt-5.2-codex", "skills": ["*"], "mcps": ["websearch"] },
+      "oracle": { "model": "openai/gpt-5.2-codex", "variant": "high", "skills": [], "mcps": [] },
+      "librarian": { "model": "openai/gpt-5.1-codex-mini", "variant": "low", "skills": [], "mcps": ["websearch", "context7", "grep_app"] },
+      "explorer": { "model": "openai/gpt-5.1-codex-mini", "variant": "low", "skills": [], "mcps": [] },
+      "designer": { "model": "openai/gpt-5.1-codex-mini", "variant": "medium", "skills": ["agent-browser"], "mcps": [] },
+      "fixer": { "model": "openai/gpt-5.1-codex-mini", "variant": "low", "skills": [], "mcps": [] }
+    }
+  }
+}
+```
+
+### Antigravity via CLIProxy Preset
+
+Routes through Antigravity's CLIProxy for Claude + Gemini models:
+
+```json
+{
+  "preset": "cliproxy",
+  "presets": {
+    "cliproxy": {
+      "orchestrator": { "model": "cliproxy/gemini-claude-opus-4-5-thinking", "skills": ["*"], "mcps": ["websearch"] },
+      "oracle": { "model": "cliproxy/gemini-3-pro-preview", "variant": "high", "skills": [], "mcps": [] },
+      "librarian": { "model": "cliproxy/gemini-3-flash-preview", "variant": "low", "skills": [], "mcps": ["websearch", "context7", "grep_app"] },
+      "explorer": { "model": "cliproxy/gemini-3-flash-preview", "variant": "low", "skills": [], "mcps": [] },
+      "designer": { "model": "cliproxy/gemini-3-flash-preview", "variant": "medium", "skills": ["agent-browser"], "mcps": [] },
+      "fixer": { "model": "cliproxy/gemini-3-flash-preview", "variant": "low", "skills": [], "mcps": [] }
+    }
+  }
+}
+```
+
+<details>
+<summary>Verify provider configuration in ~/.config/opencode/opencode.json</summary>
+
+```json
+{
+  "provider": {
+    "cliproxy": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "CliProxy",
+      "options": {
+        "baseURL": "http://127.0.0.1:8317/v1",
+        "apiKey": "your-api-key-1"
+      },
+      "models": {
+        "gemini-3-pro-high": {
+          "name": "Gemini 3 Pro High",
+          "thinking": true,
+          "attachment": true,
+          "limit": { "context": 1048576, "output": 65535 },
+          "modalities": { "input": [ "text", "image", "pdf" ], "output": [ "text" ] }
+        },
+        "gemini-3-flash-preview": {
+          "name": "Gemini 3 Flash",
+          "attachment": true,
+          "limit": { "context": 1048576, "output": 65536 },
+          "modalities": { "input": [ "text", "image", "pdf" ], "output": [ "text" ] }
+        },
+        "gemini-claude-opus-4-5-thinking": {
+          "name": "Claude Opus 4.5 Thinking",
+          "attachment": true,
+          "limit": { "context": 200000, "output": 32000 },
+          "modalities": { "input": [ "text", "image", "pdf" ], "output": [ "text" ] }
+        },
+        "gemini-claude-sonnet-4-5-thinking": {
+          "name": "Claude Sonnet 4.5 Thinking",
+          "attachment": true,
+          "limit": { "context": 200000, "output": 32000 },
+          "modalities": { "input": [ "text", "image", "pdf" ], "output": [ "text" ] }
+        }
+      }
+    }
+  }
+}
+```
+
+</details>
+
+### Author's Preset
+
+Mixed setup combining multiple providers:
+
+```json
+{
+  "preset": "alvin",
+  "presets": {
+    "alvin": {
+      "orchestrator": { "model": "cliproxy/gemini-claude-opus-4-5-thinking", "skills": ["*"], "mcps": ["*"] },
+      "oracle": { "model": "openai/gpt-5.2-codex", "variant": "high", "skills": [], "mcps": [] },
+      "librarian": { "model": "cliproxy/gemini-3-flash-preview", "variant": "low", "skills": [], "mcps": ["websearch", "context7", "grep_app"] },
+      "explorer": { "model": "cerebras/zai-glm-4.7", "variant": "low", "skills": [], "mcps": [] },
+      "designer": { "model": "cliproxy/gemini-3-flash-preview", "variant": "medium", "skills": ["agent-browser"], "mcps": [] },
+      "fixer": { "model": "cerebras/zai-glm-4.7", "variant": "low", "skills": [], "mcps": [] }
+    }
+  }
+}
+```
+
+---
+
+## Skills
+
+Skills are specialized capabilities provided by external agents and tools. Unlike MCPs which are servers, skills are prompt-based tool configurations installed via `npx skills add` during installation.
+
+### Recommended Skills (via npx)
+
+| Skill | Description | Assigned To |
+|-------|-------------|-------------|
+| [`simplify`](#simplify) | YAGNI code simplification expert | `orchestrator` |
+| [`agent-browser`](#agent-browser) | High-performance browser automation | `designer` |
+
+### Custom Skills (bundled in repo)
+
+| Skill | Description | Assigned To |
+|-------|-------------|-------------|
+| [`cartography`](#cartography) | Repository understanding and hierarchical codemap generation | `orchestrator` |
+
+### Simplify
+
+**The Minimalist's sacred truth: every line of code is a liability.**
+
+`simplify` is a specialized skill for complexity analysis and YAGNI enforcement. It identifies unnecessary abstractions and suggests minimal implementations.
+
+### Agent Browser
+
+**External browser automation for visual verification and testing.**
+
+`agent-browser` provides full high-performance browser automation capabilities. It allows agents to browse the web, interact with elements, and capture screenshots for visual state verification.
+
+### Cartography
+
+**Automated repository mapping through hierarchical codemaps.**
+
+`cartography` empowers the Orchestrator to build and maintain a deep architectural understanding of any codebase. Instead of reading thousands of lines of code every time, agents refer to hierarchical `codemap.md` files that describe the *why* and *how* of each directory.
+
+**How to use:**
+
+Just ask the **Orchestrator** to `run cartography`. It will automatically detect if it needs to initialize a new map or update an existing one.
+
+**Why it's useful:**
+
+- **Instant Onboarding:** Help agents (and humans) understand unfamiliar codebases in seconds.
+- **Efficient Context:** Agents only read architectural summaries, saving tokens and improving accuracy.
+- **Change Detection:** Only modified folders are re-analyzed, making updates fast and efficient.
+- **Timeless Documentation:** Focuses on high-level design patterns that don't get stale.
+
+<details>
+<summary><b>Technical Details & Manual Control</b></summary>
+
+The skill uses a background Python engine (`cartographer.py`) to manage state and detect changes.
+
+**How it works under the hood:**
+
+1. **Initialize** - Orchestrator analyzes repo structure and runs `init` to create `.slim/cartography.json` (hashes) and empty templates.
+2. **Map** - Orchestrator spawns specialized **Explorer** sub-agents to fill codemaps with timeless architectural details (Responsibility, Design, Flow, Integration).
+3. **Update** - On subsequent runs, the engine detects changed files and only refreshes codemaps for affected folders.
+
+**Manual Commands:**
+
+```bash
+# Initialize mapping manually
+python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py init \
+  --root . \
+  --include "src/**/*.ts" \
+  --exclude "**/*.test.ts"
+
+# Check for changes since last map
+python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py changes --root .
+
+# Sync hashes after manual map updates
+python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py update --root .
+```
+</details>
+
+### Skills Assignment
+
+You can customize which skills each agent is allowed to use in `~/.config/opencode/oh-my-opencode-slim.json`.
+
+**Syntax:**
+
+| Syntax | Description | Example |
+|--------|-------------|---------|
+| `"*"` | All installed skills | `["*"]` |
+| `"!item"` | Exclude specific skill | `["*", "!agent-browser"]` |
+| Explicit list | Only listed skills | `["simplify"]` |
+| `"!*"` | Deny all skills | `["!*"]` |
+
+**Rules:**
+- `*` expands to all available skills
+- `!item` excludes specific skills
+- Conflicts (e.g., `["a", "!a"]`) → deny wins (principle of least privilege)
+- Empty list `[]` → no skills allowed
+
+**Example Configuration:**
+
+```json
+{
+  "presets": {
+    "my-preset": {
+      "orchestrator": {
+        "skills": ["*", "!agent-browser"]
+      },
+      "designer": {
+        "skills": ["agent-browser", "simplify"]
+      }
+    }
+  }
+}
+```
+
+---
+
+## MCP Servers
+
+Built-in Model Context Protocol servers (enabled by default):
+
+| MCP | Purpose | URL |
+|-----|---------|-----|
+| `websearch` | Real-time web search via Exa AI | `https://mcp.exa.ai/mcp` |
+| `context7` | Official library documentation | `https://mcp.context7.com/mcp` |
+| `grep_app` | GitHub code search via grep.app | `https://mcp.grep.app` |
+
+### MCP Permissions
+
+Control which agents can access which MCP servers using per-agent allowlists:
+
+| Agent | Default MCPs |
+|-------|--------------|
+| `orchestrator` | `websearch` |
+| `designer` | none |
+| `oracle` | none |
+| `librarian` | `websearch`, `context7`, `grep_app` |
+| `explorer` | none |
+| `fixer` | none |
+
+### Configuration & Syntax
+
+You can configure MCP access in your plugin configuration file: `~/.config/opencode/oh-my-opencode-slim.json`.
+
+**Per-Agent Permissions**
+
+Control which agents can access which MCP servers using the `mcps` array in your preset. The syntax is the same as for skills:
+
+| Syntax | Description | Example |
+|--------|-------------|---------|
+| `"*"` | All MCPs | `["*"]` |
+| `"!item"` | Exclude specific MCP | `["*", "!context7"]` |
+| Explicit list | Only listed MCPs | `["websearch", "context7"]` |
+| `"!*"` | Deny all MCPs | `["!*"]` |
+
+**Rules:**
+- `*` expands to all available MCPs
+- `!item` excludes specific MCPs
+- Conflicts (e.g., `["a", "!a"]`) → deny wins
+- Empty list `[]` → no MCPs allowed
+
+**Example Configuration:**
+
+```json
+{
+  "presets": {
+    "my-preset": {
+      "orchestrator": {
+        "mcps": ["websearch"]
+      },
+      "librarian": {
+        "mcps": ["websearch", "context7", "grep_app"]
+      },
+      "oracle": {
+        "mcps": ["*", "!websearch"]
+      }
+    }
+  }
+}
+```
+
+**Global Disabling**
+
+You can disable specific MCP servers globally by adding them to the `disabled_mcps` array at the root of your config object.
+
+---
+
+## Tools & Capabilities
+
+### Tmux Integration
+
+> ⚠️ **Temporary workaround:** Start OpenCode with `--port` to enable tmux integration. The port must match the `OPENCODE_PORT` environment variable (default: 4096). This is required until the upstream issue is resolved. [opencode#9099](https://github.com/anomalyco/opencode/issues/9099).
+
+**Watch your agents work in real-time.** When the Orchestrator launches sub-agents or initiates background tasks, new tmux panes automatically spawn showing each agent's live progress. No more waiting in the dark.
+
+#### Quick Setup
+
+1. **Enable tmux integration** in `oh-my-opencode-slim.json` (see [Plugin Config](#plugin-config-oh-my-opencode-slimjson)).
+
+   ```json
+   {
+     "tmux": {
+       "enabled": true,
+       "layout": "main-vertical",
+       "main_pane_size": 60
+     }
+   }
+   ```
+
+2. **Run OpenCode inside tmux**:
+    ```bash
+    tmux
+    opencode --port 4096
+    ```
+
+   Or use a custom port (must match `OPENCODE_PORT` env var):
+    ```bash
+    tmux
+    export OPENCODE_PORT=5000
+    opencode --port 5000
+    ```
+
+   This allows multiple OpenCode instances on different ports.
+
+#### Layout Options
+
+| Layout | Description |
+|--------|-------------|
+| `main-vertical` | Your session on the left (60%), agents stacked on the right |
+| `main-horizontal` | Your session on top (60%), agents stacked below |
+| `tiled` | All panes in equal-sized grid |
+| `even-horizontal` | All panes side by side |
+| `even-vertical` | All panes stacked vertically |
+
+### Background Tasks
+
+The plugin provides tools to manage asynchronous work:
+
+| Tool | Description |
+|------|-------------|
+| `background_task` | Launch an agent in a new session (`sync=true` blocks, `sync=false` runs in background) |
+| `background_output` | Fetch the result of a background task by ID |
+| `background_cancel` | Abort running tasks |
+
+### LSP Tools
+
+Language Server Protocol integration for code intelligence:
+
+| Tool | Description |
+|------|-------------|
+| `lsp_goto_definition` | Jump to symbol definition |
+| `lsp_find_references` | Find all usages of a symbol across the workspace |
+| `lsp_diagnostics` | Get errors/warnings from the language server |
+| `lsp_rename` | Rename a symbol across all files |
+
+> **Built-in LSP Servers:** OpenCode includes pre-configured LSP servers for 30+ languages (TypeScript, Python, Rust, Go, etc.). See the [official documentation](https://opencode.ai/docs/lsp/#built-in) for the full list and requirements.
+
+### Code Search Tools
+
+Fast code search and refactoring:
+
+| Tool | Description |
+|------|-------------|
+| `grep` | Fast content search using ripgrep |
+| `ast_grep_search` | AST-aware code pattern matching (25 languages) |
+| `ast_grep_replace` | AST-aware code refactoring with dry-run support |
+
+### Formatters
+
+OpenCode automatically formats files after they're written or edited using language-specific formatters.
+
+> **Built-in Formatters:** Includes support for Prettier, Biome, gofmt, rustfmt, ruff, and 20+ others. See the [official documentation](https://opencode.ai/docs/formatters/#built-in) for the complete list.
+
+---
+
+## Configuration
+
+### Files You Edit
+
+| File | Purpose |
+|------|---------|
+| `~/.config/opencode/opencode.json` | OpenCode core settings |
+| `~/.config/opencode/oh-my-opencode-slim.json` | Plugin settings (agents, tmux, MCPs) |
+| `.opencode/oh-my-opencode-slim.json` | Project-local plugin overrides (optional) |
+
+### Prompt Overriding
+
+You can customize agent prompts by creating markdown files in `~/.config/opencode/oh-my-opencode-slim/`:
+
+| File | Purpose |
+|------|---------|
+| `{agent}.md` | Replaces the default prompt entirely |
+| `{agent}_append.md` | Appends to the default prompt |
+
+**Example:**
+
+```
+~/.config/opencode/oh-my-opencode-slim/
+  ├── orchestrator.md          # Custom orchestrator prompt
+  ├── orchestrator_append.md   # Append to default orchestrator prompt
+  ├── explorer.md
+  ├── explorer_append.md
+  └── ...
+```
+
+**Usage:**
+
+- Create `{agent}.md` to completely replace an agent's default prompt
+- Create `{agent}_append.md` to add custom instructions to the default prompt
+- Both files can exist simultaneously - the replacement takes precedence
+- If neither file exists, the default prompt is used
+
+This allows you to fine-tune agent behavior without modifying the source code.
+
+### Plugin Config (`oh-my-opencode-slim.json`)
+
+The installer generates this file based on your providers. You can manually customize it to mix and match models. See the [Presets](#presets) section for detailed configuration options.
+
+#### Option Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `preset` | string | - | Name of the preset to use (e.g., `"openai"`, `"cliproxy"`) |
+| `presets` | object | - | Named preset configurations containing agent mappings |
+| `presets.<name>.<agent>.model` | string | - | Model ID for the agent (e.g., `"google/claude-opus-4-5-thinking"`) |
+| `presets.<name>.<agent>.temperature` | number | - | Temperature setting (0-2) for the agent |
+| `presets.<name>.<agent>.variant` | string | - | Agent variant for reasoning effort (e.g., `"low"`, `"medium"`, `"high"`) |
+| `presets.<name>.<agent>.skills` | string[] | - | Array of skill names the agent can use (`"*"` for all, `"!item"` to exclude) |
+| `presets.<name>.<agent>.mcps` | string[] | - | Array of MCP names the agent can use (`"*"` for all, `"!item"` to exclude) |
+| `tmux.enabled` | boolean | `false` | Enable tmux pane spawning for sub-agents |
+| `tmux.layout` | string | `"main-vertical"` | Layout preset: `main-vertical`, `main-horizontal`, `tiled`, `even-horizontal`, `even-vertical` |
+| `tmux.main_pane_size` | number | `60` | Main pane size as percentage (20-80) |
+| `disabled_mcps` | string[] | `[]` | MCP server IDs to disable globally (e.g., `"websearch"`) |
+
+> **Note:** Agent configuration should be defined within `presets`. The root-level `agents` field is deprecated.