diff --git a/README.org b/README.org
new file mode 100644
index 0000000..a675f06
--- /dev/null
+++ b/README.org
@@ -0,0 +1,115 @@
+* statusbar
+
+~statusbar~ is a status line generator for [[https://i3wm.org/docs/userguide.html#_configuring_i3bar][i3bar]].
+
+Every second, it renders configured status blocks in parallel, and prints a status line to standard output.
+
+#+begin_src text
+┃  4.20/16 ┃  96℃  37℃ ┃  52%  49% ┃ / 89%  47% ┃  10.0.1.6/24 ┃  80% ┃  60% ┃  OPEN ┃ 2026-10-26 1/7 43/52 299/365 17:18 UTC
+#+end_src
+
+** Usage
+
+#+begin_src shell
+statusbar [-1]
+#+end_src
+
+Flags:
+
+- =-1= — print the status line once and exit
+
+Configuration is read from ~$XDG_CONFIG_HOME/statusbar/config.json~.
+
+Logs are written to ~$XDG_CACHE_HOME/statusbar/log~.
+
+In an ~i3~ configuration:
+
+#+begin_src text
+bar {
+    status_command statusbar
+}
+#+end_src
+
+** Blocks
+
+|----------+------------------------------------------+----------------------------|
+| Block    | Description                              | Source                     |
+|----------+------------------------------------------+----------------------------|
+| =cpu=      | 1-minute load average and CPU core count | =/proc/loadavg=              |
+| =datetime= | Formatted date and time                  | =date=                       |
+| =disk=     | Filesystem usage for configured mounts   | =df -h=                      |
+| =eth=      | Ethernet IPv4 and IPv6 addresses         | =net.InterfaceByName=        |
+| =light=    | Backlight brightness                     | =brightnessctl -m=           |
+| =memory=   | RAM and swap usage percentages           | =free -m=                    |
+| =mic=      | Default audio source mute state          | =pactl=                      |
+| =mlight=   | External monitor brightness (VCP 10)     | =ddcutil=                    |
+| =power=    | AC status, battery charge, time left     | =/sys/class/power_supply=    |
+| =temp=     | Hardware sensor temperatures             | =sensors -j=                 |
+| =volume=   | Default audio sink mute state and volume | =pactl=                      |
+| =wlan=     | Wi-Fi SSID, IPv4 address, and RSSI       | =iwctl=                      |
+| =wwan=     | Cellular modem signal quality and IPs    | =mmcli=, =net.InterfaceByName= |
+|----------+------------------------------------------+----------------------------|
+
+Each block has a 1-second render timeout.
+If a block fails to render, ~statusbar~ logs the error and displays == in its place.
+
+** Configuration
+
+Example ~$XDG_CONFIG_HOME/statusbar/config.json~:
+
+#+begin_src json
+{
+  "separator": "┃",
+  "timezone": "UTC",
+  "blocks": [
+    { "name": "cpu" },
+    {
+      "name": "temp",
+      "temp": {
+        "sensors": [
+          {
+            "label": "",
+            "path": ["k10temp-pci-00c3", "Tctl", "temp1_input"]
+          },
+          {
+            "label": "",
+            "path": ["nvme-pci-0200", "Composite", "temp1_input"]
+          }
+        ]
+      }
+    },
+    { "name": "memory" },
+    {
+      "name": "disk",
+      "disk": { "mounts": ["/", "/home"] }
+    },
+    {
+      "name": "eth",
+      "eth": { "iface": "eno1" }
+    },
+    {
+      "name": "wlan",
+      "wlan": { "iface": "wlan0" }
+    },
+    { "name": "power" },
+    { "name": "light" },
+    { "name": "mlight" },
+    { "name": "volume" },
+    { "name": "mic" },
+    {
+      "name": "datetime",
+      "datetime": {
+        "label": "",
+        "timezone": "America/New_York",
+        "format": "+%Y-%m-%d %H:%M %Z"
+      }
+    }
+  ]
+}
+#+end_src
+
+** Installation
+
+#+begin_src shell
+go install code.chimeric.al/dwrz/statusbar/cmd/statusbar@latest
+#+end_src