docs: refactor TTS provider setup documentation

docs-site/docs/configure/tts-provider-guides/custom-openai.md

@@ -1,42 +0,0 @@
----
-title: Custom OpenAI
----
-
-Use any custom OpenAI-compatible TTS service with OpenReader.
-
-Use this integration when your endpoint is not directly covered by built-in dropdown defaults.
-
-Known compatible examples include Kokoro-FastAPI, KittenTTS-FastAPI, and Orpheus-FastAPI.
-
-## Provider
-
-- Provider: `Custom OpenAI-Like`
-- `API_BASE`: required (your service base URL)
-- `API_KEY`: set if required by your service
-
-Custom providers should expose:
-
-- `GET /v1/audio/voices`
-- `POST /v1/audio/speech`
-
-## OpenReader setup
-
-1. In OpenReader Settings, choose provider `Custom OpenAI-Like`.
-2. Set `API_BASE` to your service base URL (typically ending with `/v1`).
-3. Set `API_KEY` if your service requires authentication.
-4. Choose a model and voice supported by your backend.
-
-## Notes
-
-:::warning Compatibility required
-Custom providers must implement OpenAI-compatible TTS endpoints, including `GET /v1/audio/voices` and `POST /v1/audio/speech`.
-:::
-
-:::info Voice troubleshooting
-If voices do not load, verify the `/v1/audio/voices` response shape and that the endpoint is reachable from the OpenReader server.
-:::
-
-## References
-
-- [TTS Providers](../tts-providers)
-- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/docs/configure/tts-provider-guides/deepinfra.md

@@ -1,33 +1,36 @@
 ---
-title: Deepinfra
+title: DeepInfra
 ---
 
-Use Deepinfra as a hosted OpenAI-compatible TTS provider.
+Use DeepInfra's hosted TTS models as your provider.
 
-## Provider
+## Setup
 
-- Provider: `Deepinfra`
+**Environment variables (recommended for deployment):**
-- Default endpoint: `https://api.deepinfra.com/v1/openai` (auto-filled)
-- `API_KEY`: required for authenticated DeepInfra usage
 
-## OpenReader setup
+```env
+API_BASE=https://api.deepinfra.com/v1/openai
+API_KEY=your-deepinfra-key
+NEXT_PUBLIC_DEFAULT_TTS_PROVIDER=deepinfra
+```
 
-1. In OpenReader Settings, choose provider `Deepinfra`.
+**Or in-app via Settings → TTS Provider:**
-2. Keep the default `API_BASE`.
+
-3. Set `API_KEY`.
+1. Set provider to `Deepinfra`.
-4. Choose your model and voice.
+2. The base URL is pre-filled, no changes needed.
+3. Enter your `API_KEY`.
+4. Choose a model and voice.
+
+Settings modal values override env vars. See [TTS Providers](../tts-providers) for how the two layers interact.
 
 ## Notes
 
-:::tip Built-in endpoint
+- Available models include `hexgrad/Kokoro-82M` and `canopylabs/orpheus-3b-0.1-ft`.
-`Deepinfra` is a built-in provider, so OpenReader auto-fills the default `API_BASE`.
+- Without an API key, only the free-tier model (`hexgrad/Kokoro-82M`) is shown in the dropdown.
-:::
+- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
-
-:::info Model support
-DeepInfra exposes multiple TTS models, including Kokoro-family options.
-:::
 
 ## References
 
+- [DeepInfra TTS models](https://deepinfra.com/models/text-to-speech)
 - [TTS Providers](../tts-providers)
 - [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/docs/configure/tts-provider-guides/kitten-tts-fastapi.md

@@ -2,16 +2,9 @@
 title: KittenTTS-FastAPI
 ---
 
-Use [KittenTTS-FastAPI](https://github.com/richardr1126/KittenTTS-FastAPI) as an OpenAI-compatible TTS backend for OpenReader.
+Run [KittenTTS-FastAPI](https://github.com/richardr1126/KittenTTS-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider. Lightweight and CPU-friendly.
 
-## Provider
+## Run KittenTTS
-
-- Provider: `Custom OpenAI-Like`
-- Typical model: `kitten-tts`
-- `API_BASE`: required (usually your KittenTTS URL ending with `/v1`)
-- `API_KEY`: set only if your deployment requires one
-
-## Run KittenTTS (CPU)
 
 ```bash
 docker run -it --rm \
@@ -21,23 +14,24 @@ docker run -it --rm \
   ghcr.io/richardr1126/kittentts-fastapi-cpu
 ```
 
-## OpenReader setup
+## Connect to OpenReader
 
-1. Start your KittenTTS-FastAPI server.
+**Environment variables (recommended for deployment):**
-2. In OpenReader Settings, choose provider `Custom OpenAI-Like`.
-3. Set `API_BASE` to your KittenTTS base URL (typically ending with `/v1`).
-4. Set `API_KEY` only if your deployment requires one.
-5. Choose model `kitten-tts` (or another model exposed by your deployment).
 
-## Notes
+```env
+API_BASE=http://kittentts-fastapi:8005/v1
+```
 
-:::info OpenAI-compatible API
+> Use `kittentts-fastapi` if that's the container name, or `host.docker.internal` if not.
-OpenReader expects OpenAI-compatible audio endpoints when using KittenTTS through `Custom OpenAI-Like`.
-:::
 
-:::tip Endpoint shape
+**Or in-app via Settings → TTS Provider:**
-Use an `API_BASE` that points at the KittenTTS API root (typically ending with `/v1`).
+
-:::
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your KittenTTS endpoint (e.g. `http://kittentts-fastapi:8005/v1`).
+3. Leave `API_KEY` blank unless your deployment requires one.
+4. Choose model `kitten-tts` (or the model your deployment exposes).
+
+Settings modal values override env vars. See [TTS Providers](../tts-providers) for how the two layers interact.
 
 ## References
 

docs-site/docs/configure/tts-provider-guides/kokoro-fastapi.md

@@ -2,20 +2,15 @@
 title: Kokoro-FastAPI
 ---
 
-You can run the Kokoro TTS API server directly with Docker.
+Run [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider.
 
 :::warning
 For Kokoro issues and support, use the upstream repository: [remsky/Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI).
 :::
 
-## Provider
+## Run Kokoro
 
-- Provider: `Custom OpenAI-Like`
+**CPU:**
-- Typical model: `Kokoro`
-- `API_BASE`: required (typically your Kokoro URL ending with `/v1`)
-- `API_KEY`: set only if your deployment requires one
-
-## Run Kokoro (CPU)
 
 ```bash
 docker run --name kokoro-tts \
@@ -32,7 +27,7 @@ docker run --name kokoro-tts \
   ghcr.io/remsky/kokoro-fastapi-cpu:v0.2.4
 ```
 
-## Run Kokoro (GPU)
+**GPU (NVIDIA):**
 
 ```bash
 docker run --name kokoro-tts \
@@ -47,19 +42,24 @@ docker run --name kokoro-tts \
   ghcr.io/remsky/kokoro-fastapi-gpu:v0.2.4
 ```
 
-## OpenReader setup
+## Connect to OpenReader
 
-1. Start Kokoro using either the CPU or GPU image.
+**Environment variables (recommended for deployment):**
-2. In OpenReader Settings, choose provider `Custom OpenAI-Like`.
-3. Set `API_BASE` to your Kokoro endpoint (for Docker Compose, commonly `http://kokoro-tts:8880/v1`).
-4. Set `API_KEY` only if your deployment requires one.
-5. Choose model `Kokoro`.
 
-## Notes
+```env
+API_BASE=http://kokoro-tts:8880/v1
+```
 
-:::tip Runtime guidance
+> Use `kokoro-tts` if that's the container name, or `host.docker.internal` if not.
-GPU mode requires NVIDIA Docker support and is best on NVIDIA hardware. CPU mode is a good default on Apple Silicon and modern x86 CPUs.
+
-:::
+**Or in-app via Settings → TTS Provider:**
+
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your Kokoro endpoint (e.g. `http://kokoro-tts:8880/v1`).
+3. Leave `API_KEY` blank unless your deployment requires one.
+4. Choose model `Kokoro`.
+
+Settings modal values override env vars. See [TTS Providers](../tts-providers) for how the two layers interact.
 
 ## References
 

docs-site/docs/configure/tts-provider-guides/openai.md

@@ -2,32 +2,34 @@
 title: OpenAI
 ---
 
-Use OpenAI directly as an OpenAI-compatible TTS provider.
+Use the OpenAI TTS API as your provider.
 
-## Provider
+## Setup
 
-- Provider: `OpenAI`
+**Environment variables (recommended for deployment):**
-- Default endpoint: `https://api.openai.com/v1` (auto-filled)
-- `API_KEY`: required for OpenAI access
 
-## OpenReader setup
+```env
+API_BASE=https://api.openai.com/v1
+API_KEY=sk-...
+NEXT_PUBLIC_DEFAULT_TTS_PROVIDER=openai
+```
 
-1. In OpenReader Settings, choose provider `OpenAI`.
+**Or in-app via Settings → TTS Provider:**
-2. Keep the default `API_BASE`.
+
-3. Set `API_KEY`.
+1. Set provider to `OpenAI`.
-4. Choose your model and voice.
+2. The base URL is pre-filled, no changes needed.
+3. Enter your `API_KEY`.
+4. Choose a model and voice.
+
+Settings modal values override env vars. See [TTS Providers](../tts-providers) for how the two layers interact.
 
 ## Notes
 
-:::tip Built-in endpoint
+- Models: `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`
-`OpenAI` is a built-in provider, so OpenReader auto-fills the default `API_BASE`.
+- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
-:::
-
-:::info Server-side requests
-OpenReader sends TTS requests from the server runtime, not directly from the browser.
-:::
 
 ## References
 
+- [OpenAI TTS pricing](https://platform.openai.com/docs/pricing#transcription-and-speech)
 - [TTS Providers](../tts-providers)
 - [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/docs/configure/tts-provider-guides/orpheus-fastapi.md

@@ -2,32 +2,30 @@
 title: Orpheus-FastAPI
 ---
 
-Use Orpheus-FastAPI as an OpenAI-compatible TTS backend for OpenReader.
+Run [Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider.
 
-## Provider
+## Run Orpheus
 
-- Provider: `Custom OpenAI-Like`
+Refer to the upstream repository for Docker instructions: [Lex-au/Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI).
-- Typical model: `Orpheus`
-- `API_BASE`: required (usually your Orpheus URL ending with `/v1`)
-- `API_KEY`: set only if your deployment requires one
 
-## OpenReader setup
+## Connect to OpenReader
 
-1. Start your Orpheus-FastAPI server.
+**Environment variables (recommended for deployment):**
-2. In OpenReader Settings, choose provider `Custom OpenAI-Like`.
-3. Set `API_BASE` to your Orpheus base URL (typically ending with `/v1`).
-4. Set `API_KEY` only if your Orpheus deployment requires one.
-5. Choose model `Orpheus` (or another model exposed by your deployment).
 
-## Notes
+```env
+API_BASE=http://orpheus:8000/v1
+```
 
-:::info OpenAI-compatible API
+> Use the container name if that's how it's named, or `host.docker.internal` if not.
-OpenReader expects OpenAI-compatible audio endpoints when using Orpheus through `Custom OpenAI-Like`.
-:::
 
-:::tip Endpoint shape
+**Or in-app via Settings → TTS Provider:**
-Use an `API_BASE` that points at the Orpheus API root (typically ending with `/v1`).
+
-:::
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your Orpheus endpoint (e.g. `http://orpheus:8000/v1`).
+3. Leave `API_KEY` blank unless your deployment requires one.
+4. Choose model `Orpheus` (or the model your deployment exposes).
+
+Settings modal values override env vars. See [TTS Providers](../tts-providers) for how the two layers interact.
 
 ## References
 

docs-site/docs/configure/tts-provider-guides/other.md

@@ -0,0 +1,45 @@
+---
+title: Other
+---
+
+Use any OpenAI-compatible TTS service with OpenReader, including self-hosted servers not covered by a dedicated guide.
+
+## Requirements
+
+Your service must expose these endpoints:
+
+- `GET /v1/audio/voices`
+- `POST /v1/audio/speech`
+
+Known compatible implementations: [Kokoro-FastAPI](./kokoro-fastapi), [KittenTTS-FastAPI](./kitten-tts-fastapi), [Orpheus-FastAPI](./orpheus-fastapi).
+
+## Setup
+
+**Environment variables (recommended for deployment):**
+
+```env
+API_BASE=http://your-tts-server/v1
+API_KEY=optional-key-if-required
+```
+
+**Or in-app via Settings → TTS Provider:**
+
+1. Set provider to `Custom OpenAI-Like`.
+2. Set `API_BASE` to your service's base URL (typically ending in `/v1`).
+3. Set `API_KEY` if your service requires authentication.
+4. Choose a model and voice supported by your backend.
+
+Settings modal values override env vars. See [TTS Providers](../tts-providers) for how the two layers interact.
+
+:::warning TTS requests are server-side
+`API_BASE` must be reachable from the **Next.js server**, not just the browser. In Docker, use container names or `host.docker.internal`.
+:::
+
+## Troubleshooting
+
+If voices don't load, check that `/v1/audio/voices` is reachable from the server and returns a valid response shape.
+
+## References
+
+- [TTS Providers](../tts-providers)
+- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)

docs-site/docs/configure/tts-providers.md

@@ -2,79 +2,45 @@
 title: TTS Providers
 ---
 
-import Tabs from '@theme/Tabs';
+OpenReader routes all TTS requests through the Next.js server to an OpenAI-compatible API. You choose your provider and credentials in one of two places:
-import TabItem from '@theme/TabItem';
 
-OpenReader supports OpenAI-compatible TTS providers through a common API shape.
+**Environment variables**: set in your `.env` or `docker-compose.yml` as server-level defaults. Applied when the user has no saved Settings.
 
-:::tip
+**Settings modal** (Settings > TTS Provider): stored in the browser and sent with every TTS request. **Overrides env vars.**
-If you are running a self-hosted TTS server (Kokoro/KittenTTS/Orpheus/etc.), use **Custom OpenAI-Like** in Settings.
+
+:::note
+Set env vars as deployment-level defaults. Users (or you, in a single-user setup) can then change the provider, base URL, and API key from the Settings modal without redeploying. Clearing the Settings fields falls back to the env var defaults.
 :::
 
-## Quick Setup by Provider
+## Providers
 
-<Tabs groupId="tts-provider-setup">
+- **OpenAI**: Cloud. Base URL pre-filled (`https://api.openai.com/v1`). API key required.
-  <TabItem value="openai" label="OpenAI" default>
+- **Deepinfra**: Cloud. Base URL pre-filled (`https://api.deepinfra.com/v1/openai`). API key required.
+- **Custom OpenAI-Like**: Self-hosted or any custom endpoint. `API_BASE` must be set manually (typically ending in `/v1`). API key optional.
 
-1. In Settings, choose provider: `OpenAI`.
+For `OpenAI` and `Deepinfra` you only need to supply an API key. For `Custom OpenAI-Like` you must also set `API_BASE`.
-2. Keep the default `API_BASE` (auto-filled).
-3. Set `API_KEY` to your OpenAI key.
-4. Choose model/voice.
 
-  </TabItem>
+## Custom provider requirements
-  <TabItem value="deepinfra" label="DeepInfra">
 
-1. In Settings, choose provider: `Deepinfra`.
+Self-hosted or custom providers must expose OpenAI-compatible audio endpoints:
-2. Keep the default `API_BASE` (auto-filled).
-3. Set `API_KEY` to your DeepInfra key.
-4. Choose model/voice.
-
-  </TabItem>
-  <TabItem value="custom" label="Custom OpenAI-Like">
-
-1. In Settings, choose provider: `Custom OpenAI-Like`.
-2. Set `API_BASE` to your endpoint (example: `http://host.docker.internal:8880/v1`).
-3. Set `API_KEY` if your provider requires one.
-4. Choose model/voice.
-
-  </TabItem>
-</Tabs>
-
-## Provider Dropdown Behavior
-
-In Settings, provider options include:
-
-- `OpenAI`
-- `Deepinfra`
-- `Custom OpenAI-Like` (Kokoro, KittenTTS-FastAPI, Orpheus, and other OpenAI-compatible endpoints)
-
-`API_BASE` guidance:
-
-- `OpenAI` and `Deepinfra` auto-fill default endpoints.
-- `Custom OpenAI-Like` requires setting `API_BASE` manually.
-
-:::info OpenAI-Compatible API Shape
-Custom providers should expose:
 
 - `GET /v1/audio/voices`
 - `POST /v1/audio/speech`
+
+:::warning TTS requests are server-side
+TTS requests originate from the **Next.js server**, not the browser. `API_BASE` must be reachable from the server runtime. In Docker, use container names or `host.docker.internal` rather than `localhost`.
 :::
 
-:::warning Server-Reachable API Base
+## Provider guides
-TTS requests are sent from the Next.js server, not directly from the browser. `API_BASE` must be reachable from the server runtime.
-:::
-
-## Provider Guides
 
 - [Kokoro-FastAPI](./tts-provider-guides/kokoro-fastapi)
 - [KittenTTS-FastAPI](./tts-provider-guides/kitten-tts-fastapi)
 - [Orpheus-FastAPI](./tts-provider-guides/orpheus-fastapi)
 - [DeepInfra](./tts-provider-guides/deepinfra)
 - [OpenAI](./tts-provider-guides/openai)
-- [Custom OpenAI-Like](./tts-provider-guides/custom-openai)
+- [Other](./tts-provider-guides/other)
 
-## Related Configuration
+## Related
 
 - [TTS Environment Variables](../reference/environment-variables#tts-provider-and-request-behavior)
 - [TTS Rate Limiting](./tts-rate-limiting)
-- [Auth](./auth)

docs-site/docs/introduction.md

@@ -32,7 +32,7 @@ It supports multiple TTS providers including OpenAI, DeepInfra, and custom OpenA
 - 🗂️ **Flexible Storage and Database Modes** with embedded defaults or external S3/Postgres
 - 🚀 **Production-ready Server Behavior** with TTS caching/retries/rate limits and startup migrations
 - 🎨 **Customizable Experience**
-  - Theme, TTS, and document handling controls
+  - 13 built-in themes (light and dark palettes), TTS, and document handling controls
 
 ## 🧭 Key Docs
 

docs-site/docs/reference/environment-variables.md

@@ -60,18 +60,20 @@ This is the single reference page for OpenReader environment variables.
 
 ### API_BASE
 
-Base URL for OpenAI-compatible TTS API requests.
+Server-level default base URL for OpenAI-compatible TTS API requests.
 
 - Example: `http://host.docker.internal:8880/v1`
-- Can be overridden per request from UI settings
+- Used when no `API_BASE` is set in the user's Settings modal
+- If the user sets `API_BASE` in **Settings → TTS Provider**, that value takes precedence
 - Related docs: [TTS Providers](../configure/tts-providers)
 
 ### API_KEY
 
-Default API key for TTS provider requests.
+Server-level default API key for TTS provider requests.
 
-- Example: `none` or your provider token
+- Example: your provider token, or omit if the provider doesn't require auth
-- Can be overridden by request headers from app settings
+- Used when no `API_KEY` is set in the user's Settings modal
+- If the user sets `API_KEY` in **Settings → TTS Provider**, that value takes precedence
 - Related docs: [TTS Providers](../configure/tts-providers)
 
 ### TTS_CACHE_MAX_SIZE_BYTES

docs-site/sidebars.ts

@@ -25,7 +25,7 @@ const sidebars: SidebarsConfig = {
             'configure/tts-provider-guides/orpheus-fastapi',
             'configure/tts-provider-guides/deepinfra',
             'configure/tts-provider-guides/openai',
-            'configure/tts-provider-guides/custom-openai',
+            'configure/tts-provider-guides/other',
           ],
         },
         {