Document Antigravity data sources when the app is closed

README.md

@@ -87,7 +87,7 @@ See [CLI configuration](docs/cli-configuration.md) for the full flow.
 - [Alibaba Token Plan](docs/alibaba-token-plan.md) — Bailian browser/manual cookies for token-plan credits.
 - [Qwen Cloud](docs/qwen-cloud.md) — 5-hour and weekly individual Token Plan usage via browser/manual cookies.
 - [Gemini](docs/gemini.md) — OAuth-backed quota API using Gemini CLI credentials (no browser cookies).
-- [Antigravity](docs/antigravity.md) — Local language server probe (experimental); no external auth.
+- [Antigravity](docs/antigravity.md) — Local language server probe, `agy` CLI HTTPS source, and Google OAuth fallback (experimental).
 - [Droid](docs/factory.md) — Browser cookies + WorkOS token flows for Factory usage + billing.
 - [Copilot](docs/copilot.md) — GitHub device flow + Copilot internal usage API.
 - [Devin](docs/devin.md) — Chrome localStorage session or manual Bearer token for daily and weekly quotas.

docs/antigravity.md

@@ -15,13 +15,27 @@ the Antigravity app or run `agy`, sign in, then refresh. See `docs/gemini.md` fo
 provider migration notes. CodexBar offers the handoff only after an observed Google migration
 signal and never enables or falls back to Antigravity automatically.
 
+To use the `agy` CLI source without keeping the desktop app open, install the CLI first
+(`brew install --cask antigravity-cli`; use `ANTIGRAVITY_CLI_PATH` when it is not on PATH), then
+run `agy` once and sign in. CodexBar keeps the signed-in `agy` local HTTPS server alive briefly
+after each refresh and stops it when idle.
+
 Antigravity supports four usage data sources:
 
 1. The Antigravity 2.0 app's local `language_server` (preferred when the app is open).
 2. The `agy` CLI's embedded HTTPS localhost server (preferred over the IDE because it exposes richer quota data).
 3. The Antigravity IDE extension `language_server` (used after `agy` CLI because current IDE local payloads only expose session/model quota data).
 4. Google OAuth-backed remote usage (explicit OAuth mode, and the account-scoped fallback used for multi-account switching). The OAuth path can store multiple Google accounts through the shared token-account switcher.
 
+## When the Antigravity app is closed
+
+The app-local `language_server` exists only while Antigravity.app is running. With the app closed,
+CodexBar relies on the `agy` CLI HTTPS source or the Google OAuth fallback. Without a signed-in
+`agy`, the OAuth fallback can only prove model availability, so the menu shows an all-100%
+placeholder instead of real quota numbers. A freshly spawned `agy` needs a few seconds for macOS
+keyring authentication before its quota endpoints answer, so the first refresh after a cold start
+can take a few extra seconds while CodexBar waits for readiness; later refreshes reuse the warmed session.
+
 The local and CLI paths both prefer Antigravity's internal `RetrieveUserQuotaSummary` quota payload and may fall back to
 `GetUserStatus`, then `GetCommandModelConfigs`; CodexBar never scrapes the desktop UI or the `agy` TUI.
 

docs/providers.md

@@ -185,7 +185,8 @@ scan fails, while provider/account configuration changes replace obsolete result
 
 ## Antigravity
 - Local Antigravity language server (internal protocol, HTTPS on localhost).
-- `GetUserStatus` primary; `GetCommandModelConfigs` fallback.
+- `agy` CLI HTTPS source when the app is closed; Google OAuth fallback.
+- `RetrieveUserQuotaSummary` primary; `GetUserStatus` / `GetCommandModelConfigs` fallbacks.
 - Status: Google Workspace incidents (Gemini product).
 - Details: `docs/antigravity.md`.