Update README.md

README.md

@@ -1,11 +1,80 @@
 ---
 title: Digital Life Evolution Simulator
-emoji: 🏢
-colorFrom: red
-colorTo: purple
+emoji: 🧬
+colorFrom: blue
+colorTo: red
 sdk: static
 pinned: false
 short_description: A self-evolving ecosystem that runs entirely in the browser
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Digital Life Evolution Simulator
+
+A self-evolving AI ecosystem where autonomous entities compete, reproduce, and adapt through neural networks and genetic algorithms. Watch digital life emerge and evolve in real-time.
+
+## What It Does
+
+This simulation creates a population of AI entities with unique genomes that control their behavior through neural networks. Each entity:
+
+- **Perceives** its environment (food, energy, other entities)
+- **Decides** actions based on neural network processing
+- **Adapts** through natural selection - successful traits get passed to offspring
+- **Evolves** over generations as mutations introduce variation
+
+Four entity types exist:
+
+- **Gatherers** - Collect food and energy efficiently
+- **Predators** - Hunt and consume other entities
+- **Builders** - Create structures and territorial markers
+- **Explorers** - Scavenge and discover new resources
+
+## Quick Start
+
+```bash
+# Start a local server
+npx serve .
+# or
+python3 -m http.server 8000
+
+# Open in browser
+http://localhost:8000
+```
+
+## Features
+
+- **Neural Network AI** - Each entity has a unique brain with 80+ configurable parameters
+- **Genetic Algorithm** - Reproduction with crossover and mutation
+- **Spatial Awareness** - Efficient spatial hashing for proximity detection
+- **Real-time Stats** - Track population, generations, fitness, and neural activity
+- **Visual Feedback** - See neural network activations while watching decisions
+
+## Tech Stack
+
+- Pure vanilla JavaScript (ES2022 modules)
+- HTML5 Canvas rendering
+- No build step, no dependencies
+
+## Project Structure
+
+```
+js/
+├── ecosystem.js      # Main loop, initialization
+├── world.js          # Environment, resource spawning
+├── entities.js       # Entity behavior logic
+├── entityManager.js  # Lifecycle management
+├── genetics.js       # Genome creation, reproduction
+├── neuralNetwork.js  # AI decision-making
+├── particles.js      # Visual effects
+├── stats.js          # Performance telemetry
+├── ui.js             # Controls, event logs
+└── utils.js          # Math, object pools, spatial grid
+```
+
+## How Evolution Works
+
+1. **Selection** - Entities with higher fitness are more likely to reproduce
+2. **Crossover** - Two parents combine their neural network weights
+3. **Mutation** - Random Gaussian noise introduces variation
+4. **Survival** - Less fit entities die; successful traits propagate
+
+Over time, you'll observe emergent behaviors as entities adapt to the competitive environment.