diff --git a/README.md b/README.md
index bddab94..7658c24 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,62 @@
-# alfred-mobile
+# Alfred Mobile
 
+**Alfred Linux on Android — no root required. 308-line installer for Termux + proot-distro.**
+
+Run Alfred IDE, Alfred Voice, and Alfred Search on any Android device via Termux. Full Debian Bookworm environment with AI tools — no rooting, no flashing, no custom ROM. Works on Samsung DeX for desktop-class IDE experience.
+
+## How It Works
+
+The installer (`install-alfred-mobile.sh`) uses:
+- **Termux**: Android terminal emulator (F-Droid build)
+- **proot-distro**: Userspace Linux containers (no root)
+- **Debian Bookworm**: Full Debian installed inside proot
+
+The script installs a complete Debian environment and then layers Alfred components on top:
+1. Alfred IDE (code-server) — browser-based VS Code
+2. Alfred Search (Meilisearch) — offline instant search
+3. Alfred Voice (Kokoro TTS) — offline text-to-speech
+4. Convenience commands: `alfred`, `alfred-ide`, `alfred-info`
+
+## Installation
+
+```bash
+# On Android, in Termux:
+curl -fsSL https://alfredlinux.com/downloads/install-alfred-mobile.sh | bash
+```
+
+Or download and inspect first:
+```bash
+curl -fsSL https://alfredlinux.com/downloads/install-alfred-mobile.sh -o install.sh
+less install.sh   # inspect the script
+bash install.sh
+```
+
+## Commands After Install
+
+| Command | Action |
+|---------|--------|
+| `alfred` | Enter the Alfred Linux shell |
+| `alfred-ide` | Launch Alfred IDE (opens in browser) |
+| `alfred-info` | Show status of all Alfred services |
+
+## Samsung DeX
+
+On Samsung devices with DeX, `alfred-ide` opens a full desktop IDE in the browser — multi-window, keyboard, mouse. Tested on Samsung Galaxy S-series and Tab S-series.
+
+## File Structure
+
+```
+alfred-mobile/
+├── README.md
+└── install-alfred-mobile.sh    # 308 lines — complete installer
+```
+
+## Requirements
+
+- Android 7+ with Termux (F-Droid version recommended)
+- ~2 GB storage for Debian + Alfred components
+- No root required
+
+## License
+
+AGPL-3.0
\ No newline at end of file