docs: clarify free-provider model refresh outcomes (#9087)

* docs: document provider model refresh fix

Document the verified live-model refresh path for stale provider catalogs,
record the current Pollinations anonymous-access limitation, and sync the
provider-count references after regenerating the provider reference.

Co-Authored-By: Oz <oz-agent@warp.dev>

* docs: note codex local env and mac path

Co-Authored-By: Oz <oz-agent@warp.dev>

---------

Co-authored-by: Oz <oz-agent@warp.dev>

docs/guides/CODEX-CLI-CONFIGURATION.md

@@ -1,7 +1,7 @@
 ---
 title: "Codex CLI — Configuration with OmniRoute"
 version: 3.8.49
-lastUpdated: 2026-07-26
+lastUpdated: 2026-08-01
 ---
 
 # Codex CLI — Configuration with OmniRoute
@@ -36,6 +36,35 @@ wire_api             = "responses"
 export OMNIROUTE_API_KEY="<YOUR_KEY>"
 ```
 
+### macOS: Codex bundled inside the ChatGPT app
+
+If you installed Codex through the ChatGPT desktop app, the `codex` binary may
+exist only inside the app bundle and not yet be on your shell `PATH`. Add the
+resources directory to your shell startup file:
+
+```bash
+export PATH="/Applications/ChatGPT.app/Contents/Resources:$PATH"
+```
+
+Open a new shell, then verify:
+
+```bash
+command -v codex
+codex --version
+```
+
+### Local unauthenticated OmniRoute: placeholder key is enough
+
+Codex validates that the environment variable named by `env_key` exists
+**before** the first request leaves the CLI. If your **local** OmniRoute
+instance does not require auth, any non-empty placeholder works:
+
+```bash
+export OMNIROUTE_API_KEY="${OMNIROUTE_API_KEY:-local}"
+```
+
+Use a real key instead when your OmniRoute server is protected or remote.
+
 > **Common host options**
 >
 > | Access        | URL                           |
@@ -504,6 +533,12 @@ Verify the model exists in OmniRoute with the correct prefix. Use `omniroute mod
 **`Authentication error`**
 Confirm `OMNIROUTE_API_KEY` is exported: `echo $OMNIROUTE_API_KEY`.
 
+**`ERROR: Missing environment variable: OMNIROUTE_API_KEY`**
+Codex validates that the env var exists before making the first request. Export
+a real key for protected servers, or a non-empty placeholder such as
+`OMNIROUTE_API_KEY=local` when your **local** OmniRoute instance does not
+require auth. Restart the shell if you added it to `~/.bashrc` or `~/.zshrc`.
+
 **`Connection refused`**
 Verify OmniRoute is running and the `base_url` host/port is correct for your network (local vs Tailscale vs VPS).
 

docs/guides/USER_GUIDE.md

@@ -565,6 +565,8 @@ For the full environment variable reference, see the [README](../README.md).
 <summary><b>View all available models</b></summary>
 
 > The list below is curated from `open-sse/config/providerRegistry.ts` for v3.8.0. Cloud catalogs (Gemini, OpenRouter, etc.) are synced dynamically — for the full live catalog open **Dashboard → Providers → [provider] → Available Models** or call `GET /api/models/catalog`.
+>
+> If a provider's built-in list has drifted, use **Import from /models** on that page (or enable **Auto-Sync**) to pull the live upstream catalog. This was verified in v3.8.50 for LLM7.io (`gemini-3.1-flash-lite`) and UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`); Pollinations anonymous access remained upstream-limited during the same test pass.
 
 **Claude Code (`cc/`)** — Pro/Max OAuth: `cc/claude-opus-4-8`, `cc/claude-opus-4-7`, `cc/claude-opus-4-6`, `cc/claude-opus-4-5-20251101`, `cc/claude-sonnet-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
 

src/shared/constants/providers/apikey/gateways.ts

@@ -269,7 +269,8 @@ export const APIKEY_PROVIDERS_GATEWAYS = {
     hasFree: true,
     freeNote: "Free forever — no signup, no credit card. OpenAI-compatible endpoints.",
     passthroughModels: true,
-    authHint: "No auth required. API accepts any non-empty string as key for identification.",
+    authHint:
+      "No auth required. API accepts any non-empty string as key for identification. If older built-in models return 404, use Available Models → Import from /models or Auto-Sync; verified live model: solidrust/Hermes-3-Llama-3.1-8B-AWQ.",
   },
   hackclub: {
     id: "hackclub",
@@ -388,6 +389,8 @@ export const APIKEY_PROVIDERS_GATEWAYS = {
     website: "https://llm7.io",
     hasFree: true,
     freeNote: "No signup required - 2 req/s, 20 RPM, 100 req/hr free tier",
+    authHint:
+      "Use any non-empty key (for example 'unused'). If older built-in models return model_unavailable, use Available Models → Import from /models or Auto-Sync; verified live model: gemini-3.1-flash-lite.",
     apiHint:
       "Works without API key (use 'unused' as key). Get free token at token.llm7.io for higher limits.",
   },

src/shared/constants/providers/apikey/specialty-media.ts

@@ -50,6 +50,8 @@ export const APIKEY_PROVIDERS_SPECIALTY = {
     website: "https://pollinations.ai",
     hasFree: true,
     anonymousFallback: true,
+    authHint:
+      "Anonymous/keyless access to the documented free models is best-effort. Local v3.8.50 verification (2026-07-31) returned 401 via OmniRoute and Cloudflare 1010 on direct upstream probes from the same network. Premium models still require a Pollinations API key from enter.pollinations.ai.",
     freeNote:
       "Free keyless tier: openai, openai-fast, openai-large, qwen-coder, mistral, deepseek, grok, gemini-flash-lite-3.1, perplexity-fast, perplexity-reasoning. Premium models (claude, gemini, midijourney) require a Pollinations API key from enter.pollinations.ai.",
   },