diff --git a/README.md b/README.md
index bde04aa..d0802c4 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,160 @@
-# task-6a1864f7-ekzamen-rag-agent-s-chrom
+# RAG‑Agent with ChromaDB and Web Search
 
-Решения домашних заданий
\ No newline at end of file
+A lightweight RAG (Retrieval‑Augmented Generation) agent that uses a local **ChromaDB** vector store for knowledge retrieval and **Tavily** for live web search.  
+The agent automatically decides whether to answer from the local knowledge base or to fetch fresh information from the web.
+
+> **Prerequisites**  
+> • Python 3.10+  
+> • Ollama (LLM & embeddings)  
+> • Tavily API key
+
+---
+
+## 📦 Project Structure
+
+```
+.
+├── vectorstore.py          # Vector store creation & document ingestion
+├── agent.py                # RAG agent implementation (not shown in the prompt)
+├── .env                    # Tavily API key
+├── requirements.txt        # Dependencies
+└── README.md
+```
+
+---
+
+## 🚀 Installation
+
+```bash
+# 1. Pull required models into Ollama
+ollama pull llama3
+ollama pull nomic-embed-text
+
+# 2. Install Python dependencies
+pip install -r requirements.txt
+```
+
+`requirements.txt`
+
+```text
+langchain
+langchain-chroma
+langchain-tavily
+langchain-ollama
+tavily-python
+chromadb
+python-dotenv
+```
+
+> **Note**:  
+> *If you use a different LLM or embeddings provider, adjust the `create_vectorstore` function accordingly.*
+
+---
+
+## ⚙️ Configuration
+
+Create a `.env` file in the project root:
+
+```dotenv
+TAVILY_API_KEY=your_tavily_api_key_here
+```
+
+The key is used by the Tavily client for web search.
+
+---
+
+## 📚 Using the Vector Store
+
+### 1. Create the store
+
+```python
+from vectorstore import create_vectorstore
+
+vectorstore = create_vectorstore("./chroma_db")
+```
+
+### 2. Load documents into the store
+
+```python
+from vectorstore import load_documents
+
+# Directory containing .txt or .md files
+load_documents("./knowledge_base", vectorstore)
+```
+
+The function will:
+
+1. Read all `.txt` and `.md` files in the given directory.
+2. Split them into chunks using `RecursiveCharacterTextSplitter`.
+3. Add the chunks to the Chroma collection.
+
+---
+
+## 🧩 Running the Agent
+
+> **Assumption**: `agent.py` contains the main RAG agent logic that imports `vectorstore.py`.  
+> The agent automatically chooses between the local vector store and Tavily search.
+
+```bash
+python agent.py
+```
+
+The agent will:
+
+1. Prompt the user for a question.
+2. Query the vector store for relevant chunks.
+3. If the answer is insufficient, perform a web search via Tavily.
+4. Generate a final answer with the chosen source.
+
+---
+
+## 🔧 Example Workflow
+
+```bash
+$ python agent.py
+Enter your question (or 'exit' to quit): What is the capital of France?
+
+Answer: The capital of France is Paris.
+Source: Local knowledge base (retrieved from chroma_db)
+```
+
+If the question is about a very recent event:
+
+```bash
+$ python agent.py
+Enter your question (or 'exit' to quit): Who won the 2024 World Series?
+
+Answer: The 2024 World Series was won by the Texas Rangers.
+Source: Web search (Tavily)
+```
+
+---
+
+## 📦 Adding New Documents
+
+1. Drop your `.txt` or `.md` files into the `knowledge_base/` directory.
+2. Run:
+
+```bash
+python -c "from vectorstore import load_documents, create_vectorstore; load_documents('knowledge_base', create_vectorstore())"
+```
+
+The new documents will be indexed automatically.
+
+---
+
+## 🛠️ Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| `ModuleNotFoundError: No module named 'langchain_ollama'` | Missing dependency | `pip install langchain-ollama` |
+| `Ollama` not running | Ollama daemon stopped | `ollama serve` |
+| Tavily errors | Invalid API key | Verify `.env` and restart |
+
+---
+
+## 📄 License
+
+MIT License – feel free to adapt and extend.
+
+---
\ No newline at end of file