diff --git a/README.md b/README.md
index 6c64cc8..9c18e93 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,108 @@
 # hear-on-out
-Generative ambient noise affected by environment data for your location
+
+A generative ambient music application that transforms real-time weather and air quality data into dynamic soundscapes.
+
+## Overview
+
+hear-on-out uses your geolocation to fetch current weather and air quality data, then generates unique ambient music that responds to environmental conditions in real-time. Every parameter of the audio - from tempo to reverb to note patterns - is affected by the weather around you.
+
+## Features
+
+### Weather-Reactive Generative Music
+
+**Chord Progressions**
+- 6 distinct mood-based progressions (bright, dreamy, melancholic, tense, warm, ethereal)
+- Intelligent selection based on weather comfort scoring
+- Smooth transitions between progressions
+
+**Instruments**
+- **Ambient Pad**: Day/night reactive foundation with triangle (day) or sine (night) oscillators
+- **Main Arpeggio**: Temperature-reactive note patterns with variable speed (1n → 8n) and volume
+- **Ping Arpeggio**: High-pitched reverse arpeggios that intensify with weather extremity, speed scales with temperature
+- **Bass Synth**: Root note foundation with randomized release times
+
+**Dynamic Audio Parameters**
+- **BPM**: Scales with temperature (10 BPM at 0°C → faster at 30°C+, 2x multiplier for daytime)
+- **Reverb**: Wet signal responds to humidity (more humid = more reverb)
+- **Delay**: Time and feedback react to wind speed (faster wind = shorter delay, more feedback)
+- **Filter**: Cutoff frequency darkens with cloud cover (clear sky = 8000Hz, overcast = 400Hz)
+- **Resonance**: Increases with wind speed for sharper filtering
+
+### Air Quality Monitor
+
+- Geiger-counter style noise bursts that trigger based on pollution levels
+- Higher pollution = more frequent bursts (6s intervals for clean air → 0.3s for heavy pollution)
+- Spacious reverb (30s decay) for atmospheric depth
+- Monitors PM2.5, PM10, and dust particles
+
+### Audio Visualization
+
+- Real-time particle system using p5.js
+- FFT analysis for bass, mid, and treble frequency detection
+- Particles react to audio levels with dynamic size and movement
+- Connected particle network with proximity-based relationships
+
+## Technologies
+
+- **SvelteKit** - Web framework with Svelte 5 runes
+- **Tone.js** - Web Audio API wrapper for synthesis and effects
+- **p5.js** - Creative coding for visualizations
+- **Tailwind CSS v4** - Styling with black/white monochrome theme
+- **Open-Meteo API** - Weather and air quality data
+
+## Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Run development server
+npm run dev
+
+# Build for production
+npm run build
+```
+
+## How It Works
+
+1. **Geolocation**: User grants location permissions
+2. **Data Fetch**: Current weather and air quality data retrieved from Open-Meteo API
+3. **Weather Comfort Scoring**: Algorithm calculates comfort based on temperature, humidity, cloud cover, wind, and precipitation
+4. **Progression Selection**: Chooses appropriate chord progression based on weather mood
+5. **Audio Generation**: All instruments and effects dynamically adjust to conditions
+6. **Real-time Updates**: Audio parameters smoothly transition as weather changes
+
+## Project Structure
+
+```
+src/
+├── lib/
+│   ├── audio/
+│   │   ├── instruments/        # Modular synth instruments
+│   │   ├── audio-effects.ts    # Shared audio effects
+│   │   ├── chord-progressions.ts
+│   │   └── weather-mood.ts     # Comfort scoring & progression selection
+│   ├── components/
+│   │   └── AudioVisualization.svelte
+│   └── generators/
+│       ├── weather/WeatherGen.svelte
+│       └── air-quality/AirQualityGen.svelte
+└── routes/
+    ├── +page.svelte           # Geolocation entry point
+    └── on-out/+page.svelte    # Audio generators
+```
+
+## Weather Mood Mapping
+
+| Conditions | Progression | Characteristics |
+|------------|-------------|-----------------|
+| Stormy/Extreme | Tense | Dissonant, unsettling |
+| Very Hot (30°C+) | Warm | Energetic, bright |
+| Cold/Rainy | Melancholic | Somber, introspective |
+| Foggy/Misty | Ethereal | Spacious, mysterious |
+| Pleasant Day | Bright | Uplifting, major tonality |
+| Pleasant Night | Dreamy | Calm, flowing |
+
+## License
+
+MIT