diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ffe3aa0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+# eww
+
+A minimal top bar for [Quickshell](https://quickshell.outfoxxed.me/) on [Niri](https://github.com/YaLTeR/niri).
+
+## Features
+
+- **Window strip** — shows all windows on the current workspace, ordered by niri column position. Focused window is highlighted, unfocused are greyscaled. Click to focus.
+- **System tray** — full StatusNotifier support with native DBusMenu popups (including submenus on hover).
+- **Audio widget** — shows current default sink volume, scroll to adjust by 1%, click to open a sink picker powered by PipeWire directly.
+- **Clock** — current time, updates every second.
+
+Multi-monitor aware — one bar instance per screen, each showing only that screen's windows.
+
+## Dependencies
+
+- [Quickshell](https://quickshell.outfoxxed.me/) ≥ 0.2.0
+- [Niri](https://github.com/YaLTeR/niri)
+- PipeWire
+- `niri` in `$PATH` (for window tracking via IPC)
+- Fonts: [Inter](https://rsms.me/inter/), [Maple Mono](https://github.com/subframe7536/maple-font) (for the audio icon glyph)
+- An icon theme with app icons (e.g. [Papirus](https://github.com/PapirusDevelopmentTeam/papirus-icon-theme))
+
+## Usage
+
+```sh
+qs -c ~/.config/quickshell/eww
+```
+
+Or add to your niri config for autostart:
+
+```kdl
+spawn-at-startup "qs" "-c" "/home/callie/.config/quickshell/eww"
+```
+
+> **Note:** Quickshell must be launched with `UseQApplication` mode for system tray menus to work. This is handled automatically by the `//@ pragma UseQApplication` directive at the top of `shell.qml`.
+
+## Structure
+
+```
+eww/
+├── shell.qml   # everything, for now
+└── README.md
+```
+
+## Theming
+
+All colours and fonts are hardcoded inline and easy to grep for:
+
+| Thing | Value |
+|---|---|
+| Background | `"black"` |
+| Font | `Inter`, 16px, weight 700 |
+| Focused window pill | `#555` fill, `#888` border |
+| Hover | `#2a2a2a` fill, `#555` border |
+| Popup background | `"black"` |
+| Popup hover | `#1a1a1a` |
+| Separator | `#333` |
+| Disabled text | `#555` |
+| Audio icon font | `Maple Mono` |