Reference: Mid-Scale RAG Over Internal Docs

Architectural notes

Reference architecture for an internal "ask the docs" agent over Notion,
GitHub READMEs, and a docs site.

Why these picks:
- Mastra for orchestration because the team is already TypeScript-first.
- turbopuffer for hybrid (vector + BM25) search over ~100k chunks.
- Voyage embeddings over OpenAI for retrieval quality at this scale.
- Langfuse for self-hosted observability where doc content is sensitive.
- Braintrust for golden-question eval gated in CI.

Common gotchas:
- Chunking strategy dominates retrieval quality more than embedding choice.
- Notion MCP can return inconsistent results when pages are reorganized.