diff --git a/README.md b/README.md
index 32fa76d..8896d8b 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,231 @@
 # LifePaths
 
+A Dynamic Life Simulation Game
+
+LifePaths is a web-based life simulation game inspired by BitLife, The Sims, Crusader Kings 3, and Game of Life. It offers a nonlinear choose-your-own-adventure (CYOA) experience where players navigate through various life events, make choices, and shape their character's destiny.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Demo](#demo)
+- [Installation](#installation)
+  - [Prerequisites](#prerequisites)
+  - [Setup](#setup)
+- [Usage](#usage)
+  - [Running the Game](#running-the-game)
+  - [Playing the Game](#playing-the-game)
+- [Project Structure](#project-structure)
+- [Contributing](#contributing)
+- [License](#license)
+- [Acknowledgments](#acknowledgments)
+
+---
+
+## Features
+
+- **Character Creation**: Customize your character's name, gender, skin tone, abilities, traits, and background.
+- **Dynamic Events**: Experience a wide range of events influenced by your choices, traits, and background.
+- **Nonlinear Storylines**: Navigate through multiple branching storylines and career paths.
+- **Ability Checks**: Make decisions that rely on your character's abilities, with critical successes and failures adding unpredictability.
+- **Interactive UI**: Enjoy a modern, minimalistic interface with smooth animations and responsive design.
+
+---
+
+## Demo
+
+*Add a link or screenshots of the game in action.*
+
+---
+
+## Installation
+
+### Prerequisites
+
+- **Python 3.7+**
+- **pip** (Python package installer)
+- **Virtual Environment** (Recommended)
+
+### Setup
+
+1. **Clone the Repository**
+
+   ```bash
+   git clone https://github.com/yourusername/lifepaths.git
+   cd lifepaths
+   ```
+
+2. **Create a Virtual Environment**
+
+   ```bash
+   python3 -m venv venv
+   source venv/bin/activate  # On Windows use `venv\Scripts\activate`
+   ```
+
+3. **Install Dependencies**
+
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. **Set Up Environment Variables**
+
+   - Create a `.env` file in the root directory.
+   - Add your secret key and any other necessary configurations.
+
+     ```bash
+     SECRET_KEY=your_secret_key
+     ```
+
+5. **Prepare Data Files**
+
+   - Ensure that the `data/` directory contains the necessary YAML files organized as per the project structure.
+   - Example:
+
+     ```
+     data/
+     ├── events/
+     ├── storylines/
+     └── careers/
+     ```
+
+---
+
+## Usage
+
+### Running the Game
+
+1. **Activate the Virtual Environment**
+
+   ```bash
+   source venv/bin/activate  # On Windows use `venv\Scripts\activate`
+   ```
+
+2. **Start the Flask App**
+
+   ```bash
+   flask run
+   ```
+
+   - By default, the app will run on `http://127.0.0.1:5000/`.
+
+### Playing the Game
+
+- Open your web browser and navigate to `http://127.0.0.1:5000/`.
+- Create your character by filling out the character creation form.
+- Proceed through events by making choices and experiencing the outcomes.
+- Navigate through life stages, careers, and storylines as your character ages.
+
+---
+
+## Project Structure
+
+```
+lifepaths/
+├── app.py
+├── data/
+│   ├── events/
+│   │   ├── [country]/
+│   │   │   ├── [region]/
+│   │   │   │   ├── [decade]/
+│   │   │   │   │   ├── [background]/
+│   │   │   │   │   │   ├── childhood.yaml
+│   │   │   │   │   │   ├── teen.yaml
+│   │   │   │   │   │   └── adult.yaml
+│   │   │   │   │   └── ...
+│   │   │   │   └── ...
+│   │   │   └── ...
+│   │   └── ...
+│   ├── storylines/
+│   │   ├── main_storyline.yaml
+│   │   └── ...
+│   └── careers/
+│       ├── doctor.yaml
+│       ├── engineer.yaml
+│       └── ...
+├── templates/
+│   ├── index.html
+│   ├── create_character.html
+│   ├── event.html
+│   ├── outcome.html
+│   └── no_events.html
+├── static/
+│   └── [Optional static files like CSS, JS, images]
+├── requirements.txt
+└── .env
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! Here's how you can help:
+
+1. **Fork the Repository**
+
+   - Click the "Fork" button at the top right of this page.
+
+2. **Clone Your Fork**
+
+   ```bash
+   git clone https://github.com/yourusername/lifepaths.git
+   ```
+
+3. **Create a New Branch**
+
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+4. **Make Your Changes**
+
+   - Add new features, fix bugs, or improve documentation.
+
+5. **Commit Your Changes**
+
+   ```bash
+   git commit -am 'Add some feature'
+   ```
+
+6. **Push to the Branch**
+
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+7. **Create a Pull Request**
+
+   - Open a pull request from your branch to the `main` branch of this repository.
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## Acknowledgments
+
+- **Inspiration**
+
+  - [BitLife](https://bitlifeapp.com/)
+  - [The Sims](https://www.ea.com/games/the-sims)
+  - [Crusader Kings 3](https://www.crusaderkings.com/)
+  - [Game of Life](https://en.wikipedia.org/wiki/Game_of_Life)
+
+- **Libraries and Frameworks**
+
+  - [Flask](https://flask.palletsprojects.com/)
+  - [HTMX](https://htmx.org/)
+  - [Picnic CSS](https://picnicss.com/)
+  - [PyYAML](https://pyyaml.org/)
+
+- **Contributors**
+
+  - *List of contributors or a link to the contributors' page.*
+
+---
+
+*Feel free to customize and expand this README as your project evolves.*
\ No newline at end of file