Update readme

README.md

@@ -56,11 +56,6 @@ https://raw.githubusercontent.com/alvinunreal/oh-my-opencode-slim/refs/heads/mas
 
 **Detailed installation guide:** [docs/installation.md](docs/installation.md)
 
-**Additional guides:**
-- **[Provider Configurations](docs/provider-configurations.md)** - Config examples for all supported providers
-- **[Tmux Integration](docs/tmux-integration.md)** - Real-time agent monitoring with tmux
-**[Quick Reference](docs/quick-reference.md)** - Config, fallback behavior, skills, MCPs
-
 ### ✅ Verify Your Setup
 
 After installation and authentication, verify all agents are configured and responding:
@@ -304,12 +299,35 @@ If any agent fails to respond, check your provider authentication and config fil
 
 ## 📚 Documentation
 
-- **[Quick Reference](docs/quick-reference.md)** - Skills, MCPs, Tools, Configuration
-- **[Provider Configurations](docs/provider-configurations.md)** - Config examples for OpenAI, Kimi, Copilot, ZAI
-- **[Installation Guide](docs/installation.md)** - Detailed installation and troubleshooting
-- **[Cartography Skill](docs/cartography.md)** - Custom skill for repository mapping + codemap generation
-- **[Tmux Integration](docs/tmux-integration.md)** - Real-time agent monitoring with tmux
-**[Quick Reference](docs/quick-reference.md)** - Config, fallback behavior, skills, MCPs
+### 🚀 Getting Started
+
+| Doc | Contents |
+|-----|----------|
+| **[Installation Guide](docs/installation.md)** | CLI flags, `--reset`, auth, troubleshooting |
+| **[Provider Configurations](docs/provider-configurations.md)** | OpenAI, Kimi, Copilot, ZAI, Fireworks AI — mixing providers, fallback chains |
+
+### ✨ Features
+
+| Feature | Doc | What it does |
+|---------|-----|--------------|
+| **Council** | [council.md](docs/council.md) | Run N models in parallel, synthesize one answer (`@council`) |
+| **Tmux Integration** | [tmux-integration.md](docs/tmux-integration.md) | Watch agents work in real-time with auto-spawned panes |
+| **Cartography Skill** | [cartography.md](docs/cartography.md) | Auto-generate hierarchical codemaps for any codebase |
+
+### ⚙️ Config & Reference
+
+| Doc | Contents |
+|-----|----------|
+| **[Skills](docs/skills.md)** | `simplify`, `agent-browser`, `cartography` — assignment syntax |
+| **[MCPs](docs/mcps.md)** | `websearch`, `context7`, `grep_app` — permissions per agent |
+| **[Tools](docs/tools.md)** | Background tasks, LSP, code search, formatters |
+| **[Configuration](docs/configuration.md)** | Config files, prompt overriding, JSONC, full option reference |
+
+### 💡 Author's Setup
+
+| Doc | Contents |
+|-----|----------|
+| **[Author's Preset](docs/authors-preset.md)** | The exact config the author runs daily — OpenAI + Fireworks AI + GitHub Copilot |
 
 ---
 

docs/authors-preset.md

@@ -0,0 +1,122 @@
+# Author's Preset
+
+This is the exact configuration the author runs day-to-day. It mixes three providers to get the best model for each role at the lowest cost: **OpenAI** for reasoning-heavy orchestration, **Fireworks AI (Kimi K2P5)** for fast/cheap breadth work, and **GitHub Copilot** for design and council diversity.
+
+---
+
+## The Config
+
+```jsonc
+{
+  "preset": "best",
+  "presets": {
+    "best": {
+      // High-reasoning orchestrator — needs to plan, delegate, and synthesize
+      "orchestrator": {
+        "model": "openai/gpt-5.4",
+        "skills": ["*"],
+        "mcps": ["*"]
+      },
+      // Strategic advisor — high variant for deep thinking
+      "oracle": {
+        "model": "openai/gpt-5.4",
+        "variant": "high",
+        "skills": [],
+        "mcps": []
+      },
+      // External knowledge retrieval — fast and cheap, with all search MCPs
+      "librarian": {
+        "model": "fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo",
+        "variant": "low",
+        "skills": [],
+        "mcps": ["websearch", "context7", "grep_app"]
+      },
+      // Codebase recon — fast model, no external tools needed
+      "explorer": {
+        "model": "fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo",
+        "variant": "low",
+        "skills": [],
+        "mcps": []
+      },
+      // UI/UX work — Gemini excels at visual reasoning and browser tasks
+      "designer": {
+        "model": "github-copilot/gemini-3.1-pro-preview",
+        "skills": ["agent-browser"],
+        "mcps": []
+      },
+      // Fast implementation — Kimi is quick and capable for focused coding tasks
+      "fixer": {
+        "model": "fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo",
+        "variant": "low",
+        "skills": [],
+        "mcps": []
+      }
+    }
+  },
+
+  // Real-time pane monitoring
+  "tmux": {
+    "enabled": true,
+    "layout": "main-vertical",
+    "main_pane_size": 60
+  },
+
+  // Council: diverse providers for maximum perspective spread
+  "council": {
+    "master": { "model": "openai/gpt-5.4" },
+    "presets": {
+      "default": {
+        "alpha": { "model": "github-copilot/claude-opus-4.6" },
+        "beta":  { "model": "github-copilot/gemini-3.1-pro-preview" },
+        "gamma": { "model": "fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo" }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Why These Choices
+
+### Orchestrator & Oracle → `openai/gpt-5.4`
+
+The Orchestrator is the most important agent — it plans, delegates, and synthesizes results from the whole team. Oracle handles hard architectural questions. Both benefit from the strongest available reasoning model.
+
+### Librarian, Explorer, Fixer → Kimi K2P5 via Fireworks AI
+
+[Fireworks AI](https://fireworks.ai) offers Kimi K2P5 as a routed endpoint (`fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo`). The model is fast and highly capable for coding tasks. These three agents do high-volume breadth work (searching, reading, writing), so speed and cost matter more than raw reasoning power.
+
+To authenticate with Fireworks AI:
+```bash
+opencode auth login
+# Select "fireworks-ai" provider
+```
+
+### Designer → `github-copilot/gemini-3.1-pro-preview`
+
+Gemini has strong multimodal and visual reasoning — good fit for UI/UX work and browser-based tasks. GitHub Copilot subscription gives access to it alongside Claude and Grok.
+
+### Council → Three Providers
+
+The council uses one model each from Anthropic (Claude), Google (Gemini), and Fireworks/Kimi — three architecturally different models. The more diverse the perspectives, the more useful the synthesis. GPT-5.4 as master keeps synthesis coherent.
+
+---
+
+## Required Authentication
+
+This preset requires three providers to be authenticated:
+
+```bash
+opencode auth login  # run once per provider
+
+# Authenticate:
+# → openai
+# → github-copilot
+# → fireworks-ai
+```
+
+Verify all agents are responding after setup:
+```
+ping all agents
+```

docs/configuration.md

@@ -0,0 +1,112 @@
+# Configuration Reference
+
+Complete reference for all configuration files and options in oh-my-opencode-slim.
+
+---
+
+## Config Files
+
+| File | Purpose |
+|------|---------|
+| `~/.config/opencode/opencode.json` | OpenCode core settings (plugin registration, providers) |
+| `~/.config/opencode/oh-my-opencode-slim.json` | Plugin settings — agents, tmux, MCPs, council |
+| `~/.config/opencode/oh-my-opencode-slim.jsonc` | Same, but with JSONC (comments + trailing commas). Takes precedence over `.json` if both exist |
+| `.opencode/oh-my-opencode-slim.json` | Project-local overrides (optional, checked first) |
+
+> **💡 JSONC recommended:** Use the `.jsonc` extension to add comments and trailing commas. If both `.jsonc` and `.json` exist, `.jsonc` takes precedence.
+
+---
+
+## Prompt Overriding
+
+Customize agent prompts without modifying source code. Create markdown files in `~/.config/opencode/oh-my-opencode-slim/`:
+
+| File | Effect |
+|------|--------|
+| `{agent}.md` | Replaces the agent's default prompt entirely |
+| `{agent}_append.md` | Appends custom instructions to the default prompt |
+
+When a `preset` is active, the plugin checks `~/.config/opencode/oh-my-opencode-slim/{preset}/` first, then falls back to the root directory.
+
+**Example directory structure:**
+
+```
+~/.config/opencode/oh-my-opencode-slim/
+  ├── best/
+  │   ├── orchestrator.md        # Preset-specific override (used when preset=best)
+  │   └── explorer_append.md
+  ├── orchestrator.md            # Fallback override
+  ├── orchestrator_append.md
+  ├── explorer.md
+  └── ...
+```
+
+Both `{agent}.md` and `{agent}_append.md` can coexist — the full replacement takes effect first, then the append. If neither exists, the built-in default prompt is used.
+
+---
+
+## JSONC Format
+
+All config files support **JSONC** (JSON with Comments):
+
+- Single-line comments (`//`)
+- Multi-line comments (`/* */`)
+- Trailing commas in arrays and objects
+
+**Example:**
+
+```jsonc
+{
+  // Active preset
+  "preset": "openai",
+
+  /* Agent model mappings */
+  "presets": {
+    "openai": {
+      "oracle": { "model": "openai/gpt-5.4" },
+      "explorer": { "model": "openai/gpt-5.4-mini" },
+    },
+  },
+
+  "tmux": {
+    "enabled": true,  // Enable pane monitoring
+    "layout": "main-vertical",
+  },
+}
+```
+
+---
+
+## Full Option Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `preset` | string | — | Active preset name (e.g. `"openai"`, `"best"`) |
+| `presets` | object | — | Named preset configurations |
+| `presets.<name>.<agent>.model` | string | — | Model ID in `provider/model` format |
+| `presets.<name>.<agent>.temperature` | number | — | Temperature (0–2) |
+| `presets.<name>.<agent>.variant` | string | — | Reasoning effort: `"low"`, `"medium"`, `"high"` |
+| `presets.<name>.<agent>.skills` | string[] | — | Skills the agent can use (`"*"`, `"!item"`, explicit list) |
+| `presets.<name>.<agent>.mcps` | string[] | — | MCPs the agent can use (`"*"`, `"!item"`, explicit list) |
+| `tmux.enabled` | boolean | `false` | Enable tmux pane spawning |
+| `tmux.layout` | string | `"main-vertical"` | Layout: `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 |
+| `fallback.enabled` | boolean | `false` | Enable model failover on timeout/error |
+| `fallback.timeoutMs` | number | `15000` | Time before aborting and trying next model |
+| `fallback.retryDelayMs` | number | `500` | Delay between retry attempts |
+| `fallback.chains.<agent>` | string[] | — | Ordered fallback model IDs for an agent |
+| `council.master.model` | string | — | **Required if using council.** Council master model |
+| `council.master.variant` | string | — | Council master variant |
+| `council.master.prompt` | string | — | Optional synthesis guidance for the master |
+| `council.presets` | object | — | **Required if using council.** Named councillor presets |
+| `council.presets.<name>.<councillor>.model` | string | — | Councillor model |
+| `council.presets.<name>.<councillor>.variant` | string | — | Councillor variant |
+| `council.presets.<name>.<councillor>.prompt` | string | — | Optional role guidance for the councillor |
+| `council.presets.<name>.master.model` | string | — | Override global master model for this preset |
+| `council.presets.<name>.master.variant` | string | — | Override global master variant for this preset |
+| `council.presets.<name>.master.prompt` | string | — | Override global master prompt for this preset |
+| `council.default_preset` | string | `"default"` | Default preset when none is specified |
+| `council.master_timeout` | number | `300000` | Master synthesis timeout (ms) |
+| `council.councillors_timeout` | number | `180000` | Per-councillor timeout (ms) |
+| `council.master_fallback` | string[] | — | Fallback models for the council master |

docs/mcps.md

@@ -0,0 +1,84 @@
+# MCP Servers
+
+Built-in Model Context Protocol (MCP) servers ship with oh-my-opencode-slim and give agents access to external tools — web search, library documentation, and code search.
+
+---
+
+## Built-in MCPs
+
+| MCP | Purpose | Endpoint |
+|-----|---------|----------|
+| `websearch` | Real-time web search via Exa AI | `https://mcp.exa.ai/mcp` |
+| `context7` | Official library documentation (up-to-date) | `https://mcp.context7.com/mcp` |
+| `grep_app` | GitHub code search via grep.app | `https://mcp.grep.app` |
+
+---
+
+## Default Permissions Per Agent
+
+| Agent | Default MCPs |
+|-------|-------------|
+| `orchestrator` | `websearch` |
+| `librarian` | `websearch`, `context7`, `grep_app` |
+| `designer` | none |
+| `oracle` | none |
+| `explorer` | none |
+| `fixer` | none |
+| `councillor` | none |
+| `council-master` | none |
+
+---
+
+## Configuring MCP Access
+
+Control which MCPs each agent can use via the `mcps` array in your preset config (`~/.config/opencode/oh-my-opencode-slim.json` or `.jsonc`):
+
+| Syntax | Meaning |
+|--------|---------|
+| `["*"]` | All MCPs |
+| `["*", "!context7"]` | All MCPs except `context7` |
+| `["websearch", "context7"]` | Only listed MCPs |
+| `[]` | No MCPs |
+| `["!*"]` | Deny all MCPs |
+
+**Rules:**
+- `*` expands to all available MCPs
+- `!item` excludes a specific MCP
+- Conflicts (e.g. `["a", "!a"]`) → deny wins
+
+**Example:**
+
+```json
+{
+  "presets": {
+    "my-preset": {
+      "orchestrator": {
+        "mcps": ["websearch"]
+      },
+      "librarian": {
+        "mcps": ["websearch", "context7", "grep_app"]
+      },
+      "oracle": {
+        "mcps": ["*", "!websearch"]
+      },
+      "fixer": {
+        "mcps": []
+      }
+    }
+  }
+}
+```
+
+---
+
+## Disabling MCPs Globally
+
+To disable specific MCPs for all agents regardless of preset, add them to `disabled_mcps` at the root of your config:
+
+```json
+{
+  "disabled_mcps": ["websearch"]
+}
+```
+
+This is useful when you want to cut external network calls entirely (e.g. air-gapped environments or cost control).

docs/provider-configurations.md

@@ -133,3 +133,45 @@ You can mix models from different providers across agents. Create a custom prese
 export OH_MY_OPENCODE_SLIM_PRESET=my-mix
 opencode
 ```
+
+---
+
+## Fallback / Failover
+
+The plugin can automatically fail over from one model to the next when a prompt times out or errors. This is separate from your preset selection — it's a runtime safety net.
+
+**How it works:**
+
+- Each agent can have a fallback chain under `fallback.chains.<agent>`
+- The agent uses its configured model first
+- If that model fails or times out, the manager aborts the session, waits briefly, and tries the next model in the chain
+- Duplicate model IDs are ignored — the same model is never retried twice
+- If fallback is disabled, tasks run with no failover
+
+**Example:**
+
+```jsonc
+{
+  "fallback": {
+    "enabled": true,
+    "timeoutMs": 15000,
+    "retryDelayMs": 500,
+    "chains": {
+      "orchestrator": [
+        "openai/gpt-5.4",
+        "anthropic/claude-sonnet-4-6",
+        "google/gemini-3.1-pro"
+      ],
+      "fixer": [
+        "fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo",
+        "openai/gpt-5.4-mini"
+      ]
+    }
+  }
+}
+```
+
+**Notes:**
+- Model IDs must use `provider/model` format
+- Chains are per agent: `orchestrator`, `oracle`, `designer`, `explorer`, `librarian`, `fixer`, `councillor`, `council-master`
+- If an agent has no chain configured, only its primary model is used

docs/quick-reference.md

@@ -1,531 +1,33 @@
-# Quick Reference Guide
+# Quick Reference
 
-Complete reference for oh-my-opencode-slim configuration and capabilities.
+> This page is an index. Each topic has its own dedicated guide.
 
-## Table of Contents
+## 🚀 Getting Started
 
-- [Presets](#presets)
-- [Skills](#skills)
-  - [Cartography](#cartography)
-- [MCP Servers](#mcp-servers)
-- [Tools & Capabilities](#tools--capabilities)
-- [Configuration](#configuration)
+| Doc | Contents |
+|-----|----------|
+| [Installation Guide](installation.md) | CLI flags, `--reset`, auth, troubleshooting |
+| [Provider Configurations](provider-configurations.md) | OpenAI, Kimi, Copilot, ZAI, Fireworks AI, mixing providers, fallback chains |
 
----
+## ✨ Features
 
-## Presets
+| Doc | Contents |
+|-----|----------|
+| [Council Agent](council.md) | Multi-LLM consensus, presets, role prompts, timeouts |
+| [Tmux Integration](tmux-integration.md) | Real-time pane monitoring, layouts, troubleshooting |
+| [Cartography Skill](cartography.md) | Hierarchical codemap generation |
 
-The default installer generates an OpenAI preset. To use alternative providers (Kimi, GitHub Copilot, ZAI Coding Plan), see **[Provider Configurations](provider-configurations.md)** for step-by-step instructions and full config examples.
+## ⚙️ Config & Reference
 
-### Switching Presets
+| Doc | Contents |
+|-----|----------|
+| [Skills](skills.md) | `simplify`, `agent-browser`, `cartography` — skills assignment syntax |
+| [MCPs](mcps.md) | `websearch`, `context7`, `grep_app` — permissions per agent, global disable |
+| [Tools](tools.md) | Background tasks, LSP, code search (`ast_grep`), formatters |
+| [Configuration](configuration.md) | Config files, prompt overriding, JSONC, full option reference table |
 
-**Method 1: Edit Config File**
+## 💡 Author's Setup
 
-Edit `~/.config/opencode/oh-my-opencode-slim.json` (or `.jsonc`) 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 (Default)
-
-Uses OpenAI models exclusively:
-
-```json
-{
-  "preset": "openai",
-  "presets": {
-    "openai": {
-      "orchestrator": { "model": "openai/gpt-5.4", "skills": ["*"], "mcps": ["websearch"] },
-      "oracle": { "model": "openai/gpt-5.4", "variant": "high", "skills": [], "mcps": [] },
-      "librarian": { "model": "openai/gpt-5.4-mini", "variant": "low", "skills": [], "mcps": ["websearch", "context7", "grep_app"] },
-      "explorer": { "model": "openai/gpt-5.4-mini", "variant": "low", "skills": [], "mcps": [] },
-      "designer": { "model": "openai/gpt-5.4-mini", "variant": "medium", "skills": ["agent-browser"], "mcps": [] },
-      "fixer": { "model": "openai/gpt-5.4-mini", "variant": "low", "skills": [], "mcps": [] }
-    }
-  }
-}
-```
-
-### Other Providers
-
-For Kimi, GitHub Copilot, and ZAI Coding Plan presets, see **[Provider Configurations](provider-configurations.md)**.
-
-### Fallback / Failover
-
-The plugin can fail over from one model to the next when a prompt times out or errors. This is the runtime fallback path used by the background task manager; it is separate from your preset selection.
-
-**How it works:**
-
-- Each agent can have a fallback chain under `fallback.chains.<agent>`
-- The active prompt uses the agent's configured model first
-- If that model fails, the manager aborts the session, waits briefly, and tries the next model in the chain
-- Duplicate model IDs are ignored, so the same model is not retried twice
-- If fallback is disabled, the task runs with no failover timeout
-
-**Minimal example:**
-
-```jsonc
-{
-  "fallback": {
-    "enabled": true,
-    "timeoutMs": 15000,
-    "retryDelayMs": 500,
-    "chains": {
-      "orchestrator": [
-        "openai/gpt-5.4",
-        "anthropic/claude-sonnet-4-6",
-        "google/gemini-3.1-pro"
-      ]
-    }
-  }
-}
-```
-
-**Important notes:**
-
-- Fallback models must use the `provider/model` format
-- Chains are per agent (`orchestrator`, `oracle`, `designer`, `explorer`, `librarian`, `fixer`, `councillor`, `council-master`)
-- If an agent has no configured chain, only its primary model is used
-- This is documented here because it is easy to miss in the config file
-
----
-
-## 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.**
-
-A dedicated guide (with screenshots) lives at: **[docs/cartography.md](cartography.md)**.
-
-`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` (or `.jsonc`).
-
-**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 |
-| `councillor` | none |
-| `council-master` | none |
-
-### Configuration & Syntax
-
-You can configure MCP access in your plugin configuration file: `~/.config/opencode/oh-my-opencode-slim.json` (or `.jsonc`).
-
-**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
-
-**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` (or `.jsonc`):
-
-   ```json
-   {
-     "tmux": {
-       "enabled": true,
-       "layout": "main-vertical",
-       "main_pane_size": 60
-     }
-   }
-   ```
-
-2. **Run OpenCode inside tmux**:
-    ```bash
-    tmux
-    opencode
-    ```
-
-#### 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 |
-
-> **Detailed Guide:** For complete tmux integration documentation, troubleshooting, and advanced usage, see [Tmux Integration](tmux-integration.md)
-
-### Council Agent
-
-**Multi-model consensus for higher-confidence answers.** The Council agent sends your prompt to multiple LLMs in parallel, then a council master synthesises the best response.
-
-#### Quick Setup
-
-Add council configuration to `oh-my-opencode-slim.json` (or `.jsonc`):
-
-```jsonc
-{
-  "council": {
-    "master": { "model": "anthropic/claude-opus-4-6" },
-    "presets": {
-      "default": {
-        "alpha": { "model": "openai/gpt-5.4-mini" },
-        "beta":  { "model": "google/gemini-3-pro" },
-        "gamma": { "model": "openai/gpt-5.3-codex" }
-      }
-    }
-  }
-}
-```
-
-Then invoke: `@council What's the best approach for rate limiting?`
-
-#### How It Works
-
-1. Prompt is sent to all councillors in parallel as agent sessions with read-only codebase access
-2. Each councillor examines the codebase (read, glob, grep, lsp, codesearch) and provides independent analysis
-3. A council master reviews all responses and synthesises the optimal answer
-4. Result is returned with a summary including model composition (`Council: 3/3 councillors responded (alpha: gpt-5.4-mini, beta: gemini-3-pro, gamma: gpt-5.3-codex)`)
-
-#### Preset Sizes
-
-| Preset | Councillors | Best For |
-|--------|-------------|----------|
-| 1-councillor | 1 | Quick second opinion from a different model |
-| 2-councillor | 2 | Compare & contrast (e.g., analytical vs. creative) |
-| 3-councillor | 3 | General consensus (default) |
-| N-councillor | N | Full review board for high-stakes decisions |
-
-Each councillor has its own model (and optional variant). Define multiple named presets and select at invocation time.
-
-> **Detailed Guide:** For complete council documentation, configuration examples, and troubleshooting, see [Council Agent](council.md)
-
-### 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` or `.jsonc` | Plugin settings (agents, tmux, MCPs) |
-| `.opencode/oh-my-opencode-slim.json` or `.jsonc` | Project-local plugin overrides (optional) |
-
-> **💡 JSONC Support:** Configuration files support JSONC format (JSON with Comments). Use `.jsonc` extension to enable comments and trailing commas. If both `.jsonc` and `.json` exist, `.jsonc` takes precedence.
-
-### Prompt Overriding
-
-You can customize agent prompts by creating markdown files in `~/.config/opencode/oh-my-opencode-slim/`:
-
-- With no preset, prompt files are loaded directly from this directory.
-- With `preset` set (for example `test`), the plugin first checks `~/.config/opencode/oh-my-opencode-slim/{preset}/`, then falls back to the root prompt directory.
-
-| File | Purpose |
-|------|---------|
-| `{agent}.md` | Replaces the default prompt entirely |
-| `{agent}_append.md` | Appends to the default prompt |
-
-**Example:**
-
-```
-~/.config/opencode/oh-my-opencode-slim/
-  ├── test/
-  │   ├── orchestrator.md      # Preset-specific override (preferred)
-  │   └── explorer_append.md
-  ├── 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
-- When `preset` is set, `{preset}/{agent}.md` and `{preset}/{agent}_append.md` are checked first
-- If neither file exists, the default prompt is used
-
-This allows you to fine-tune agent behavior without modifying the source code.
-
-### JSONC Format (JSON with Comments)
-
-The plugin supports **JSONC** format for configuration files, allowing you to:
-
-- Add single-line comments (`//`)
-- Add multi-line comments (`/* */`)
-- Use trailing commas in arrays and objects
-
-**File Priority:**
-1. `oh-my-opencode-slim.jsonc` (preferred if exists)
-2. `oh-my-opencode-slim.json` (fallback)
-
-**Example JSONC Configuration:**
-
-```jsonc
-{
-  // Use preset for development
-  "preset": "openai",
-
-  /* Presets definition - customize agent models here */
-  "presets": {
-    "openai": {
-      // Fast models for quick iteration
-      "oracle": { "model": "openai/gpt-5.4" },
-      "explorer": { "model": "openai/gpt-5.4-mini" },
-    },
-  },
-
-  "tmux": {
-    "enabled": true,  // Enable for monitoring
-    "layout": "main-vertical",
-  },
-}
-```
-
-### Plugin Config (`oh-my-opencode-slim.json` or `oh-my-opencode-slim.jsonc`)
-
-The installer generates this file with the OpenAI preset by default. You can manually customize it to mix and match models from any provider. See [Provider Configurations](provider-configurations.md) for examples.
-
-#### Option Reference
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `preset` | string | - | Name of the preset to use (e.g., `"openai"`, `"kimi"`) |
-| `presets` | object | - | Named preset configurations containing agent mappings |
-| `presets.<name>.<agent>.model` | string | - | Model ID for the agent (e.g., `"openai/gpt-5.4"`) |
-| `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"`) |
-| `council.master.model` | string | - | **Required if using council.** Model ID for the council master (e.g., `"anthropic/claude-opus-4-6"`) |
-| `council.master.variant` | string | - | Variant for the council master model |
-| `council.master.prompt` | string | - | Optional guidance for the master's synthesis |
-| `council.presets` | object | - | **Required if using council.** Named councillor presets (see [Council Agent](council.md)) |
-| `council.presets.<name>.<councillor>.model` | string | - | Model ID for the councillor |
-| `council.presets.<name>.<councillor>.prompt` | string | - | Optional role guidance for the councillor |
-| `council.presets.<name>.master.model` | string | - | Override the global master model for this preset |
-| `council.presets.<name>.master.variant` | string | - | Override the global master variant for this preset |
-| `council.presets.<name>.master.prompt` | string | - | Override the global master prompt for this preset |
-| `council.default_preset` | string | `"default"` | Which preset to use when none is specified |
-| `council.master_timeout` | number | `300000` | Master synthesis timeout in ms |
-| `council.councillors_timeout` | number | `180000` | Per-councillor timeout in ms |
-| `council.master_fallback` | string[] | — | Optional fallback models for the council master (tried in order on primary failure) |
+| Doc | Contents |
+|-----|----------|
+| [Author's Preset](authors-preset.md) | The exact config the author runs daily — OpenAI + Fireworks AI + GitHub Copilot |

docs/skills.md

@@ -0,0 +1,95 @@
+# Skills
+
+Skills are specialized capabilities you can assign to agents. Unlike MCPs (which are running servers), skills are **prompt-based tool configurations** — instructions injected into an agent's system prompt that describe how to use a particular tool.
+
+Skills are installed via the `oh-my-opencode-slim` installer or manually with `npx skills add`.
+
+---
+
+## Available Skills
+
+### Recommended (via installer)
+
+| Skill | Description | Assigned to by default |
+|-------|-------------|----------------------|
+| [`simplify`](#simplify) | YAGNI code simplification expert | `orchestrator` |
+| [`agent-browser`](#agent-browser) | High-performance browser automation | `designer` |
+
+### Bundled in repo
+
+| Skill | Description | Assigned to by default |
+|-------|-------------|----------------------|
+| [`cartography`](#cartography) | Repository 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, over-engineered patterns, and redundant code — and suggests minimal, direct implementations instead.
+
+---
+
+## agent-browser
+
+**External browser automation for visual verification and testing.**
+
+`agent-browser` provides full high-performance browser automation. It allows agents to browse the web, interact with page elements, take screenshots, and verify visual state — useful for UI/UX work, end-to-end testing, and researching live documentation.
+
+---
+
+## 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 on every task, agents refer to hierarchical `codemap.md` files describing the *why* and *how* of each directory.
+
+**How to use:** Ask the Orchestrator to `run cartography`. It automatically detects whether to initialize a new map or update an existing one.
+
+**Why it's useful:**
+- **Instant onboarding** — understand unfamiliar codebases in seconds
+- **Efficient context** — agents read architectural summaries, saving tokens and improving accuracy
+- **Change detection** — only modified folders are re-analyzed
+- **Timeless documentation** — focuses on high-level design, not implementation details
+
+See **[Cartography Skill](cartography.md)** for full documentation including manual commands and technical details.
+
+---
+
+## Skills Assignment
+
+Control which skills each agent can use in `~/.config/opencode/oh-my-opencode-slim.json` (or `.jsonc`):
+
+| Syntax | Meaning |
+|--------|---------|
+| `["*"]` | All installed skills |
+| `["*", "!agent-browser"]` | All skills except `agent-browser` |
+| `["simplify"]` | Only `simplify` |
+| `[]` | No skills |
+| `["!*"]` | Deny all skills |
+
+**Rules:**
+- `*` expands to all available installed skills
+- `!item` excludes a specific skill
+- Conflicts (e.g. `["a", "!a"]`) → deny wins (principle of least privilege)
+
+**Example:**
+
+```json
+{
+  "presets": {
+    "my-preset": {
+      "orchestrator": {
+        "skills": ["*", "!agent-browser"]
+      },
+      "designer": {
+        "skills": ["agent-browser", "simplify"]
+      },
+      "fixer": {
+        "skills": []
+      }
+    }
+  }
+}
+```

docs/tools.md

@@ -0,0 +1,56 @@
+# Tools & Capabilities
+
+Built-in tools available to agents beyond the standard file and shell operations.
+
+---
+
+## Background Tasks
+
+Launch agents asynchronously and collect results later. This is how the Orchestrator runs Explorer, Librarian, and other sub-agents in parallel without blocking.
+
+| Tool | Description |
+|------|-------------|
+| `background_task` | Launch an agent in a new session. `sync=true` blocks until complete; `sync=false` returns a task ID immediately |
+| `background_output` | Fetch the result of a background task by ID |
+| `background_cancel` | Abort a running background task |
+
+Background tasks integrate with [Tmux Integration](tmux-integration.md) — when tmux is enabled, each background task spawns a pane so you can watch it live.
+
+---
+
+## LSP Tools
+
+Language Server Protocol integration for code intelligence across 30+ languages. OpenCode ships pre-configured LSP servers for TypeScript, Python, Rust, Go, and more.
+
+| Tool | Description |
+|------|-------------|
+| `lsp_goto_definition` | Jump to a symbol's definition |
+| `lsp_find_references` | Find all usages of a symbol across the workspace |
+| `lsp_diagnostics` | Get errors and warnings from the language server |
+| `lsp_rename` | Rename a symbol across all files atomically |
+
+> See the [official OpenCode docs](https://opencode.ai/docs/lsp/#built-in) for the full list of built-in LSP servers and their requirements.
+
+---
+
+## Code Search Tools
+
+Fast, structural code search and refactoring — more powerful than plain text grep.
+
+| Tool | Description |
+|------|-------------|
+| `grep` | Fast content search using ripgrep |
+| `ast_grep_search` | AST-aware code pattern matching across 25 languages |
+| `ast_grep_replace` | AST-aware code refactoring with dry-run support |
+
+`ast_grep` understands code structure, so it can find patterns like "all arrow functions that return a JSX element" rather than relying on exact text matching.
+
+---
+
+## Formatters
+
+OpenCode automatically formats files after they are written or edited, using language-specific formatters. No manual step needed.
+
+Includes Prettier, Biome, `gofmt`, `rustfmt`, `ruff`, and 20+ others.
+
+> See the [official OpenCode docs](https://opencode.ai/docs/formatters/#built-in) for the complete list.