README update

README.md

@@ -4,6 +4,7 @@
 - Secrets live in **.env** at the repo root (NOT committed).
 - Commit **.env.example**. Users copy it to `.env` and fill in their values.
 - We also include **.gitignore** to keep `.env` and data paths out of git.
+- `.env.example` now includes variables for Meilisearch **and** OpenWebUI, including `OPENWEBUI_URL`, `OPENWEBUI_API_KEY`, and `OPENWEBUI_KB_ID`.
 
 ## Quick start
 ```bash
@@ -12,7 +13,9 @@ docker compose up -d --build
 # UI:   http://<host>:8088
 # Meili: http://<host>:7700
 ```
-The worker reaches OpenWebUI at `$OPENWEBUI_URL` (default: http://host.docker.internal:3003).
+The worker reaches OpenWebUI at `$OPENWEBUI_URL` (default: http://host.docker.internal:3003 on macOS/Windows, or http://openwebui:3003 on Linux Docker networks).
+
+Note: `.env.example` includes placeholders for both **Meili** and **OpenWebUI** configuration. Be sure to set `OPENWEBUI_URL` to point to your OpenWebUI container accordingly.
 
 ## Components Overview
 
@@ -31,6 +34,10 @@ The worker reaches OpenWebUI at `$OPENWEBUI_URL` (default: http://host.docker.in
 - `WHISPER_PRECISION`: Precision setting for Whisper inference (`float32` or `float16`).
 - `WHISPER_LANGUAGE`: Language code for Whisper to use during transcription (e.g., `en` for English).
 - `YTDLP_COOKIES`: Path to YouTube-DL cookies file for accessing age-restricted or private videos.
+- `OPENWEBUI_URL`: Base URL of the OpenWebUI API (default depends on platform).
+- `OPENWEBUI_API_KEY`: API key for authenticating PodX workers with OpenWebUI.
+- `OPENWEBUI_KB_NAME`: Human-readable Knowledge Base name to attach documents to.
+- `OPENWEBUI_KB_ID`: Fixed UUID of the Knowledge Base (avoids duplicate KBs on restart).
 
 ## RSS Ingestion
 
@@ -120,3 +127,46 @@ OPENWEBUI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 ```
 
 If the key is ever leaked, revoke it in OpenWebUI and generate a new one.
+
+### 3. Knowledge Base ID
+To avoid creating duplicate Knowledge Bases on every PodX restart, use a fixed Knowledge Base ID:
+
+- Run the command below to list your OpenWebUI Knowledge Bases and their IDs:
+
+```bash
+./scripts/podx-tools.sh owui-kbs
+```
+
+- Copy the UUID of the desired Knowledge Base and set it in your `.env`:
+
+```dotenv
+OPENWEBUI_KB_ID=your-knowledge-base-uuid-here
+```
+
+This ensures PodX attaches documents consistently to the same Knowledge Base.
+
+## Troubleshooting
+
+### Common errors and fixes
+
+- **`400: The content provided is empty`**  
+  This usually means the transcript file was empty, binary, or mis-encoded. Verify that the `.txt` files really contain text and are not corrupted.
+
+- **Duplicate Knowledge Base creation**  
+  Fix this by setting `OPENWEBUI_KB_ID` in your `.env` after running `./scripts/podx-tools.sh owui-kbs` to get the fixed KB ID.
+
+- **Worker cannot connect to OpenWebUI (`curl: Failed to connect to localhost:3003`)**  
+  Ensure `OPENWEBUI_URL` is correctly set to `http://host.docker.internal:3003` on macOS/Windows or `http://openwebui:3003` on Linux Docker networks.
+
+- **Attaching files silently fails or shows `pending` forever**  
+  Check `podx-worker` logs for errors, make sure the `podx-worker-transcribe` is running for audio transcription tasks, and verify that `OPENWEBUI_API_KEY` is valid.
+
+- **Multiple Knowledge Bases with the same name**  
+  Resolve this explicitly using the `owui-kb-resolve` command to get the fixed Knowledge Base ID.
+
+### Worker separation
+
+PodX runs two types of workers for better resource management:
+
+- `podx-worker`: Handles general tasks such as scanning, metadata fetching, and indexing.
+- `podx-worker-transcribe`: Dedicated to Whisper transcription jobs, isolating resource-intensive audio processing to optimize performance.