diff --git a/README.md b/README.md
index e69de29..ef0f9e7 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,79 @@
+# KX-Bridge Android
+
+KX-Bridge Android is a Kotlin Jetpack Compose client for controlling a printer bridge server. It connects to a local bridge API, displays printer status, camera preview, filament AMS information, and exposes controls for pause/resume/cancel, lighting, and temperature.
+
+## Features
+
+- Connect to a KX bridge server via URL
+- Persistent server URL storage in app preferences
+- Live printer state polling
+- Print status and progress display
+- Pause, resume, and cancel print jobs
+- Nozzle and bed temperature control
+- Light control with brightness settings
+- MJPEG camera preview streaming
+- Filament AMS slot display
+- Error handling for server connectivity
+
+## Technology
+
+- Android Gradle plugin `8.13.2`
+- Kotlin `2.0.0`
+- Jetpack Compose UI
+- AndroidX Lifecycle and ViewModel
+- OkHttp for HTTP and MJPEG stream
+- Kotlinx Serialization for JSON parsing
+- Kotlin Coroutines for asynchronous polling
+
+## Project structure
+
+- `app/` - Android application module
+- `app/src/main/java/com/kxbridge/` - app source code
+- `app/src/main/AndroidManifest.xml` - app manifest and permissions
+- `build.gradle.kts` - top-level Gradle plugin configuration
+- `app/build.gradle.kts` - module dependencies and Android config
+
+## Requirements
+
+- Android Studio or Gradle-compatible IDE
+- Java 17 / JDK 17
+- Android SDK API level 34
+- Android device or emulator with minimum SDK 26
+
+## Setup
+
+1. Clone the repository.
+2. Open the project in Android Studio.
+3. Sync Gradle and ensure SDK 34 is installed.
+4. Run the app on a device or emulator.
+
+## Usage
+
+1. Launch the app.
+2. Enter the bridge server URL, e.g. `http://192.168.1.x:7125`.
+3. Tap `Connect`.
+4. Control printing, lighting, temperatures, and camera preview from the dashboard.
+
+## Build
+
+From the project root:
+
+```bash
+./gradlew assembleDebug
+```
+
+On Windows PowerShell:
+
+```powershell
+./gradlew.bat assembleDebug
+```
+
+## Notes
+
+- The app requires `INTERNET` permission.
+- Cleartext traffic is enabled for local HTTP bridge servers.
+- The app uses a basic bridge API at `/api/state`, `/printer/print/*`, `/api/light`, `/api/temperature`, and `/api/camera/*`.
+
+## License
+
+This repository does not include a license file. Add one if you want to define reuse terms.