feat(providers): auto-discover suffixed env providers

.env.template

@@ -234,6 +234,10 @@
 # =============================================================================
 # Provider API Keys (uncomment and set the ones you need)
 # =============================================================================
+# Add more instances with <PROVIDER>_<SUFFIX>_*.
+# Example: OPENAI_EAST_API_KEY and OPENAI_EAST_BASE_URL register provider openai-east.
+# Underscores in the suffix become hyphens in the provider name.
+
 # OpenAI
 # OPENAI_API_KEY=sk-...
 # OPENAI_BASE_URL=https://api.openai.com/v1

README.md

@@ -84,6 +84,10 @@ Example model identifiers are illustrative and subject to change; consult provid
 For Z.ai's GLM Coding Plan, set `ZAI_BASE_URL=https://api.z.ai/api/coding/paas/v4`.
 For Oracle, set `ORACLE_MODELS=openai.gpt-oss-120b,xai.grok-3` when the
 upstream `/models` endpoint is unavailable.
+To register multiple instances of the same provider type without `config.yaml`,
+use suffixed env vars such as `OPENAI_EAST_API_KEY` and
+`OPENAI_EAST_BASE_URL`; this registers provider `openai-east` with type
+`openai`.
 
 ---
 

docs/advanced/config-yaml.mdx

@@ -11,13 +11,21 @@ injection.
 Use `config.yaml` when you need structure that env vars cannot express cleanly,
 especially:
 
-- multiple providers with the same type
-- custom provider instance names such as `ollama-a`, `ollama-b`, or `my-openai`
+- per-provider resilience overrides
+- custom provider instance names that do not fit the generated
+  `<provider-type>-<suffix>` env naming
 - larger nested config that is easier to review in one file
 
+For multiple provider instances, env vars support
+`<PROVIDER>_<SUFFIX>_API_KEY`, `<PROVIDER>_<SUFFIX>_BASE_URL`, and
+`<PROVIDER>_<SUFFIX>_MODELS`. The suffix becomes a hyphenated provider name:
+`OPENAI_EAST_API_KEY` registers `openai-east`, and
+`OLLAMA_A_BASE_URL` registers `ollama-a`. Azure also supports
+`<PROVIDER>_<SUFFIX>_API_VERSION`.
+
 For Oracle specifically, a single fallback model list can now stay in env via
-`ORACLE_MODELS`. Use YAML when you need custom Oracle provider names or more
-than one Oracle provider instance.
+`ORACLE_MODELS`. Use suffixed env vars such as `ORACLE_US_MODELS` for multiple
+Oracle instances without YAML.
 
 ## Priority Order
 

docs/advanced/configuration.mdx

@@ -227,8 +227,9 @@ providers:
 
 <Tip>
   The YAML file is entirely optional. Any setting you can put in YAML can also
-  be set via environment variables. Use YAML when you need to configure custom
-  providers or prefer a structured config file.
+  be set via environment variables. Use YAML when you need per-provider
+  resilience overrides, generated provider names are not enough, or you prefer
+  a structured config file.
 </Tip>
 
 ## Provider Configuration
@@ -254,12 +255,29 @@ export ORACLE_MODELS="openai.gpt-oss-120b,xai.grok-3" # Optional fallback invent
 export OLLAMA_BASE_URL="http://localhost:11434/v1" # Registers "ollama" provider
 ```
 
-GoModel also works with additional OpenAI-compatible providers out of the box
-through YAML provider blocks.
+Use suffixed variables to register more than one instance of the same provider
+type without YAML. GoModel normalizes the suffix to lowercase and converts
+underscores to hyphens in the configured provider name:
+
+```bash
+export OPENAI_EAST_API_KEY="sk-..." # Registers "openai-east", type "openai"
+export OPENAI_EAST_BASE_URL="https://east.example.com/v1"
+
+export OPENAI_WEST_API_KEY="sk-..." # Registers "openai-west", type "openai"
+export OPENAI_WEST_BASE_URL="https://west.example.com/v1"
+```
+
+The same pattern works for every registered provider type:
+`<PROVIDER>_<SUFFIX>_API_KEY`, `<PROVIDER>_<SUFFIX>_BASE_URL`, and
+`<PROVIDER>_<SUFFIX>_MODELS`. Azure also supports
+`<PROVIDER>_<SUFFIX>_API_VERSION`. Azure and Oracle still require their
+suffixed `BASE_URL` values because their endpoints are deployment- or
+region-specific.
 
 ### YAML Provider Blocks
 
-For more control (custom base URLs, model restrictions, or custom provider names), use the YAML file:
+For more control (custom names, per-provider resilience, or larger structured
+settings), use the YAML file:
 
 ```yaml
 providers:
@@ -297,7 +315,8 @@ providers:
 <Note>
   For Oracle, give GoModel a fallback inventory with `ORACLE_MODELS` or
   `models:`. `ORACLE_MODELS` is enough for the default single-provider setup;
-  use YAML when you need custom provider names or multiple Oracle providers.
+  use suffixed env vars such as `ORACLE_US_MODELS` for env-only multi-provider
+  setups. Use YAML when you need custom names or larger provider blocks.
   See the [Oracle guide](/guides/oracle) for the required OCI policy and a
   tested configuration. Automatic model discovery is not yet a reliable,
   validated path for this provider: GoModel can try Oracle's OpenAI-compatible