diff --git a/README.md b/README.md
index a47ac6a..9d363d5 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,182 @@
-A tactical roguelike voxel game.
+# Aether Shards
+
+A tactical turn-based roguelike strategy game built with Three.js, featuring procedurally generated voxel worlds, squad-based combat, and a narrative-driven campaign system.
+
+## Overview
+
+**Aether Shards** is a tactical roguelike where players lead a squad of explorers through procedurally generated 3D voxel environments. The game combines turn-based tactical combat with roguelike progression, featuring a class-based unit system, mission objectives, and persistent campaign progression.
+
+## Key Features
+
+### 🎮 Core Gameplay
+
+- **Turn-Based Tactical Combat**: Strategic positioning and action point management on a 3D voxel grid
+- **Squad Management**: Build and customize teams from multiple character classes (Vanguard, Aether Weaver, Scavenger, Tinker, Custodian, and more)
+- **Procedural Generation**: Multiple biome generators (Caves, Ruins, Crystal Spires) create unique levels each run
+- **Mission System**: Campaign progression with objectives, narrative sequences, and rewards
+- **Deployment Phase**: Pre-battle unit placement on designated spawn zones
+
+### 🏗️ Technical Architecture
+
+- **3D Voxel Rendering**: Three.js-powered voxel grid system with custom texture generators
+- **Modular Class System**: JSON-defined character classes with skill trees, stats, and equipment
+- **State Management**: Persistent save system using IndexedDB for campaign progress
+- **Component-Based UI**: Lit-based web components for HUD, team builder, and dialogue systems
+- **Input System**: Keyboard and gamepad support with cursor-based grid navigation
+
+### 🎨 Game Systems
+
+- **Unit Classes**: 10+ character classes with unique roles (Tank, DPS, Healer, Utility, Tech)
+- **Skill Trees**: Active and passive abilities per class
+- **Equipment System**: Gear that modifies unit stats and capabilities
+- **Narrative System**: Dialogue sequences and story integration
+- **Objective Tracking**: Mission goals with real-time progress monitoring
+
+## Tech Stack
+
+- **Rendering**: Three.js (WebGL)
+- **UI Framework**: Lit (Web Components)
+- **Build Tool**: esbuild
+- **Testing**: Web Test Runner
+- **Language**: JavaScript (ES Modules)
+
+## Project Structure
+
+```
+src/
+├── assets/
+│   ├── data/
+│   │   ├── classes/          # Character class definitions (JSON)
+│   │   ├── missions/          # Mission configurations
+│   │   └── narrative/         # Dialogue sequences
+│   └── images/                # Character portraits and assets
+├── core/
+│   ├── GameLoop.js           # Main game loop and Three.js setup
+│   ├── GameStateManager.js   # Application state management
+│   ├── InputManager.js       # Input handling (keyboard/gamepad)
+│   └── Persistence.js        # Save/load system
+├── generation/
+│   ├── BaseGenerator.js     # Base class for world generators
+│   ├── CaveGenerator.js     # Cave biome generator
+│   ├── RuinGenerator.js     # Ruin biome generator
+│   └── textures/            # Procedural texture generators
+├── grid/
+│   ├── VoxelGrid.js         # 3D voxel grid data structure
+│   └── VoxelManager.js      # Voxel rendering and mesh management
+├── managers/
+│   ├── MissionManager.js    # Mission progression and objectives
+│   ├── NarrativeManager.js  # Dialogue and story sequences
+│   ├── RosterManager.js     # Character roster management
+│   └── UnitManager.js       # Unit lifecycle and combat state
+├── ui/
+│   ├── deployment-hud.js    # Pre-battle deployment interface
+│   ├── team-builder.js      # Squad composition screen
+│   ├── game-viewport.js     # 3D game viewport component
+│   └── dialogue-overlay.js  # Narrative dialogue display
+├── units/
+│   ├── Unit.js              # Base unit class
+│   ├── Explorer.js          # Player-controlled units
+│   └── Enemy.js             # Enemy AI units
+└── index.js                 # Application entry point
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js (v16+)
+- npm
+
+### Installation
+
+```bash
+npm install
+```
+
+### Development
+
+Start the development server:
+
+```bash
+npm start
+```
+
+The game will be available at `http://localhost:8000`
+
+### Building
+
+Create a production build:
+
+```bash
+npm run build
+```
+
+### Testing
+
+Run the test suite:
+
+```bash
+npm test
+```
+
+Run tests in watch mode:
+
+```bash
+npm run test:watch
+```
+
+## Game Flow
+
+1. **Main Menu**: Start a new run or continue a saved game
+2. **Team Builder**: Select and customize your squad from available classes
+3. **Mission Selection**: Choose a mission (currently starts with tutorial)
+4. **Deployment Phase**: Place units on designated spawn zones
+5. **Tactical Combat**: Turn-based combat with action points, movement, and abilities
+6. **Mission Completion**: Complete objectives to earn rewards and progress the campaign
+
+## Game Mechanics
+
+### Units
+
+- **Action Points (AP)**: Units spend AP to move, attack, and use abilities
+- **Charge Meter**: Dynamic initiative system (0-100) determines turn order
+- **Stats**: Health, Attack, Defense, Magic, Speed, Willpower, Movement, Tech
+- **Status Effects**: Buffs and debuffs that modify unit capabilities
+
+### World Generation
+
+- **Seeded Random**: Deterministic procedural generation for consistent runs
+- **Biomes**: Different environment types with unique generation rules
+- **Spawn Zones**: Designated areas for player and enemy deployment
+- **Cover System**: Destructible objects provide tactical positioning
+
+### Missions
+
+- **Objectives**: Primary goals (e.g., eliminate all enemies, reach location)
+- **Rewards**: XP and currency (Aether Shards) for completion
+- **Narrative**: Intro and outro sequences that advance the story
+- **Campaign Progression**: Unlock new missions as you complete objectives
+
+## Development Status
+
+This is an active development project. Current features include:
+
+- ✅ Core game loop and rendering
+- ✅ Voxel grid system
+- ✅ Team builder UI
+- ✅ Deployment phase
+- ✅ Mission system foundation
+- ✅ Basic world generation
+- ✅ Save/load system
+
+Planned features:
+
+- 🔄 Turn-based combat system
+- 🔄 AI behavior
+- 🔄 Skill tree implementation
+- 🔄 Equipment system
+- 🔄 Additional biomes and missions
+
+## License
+
+ISC