docs: add HuggingFace cache troubleshooting to README

- Document HF_HOME environment variable for writable cache
- Add systemd service permission guidance for /tmp paths
- Troubleshooting steps for read-only file system errors

README.md

@@ -253,6 +253,27 @@ Test any combination of voice and effects before committing:
 - Ensure the reference audio is clear with minimal background noise
 - Try a longer reference clip (5-10 seconds)
 
+### HuggingFace cache read-only error
+If you see errors like `OSError: [Errno 30] Read-only file system` when the bot tries to download the TTS model:
+
+1. **Set a writable cache directory**: Add to your `.env` file:
+   ```env
+   HF_HOME=/tmp/huggingface
+   ```
+
+2. **Create and set permissions** on the directory:
+   ```bash
+   sudo mkdir /tmp/huggingface
+   sudo chown -R $USER:$USER /tmp/huggingface
+   ```
+
+3. **If using systemd service**: Ensure the service has write access to `/tmp` or the chosen cache directory. You may need to add `ReadWritePaths=/tmp/huggingface` to the service file or remove `ProtectHome=read-only`.
+
+4. **Restart the bot**:
+   ```bash
+   sudo systemctl restart vox.service
+   ```
+
 ## Linux Server Deployment
 
 To run the bot as a service on a Linux server: