@cortexkit/opencode-antigravity-auth 1.1.0 → 2.0.1

package/README.md

@@ -1,559 +1,252 @@
-# Antigravity + Gemini CLI OAuth Plugin for Opencode
+# `@cortexkit/opencode-antigravity-auth`
 
 [![npm version](https://img.shields.io/npm/v/@cortexkit/opencode-antigravity-auth.svg)](https://www.npmjs.com/package/@cortexkit/opencode-antigravity-auth)
 [![npm downloads](https://img.shields.io/npm/dw/@cortexkit/opencode-antigravity-auth.svg)](https://www.npmjs.com/package/@cortexkit/opencode-antigravity-auth)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Enable Opencode to authenticate against **Antigravity** (Google's IDE) via OAuth so you can use Antigravity rate limits and access models like `gemini-3.6-flash` and `claude-opus-4-6-thinking` with your Google credentials.
+OpenCode 1.x plugin + OpenTUI sidebar for Google Antigravity. Authenticate with your Google account, get **Antigravity quota** access to Claude 4.6, Gemini 3.x/2.5, and GPT-OSS 120B, plus standalone OAuth login and quota commands through the bundled `antigravity-auth` CLI.
 
-## What You Get
-
-- **Claude Opus 4.6, Sonnet 4.6, Gemini 3.6/3.5 Flash, Gemini 3.1 Pro/Image, and GPT-OSS 120B** 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.)
-
----
-
-<details open>
-<summary><b>⚠️ Terms of Service Warning — Read Before Installing</b></summary>
-
-> [!CAUTION]
-> Using this plugin (and any proxy for Antigravity) violates Google's Terms of Service. A number of users have reported their Google accounts being **banned** or **shadow-banned** (restricted access without explicit notification).
+> **CAUTION — read before installing.**
 >
-> **By using this plugin, you acknowledge:**
-> - This is an unofficial tool not endorsed by Google
-> - Your account may be suspended or permanently banned
-> - You assume all risks associated with using this plugin
->
-
-</details>
-
----
-
-## Installation
-
-<details open>
-<summary><b>For Humans</b></summary>
-
-**Option A: Let an LLM do it**
-
-Paste this into any LLM agent (Claude Code, OpenCode, Cursor, etc.):
-
-```
-Install the opencode-antigravity-auth plugin and add the Antigravity model definitions to ~/.config/opencode/opencode.json by following: https://raw.githubusercontent.com/cortexkit/antigravity-auth/main/README.md
-```
-
-**Option B: Manual setup**
+> Using this plugin (and any proxy for Antigravity) violates Google's Terms of Service. Google account holders have reported suspensions, bans, and shadow-bans (restricted access without notice). The plugin is **not endorsed by Google**; you assume all risks.
 
-1. **Add the plugin** to `~/.config/opencode/opencode.json`:
+This package is part of the `@cortexkit/antigravity-auth@2.0.0` monorepo. See the [root README](../../README.md) for the full operator and contributor guide, the installation matrix, the configuration reference, and the release process.
 
-   ```json
-   {
-     "plugin": ["@cortexkit/opencode-antigravity-auth@latest"]
-   }
-   ```
+## What you get
 
-2. **Login** with your Google account:
+- **Claude Opus 4.6 / Sonnet 4.6 (thinking)** and **Gemini 3 Pro / Flash / 3.6 Flash / 3.1 Pro / 3.1 Flash Image** via Google OAuth against the Antigravity quota pool.
+- **GPT-OSS 120B Medium** through the Antigravity-style headers.
+- **Multi-account rotation** with deterministic selection (`sticky`, `round-robin`, `hybrid`), per-account rate-limit cooldowns, and a failsafe **killswitch** that hard-blocks accounts below a quota threshold.
+- **Dual quota pools:** Antigravity headers + Gemini CLI headers with style-fallback so a single exhausted pool does not stall a request.
+- **OpenTUI sidebar** — read-only, polls the on-disk sidebar-state file every 2s. Carries per-account health, cooldown, and per-quota-group remaining percent; never carries credentials.
+- **Six slash commands** wired through the OpenTUI dialog system — `/antigravity-quota`, `/antigravity-account`, `/antigravity-routing`, `/antigravity-killswitch`, `/antigravity-dump`, `/antigravity-logging`. See `packages/opencode/src/plugin/commands.ts` and `packages/opencode/src/tui/command-dialogs.tsx`. `/gemini-dump` remains a backward-compat alias.
+- **Thinking models** with optional signature caching and precompiled OpenTUI JSX.
+- **Standalone CLI** shipped as the `antigravity-auth` bin (`login`, `list`, `quota`) — same storage as the plugin.
+- **Auto-recovery** from `tool_result_missing` errors and proactive background token refresh.
 
-   ```bash
-   opencode auth login
-   ```
+## Host requirement
 
-3. **Add models** — choose one:
-   - Run `opencode auth login` → Google → OAuth with Google (Antigravity) → select **"Configure models in opencode.json"** (auto-configures all models)
-   - Or manually copy the [full configuration](#models) below
+| Host field | Required range |
+| --- | --- |
+| `@opencode-ai/plugin` peer dependency | `>=1.17.13 <2` |
+| `@opentui/core`, `@opentui/keymap`, `@opentui/solid` (peer) | `^0.4.5` each |
+| Node | `>=20` |
 
-4. **Use it:**
+The package pins the supported host range through `engines.opencode` (`>=1.17.13 <2`); `opencode plugin` refuses to install a plugin that asks for an unsupported range.
 
-   ```bash
-   opencode run "Hello" --model=google/antigravity-claude-opus-4-6-thinking --variant=max
-   ```
+The package exposes two `exports` subpaths the host installer reads:
 
-</details>
+- `exports["."]` — the bundled `dist/index.js` server root. `opencode plugin` writes this entry into `opencode.json`'s `plugin` array.
+- `exports["./tui"]` — `src/tui/entry.mjs`, the OpenTUI sidebar loader. `opencode plugin` writes this entry into `tui.json` so the TUI process picks it up on the next host start.
 
-<details>
-<summary><b>For LLM Agents</b></summary>
-
-### Step-by-Step Instructions
-
-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 `plugin` array
-
-3. Add the model definitions from the [Full models configuration](#models) section
+## Installation
 
-4. Set `provider` to `"google"` and choose a model
+### End-user (npm) — the supported path
 
-### Verification
+The supported installer writes both registrations in one step:
 
 ```bash
-opencode run "Hello" --model=google/antigravity-claude-opus-4-6-thinking --variant=max
+opencode plugin @cortexkit/opencode-antigravity-auth@latest
 ```
 
-</details>
+What this does:
 
----
+- Reads the package's `exports["."]` and writes it into `~/.config/opencode/opencode.json` under the `plugin` array — the `auth.loader` and `fetch` interceptor the host calls on every model dispatch.
+- Reads the package's `exports["./tui"]` and writes it into `~/.config/opencode/tui.json` so the TUI process picks the sidebar up on the next host start.
+- Refuses to install when the host's OpenCode version falls outside the package's `engines.opencode` range.
 
-## Models
+#### Manual config (hand-edited configs)
 
-### Model Reference
-
-**Antigravity quota:**
-
-| Model | Variants | Notes |
-|-------|----------|-------|
-| `antigravity-gemini-3.6-flash` | low, high | Gemini 3.6 Flash with medium as the default |
-| `antigravity-gemini-3.5-flash` | low, high | Gemini 3.5 Flash with medium as the default |
-| `antigravity-gemini-3.1-pro` | low, high | Gemini 3.1 Pro with thinking |
-| `antigravity-gemini-3.1-flash-image` | — | Gemini 3.1 image generation |
-| `antigravity-claude-sonnet-4-6-thinking` | — | Claude Sonnet 4.6 with thinking |
-| `antigravity-claude-opus-4-6-thinking` | — | Claude Opus 4.6 with thinking |
-| `antigravity-gpt-oss-120b-medium` | — | GPT-OSS 120B medium reasoning |
-
-> Gemini 3.5 Flash-Lite is available through the Gemini API but is not present in
-> the AGY 1.1.5 Antigravity or Gemini CLI quota catalogs. Gemini 3.5 Flash Cyber
-> is restricted to a limited-access CodeMender pilot. Neither model is advertised
-> by this plugin.
-
-**Gemini CLI quota** (separate from Antigravity; used when `cli_first` is true or as fallback):
-
-| 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) |
-| `gemini-3.1-pro-preview` | Gemini 3.1 Pro (preview, rollout-dependent) |
-| `gemini-3.1-pro-preview-customtools` | Gemini 3.1 Pro Preview Custom Tools (preview, rollout-dependent) |
-
-> **Routing Behavior:**
-> - **Antigravity-first (default):** Gemini models use Antigravity quota across accounts.
-> - **CLI-first (`cli_first: true`):** Gemini models use Gemini CLI quota first.
-> - When a Gemini quota pool is exhausted, the plugin automatically falls back to the other pool.
-> - Claude and image models always use Antigravity.
-> Model names are automatically transformed for the target API (e.g., `antigravity-gemini-3-flash` → `gemini-3-flash-preview` for CLI).
-
-**Using variants:**
-```bash
-opencode run "Hello" --model=google/antigravity-claude-opus-4-6-thinking --variant=max
-```
+If you cannot use `opencode plugin`, write both files by hand:
 
-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
+```jsonc
+// ~/.config/opencode/opencode.json
 {
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@cortexkit/opencode-antigravity-auth@latest"],
-  "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.6-flash": {
-          "name": "Gemini 3.6 Flash (Antigravity)",
-          "limit": { "context": 1048576, "output": 65536 },
-          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
-          "variants": {
-            "low": { "thinkingLevel": "low" },
-            "high": { "thinkingLevel": "high" }
-          }
-        },
-        "antigravity-gemini-3.1-pro": {
-          "name": "Gemini 3.1 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-6": {
-          "name": "Claude Sonnet 4.6 (Antigravity)",
-          "limit": { "context": 200000, "output": 64000 },
-          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
-        },
-        "antigravity-claude-opus-4-6-thinking": {
-          "name": "Claude Opus 4.6 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"] }
-        },
-        "gemini-3.1-pro-preview": {
-          "name": "Gemini 3.1 Pro Preview (Gemini CLI)",
-          "limit": { "context": 1048576, "output": 65535 },
-          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
-        },
-        "gemini-3.1-pro-preview-customtools": {
-          "name": "Gemini 3.1 Pro Preview Custom Tools (Gemini CLI)",
-          "limit": { "context": 1048576, "output": 65535 },
-          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
-        }
-      }
-    }
-  }
+  "plugin": ["@cortexkit/opencode-antigravity-auth@latest"]
 }
 ```
 
-> **Backward Compatibility:** Legacy model names with `antigravity-` prefix (e.g., `antigravity-gemini-3-flash`) still work. The plugin automatically handles model name transformation for both Antigravity and Gemini CLI APIs.
-
-</details>
-
----
-
-## Multi-Account Setup
-
-Add multiple Google accounts for a higher combined quota. The plugin automatically rotates between accounts when one is rate-limited.
-
-```bash
-opencode auth login  # Run again to add more accounts
-```
-
-**Account management options (via `opencode auth login`):**
-- **Configure models** — Auto-configure all plugin models in opencode.json
-- **Check quotas** — View remaining API quota for each account
-- **Manage accounts** — Enable/disable specific accounts for rotation
-
-For details on load balancing, dual quota pools, and account storage, see [docs/MULTI-ACCOUNT.md](docs/MULTI-ACCOUNT.md).
-
----
-
-## Troubleshooting
-
-> **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%`.
-
-> **Custom path**: Set `OPENCODE_CONFIG_DIR` environment variable to use a custom location.
-
-> **Windows migration**: If upgrading from plugin v1.3.x or earlier, the plugin will automatically find your existing config in `%APPDATA%\opencode\` and use it. New installations use `~/.config/opencode/`.
-
----
-
-### 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
-   ```
-
----
-
-### 403 Permission Denied (`rising-fact-p41fc`)
-
-**Error:**
-```
-Permission 'cloudaicompanion.companions.generateChat' denied on resource 
-'//cloudaicompanion.googleapis.com/projects/rising-fact-p41fc/locations/global'
-```
-
-**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.
-
-**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
+```jsonc
+// ~/.config/opencode/tui.json
 {
-  "provider": {
-    "google": {
-      "npm": "@ai-sdk/google",
-      "models": { ... }
-    }
-  }
+  "plugin": ["@cortexkit/opencode-antigravity-auth"]
 }
 ```
 
----
-
-### Gemini 3 Models 400 Error ("Unknown name 'parameters'")
-
-**Error:**
-```
-Invalid JSON payload received. Unknown name "parameters" at 'request.tools[0]'
-```
-
-**Causes:**
-- Tool schema incompatibility with Gemini's strict protobuf validation
-- MCP servers with malformed schemas
-- Plugin version regression
-
-**Solutions:**
-1. **Update to latest beta:**
-   ```json
-   { "plugin": ["@cortexkit/opencode-antigravity-auth@latest"] }
-   ```
+The two files are independent — the server registration is read from `opencode.json` and the TUI registration from `tui.json`.
 
-2. **Disable MCP servers** one-by-one to find the problematic one
+Then start OpenCode and run `opencode auth login`, pick **Antigravity (Google OAuth)** in the menu (or `/antigravity-account add`). Verify with `npx -y @cortexkit/opencode-antigravity-auth quota`.
 
-3. **Add npm override:**
-   ```json
-   { "provider": { "google": { "npm": "@ai-sdk/google" } } }
-   ```
+### Contributor (Bun)
 
----
-
-### MCP Servers Causing Errors
-
-Some MCP servers have schemas incompatible with Antigravity's strict JSON format.
-
-**Common symptom:**
 ```bash
-Invalid function name must start with a letter or underscore
+bun install                                          # at repo root
+bun run build                                        # core -> opencode -> pi
+bun run --cwd packages/opencode smoke:tui            # bundle + spawn the precompiled TUI
 ```
 
-Sometimes it shows up as:
-```bash
-GenerateContentRequest.tools[0].function_declarations[12].name: Invalid function name must start with a letter or underscore
-```
+A precompiled JSX tree ships under `dist/src/tui-compiled/` and is regenerated by `bun run build:tui` (alias of `bunx tsx packages/opencode/scripts/build-tui.ts`). The host runtime module loads either the **precompiled** tree (production) or the **raw** `src/tui.tsx` source (development installs). `bun run --cwd packages/opencode smoke:tui` confirms both subpaths resolve correctly against the packaged tarball.
 
-This usually means an MCP tool name starts with a number (for example, a 1mcp key like `1mcp_*`). Rename the MCP key to start with a letter (e.g., `gw`) or disable that MCP entry for Antigravity models.
+> Note: the pre-`2.0` inline quota helper is no longer shipped. Use `antigravity-auth quota [--refresh] [--json]` from this package or from the standalone CLI.
 
-**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/cortexkit/antigravity-auth/issues)
+## v2.0 migration
 
----
+- **Root exports changed.** The package no longer re-exports `authorizeAntigravity` / `exchangeAntigravity` at the root — import them from `@cortexkit/antigravity-auth-core` instead:
 
-### "All Accounts Rate-Limited" (But Quota Available)
+  ```ts
+  // v1.x — no longer supported at the root
+  // import { authorizeAntigravity } from "@cortexkit/opencode-antigravity-auth"
 
-**Cause:** Cascade bug in `clearExpiredRateLimits()` in hybrid mode (fixed in recent beta).
+  // v2.0 — explicit core import
+  import { authorizeAntigravity, exchangeAntigravity } from "@cortexkit/antigravity-auth-core"
+  ```
 
-**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`
+- **`@opencode-ai/plugin` peer dependency** moved from `^0.15.30` to `^1.17.13`. Hosts on 1.17.13+ get the TUI registration through `opencode plugin` (the host reads `exports["./tui"]` and writes it into `tui.json`).
+- **New peer dependencies** (`@opentui/core`, `@opentui/keymap`, `@opentui/solid` at `^0.4.5`) — required by the sidebar.
+- No account-storage changes: the on-disk format is unchanged from the v1.4+ storage schema (`AccountStorageV4`).
+- Missing accounts now return **HTTP 401 `UNAUTHENTICATED`** from the fetch interceptor instead of a synthetic 200 with assistant text.
 
----
+See [packages/opencode/CHANGELOG.md](./CHANGELOG.md) for the full list of v2.0.0 changes.
 
-### Session Recovery
+## Models
 
-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
+### Quick reference
 
----
+The model registry lives at `packages/core/src/model-registry.ts`; the OpenCode package re-exports it through `getAntigravityOpencodeModelIds()`. Models below are an authoritative mirror at the time of release.
 
-### Using with Oh-My-OpenCode
+| Model | Variants | Quota group |
+| --- | --- | --- |
+| `antigravity-gemini-3.6-flash` | `low`, `high` | `gemini-flash` |
+| `antigravity-gemini-3.5-flash` | `low`, `high` | `gemini-flash` |
+| `antigravity-gemini-3.1-pro` | `low`, `high` | `gemini-pro` |
+| `antigravity-gemini-3.1-flash-image` | — | `gemini-flash` |
+| `antigravity-claude-sonnet-4-6` | — | `claude` |
+| `antigravity-claude-opus-4-6-thinking` | `low`, `max` | `claude` |
+| `antigravity-gpt-oss-120b-medium` | — | `gpt-oss` |
+| `gemini-2.5-flash` | — | `gemini-flash` (CLI pool) |
+| `gemini-2.5-pro` | — | `gemini-pro` (CLI pool) |
+| `gemini-3-flash-preview` | — | `gemini-flash` (CLI pool) |
+| `gemini-3-pro-preview` | — | `gemini-pro` (CLI pool) |
+| `gemini-3.1-pro-preview` | — | `gemini-pro` (CLI pool) |
+| `gemini-3.1-pro-preview-customtools` | — | `gemini-pro` (CLI pool) |
 
-**Important:** Disable the built-in Google auth to prevent conflicts:
+> Gemini 3.5 Flash-Lite is not in the AGY 1.1.5 Antigravity or Gemini CLI quota catalogs, and Gemini 3.5 Flash Cyber is restricted to a limited-access CodeMender pilot — neither is exposed by this plugin.
 
-```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" }
-  }
-}
-```
+### Routing
 
----
+- **Antigravity-first (default).** Gemini requests go to the Antigravity header style first; on `429 RESOURCE_EXHAUSTED` they fall back to the Gemini CLI header set.
+- **CLI-first** (`cli_first: true`). Flip the order — Gemini CLI first, Antigravity fallback. Toggle at runtime through `/antigravity-routing cli_first=true`.
+- **Style-fallback** (`quota_style_fallback: true`). Re-send the SAME request through the other header set on a rate limit. Default OFF to prevent double-spend across pools. Toggle at runtime through `/antigravity-routing quota_style_fallback=true`.
+- **Claude and image models** always use Antigravity regardless of toggles.
+- Model names transform automatically between Antigravity and Gemini CLI namespaces (`antigravity-gemini-3-flash` ↔ `gemini-3-flash-preview`).
 
-### Infinite `.tmp` Files Created
+### Quota, killswitch, and the soft-threshold fail-open
 
-**Cause:** When account is rate-limited and plugin retries infinitely, it creates many temp files.
+Each cached quota entry carries `{ remainingFraction, resetTime }` per group:
 
-**Workaround:**
-1. Stop OpenCode
-2. Clean up: `rm ~/.config/opencode/*.tmp`
-3. Add more accounts or wait for rate limit to expire
+- **Soft-quota threshold** — `soft_quota_threshold_percent` (default 80). Accounts above the threshold are skipped as if rate-limited. Set to `100` to disable.
+- **Stale-TTL fail-open** — `soft_quota_cache_ttl_minutes = "auto"` resolves to `max(2 × refresh, 10)` minutes. Cache older than the TTL is treated as unknown and allowed through.
+- **Proactive rotation** — `proactive_rotation_threshold_percent` (default 20). When the active account's remaining quota drops below, dispatch the next request from a warm-cache account.
+- **All-throttled wait** — `max_rate_limit_wait_seconds` (default 300). Cap on how long the interceptor waits when every account is rate-limited before failing fast.
 
----
+The **operator killswitch** is a hard rejection layer run BEFORE the soft-quota filter:
 
-### OAuth Callback Issues
+- `enabled` master switch.
+- `minimum_remaining_percent` (default 5) — global hard-block threshold.
+- `accounts[key]` — per-account override keyed by `sha256(refreshToken).slice(0,12)`. The hash is deterministic but irreversible; the raw token never appears in the config, the sidebar, RPC payloads, or apply responses.
+- **Cache-TTL fail-open** — when an account has no fresh cached quota (default 5 min TTL), it is allowed through so a cold start cannot deadlock.
+- **All-killed error** — if the entire pool is excluded, the interceptor throws `AntigravityKillswitchError` with a per-account summary.
 
-<details>
-<summary><b>Safari OAuth Callback Fails (macOS)</b></summary>
+Both filters run before the token bucket / health score pick, so the operator's threshold is authoritative even on a healthy pool.
 
-**Symptoms:**
-- "fail to authorize" after successful Google login
-- Safari shows "Safari can't open the page"
+## Six slash commands
 
-**Cause:** Safari's "HTTPS-Only Mode" blocks `http://localhost` callback.
+All commands are registered through `packages/opencode/src/plugin/catalog.ts` and the modal flow renders in `packages/opencode/src/tui/command-dialogs.tsx`. The apply RPC defaults to `2_000` ms; account `add` / `refresh` opts into `120_000` ms because OAuth can take up to two minutes on a fresh login.
 
-**Solutions:**
+| Command | Args | Default timeout |
+| --- | --- | --- |
+| `/antigravity-quota` | `[refresh]` — status (default) or refresh all accounts | `2_000` |
+| `/antigravity-account` | `add` · `refresh` · `remove` · `list` | `2_000` for list/remove, `120_000` for add/refresh |
+| `/antigravity-routing` | `cli_first=true\|false` · `quota_style_fallback=true\|false` (omit a key to flip) | `2_000` |
+| `/antigravity-killswitch` | `enabled=true\|false` · `minimum_remaining_percent=0..100` | `2_000` |
+| `/antigravity-dump` | `enable` · `disable` · `status` (alias: `/gemini-dump`) | `2_000` |
+| `/antigravity-logging` | `error` · `warn` · `info` · `debug` · `trace` | `2_000` |
 
-1. **Use Chrome or Firefox** (easiest):
-   Copy the OAuth URL and paste into a different browser.
+Every apply mutates persistent state and bumps the sidebar's `checkedAt` via `createSidebarRefresher` so the TUI's next poll sees a fresh snapshot. Sidebar writers go through `sidebarWriteChain` (cross-process fenced lock, 2s lock timeout, atomic write `0600`).
 
-2. **Disable HTTPS-Only Mode temporarily:**
-   - Safari > Settings (⌘,) > Privacy
-   - Uncheck "Enable HTTPS-Only Mode"
-   - Run `opencode auth login`
-   - Re-enable after authentication
+## Standalone CLI
 
-</details>
+The `antigravity-auth` bin is bundled into this package:
 
-<details>
-<summary><b>Port Conflict (Address Already in Use)</b></summary>
-
-**macOS / Linux:**
 ```bash
-# Find process using the port
-lsof -i :51121
+npx -y @cortexkit/opencode-antigravity-auth login [--project <id>] [--no-browser]
+npx -y @cortexkit/opencode-antigravity-auth list [--json]
+npx -y @cortexkit/opencode-antigravity-auth quota [--json] [--refresh]
+```
 
-# Kill if stale
-kill -9 <PID>
+- `login` runs the full PKCE + local callback flow. `--no-browser` prints the URL instead of opening it (handy in headless / SSH sessions where the browser cannot reach the callback port; see Troubleshooting).
+- `list` prints `INDEX`, `EMAIL`, `STATUS` for every account in storage (`active`, `disabled`, `ineligible`, `verification-required`).
+- `quota` prints `ACCOUNT`, `STATUS`, `GROUP`, `REMAINING`, `RESET` rows. `--refresh` forces a live refresh; `--json` emits the same data as JSON.
 
-# Retry
-opencode auth login
-```
+Exit codes: `0` success, `1` thrown error, `2` parse failure. The CLI writes to the same `antigravity-accounts.json` the plugin reads — a CLI login shows up at the next plugin reload.
 
-**Windows (PowerShell):**
-```powershell
-netstat -ano | findstr :51121
-taskkill /PID <PID> /F
-opencode auth login
-```
+## Multi-account setup
 
-</details>
+```bash
+opencode auth login                  # run again to add more accounts; pick Antigravity (Google OAuth)
+opencode auth login                  # → "Check quotas" or "Manage accounts" for the existing pool
+```
 
-<details>
-<summary><b>Docker / WSL2 / Remote Development</b></summary>
+Options exposed through the auth menu: configure models in `opencode.json` automatically, view remaining quota per account, enable/disable specific accounts. See [docs/MULTI-ACCOUNT.md](./docs/MULTI-ACCOUNT.md) for the storage schema, fenced-lock writers, and the rotation strategies (`sticky`, `hybrid`, `round-robin`) in depth.
 
-OAuth callback requires browser to reach `localhost` on the machine running OpenCode.
+## Sidebar / RPC state and recovery
 
-**WSL2:**
-- Use VS Code's port forwarding, or
-- Configure Windows → WSL port forwarding
+The sidebar reads from `$XDG_STATE_HOME/cortexkit/antigravity-auth/sidebar-state.json` (or whatever `ANTIGRAVITY_AUTH_SIDEBAR_STATE_FILE` points at) and polls every `2s`. The contract version is `1`; malformed JSON or unknown versions silently fall back to `DEFAULT_SIDEBAR_STATE` (which is rendered as "Awaiting Antigravity state"). Carries `version`, `checkedAt`, `accounts[]`, `activeRouting` (per-session map, pruned to 24h / 100 entries), `routingAuthoritative`, optional `quotaBackoffUntil` and `lastError`. **Never carries refresh tokens, access tokens, project IDs, or fingerprints.**
 
-**SSH / Remote:**
-```bash
-ssh -L 51121:localhost:51121 user@remote
-```
+The RPC lives under `$XDG_STATE_HOME/cortexkit/antigravity-auth/rpc/<project-hash>/port-<pid>.json` (override via `ANTIGRAVITY_AUTH_RPC_DIR`). The TUI process reads the highest-mtime live entry, drops entries whose owning PID is dead (`process.kill(pid, 0)`), and posts to `/rpc/apply` / `/rpc/pending-notifications` with a `Bearer <token>` header on `http://127.0.0.1`. The default request timeout is `2_000` ms; account `add` / `refresh` opts into `120_000` ms.
 
-**Docker / Containers:**
-- OAuth with localhost redirect doesn't work in containers
-- Wait 30s for manual URL flow, or use SSH port forwarding
+**Recovery from a stale sidebar** — stop the host, verify `$XDG_STATE_HOME/cortexkit/antigravity-auth/sidebar-state.json` exists and is `0600`, then restart. **Recovery from a missing RPC port file** — confirm the running plugin process exists; `getRpcDir(directory)` derives the directory from a sha256 of the project directory, so two projects on the same host get independent RPC dirs.
 
-</details>
+## Disposal
 
----
+The plugin's `dispose()` (host shutdown) runs in order:
 
-### Configuration Key Typo: `plugin` not `plugins`
+1. Dispose the active `AccountManager` + proactive token-refresh queue.
+2. Shut down the disk signature cache (if `keep_thinking` is on).
+3. Clear the session registry.
+4. Drop the fetch-interceptor state.
+5. `drainSidebarWrites()` — wait for any in-flight sidebar-state merge to land so the TUI sees a fully landed snapshot if the user immediately reopens.
+6. Tear down registered disposables (RPC server, file logger, quota manager).
 
-The correct key is `plugin` (singular):
+This ordering matters because a routing upsert enqueued at shutdown must land before the host closes the terminal. See `packages/opencode/src/plugin/lifecycle.ts:createPluginLifecycle`.
 
-```json
-{
-  "plugin": ["@cortexkit/opencode-antigravity-auth@latest"]
-}
-```
+## File / state inventory (this package)
 
-**Not** `"plugins"` (will cause "Unrecognized key" error).
+| Purpose | Path | Mode | Notes |
+| --- | --- | --- | --- |
+| Account pool | `~/.config/opencode/antigravity-accounts.json` (`%APPDATA%\opencode\…` on Windows) | `0600` | Storage schema `V4`. |
+| Plugin config | `~/.config/opencode/antigravity.json` (and project `.opencode/antigravity.json`) | `0600` | Zod-validated config. |
+| Debug logs | `~/.config/opencode/antigravity-logs/` (or `log_dir`) | `0600` | Sensitive — request/response bodies. |
+| Sidebar state | `$XDG_STATE_HOME/cortexkit/antigravity-auth/sidebar-state.json` | `0600` dir `0700` | Poll-every-2s; pruned to 24h / 100 entries. |
+| RPC port file | `$XDG_STATE_HOME/cortexkit/antigravity-auth/rpc/<project-hash>/port-<pid>.json` | `0600` | Loopback token bearer. |
+| Signature cache | `signature-cache-disk-<hash>.json` (when `keep_thinking: true`) | `0600` | 2-day default TTL. |
 
----
+## Debug sinks
 
-### Migrating Accounts Between Machines
+The plugin has **two** debug sinks controlled independently:
 
-When copying `antigravity-accounts.json` to a new machine:
-1. Ensure the plugin is installed: `"plugin": ["@cortexkit/opencode-antigravity-auth@latest"]`
-2. Copy `~/.config/opencode/antigravity-accounts.json`
-3. If you get "API key missing" error, the refresh token may be invalid — re-authenticate
+- `debug: true` — file logging under `log_dir`. Disabled by default. May include request/response bodies; handle with care.
+- `debug_tui: true` — TUI log-panel verbosity. Independent of `debug`.
 
-## Known Plugin Interactions
-For details on load balancing, dual quota pools, and account storage, see [docs/MULTI-ACCOUNT.md](docs/MULTI-ACCOUNT.md).
+Combined with the runtime log-level filter (`operator.log_level`, mutable through `/antigravity-logging`), you have three independent knobs.
 
----
+## Plugin interactions
 
-## Plugin Compatibility
+For load-balancing, dual quota pools, and account storage details, see [docs/MULTI-ACCOUNT.md](./docs/MULTI-ACCOUNT.md).
 
-### @tarquinen/opencode-dcp
+### `@tarquinen/opencode-dcp`
 
-DCP creates synthetic assistant messages that lack thinking blocks. **List this plugin BEFORE DCP:**
+DCP creates synthetic assistant messages that lack thinking blocks. **List this plugin BEFORE DCP**:
 
 ```json
 {
@@ -564,7 +257,7 @@ DCP creates synthetic assistant messages that lack thinking blocks. **List this
 }
 ```
 
-### oh-my-opencode
+### `oh-my-opencode`
 
 Disable built-in auth and override agent models in `oh-my-opencode.json`:
 
@@ -583,117 +276,105 @@ Disable built-in auth and override agent models in `oh-my-opencode.json`:
 
 ### Plugins you don't need
 
-- **gemini-auth plugins** — Not needed. This plugin handles all Google OAuth.
-
----
+- **gemini-auth plugins** — not needed; this plugin handles all Google OAuth.
 
-## Configuration
+## Configuration keys (selected)
 
-Create `~/.config/opencode/antigravity.json` for optional settings:
+Created by `~/.config/opencode/antigravity.json` for optional overrides. The full list with defaults and env overrides is in the [root README](../../README.md#configuration-reference) and the generated schema at [`assets/antigravity.schema.json`](./assets/antigravity.schema.json).
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/cortexkit/antigravity-auth/main/assets/antigravity.schema.json"
+  "$schema": "https://raw.githubusercontent.com/cortexkit/antigravity-auth/main/assets/antigravity.schema.json",
+  "account_selection_strategy": "hybrid",
+  "scheduling_mode": "cache_first",
+  "soft_quota_threshold_percent": 80,
+  "quota_refresh_interval_minutes": 30,
+  "keep_thinking": false
 }
 ```
 
-Most users don't need to configure anything — defaults work well.
+Environment variables:
 
-### Model Behavior
+```bash
+OPENCODE_CONFIG_DIR=/path/to/config opencode
+OPENCODE_ANTIGRAVITY_DEBUG=1 opencode
+OPENCODE_ANTIGRAVITY_DEBUG_TUI=1 opencode
+OPENCODE_ANTIGRAVITY_LOG_DIR=/secure/path opencode
+```
 
-| 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 |
-| `cli_first` | `false` | Route Gemini models to Gemini CLI first (Claude and image models stay on Antigravity). |
+For every option, see [docs/CONFIGURATION.md](./docs/CONFIGURATION.md) and the generated [`assets/antigravity.schema.json`](./assets/antigravity.schema.json).
 
-### Account Rotation
+## Tests
 
-| 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` |
+This package ships **deterministic** tests for everything except the model registry and the live cross-model regression suite:
 
-### Quota Protection
+| Scope | Tooling | Network | Command |
+| --- | --- | --- | --- |
+| Unit (deterministic) | `bun test --isolate` | No | `bun run test` |
+| Black-box e2e (deterministic) | mock Antigravity + harness runner in `packages/e2e-tests/` | No | `bun run test:e2e` |
+| Live model inventory | `script/test-models.ts` | Yes (gated by label) | `bun run test:e2e:models` |
+| Cross-model regression | `script/test-regression.ts` + `script/test-cross-model*.sh` | Yes | `bun run test:e2e:regression` |
+| TUI smoke | install tarball + spawn | No | `bun run smoke:tui` |
 
-| Option | Default | What it does |
-|--------|---------|--------------|
-| `soft_quota_threshold_percent` | `90` | Skip account when quota usage exceeds this percentage. Prevents Google from penalizing accounts that fully exhaust quota. Set to `100` to disable. |
-| `quota_refresh_interval_minutes` | `15` | Background quota refresh interval. After successful API requests, refreshes quota cache if older than this interval. Set to `0` to disable. |
-| `soft_quota_cache_ttl_minutes` | `"auto"` | How long quota cache is considered fresh. `"auto"` = max(2 × refresh interval, 10 minutes). Set a number (1-120) for fixed TTL. |
+The deterministic tier is what CI gates; the live tier is opt-in for changes that touch the model registry, the request transform, or the response transform.
 
-> **How it works**: Quota cache is refreshed automatically after API requests (when older than `quota_refresh_interval_minutes`) and manually via "Check quotas" in `opencode auth login`. The threshold check uses `soft_quota_cache_ttl_minutes` to determine cache freshness - if cache is older, the account is considered "unknown" and allowed (fail-open). When ALL accounts exceed the threshold, the plugin waits for the earliest quota reset time (like rate limit behavior). If wait time exceeds `max_rate_limit_wait_seconds`, it errors immediately.
+## Troubleshooting
 
-### Rate Limit Scheduling
+> **Quick reset** when nothing else works: stop OpenCode, `rm ~/.config/opencode/antigravity-accounts.json`, then `opencode auth login`.
 
-Control how the plugin handles rate limits:
+### Configuration paths (all platforms)
 
-| Option | Default | What it does |
-|--------|---------|--------------|
-| `scheduling_mode` | `"cache_first"` | `"cache_first"` = wait for same account (preserves prompt cache), `"balance"` = switch immediately, `"performance_first"` = round-robin |
-| `max_cache_first_wait_seconds` | `60` | Max seconds to wait in cache_first mode before switching accounts |
-| `failure_ttl_seconds` | `3600` | Reset failure count after this many seconds (prevents old failures from permanently penalizing accounts) |
+OpenCode uses `~/.config/opencode/` on **all platforms** including Windows; do not use `%APPDATA%` for new installs. Override with `OPENCODE_CONFIG_DIR`. v1.3.x and earlier stored config under `%APPDATA%\opencode\` — the plugin auto-migrates on first read.
 
-**When to use each mode:**
-- **cache_first** (default): Best for long conversations. Waits for the same account to recover, preserving your prompt cache.
-- **balance**: Best for quick tasks. Switches accounts immediately when rate-limited for maximum availability.
-- **performance_first**: Best for many short requests. Distributes load evenly across all accounts.
+### OAuth callback issues
 
-### App Behavior
+- **Safari HTTPS-Only mode** blocks `http://localhost`. Switch browsers or temporarily disable HTTPS-Only (Safari → Settings → Privacy) during login.
+- **Stale `Address already in use :51121`** — `lsof -i :51121` (or `netstat -ano | findstr :51121` on Windows) → kill the PID → retry. The standalone CLI's `--no-browser` flag avoids the listener entirely.
+- **SSH / remote dev** — forward the callback port with `ssh -L 51121:localhost:51121 user@remote`. The standalone CLI + `--no-browser` is the simplest workaround when SSH-port-forwarding is awkward.
+- **Docker / WSL2 / containers** — localhost OAuth does not work in containers out of the box. Wait 30s for the manual URL flow, or port-forward `51121` to the host.
 
-| Option | Default | What it does |
-|--------|---------|--------------|
-| `quiet_mode` | `false` | Hide toast notifications |
-| `debug` | `false` | Enable debug file logging (`~/.config/opencode/antigravity-logs/`) |
-| `debug_tui` | `false` | Show debug logs in the TUI log panel (independent from `debug`) |
-| `auto_update` | `true` | Auto-update plugin |
+### Common errors
 
-For all options, see [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
+- **`Permission 'cloudaicompanion.companions.generateChat' denied on resource '…/locations/global'`** — Antigravity returned no project ID (likely a workspace account) and the plugin used the hardcoded fallback `rising-fact-p41fc`. Enable the Gemini for Google Cloud API on a Cloud project and set `projectId` on the account in `antigravity-accounts.json`.
+- **Gemini 3 model 400 "Unknown name 'parameters'"** — usually a tool-schema incompatibility. Update to the latest plugin version; or disable MCP servers one-by-one to isolate the offender.
+- **`Invalid function name must start with a letter or underscore`** — an MCP tool name starts with a digit (e.g. `1mcp_*`). Rename the MCP key to start with a letter (e.g. `gw`) or disable that MCP entry for Antigravity models.
+- **`All Accounts Rate-Limited (But Quota Available)`** — usually a stale cascade in `clearExpiredRateLimits()`. Lower `soft_quota_threshold_percent` (or raise to `100`), run `/antigravity-quota refresh`, or delete `antigravity-accounts.json` and re-authenticate.
+- **Infinite `.tmp` files** — a rate-limit retry loop is creating temp files faster than cleanup. Stop OpenCode, `rm ~/.config/opencode/*.tmp`, add accounts, or wait for the cooldown.
 
-**Environment variables:**
-```bash
-OPENCODE_CONFIG_DIR=/path/to/config opencode  # Custom config directory
-OPENCODE_ANTIGRAVITY_DEBUG=1 opencode         # Enable debug file logging
-OPENCODE_ANTIGRAVITY_DEBUG=2 opencode         # Verbose debug file logging
-OPENCODE_ANTIGRAVITY_DEBUG_TUI=1 opencode     # Enable TUI log panel debug output
-```
+### Sidebar / TUI
 
----
+- **`Awaiting Antigravity state` stuck** — verify `$XDG_STATE_HOME/cortexkit/antigravity-auth/sidebar-state.json` exists, is `0600`, and the host user can write. Restart the host.
+- **TUI bundle fails to spawn** — `bun run --cwd packages/opencode build` regenerates `dist/src/tui-compiled/tui.tsx`. Verify the file exists. Then `bun run --cwd packages/opencode smoke:tui`.
+- **`Antigravity RPC server is not available`** — the TUI posts to a per-PID port file in `$XDG_STATE_HOME/cortexkit/antigravity-auth/rpc/<project-hash>/`. If the running plugin process is gone, stop and restart the host.
 
-## Troubleshooting
+### Migration between machines
+
+When copying `antigravity-accounts.json` to a new machine:
 
-See the full [Troubleshooting Guide](docs/TROUBLESHOOTING.md) for solutions to common issues including:
+1. Ensure the plugin is installed: `"plugin": ["@cortexkit/opencode-antigravity-auth@latest"]`.
+2. Copy `~/.config/opencode/antigravity-accounts.json` (preserve the `0600` mode).
+3. If you see `API key missing`, the refresh token may be invalid — re-authenticate.
 
-- Auth problems and token refresh
-- "Model not found" errors
-- Session recovery
-- Gemini CLI permission errors
-- Safari OAuth issues
-- Plugin compatibility
-- Migration guides
+### Plugin config schema
 
----
+The schema reference at `assets/antigravity.schema.json` drives editor IntelliSense. Set `$schema: "https://raw.githubusercontent.com/cortexkit/antigravity-auth/main/assets/antigravity.schema.json"` in your `antigravity.json` for autocomplete in the IDE.
 
 ## Documentation
 
-- [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
-
----
+- [Root README](../../README.md) — full operator + contributor guide
+- [CHANGELOG.md](./CHANGELOG.md) — release history
+- [STRUCTURE.md](./STRUCTURE.md) — file-system map
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — architecture overview
+- [docs/CONFIGURATION.md](./docs/CONFIGURATION.md) — every option with examples
+- [docs/MULTI-ACCOUNT.md](./docs/MULTI-ACCOUNT.md) — load balancing, dual quota, storage
+- [docs/MODEL-VARIANTS.md](./docs/MODEL-VARIANTS.md) — variants and thinking budgets
+- [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) — long-form troubleshooting
+- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) — internal architecture
+- [docs/ANTIGRAVITY_API_SPEC.md](./docs/ANTIGRAVITY_API_SPEC.md) — Antigravity API reference
 
 ## Support
 
-If this plugin saves you time, consider supporting its development:
-
-[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/S6S81QBOIR)
-
----
+If this plugin saves you time, consider supporting its development at <https://ko-fi.com/S6S81QBOIR>.
 
 ## Credits
 
@@ -702,29 +383,4 @@ If this plugin saves you time, consider supporting its development:
 
 ## License
 
-MIT License. See [LICENSE](LICENSE) for details.
-
-<details>
-<summary><b>Legal</b></summary>
-
-### Intended Use
-
-- Personal / internal development only
-- Respect internal quotas and data handling policies
-- Not for production services or bypassing intended limits
-
-### 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
-
-### Disclaimer
-
-- Not affiliated with Google. This is an independent open-source project.
-- "Antigravity", "Gemini", "Google Cloud", and "Google" are trademarks of Google LLC.
-
-</details>
+MIT. See [LICENSE](./LICENSE).