diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8c09e5d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,68 @@
+# Sloppy Focus — KTextEditor Plugin for Kate
+
+A KTextEditor plugin that brings focus-follows-mouse (sloppy focus) behavior to Kate's split views, tool views, terminals, and other panes. Hover over a pane to give it keyboard focus, just like sloppy focus in X11 window managers.
+
+## Features
+
+- Focus follows mouse across all Kate panes: editor splits, tool views, terminals, file browsers, etc.
+- Configurable focus delay (0–5000 ms)
+- Minimum stay time to prevent rapid focus bouncing
+- Optional raise-on-focus
+- Focus-stealing prevention:
+  - Ignores focus changes while modal dialogs are active
+  - Ignores focus changes when floating widgets (completion popups, tooltips) have focus
+- Verifies mouse is still over the target pane before switching
+- Full configuration page in Kate's settings (Settings → Configure Kate → Sloppy Focus)
+
+## Requirements
+
+- CMake ≥ 3.16
+- Extra CMake Modules (ECM) ≥ 5.80
+- Qt 6 + KDE Frameworks 6 (KF6), or Qt 5 + KDE Frameworks 5 (KF5)
+- KTextEditor development headers
+
+On Debian/Ubuntu (KF6):
+
+```sh
+sudo apt install cmake extra-cmake-modules libkf6texteditor-dev qt6-base-dev
+```
+
+On Arch Linux (KF6):
+
+```sh
+sudo pacman -S cmake extra-cmake-modules ktexteditor qt6-base
+```
+
+## Building
+
+```sh
+make
+```
+
+This creates a `build/` directory, runs CMake, and builds the plugin. The build system auto-detects KF6 or falls back to KF5.
+
+## Installing
+
+```sh
+make install
+```
+
+This installs the plugin library to the appropriate KTextEditor plugin directory (typically `/usr/lib/qt6/plugins/kf6/ktexteditor/` for KF6).
+
+After installing, restart Kate and enable the plugin in Settings → Configure Kate → Plugins → Sloppy Focus.
+
+## Configuration
+
+All settings are accessible via Settings → Configure Kate → Sloppy Focus:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Focus delay | 150 ms | Time the mouse must hover before focus switches |
+| Minimum stay time | 50 ms | Minimum time before another switch is allowed |
+| Raise on focus | Off | Raise the view widget when it receives focus |
+| Ignore dialogs | On | Disable sloppy focus while a modal dialog is active |
+| Ignore floating widgets | On | Disable sloppy focus when popups/tooltips have focus |
+
+## License
+
+See the source files for license information.