opencode-antigravity-auth 1.2.9-beta.1 → 1.2.9-beta.10

package/README.md

@@ -2,24 +2,28 @@
 
 [![npm version](https://img.shields.io/npm/v/opencode-antigravity-auth.svg)](https://www.npmjs.com/package/opencode-antigravity-auth)
 [![npm beta](https://img.shields.io/npm/v/opencode-antigravity-auth/beta.svg?label=beta)](https://www.npmjs.com/package/opencode-antigravity-auth)
+[![npm downloads](https://img.shields.io/npm/dw/opencode-antigravity-auth.svg)](https://www.npmjs.com/package/opencode-antigravity-auth)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![X (Twitter)](https://img.shields.io/badge/X-@dopesalmon-000000?style=flat&logo=x)](https://x.com/dopesalmon)
 
 Enable Opencode to authenticate against **Antigravity** (Google's IDE) via OAuth so you can use Antigravity rate limits and access models like `gemini-3-pro` and `claude-opus-4-5-thinking` with your Google credentials.
 
-## What you get
+## What You Get
 
-- **Google OAuth sign-in** with automatic token refresh via `opencode auth login`
-- **Dual Quota System** - Access both Antigravity quota (Claude, Gemini 3) and Gemini CLI quota from a single plugin
-- **Multi-Account Rotation** - Add multiple Google accounts; automatically rotates when one is rate-limited
-- **Real-time SSE streaming** including thinking blocks and incremental output
-- **Model Variants** - Configure thinking budget dynamically via OpenCode's variant system
-- **Extended Thinking** - Native support for Claude thinking budgets and Gemini 3 thinking levels
-- **Auto Recovery** - Automatic session recovery from Claude tool_result_missing errors
-- **Plugin Compatible** - Works alongside other OpenCode plugins (opencodesync, etc.)
+- **Claude Opus 4.5, Sonnet 4.5** and **Gemini 3 Pro/Flash** via Google OAuth
+- **Multi-account support** — add multiple Google accounts, auto-rotates when rate-limited
+- **Dual quota system** — access both Antigravity and Gemini CLI quotas from one plugin
+- **Thinking models** — extended thinking for Claude and Gemini 3 with configurable budgets
+- **Google Search grounding** — enable web search for Gemini models (auto or always-on)
+- **Auto-recovery** — handles session errors and tool failures automatically
+- **Plugin compatible** — works alongside other OpenCode plugins (oh-my-opencode, dcp, etc.)
+
+---
 
 ## Installation
 
-### For Humans
+<details open>
+<summary><b>For Humans</b></summary>
 
 **Option A: Let an LLM do it**
 
@@ -31,42 +35,23 @@ Install the opencode-antigravity-auth plugin and add the Antigravity model defin
 
 **Option B: Manual setup**
 
-1. **Add the plugin to your config** (`~/.config/opencode/opencode.json`):
+1. **Add the plugin** to `~/.config/opencode/opencode.json`:
 
    ```json
    {
-     "plugin": ["opencode-antigravity-auth@beta"]
+     "plugin": ["opencode-antigravity-auth@latest"]
    }
    ```
 
-2. **Authenticate:**
+   > Want bleeding-edge features? Use `opencode-antigravity-auth@beta` instead.
+
+2. **Login** with your Google account:
 
    ```bash
    opencode auth login
    ```
 
-3. **Add models** (see [Available Models](#available-models) for full list):
-
-   ```json
-   {
-     "plugin": ["opencode-antigravity-auth@beta"],
-     "provider": {
-       "google": {
-         "models": {
-            "antigravity-claude-sonnet-4-5-thinking": {
-              "name": "Claude Sonnet 4.5 Thinking",
-              "limit": { "context": 200000, "output": 64000 },
-              "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
-              "variants": {
-                "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
-                "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
-              }
-            }
-         }
-       }
-     }
-   }
-   ```
+3. **Add models** — copy the [full configuration](#models) below
 
 4. **Use it:**
 
@@ -74,97 +59,22 @@ Install the opencode-antigravity-auth plugin and add the Antigravity model defin
    opencode run "Hello" --model=google/antigravity-claude-sonnet-4-5-thinking --variant=max
    ```
 
+</details>
+
 <details>
-<summary><b>Installation Guide for LLM Agents</b></summary>
+<summary><b>For LLM Agents</b></summary>
 
 ### Step-by-Step Instructions
 
-1. Edit the OpenCode configuration file:
-   - Linux/Mac: `~/.config/opencode/opencode.json`
-   - Windows: `%APPDATA%\opencode\opencode.json`
+1. Edit the OpenCode configuration file at `~/.config/opencode/opencode.json`
+   
+   > **Note**: This path works on all platforms. On Windows, `~` resolves to your user home directory (e.g., `C:\Users\YourName`).
 
-2. Add the plugin to the `plugins` array
+2. Add the plugin to the `plugin` array
 
-3. Set `provider` to `"google"` and choose a model
+3. Add the model definitions from the [Full models configuration](#models) section
 
-### Complete Configuration Example
-
-Create `~/.config/opencode/opencode.json`:
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-antigravity-auth@beta"],
-  "provider": {
-    "google": {
-      "models": {
-        "antigravity-gemini-3-pro": {
-          "name": "Gemini 3 Pro (Antigravity)",
-          "limit": { "context": 1048576, "output": 65535 },
-          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
-          "variants": {
-            "low": { "thinkingLevel": "low" },
-            "high": { "thinkingLevel": "high" }
-          }
-        },
-        "antigravity-gemini-3-flash": {
-          "name": "Gemini 3 Flash (Antigravity)",
-          "limit": { "context": 1048576, "output": 65536 },
-          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
-          "variants": {
-            "minimal": { "thinkingLevel": "minimal" },
-            "low": { "thinkingLevel": "low" },
-            "medium": { "thinkingLevel": "medium" },
-            "high": { "thinkingLevel": "high" }
-          }
-        },
-        "antigravity-claude-sonnet-4-5": {
-          "name": "Claude Sonnet 4.5 (Antigravity)",
-          "limit": { "context": 200000, "output": 64000 },
-          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
-        },
-        "antigravity-claude-sonnet-4-5-thinking": {
-          "name": "Claude Sonnet 4.5 Thinking (Antigravity)",
-          "limit": { "context": 200000, "output": 64000 },
-          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
-          "variants": {
-            "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
-            "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
-          }
-        },
-        "antigravity-claude-opus-4-5-thinking": {
-          "name": "Claude Opus 4.5 Thinking (Antigravity)",
-          "limit": { "context": 200000, "output": 64000 },
-          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
-          "variants": {
-            "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
-            "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
-          }
-        },
-        "gemini-2.5-flash": {
-          "name": "Gemini 2.5 Flash (Gemini CLI)",
-          "limit": { "context": 1048576, "output": 65536 },
-          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
-        },
-        "gemini-2.5-pro": {
-          "name": "Gemini 2.5 Pro (Gemini CLI)",
-          "limit": { "context": 1048576, "output": 65536 },
-          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
-        },
-        "gemini-3-flash-preview": {
-          "name": "Gemini 3 Flash Preview (Gemini CLI)",
-          "limit": { "context": 1048576, "output": 65536 },
-          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
-        },
-        "gemini-3-pro-preview": {
-          "name": "Gemini 3 Pro Preview (Gemini CLI)",
-          "limit": { "context": 1048576, "output": 65535 },
-          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
-        }
-      }
-    }
-  }
-}
-```
+4. Set `provider` to `"google"` and choose a model
 
 ### Verification
 
@@ -174,47 +84,47 @@ opencode run "Hello" --model=google/antigravity-claude-sonnet-4-5-thinking --var
 
 </details>
 
-## Available Models
+---
+
+## Models
+
+### Model Reference
 
-### Antigravity Quota (with Variants)
+**Antigravity quota** (Claude + Gemini 3):
 
-Models with `antigravity-` prefix use Antigravity quota. **Thinking models support variants** for dynamic thinking budget configuration:
+| Model | Variants | Notes |
+|-------|----------|-------|
+| `antigravity-gemini-3-pro` | low, high | Gemini 3 Pro with thinking |
+| `antigravity-gemini-3-flash` | minimal, low, medium, high | Gemini 3 Flash with thinking |
+| `antigravity-claude-sonnet-4-5` | — | Claude Sonnet 4.5 |
+| `antigravity-claude-sonnet-4-5-thinking` | low, max | Claude Sonnet with extended thinking |
+| `antigravity-claude-opus-4-5-thinking` | low, max | Claude Opus with extended thinking |
 
-| Model | Variants | Description |
-|-------|----------|-------------|
-| `google/antigravity-gemini-3-pro` | low, high | Gemini 3 Pro with configurable thinking |
-| `google/antigravity-gemini-3-flash` | minimal, low, medium, high | Gemini 3 Flash with configurable thinking |
-| `google/antigravity-claude-sonnet-4-5` | - | Claude Sonnet 4.5 (no thinking) |
-| `google/antigravity-claude-sonnet-4-5-thinking` | low, max | Claude Sonnet with configurable thinking |
-| `google/antigravity-claude-opus-4-5-thinking` | low, max | Claude Opus with configurable thinking |
+**Gemini CLI quota** (separate from Antigravity):
 
-**Variant configuration:**
-- **Gemini 3**: Uses `thinkingLevel` string (`"low"`, `"medium"`, `"high"`)
-- **Claude**: Uses `thinkingBudget` number (8192, 32768 tokens)
+| Model | Notes |
+|-------|-------|
+| `gemini-2.5-flash` | Gemini 2.5 Flash |
+| `gemini-2.5-pro` | Gemini 2.5 Pro |
+| `gemini-3-flash-preview` | Gemini 3 Flash (preview) |
+| `gemini-3-pro-preview` | Gemini 3 Pro (preview) |
 
-**Usage:**
+**Using variants:**
 ```bash
 opencode run "Hello" --model=google/antigravity-claude-sonnet-4-5-thinking --variant=max
 ```
 
-### Gemini CLI Quota
-
-Models with `-preview` suffix use Gemini CLI quota:
-
-| Model | Description |
-|-------|-------------|
-| `google/gemini-2.5-flash` | Gemini 2.5 Flash |
-| `google/gemini-2.5-pro` | Gemini 2.5 Pro |
-| `google/gemini-3-flash-preview` | Gemini 3 Flash (preview) |
-| `google/gemini-3-pro-preview` | Gemini 3 Pro (preview) |
+For details on variant configuration and thinking levels, see [docs/MODEL-VARIANTS.md](docs/MODEL-VARIANTS.md).
 
 <details>
 <summary><b>Full models configuration (copy-paste ready)</b></summary>
 
+Add this to your `~/.config/opencode/opencode.json`:
+
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-antigravity-auth@beta"],
+  "plugin": ["opencode-antigravity-auth@latest"],
   "provider": {
     "google": {
       "models": {
@@ -239,7 +149,7 @@ Models with `-preview` suffix use Gemini CLI quota:
           }
         },
         "antigravity-claude-sonnet-4-5": {
-          "name": "Claude Sonnet 4.5 (no thinking) (Antigravity)",
+          "name": "Claude Sonnet 4.5 (Antigravity)",
           "limit": { "context": 200000, "output": 64000 },
           "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
         },
@@ -289,415 +199,413 @@ Models with `-preview` suffix use Gemini CLI quota:
 
 </details>
 
-## Model Variants
+---
+
+## Multi-Account Setup
+
+Add multiple Google accounts for higher combined quotas. The plugin automatically rotates between accounts when one is rate-limited.
+
+```bash
+opencode auth login  # Run again to add more accounts
+```
+
+For details on load balancing, dual quota pools, and account storage, see [docs/MULTI-ACCOUNT.md](docs/MULTI-ACCOUNT.md).
+
+---
+
+## Troubleshoot
+
+> **Quick Reset**: Most issues can be resolved by deleting `~/.config/opencode/antigravity-accounts.json` and running `opencode auth login` again.
+
+### Configuration Path (All Platforms)
+
+OpenCode uses `~/.config/opencode/` on **all platforms** including Windows.
+
+| File | Path |
+|------|------|
+| Main config | `~/.config/opencode/opencode.json` |
+| Accounts | `~/.config/opencode/antigravity-accounts.json` |
+| Plugin config | `~/.config/opencode/antigravity.json` |
+| Debug logs | `~/.config/opencode/antigravity-logs/` |
+
+> **Windows users**: `~` resolves to your user home directory (e.g., `C:\Users\YourName`). Do NOT use `%APPDATA%`.
+
+---
+
+### Multi-Account Auth Issues
+
+If you encounter authentication issues with multiple accounts:
+
+1. Delete the accounts file:
+   ```bash
+   rm ~/.config/opencode/antigravity-accounts.json
+   ```
+2. Re-authenticate:
+   ```bash
+   opencode auth login
+   ```
+
+---
 
-OpenCode's variant system allows you to configure thinking budget dynamically instead of defining separate models for each thinking level.
+### 403 Permission Denied (`rising-fact-p41fc`)
 
-### How Variants Work
+**Error:**
+```
+Permission 'cloudaicompanion.companions.generateChat' denied on resource 
+'//cloudaicompanion.googleapis.com/projects/rising-fact-p41fc/locations/global'
+```
 
-When you define a model with `variants`, OpenCode will show variant options in the model picker. Selecting a variant passes the `providerOptions` to the plugin, which extracts the thinking configuration.
+**Cause:** Plugin falls back to a default project ID when no valid project is found. This works for Antigravity but fails for Gemini CLI models.
 
-### Variant Configuration
+**Solution:**
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create or select a project
+3. Enable the **Gemini for Google Cloud API** (`cloudaicompanion.googleapis.com`)
+4. Add `projectId` to your accounts file:
+   ```json
+   {
+     "accounts": [
+       {
+         "email": "your@email.com",
+         "refreshToken": "...",
+         "projectId": "your-project-id"
+       }
+     ]
+   }
+   ```
+
+> **Note**: Do this for each account in a multi-account setup.
+
+---
+
+### Gemini Model Not Found
+
+Add this to your `google` provider config:
 
 ```json
 {
-  "antigravity-claude-sonnet-4-5-thinking": {
-    "name": "Claude Sonnet 4.5 Thinking",
-    "limit": { "context": 200000, "output": 64000 },
-    "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
-    "variants": {
-      "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
-      "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
+  "provider": {
+    "google": {
+      "npm": "@ai-sdk/google",
+      "models": { ... }
     }
   }
 }
 ```
 
-### Supported Variant Formats
+---
 
-The plugin accepts different variant formats depending on the model family:
+### Gemini 3 Models 400 Error ("Unknown name 'parameters'")
 
-| Model Family | Variant Format |
-|--------------|----------------|
-| **Gemini 3** | `{ "thinkingLevel": "low" \| "medium" \| "high" }` |
-| **Claude** | `{ "thinkingConfig": { "thinkingBudget": N } }` |
-| **Gemini 2.5** | `{ "thinkingConfig": { "thinkingBudget": N } }` |
+**Error:**
+```
+Invalid JSON payload received. Unknown name "parameters" at 'request.tools[0]'
+```
 
-### Gemini 3 Thinking Levels
+**Causes:**
+- Tool schema incompatibility with Gemini's strict protobuf validation
+- MCP servers with malformed schemas
+- Plugin version regression
 
-Gemini 3 models use string-based thinking levels. Available levels differ by model:
+**Solutions:**
+1. **Update to latest beta:**
+   ```json
+   { "plugin": ["opencode-antigravity-auth@beta"] }
+   ```
 
-| Level | Flash | Pro | Description |
-|-------|-------|-----|-------------|
-| `minimal` | Yes | No | Minimal thinking, lowest latency |
-| `low` | Yes | Yes | Light thinking |
-| `medium` | Yes | No | Balanced thinking |
-| `high` | Yes | Yes | Maximum thinking (default for both Pro and Flash) |
+2. **Disable MCP servers** one-by-one to find the problematic one
 
-> **Note:** The API will reject invalid levels (e.g., `"minimal"` on Pro). Configure variants accordingly.
+3. **Add npm override:**
+   ```json
+   { "provider": { "google": { "npm": "@ai-sdk/google" } } }
+   ```
 
-### Legacy Budget Format (Deprecated)
+---
 
-For Gemini 3 models, the old `thinkingBudget` format is still supported but deprecated:
+### MCP Servers Causing Errors
 
-| Budget Range | Maps to Level |
-|--------------|---------------|
-| ≤ 8192 | low |
-| ≤ 16384 | medium |
-| > 16384 | high |
+Some MCP servers have schemas incompatible with Antigravity's strict JSON format.
 
-### Backward Compatibility
+**Diagnosis:**
+1. Disable all MCP servers in your config
+2. Enable one-by-one until error reappears
+3. Report the specific MCP in a [GitHub issue](https://github.com/NoeFabris/opencode-antigravity-auth/issues)
 
-Legacy tier-suffixed models still work:
-- `antigravity-claude-sonnet-4-5-thinking-low`
-- `antigravity-claude-sonnet-4-5-thinking-medium`
-- `antigravity-claude-sonnet-4-5-thinking-high`
-- `antigravity-gemini-3-pro-low`
-- `antigravity-gemini-3-pro-high`
+---
 
-However, **we recommend using variants** for a cleaner model picker and more flexibility.
+### "All Accounts Rate-Limited" (But Quota Available)
 
-## Multi-Account Setup
+**Cause:** Cascade bug in `clearExpiredRateLimits()` in hybrid mode (fixed in recent beta).
 
-Add multiple Google accounts for higher combined quotas. The plugin automatically rotates between accounts when one is rate-limited.
+**Solutions:**
+1. Update to latest beta version
+2. If persists, delete accounts file and re-authenticate
+3. Try switching `account_selection_strategy` to `"sticky"` in `antigravity.json`
 
-```bash
-opencode auth login
-```
+---
 
-<details>
-<summary><b>How multi-account works</b></summary>
+### Session Recovery
 
-### Load Balancing Behavior
+If you encounter errors during a session:
+1. Type `continue` to trigger the recovery mechanism
+2. If blocked, use `/undo` to revert to pre-error state
+3. Retry the operation
 
-- **Sticky account selection** - Sticks to the same account until rate-limited (preserves Anthropic's prompt cache)
-- **Per-model-family limits** - Rate limits tracked separately for Claude and Gemini models
-- **Dual quota pools for Gemini** - Automatic fallback between Antigravity quota and Gemini CLI quota before switching accounts
-- **Smart retry threshold** - Short rate limits (≤5s) are retried on same account
-- **Exponential backoff** - Increasing delays for consecutive rate limits
+---
 
-### Dual Quota Pools (Gemini only)
+### Using with Oh-My-OpenCode
 
-For Gemini models, the plugin accesses **two independent quota pools** per account:
+**Important:** Disable the built-in Google auth to prevent conflicts:
 
-| Quota Pool | When Used |
-|------------|-----------|
-| **Antigravity** | Primary (tried first) |
-| **Gemini CLI** | Fallback when Antigravity is rate-limited |
+```json
+// ~/.config/opencode/oh-my-opencode.json
+{
+  "google_auth": false,
+  "agents": {
+    "frontend-ui-ux-engineer": { "model": "google/antigravity-gemini-3-pro" },
+    "document-writer": { "model": "google/antigravity-gemini-3-flash" }
+  }
+}
+```
 
-This effectively **doubles your Gemini quota** per account.
+---
 
-### Adding Accounts
+### Infinite `.tmp` Files Created
 
-When running `opencode auth login` with existing accounts:
+**Cause:** When account is rate-limited and plugin retries infinitely, it creates many temp files.
 
-```
-2 account(s) saved:
-  1. user1@gmail.com
-  2. user2@gmail.com
+**Workaround:**
+1. Stop OpenCode
+2. Clean up: `rm ~/.config/opencode/*.tmp`
+3. Add more accounts or wait for rate limit to expire
 
-(a)dd new account(s) or (f)resh start? [a/f]:
-```
+---
 
-### Account Storage
+### OAuth Callback Issues
 
-- Stored in `~/.config/opencode/antigravity-accounts.json`
-- Contains OAuth refresh tokens - **treat like a password**
-- If Google revokes a token (`invalid_grant`), that account is automatically removed
+<details>
+<summary><b>Safari OAuth Callback Fails (macOS)</b></summary>
 
-</details>
+**Symptoms:**
+- "fail to authorize" after successful Google login
+- Safari shows "Safari can't open the page"
 
-## Configuration
+**Cause:** Safari's "HTTPS-Only Mode" blocks `http://localhost` callback.
 
-Create `~/.config/opencode/antigravity.json` (or `.opencode/antigravity.json` in project root):
+**Solutions:**
 
-### General Settings
+1. **Use Chrome or Firefox** (easiest):
+   Copy the OAuth URL and paste into a different browser.
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `quiet_mode` | `false` | Suppress toast notifications (except recovery) |
-| `debug` | `false` | Enable debug logging to file |
-| `log_dir` | OS default | Custom directory for debug logs |
-| `auto_update` | `true` | Enable automatic plugin updates |
+2. **Disable HTTPS-Only Mode temporarily:**
+   - Safari > Settings (⌘,) > Privacy
+   - Uncheck "Enable HTTPS-Only Mode"
+   - Run `opencode auth login`
+   - Re-enable after authentication
 
-### Session Recovery
+</details>
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `session_recovery` | `true` | Auto-recover from tool_result_missing errors |
-| `auto_resume` | `true` | Auto-send resume prompt after recovery |
-| `resume_text` | `"continue"` | Text to send when auto-resuming |
+<details>
+<summary><b>Port Conflict (Address Already in Use)</b></summary>
 
-### Error Recovery
+**macOS / Linux:**
+```bash
+# Find process using the port
+lsof -i :51121
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `empty_response_max_attempts` | `4` | Retries for empty API responses |
-| `empty_response_retry_delay_ms` | `2000` | Delay between retries |
-| `tool_id_recovery` | `true` | Fix mismatched tool IDs from context compaction |
-| `claude_tool_hardening` | `true` | Prevent tool parameter hallucination |
+# Kill if stale
+kill -9 <PID>
 
-### Token Management
+# Retry
+opencode auth login
+```
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `proactive_token_refresh` | `true` | Refresh tokens before expiry |
-| `proactive_refresh_buffer_seconds` | `1800` | Refresh 30min before expiry |
-| `max_rate_limit_wait_seconds` | `300` | Max wait time when rate limited (0=unlimited) |
-| `quota_fallback` | `false` | Try alternate quota when rate limited |
-| `switch_on_first_rate_limit` | `true` | Switch account immediately on first 429 (after 1s) |
+**Windows (PowerShell):**
+```powershell
+netstat -ano | findstr :51121
+taskkill /PID <PID> /F
+opencode auth login
+```
 
-### Account Selection
+</details>
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `account_selection_strategy` | `"sticky"` | Strategy for distributing requests across accounts |
-| `pid_offset_enabled` | `false` | Use PID-based offset for multi-session distribution |
+<details>
+<summary><b>Docker / WSL2 / Remote Development</b></summary>
 
-**Available strategies:**
+OAuth callback requires browser to reach `localhost` on the machine running OpenCode.
 
-| Strategy | Behavior | Best For |
-|----------|----------|----------|
-| `sticky` | Same account until rate-limited | Prompt cache preservation |
-| `round-robin` | Rotate to next account on every request | Maximum throughput |
-| `hybrid` | Touch all fresh accounts first, then sticky | Sync reset timers + cache |
+**WSL2:**
+- Use VS Code's port forwarding, or
+- Configure Windows → WSL port forwarding
 
-**Error handling:**
+**SSH / Remote:**
+```bash
+ssh -L 51121:localhost:51121 user@remote
+```
 
-| Error Type | Behavior |
-|------------|----------|
-| `MODEL_CAPACITY_EXHAUSTED` | Wait (escalating 5s→60s) and retry same account |
-| `QUOTA_EXCEEDED` | Switch to next available account immediately |
+**Docker / Containers:**
+- OAuth with localhost redirect doesn't work in containers
+- Wait 30s for manual URL flow, or use SSH port forwarding
 
-This prevents unnecessary account switching when server-side capacity issues affect all accounts equally.
+</details>
 
-### Environment Overrides
+---
 
-```bash
-OPENCODE_ANTIGRAVITY_QUIET=1                              # quiet_mode
-OPENCODE_ANTIGRAVITY_DEBUG=1                              # debug
-OPENCODE_ANTIGRAVITY_LOG_DIR=/path                        # log_dir
-OPENCODE_ANTIGRAVITY_KEEP_THINKING=1                      # keep_thinking
-OPENCODE_ANTIGRAVITY_ACCOUNT_SELECTION_STRATEGY=round-robin  # account_selection_strategy
-OPENCODE_ANTIGRAVITY_PID_OFFSET_ENABLED=1                 # pid_offset_enabled
-```
+### Configuration Key Typo: `plugin` not `plugins`
 
-<details>
-<summary><b>Full configuration example</b></summary>
+The correct key is `plugin` (singular):
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json",
-  "quiet_mode": false,
-  "debug": false,
-  "log_dir": "/custom/log/path",
-  "auto_update": true,
-  "keep_thinking": false,
-  "session_recovery": true,
-  "auto_resume": true,
-  "resume_text": "continue",
-  "empty_response_max_attempts": 4,
-  "empty_response_retry_delay_ms": 2000,
-  "tool_id_recovery": true,
-  "claude_tool_hardening": true,
-  "proactive_token_refresh": true,
-  "proactive_refresh_buffer_seconds": 1800,
-  "proactive_refresh_check_interval_seconds": 300,
-  "max_rate_limit_wait_seconds": 300,
-  "quota_fallback": false,
-  "account_selection_strategy": "sticky",
-  "pid_offset_enabled": false,
-  "signature_cache": {
-    "enabled": true,
-    "memory_ttl_seconds": 3600,
-    "disk_ttl_seconds": 172800,
-    "write_interval_seconds": 60
-  }
+  "plugin": ["opencode-antigravity-auth@beta"]
 }
 ```
 
-</details>
-
-## Troubleshoot
+**Not** `"plugins"` (will cause "Unrecognized key" error).
 
-### Multi account auth issues
-If you encounter auth issue please try remove `antigravity-account.json` and auth again
+---
 
-### Gemini model not found
-Try add this line to in `google` field under `provider`
-`"npm": "@ai-sdk/google"`
+### Migrating Accounts Between Machines
 
-### Error during the session
-If you encounter error during the session, try chat `continue` the recover session mechanism should be trigger and you can continue the session, if the error blocked the session please workaround by use command `/undo` to revert to the state before the error and try again it should work
+When copying `antigravity-accounts.json` to a new machine:
+1. Ensure the plugin is installed: `"plugin": ["opencode-antigravity-auth@beta"]`
+2. Copy `~/.config/opencode/antigravity-accounts.json`
+3. If you get "API key missing" error, the refresh token may be invalid — re-authenticate
 
 ## Known Plugin Interactions
+For details on load balancing, dual quota pools, and account storage, see [docs/MULTI-ACCOUNT.md](docs/MULTI-ACCOUNT.md).
+
+---
+
+## Plugin Compatibility
 
 ### @tarquinen/opencode-dcp
 
-DCP creates synthetic assistant messages that lack thinking blocks. **Our plugin must be listed BEFORE DCP:**
+DCP creates synthetic assistant messages that lack thinking blocks. **List this plugin BEFORE DCP:**
 
 ```json
 {
   "plugin": [
-    "opencode-antigravity-auth@beta",
-    "@tarquinen/opencode-dcp@latest",
+    "opencode-antigravity-auth@latest",
+    "@tarquinen/opencode-dcp@latest"
   ]
 }
 ```
 
 ### oh-my-opencode
-When using opencode-antigravity-auth, disable the built-in auth and override agent models in oh-my-opencode.json:
+
+Disable built-in auth and override agent models in `oh-my-opencode.json`:
+
 ```json
 {
   "google_auth": false,
   "agents": {
-    "frontend-ui-ux-engineer": { "model": "google/gemini-3-pro-high" },
-    "document-writer": { "model": "google/gemini-3-flash" },
-    "multimodal-looker": { "model": "google/gemini-3-flash" }
+    "frontend-ui-ux-engineer": { "model": "google/antigravity-gemini-3-pro" },
+    "document-writer": { "model": "google/antigravity-gemini-3-flash" },
+    "multimodal-looker": { "model": "google/antigravity-gemini-3-flash" }
   }
 }
 ```
 
-When spawning parallel subagents, multiple processes may select the same account causing rate limit errors. **Workaround:** Enable `pid_offset_enabled: true` to distribute sessions across accounts, or add more accounts via `opencode auth login`.
-
-### Plugins You Don't Need
+> **Tip:** When spawning parallel subagents, enable `pid_offset_enabled: true` in `antigravity.json` to distribute sessions across accounts.
 
-- **gemini-auth plugins** - Not needed. This plugin handles all Google OAuth authentication.
+### Plugins you don't need
 
-<details>
-<summary><b>Migration Guide (v1.2.8+ - Variants)</b></summary>
+- **gemini-auth plugins** — Not needed. This plugin handles all Google OAuth.
 
-### What Changed
+---
 
-v1.2.8+ introduces **model variants** for dynamic thinking configuration. Instead of separate models for each thinking level, you now define one model with variants.
+## Configuration
 
-### Before (v1.2.7)
+Create `~/.config/opencode/antigravity.json` for optional settings:
 
 ```json
 {
-  "antigravity-claude-sonnet-4-5-thinking-low": { ... },
-  "antigravity-claude-sonnet-4-5-thinking-medium": { ... },
-  "antigravity-claude-sonnet-4-5-thinking-high": { ... }
+  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json"
 }
 ```
 
-### After (v1.2.8+)
+Most users don't need to configure anything — defaults work well.
 
-```json
-{
-  "antigravity-claude-sonnet-4-5-thinking": {
-    "name": "Claude Sonnet 4.5 Thinking",
-    "limit": { "context": 200000, "output": 64000 },
-    "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
-    "variants": {
-      "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
-      "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
-    }
-  }
-}
-```
+### Model Behavior
 
-### Benefits
+| Option | Default | What it does |
+|--------|---------|--------------
+| `keep_thinking` | `false` | Preserve Claude's thinking across turns. **Warning:** enabling may degrade model stability. |
+| `session_recovery` | `true` | Auto-recover from tool errors |
+| `web_search.default_mode` | `"off"` | Gemini Google Search: `"auto"` or `"off"` |
 
-- **Cleaner model picker** - 4 models instead of 12+
-- **Flexible budgets** - Define any budget, not just low/max
-- **Future-proof** - Works with OpenCode's native variant system
+### Account Rotation
 
-### Backward Compatibility
+| Your Setup | Recommended Config |
+|------------|-------------------|
+| **1 account** | `"account_selection_strategy": "sticky"` |
+| **2-5 accounts** | Default (`"hybrid"`) works great |
+| **5+ accounts** | `"account_selection_strategy": "round-robin"` |
+| **Parallel agents** | Add `"pid_offset_enabled": true` |
 
-Old tier-suffixed models (`antigravity-claude-sonnet-4-5-thinking-low`, etc.) still work. No action required if you prefer the old style.
+### App Behavior
 
-</details>
+| Option | Default | What it does |
+|--------|---------|--------------|
+| `quiet_mode` | `false` | Hide toast notifications |
+| `debug` | `false` | Enable debug logging |
+| `auto_update` | `true` | Auto-update plugin |
 
-<details>
-<summary><b>Migration Guide (v1.2.7 - Prefix)</b></summary>
-
-If upgrading from v1.2.6 or earlier:
-
-### What Changed
-
-v1.2.7+ uses explicit prefixes to distinguish quota sources:
-
-| Model Type | New Name (Recommended) | Old Name (Still Works) |
-|------------|------------------------|------------------------|
-| Gemini 3 (Antigravity) | `antigravity-gemini-3-pro` | `gemini-3-pro-low` |
-| Gemini 3 (CLI) | `gemini-3-pro-preview` | N/A |
-| Claude | `antigravity-claude-sonnet-4-5` | `claude-sonnet-4-5` |
-
-### Action Required
-
-**Update your config to use `antigravity-` prefix:**
-
-```diff
-- "gemini-3-pro-low": { ... }
-+ "antigravity-gemini-3-pro": { ... }
-```
-
-> **Why update?** Old names work now as a fallback, but this depends on Gemini CLI using `-preview` suffix. If Google removes `-preview` in the future, old names may route to the wrong quota. The `antigravity-` prefix is explicit and stable.
-
-### Step 1: Clear Old Tokens (Optional - do this if you have issues calling models)
+For all options, see [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
 
+**Environment variables:**
 ```bash
-rm -rf ~/.config/opencode/antigravity-account.json
-opencode auth login
+OPENCODE_ANTIGRAVITY_DEBUG=1 opencode   # Enable debug logging
+OPENCODE_ANTIGRAVITY_DEBUG=2 opencode   # Verbose logging
 ```
 
-### Step 2: Update opencode.json
-
-Models now use `antigravity-` prefix for Antigravity quota. See [Available Models](#available-models).
-
-### Step 3: Create antigravity.json (Optional)
+---
 
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json",
-  "quiet_mode": false,
-  "debug": false
-}
-```
+## Troubleshooting
 
-</details>
+See the full [Troubleshooting Guide](docs/TROUBLESHOOTING.md) for solutions to common issues including:
 
-<details>
-<summary><b>E2E Testing</b></summary>
+- Auth problems and token refresh
+- "Model not found" errors
+- Session recovery
+- Gemini CLI permission errors
+- Safari OAuth issues
+- Plugin compatibility
+- Migration guides
 
-The plugin includes regression tests for stability verification. Tests consume API quota.
+---
 
-```bash
-# Sanity tests (7 tests, ~5 min)
-npx tsx script/test-regression.ts --sanity
+## Documentation
 
-# Heavy tests (4 tests, ~30 min)
-npx tsx script/test-regression.ts --heavy
+- [Configuration](docs/CONFIGURATION.md) — All configuration options
+- [Multi-Account](docs/MULTI-ACCOUNT.md) — Load balancing, dual quota pools, account storage
+- [Model Variants](docs/MODEL-VARIANTS.md) — Thinking budgets and variant system
+- [Troubleshooting](docs/TROUBLESHOOTING.md) — Common issues and fixes
+- [Architecture](docs/ARCHITECTURE.md) — How the plugin works
+- [API Spec](docs/ANTIGRAVITY_API_SPEC.md) — Antigravity API reference
 
-# Concurrent tests (3 tests)
-npx tsx script/test-regression.ts --category concurrency
+---
 
-# Run specific test
-npx tsx script/test-regression.ts --test thinking-tool-use
+## Support
 
-# List tests without running
-npx tsx script/test-regression.ts --dry-run
-```
+If this plugin helps you, consider supporting its maintenance:
 
-</details>
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/S6S81QBOIR)
 
-## Debugging
+---
 
-```bash
-OPENCODE_ANTIGRAVITY_DEBUG=1 opencode   # Basic logging
-OPENCODE_ANTIGRAVITY_DEBUG=2 opencode   # Verbose (full request/response bodies)
-```
+## Credits
 
-Logs are written to `~/.config/opencode/antigravity-logs/`.
+- [opencode-gemini-auth](https://github.com/jenslys/opencode-gemini-auth) by [@jenslys](https://github.com/jenslys)
+- [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)
 
-## Documentation
+## License
 
-- [Architecture](docs/ARCHITECTURE.md) - Plugin internals and request flow
-- [API Spec](docs/ANTIGRAVITY_API_SPEC.md) - Antigravity API reference
+MIT License. See [LICENSE](LICENSE) for details.
 
 <details>
-<summary><b>Safety, Usage & Legal</b></summary>
+<summary><b>Legal</b></summary>
 
 ### Intended Use
 
@@ -705,36 +613,18 @@ Logs are written to `~/.config/opencode/antigravity-logs/`.
 - Respect internal quotas and data handling policies
 - Not for production services or bypassing intended limits
 
-### Warning (Assumption of Risk)
+### Warning
 
 By using this plugin, you acknowledge:
 
-- **Terms of Service risk** - This approach may violate ToS of AI model providers
-- **Account risk** - Providers may suspend or ban accounts
-- **No guarantees** - APIs may change without notice
-- **Assumption of risk** - You assume all legal, financial, and technical risks
+- **Terms of Service risk** — This approach may violate ToS of AI model providers
+- **Account risk** — Providers may suspend or ban accounts
+- **No guarantees** — APIs may change without notice
+- **Assumption of risk** — You assume all legal, financial, and technical risks
 
-### Legal
+### Disclaimer
 
 - Not affiliated with Google. This is an independent open-source project.
 - "Antigravity", "Gemini", "Google Cloud", and "Google" are trademarks of Google LLC.
-- Software is provided "as is", without warranty.
 
 </details>
-
-## Credits
-
-Built with help from:
-
-- [opencode-gemini-auth](https://github.com/jenslys/opencode-gemini-auth) - Gemini OAuth groundwork by [@jenslys](https://github.com/jenslys)
-- [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) - Antigravity API reference
-
-## Support
-
-If this plugin helps you, consider supporting its continued maintenance:
-
-[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/S6S81QBOIR)
-
-## License
-
-MIT