diff --git a/README.md b/README.md
index e69de29..49e19e6 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,166 @@
+# 🌤️ Weather Forecast App  
+
+A simple yet modern **Flask-based weather forecast application** that fetches real-time weather data from [OpenWeatherMap](https://openweathermap.org/) and provides a beautiful, responsive UI.  
+
+This project is **Dockerized** and supports **CI/CD deployment** to **Ghaymah Cloud** using the included shell script.  
+
+---
+
+## 🚀 Features  
+
+- 🌍 Search weather for any city worldwide  
+- 🌡️ Shows temperature, feels-like, humidity, pressure, wind speed, and visibility  
+- 🌅 Displays sunrise and sunset times  
+- 📊 Auto-updating with timestamp  
+- 🎨 Responsive and modern UI (HTML, CSS, JS embedded in Flask)  
+- 🐳 Dockerized for portability  
+- ☁️ CI/CD ready with Ghaymah Cloud  
+
+---
+
+## 📂 Project Structure  
+
+```
+.
+├── app.py                # Flask application with weather API integration
+├── CICDpipeline.sh       # CI/CD pipeline script for Docker + Ghaymah Cloud
+├── Dockerfile            # Dockerfile to containerize the Flask app
+├── requirements.txt      # Python dependencies
+├── templates/            # HTML templates (auto-generated by Dockerfile)
+└── README.md             # Documentation
+```
+
+---
+
+## ⚙️ Prerequisites  
+
+Before running or deploying the app, ensure you have:  
+
+- [Python 3.9+](https://www.python.org/downloads/)  
+- [Docker](https://docs.docker.com/get-docker/)  
+- [Ghaymah CLI (`gy`)](https://docs.ghaymah.io) installed and configured  
+- An [OpenWeatherMap API key](https://home.openweathermap.org/api_keys)  
+
+---
+
+## 🛠️ Local Development  
+
+1. Clone this repository:  
+
+   ```bash
+   git clone https://github.com/your-username/weather-app.git
+   cd weather-app
+   ```
+
+2. Create and activate a virtual environment:  
+
+   ```bash
+   python -m venv venv
+   source venv/bin/activate   # Linux/Mac
+   venv\Scripts\activate      # Windows
+   ```
+
+3. Install dependencies:  
+
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. Run the app:  
+
+   ```bash
+   python app.py
+   ```
+
+5. Open your browser at:  
+   👉 http://127.0.0.1:5000
+
+---
+
+## 🐳 Running with Docker  
+
+1. Build the Docker image:  
+
+   ```bash
+   docker build -t weather-app:1 .
+   ```
+
+2. Run the container:  
+
+   ```bash
+   docker run -p 5000:5000 weather-app:1
+   ```
+
+3. Visit the app at:  
+   👉 http://localhost:5000
+
+---
+
+## ☁️ CI/CD Deployment to Ghaymah Cloud  
+
+This project includes a **CICDpipeline.sh** script that:  
+- Builds and tags Docker images  
+- Pushes them to Docker Hub  
+- Creates a `.ghaymah.json` config  
+- Deploys the app to **Ghaymah Cloud**  
+
+### 🔧 Steps  
+
+1. Make the script executable:  
+
+   ```bash
+   chmod +x CICDpipeline.sh
+   ```
+
+2. Run the deployment script:  
+
+   ```bash
+   ./CICDpipeline.sh
+   ```
+
+3. Follow the prompts:  
+   - Enter your **Ghaymah Project Name**  
+   - Enter your **App Name**  
+
+4. If Ghaymah CLI is installed, the app will be deployed automatically.  
+
+✅ Your app will be accessible at:  
+
+```
+https://<your-app-name>.hosted.ghaymah.systems
+```
+
+---
+
+## 🧾 Environment Variables  
+
+Set your OpenWeatherMap API key (recommended):  
+
+```bash
+export API_KEY="your_openweathermap_api_key"
+```
+
+If not set, a demo key will be used (limited requests).  
+
+---
+
+## 📊 Health Check  
+
+Check if the app is running:  
+
+```bash
+curl http://localhost:5000/health
+```
+
+Example response:  
+
+```json
+{
+  "status": "healthy",
+  "timestamp": "2025-09-25T14:30:00"
+}
+```
+
+---
+
+