RAG integration follows 6 rules: opt-in, complement, provenance, no mutation, feature-gated, graceful failure

0. The 6 rules (the one-glance table)

#	Rule	Why
1	RAG is opt-in. Default-off in new projects	Most features don't need it; the cost of unnecessary RAG is the embedding-provider round trip + the storage cost
2	RAG complements; it never replaces	Curation / Discussion / Knowledge are the durable, user-editable dimensions; RAG is the fuzzy, semantic search
3	RAG results display with provenance	The user needs to know which file and which chunk produced the result
4	RAG never mutates state	No auto-injection of RAG results into `disc_entries`; no auto-update of `FileItem`; no auto-write to disk
5	RAG integration is feature-gated	A feature must explicitly request RAG in its scope; RAG is not the default for "give me context"
6	RAG failure is graceful	A failed search returns `Result.empty` or an empty list; never crashes the request