# 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 |