docs and api mostly work

README.md

@@ -177,6 +177,49 @@ Edit `data/settings.cfg` to customize:
 - Number of prompts per session
 - Pool volume targets
 
+## 🐛 Troubleshooting
+
+### Docker Permission Issues
+If you encounter permission errors when running Docker containers:
+
+1. **Check directory permissions**:
+   ```bash
+   ls -la data/
+   ```
+   The `data/` directory should be readable/writable by your user (UID 1000 typically).
+
+2. **Fix permissions** (if needed):
+   ```bash
+   chmod 700 data/
+   chown -R $(id -u):$(id -g) data/
+   ```
+
+3. **Verify Docker user matches host user**:
+   The Dockerfile creates a user with UID 1000. If your host user has a different UID:
+   ```bash
+   # Check your UID
+   id -u
+
+   # Update Dockerfile to match your UID
+   # Change: RUN useradd -m -u 1000 appuser
+   # To: RUN useradd -m -u YOUR_UID appuser
+   ```
+
+### npm Build Errors
+If you see `npm ci` errors:
+- The Dockerfile uses `npm install` instead of `npm ci` for development
+- For production, generate a `package-lock.json` file first:
+  ```bash
+  cd frontend
+  npm install
+  ```
+
+### API Connection Issues
+If the backend can't connect to AI APIs:
+1. Verify your API key is set in `.env`
+2. Check network connectivity
+3. Ensure the API service is available
+
 ## 🧪 Testing
 
 Run the backend tests: