docs: clarify custom provider configuration

[LING71671]

Summary

• document how existing provider IDs cover custom DeepSeek-compatible endpoints and generic OpenAI-compatible gateways
• add concrete README and config.example.toml examples for DeepSeek-compatible and gateway base_url/model overrides
• add a native /config base_url hint so the TUI points users toward saved user config instead of project overlays

Closes #2247

Verification

• git diff --check
• cargo fmt --all --check
• cargo test -p codewhale-tui --bin codewhale-tui config_view --all-features

Greptile Summary

This is a docs-only PR that clarifies how existing provider IDs (deepseek, openai) can be reused for custom DeepSeek-compatible endpoints and generic OpenAI-compatible gateways, rather than requiring users to invent new provider names.

• Adds a new "Custom DeepSeek-Compatible Endpoints" section to docs/PROVIDERS.md with concrete TOML examples and a note that project overlays cannot override provider/api_key/base_url.
• Extends README.md with a CLI quickstart snippet for custom endpoints and a short prose paragraph reinforcing the user-config restriction.
• Adds commented-out gateway/custom-endpoint examples in config.example.toml and a new base_url hint in the TUI /config editor.

Confidence Score: 4/5

Documentation-only changes; no executable logic is altered beyond adding a single hint string in the TUI config view.

All changes are in Markdown, TOML comments, and a single Rust string constant. The TUI hint for base_url mixes an imperative instruction with example URLs, making it inconsistent with every other hint in the same function. The config.example.toml now has two commented base_url/model pairs in [providers.deepseek] without a clear mutual-exclusion note, which could mislead users who uncomment both. Neither issue affects runtime behaviour.

crates/tui/src/tui/views/mod.rs (hint text format) and config.example.toml (duplicate commented key pairs).

Important Files Changed

Filename	Overview
crates/tui/src/tui/views/mod.rs	Adds a base_url hint to config_hint_for_key; the hint text blends an instruction ("save user config") with example URLs, inconsistent with the format every other hint in this function uses.
config.example.toml	Adds documentation comments for custom provider endpoint overrides; introduces duplicate commented-out base_url/model keys in [providers.deepseek] that could confuse users who uncomment them simultaneously.
docs/PROVIDERS.md	Adds a clear "Custom DeepSeek-Compatible Endpoints" section with worked TOML examples and an explanation of the project-overlay restriction; content is accurate and well-structured.
README.md	Adds a CLI quickstart example for custom DeepSeek-compatible endpoints and a prose paragraph explaining the user-config restriction; content is consistent with PROVIDERS.md.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User wants custom endpoint] --> B{DeepSeek-compatible?}
    B -->|Yes| C[provider = deepseek]
    B -->|No - generic OpenAI| D[provider = openai]
    B -->|No - local runtime| E[provider = vllm / sglang / ollama]

    C --> F[Set providers.deepseek.base_url + model\nor DEEPSEEK_BASE_URL + DEEPSEEK_MODEL]
    D --> G[Set providers.openai.base_url + model\nor OPENAI_BASE_URL + OPENAI_MODEL]
    E --> H[Set provider-specific BASE_URL + MODEL env vars]

    F --> I{Where to save?}
    G --> I
    H --> I

    I -->|Allowed| J["~/.codewhale/config.toml\nor process env vars"]
    I -->|Blocked| K["workspace/.codewhale/config.toml\n(project overlay — provider/api_key/base_url denied)"]

    J --> L[TUI /config base_url hint now points here]

Loading

_{Reviews (1): Last reviewed commit: "docs: clarify custom provider configurat..." | Re-trigger Greptile}

Greptile also left 2 inline comments on this PR.

[gemini-code-assist]

Code Review

This pull request adds comprehensive documentation and configuration examples for using custom DeepSeek-compatible endpoints and generic OpenAI-compatible gateways. It also introduces a configuration hint for the base_url key in the TUI views. The reviewer suggests simplifying the base_url configuration hint by removing the redundant and inconsistent "save user config; " prefix to match the style of other hints.

[gemini-code-assist]

The prefix save user config; in the hint is grammatically confusing and inconsistent with the other hints in config_hint_for_key, which only describe the expected value format or examples. Since the scope of base_url is already displayed as SAVED in the TUI table, this prefix is redundant. Removing it makes the hint cleaner and more consistent.

Suggested change

	"base_url" => "save user config; e.g. https://api.deepseek.com/beta or https://gateway/v1",
	"base_url" => "e.g. https://api.deepseek.com/beta or https://gateway/v1",

[greptile-apps]

The base_url hint mixes an imperative instruction ("save user config") with example URL values, which is inconsistent with every other entry in this function (all of which show only valid value formats or examples). A user typing in the TUI field would see "save user config; e.g. …" as the hint and might be confused about what to actually enter.

Suggested change

	"base_url" => "save user config; e.g. https://api.deepseek.com/beta or https://gateway/v1",
	"base_url" => "https://api.deepseek.com/beta | https://gateway/v1 (set in user config)",

[greptile-apps]

There are now two separate commented base_url and model lines inside [providers.deepseek] — the original defaults and the new custom-endpoint examples. If a user naively uncomments both groups, TOML parsers that enforce unique keys will error; others will silently use the last value. Adding a clear mutual-exclusion note or restructuring so only one pair appears at a time would prevent the confusion.

Suggested change

	# api_key = "YOUR_DEEPSEEK_API_KEY"
	# base_url = "https://api.deepseek.com/beta"
	# model = "deepseek-v4-pro"
	# Custom DeepSeek-compatible example:
	# base_url = "https://your-provider.example/v1"
	# model = "deepseek-ai/DeepSeek-V4-Pro"
	# http_headers = { "X-Model-Provider-Id" = "your-model-provider" } # optional custom request headers
	# api_key = "YOUR_DEEPSEEK_API_KEY"
	# base_url = "https://api.deepseek.com/beta" # default DeepSeek platform (beta features)
	# model = "deepseek-v4-pro"
	# --- OR: custom DeepSeek-compatible endpoint (pick one base_url/model pair) ---
	# base_url = "https://your-provider.example/v1"
	# model = "deepseek-ai/DeepSeek-V4-Pro"
	# http_headers = { "X-Model-Provider-Id" = "your-model-provider" } # optional custom request headers