diff --git a/README.md b/README.md
index 044bf90..411572b 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,59 @@
-# task-69b1a07c67bbf488a1177da4
+# Text Adventure Game with LLM and Interrupt
 
-Text adventure game using LangGraph with interrupt
\ No newline at end of file
+## Overview
+This repository implements a **text‑based choose‑your‑story** game that demonstrates how to combine LangGraph, LangChain and the BroJS LLM for interactive storytelling.
+
+The key concepts showcased are:
+- A stateful graph that pauses for user input via `interrupt()`.
+- Two LLM calls: one generates an opening paragraph with three actions; the second writes a short ending based on the chosen action.
+- Human‑in‑the‑loop (HITL) using `questionary` to present a menu and capture the user's choice.
+
+The game is intentionally lightweight so you can run it locally with minimal setup.
+
+## File Structure
+| Path | Purpose |
+|------|---------|
+| `main.py` | Entry point – defines state, nodes, graph and runs the game. |
+| `requirements.txt` | Exact dependencies with pinned versions. |
+| `README.md` | Project description, installation and usage instructions. |
+
+## Installation
+```bash
+# Create a virtual environment (optional but recommended)
+python -m venv .venv
+source .venv/bin/activate   # On Windows use `.venv\Scripts\activate`
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+**Important:** The BroJS LLM requires an API key. Export it as:
+```bash
+export JOURNAL_MCP_PAT=your_api_key_here
+```
+or set it in your IDE’s environment variables.
+
+## Running the Game
+```bash
+python main.py
+```
+You will be prompted to enter a theme for the adventure (e.g., "a lonely astronaut on a deserted moon"). The game proceeds as follows:
+1. **Intro generation** – The LLM writes a short opening paragraph and three numbered actions.
+2. **Interrupt** – The graph pauses, displaying the intro and asking you to choose an action via a console menu.
+3. **Ending generation** – After you select an option, the LLM produces a concluding paragraph that reflects your choice.
+4. **Final output** – The complete story (intro, chosen action, ending) is printed to the console.
+
+## Customization
+- **Change the theme**: Edit `main.py` or provide a different prompt when running.
+- **Adjust LLM temperature**: Modify the `temperature` parameter in the `ChatOpenAI` initialization.
+- **Add more options**: Update the prompt to request more than three actions and adjust parsing logic accordingly.
+
+## Troubleshooting
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| No output after running | API key missing or invalid | Ensure `JOURNAL_MCP_PAT` is set correctly. |
+| LLM returns unexpected format | Prompt not strict enough | Tighten the prompt to enforce a predictable response structure. |
+| Errors in parsing options | Options list contains extra text | Verify that each option line starts with "1)" / "2)" / "3)".
+
+## License & Credits
+This project is released under the MIT license. The LLM model used is provided by BroJS and is subject to their terms of service.