docs: refresh gemini cli usage refs

docs/concepts/model-providers.md

@@ -283,6 +283,8 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
   - Note: you do **not** paste a client id or secret into `openclaw.json`. The CLI login flow stores
     tokens in auth profiles on the gateway host.
   - If requests fail after login, set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` on the gateway host.
+  - Gemini CLI JSON replies are parsed from `response`; usage falls back to
+    `stats`, with `stats.cached` normalized into OpenClaw `cacheRead`.
 
 ### Z.AI (GLM)
 

docs/concepts/usage-tracking.md

@@ -29,6 +29,8 @@ title: "Usage Tracking"
 - **Anthropic (Claude)**: OAuth tokens in auth profiles.
 - **GitHub Copilot**: OAuth tokens in auth profiles.
 - **Gemini CLI**: OAuth tokens in auth profiles.
+  - JSON usage falls back to `stats`; `stats.cached` is normalized into
+    `cacheRead`.
 - **OpenAI Codex**: OAuth tokens in auth profiles (accountId used when present).
 - **MiniMax**: API key (coding plan key; `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`, or `MINIMAX_API_KEY`); uses the 5‑hour coding plan window. MiniMax's raw `usage_percent` / `usagePercent` fields mean **remaining** quota, so OpenClaw inverts them before display; count-based fields win when present.
 - **z.ai**: API key via env/config/auth store.

docs/gateway/cli-backends.md

@@ -185,6 +185,8 @@ load local files from plain paths (Claude Code CLI behavior).
 ## Inputs / outputs
 
 - `output: "json"` (default) tries to parse JSON and extract text + session id.
+- For Gemini CLI JSON output, OpenClaw reads reply text from `response` and
+  usage from `stats` when `usage` is missing or empty.
 - `output: "jsonl"` parses JSONL streams (for example Claude CLI `stream-json`
   and Codex CLI `--json`) and extracts the final agent message plus session
   identifiers when present.
@@ -231,6 +233,14 @@ The bundled Google plugin also registers a default for `google-gemini-cli`:
 - `sessionMode: "existing"`
 - `sessionIdFields: ["session_id", "sessionId"]`
 
+Gemini CLI JSON notes:
+
+- Reply text is read from the JSON `response` field.
+- Usage falls back to `stats` when `usage` is absent or empty.
+- `stats.cached` is normalized into OpenClaw `cacheRead`.
+- If `stats.input` is missing, OpenClaw derives input tokens from
+  `stats.input_tokens - stats.cached`.
+
 Override only if needed (common: absolute `command` path).
 
 ## Plugin-owned defaults

docs/providers/google.md

@@ -71,6 +71,14 @@ If Gemini CLI OAuth requests fail after login, set
 `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` on the gateway host and
 retry.
 
+Gemini CLI JSON usage notes:
+
+- Reply text comes from the CLI JSON `response` field.
+- Usage falls back to `stats` when the CLI leaves `usage` empty.
+- `stats.cached` is normalized into OpenClaw `cacheRead`.
+- If `stats.input` is missing, OpenClaw derives input tokens from
+  `stats.input_tokens - stats.cached`.
+
 ## Capabilities
 
 | Capability             | Supported         |

docs/reference/api-usage-costs.md

@@ -23,6 +23,9 @@ OpenClaw features that can generate provider usage or paid API calls.
 
 - `/usage full` appends a usage footer to every reply, including **estimated cost** (API-key only).
 - `/usage tokens` shows tokens only; subscription-style OAuth, legacy token, and CLI flows hide dollar cost.
+- Gemini CLI note: when the CLI returns JSON output, OpenClaw reads usage from
+  `stats`, normalizes `stats.cached` into `cacheRead`, and derives input tokens
+  from `stats.input_tokens - stats.cached` when needed.
 
 Anthropic note: starting **April 4, 2026 at 12:00 PM PT / 8:00 PM BST**,
 Anthropic says OpenClaw no longer uses included Claude subscription limits.

docs/reference/prompt-caching.md

@@ -138,6 +138,15 @@ If the provider does not support this cache mode, `cacheRetention` has no effect
   forwarding a provider-native cached-content reference, not synthesizing cache
   markers.
 
+### Gemini CLI JSON usage
+
+- Gemini CLI JSON output can also surface cache hits through `stats.cached`;
+  OpenClaw maps that to `cacheRead`.
+- If the CLI omits a direct `stats.input` value, OpenClaw derives input tokens
+  from `stats.input_tokens - stats.cached`.
+- This is usage normalization only. It does not mean OpenClaw is creating
+  Anthropic/OpenAI-style prompt-cache markers for Gemini CLI.
+
 ## OpenClaw cache-stability guards
 
 OpenClaw also keeps several cache-sensitive payload shapes deterministic before

docs/reference/token-use.md

@@ -65,6 +65,9 @@ Usage surfaces normalize common provider-native field aliases before display.
 For OpenAI-family Responses traffic, that includes both `input_tokens` /
 `output_tokens` and `prompt_tokens` / `completion_tokens`, so transport-specific
 field names do not change `/status`, `/usage`, or session summaries.
+Gemini CLI JSON usage is normalized too: reply text comes from `response`, and
+`stats.cached` maps to `cacheRead` with `stats.input_tokens - stats.cached`
+used when the CLI omits an explicit `stats.input` field.
 
 ## Cost estimation (when shown)