feat(webui): update README with comprehensive documentation for WebUI features and usage

README.md

@@ -59,62 +59,7 @@ npm start
 
 ## Quick Start
 
-### 1. Add Account(s)
+### 1. Start the Proxy Server
-
-You have two options:
-
-**Option A: Use Antigravity (Single Account)**
-
-If you have Antigravity installed and logged in, the proxy will automatically extract your token. No additional setup needed.
-
-**Option B: Add Google Accounts via OAuth (Recommended for Multi-Account)**
-
-Add one or more Google accounts for load balancing.
-
-#### Desktop/Laptop (with browser)
-
-```bash
-# If installed via npm
-antigravity-claude-proxy accounts add
-
-# If using npx
-npx antigravity-claude-proxy@latest accounts add
-
-# If cloned locally
-npm run accounts:add
-```
-
-This opens your browser for Google OAuth. Sign in and authorize access. Repeat for multiple accounts.
-
-#### Headless Server (Docker, SSH, no desktop)
-
-```bash
-# If installed via npm
-antigravity-claude-proxy accounts add --no-browser
-
-# If using npx
-npx antigravity-claude-proxy@latest accounts add -- --no-browser
-
-# If cloned locally
-npm run accounts:add -- --no-browser
-```
-
-This displays an OAuth URL you can open on another device (phone/laptop). After signing in, copy the redirect URL or authorization code and paste it back into the terminal.
-
-#### Manage accounts
-
-```bash
-# List all accounts
-antigravity-claude-proxy accounts list
-
-# Verify accounts are working
-antigravity-claude-proxy accounts verify
-
-# Interactive account management
-antigravity-claude-proxy accounts
-```
-
-### 2. Start the Proxy Server
 
 ```bash
 # If installed via npm
@@ -129,6 +74,34 @@ npm start
 
 The server runs on `http://localhost:8080` by default.
 
+### 2. Link Account(s)
+
+Choose one of the following methods to authorize the proxy:
+
+#### **Method A: Web Dashboard (Recommended)**
+
+1. With the proxy running, open `http://localhost:8080` in your browser.
+2. Navigate to the **Accounts** tab and click **Add Account**.
+3. Complete the Google OAuth authorization in the popup window.
+
+#### **Method B: CLI (Desktop or Headless)**
+
+If you prefer the terminal or are on a remote server:
+
+```bash
+# Desktop (opens browser)
+antigravity-claude-proxy accounts add
+
+# Headless (Docker/SSH)
+antigravity-claude-proxy accounts add --no-browser
+```
+
+> For full CLI account management options, run `antigravity-claude-proxy accounts --help`.
+
+#### **Method C: Automatic (Antigravity Users)**
+
+If you have the **Antigravity** app installed and logged in, the proxy will automatically detect your local session. No additional setup is required.
+
 ### 3. Verify It's Working
 
 ```bash
@@ -145,6 +118,18 @@ curl "http://localhost:8080/account-limits?format=table"
 
 ### Configure Claude Code
 
+You can configure these settings in two ways:
+
+#### **Via Web Console (Recommended)**
+
+1. Open the WebUI at `http://localhost:8080`.
+2. Go to **Settings** → **Claude CLI**.
+3. Select your preferred models and click **Apply to Claude CLI**.
+
+> [!TIP] > **Configuration Precedence**: System environment variables (set in shell profile like `.zshrc`) take precedence over the `settings.json` file. If you use the Web Console to manage settings, ensure you haven't manually exported conflicting variables in your terminal.
+
+#### **Manual Configuration**
+
 Create or edit the Claude Code settings file:
 
 **macOS:** `~/.claude/settings.json`
@@ -236,18 +221,18 @@ claude
 
 ### Claude Models
 
-| Model ID | Description |
+| Model ID                     | Description                              |
-|----------|-------------|
+| ---------------------------- | ---------------------------------------- |
 | `claude-sonnet-4-5-thinking` | Claude Sonnet 4.5 with extended thinking |
-| `claude-opus-4-5-thinking` | Claude Opus 4.5 with extended thinking |
+| `claude-opus-4-5-thinking`   | Claude Opus 4.5 with extended thinking   |
-| `claude-sonnet-4-5` | Claude Sonnet 4.5 without thinking |
+| `claude-sonnet-4-5`          | Claude Sonnet 4.5 without thinking       |
 
 ### Gemini Models
 
-| Model ID | Description |
+| Model ID            | Description                     |
-|----------|-------------|
+| ------------------- | ------------------------------- |
-| `gemini-3-flash` | Gemini 3 Flash with thinking |
+| `gemini-3-flash`    | Gemini 3 Flash with thinking    |
-| `gemini-3-pro-low` | Gemini 3 Pro Low with thinking |
+| `gemini-3-pro-low`  | Gemini 3 Pro Low with thinking  |
 | `gemini-3-pro-high` | Gemini 3 Pro High with thinking |
 
 Gemini models include full thinking support with `thoughtSignature` handling for multi-turn conversations.
@@ -267,20 +252,71 @@ When you add multiple accounts, the proxy automatically:
 Check account status anytime:
 
 ```bash
+# Web UI: http://localhost:8080/ (Accounts tab)
+# CLI Table:
 curl "http://localhost:8080/account-limits?format=table"
 ```
 
+#### CLI Management Reference
+
+If you prefer using the terminal for management:
+
+```bash
+# List all accounts
+antigravity-claude-proxy accounts list
+
+# Verify account health
+antigravity-claude-proxy accounts verify
+
+# Interactive CLI menu
+antigravity-claude-proxy accounts
+```
+
+---
+
+## Web Management Console
+
+The proxy includes a built-in, modern web interface for real-time monitoring and configuration. Access the console at: `http://localhost:8080` (default port).
+
+![Antigravity Console](images/webui-dashboard.png)
+
+### Key Features
+
+- **Real-time Dashboard**: Monitor request volume, active accounts, and model health.
+- **Visual Model Quota**: Track per-model usage and next reset times.
+- **Account Management**: Add/remove Google accounts via OAuth without using the CLI.
+- **Claude CLI Configuration**: Edit your `~/.claude/settings.json` directly from the browser.
+- **Live Logs**: Stream server logs with level-based filtering and search.
+- **Advanced Tuning**: Configure retries, timeouts, and debug mode on the fly.
+- **Bilingual Interface**: Full support for English and Chinese (switch via Settings).
+
+---
+
+## Advanced Configuration
+
+While most users can use the default settings, you can tune the proxy behavior via the **Settings → Server** tab in the WebUI or by creating a `config.json` file.
+
+### Configurable Options
+
+- **WebUI Password**: Secure your dashboard with `WEBUI_PASSWORD` env var or in config.
+- **Custom Port**: Change the default `8080` port.
+- **Retry Logic**: Configure `maxRetries`, `retryBaseMs`, and `retryMaxMs`.
+- **Load Balancing**: Adjust `defaultCooldownMs` and `maxWaitBeforeErrorMs`.
+- **Persistence**: Enable `persistTokenCache` to save OAuth sessions across restarts.
+
+Refer to `config.example.json` for a complete list of fields and documentation.
+
 ---
 
 ## API Endpoints
 
-| Endpoint | Method | Description |
+| Endpoint          | Method | Description                                                           |
-|----------|--------|-------------|
+| ----------------- | ------ | --------------------------------------------------------------------- |
-| `/health` | GET | Health check |
+| `/health`         | GET    | Health check                                                          |
-| `/account-limits` | GET | Account status and quota limits (add `?format=table` for ASCII table) |
+| `/account-limits` | GET    | Account status and quota limits (add `?format=table` for ASCII table) |
-| `/v1/messages` | POST | Anthropic Messages API |
+| `/v1/messages`    | POST   | Anthropic Messages API                                                |
-| `/v1/models` | GET | List available models |
+| `/v1/models`      | GET    | List available models                                                 |
-| `/refresh-token` | POST | Force token refresh |
+| `/refresh-token`  | POST   | Force token refresh                                                   |
 
 ---
 
@@ -314,6 +350,7 @@ npm run test:caching       # Prompt caching
 ### "Could not extract token from Antigravity"
 
 If using single-account mode with Antigravity:
+
 1. Make sure Antigravity app is installed and running
 2. Ensure you're logged in to Antigravity
 
@@ -322,11 +359,13 @@ Or add accounts via OAuth instead: `antigravity-claude-proxy accounts add`
 ### 401 Authentication Errors
 
 The token might have expired. Try:
+
 ```bash
 curl -X POST http://localhost:8080/refresh-token
 ```
 
 Or re-authenticate the account:
+
 ```bash
 antigravity-claude-proxy accounts
 ```
@@ -338,6 +377,7 @@ With multiple accounts, the proxy automatically switches to the next available a
 ### Account Shows as "Invalid"
 
 Re-authenticate the account:
+
 ```bash
 antigravity-claude-proxy accounts
 # Choose "Re-authenticate" for the invalid account
@@ -404,4 +444,4 @@ MIT
 
 ## Star History
 
-[![Star History Chart](https://api.star-history.com/svg?repos=badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left&cache-control=no-cache)](https://www.star-history.com/#badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left)
+[![Star History Chart](https://api.star-history.com/svg?repos=badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left&cache-control=no-cache)](https://www.star-history.com/#badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left)

public/favicon.svg

@@ -0,0 +1,10 @@
+<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="favicon_grad" x1="0" y1="0" x2="32" y2="32" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#A855F7" />
+      <stop offset="1" stop-color="#2563EB" />
+    </linearGradient>
+  </defs>
+  <rect width="32" height="32" rx="6" fill="url(#favicon_grad)" />
+  <text x="50%" y="50%" dominant-baseline="central" text-anchor="middle" fill="white" font-family="Inter, system-ui, sans-serif" font-weight="800" font-size="14">AG</text>
+</svg>

public/index.html

@@ -5,6 +5,7 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>Antigravity Console</title>
+    <link rel="icon" type="image/svg+xml" href="favicon.svg">
 
     <!-- Libraries -->
     <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>