opencode-resolve 0.1.2 → 0.1.4

package/README.md

@@ -1,17 +1,44 @@
-# opencode-resolve
+# opencode-resolve — Lightweight Resolver Plugin for OpenCode
+
+**[English](./README.md) | [한국어](./README.ko.md)**
 
 [![npm version](https://img.shields.io/npm/v/opencode-resolve.svg)](https://www.npmjs.com/package/opencode-resolve)
+[![CI](https://github.com/jshsakura/opencode-resolve/actions/workflows/publish.yml/badge.svg)](https://github.com/jshsakura/opencode-resolve/actions/workflows/publish.yml)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-Small OpenCode plugin that turns a single instruction into a finished, verified change.
+> **opencode-resolve** is a **lightweight resolver plugin for [OpenCode](https://opencode.ai)**. It lives _inside_ your OpenCode session and turns a single instruction into a finished, verified change — that is what _resolving_ means here.
+>
+> It is **not** a standalone application, not a model provider, not a separate CLI you run daily, and not a replacement for your `opencode.json` configuration. It is an OpenCode plugin and nothing more.
+
+It exposes a **fixed-role verified resolve loop** — **resolver** (context-efficient planner/judge) and **coder** (focused implementer) — running with auto-approved permissions so a task drives to completion without prompting at every step. The resolver inspects only relevant files, plans the smallest patch, dispatches coder with exact instructions, verifies, and iterates through verified checkpoints. Each checkpoint is retried up to 3 times on failure, then the resolver moves forward. Internal specialist subagents (**explorer**, **reviewer**, **deep-reviewer**) are injected by default as OpenCode-native subagents — available when the resolver judges them justified — but they are not part of the core path and are never user-facing primary roles. It defines roles, not model providers: agents inherit your OpenCode default model unless you pin them.
 
-`opencode-resolve` ships three roles by default — **resolver** (orchestrator), **coder** (implementer), and **reviewer** (read-only auditor) — and runs them with auto-approved permissions so a task drives to completion without prompting at every step. It defines roles, not model providers: agents inherit your OpenCode default model unless you pin them.
+```
+# Paste this into any AI coding assistant for fully guided setup
+Install and configure opencode-resolve by following the instructions here:
+https://github.com/jshsakura/opencode-resolve#drop-in-setup-give-to-an-llm
+```
+
+---
+
+## What this is — and isn't
+
+| ✅ What it is | ❌ What it isn't |
+|---|---|
+| A **lightweight resolver plugin for OpenCode** installed via `opencode plugin opencode-resolve` | A standalone app or separate CLI |
+| A fixed-role verified loop (resolver + coder) injected into OpenCode | A model provider or API key manager |
+| A Context7 MCP auto-registration hook | A replacement for your `opencode.json` config |
+| A config file (`resolve.json`) that lives alongside OpenCode config | Something you invoke manually every time you code |
+| Installed once, then runs automatically inside OpenCode | An alternative to OpenCode itself |
+
+If OpenCode is not installed or not running, opencode-resolve does nothing.
 
 ---
 
 ## Table of Contents
 
-- [Roles at a glance](#roles-at-a-glance)
+- [Features](#features)
+- [AI-Powered Setup](#ai-powered-setup)
+- [Prerequisites](#prerequisites)
 - [Quick Start](#quick-start)
 - [Drop-in setup (give to an LLM)](#drop-in-setup-give-to-an-llm)
 - [Default Behavior](#default-behavior)
@@ -23,39 +50,115 @@ Small OpenCode plugin that turns a single instruction into a finished, verified
 - [Model Setup](#model-setup)
 - [Agent Reference](#agent-reference)
 - [Optional Commands](#optional-commands)
+- [Context7 Integration](#context7-integration)
+- [Keeping Up to Date](#keeping-up-to-date)
 - [Local Development](#local-development)
 - [Verification](#verification)
 - [Release](#release)
 - [Design Rules](#design-rules)
+- [License](#license)
+
+---
+
+## Features
+
+- **Fixed-role verified resolve loop** — `resolver` (context-efficient planner/judge) + `coder` (focused implementer)
+- **Context-efficient by default** — minimal file reads, smallest patch, targeted verification, checkpointed execution with max 3 retries per failing checkpoint
+- **OpenCode-native internal specialist subagents** — `reviewer` (verification-gap audit), `explorer` (codebase scout), `deep-reviewer` (risky/security review) — injected as subagents by default but not part of the core path; resolver dispatches them only when justified
+- **Auto-approved permissions** — coder and resolver work without per-action prompts
+- **Context7 MCP** — auto-registers [Context7](https://context7.com) documentation lookup when `context7: true`
+- **Model pinning** — pin different models per role when you have measured a benefit; by default all roles inherit your OpenCode default model
+- **Soft parallel cap** — `maxParallelSubagents` controls how many coders the resolver fans out
+- **Strict validation** — unknown keys, typos, invalid modes, and wrong types all fail fast at load time
+- **Additive migration** — upgrades never overwrite your existing config
+- **Zero dependencies beyond `@opencode-ai/plugin`** — nothing extra to install
+
+---
+
+## AI-Powered Setup
+
+> **One line. Any AI coding assistant. Everything configured automatically.**
+
+Paste this into Claude Code, Cursor, Codex, OpenCode, Windsurf, VS Code Copilot, or Gemini CLI:
+
+```
+Install and configure opencode-resolve by following the instructions here:
+https://github.com/jshsakura/opencode-resolve#drop-in-setup-give-to-an-llm
+```
+
+Your AI will:
+
+1. Install the plugin via `opencode plugin opencode-resolve --global --force`
+2. Merge `opencode-resolve` into your `opencode.json` plugin array
+3. Create `resolve.json` with a working configuration
+4. Tell you to restart OpenCode
+
+No manual config editing required. Works on macOS, Linux, and Windows.
+
+> For manual setup, see [Prerequisites](#prerequisites) and [Quick Start](#quick-start) below.
 
 ---
 
-## Roles at a glance
+## Prerequisites
+
+### 1. OpenCode
+
+opencode-resolve is an OpenCode plugin. You need [OpenCode](https://opencode.ai) installed and running.
+
+Verify:
+
+```sh
+opencode --version
+```
 
-| Role | Default | Can edit? | Can run shell? | Purpose |
-|---|:---:|:---:|:---:|---|
-| `resolver` | Yes | Yes (auto) | Yes (auto) | Primary orchestrator. Plans, dispatches `coder` (one at a time), verifies, iterates. |
-| `coder` | Yes | Yes (auto) | Yes (auto) | Focused implementer. Makes the smallest correct change and verifies. |
-| `reviewer` | Yes | **Never** | **Never** | Read-only auditor. Inspects only — recommends fixes for `coder` or `resolver` to apply. |
+### 2. Node.js ≥ 20
+
+The plugin and OpenCode itself require Node.js 20 or later.
+
+Verify:
+
+```sh
+node --version   # should be v20.x or later
+```
+
+### 3. A configured model provider
+
+OpenCode needs at least one model provider configured in `~/.config/opencode/opencode.json` with a valid API key. opencode-resolve agents inherit your default model unless you pin them.
+
+Example minimal provider setup:
+
+```json
+{
+  "model": "openai/gpt-4o",
+  "provider": {
+    "openai": {
+      "name": "OpenAI"
+    }
+  }
+}
+```
 
-Hard rule: **the reviewer cannot modify the project by any means.** Both `edit` and `bash` are denied for the reviewer regardless of `autoApprove`. Any required fix is routed back through `coder` or `resolver`.
+> No additional API keys or MCP servers are required. Context7 is auto-registered by the plugin.
 
 ---
 
 ## Quick Start
 
-Install from npm:
+### Install from npm
 
 ```sh
 npm install -g opencode-resolve
 ```
 
-The package `postinstall` step:
+The `postinstall` script automatically:
 
-1. Adds `opencode-resolve` to `~/.config/opencode/opencode.json` `plugin` array.
-2. Creates `~/.config/opencode/resolve.json` from [`opencode-resolve.example.json`](./opencode-resolve.example.json) when missing.
+1. Adds `opencode-resolve` to `~/.config/opencode/opencode.json` `plugin` array (if not already present).
+2. Creates `~/.config/opencode/resolve.json` adapted to your current model provider when the file does not exist:
+   - **GLM/ZAI model detected** → mixed GLM + GPT alias preset (`coder` → GLM, `resolver` → GPT).
+   - **OpenAI/GPT model detected** → single-provider GPT preset using your current model for all roles.
+   - **Other or no model** → model-neutral `models: {}` (all roles inherit OpenCode default).
 
-Restart OpenCode after installation.
+   Existing `resolve.json` files are **never overwritten** — the adaptive preset only applies to first-time creation. To regenerate, delete `resolve.json` and reinstall.
 
 To skip automatic registration:
 
@@ -63,7 +166,17 @@ To skip automatic registration:
 OPENCODE_RESOLVE_SKIP_POSTINSTALL=1 npm install -g opencode-resolve
 ```
 
-Manual fallback: add the plugin to `~/.config/opencode/opencode.json` yourself:
+### Refresh the plugin cache
+
+> **Important — OpenCode caches plugins itself.** OpenCode does NOT use globally-installed npm packages directly. It maintains its own cache at `~/.cache/opencode/packages/`. After the very first install (or any future upgrade), refresh the cache:
+
+```sh
+opencode plugin opencode-resolve --global --force
+```
+
+### Manual fallback
+
+If `postinstall` didn't register the plugin, add it to `~/.config/opencode/opencode.json` yourself:
 
 ```json
 {
@@ -71,46 +184,209 @@ Manual fallback: add the plugin to `~/.config/opencode/opencode.json` yourself:
 }
 ```
 
+### Restart OpenCode
+
+```sh
+opencode
+```
+
+You should now see `resolver` and `coder` agents available.
+
 ---
 
 ## Drop-in setup (give to an LLM)
 
-Hand the block below to any reasonably capable LLM along with the instruction _"set up opencode-resolve on this machine"_ and it can finish the install end-to-end. Everything below is the entire required configuration — no other MCP servers, environment variables, or files are needed.
+Hand the block below to any reasonably capable LLM along with the instruction _"set up opencode-resolve on this machine"_ and it will finish the install end-to-end. The LLM **must run this interactively** — it discovers what providers and models are already configured, then asks the user which to pin per role. No guessing, no invented model IDs.
 
-**Step 1 — install the plugin:**
+> **For LLMs reading this:** treat every "Ask the user" prompt below as a real question — wait for the user's answer before continuing. Never proceed with a default if the user hasn't responded. Never invent model IDs that aren't in the user's `opencode.json` (or in their declared `provider.*` registry).
+
+### Step 1 — Install and prime the cache
 
 ```sh
-npm install -g opencode-resolve
+opencode plugin opencode-resolve --global --force
 ```
 
-**Step 2 — `~/.config/opencode/opencode.json`** (the only required keys; merge into an existing file rather than replacing if one exists):
+This downloads the plugin, installs it into OpenCode's package cache (`~/.cache/opencode/packages/`), and makes it available.
+
+### Step 2 — Register the plugin in `~/.config/opencode/opencode.json`
+
+Add the string `"opencode-resolve"` to the `plugin` array. **Do not use the inline tuple form here** — keep the entry as a bare string so all role/model config lives in `resolve.json` (Step 3). This avoids split-brain configuration.
 
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "model": "<your-default-model-id>",
+  "model": "<user-default-model-id>",
   "plugin": ["opencode-resolve"]
 }
 ```
 
-**Step 3 — `~/.config/opencode/resolve.json`** (created automatically by `postinstall`; the file below is the canonical default):
+> If the user already has other plugins, append `"opencode-resolve"` to the existing array. **Never overwrite** their existing config.
+
+### Step 3 — Pick models interactively, then write `~/.config/opencode/resolve.json`
+
+The LLM **drives a short Q&A** here. Goal: end with `resolve.json` containing model IDs the user explicitly chose from their own configuration.
+
+#### 3a. Discover the user's installed providers and models
+
+Read `~/.config/opencode/opencode.json` and build a candidate map:
+
+| Source | What to collect |
+|---|---|
+| `provider.*` keys | Each configured provider (e.g. `zai`, `openai`, `anthropic`). |
+| `provider.<key>.models.*` keys | The model keys the user has declared under that provider. |
+| Top-level `model` | If the prefix before `/` is not already in `provider.*`, add it as an implicit candidate (e.g. `zai-coding-plan` from `zai-coding-plan/glm-5.1`). |
+| `agent.*.model` | Any per-agent overrides — add their provider/model pairs as candidates. |
+
+If the user has **no providers configured at all**, stop and tell them to add at least one provider with a valid API key to `opencode.json` first — opencode-resolve cannot pick a model that does not exist.
+
+#### 3b. Ask the user: which provider?
+
+Print the candidate list and ask. Example wording the LLM should use:
+
+> _I found these providers in your OpenCode config. Which one should opencode-resolve roles use?_
+>
+> 1. `zai-coding-plan` — models: `glm-5.1`, `glm-4.7-flash`
+> 2. `openai` — models: `gpt-4o`, `gpt-4o-mini`, `o1`, `o1-mini`, `o3-mini`, `gpt-5.5`
+> 3. _Other (provide an explicit `provider/model` ID)_
+
+If exactly one provider candidate exists, skip the question and use it.
+
+#### 3c. Ask the user: single-tier or split?
+
+> _Do you want a single model for every role, or split — a fast model for `coder`/`explorer` and a stronger model for `resolver`/`reviewer`/`deep-reviewer`?_
+>
+> A. Single model for all roles (simplest, recommended for one-provider setups)
+> B. Split — fast + strong (recommended when you have both a cheap and a strong model)
+
+#### 3d. Ask the user: which model(s)?
+
+Show only the models under the provider picked in 3b.
+
+- For **single-tier (A)** — ask one question:
+  > _Which model should every role use?_ → list models from the chosen provider.
+- For **split (B)** — ask two questions, in order:
+  > _Pick the **fast** model for `coder` and `explorer`:_ → list models.
+  >
+  > _Pick the **strong** model for `resolver`, `reviewer`, `deep-reviewer`:_ → list models.
+
+Confirm each pick back to the user before writing the file. Example:
+
+> _I'll pin `coder` and `explorer` to `zai-coding-plan/glm-5.1`, and `resolver`/`reviewer`/`deep-reviewer` to `openai/gpt-5.5`. Proceed?_
+
+#### 3e. Write `~/.config/opencode/resolve.json`
+
+If the user picked **A (single-tier)**, write:
 
 ```json
 {
-  "enabled": ["coder", "reviewer", "resolver"],
+  "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"],
   "preserveNative": true,
   "context7": true,
   "commands": false,
+  "models": {
+    "primary":       "<chosen-provider>/<chosen-model>",
+    "coder":         "primary",
+    "explorer":      "primary",
+    "resolver":      "primary",
+    "reviewer":      "primary",
+    "deep-reviewer": "primary"
+  },
+  "agents": {
+    "coder":         { "enabled": true,  "mode": "all" },
+    "resolver":      { "enabled": true },
+    "explorer":      { "enabled": true,  "mode": "subagent" },
+    "reviewer":      { "enabled": true,  "mode": "subagent" },
+    "deep-reviewer": { "enabled": true,  "mode": "subagent" },
+    "architect":     { "enabled": false },
+    "gpt-coder":     { "enabled": false },
+    "debugger":      { "enabled": false },
+    "researcher":    { "enabled": false }
+  },
   "autoApprove": true,
-  "maxParallelSubagents": 1
+  "maxParallelSubagents": 2
 }
 ```
 
-**Step 4 — restart OpenCode.**
+If the user picked **B (split)**, write:
+
+```json
+{
+  "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"],
+  "preserveNative": true,
+  "context7": true,
+  "commands": false,
+  "models": {
+    "fast":          "<provider>/<fast-model>",
+    "strong":        "<provider>/<strong-model>",
+    "coder":         "fast",
+    "explorer":      "fast",
+    "resolver":      "strong",
+    "reviewer":      "strong",
+    "deep-reviewer": "strong"
+  },
+  "agents": {
+    "coder":         { "enabled": true,  "mode": "all" },
+    "resolver":      { "enabled": true },
+    "explorer":      { "enabled": true,  "mode": "subagent" },
+    "reviewer":      { "enabled": true,  "mode": "subagent" },
+    "deep-reviewer": { "enabled": true,  "mode": "subagent" },
+    "architect":     { "enabled": false },
+    "gpt-coder":     { "enabled": false },
+    "debugger":      { "enabled": false },
+    "researcher":    { "enabled": false }
+  },
+  "autoApprove": true,
+  "maxParallelSubagents": 2
+}
+```
+
+Replace every `<provider>/<model>` placeholder with the **exact** ID strings the user picked in 3b/3d — no inventing, no autocompletion, no version drift. If you cannot map the picked model to a `provider/model` string, ask the user to clarify rather than guessing.
+
+> Each enabled agent carries an explicit `enabled: true` so the file is self-documenting. The `enabled` array remains authoritative; the per-agent flag just removes ambiguity for humans reading the file.
+
+> If `resolve.json` already exists, **do not overwrite it silently**. Show the user the existing content first, summarize what would change, and ask whether to overwrite, merge, or abort.
+
+### Step 4 — Restart OpenCode and verify
+
+Close and reopen OpenCode, then confirm the install worked:
+
+```sh
+opencode run "list available agents"
+```
+
+The output **must** include `resolver` and `coder` (and `reviewer` if enabled). Two failure modes to check explicitly:
 
-That is the entire setup. `context7` is the only MCP server the plugin needs (auto-registered when the key above is `true`) — no other MCP entries are required for `opencode-resolve` itself. Models are inherited from your top-level OpenCode `model` unless you pin per-role models under `models` (see [Model Setup](#model-setup)).
+| Symptom | Cause | Fix |
+|---|---|---|
+| Only OpenCode's built-in `explore` / `general` appear | Plugin didn't load | Re-run `opencode plugin opencode-resolve --global --force`; verify `"opencode-resolve"` is in `opencode.json` `plugin` array as a string. |
+| Agents appear but fail when invoked with "model not found" | A pinned model ID in `models` doesn't exist | Re-open `resolve.json`, replace the offending ID with one the user actually has, restart. |
+| The user said split but only one tier shows up | `models` block missing `fast` or `strong` | Re-run Step 3 from 3d. |
+
+Internal specialist subagents (`explorer`, `reviewer`, `deep-reviewer`) are subagent-only and won't appear in the primary picker — only `resolver` (and `coder` since it has `mode: "all"`) show up there.
 
-If you want stricter behavior, flip `autoApprove` to `false` (every action prompts for approval) and/or raise `maxParallelSubagents` to let the resolver fan out independent subtasks.
+### Why this template
+
+| Setting | Why |
+|---|---|
+| `enabled: ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"]` | Fixed core path (resolver→coder) plus OpenCode-native internal specialist subagents injected by default |
+| `autoApprove: true` | Coder and resolver work without per-action prompts |
+| `maxParallelSubagents: 2` | Up to two coders may run in parallel for independent work |
+| `agents.coder.mode = "all"` | Coder appears in the agent picker, not just as a subagent |
+| `agents.{explorer,reviewer,deep-reviewer}.mode = "subagent"` | Internal specialists are subagent-only — never user-facing primary roles |
+| `context7: true` | Plugin auto-registers Context7 MCP — no manual MCP config needed |
+| `models` aliases | Empty by default — all roles inherit the OpenCode default model. Pin role-specific models only when you have measured a benefit |
+| Other agents disabled | `architect`, `gpt-coder`, `debugger`, `researcher` off by default. Enable when needed |
+
+### What happens when you call the resolver
+
+1. **Classify** — Resolver classifies the work as quick, normal, deep, or risky.
+2. **Inspect** — Reads only relevant files using local tools. No broad exploration.
+3. **For trivial work** — Resolver applies the small edit directly. No subagent needed.
+4. **Implement** — Dispatches `coder` with exact file paths and focused instructions.
+5. **Verify** — Runs the cheapest meaningful check first (targeted test, type check, or lint).
+6. **Retry** — If issues remain, dispatches `coder` again with a focused fix. Max 3 attempts per failing checkpoint. When verified, proceed to the next checkpoint.
+7. **Report** — Returns a concise evidence summary: what changed, verification results, and any remaining blockers.
+8. **Internal specialists** — When justified: dispatch `explorer` (scope genuinely unknown), `reviewer` (verification gap on non-trivial changes), or `deep-reviewer` (risky/security/high-impact only). These are available by default as subagents but are not the core path.
 
 ---
 
@@ -118,14 +394,16 @@ If you want stricter behavior, flip `autoApprove` to `false` (every action promp
 
 | Item | Default |
 |---|---|
-| Enabled agents | `coder`, `reviewer`, `resolver` |
+| Enabled agents | `coder`, `resolver`, `explorer`, `reviewer`, `deep-reviewer` |
+| Core path | `resolver` → `coder` (fixed-role verified loop) |
+| Internal subagents | `explorer`, `reviewer`, `deep-reviewer` (subagent-only, dispatched when justified) |
 | Primary agent for new tasks | `resolver` (`mode: "all"`) |
 | Agent model | Inherits top-level OpenCode `model` |
 | Native `plan` / `build` | Preserved untouched |
-| Context7 MCP preset | Added if absent |
+| Context7 MCP preset | Added automatically when `context7: true` |
 | Optional commands | Disabled |
 | `autoApprove` | `true` (no per-action prompts on coder/resolver) |
-| Reviewer modification | Denied (cannot be auto-approved) |
+| Max retries per checkpoint | 3 (via resolver prompt) |
 
 ---
 
@@ -145,14 +423,14 @@ Inline plugin options in `opencode.json` override file config.
 Config precedence:
 
 ```text
-built-in defaults -> first config file found -> inline plugin options
+built-in defaults → first config file found → inline plugin options
 ```
 
 Minimal config (matches defaults):
 
 ```json
 {
-  "enabled": ["coder", "reviewer", "resolver"],
+  "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"],
   "autoApprove": true,
   "context7": true,
   "commands": false
@@ -167,7 +445,7 @@ Inline form inside `opencode.json`:
     [
       "opencode-resolve",
       {
-        "enabled": ["coder", "reviewer", "resolver"],
+        "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"],
         "autoApprove": true,
         "context7": true,
         "commands": false
@@ -187,13 +465,13 @@ Every accepted top-level option:
 
 | Key | Type | Default | Purpose |
 |---|---|---|---|
-| `enabled` | `string[]` | `["coder", "reviewer", "resolver"]` | Which resolve agents to inject. Per-agent `agents.<name>.enabled` overrides this. |
+| `enabled` | `string[]` | `["coder", "resolver", "explorer", "reviewer", "deep-reviewer"]` | Which resolve agents to inject. Core path: resolver→coder. Internal specialists (explorer, reviewer, deep-reviewer) are subagent-only. Per-agent `agents.<name>.enabled` overrides this. |
 | `preserveNative` | `boolean` | `true` | Native `plan`/`build` are always preserved. Accepted for readability. |
 | `context7` | `boolean` | `true` | When true, registers the Context7 MCP server unless already configured. |
 | `commands` | `boolean` | `false` | When true, adds `resolve`, `resolve-code`, `resolve-review` commands. |
 | `autoApprove` | `boolean` | `true` | Flips default `"ask"` permissions to `"allow"` on enabled agents. Never touches `"deny"` or user-set keys. |
-| `maxParallelSubagents` | `positive integer` | `1` | Cap on simultaneous subagents the resolver dispatches across coder, reviewer, etc. |
-| `models` | `object` | `{}` | Alias map. Keys are agent names or `glm`/`gpt`. Values are model ids or other aliases. |
+| `maxParallelSubagents` | `positive integer` | `2` | Cap on simultaneous subagents the resolver dispatches per role. |
+| `models` | `object` | `{}` | Alias map. Keys are agent names or `fast`/`strong`/`mini`/`codex`/`quick`/`deep`/`glm`/`gpt`. Values are model ids or other aliases. Empty by default — all roles inherit the OpenCode default model. |
 | `agents` | `object` | `{}` | Per-agent overrides (see below). |
 | `config` | `string` | _none_ | Custom path to a config file (relative to the project or absolute). |
 
@@ -225,9 +503,7 @@ Permission keys (each takes `"ask"`, `"allow"`, or `"deny"`):
 }
 ```
 
-A fully-annotated reference config ships with the package as
-[`opencode-resolve.reference.jsonc`](./opencode-resolve.reference.jsonc) — copy
-the keys you need into your `resolve.json` (without the comments).
+A fully-annotated reference config ships with the package as [`opencode-resolve.reference.jsonc`](./opencode-resolve.reference.jsonc) — copy the keys you need into your `resolve.json` (without the comments).
 
 ---
 
@@ -243,7 +519,7 @@ the keys you need into your `resolve.json` (without the comments).
 | User explicit `"allow"` | stays `"allow"` | stays `"allow"` |
 | User explicit `"deny"` | stays `"deny"` | stays `"deny"` |
 
-Reviewer permissions for `edit` and `bash` are `"deny"` in the defaults, so `autoApprove` cannot grant the reviewer modification rights.
+Agents with `"deny"` defaults (e.g. reviewer's `edit` and `bash`) keep those denials even with `autoApprove: true`. Reviewer is enabled by default as an internal subagent — its deny permissions ensure it stays read-only.
 
 Turn it off when you want the conservative ask-every-time behavior:
 
@@ -253,23 +529,31 @@ Turn it off when you want the conservative ask-every-time behavior:
 }
 ```
 
-Trust note: `autoApprove: true` assumes you trust the workspace and the model you have configured. Use a sandbox or VM for untrusted code, and keep `autoApprove: false` if you want to inspect every action.
+> **Trust note:** `autoApprove: true` assumes you trust the workspace and the model you have configured. Use a sandbox or VM for untrusted code, and keep `autoApprove: false` if you want to inspect every action.
 
 ---
 
 ## Parallel Subagent Limit
 
-`maxParallelSubagents` (default `1`) caps how many subagents the **resolver** may dispatch in parallel — across `coder`, `reviewer`, or any other subagent. The default of `1` enforces strictly serial dispatch: resolver waits for each subagent to finish before launching the next.
+`maxParallelSubagents` (default `2`) caps how many subagents the **resolver** may dispatch concurrently **per role** for context efficiency. The default of `2` lets up to two coders run in parallel for genuinely independent work.
+
+| Value | Behavior |
+|---|---|
+| `1` | Strictly one coder at a time. |
+| `2` (default) | Up to two coders concurrently. Useful when fanning out genuinely independent work. |
+| `N > 2` | Up to N coders concurrently. Use sparingly to avoid context waste. |
 
-Raise it when you want resolver to fan out independent subtasks:
+Override per project or per user:
 
 ```json
-{
-  "maxParallelSubagents": 3
-}
+{ "maxParallelSubagents": 1 }
+{ "maxParallelSubagents": 2 }
+{ "maxParallelSubagents": 4 }
 ```
 
-The limit is woven into the resolver's prompt at config-load time, so changing it does not require any code changes — restart OpenCode to pick up the new limit. If you provide a custom `agents.resolver.prompt`, the templated rule is skipped and your prompt wins.
+> **Important — soft limit, not a hard cap.** The limit is woven into the resolver's system prompt only. There is no runtime interceptor that blocks excess dispatches. Capable instruction-following coding models generally respect the directive, but if a model misbehaves, dispatches above the limit will go through. Pair this with `maxSteps` to bound total iterations if you want a stricter ceiling.
+
+The limit is templated into the prompt at config-load time, so restart OpenCode to pick up the new value. If you provide a custom `agents.resolver.prompt`, the templated rule is skipped and your prompt wins entirely.
 
 ---
 
@@ -282,6 +566,18 @@ When you upgrade to a newer version of `opencode-resolve`, the `postinstall` scr
 - **Never** rewrites your `enabled` list, `models` map, or `agents` overrides.
 - If `enabled` is set and does not include `"resolver"`, prints a one-line tip suggesting you add it. Your file is left untouched.
 
+### Adaptive first-install preset
+
+When `resolve.json` does **not** exist, postinstall inspects your OpenCode model configuration and writes a provider-adapted `models` block:
+
+| Detected provider | Preset |
+|---|---|
+| GLM / ZAI | Mixed GLM + GPT: coder/explorer → GLM, resolver/reviewer/deep-reviewer → GPT |
+| OpenAI / GPT | Single-provider: all roles use your current OpenAI model |
+| Other or none | Model-neutral: `models: {}` (all roles inherit OpenCode default) |
+
+To change presets at any time, edit `models` in `resolve.json` directly or delete the file and reinstall.
+
 Skip the migration entirely with:
 
 ```sh
@@ -292,7 +588,7 @@ OPENCODE_RESOLVE_SKIP_POSTINSTALL=1 npm install -g opencode-resolve
 
 ## Model Setup
 
-`opencode-resolve` does not ship a provider-specific role default.
+`opencode-resolve` does not pin any provider-specific model by default. All resolve agents inherit your top-level OpenCode `model` — use a single efficient model if it gives the best token-per-result efficiency. Only pin role-specific models when you have measured a benefit.
 
 Model resolution order for each resolve agent:
 
@@ -301,68 +597,80 @@ Model resolution order for each resolve agent:
 3. top-level OpenCode `model`
 4. OpenCode's own fallback when no model is configured
 
-Use the default config when all resolve roles should follow your current OpenCode model.
+### Use default model for everything (recommended)
 
-Pin models only when you intentionally want fixed role behavior, such as fast coding on one model and deeper review on another.
+```json
+{
+  "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"],
+  "models": {}
+}
+```
 
-Role-specific aliases:
+### Role-specific aliases (when measured benefit exists)
 
 ```json
 {
-  "enabled": ["coder", "reviewer", "resolver"],
+  "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"],
   "models": {
-    "glm": "zai-coding-plan/glm-5.1",
-    "gpt": "openai/gpt-5.5",
-    "coder": "glm",
-    "resolver": "gpt",
-    "reviewer": "gpt"
+    "fast": "openai/gpt-5-mini",
+    "strong": "openai/gpt-5.3-codex",
+    "coder": "fast",
+    "resolver": "strong"
   }
 }
 ```
 
-Pin one role directly:
+### Pin one role directly
 
 ```json
 {
   "agents": {
-    "reviewer": {
-      "model": "openai/gpt-5.5"
+    "resolver": {
+      "model": "openai/gpt-5.3-codex"
     }
   }
 }
 ```
 
-Native OpenCode agents such as `plan` and `build` are configured through the top-level OpenCode `agent`, not through `opencode-resolve`.
+### Mixed setup (OpenCode config + resolve models)
 
-Mixed setup example:
+Native OpenCode agents such as `plan` and `build` are configured through the top-level OpenCode `agent`, not through `opencode-resolve`.
 
 ```json
 {
-  "model": "zai-coding-plan/glm-5.1",
+  "model": "openai/gpt-5-mini",
   "agent": {
     "plan": {
-      "model": "openai/gpt-5.5"
+      "model": "openai/gpt-5.3-codex"
     }
   },
   "plugin": [
     [
       "opencode-resolve",
       {
-        "enabled": ["coder", "reviewer", "resolver"],
-        "models": {
-          "glm": "zai-coding-plan/glm-5.1",
-          "gpt": "openai/gpt-5.5",
-          "coder": "glm",
-          "resolver": "gpt",
-          "reviewer": "gpt"
-        }
+        "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"]
       }
     ]
   ]
 }
 ```
 
-In this setup, `plan`, `resolver`, and `reviewer` use `openai/gpt-5.5`; native `build` and resolve `coder` use `zai-coding-plan/glm-5.1`.
+In this setup, `plan` uses `openai/gpt-5.3-codex`; native `build`, resolve `coder`, and resolve `resolver` all use `openai/gpt-5-mini`.
+
+### Supported model alias keys
+
+| Alias | Purpose |
+|---|---|
+| `fast` | Provider-neutral alias for a fast/cheap model |
+| `strong` | Provider-neutral alias for a strong/expensive model |
+| `mini` | Provider-neutral alias for a mini/efficient model |
+| `codex` | Provider-neutral alias for a codex-style coding model |
+| `quick` | Legacy alias (equivalent to `fast`) |
+| `deep` | Legacy alias (equivalent to `strong`) |
+| `glm` | Legacy alias (backward compatibility) |
+| `gpt` | Legacy alias (backward compatibility) |
+
+Aliases only resolve when defined in `models`. Agent names (`coder`, `resolver`, etc.) are also valid alias keys.
 
 ---
 
@@ -370,9 +678,11 @@ In this setup, `plan`, `resolver`, and `reviewer` use `openai/gpt-5.5`; native `
 
 | Agent | Default | Mode | Edit | Bash | WebFetch | Purpose |
 |---|:---:|---|---|---|---|---|
-| `resolver` | Yes | `all` | ask → allow | ask → allow | ask → allow | Primary orchestrator. Plans, dispatches `coder` (one at a time), verifies, iterates to completion. |
-| `coder` | Yes | `subagent` | ask → allow | ask → allow | ask → allow | Focused implementer. Smallest correct change. |
-| `reviewer` | Yes | `subagent` | **deny** | **deny** | ask → allow | Read-only auditor. Cannot modify by any means. |
+| `resolver` | Yes (core) | `all` | ask → allow | ask → allow | ask → allow | Context-efficient orchestrator. Decomposes work into verified checkpoints, dispatches coder, verifies each, carries forward. Max 3 retries per failing checkpoint. |
+| `coder` | Yes (core) | `subagent` | ask → allow | ask → allow | ask → allow | Focused implementer. Smallest correct patch. Reads only needed files. |
+| `explorer` | Yes (subagent) | `subagent` | **deny** | ask → allow | ask → allow | Internal fast codebase scout. Resolver dispatches when scope is genuinely unknown; prefers local read/grep/glob for narrow scope. |
+| `reviewer` | Yes (subagent) | `subagent` | **deny** | **deny** | ask → allow | Internal verification-gap auditor. Resolver dispatches for post-change verification gaps on non-trivial changes. |
+| `deep-reviewer` | Yes (subagent) | `subagent` | **deny** | **deny** | ask → allow | Internal thorough review for risky/security/architecture changes. Resolver dispatches ONLY for high-impact work. |
 | `architect` | No | `subagent` | deny | ask → allow | ask → allow | Design and task decomposition. |
 | `gpt-coder` | No | `subagent` | ask → allow | ask → allow | ask → allow | Stronger-reasoning implementation fallback. |
 | `debugger` | No | `subagent` | ask → allow | ask → allow | ask → allow | Reproduction and root-cause analysis. |
@@ -390,19 +700,25 @@ Supported modes:
 
 Supported permission values: `ask`, `allow`, `deny`.
 
-Supported model alias keys: `glm`, `gpt`, and every supported agent name. Aliases only resolve when defined in `models`.
+Supported model alias keys: `fast`, `strong`, `mini`, `codex`, `quick`, `deep`, `glm`, `gpt`, and every supported agent name. Aliases only resolve when defined in `models`.
 
 `preserveNative` is accepted for readability, but native `plan` and `build` are always preserved. The plugin never rewrites built-in OpenCode agents.
 
 ### Resolver orchestration rules
 
-The resolver's prompt enforces the following behavior:
+The resolver uses a context-efficient approach with checkpointed execution (max 3 retries per failing checkpoint):
 
-- Plan the smallest correct change before dispatching.
-- Dispatch **only one `coder` subagent at a time**. Never call coders in parallel.
-- After each coder run, verify (tests, type checks, targeted checks) when practical.
-- Optionally consult `reviewer` for an independent read-only audit on risky changes; route any required fixes back through `coder`.
-- Iterate until the task is resolved or clearly blocked, then return a concise summary.
+- **Classify** the work as quick, normal, deep, or risky before planning.
+- **Inspect only relevant files** using local tools — avoid broad exploration.
+- For trivial work, apply edits directly — no subagent needed.
+- Dispatch **coder** with focused file/behavior instructions.
+- Run the **cheapest meaningful verification** first.
+- Retry from verification logs if issues remain. Max 3 attempts per failing checkpoint; then move forward or report the blocker.
+- Use **explorer** only when scope is genuinely unknown and local read/grep/glob are insufficient (internal subagent, not core path).
+- Use **reviewer** only when a verification gap exists on non-trivial changes (internal subagent, not core path).
+- Use **deep-reviewer** only for risky, security-sensitive, architectural, or high-impact changes (internal subagent, not core path).
+- Return a concise evidence summary when resolved or blocked.
+- Honor the `maxParallelSubagents` per-role limit for context efficiency.
 
 ---
 
@@ -418,6 +734,56 @@ Set `commands: true` to add helper subtask commands:
 
 ---
 
+## Context7 Integration
+
+When `context7: true` (the default), the plugin automatically registers the [Context7](https://context7.com) MCP server at startup:
+
+```json
+{
+  "type": "remote",
+  "url": "https://mcp.context7.com/mcp"
+}
+```
+
+This gives all resolve agents access to up-to-date library and framework documentation through the `resolve-library-id` and `query-docs` tools — no manual MCP configuration needed.
+
+To disable Context7 registration (e.g. you already have it configured, or you don't want it):
+
+```json
+{
+  "context7": false
+}
+```
+
+If `mcp.context7` is already present in your OpenCode config, the plugin does not overwrite it.
+
+---
+
+## Keeping Up to Date
+
+> **OpenCode caches the last version it downloaded.** To get a new release you must explicitly refresh.
+
+```sh
+# Upgrade via npm
+npm install -g opencode-resolve@latest
+
+# Refresh the OpenCode cache
+opencode plugin opencode-resolve --global --force
+
+# Restart OpenCode
+```
+
+After upgrading, `postinstall` runs additive migration on your `resolve.json` — new keys are added, existing keys are never modified.
+
+### Pinning a specific version
+
+```sh
+npm install -g opencode-resolve@0.1.3
+opencode plugin opencode-resolve --global --force
+```
+
+---
+
 ## Local Development
 
 From this repository:
@@ -493,7 +859,19 @@ The release workflow runs `npm ci`, `npm run typecheck`, `npm test`, and `npm pu
 ## Design Rules
 
 - Do not overwrite native `plan` or `build` agents.
-- Keep the default agent set small and role-clear: `resolver` orchestrates, `coder` modifies, `reviewer` only reads.
-- The reviewer never modifies anything — fixes always go through `coder` or `resolver`.
-- The resolver dispatches at most one coder at a time.
+- Core path is fixed: `resolver` (context-efficient planner/judge) → `coder` (implementer).
+- Internal specialist subagents (`explorer`, `reviewer`, `deep-reviewer`) are injected by default as OpenCode-native subagents — they inherit OpenCode's composition philosophy — but are not the default execution path and are never user-facing primary roles.
+- Resolver prefers local read/grep/glob for narrow scope; dispatches `explorer` only when scope is genuinely unknown.
+- Resolver dispatches `reviewer` only for verification gaps on non-trivial changes.
+- Resolver dispatches `deep-reviewer` only for risky, security-sensitive, architectural, or high-impact changes.
+- Reviewer and deep-reviewer are read-only — fixes always go through `coder` or `resolver`.
+- Max 3 retries per failing checkpoint to avoid wasted context. Large tasks are decomposed into verified checkpoints.
+- The resolver honors `maxParallelSubagents` for context efficiency.
 - Search and inspect before editing. Make the smallest correct change. Verify when practical.
+- Read only needed files. Avoid broad exploration. Targeted verification, not full suites.
+
+---
+
+## License
+
+[MIT](./LICENSE)