docs(api): explain automatic transport selection

CHANGELOG.md

@@ -2,8 +2,9 @@
 
 ## Unreleased
 
-- Replace the reverse-engineered `/alpha/generate` integration with Command Code's documented Provider API: `/provider/v1/chat/completions` for non-Claude models and `/provider/v1/messages` for Claude models.
+- Prefer Command Code's Provider API (`/provider/v1/chat/completions` and `/provider/v1/messages`) and automatically fall back to the existing `/alpha/generate` transport only when the Provider API returns `403 upgrade_required` for a Go-plan account.
-- Use Pi's native OpenAI- and Anthropic-compatible providers for streaming, tools, reasoning, images, usage, errors, and retries while preserving dynamic model discovery, offline cache, refresh/status commands, pricing, and OAuth credentials.
+- Remember the detected transport for the running process, re-detect it when credentials change, and never fall back for unrelated authentication, permission, rate-limit, network, or server failures.
+- Use Pi's native OpenAI- and Anthropic-compatible providers for Provider API streaming while preserving the existing hardened generate transport, dynamic model discovery, offline cache, refresh/status commands, pricing, and OAuth credentials.
 - Let `/login` use browser authentication, an explicit API-key prompt, or a directly pasted API key.
 - Add optional zero-data-retention headers through `COMMANDCODE_ZDR=1`.
 - Refresh GPT-5.6 Terra and Luna display prices after their temporary 50% promotion ended.

README.md

@@ -7,13 +7,14 @@ A custom provider for [pi](https://github.com/earendil-works/pi) that connects t
 
 > **Disclaimer:** This is an unofficial, community-maintained integration. It is not affiliated with, endorsed by, or supported by Command Code. You need your own Command Code account, API key, and a plan with Provider API access. Command Code's terms, availability, and pricing apply.
 
-The extension uses only Command Code's documented Provider API endpoints:
+The extension uses one provider and automatically selects the transport supported by the authenticated account:
 
-- `GET /provider/v1/models`
+- `GET /provider/v1/models` for model discovery
-- `POST /provider/v1/chat/completions` for non-Claude models
+- `POST /provider/v1/chat/completions` for non-Claude models with Provider API access
-- `POST /provider/v1/messages` for Claude models
+- `POST /provider/v1/messages` for Claude models with Provider API access
+- `/alpha/generate` after the Provider API explicitly returns `403 upgrade_required`, which currently identifies Go-plan accounts
 
-Every current Command Code plan except **Go** has Provider API access: GOAT, Pro, Max, Team, and Provider.
+The detected transport is remembered only for the running process and is re-evaluated when the credential changes. Other authentication, permission, rate-limit, network, and server errors never trigger the fallback.
 
 ## Install
 
@@ -92,7 +93,7 @@ Open `/model` and select one of the models provided by Command Code. Model avail
 
 ### Reasoning support
 
-Reasoning metadata is enriched only for models whose Command Code effort support is known. Those models register a model-specific `thinkingLevelMap`, so pi and OMP expose only supported levels. Pi's native OpenAI- and Anthropic-compatible providers translate the selected level to the endpoint's documented reasoning fields. Unsupported levels and newly discovered models without metadata do not claim reasoning support.
+Reasoning metadata is enriched only for models whose Command Code effort support is known. Those models register a model-specific `thinkingLevelMap`, so pi and OMP expose only supported levels. Pi's native OpenAI- and Anthropic-compatible providers translate the selected level for Provider API accounts; the existing Command Code generate transport sends the matching `reasoning_effort` for Go accounts. Unsupported levels and newly discovered models without metadata do not claim reasoning support.
 
 List Command Code models from the terminal: