Rename README.md to RAG_Problems.md

ProblemMap/RAG_Problems.md

@@ -0,0 +1,61 @@
+# 🧠 WFGY Problem → Module → Solution Map (v0.1 · RAG Focus)
+
+This page maps common reasoning and retrieval failures — especially in RAG pipelines — to their corresponding WFGY solutions.
+
+WFGY is not a retrieval system.  
+It is a semantic reasoning engine that augments, replaces, or corrects what existing RAG stacks often fail to do.
+
+---
+
+## 🔍 RAG-Related Failures and WFGY Solutions
+
+| Problem | WFGY Solution | Module(s) | Status | Notes |
+|--------|----------------|-----------|--------|-------|
+| [🔸 Hallucination from irrelevant chunks](./hallucination.md) | Semantic Boundary + ΔS monitoring | BBCR, BBMC | ✅ | System detects when input has low semantic match and activates fallback |
+| [🔸 Retrieval returns correct chunk but reasoning fails](./retrieval-collapse.md) | Multi-path semantic logic | BBCR | ✅ | WFGY builds stable reasoning paths even from vague sources |
+| [🔸 Long question-answer chains drift off-topic](./context-drift.md) | Semantic Tree memory + ΔS threshold | BBMC, Tree | ✅ | Semantic jump tracking records nodes, avoids context collapse |
+| [🔸 System "bluffs" when it doesn’t know](./bluffing.md) | Knowledge boundary map | BBCR, λ_observe | ✅ | WFGY detects unstable ΔS + λ_observe and requests clarification |
+| [🔸 Embedding similarity ≠ semantic meaning](./embedding-vs-semantic.md) | Residual Minimization | BBMC, BBAM | ✅ | Matches logic anchor, not just vector cosine |
+| [🔸 System doesn't know what it doesn't know](./unknown-boundary.md) | Knowledge boundary guard | BBCR, Tree | ✅ | Detects unmapped topics and requests clarification |
+| 🔸 No traceability across user sessions | External semantic memory tree | Tree engine | ⚠️ | Manual export/import for now; persistent store upcoming |
+| 🔸 Debugging why RAG failed = painful | Manual tree audit | All modules | ✅ | Tree view shows where logic drifted or ΔS spiked |
+| 🔸 Chunk ingestion pipeline | — | — | 🛠 | Not yet implemented; user pastes chunk into node manually |
+| 🔸 No LangChain compatibility yet | — | — | 🛠 | Adapter planned; WFGY can serve as pre/post-processing layer |
+
+---
+
+## ✅ What you can do now
+
+Even without any retriever, WFGY lets you:
+
+- Paste content manually and reason on it
+- Test hallucination safety via ΔS / λ_observe
+- Record and inspect logic paths via Tree
+- Detect unknown zones before the model bluffs
+
+This means: WFGY is a **RAG failsafe layer**, even without retrieval working.
+
+---
+
+## 🧪 Example Use: "My PDF bot keeps hallucinating answers"
+
+> → Paste the question and chunk into WFGY  
+> → If ΔS is too high, it’ll pause or route to BBCR  
+> → You can inspect the logic trace and see where it went off  
+> → You’ll know if it’s the chunk’s fault — or the reasoning engine
+
+---
+
+## 🔧 Next Steps (Roadmap)
+
+- [ ] Vector chunking → semantic node auto-mapping  
+- [ ] LangChain & LlamaIndex adapters  
+- [ ] Auto-summarization of Tree for memory replay  
+- [ ] GUI explorer for Tree inspection  
+- [ ] Integration with BlotBlotBlot / Persona agents
+
+---
+
+For now, if you're a RAG user tired of hallucinations, TXT OS + WFGY gives you a stable, inspectable core to reason with.
+
+Feel free to open an issue if your failure case isn’t listed.