diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5e0665b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,142 @@
+# blekin
+
+A Rust proxy that translates the Belkin OmniView Remote IP Manager's proprietary
+e-RIC RFB protocol (Peppercon LARA, originally served via a Java applet) into a
+modern HTML5 KVM console. No Java anywhere in the stack.
+
+## What it does
+
+```
+Browser (Vite + TypeScript)
+   │ WebSocket (binary, RGBA blits + input events)
+   ▼
+blekin proxy (Rust, tokio + axum)
+   │ HTTP session (cookie + APPLET_ID extraction)
+   │ TCP to OmniView:443 (e-RIC RFB)
+   ▼
+Belkin OmniView Remote IP Manager → downstream KVM switch → servers
+```
+
+The proxy authenticates with the OmniView's web interface, establishes an e-RIC
+RFB session over TCP, decodes the proprietary 8bpp protocol to RGBA, and bridges
+video frames and input events to a browser-based console over WebSocket.
+
+## Features
+
+- Full KVM console: keyboard, mouse, scroll wheel
+- Encodings: Raw, CopyRect, Hextile, Tight (with zlib), IIP tile cache, Raw-tile
+- Send Key menu for browser-intercepted keys (Print Screen, Scroll Lock, etc.)
+- Port switching with downstream KVM support (Avocent OSCAR tested)
+- Port configuration: naming, hotkeys, visibility
+- Auto-reconnect with exponential backoff
+- Session persistence across page refreshes
+- Dark theme, fullscreen mode
+
+## Building
+
+```sh
+# Backend
+cargo build --release -p ericrfb-proxy
+
+# Frontend
+cd crates/ericrfb-frontend
+npm ci
+npm run build   # outputs to ../../dist/
+```
+
+## Configuration
+
+The proxy reads `config.toml` or falls back to the `BLEKIN_HOST` environment variable:
+
+```toml
+bind = "0.0.0.0:3000"
+static_dir = "dist"
+
+[omniview]
+host = "10.3.0.130"
+http_port = 80
+rfb_port = 443
+```
+
+## Deployment
+
+The systemd unit runs the proxy as a service. Nginx serves the static frontend
+and reverse-proxies `/api/` to the proxy:
+
+```sh
+# Backend
+sudo cp target/release/ericrfb-proxy /usr/local/bin/
+sudo cp asset/systemd/blekin.service /etc/systemd/system/
+sudo systemctl enable --now blekin.service
+
+# Frontend
+sudo cp -r dist/* /var/www/blekin.example.com/
+sudo cp asset/nginx/blekin.example.conf /etc/nginx/sites-available/
+sudo ln -sf /etc/nginx/sites-available/blekin.example.conf /etc/nginx/sites-enabled/
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+## Port switching with downstream KVM
+
+The Belkin OmniView can control a downstream KVM switch (e.g., Avocent AutoView)
+by sending configurable hotkey sequences when switching ports. Configure these
+in the Ports page of the blekin interface.
+
+### Avocent OSCAR setup
+
+The Avocent OSCAR menu is invoked with Print Screen, then expects the port's EID
+(Electronic ID) typed as digits, followed by Enter. Each phase needs a pause to
+let the OSCAR process the input.
+
+**Recommended settings:**
+
+- **Key pause:** `1000` ms (in the Ports page global settings)
+- **Hotkey format:** `PRINTSCREEN-***<EID digits>-***ENTER`
+
+The `*` character inserts a pause of the configured duration. Three `***` = 3
+seconds, which gives the OSCAR reliable processing time.
+
+**Examples** (with key pause = 1000ms):
+
+| Server | Avocent EID | Hotkey |
+|--------|-------------|--------|
+| server-a | 01 | `PRINTSCREEN-***1-***ENTER` |
+| server-b | 05 | `PRINTSCREEN-***5-***ENTER` |
+| server-c | 17 | `PRINTSCREEN-***1-7-***ENTER` |
+| server-d | 22 | `PRINTSCREEN-***2-2-***ENTER` |
+| server-e | 31 | `PRINTSCREEN-***3-1-***ENTER` |
+
+Note: don't type the leading zero in EIDs (per Avocent OSCAR convention).
+
+### Hotkey syntax reference
+
+The Belkin hotkey syntax uses key names connected by operators:
+
+| Operator | Meaning |
+|----------|---------|
+| `+` | Press additionally (hold previous, press next) |
+| `-` | Release all pressed keys |
+| `>` | Release most recently pressed key only |
+| `*` | Pause for the configured key pause duration |
+
+Key names: `A`-`Z`, `0`-`9`, `F1`-`F12`, `PRINTSCREEN`, `ENTER`, `ESCAPE`,
+`LCTRL`/`CTRL`, `LALT`/`ALT`, `LSHIFT`/`SHIFT`, `SPACE`, `TAB`, `DELETE`,
+`INSERT`, `HOME`, `END`, `PAGE_UP`, `PAGE_DOWN`, `UP`, `DOWN`, `LEFT`, `RIGHT`,
+`BACK_SPACE`, `NUM_LOCK`, `NUMPAD0`-`NUMPAD9`, `NUMPADPLUS`, `NUMPADMINUS`,
+`NUMPADMUL`, `NUMPAD/`, `NUMPADENTER`, `SCROLL_LOCK`, `BREAK`, `CAPS_LOCK`.
+
+## Protocol heritage
+
+The e-RIC RFB protocol is a proprietary variant of VNC/RFB developed by
+Peppercon (later acquired by Raritan) under the name "LARA" (LAN Attached
+Remote Access). It was used in several KVM-over-IP products including the Belkin
+OmniView Remote IP Manager (F1DE101H). The protocol shares structural
+similarities with standard RFB but uses its own handshake, pixel format
+negotiation, and encoding extensions.
+
+This implementation was reverse-engineered from the CFR-decompiled `rc.jar` Java
+applet that originally provided the browser-based console.
+
+## License
+
+MIT