docs: surface per-provider AI model override env vars (#290)

* docs: surface per-provider AI model override env vars

.env.example only showed AI_TEXT_PROVIDER/AI_IMAGE_PROVIDER/
AI_AUDIO_PROVIDER (which provider to use), never the per-provider
model overrides (OPENAI_IMAGE_MODEL, GEMINI_AUDIO_MODEL, etc.) that
config/ai.php already wires up for every provider capability. A
self-hoster reading only .env.example had no way to discover these
existed.

These aren't new: laravel/ai already resolves each capability's
model independently per provider (confirmed in vendor - e.g.
OpenAiProvider::defaultImageModel() falls back to a hardcoded image
model, never to the text model), so there was never actually a
text-model fallback bug to fix in code. The gap was purely that the
override knobs were invisible outside of reading config/ai.php's
source directly.

* docs: document AI provider keys, URLs and example model values

The override block landed with bare variable names and only covered the
five providers whose API keys were already in .env.example. Filled in
what a self-hoster still could not discover:

- Example values on every model override, taken from laravel/ai's
  current per-capability defaults, so the ID format is visible (an
  Ollama tag, an OpenRouter vendor/model path and a bare OpenAI ID
  look nothing alike).
- The keys and URLs for the providers .env.example already advertises
  as valid but never documented: XAI, GROQ, MISTRAL, DEEPSEEK,
  OLLAMA_URL and the openai-compatible endpoint. Ollama was the
  scenario in the original report and OLLAMA_URL matters more there
  than OLLAMA_TEXT_MODEL does.
- GROQ/MISTRAL/DEEPSEEK text models, missing while their providers
  were listed as options.
- openai-compatible has no built-in default model and throws without
  OPENAI_COMPATIBLE_TEXT_MODEL, so that one is flagged as required.
- Corrected the audio provider list: gemini and openrouter implement
  AudioProvider too. The image and audio lists are no longer written
  as exhaustive.
- Mirrored all of it into docker/.env.docker.example, which carried the
  same block untouched and is the file Docker self-hosters copy. Its
  OLLAMA_URL points at the host instead of localhost.

---------

Co-authored-by: Paulo Castellano <paulo@castellanos.llc>

.env.example

@@ -185,16 +185,55 @@ ANTHROPIC_API_KEY=
 GEMINI_API_KEY=
 OPENROUTER_API_KEY=
 ELEVENLABS_API_KEY=
+# Only needed if you point one of the AI_*_PROVIDER vars below at these providers.
+# XAI_API_KEY=
+# GROQ_API_KEY=
+# MISTRAL_API_KEY=
+# DEEPSEEK_API_KEY=
+# Ollama runs locally and needs no key — set the URL only if it isn't on the default port.
+# OLLAMA_URL=http://localhost:11434
+# Any OpenAI-compatible endpoint (LM Studio, vLLM, LocalAI, ...) via AI_TEXT_PROVIDER=openai-compatible.
+# It has no built-in default model, so OPENAI_COMPATIBLE_TEXT_MODEL is required for that provider.
+# OPENAI_COMPATIBLE_URL=
+# OPENAI_COMPATIBLE_API_KEY=
+# OPENAI_COMPATIBLE_TEXT_MODEL=
 
 # AI Provider Selection
-# text:  openai | anthropic | gemini | openrouter | xai | groq | mistral | deepseek | ...
+# text:  openai | anthropic | gemini | openrouter | xai | groq | mistral | deepseek | ollama | ...
-# image: openai | gemini | xai | openrouter
+# image: openai | gemini | xai | openrouter | ...
-# audio: openai | elevenlabs
+# audio: openai | elevenlabs | gemini | openrouter | ...
 # OpenRouter is a first-class laravel/ai provider (AI_TEXT_PROVIDER=openrouter + OPENROUTER_API_KEY).
 AI_TEXT_PROVIDER=openai
 AI_IMAGE_PROVIDER=openai
 AI_AUDIO_PROVIDER=elevenlabs
 
+# AI Model Overrides (optional)
+# Each provider picks a sensible default model per capability on its own -
+# these are NOT shared across capabilities, so overriding one (e.g. a text
+# model) never affects another (e.g. that same provider's image model).
+# Uncomment only the ones you want to override; every provider in play above
+# (AI_TEXT_PROVIDER / AI_IMAGE_PROVIDER / AI_AUDIO_PROVIDER) reads its own set.
+# The values below are laravel/ai's current defaults, shown as format examples -
+# they move with the package, so don't treat them as a contract.
+# OPENAI_TEXT_MODEL=gpt-5.4
+# OPENAI_IMAGE_MODEL=gpt-image-2
+# OPENAI_AUDIO_MODEL=gpt-4o-mini-tts
+# ANTHROPIC_TEXT_MODEL=claude-sonnet-5
+# GEMINI_TEXT_MODEL=gemini-3.6-flash
+# GEMINI_IMAGE_MODEL=gemini-3.1-flash-image-preview
+# GEMINI_AUDIO_MODEL=gemini-2.5-flash-preview-tts
+# XAI_TEXT_MODEL=grok-4.20-non-reasoning
+# XAI_IMAGE_MODEL=grok-imagine-image
+# OPENROUTER_TEXT_MODEL=anthropic/claude-sonnet-4.6
+# OPENROUTER_IMAGE_MODEL=google/gemini-3.1-flash-image-preview
+# OPENROUTER_AUDIO_MODEL=google/gemini-3.1-flash-tts-preview
+# ELEVENLABS_AUDIO_MODEL=eleven_multilingual_v2
+# GROQ_TEXT_MODEL=openai/gpt-oss-120b
+# MISTRAL_TEXT_MODEL=mistral-medium-latest
+# DEEPSEEK_TEXT_MODEL=deepseek-v4-flash
+# OLLAMA_TEXT_MODEL=llama3.1:8b
+# Ollama has no image/audio-capable driver in laravel/ai - text only.
+
 # ============================================
 # Stripe (Cashier — billing)
 # ============================================

docker/.env.docker.example

@@ -147,16 +147,55 @@ ANTHROPIC_API_KEY=
 GEMINI_API_KEY=
 OPENROUTER_API_KEY=
 ELEVENLABS_API_KEY=
+# Only needed if you point one of the AI_*_PROVIDER vars below at these providers.
+# XAI_API_KEY=
+# GROQ_API_KEY=
+# MISTRAL_API_KEY=
+# DEEPSEEK_API_KEY=
+# Ollama runs locally and needs no key — from inside Docker point it at the host, not localhost.
+# OLLAMA_URL=http://host.docker.internal:11434
+# Any OpenAI-compatible endpoint (LM Studio, vLLM, LocalAI, ...) via AI_TEXT_PROVIDER=openai-compatible.
+# It has no built-in default model, so OPENAI_COMPATIBLE_TEXT_MODEL is required for that provider.
+# OPENAI_COMPATIBLE_URL=
+# OPENAI_COMPATIBLE_API_KEY=
+# OPENAI_COMPATIBLE_TEXT_MODEL=
 
 # AI Provider Selection
-# text:  openai | anthropic | gemini | openrouter | xai | groq | mistral | deepseek | ...
+# text:  openai | anthropic | gemini | openrouter | xai | groq | mistral | deepseek | ollama | ...
-# image: openai | gemini | xai | openrouter
+# image: openai | gemini | xai | openrouter | ...
-# audio: openai | elevenlabs
+# audio: openai | elevenlabs | gemini | openrouter | ...
 # OpenRouter is a first-class laravel/ai provider (AI_TEXT_PROVIDER=openrouter + OPENROUTER_API_KEY).
 AI_TEXT_PROVIDER=openai
 AI_IMAGE_PROVIDER=openai
 AI_AUDIO_PROVIDER=elevenlabs
 
+# AI Model Overrides (optional)
+# Each provider picks a sensible default model per capability on its own -
+# these are NOT shared across capabilities, so overriding one (e.g. a text
+# model) never affects another (e.g. that same provider's image model).
+# Uncomment only the ones you want to override; every provider in play above
+# (AI_TEXT_PROVIDER / AI_IMAGE_PROVIDER / AI_AUDIO_PROVIDER) reads its own set.
+# The values below are laravel/ai's current defaults, shown as format examples -
+# they move with the package, so don't treat them as a contract.
+# OPENAI_TEXT_MODEL=gpt-5.4
+# OPENAI_IMAGE_MODEL=gpt-image-2
+# OPENAI_AUDIO_MODEL=gpt-4o-mini-tts
+# ANTHROPIC_TEXT_MODEL=claude-sonnet-5
+# GEMINI_TEXT_MODEL=gemini-3.6-flash
+# GEMINI_IMAGE_MODEL=gemini-3.1-flash-image-preview
+# GEMINI_AUDIO_MODEL=gemini-2.5-flash-preview-tts
+# XAI_TEXT_MODEL=grok-4.20-non-reasoning
+# XAI_IMAGE_MODEL=grok-imagine-image
+# OPENROUTER_TEXT_MODEL=anthropic/claude-sonnet-4.6
+# OPENROUTER_IMAGE_MODEL=google/gemini-3.1-flash-image-preview
+# OPENROUTER_AUDIO_MODEL=google/gemini-3.1-flash-tts-preview
+# ELEVENLABS_AUDIO_MODEL=eleven_multilingual_v2
+# GROQ_TEXT_MODEL=openai/gpt-oss-120b
+# MISTRAL_TEXT_MODEL=mistral-medium-latest
+# DEEPSEEK_TEXT_MODEL=deepseek-v4-flash
+# OLLAMA_TEXT_MODEL=llama3.1:8b
+# Ollama has no image/audio-capable driver in laravel/ai - text only.
+
 # Telemetry — disabled by default in Docker dev.
 NIGHTWATCH_ENABLED=false
 NIGHTWATCH_TOKEN=