Node too old: Use Node 18.17+ (20.x recommended). Node 16 will fail with Vite 5.
Puppeteer missing Chrome: Run npx puppeteer browsers install chrome.
YouTube 403/restricted: Install yt-dlp and/or provide cookies in the Transcribe view; ensure puppeteer fallback is available.
Vector DB dimension mismatch: Align Qdrant collection vector size with embedding model output; recreate or update collection if needed.
Worker errors (chunking): Fallback to main-thread chunking; check browser CSP if worker fails to load.
Where to set keys
.env.local or the in-app Environment view for OpenAI/Gemini/OpenRouter, Qdrant host/apiKey, custom OpenAI-compatible endpoint.
Build/runtime
Run npm run build to catch TypeScript/ESM issues before deploying.
If pdf.js balks under strict CSP, ensure configurePdfJsForStrictCsp remains intact (already set in services/api.ts).
Why only QDrant?
During development, AuldLangSynth required a vector database that was open-source, high-performance, and offered a clean, well-documented API. Qdrant met these requirements and was selected as the initial backend. A significant portion of the application’s internal logic is currently integrated with Qdrant-specific APIs and behaviors, meaning that switching vector databases is not a drop-in change. For this reason, alternative vector backends are not yet supported. That said, support for additional vector databases is planned for the future as time and resources allow.