diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b5df819
--- /dev/null
+++ b/README.md
@@ -0,0 +1,117 @@
+# Orbis
+
+A modern Android application showcasing real-time GPU-accelerated graphics rendering using WebGPU. The app displays an animated, procedurally-generated sphere with interactive controls for visual customization.
+
+<p align="center">
+  <video src="media/orbis.mp4" width="300" />
+</p>
+
+## Features
+
+- **WebGPU Rendering** — GPU-accelerated graphics using the modern `androidx.webgpu` API
+- **Raymarching Shader** — Real-time sphere tracing with signed distance functions (SDF)
+- **Procedural Animation** — Noise-based surface displacement for organic, fluid-like motion
+- **Dynamic Lighting** — Fresnel reflections, environment mapping, and Blinn-Phong specular
+- **Interactive Controls** — Real-time adjustment of color (RGBA) and displacement amplitude
+- **Live FPS Counter** — Performance monitoring overlay
+
+## Architecture
+
+```
+Orbis
+├── app/                          # Main application entry point
+│   ├── MainActivity.kt
+│   ├── OrbisApplication.kt
+│   └── di/AppModule.kt
+│
+├── feature/orb/                  # Orb rendering feature
+│   ├── ui/
+│   │   ├── OrbScreen.kt          # Main composable with controls
+│   │   ├── OrbSurface.kt         # WebGPU surface integration
+│   │   └── OrbViewModel.kt       # State management
+│   ├── service/
+│   │   └── OrbRenderServiceImpl.kt   # WebGPU renderer
+│   ├── util/CubemapGenerator.kt  # Procedural environment map
+│   └── assets/
+│       ├── shaders/Orb.wgsl      # WGSL raymarching shader
+│       └── textures/noise_map.png
+│
+└── core/ui/                      # Shared design system
+    ├── Theme.kt                  # OrbisTheme
+    ├── Color.kt                  # Color palette
+    ├── Typography.kt             # Text styles
+    └── components/               # Reusable UI components
+```
+
+## Tech Stack
+
+| Category | Technology |
+|----------|------------|
+| Language | Kotlin 2.3.0 |
+| UI | Jetpack Compose (BOM 2026.01.00) |
+| Graphics | WebGPU (`androidx.webgpu`) |
+| Shaders | WGSL (WebGPU Shading Language) |
+| DI | Koin 4.1.1 |
+| Min SDK | 24 |
+| Target SDK | 36 |
+
+## Getting Started
+
+### Prerequisites
+
+- Android Studio Ladybug or later
+- JDK 17
+- Android device or emulator with API 24+
+
+### Build
+
+```bash
+# Clone the repository
+git clone https://github.com/your-username/orbis.git
+cd orbis
+
+# Build debug APK
+./gradlew assembleDebug
+
+# Install on connected device
+./gradlew installDebug
+```
+
+### Run Tests
+
+```bash
+# Unit tests
+./gradlew test
+
+# Instrumented tests (requires device/emulator)
+./gradlew connectedAndroidTest
+```
+
+### Lint
+
+```bash
+./gradlew lint
+```
+
+## Shader Pipeline
+
+The rendering uses a raymarching approach with the following stages:
+
+1. **Ray Generation** — Compute ray direction from screen UV coordinates
+2. **Sphere Tracing** — March along ray using SDF, with early-out intersection test
+3. **Surface Displacement** — Sample animated noise texture for organic deformation
+4. **Lighting** — Combine diffuse, specular, Fresnel, and environment reflections
+5. **Background** — Radial gradient fallback for missed rays
+
+### Performance Optimizations
+
+- 60% resolution scaling
+- 32 raymarching iterations (reduced for mobile)
+- Single noise sample per ray
+- Tetrahedral normal computation (4 samples vs 6)
+- VSync synchronization via Choreographer
+
+## Configuration
+
+Theme and component generation is handled by the Lumo plugin, configured in `lumo.properties`.
+
diff --git a/media/orbis.jpg b/media/orbis.jpg
new file mode 100644
index 0000000..762c928
Binary files /dev/null and b/media/orbis.jpg differ
diff --git a/media/orbis.mp4 b/media/orbis.mp4
new file mode 100644
index 0000000..d9f7782
Binary files /dev/null and b/media/orbis.mp4 differ