diff --git a/README.md b/README.md
index d9edbdf..0d1c360 100644
--- a/README.md
+++ b/README.md
@@ -78,29 +78,26 @@ Once installed, your agent will recognize when someone hits the Claude auth erro
 
 ## Quick start (manual — Gemini recommended for most people)
 
-1. Get a free API key at [aistudio.google.com](https://aistudio.google.com)
-2. Open your OpenClaw config (`~/.openclaw/openclaw.json`)
-3. Set your provider:
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "model": {
-        "primary": "gemini/gemini-2.5-pro"
-      }
-    }
-  }
-}
+1. Get a Gemini API key at [aistudio.google.com](https://aistudio.google.com)
+2. Add auth to OpenClaw:
+
+```bash
+openclaw models auth login --provider gemini
+```
+
+3. Set Gemini as the default model:
+
+```bash
+openclaw models set gemini/gemini-2.5-pro
 ```
 
-4. Add your key to OpenClaw:
+4. Restart the gateway:
 
 ```bash
-openclaw auth add --provider gemini --key YOUR_API_KEY
+openclaw gateway restart
 ```
 
-5. Restart the gateway. Done.
+5. Done.
 
 → Full guide with troubleshooting: [guides/gemini.md](guides/gemini.md)
 
diff --git a/guides/gemini.md b/guides/gemini.md
index 9318a92..b1354a5 100644
--- a/guides/gemini.md
+++ b/guides/gemini.md
@@ -1,6 +1,6 @@
 # Gemini 2.5 Pro — OpenClaw Setup Guide
 
-Gemini 2.5 Pro is Google's flagship model. It has a **free tier** with generous daily limits, making it the easiest drop-in Claude replacement for most OpenClaw users.
+Gemini 2.5 Pro is a strong Claude replacement for many OpenClaw setups, especially if you want a direct API-backed provider instead of relying on Claude subscriptions.
 
 ---
 
@@ -11,51 +11,26 @@ Gemini 2.5 Pro is Google's flagship model. It has a **free tier** with generous
 3. Click **Get API key** → **Create API key**
 4. Copy it somewhere safe
 
-**Free tier limits (as of April 2026):**
-- 1,500 requests/day
-- 1M tokens/minute
-- No credit card required
+> **Note:** Google’s free-tier limits and paid pricing change over time and can vary by account. Check Google AI Studio’s current pricing/rate-limit pages instead of relying on hardcoded numbers.
 
 ---
 
-## Step 2: Add to OpenClaw
+## Step 2: Add Gemini auth to OpenClaw
+
+Use the current OpenClaw auth flow:
 
 ```bash
-openclaw auth add --provider gemini --key YOUR_GEMINI_API_KEY
+openclaw models auth login --provider gemini
 ```
 
-Or add it directly to `~/.openclaw/openclaw.json`:
-
-```json
-{
-  "auth": {
-    "profiles": {
-      "gemini:default": {
-        "provider": "gemini",
-        "mode": "token",
-        "token": "YOUR_GEMINI_API_KEY"
-      }
-    }
-  }
-}
-```
+Follow the prompts and paste your Gemini API key when asked.
 
 ---
 
-## Step 3: Set as default model
-
-In `~/.openclaw/openclaw.json`:
+## Step 3: Set Gemini as your default model
 
-```json
-{
-  "agents": {
-    "defaults": {
-      "model": {
-        "primary": "gemini/gemini-2.5-pro"
-      }
-    }
-  }
-}
+```bash
+openclaw models set gemini/gemini-2.5-pro
 ```
 
 ---
@@ -63,46 +38,52 @@ In `~/.openclaw/openclaw.json`:
 ## Step 4: Restart the gateway
 
 ```bash
-# Graceful restart (preferred)
-kill -SIGUSR1 $(pgrep -x openclaw-gateway)
-
-# Or full restart via systemd
-systemctl --user restart openclaw-gateway
+openclaw gateway restart
 ```
 
 ---
 
 ## Verify it's working
 
-Send a message to your OpenClaw agent. Check gateway logs:
+Quick check:
 
 ```bash
-journalctl --user -u openclaw-gateway -f | grep -E "gemini|model|error"
+openclaw models status --plain
 ```
 
-You should see `gemini` in the provider output, not `anthropic`.
+Optional live auth probe:
+
+```bash
+openclaw models status --probe --probe-provider gemini
+```
+
+You can also watch gateway logs while sending a test message:
+
+```bash
+journalctl --user -u openclaw-gateway -f | grep -E "gemini|model|error"
+```
 
 ---
 
 ## Troubleshooting
 
 **`PERMISSION_DENIED` or `API key not valid`**
-→ Double-check the key in `openclaw.json`. No extra spaces or quotes.
+→ Re-run:
 
-**`RESOURCE_EXHAUSTED`**
-→ You've hit the free tier limit. Wait until midnight Pacific, or upgrade to a paid Gemini API key (~$7/MTok for 2.5 Pro).
+```bash
+openclaw models auth login --provider gemini
+```
 
-**Model not found**
-→ Check OpenClaw version supports Gemini. Run `openclaw --version`. Update if below v2026.3.x.
+Then paste the key again carefully.
 
----
+**`RESOURCE_EXHAUSTED`**
+→ You likely hit Gemini rate limits or quota. Check your current Google AI Studio limits/pricing and wait for quota reset if you’re on a free tier.
 
-## Cost estimate (paid tier)
+**Model not found**
+→ Check your OpenClaw version:
 
-| Usage | Cost/month |
-|-------|-----------|
-| Light (10k msgs) | ~$2 |
-| Medium (50k msgs) | ~$8 |
-| Heavy (200k msgs) | ~$30 |
+```bash
+openclaw --version
+```
 
-*Based on ~500 tokens avg per message, Gemini 2.5 Pro pricing.*
+If needed, update OpenClaw first.